@urbicon-ui/blocks 6.40.4 → 6.43.0

package/dist/components/Chat/A2UIView/a2ui-prompt.d.ts

@@ -1,18 +1,29 @@
 /**
- * System-prompt generator for the A2UI subset. Renders the agent-facing catalog
- * description straight from `A2UI_REGISTRY`, so the prompt and the validator can
- * never drift (a drift-guard test asserts every component and enum value is
- * covered). Pure TS, no Svelte — a server building the prompt has no DOM.
+ * System-prompt generator for an A2UI catalog. Renders the agent-facing catalog
+ * description straight from the catalog's registry, so the prompt and the
+ * validator can never drift (a drift-guard test asserts every component and enum
+ * value is covered). Pure TS, no Svelte — a server building the prompt has no
+ * DOM, and this module never imports catalog VALUE code from `urbicon/` (the
+ * caller passes the spec), so it stays out of the Basic bundle.
  *
- * Deliberately excludes any TRANSPORT section (how envelopes reach the client):
- * that is app-specific and each app appends it (the chat-demo appends its fenced
- * `a2ui` JSONL protocol).
+ * With no options the output is the Basic-catalog prompt, byte-identical to
+ * before the catalog refactor. Pass `catalog` to render a richer catalog: when
+ * its specs carry categories / shared axes (the Urbicon catalog), the prompt
+ * grows a "Shared axes" section, groups components by category, compresses
+ * shared-axis props, and adds catalog-specific don'ts — all gated on features
+ * the Basic catalog does not have, so the default stays untouched.
+ *
+ * Deliberately excludes any TRANSPORT section (how envelopes reach the client)
+ * and any data-schema section: those are app-specific and each app appends them
+ * (the chat-demo appends its fenced `a2ui` protocol + `a2uiDataSchemaSection`).
  */
+import { type A2uiCatalogSpec } from './a2ui-catalog.js';
 /**
- * Build the A2UI system prompt for this subset. Pass `catalogId` to override the
- * default `createSurface` catalog identifier (the value must round-trip
- * unchanged in every envelope).
+ * Build the A2UI system prompt. Pass `catalogId` to override the advertised
+ * `createSurface` catalog id, and `catalog` to render a specific catalog's
+ * components (defaults to the Basic catalog — byte-identical output).
  */
 export declare function a2uiSystemPrompt(options?: {
     catalogId?: string;
+    catalog?: A2uiCatalogSpec;
 }): string;

package/dist/components/Chat/A2UIView/a2ui-prompt.js

@@ -1,17 +1,49 @@
 /**
- * System-prompt generator for the A2UI subset. Renders the agent-facing catalog
- * description straight from `A2UI_REGISTRY`, so the prompt and the validator can
- * never drift (a drift-guard test asserts every component and enum value is
- * covered). Pure TS, no Svelte — a server building the prompt has no DOM.
+ * System-prompt generator for an A2UI catalog. Renders the agent-facing catalog
+ * description straight from the catalog's registry, so the prompt and the
+ * validator can never drift (a drift-guard test asserts every component and enum
+ * value is covered). Pure TS, no Svelte — a server building the prompt has no
+ * DOM, and this module never imports catalog VALUE code from `urbicon/` (the
+ * caller passes the spec), so it stays out of the Basic bundle.
  *
- * Deliberately excludes any TRANSPORT section (how envelopes reach the client):
- * that is app-specific and each app appends it (the chat-demo appends its fenced
- * `a2ui` JSONL protocol).
+ * With no options the output is the Basic-catalog prompt, byte-identical to
+ * before the catalog refactor. Pass `catalog` to render a richer catalog: when
+ * its specs carry categories / shared axes (the Urbicon catalog), the prompt
+ * grows a "Shared axes" section, groups components by category, compresses
+ * shared-axis props, and adds catalog-specific don'ts — all gated on features
+ * the Basic catalog does not have, so the default stays untouched.
+ *
+ * Deliberately excludes any TRANSPORT section (how envelopes reach the client)
+ * and any data-schema section: those are app-specific and each app appends them
+ * (the chat-demo appends its fenced `a2ui` protocol + `a2uiDataSchemaSection`).
  */
-import { A2UI_CATALOG_ID, A2UI_ICON_NAMES, A2UI_REGISTRY, UNSUPPORTED_A2UI_COMPONENTS } from './a2ui-registry.js';
+import { basicA2uiCatalogSpec } from './a2ui-catalog.js';
 /** Props documented once in the shared section rather than per component. */
 const COMMON_PROP_KEYS = new Set(['accessibility', 'weight']);
+/** Category order for grouped rendering; unknown categories follow, sorted. */
+const CATEGORY_ORDER = ['Layout', 'Text', 'Form', 'Status', 'Media'];
+function sharedAxisOf(spec) {
+    return spec.sharedAxis;
+}
+function categoryOf(spec) {
+    return spec.category;
+}
+/** Collect the distinct shared axes (name → value list) referenced across the registry. */
+function collectSharedAxes(registry) {
+    const axes = new Map();
+    for (const spec of Object.values(registry)) {
+        for (const propSpec of Object.values(spec.props)) {
+            const shared = sharedAxisOf(propSpec);
+            if (shared && propSpec.values && !axes.has(shared))
+                axes.set(shared, propSpec.values);
+        }
+    }
+    return axes;
+}
 function renderKind(spec) {
+    const shared = sharedAxisOf(spec);
+    if (shared)
+        return `shared ${shared} (see Shared axes)`;
     switch (spec.kind) {
         case 'enum':
         case 'icon':
@@ -28,10 +60,14 @@ function renderKind(spec) {
             return 'component id (string)';
         case 'childList':
             return 'array of ids OR template { componentId, path }';
+        case 'labeledChildren':
+            return 'array of { label, child } (child is a component id)';
         case 'action':
             return 'action { event: { name, context } }';
         case 'options':
-            return 'array of { label, value }';
+            return spec.dynamic
+                ? 'array of { label, value }, or { path } binding to such an array'
+                : 'array of { label, value }';
         case 'accessibility':
             return 'object { label?, description? }';
     }
@@ -44,9 +80,8 @@ function renderProp(key, spec) {
         flags.push(`default ${JSON.stringify(spec.default)}`);
     return `  - ${key} (${flags.join('; ')}): ${spec.description}`;
 }
-function renderComponent(name) {
-    const spec = A2UI_REGISTRY[name];
-    const lines = [`### ${name}`, spec.description, 'Props:'];
+function renderComponent(name, spec, heading) {
+    const lines = [`${heading} ${name}`, spec.description, 'Props:'];
     for (const [key, propSpec] of Object.entries(spec.props)) {
         if (COMMON_PROP_KEYS.has(key) || propSpec.promptHidden)
             continue;
@@ -54,14 +89,53 @@ function renderComponent(name) {
     }
     return lines.join('\n');
 }
+/** Flat component list — the Basic rendering (byte-identical). */
+function renderFlatComponents(registry, names) {
+    return [
+        '## Components',
+        '',
+        ...names.map((name) => renderComponent(name, registry[name], '###'))
+    ].join('\n\n');
+}
+/** Category-grouped component list — the Urbicon rendering. */
+function renderGroupedComponents(registry, names) {
+    const byCategory = new Map();
+    for (const name of names) {
+        const category = categoryOf(registry[name]) ?? 'Other';
+        let list = byCategory.get(category);
+        if (!list) {
+            list = [];
+            byCategory.set(category, list);
+        }
+        list.push(name);
+    }
+    const known = CATEGORY_ORDER.filter((category) => byCategory.has(category));
+    const extra = [...byCategory.keys()]
+        .filter((category) => !CATEGORY_ORDER.includes(category))
+        .sort();
+    const parts = ['## Components'];
+    for (const category of [...known, ...extra]) {
+        parts.push(`### ${category}`);
+        for (const name of byCategory.get(category) ?? []) {
+            parts.push(renderComponent(name, registry[name], '####'));
+        }
+    }
+    return parts.join('\n\n');
+}
 /**
- * Build the A2UI system prompt for this subset. Pass `catalogId` to override the
- * default `createSurface` catalog identifier (the value must round-trip
- * unchanged in every envelope).
+ * Build the A2UI system prompt. Pass `catalogId` to override the advertised
+ * `createSurface` catalog id, and `catalog` to render a specific catalog's
+ * components (defaults to the Basic catalog — byte-identical output).
  */
 export function a2uiSystemPrompt(options) {
-    const catalogId = options?.catalogId ?? A2UI_CATALOG_ID;
-    const componentNames = Object.keys(A2UI_REGISTRY);
+    const catalog = options?.catalog ?? basicA2uiCatalogSpec;
+    const catalogId = options?.catalogId ?? catalog.catalogId;
+    const registry = catalog.registry;
+    const componentNames = Object.keys(registry);
+    const sharedAxes = collectSharedAxes(registry);
+    const grouped = componentNames.some((name) => categoryOf(registry[name]) !== undefined);
+    const hasRichText = 'RichText' in registry;
+    const hasSelectArray = 'Select' in registry && registry.Select.props.value?.kind === 'stringList';
     const sections = [];
     sections.push([
         '# A2UI rendering',
@@ -99,6 +173,46 @@ export function a2uiSystemPrompt(options) {
         '  The client buffers until "root" exists and shows placeholders for',
         '  children that have not arrived yet.'
     ].join('\n'));
+    sections.push([
+        '## Surfaces live on, and you only hear from them when the user acts',
+        '',
+        'A surfaceId is unique for as long as the client runs, and a surface stays',
+        'alive and editable after the reply that created it. Send further envelopes',
+        'for the SAME surfaceId later and it updates in place, keeping what the user',
+        'typed. Prefer ONE surface that grows over a chain of near-identical ones.',
+        '',
+        '- updateDataModel to fill in a value you just learned; updateComponents to',
+        '  add or change controls. Re-sending a component id REPLACES it — to append',
+        '  a child, re-send its container with the full children list.',
+        '- Never createSurface twice for one id, and never rebuild an equivalent',
+        "  surface under a new id to change a field: both discard the user's input.",
+        '- deleteSurface when a surface has served its purpose.',
+        '',
+        'But you are NOT watching the form. The client speaks to you in exactly one',
+        'case: the user activates a control carrying an `action`. Typing, picking a',
+        'date, choosing an option — all of it updates the data model LOCALLY and',
+        'tells you nothing.',
+        '',
+        '- Anything you mean to fill in later needs a control the user can press to',
+        '  ask you for it ("Show available times"), with the fields it depends on in',
+        '  its action.context. An empty area with no trigger is a dead end — never',
+        '  write "pick a date and I will show the times" without one.',
+        '- But do NOT route a plain choice through you. A control that only records',
+        '  what the user picked should BIND: a single-choice input with',
+        '  value: { path } highlights the selection instantly, no round-trip. A row',
+        '  of Buttons that each set a value is the wrong shape — buttons show no',
+        '  selected state, so the choice looks lost, and every tap costs a turn.',
+        '  Reach for an action only when YOU must fetch or commit something.',
+        '- Options you fetched belong in the data model: write them with',
+        '  updateDataModel and bind options: { path } (see the prop docs), rather',
+        '  than rewriting the component for every result.',
+        '- Set "sendDataModel": true on createSurface: every action then carries the',
+        "  surface's ENTIRE data model, so you see what the user filled in even for",
+        '  fields you left out of context. Prefer it on any form you will act on.',
+        '- If an action arrives with required fields still empty, do NOT carry it',
+        '  out — patch a short message next to the offending field instead. You are',
+        '  the only validator; the client submits whatever it is given.'
+    ].join('\n'));
     sections.push([
         '## Data bindings',
         '',
@@ -120,7 +234,27 @@ export function a2uiSystemPrompt(options) {
         '"context": { ... } } }. Context values may be literals or { path } bindings and',
         'are resolved before dispatch. Do NOT use local function-call actions.'
     ].join('\n'));
-    sections.push(['## Components', '', ...componentNames.map(renderComponent)].join('\n\n'));
+    if (sharedAxes.size > 0) {
+        const lines = [
+            '## Shared axes',
+            '',
+            'Several components share these value sets. A prop documented as "shared intent"',
+            'or "shared size" accepts exactly the values listed here — pick one:'
+        ];
+        for (const axis of ['intent', 'size']) {
+            const values = sharedAxes.get(axis);
+            if (values)
+                lines.push(`- ${axis}: ${values.join(' | ')}`);
+        }
+        for (const [axis, values] of sharedAxes) {
+            if (axis !== 'intent' && axis !== 'size')
+                lines.push(`- ${axis}: ${values.join(' | ')}`);
+        }
+        sections.push(lines.join('\n'));
+    }
+    sections.push(grouped
+        ? renderGroupedComponents(registry, componentNames)
+        : renderFlatComponents(registry, componentNames));
     sections.push([
         '## Common props (every component)',
         '',
@@ -130,18 +264,30 @@ export function a2uiSystemPrompt(options) {
     sections.push([
         '## Icons',
         '',
-        `Icon.name must be one of: ${A2UI_ICON_NAMES.join(', ')}. Unknown names render a`,
+        `Icon.name must be one of: ${catalog.iconNames.join(', ')}. Unknown names render a`,
         'fallback glyph.'
     ].join('\n'));
-    sections.push([
+    const donts = [
         "## Don'ts",
         '',
         '- Do NOT define children inline; reference them by id.',
         '- Do NOT use more than one "root".',
         '- Do NOT use function-call bindings or local function-call actions.',
-        `- Do NOT use unsupported components: ${[...UNSUPPORTED_A2UI_COMPONENTS].join(', ')}.`,
-        '- Do NOT put HTML, images or links in Text markdown (inline bold/italic/code only).',
-        '- Images are blocked by default — always give Image a meaningful description.'
-    ].join('\n'));
+        `- Do NOT use unsupported components: ${[...catalog.unsupportedComponents].join(', ')}.`
+    ];
+    if (hasRichText) {
+        donts.push('- Text renders PLAIN — a literal "**x**" shows the asterisks. For bold/italic/', '  lists/links/code use RichText, never Text.');
+    }
+    else {
+        donts.push('- Do NOT put HTML, images or links in Text markdown (inline bold/italic/code only).');
+    }
+    if (hasSelectArray) {
+        donts.push('- A Select `value` is ALWAYS a string ARRAY — even single-select writes a', '  one-element array. RadioGroup `value` is a single string.');
+    }
+    if (hasRichText) {
+        donts.push('- Do NOT set an intent on a form field for errors — use its `error` string prop.');
+    }
+    donts.push('- Images are blocked by default — always give Image a meaningful description.');
+    sections.push(donts.join('\n'));
     return sections.join('\n\n');
 }

package/dist/components/Chat/A2UIView/a2ui-registry.d.ts

@@ -13,7 +13,7 @@
  * is written to be read by an agent — it is emitted verbatim into the prompt.
  */
 /** How a prop value is shaped and validated. */
-export type A2uiPropKind = 'string' | 'number' | 'boolean' | 'stringList' | 'enum' | 'childId' | 'childList' | 'action' | 'options' | 'icon' | 'accessibility';
+export type A2uiPropKind = 'string' | 'number' | 'boolean' | 'stringList' | 'enum' | 'childId' | 'childList' | 'labeledChildren' | 'action' | 'options' | 'icon' | 'accessibility';
 export interface A2uiPropSpec {
     kind: A2uiPropKind;
     /** Required on the component. @default false */

package/dist/components/Chat/A2UIView/a2ui-registry.js

@@ -283,7 +283,8 @@ export const A2UI_REGISTRY = Object.freeze({
             options: {
                 kind: 'options',
                 required: true,
-                description: 'The available options as an array of { label, value } objects. `value` is a stable string.'
+                dynamic: true,
+                description: 'The available options as an array of { label, value } objects; `value` is a stable string. Bind it when the options come from data you fetched.'
             },
             value: {
                 kind: 'stringList',

package/dist/components/Chat/A2UIView/a2ui-render.d.ts

@@ -14,6 +14,7 @@
  * still produced by `collectGraphIssues` in `a2ui-validate.ts`; this walk only
  * shapes what renders.
  */
+import type { Component, Snippet } from 'svelte';
 import type { IconComponent } from '../../../icons/index.js';
 import type { MarkdownUrlPolicy } from '../markdown/types.js';
 import type { A2uiActionEvent, A2uiValidationIssue } from './a2ui.types.js';
@@ -37,6 +38,12 @@ export interface A2uiRenderNode {
     children: A2uiRenderNode[];
     /** flex-grow, present only when this node is a direct Row/Column child with a finite `weight`. */
     weight?: number;
+    /**
+     * The parent prop this child came from (e.g. Card `header`/`footer`/`child`).
+     * Lets a dispatcher with several named childId slots pick the right child by
+     * name instead of position; single-slot / list components ignore it.
+     */
+    slot?: string;
 }
 /** Static text labels threaded to the node dispatcher (i18n comes from A2UIView props). */
 export interface A2uiRenderLabels {
@@ -60,6 +67,12 @@ export interface A2uiRenderContext {
     inline: boolean;
     surfaceId: string;
     onAction: ((event: A2uiActionEvent) => void) | undefined;
+    /**
+     * The data model to attach to a dispatched action, or `undefined` when the
+     * surface did not ask for it (`createSurface.sendDataModel`). Read as a
+     * function so the action carries the state at CLICK time, not at render time.
+     */
+    actionDataModel: (() => unknown) | undefined;
     /** Resolve a Dynamic value (literal | { path } | function-call) against the model in `scope`. */
     resolve: (value: unknown, scopePrefix: string | undefined) => {
         value: unknown;
@@ -74,6 +87,23 @@ export interface A2uiRenderContext {
     /** Fallback glyph for an unmapped icon name. */
     fallbackIcon: IconComponent;
     labels: A2uiRenderLabels;
+    /**
+     * The catalog's recursive node dispatcher (Basic → `A2UINode`; a custom
+     * catalog → its own dispatcher). A2UIView's `renderNode` snippet renders
+     * THIS rather than importing one dispatcher directly, so each surface renders
+     * through the component that matches its catalog.
+     */
+    nodeComponent: Component<A2uiNodeProps>;
+}
+/**
+ * Props of a catalog node dispatcher. Every dispatcher (Basic/Urbicon/…) takes
+ * the same triple: the node, its render context, and the self-referencing
+ * `renderChild` snippet A2UIView threads down for bounded recursion.
+ */
+export interface A2uiNodeProps {
+    node: A2uiRenderNode;
+    context: A2uiRenderContext;
+    renderChild: Snippet<[A2uiRenderNode, A2uiRenderContext]>;
 }
 /**
  * Resolve a `{ path }` data binding to the ABSOLUTE JSON Pointer it addresses,

package/dist/components/Chat/A2UIView/a2ui-render.js

@@ -58,33 +58,67 @@ export function toInputString(value) {
         return String(value);
     return '';
 }
+/**
+ * Resolve a component's child references by walking its spec's child-bearing
+ * props (`childId` = one id; `childList` = an id array or a `{ componentId,
+ * path }` template; `labeledChildren` = a `[{ label, child }]` list). Kind-
+ * driven rather than reading fixed `child`/`children` keys, so a catalog may
+ * name its child slots freely (Card header/footer, Section child, Accordion
+ * items, …). Behaviour is unchanged for the Basic catalog, whose only child
+ * props ARE `child`/`children`. One ref is pushed per `labeledChildren` item
+ * (even a dangling one) so the dispatcher can zip labels with resolved children
+ * by index.
+ */
 function childRefs(instance, scopePrefix, state) {
     const out = [];
-    const single = instance.props.get('child');
-    if (typeof single === 'string')
-        out.push({ id: single, scope: scopePrefix });
-    const children = instance.props.get('children');
-    if (Array.isArray(children)) {
-        for (const childId of children) {
-            if (typeof childId === 'string')
-                out.push({ id: childId, scope: scopePrefix });
+    const spec = state.registry[instance.component];
+    if (!spec)
+        return out;
+    for (const [key, propSpec] of Object.entries(spec.props)) {
+        if (propSpec.kind === 'childId') {
+            const single = instance.props.get(key);
+            if (typeof single === 'string')
+                out.push({ id: single, scope: scopePrefix, slot: key });
         }
-    }
-    else if (children !== null && typeof children === 'object') {
-        const template = children;
-        if (typeof template.componentId === 'string' && typeof template.path === 'string') {
-            const absPath = template.path.startsWith('/')
-                ? template.path
-                : `${scopePrefix ?? ''}/${template.path}`;
-            const list = getAtPointer(state.dataModel, absPath);
-            if (Array.isArray(list)) {
-                for (let i = 0; i < list.length; i++) {
-                    out.push({ id: template.componentId, scope: `${absPath}/${i}` });
+        else if (propSpec.kind === 'labeledChildren') {
+            const items = instance.props.get(key);
+            if (Array.isArray(items)) {
+                for (const item of items) {
+                    if (item !== null && typeof item === 'object') {
+                        const child = item.child;
+                        if (typeof child === 'string')
+                            out.push({ id: child, scope: scopePrefix, slot: key });
+                    }
                     if (out.length > state.maxNodes)
-                        break; // bound the expansion itself
+                        break;
+                }
+            }
+        }
+        else if (propSpec.kind === 'childList') {
+            const children = instance.props.get(key);
+            if (Array.isArray(children)) {
+                for (const childId of children) {
+                    if (typeof childId === 'string')
+                        out.push({ id: childId, scope: scopePrefix, slot: key });
+                }
+            }
+            else if (children !== null && typeof children === 'object') {
+                const template = children;
+                if (typeof template.componentId === 'string' && typeof template.path === 'string') {
+                    const absPath = template.path.startsWith('/')
+                        ? template.path
+                        : `${scopePrefix ?? ''}/${template.path}`;
+                    const list = getAtPointer(state.dataModel, absPath);
+                    if (Array.isArray(list)) {
+                        for (let i = 0; i < list.length; i++) {
+                            out.push({ id: template.componentId, scope: `${absPath}/${i}`, slot: key });
+                            if (out.length > state.maxNodes)
+                                break; // bound the expansion itself
+                        }
+                    }
+                    // non-array / undefined → render nothing (issue reported by collectGraphIssues)
                 }
             }
-            // non-array / undefined → render nothing (issue reported by collectGraphIssues)
         }
     }
     return out;
@@ -104,7 +138,7 @@ function buildNode(id, scopePrefix, key, parentIsFlex, ancestors, depth, state)
             node.weight = clampWeight(weight, 0, 100);
         }
     }
-    const isFlex = instance.component === 'Row' || instance.component === 'Column';
+    const isFlex = state.flexContainers.has(instance.component);
     const nextAncestors = new Set(ancestors);
     nextAncestors.add(id);
     const refs = childRefs(instance, scopePrefix, state);
@@ -116,8 +150,10 @@ function buildNode(id, scopePrefix, key, parentIsFlex, ancestors, depth, state)
             continue; // cycle: truncate (issue reported elsewhere)
         const childKey = `${ref.id}@${ref.scope ?? ''}#${i}`;
         const child = buildNode(ref.id, ref.scope, childKey, isFlex, nextAncestors, depth + 1, state);
-        if (child)
+        if (child) {
+            child.slot = ref.slot;
             node.children.push(child);
+        }
     }
     return node;
 }
@@ -132,6 +168,8 @@ export function buildRenderTree(surface, options) {
     const state = {
         components: surface.components,
         dataModel: surface.dataModel,
+        registry: surface.catalog.registry,
+        flexContainers: surface.catalog.flexContainers,
         maxDepth: options?.maxDepth ?? A2UI_MAX_DEPTH,
         maxNodes: options?.maxNodes ?? A2UI_MAX_NODES,
         count: 0

package/dist/components/Chat/A2UIView/a2ui-router.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Surface routing across message boundaries.
+ *
+ * `A2UIView` is payload-driven: one view renders one envelope array, and its
+ * processor lives with that view. In a chat that means one view per assistant
+ * message — so a surface dies with the message that created it. The A2UI spec
+ * says the opposite: a `surfaceId` is "globally unique for the renderer's
+ * lifetime", `deleteSurface` is the only way to retire one, and
+ * `updateComponents`/`updateDataModel` are patches an agent may send at any
+ * later point. A model that patches a form it built two turns ago is reading
+ * the protocol correctly; the renderer just had nowhere to put the envelope.
+ *
+ * This router closes that gap WITHOUT giving the engine a second state
+ * lifetime. It is a pure bookkeeping layer over the transcript: it remembers
+ * which source (message + a2ui part) owns which surface, and splits each
+ * source's envelopes into the ones that stay put and the ones that belong to an
+ * earlier source's payload. The consumer appends those to that payload
+ * (`[...payload, ...patch]`, keeping element identity) and `A2UIView` consumes
+ * them incrementally — two-way edits the user already made survive, because the
+ * view never rebuilds.
+ *
+ * The transcript stays the single source of truth: every envelope still lives
+ * in exactly one payload, so undo (`revoke`) and replay are plain array work.
+ *
+ * Zero-dependency and Svelte-free — usable from a server-side transcript
+ * reducer, not just from the browser.
+ */
+import { type A2uiValidationIssue } from './a2ui.types.js';
+/**
+ * Envelopes destined for one source's payload.
+ *
+ * `envelopes` are the very objects the caller passed in — element identity is
+ * what lets `A2UIView` apply them incrementally instead of rebuilding, and what
+ * makes {@link A2uiSurfaceRouter.revoke} a reference filter.
+ */
+export interface A2uiRoutePatch {
+    /** The `sourceKey` whose payload these envelopes belong to. */
+    targetKey: string;
+    envelopes: unknown[];
+}
+/** The verdict for one {@link A2uiSurfaceRouter.route} call. */
+export interface A2uiRouteResult {
+    /**
+     * The full envelope list this source keeps — assign it as the part's payload.
+     * Envelopes routed to an earlier source are absent; everything else stays,
+     * including malformed ones (the processor is what reports those).
+     */
+    own: unknown[];
+    /** Envelopes to append to earlier sources' payloads, grouped by target. */
+    patches: A2uiRoutePatch[];
+    /**
+     * Envelopes to REMOVE from earlier payloads (by reference) because this
+     * source was rebuilt — a regenerated turn must not leave its old patches
+     * behind. Empty on an append-only call.
+     */
+    revoked: A2uiRoutePatch[];
+    /**
+     * Surfaces that this call patched from a later source — i.e. surfaces that
+     * just proved they outlive their own message. This is the promotion signal
+     * for a client heuristic: a surface listed here is long-lived and deserves
+     * treatment beyond an inline transcript entry (a jump anchor, a pinned card,
+     * an artifact panel). Only fires on the transition, not on every patch.
+     */
+    promoted: string[];
+    /** Router-level findings, shaped for the same channel as processor issues. */
+    issues: A2uiValidationIssue[];
+}
+/**
+ * Tracks surface ownership across sources and routes envelopes to the payload
+ * that owns their surface.
+ *
+ * A "source" is one A2UI payload in the transcript — in a chat app, one `a2ui`
+ * part of one message. The key is the consumer's to choose; it only has to be
+ * stable for that payload's lifetime (e.g. `` `${messageId}#${partIndex}` ``).
+ *
+ * Ownership rules:
+ * - `createSurface` for an unknown id → the calling source owns it.
+ * - `createSurface` for an id owned by ANOTHER source → ownership transfers to
+ *   the caller (last writer wins, so the new surface actually renders) and a
+ *   `SURFACE_RECREATED` issue is raised for the agent.
+ * - Any operation on a surface owned by another source → routed to that owner.
+ * - Any operation on an UNKNOWN surface stays with the caller, so the
+ *   processor's `NO_SURFACE` error surfaces instead of vanishing here.
+ * - `deleteSurface` routes to the owner and then frees the id for re-use.
+ *
+ * @example One assistant turn, wired into the transcript
+ * ```ts
+ * const result = router.route(`${messageId}#0`, part.payload);
+ * part.payload = result.own;
+ * for (const patch of result.patches) appendToPayload(patch.targetKey, patch.envelopes);
+ * for (const surfaceId of result.promoted) markLongLived(surfaceId);
+ * ```
+ */
+export declare class A2uiSurfaceRouter {
+    #private;
+    /**
+     * Route one source's envelope list.
+     *
+     * Call it as often as you like — on every streamed token, if that is when the
+     * payload grows. Only envelopes appended since the last call are examined; an
+     * unchanged prefix is never re-routed, so patches are never duplicated. If
+     * the prefix DID change (a regenerated turn), the source is rebuilt from
+     * scratch and its previous patches come back in `revoked`.
+     *
+     * @param sourceKey Stable id of the payload being routed.
+     * @param envelopes The payload's accumulated envelopes, in stream order.
+     */
+    route(sourceKey: string, envelopes: readonly unknown[]): A2uiRouteResult;
+    /**
+     * Forget a source entirely — call it when a message leaves the transcript
+     * (regenerate, delete, branch switch). The returned patches are the envelopes
+     * this source had pushed into other payloads; remove them by reference so no
+     * orphaned patch survives its author.
+     */
+    revoke(sourceKey: string): A2uiRoutePatch[];
+    /** The source whose payload currently holds `surfaceId`, if any. */
+    ownerOf(surfaceId: string): string | undefined;
+    /**
+     * Whether a surface has been patched from a later source — the promotion
+     * predicate, for clients that need to ask after the fact rather than react to
+     * {@link A2uiRouteResult.promoted}.
+     */
+    isLongLived(surfaceId: string): boolean;
+    /** Every surface currently owned by a source, in creation order. */
+    surfaceIds(): string[];
+    /**
+     * Every source key routed so far, in first-seen order.
+     *
+     * Needed to retire a source whose payload no longer shows it: a message whose
+     * envelopes ALL travelled to earlier surfaces keeps no a2ui part of its own,
+     * so the caller cannot reconstruct its keys by counting parts.
+     */
+    sourceKeys(): string[];
+    /** Drop all bookkeeping (new conversation). */
+    reset(): void;
+}