@urbicon-ui/blocks 6.38.0 → 6.39.0

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

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ *
+ * 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).
+ */
+import { A2UI_CATALOG_ID, A2UI_ICON_NAMES, A2UI_REGISTRY, UNSUPPORTED_A2UI_COMPONENTS } from './a2ui-registry.js';
+/** Props documented once in the shared section rather than per component. */
+const COMMON_PROP_KEYS = new Set(['accessibility', 'weight']);
+function renderKind(spec) {
+    switch (spec.kind) {
+        case 'enum':
+        case 'icon':
+            return `one of: ${(spec.values ?? []).join(' | ')}`;
+        case 'string':
+            return spec.dynamic ? 'string literal or { path } binding' : 'string';
+        case 'number':
+            return spec.dynamic ? 'number literal or { path } binding' : 'number';
+        case 'boolean':
+            return spec.dynamic ? 'boolean literal or { path } binding' : 'boolean';
+        case 'stringList':
+            return 'string array or { path } binding';
+        case 'childId':
+            return 'component id (string)';
+        case 'childList':
+            return 'array of ids OR template { componentId, path }';
+        case 'action':
+            return 'action { event: { name, context } }';
+        case 'options':
+            return 'array of { label, value }';
+        case 'accessibility':
+            return 'object { label?, description? }';
+    }
+}
+function renderProp(key, spec) {
+    const flags = [];
+    flags.push(spec.required ? 'required' : 'optional');
+    flags.push(renderKind(spec));
+    if (spec.default !== undefined)
+        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:'];
+    for (const [key, propSpec] of Object.entries(spec.props)) {
+        if (COMMON_PROP_KEYS.has(key) || propSpec.promptHidden)
+            continue;
+        lines.push(renderProp(key, propSpec));
+    }
+    return lines.join('\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).
+ */
+export function a2uiSystemPrompt(options) {
+    const catalogId = options?.catalogId ?? A2UI_CATALOG_ID;
+    const componentNames = Object.keys(A2UI_REGISTRY);
+    const sections = [];
+    sections.push([
+        '# A2UI rendering',
+        '',
+        'You can render live, interactive UI by emitting A2UI (Agent-to-UI) envelopes',
+        'against the catalog below. Emit UI when a structured surface (form, list, card,',
+        'chooser) serves the user better than prose; otherwise answer in plain text.',
+        '',
+        `Protocol version: v0.9.1. Catalog id: ${catalogId}`
+    ].join('\n'));
+    sections.push([
+        '## Envelopes',
+        '',
+        'Emit one JSON envelope per line (JSONL). Every envelope is an object with a',
+        '"version" of "v0.9.1" and EXACTLY ONE of these operations:',
+        '',
+        `- createSurface: { surfaceId, catalogId: "${catalogId}" } — send this FIRST.`,
+        '- updateComponents: { surfaceId, components: [ ... ] } — the component tree.',
+        '- updateDataModel: { surfaceId, path?, value? } — the surface state.',
+        '- deleteSurface: { surfaceId } — remove a surface.',
+        '',
+        'Rules:',
+        '- components is a FLAT list; each entry is { id, component, ...props }.',
+        '- EXACTLY ONE component MUST have id "root" — it is the tree root.',
+        '- Children are referenced by ID only — NEVER define a component inline.',
+        '- A single-child container (Card, Button) uses "child" (one id).',
+        '- A multi-child container (Row, Column, List) uses "children": either an',
+        '  array of ids, or a template { componentId, path } that repeats one',
+        '  component over a data-model array.',
+        '- You may stream components incrementally; buffer until "root" exists.'
+    ].join('\n'));
+    sections.push([
+        '## Data bindings',
+        '',
+        'Any value prop may be a literal OR a data binding { "path": "/json/pointer" }',
+        '(RFC 6901). Inside a template, use a RELATIVE path (no leading slash) to address',
+        'the current array item, e.g. { "path": "name" }.',
+        '',
+        'Inputs are two-way: typing/checking/selecting writes back into the data model',
+        'immediately; bound text updates live. Update state with updateDataModel — omit',
+        '"value" to DELETE the key at "path".',
+        '',
+        'Function-call bindings ({ "call": ..., "args": ... }) are NOT supported and',
+        'resolve to nothing — do NOT use them. Use literals and { path } only.'
+    ].join('\n'));
+    sections.push([
+        '## Actions',
+        '',
+        'A Button action MUST be a server event: { "event": { "name": string,',
+        '"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'));
+    sections.push([
+        '## Common props (every component)',
+        '',
+        '- accessibility (optional; object { label?, description? }): ARIA label/description.',
+        '- weight (optional; number): flex-grow, honored ONLY on a direct Row/Column child.'
+    ].join('\n'));
+    sections.push([
+        '## Icons',
+        '',
+        `Icon.name must be one of: ${A2UI_ICON_NAMES.join(', ')}. Unknown names render a`,
+        'fallback glyph.'
+    ].join('\n'));
+    sections.push([
+        "## 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'));
+    return sections.join('\n\n');
+}

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

@@ -0,0 +1,64 @@
+/**
+ * The A2UI catalog subset this engine renders — the single source of truth for
+ * BOTH validation (`a2ui-validate.ts`) and the agent-facing system prompt
+ * (`a2ui-prompt.ts`). No Svelte imports: this module must be importable
+ * standalone (a server building the system prompt has no DOM).
+ *
+ * The subset is 12 of the 18 v0.9.1 `basic` components. The six excluded
+ * (Modal, Tabs, Video, AudioPlayer, DateTimeInput — plus any future addition)
+ * validate to a visible error chip; see `UNSUPPORTED_A2UI_COMPONENTS`.
+ *
+ * Prop names, kinds, `required`, defaults and enum sets mirror
+ * `catalogs/basic/catalog.json` **case-sensitively**. Every `description` here
+ * 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 interface A2uiPropSpec {
+    kind: A2uiPropKind;
+    /** Required on the component. @default false */
+    required?: boolean;
+    /** Accepts the Dynamic union (literal | `{ path }` | function call). @default false */
+    dynamic?: boolean;
+    /** Allowed values for `enum`/`icon` kinds. */
+    values?: readonly string[];
+    /** Documented default (rendered in the prompt). */
+    default?: string | number | boolean;
+    /** Agent-facing description; emitted into the system prompt verbatim. */
+    description: string;
+    /**
+     * Accepted for spec-compatibility but omitted from the prompt and rendered
+     * with a degraded fallback (e.g. ChoicePicker `displayStyle`/`filterable`).
+     */
+    promptHidden?: boolean;
+}
+export interface A2uiComponentSpec {
+    /** Agent-facing description; emitted into the system prompt verbatim. */
+    description: string;
+    props: Record<string, A2uiPropSpec>;
+}
+/** Opaque catalog identifier this subset advertises in `createSurface`. */
+export declare const A2UI_CATALOG_ID = "urbicon-ui/a2ui-basic-subset/v0.9.1";
+/** Envelope `version` strings this engine accepts. */
+export declare const A2UI_SUPPORTED_VERSIONS: readonly string[];
+/**
+ * Real v0.9.1 `basic` components the engine deliberately does not render.
+ * Distinguished from wholly-unknown component names so the error message can
+ * say "not part of the rendered subset" rather than "unknown".
+ */
+export declare const UNSUPPORTED_A2UI_COMPONENTS: ReadonlySet<string>;
+/**
+ * Mapped `Icon.name` values. A name outside this set degrades to a fallback
+ * glyph (a warning, not an error). Kept in sync with the direct icon imports in
+ * `A2UINode.svelte` (WP-B).
+ */
+export declare const A2UI_ICON_NAMES: readonly string[];
+/**
+ * Grammar guard for inline `Icon.name.svgPath`. Only SVG path commands, digits,
+ * whitespace and separators — no `<`, no attributes, no entities. WP-B MUST
+ * re-apply this guard before inlining a `<path d>` (defense in depth).
+ */
+export declare const A2UI_SVG_PATH_RE: RegExp;
+export declare const A2UI_REGISTRY: Readonly<Record<string, A2uiComponentSpec>>;
+/** Props recognized anywhere but intentionally ignored (validation only, dropped before render). */
+export declare const A2UI_IGNORED_PROPS: ReadonlySet<string>;

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

@@ -0,0 +1,348 @@
+/**
+ * The A2UI catalog subset this engine renders — the single source of truth for
+ * BOTH validation (`a2ui-validate.ts`) and the agent-facing system prompt
+ * (`a2ui-prompt.ts`). No Svelte imports: this module must be importable
+ * standalone (a server building the system prompt has no DOM).
+ *
+ * The subset is 12 of the 18 v0.9.1 `basic` components. The six excluded
+ * (Modal, Tabs, Video, AudioPlayer, DateTimeInput — plus any future addition)
+ * validate to a visible error chip; see `UNSUPPORTED_A2UI_COMPONENTS`.
+ *
+ * Prop names, kinds, `required`, defaults and enum sets mirror
+ * `catalogs/basic/catalog.json` **case-sensitively**. Every `description` here
+ * is written to be read by an agent — it is emitted verbatim into the prompt.
+ */
+/** Opaque catalog identifier this subset advertises in `createSurface`. */
+export const A2UI_CATALOG_ID = 'urbicon-ui/a2ui-basic-subset/v0.9.1';
+/** Envelope `version` strings this engine accepts. */
+export const A2UI_SUPPORTED_VERSIONS = ['v0.9', 'v0.9.1'];
+/**
+ * Real v0.9.1 `basic` components the engine deliberately does not render.
+ * Distinguished from wholly-unknown component names so the error message can
+ * say "not part of the rendered subset" rather than "unknown".
+ */
+export const UNSUPPORTED_A2UI_COMPONENTS = new Set([
+    'Modal',
+    'Tabs',
+    'Video',
+    'AudioPlayer',
+    'DateTimeInput'
+]);
+/**
+ * Mapped `Icon.name` values. A name outside this set degrades to a fallback
+ * glyph (a warning, not an error). Kept in sync with the direct icon imports in
+ * `A2UINode.svelte` (WP-B).
+ */
+export const A2UI_ICON_NAMES = [
+    'add',
+    'arrowBack',
+    'check',
+    'close',
+    'delete',
+    'edit',
+    'error',
+    'home',
+    'info',
+    'mail',
+    'menu',
+    'search',
+    'send',
+    'settings',
+    'star',
+    'warning'
+];
+/**
+ * Grammar guard for inline `Icon.name.svgPath`. Only SVG path commands, digits,
+ * whitespace and separators — no `<`, no attributes, no entities. WP-B MUST
+ * re-apply this guard before inlining a `<path d>` (defense in depth).
+ */
+export const A2UI_SVG_PATH_RE = /^[MmLlHhVvCcSsQqTtAaZz0-9\s,.+\-eE]+$/;
+/**
+ * Props every component accepts (spread into each entry). `accessibility` maps
+ * to ARIA; `weight` is flex-grow, honored only on a direct Row/Column child.
+ */
+const COMMON_PROPS = {
+    accessibility: {
+        kind: 'accessibility',
+        description: 'Accessibility attributes { label, description } for assistive technologies. label is a short (1–3 word) purpose string; description adds instructions or format requirements.'
+    },
+    weight: {
+        kind: 'number',
+        description: 'Relative flex-grow weight within a Row or Column (like CSS flex-grow). ONLY honored when this component is a direct child of a Row or Column.'
+    }
+};
+function withCommon(props) {
+    return { ...props, ...COMMON_PROPS };
+}
+export const A2UI_REGISTRY = Object.freeze({
+    Column: {
+        description: 'A layout container that arranges its children vertically. Nest Rows inside a Column to build a grid.',
+        props: withCommon({
+            children: {
+                kind: 'childList',
+                required: true,
+                description: 'The children: either an array of component IDs, or a template { componentId, path } that repeats one component over a data-model array. Children are referenced by ID only — never defined inline.'
+            },
+            justify: {
+                kind: 'enum',
+                values: ['start', 'center', 'end', 'spaceBetween', 'spaceAround', 'spaceEvenly', 'stretch'],
+                default: 'start',
+                description: 'Arrangement along the main (vertical) axis. Use spaceBetween to push items to the top and bottom edges.'
+            },
+            align: {
+                kind: 'enum',
+                values: ['start', 'center', 'end', 'stretch'],
+                default: 'stretch',
+                description: 'Alignment along the cross (horizontal) axis, like CSS align-items.'
+            }
+        })
+    },
+    Row: {
+        description: 'A layout container that arranges its children horizontally. Nest Columns inside a Row to build a grid.',
+        props: withCommon({
+            children: {
+                kind: 'childList',
+                required: true,
+                description: 'The children: either an array of component IDs, or a template { componentId, path } that repeats one component over a data-model array. Children are referenced by ID only — never defined inline.'
+            },
+            justify: {
+                kind: 'enum',
+                values: ['start', 'center', 'end', 'spaceBetween', 'spaceAround', 'spaceEvenly', 'stretch'],
+                default: 'start',
+                description: 'Arrangement along the main (horizontal) axis. Use spaceBetween to push items to the left and right edges.'
+            },
+            align: {
+                kind: 'enum',
+                values: ['start', 'center', 'end', 'stretch'],
+                default: 'stretch',
+                description: 'Alignment along the cross (vertical) axis, like CSS align-items.'
+            }
+        })
+    },
+    List: {
+        description: 'A list container. Prefer a template { componentId, path } to render one row per data-model array item.',
+        props: withCommon({
+            children: {
+                kind: 'childList',
+                required: true,
+                description: 'The children: an array of component IDs, or a template { componentId, path }. Children are referenced by ID only.'
+            },
+            direction: {
+                kind: 'enum',
+                values: ['vertical', 'horizontal'],
+                default: 'vertical',
+                description: 'The direction list items flow in.'
+            },
+            align: {
+                kind: 'enum',
+                values: ['start', 'center', 'end', 'stretch'],
+                default: 'stretch',
+                description: 'Alignment of items along the cross axis.'
+            }
+        })
+    },
+    Card: {
+        description: 'A visually grouped container with exactly one child. To place several elements in a Card, wrap them in a Column or Row and pass that container ID as the child.',
+        props: withCommon({
+            child: {
+                kind: 'childId',
+                required: true,
+                description: 'The ID of the single child component to render inside the card. Pass a layout container ID for multiple elements. Never inline the child.'
+            }
+        })
+    },
+    Divider: {
+        description: 'A thin rule that visually separates content.',
+        props: withCommon({
+            axis: {
+                kind: 'enum',
+                values: ['horizontal', 'vertical'],
+                default: 'horizontal',
+                description: 'Orientation of the divider.'
+            }
+        })
+    },
+    Text: {
+        description: 'Displays text. `text` supports simple inline Markdown (bold, italic, code) — no HTML, images or links. Prefer dedicated components over Markdown for structured content.',
+        props: withCommon({
+            text: {
+                kind: 'string',
+                required: true,
+                dynamic: true,
+                description: 'The text to display. Bind to the data model with { path } for live values.'
+            },
+            variant: {
+                kind: 'enum',
+                values: ['h1', 'h2', 'h3', 'h4', 'h5', 'caption', 'body'],
+                default: 'body',
+                description: 'Text style hint. h1–h5 are headings; caption is small secondary text; body is default.'
+            }
+        })
+    },
+    Image: {
+        description: 'Displays an image from a URL. Images are blocked by default unless the host allows the source — provide a meaningful `description` so a blocked image still conveys meaning.',
+        props: withCommon({
+            url: {
+                kind: 'string',
+                required: true,
+                dynamic: true,
+                description: 'The image URL. Subject to the host URL policy (blocked by default).'
+            },
+            description: {
+                kind: 'string',
+                dynamic: true,
+                description: 'Alt text describing the image for accessibility and when the image is blocked.'
+            },
+            fit: {
+                kind: 'enum',
+                values: ['contain', 'cover', 'fill', 'none', 'scaleDown'],
+                default: 'fill',
+                description: 'How the image resizes to fit its box (CSS object-fit).'
+            },
+            variant: {
+                kind: 'enum',
+                values: ['icon', 'avatar', 'smallFeature', 'mediumFeature', 'largeFeature', 'header'],
+                default: 'mediumFeature',
+                description: 'Size/style preset for the image.'
+            }
+        })
+    },
+    Icon: {
+        description: 'Displays a named icon from the mapped set. Use `name` with one of the supported names; unknown names fall back to a generic glyph.',
+        props: withCommon({
+            name: {
+                kind: 'icon',
+                required: true,
+                values: A2UI_ICON_NAMES,
+                description: 'The icon name (one of the supported names). May also bind to the data model with { path }. Custom vector art via { svgPath } is accepted but discouraged.'
+            }
+        })
+    },
+    Button: {
+        description: 'A clickable button. Its `child` is the label (use a Text component). `action` MUST be a server event. Both `child` and `action` are required.',
+        props: withCommon({
+            child: {
+                kind: 'childId',
+                required: true,
+                description: 'The ID of the label component (usually a Text). For an icon-only button pass an Icon ID. Never inline the child.'
+            },
+            action: {
+                kind: 'action',
+                required: true,
+                description: 'The interaction handler. Use the server-event form { event: { name, context } }. Resolve dynamic context values with { path } bindings; use literals for static values.'
+            },
+            variant: {
+                kind: 'enum',
+                values: ['default', 'primary', 'borderless'],
+                default: 'default',
+                description: 'Button style. primary marks the main call to action; borderless renders as a link-like button.'
+            }
+        })
+    },
+    TextField: {
+        description: 'A single- or multi-line text input. `label` is required. Bind `value` to a data-model path for two-way binding (typing writes to the model immediately).',
+        props: withCommon({
+            label: {
+                kind: 'string',
+                required: true,
+                dynamic: true,
+                description: 'The field label.'
+            },
+            value: {
+                kind: 'string',
+                dynamic: true,
+                description: 'The field value. Bind with { path } for two-way binding.'
+            },
+            variant: {
+                kind: 'enum',
+                values: ['shortText', 'longText', 'number', 'obscured'],
+                default: 'shortText',
+                description: 'Input type: shortText (one line), longText (multi-line), number (numeric), obscured (password).'
+            }
+        })
+    },
+    CheckBox: {
+        description: 'A single boolean checkbox with a label. Bind `value` to a data-model boolean for two-way binding.',
+        props: withCommon({
+            label: {
+                kind: 'string',
+                required: true,
+                dynamic: true,
+                description: 'The text shown next to the checkbox.'
+            },
+            value: {
+                kind: 'boolean',
+                required: true,
+                dynamic: true,
+                description: 'The checked state. Bind with { path } for two-way binding.'
+            }
+        })
+    },
+    ChoicePicker: {
+        description: 'Select one or more options from a list. Bind `value` to a data-model string array. Use variant mutuallyExclusive for single-select, multipleSelection for multi-select.',
+        props: withCommon({
+            options: {
+                kind: 'options',
+                required: true,
+                description: 'The available options as an array of { label, value } objects. `value` is a stable string.'
+            },
+            value: {
+                kind: 'stringList',
+                required: true,
+                dynamic: true,
+                description: 'The selected values as a string array in the data model. Single-select writes a one-element array.'
+            },
+            label: {
+                kind: 'string',
+                dynamic: true,
+                description: 'An optional label for the whole group.'
+            },
+            variant: {
+                kind: 'enum',
+                values: ['mutuallyExclusive', 'multipleSelection'],
+                default: 'mutuallyExclusive',
+                description: 'mutuallyExclusive is single-select (radios); multipleSelection allows several.'
+            },
+            displayStyle: {
+                kind: 'enum',
+                values: ['checkbox', 'chips'],
+                default: 'checkbox',
+                promptHidden: true,
+                description: 'Display hint. chips is rendered with a checkbox/radio fallback.'
+            },
+            filterable: {
+                kind: 'boolean',
+                promptHidden: true,
+                description: 'If true, requests a filter input; rendered without one (fallback).'
+            }
+        })
+    },
+    Slider: {
+        description: 'A numeric slider. `value` and `max` are required (`min` defaults to 0). Bind `value` for two-way binding.',
+        props: withCommon({
+            value: {
+                kind: 'number',
+                required: true,
+                dynamic: true,
+                description: 'The current value. Bind with { path } for two-way binding.'
+            },
+            max: {
+                kind: 'number',
+                required: true,
+                description: 'The maximum value.'
+            },
+            min: {
+                kind: 'number',
+                default: 0,
+                description: 'The minimum value (default 0).'
+            },
+            label: {
+                kind: 'string',
+                dynamic: true,
+                description: 'An optional label for the slider.'
+            }
+        })
+    }
+});
+/** Props recognized anywhere but intentionally ignored (validation only, dropped before render). */
+export const A2UI_IGNORED_PROPS = new Set(['checks', 'validationRegexp']);

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

@@ -0,0 +1,96 @@
+/**
+ * Render-tree assembly for the A2UI renderer — the bridge between the pure-TS
+ * processor (`a2ui-validate.ts`, plain Maps) and the recursive Svelte dispatcher
+ * (`A2UINode.svelte`). Pure TS, no Svelte, so `A2UINode` and `A2UIView` share
+ * one typed contract (the house pattern of `md-context.ts`, deliberately not a
+ * Svelte context — the tree is private and explicit prop flow keeps it
+ * inspectable).
+ *
+ * `buildRenderTree` walks the component graph from `root` into a fully-expanded,
+ * BOUNDED node tree: child/children references resolved, list templates expanded
+ * over the data model, dangling references marked, and the depth/node/cycle
+ * limits enforced in ONE place so the Svelte layer can never recurse without
+ * bound regardless of payload. Graph-level ISSUES (the reportable faults) are
+ * still produced by `collectGraphIssues` in `a2ui-validate.ts`; this walk only
+ * shapes what renders.
+ */
+import type { IconComponent } from '../../../icons/index.js';
+import type { MarkdownUrlPolicy } from '../markdown/types.js';
+import type { A2uiActionEvent, A2uiValidationIssue } from './a2ui.types.js';
+import type { A2uiComponentInstance, A2uiSurfaceState } from './a2ui-validate.js';
+/** Default traversal bounds — mirror `collectGraphIssues` so the tree and the issue list agree. */
+export declare const A2UI_MAX_DEPTH = 32;
+export declare const A2UI_MAX_NODES = 512;
+/**
+ * One node of the assembled render tree. `instance === null` marks a dangling
+ * reference (a child id that was never defined) — rendered as a streaming
+ * placeholder or, once settled, a fault chip. `children` are pre-expanded and
+ * ordered; `key` is stable across incremental rebuilds so keyed `{#each}` keeps
+ * component identity (and input focus) through a keystroke-triggered rebuild.
+ */
+export interface A2uiRenderNode {
+    key: string;
+    id: string;
+    instance: A2uiComponentInstance | null;
+    /** Template-item scope for relative-path resolution and two-way write-back. */
+    scopePrefix: string | undefined;
+    children: A2uiRenderNode[];
+    /** flex-grow, present only when this node is a direct Row/Column child with a finite `weight`. */
+    weight?: number;
+}
+/** Static text labels threaded to the node dispatcher (i18n comes from A2UIView props). */
+export interface A2uiRenderLabels {
+    unsupported: string;
+    blockedImage: string;
+    pending: string;
+}
+/**
+ * The single context object each `A2UINode` receives. Carries resolved slot
+ * classes, the icon map, the data-binding resolver, the two-way write-back
+ * callbacks, the action sink and rendering flags. Rebuilt per version bump so a
+ * live data-model edit propagates fresh resolved values without remounting.
+ */
+export interface A2uiRenderContext {
+    /** Resolved class string per slot (tv() + slotClasses + unstyled already applied). */
+    classes: Readonly<Record<string, string>>;
+    urlPolicy: MarkdownUrlPolicy | undefined;
+    /** Dangling refs render placeholders while true; fault chips once false. */
+    streaming: boolean;
+    /** True inside a Button label (Text renders as an inline plain span). */
+    inline: boolean;
+    surfaceId: string;
+    onAction: ((event: A2uiActionEvent) => void) | undefined;
+    /** Resolve a Dynamic value (literal | { path } | function-call) against the model in `scope`. */
+    resolve: (value: unknown, scopePrefix: string | undefined) => {
+        value: unknown;
+        issue?: A2uiValidationIssue;
+    };
+    /** Write a value at an absolute JSON Pointer into the surface model, then bump. */
+    write: (pointer: string, value: unknown) => void;
+    /** Delete the key at an absolute JSON Pointer from the surface model, then bump. */
+    remove: (pointer: string) => void;
+    /** A2UI icon-name → resolved icon component (IconProvider override honoured, direct import fallback). */
+    icons: Readonly<Record<string, IconComponent>>;
+    /** Fallback glyph for an unmapped icon name. */
+    fallbackIcon: IconComponent;
+    labels: A2uiRenderLabels;
+}
+/**
+ * Resolve a `{ path }` data binding to the ABSOLUTE JSON Pointer it addresses,
+ * honouring the template scope for relative paths. Returns `undefined` for
+ * literals and function-call bindings (nothing to write back into).
+ */
+export declare function bindingPointer(value: unknown, scopePrefix: string | undefined): string | undefined;
+/** Coerce an unknown model value to a string array of stable option values (for ChoicePicker). */
+export declare function toStringArray(value: unknown): string[];
+/** Coerce a scalar model value to the string an `<input>` displays. */
+export declare function toInputString(value: unknown): string;
+/**
+ * Assemble the bounded render tree for a surface, starting at `root`. Returns
+ * `null` when no `root` component exists yet (the caller renders a placeholder
+ * while streaming, or a fault chip once settled).
+ */
+export declare function buildRenderTree(surface: A2uiSurfaceState, options?: {
+    maxDepth?: number;
+    maxNodes?: number;
+}): A2uiRenderNode | null;