a2ui-project / a2ui-project/a2ui

Explicit "root" ID Enforcement

Open
#843 5 comments 0 reactions 0 assignees View on GitHub
P2 type: feature/enhancement
Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
2d 13h
Merged PRs (30d)
134

Description

# Proposal: Explicit "root" ID Enforcement

## Reason
A surface is not valid for rendering until a component with `id="root"` is defined. Currently, the renderers perform a simple null check, leading to inconsistent "empty" states or flicker while the stream is loading.

## Design
1. **Ready State**: Add an `isReady` signal to `SurfaceModel` (or `SurfaceComponentsModel`) that specifically tracks the presence of the `root` ID.
2. **Progressive Feedback**: Update `A2uiSurface` to check `isReady`. While false, it should render a standardized "Loading Surface" state or a shimmer effect.
3. **Enforcement**: Log a warning if components are added to a surface that has been active for a significant time without a root component, aiding developer debugging.

## Key Files
- `renderers/web_core/src/v0_9/state/surface-model.ts`
- `renderers/react_prototype/src/A2uiSurface.tsx`

Contributor guide

Open the contributing guide

Research direction

Start by reading the key files mentioned: `renderers/web_core/src/v0_9/state/surface-model.ts` and `renderers/react_prototype/src/A2uiSurface.tsx`. Understand how the surface state is managed and where the root component check currently happens. The goal is to add an `isReady` signal and update the React component to show a loading state. Check for existing tests related to surface rendering to ensure the new behavior works correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
developer-experience, frontend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.