Implement Node Layer Architecture across Core and Renderers

[jacobsimionato]

This is a proposal based on a comment that @yjbanov made on the original design for web_core. After thinking about it a bit more and seeing how the libraries evolved, I think he was right!

Description and Rationale

We are introducing a "Node Layer" architecture into the A2UI core libraries and refactoring the existing rendering frameworks (React, Angular, Lit) to consume it.

Currently, frameworks are responsible for complex tasks: traversing the flat SurfaceModel adjacency list, resolving data bindings using GenericBinder, handling template expansions (e.g., ChildList), and managing subscription lifecycles. This causes duplicated logic across frameworks, risks memory leaks due to forgotten binder disposals, and makes adding new framework adapters difficult.

The Node Layer centralizes this "business logic" into the core library. It transforms the flat component map into a living, reactive view hierarchy. Renderers will simply receive fully-resolved, type-safe Node instances and focus solely on mapping them to native UI primitives (pixels).

Detailed Architecture & Design

The Node Layer represents a shift from frameworks directly managing components and data to having the SurfaceModel manage the entire view hierarchy lifecycle.

1. Core Data Structures: The Node

The new architecture introduces a Node<TProps> interface. A Node represents a living, fully resolved component instance in the view hierarchy. By utilizing generics, the Node interface provides type-safe property access to the rendering frameworks.

• instanceId: A stable, unique identifier for this instance in the rendered tree. For templated nodes, this incorporates the data path (e.g., 'item-card-[/users/0]') to ensure React/Flutter keys remain stable.
• props: A reactive Signal<TProps>. Dynamic values are primitive strings/numbers/booleans, Actions are callable () => void closures, and Structural props (e.g., child or children) contain actual child Node references (not string IDs).
• Lifecycle: onDestroyed event and a dispose() method.

2. Internal Node Engine inside SurfaceModel

The management of the Node tree is an implementation detail inside SurfaceModel. Because SurfaceModel encapsulates both the DataModel and the SurfaceComponentsModel, it is perfectly positioned to handle this.

• Public API: SurfaceModel exposes a single, reactive rootNode: Signal<Node | undefined>. Frameworks simply subscribe to this signal.
• Internal Engine: The SurfaceModel internally tracks SurfaceComponentsModel changes and DataModel mutations. It manages a private cache of active nodes, automatically instantiating and destroying child nodes as requested by layout containers.

3. 1-to-N Mapping for Templates (ChildLists)

A primary responsibility of the internal Node engine is managing the 1-to-N mapping between a single ComponentModel and multiple rendered Node instances.
When an A2UI payload contains a ChildList acting as a template (e.g., a Card with ID "user-card" iterating over /users), it will be rendered multiple times.

• The internal engine handles subscribing to the DataModel array path (e.g., /users).
• If the array has 3 items, the engine spawns 3 unique Node instances for the same componentId.
• Each spawned node receives its own instanceId, scoped dataPath, and an isolated GenericBinder to resolve its properties.
• If the array length changes (e.g., a 4th user is added), the parent node detects the array mutation and spawns a 4th Node, emitting an updated ChildList prop containing the 4 nodes.
• When destroyed (e.g., a user is deleted), the Node fires onDestroyed, disposes its GenericBinder, and destroys its children.

4. Soft Transition for Adapters

Framework adapters will expose Node objects for structural properties, but will maintain backward-compatible shims so component authors don't have to rewrite all their UI code immediately.

• buildChild Overload: The buildChild helper will accept child: string | Node. If it receives a Node, it renders it directly.
• Node.toString(): Implement Node.prototype.toString() to return its componentId, preventing breakage for logic using ID comparisons.

[jacobsimionato]

Coding agent prompt:

Goal: Implement the Node Layer architecture in A2UI and migrate the framework renderers (Angular, Lit, React) to use it with a non-breaking soft transition. This involves moving hierarchy resolution, template expansion, and data binding lifecycle management from the framework layer into the framework-agnostic core (web_core).

Rationale & Architecture Overview

Currently, frameworks independently traverse the flat SurfaceModel adjacency list and manually manage GenericBinder instances. This duplication causes inconsistencies, memory leaks, and high complexity for new renderers.

The Node Layer centralizes this logic into a reactive, living view hierarchy.
Because the SurfaceModel encapsulates both the DataModel (for bindings/templating) and the SurfaceComponentsModel (for definitions), it is perfectly positioned to manage this hierarchy. SurfaceModel will expose a single, reactive rootNode: Signal<Node | undefined>.

---

1. Core Implementation in web_core (@renderers/web_core/src/v0_9/)

1.1 The Node Interface

Define a living representation of a component instance in the core library.

interface Node<TProps = Record<string, any>> {
  /** Stable, unique ID in the hierarchy (e.g., 'item-card-[/users/0]'). */
  readonly instanceId: string;
  /** The original component ID from the JSON payload (e.g., 'item-card'). */
  readonly componentId: string;
  /** The component type string (e.g., 'Text', 'Button'). */
  readonly type: string;
  /** The scoped data path (e.g., '/users/0'). */
  readonly dataPath: string;
  /** Fully resolved, strongly-typed properties as a reactive signal. */
  readonly props: Signal<TProps>;
  /** Event fired when the node is removed from the view hierarchy. */
  readonly onDestroyed: EventSource<void>;
  /** Cleanup logic for binders and child nodes. */
  dispose(): void;
}

1.2 SurfaceModel Integration

The management of the Node tree should be an implementation detail inside SurfaceModel.

• Expose: rootNode: Signal<Node | undefined> on SurfaceModel.
• Internal Node Engine:
  • Watch SurfaceComponentsModel for the component with ID root.
  • Use the GenericBinder logic internally to resolve properties for nodes.
  • 1-to-N Mapping: Handle templated ChildLists. If a container points to a data model array (e.g., path: '/users'), the engine must subscribe to that path in the DataModel and spawn a unique Node for each item.
  • Stability: Ensure instanceId incorporates the data path for templated items so that framework "keys" remain stable.
  • Reconciliation: Update existing nodes' properties when the model changes. If a component's type changes, destroy the old node and create a new one.

---

2. Framework Integration & Soft Transition

We must ensure existing component implementations continue to work without a full rewrite.

2.1 Compatibility Shims

• buildChild Overload: Update the buildChild helper in all framework wrappers to accept string | Node. If it receives a Node, it renders it directly. This allows existing code like ${buildChild(props.child)} to stay exactly the same.
• Node.toString(): Implement Node.prototype.toString() to return its componentId. This prevents breakage for logic using ID comparisons (e.g., if (props.child === 'submit-btn')).

2.2 Framework-Specific Tasks

React Renderer (@renderers/react/src/v0_9/)

• Adapter: Update A2uiSurface.tsx to subscribe to surface.rootNode. createComponentImplementation should provide a Node object to the component instead of raw IDs.
• Hook: Create useNodeProps(node) using useSyncExternalStore to subscribe to the node's props signal.
• Rendering: Update standard components (e.g., ChildList.tsx) to map over Node arrays, passing them directly to buildChild.

Angular Renderer (@renderers/angular/)

• Signals: Wrap the Preact node.props signal into an Angular Signal using @angular/core. Subscribe the base A2UI Surface component to SurfaceModel.rootNode.
• Directive: Update the internal outlet directive (e.g., *a2uiOutlet) to accept a Node input. It should gracefully transition from ID-based lookup to direct Node rendering.

Lit Renderer (@renderers/lit/)

• Controller: Implement a NodeController that subscribes to the node's reactive state and calls host.requestUpdate().
• Base class: Overload the base class's buildChild method to handle the new Node type.

---

3. Edge Cases & Testing

• Memory Safety: Verify that deleting a surface or removing an item from a templated list calls dispose() on all affected nodes and clears all DataModel subscriptions.
• Type Safety: Properties resolution must remain type-safe. Ensure props.child in a component implementation is typed as Node.
• Progressive Rendering: Handle cases where a container refers to a component ID that hasn't arrived in the message stream yet (render as a placeholder until the ID is defined).

Context

• @renderers/web_core/src/v0_9/
• @renderers/react/src/v0_9/
• @renderers/angular/
• @renderers/lit/
• @specification/v0_9/json/server_to_client.json
• @specification/v0_9/json/common_types.json
• @specification/v0_9/json/basic_catalog.json

[jacobsimionato]

@ditman @josemontesp WDYT?

[ditman]

Renderers will simply receive fully-resolved, type-safe Node instances and focus solely on mapping them to native UI primitives (pixels).

I like this!

---

interface Node<TProps = Record<string, any>> {

Should TProps be a more specific type, maybe inferred from the Zod definition of the catalog items?

---

props: A reactive Signal. Dynamic values are primitive strings/numbers/booleans, Actions are callable () => void closures, and Structural props (e.g., child or children) contain actual child Node references (not string IDs).

We got some feedback about props being a single signal maybe being a performance issue, and we should prefer each separate prop to be its own independent signal. Should we model that here?

---

Structural props (e.g., child or children) contain actual child Node references (not string IDs).

Hmmm, I guess this is fine for the view of the node tree that the renderers use, so rendering there is just a tree traversal, but there's some advantages to the current implementation based off of ids and an adjacency list (for example, almost free path resolutions), no?

I guess the implementation details of the actual tree data structure are TBD, but I'm not sure I'd like to go full blown tree traversal for everything.

---

Also, can we decouple this work from the v0.10 of the protocol? From my experience in v0.9, updating the protocol seems like quite a fast affair, but then updating the renderers is a whole can of worms.

[jacobsimionato]

Thanks for taking a look!

Should TProps be a more specific type, maybe inferred from the Zod definition of the catalog items?

Yeah, let's type it as well as we can. This is templated right? So I assume we can instantiate Node instances with more specific props types?

We got some feedback about props being a single signal maybe being a performance issue, and we should prefer each separate prop to be its own independent signal. Should we model that here?

I hear this, but did the developer have measurable issues with performance, or they were they just concerned? Even if we expose a single Signal with all the props, in the uncommon case that someone has a very complex component that they want to update incrementally, l assume frameworks have some way that you could diff the previous props from the current props, allowing for a partial rendering update?

Also, can we decouple this work from the v0.10 of the protocol? From my experience in v0.9, updating the protocol seems like quite a fast affair, but then updating the renderers is a whole can of worms.

Yes! Definitely! That milestone setting was a mistake. We can do this anytime, an incremental improvement.

[jacobsimionato]

See prototype implementation here: #1294