@adecore/intelligent-ui 0.0.0 → 0.21.0

package/README.md

@@ -2,7 +2,7 @@
 
 A streaming compiler and bounded expression interpreter for UI blocks in agent replies. The catalog defines props once with Zod. Renderers consume evaluated props and input bindings; they do not evaluate model text.
 
-This package is private while its first publication is being prepared. Chat wire integration, daemon scheduling, host actions, query authorization and platform renderers are separate work. These APIs do not authorize a query or an action.
+Chat wire integration and scheduling are provided by `@adecore/agents`; React renderers are provided by `@adecore/agents-react`. Hosts supply actions, query authorization and platform renderers. The compiler and interpreter do not authorize a query or an action.
 
 ```ts
 import { compileUi, evaluateUiBlock, UiState } from '@adecore/intelligent-ui';
@@ -29,7 +29,7 @@ The parser recovers at the next tag or line after malformed input. Open tags rem
 
 ## Catalog
 
-`UI_CATALOG` contains each component's schema, description, group and applicable parent, child or binding rule. `UI_GROUPS` contains the instructions shared by each group. `isUiComponent` recognizes a catalog name; `uiCatalogText` lists names, props and descriptions for tooling. `uiCompactCatalog` derives the short prop list from those schemas, `uiSessionNote` adds the language instructions, and `uiReferenceText` combines full descriptions with group rules. `uiFallbackText` replaces UI fences with their compiled fallback while retaining surrounding prose.
+`UI_CATALOG` contains each component's schema, description, group and applicable parent, child or binding rule. `UI_GROUPS` contains the instructions shared by each group. `isUiComponent` recognizes a catalog name; `uiCatalogText` lists names, props and descriptions for tooling. `uiCompactCatalog` derives the short prop list from those schemas, `uiSessionNote` adds explicit tag syntax and a fenced example checked by the compiler, and `uiReferenceText` combines full descriptions with group rules. `uiFallbackText` replaces UI fences with their compiled fallback while retaining surrounding prose.
 
 `UiComponentName` is the key union. `UiProps<Name>` is inferred from that component's schema. `UiToneSchema` and `UiTone` provide neutral, info, success, warning and danger. `UI_CATALOG_VERSION` identifies this catalog.
 

package/dist/compiler.d.ts

@@ -3,6 +3,12 @@ import { type UiExpression, type UiValue } from './expression.ts';
 import { type UiDiagnostic } from './syntax.ts';
 import { type z } from 'zod';
 export declare const UI_FENCE_LANGUAGE = "ruimte-ui";
+export declare const UI_REPLY_LIMITS: {
+    readonly blocks: 16;
+    readonly characters: 262144;
+    readonly nodes: 2048;
+    readonly milliseconds: 60;
+};
 export interface UiNode {
     id: string;
     type: string;
@@ -19,10 +25,12 @@ export interface UiNode {
 export interface UiQuery {
     source: string;
     args: Record<string, UiValue>;
+    expression?: UiExpression;
 }
 export interface UiBlock {
     id: string;
     catalogVersion: number;
+    revision?: string;
     start: number;
     end: number;
     complete: boolean;
@@ -41,4 +49,13 @@ export interface UiCompileOptions {
     now?: () => number;
 }
 export declare function compileUiBlock(source: string, options: UiCompileOptions): UiBlock;
+export type UiCompilerOptions = Omit<UiCompileOptions, 'final' | 'latestAttachment'>;
+export type UiCompileUpdate = Pick<UiCompileOptions, 'final' | 'latestAttachment'>;
+export declare class UiCompiler {
+    private readonly options;
+    private cache;
+    constructor(options: UiCompilerOptions);
+    compile(text: string, update?: UiCompileUpdate): UiBlock[];
+    clear(): void;
+}
 export declare function compileUi(text: string, options: UiCompileOptions): UiBlock[];

package/dist/compiler.js

@@ -4,6 +4,7 @@ import { evaluateUiExpression } from './expression.js';
 import { parseUiSyntax, uiDiagnostic } from './syntax.js';
 import {} from 'zod';
 export const UI_FENCE_LANGUAGE = 'ruimte-ui';
+export const UI_REPLY_LIMITS = { blocks: 16, characters: 262144, nodes: 2048, milliseconds: 60 };
 function isConstant(expression) {
     switch (expression.kind) {
         case 'literal':
@@ -178,14 +179,27 @@ export function compileUiBlock(source, options) {
     try {
         const syntax = parseUiSyntax(source, options.id, options.final, budget);
         block.diagnostics = syntax.diagnostics;
-        for (const [name, expression] of Object.entries(syntax.declarations)) {
+        for (const [name, expression] of Object.entries(syntax.declarations).sort(([, a], [, b]) => Number(a.kind === 'call' && a.name === 'Query') - Number(b.kind === 'call' && b.name === 'Query'))) {
             try {
                 if (expression.kind === 'call' && expression.name === 'Query') {
-                    if (expression.args.length !== 2 || !expression.args.every(isConstant)) {
-                        throw new UiFailure('invalid_query', '@Query needs a literal source and literal argument record.');
+                    if (expression.args.length !== 2 || !isConstant(expression.args[0]) || expression.args[1].kind !== 'object') {
+                        throw new UiFailure('invalid_query', '@Query needs a literal source and an argument record.');
                     }
                     const querySource = evaluateUiExpression(expression.args[0], {}, budget);
-                    const args = evaluateUiExpression(expression.args[1], {}, budget);
+                    const argument = expression.args[1];
+                    const references = (part) => {
+                        if (!part || typeof part !== 'object') {
+                            return;
+                        }
+                        if ('kind' in part && part.kind === 'reference' && 'name' in part && !Object.hasOwn(block.defaults, String(part.name))) {
+                            throw new UiFailure('invalid_query', 'Query arguments may reference only declared local state.');
+                        }
+                        for (const value of Object.values(part)) {
+                            references(value);
+                        }
+                    };
+                    references(argument);
+                    const args = evaluateUiExpression(argument, block.defaults, budget);
                     if (typeof querySource !== 'string' || !args || Array.isArray(args) || typeof args !== 'object') {
                         throw new UiFailure('invalid_query', 'Invalid query source or argument record.');
                     }
@@ -196,7 +210,10 @@ export function compileUiBlock(source, options) {
                     if (!checked.success) {
                         throw new UiFailure('invalid_query', 'Query arguments do not match the host schema.');
                     }
-                    block.queries[name] = { source: querySource, args };
+                    if (Object.keys(block.queries).length >= 8) {
+                        throw new UiFailure('budget_exceeded', 'A block may declare at most eight queries.');
+                    }
+                    block.queries[name] = { source: querySource, args, ...(!isConstant(argument) ? { expression: argument } : {}) };
                 }
                 else {
                     if (!isConstant(expression)) {
@@ -230,37 +247,116 @@ export function compileUiBlock(source, options) {
     }
     return block;
 }
-export function compileUi(text, options) {
-    const blocks = [];
-    let fence = null;
-    let position = 0;
-    for (const line of text.split(/(?<=\n)/)) {
-        const opening = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)/.exec(line);
-        if (!fence && opening) {
-            fence = {
-                marker: opening[1][0],
-                length: opening[1].length,
-                start: position,
-                codeStart: position + line.length,
-                ui: opening[2].trim() === UI_FENCE_LANGUAGE
-            };
-        }
-        else if (fence && opening && opening[1][0] === fence.marker && opening[1].length >= fence.length && !opening[2].trim()) {
-            if (fence.ui) {
-                const block = compileUiBlock(text.slice(fence.codeStart, position), { ...options, id: `${options.id}:ui:${fence.start}`, final: true });
-                block.start = fence.start;
-                block.end = position + line.length;
-                blocks.push(block);
+export class UiCompiler {
+    options;
+    cache = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    compile(text, update = {}) {
+        const blocks = [];
+        const next = new Map();
+        let fence = null;
+        let position = 0;
+        let characters = 0;
+        let nodes = 0;
+        let exhausted = false;
+        const now = this.options.now ?? Date.now;
+        const started = now();
+        const nodeCount = (items) => items.reduce((count, node) => count + 1 + nodeCount(node.children), 0);
+        const rejected = (start, codeStart, codeEnd, end, complete) => ({
+            id: `${this.options.id}:ui:${start}`,
+            catalogVersion: UI_CATALOG_VERSION,
+            start,
+            end,
+            complete,
+            defaults: {},
+            queries: {},
+            nodes: [],
+            fallback: text.slice(codeStart, Math.min(codeEnd, codeStart + 4096)),
+            diagnostics: [uiDiagnostic(new UiFailure('budget_exceeded', 'This reply exceeded its UI budget; remaining fences stay text.'), start, end)]
+        });
+        const append = (start, codeStart, codeEnd, end, closed) => {
+            if (exhausted) {
+                return;
+            }
+            if (blocks.length >= UI_REPLY_LIMITS.blocks) {
+                const last = blocks.at(-1);
+                blocks[blocks.length - 1] = {
+                    ...last,
+                    diagnostics: [
+                        ...last.diagnostics.slice(0, 19),
+                        uiDiagnostic(new UiFailure('budget_exceeded', 'Further UI fences stay text because this reply has too many blocks.'), start, end)
+                    ]
+                };
+                exhausted = true;
+                return;
+            }
+            const complete = closed || update.final === true;
+            characters += codeEnd - codeStart;
+            if (characters > UI_REPLY_LIMITS.characters || now() - started > UI_REPLY_LIMITS.milliseconds) {
+                blocks.push(rejected(start, codeStart, codeEnd, end, complete));
+                exhausted = true;
+                return;
             }
-            fence = null;
+            const source = text.slice(codeStart, codeEnd);
+            const cached = this.cache.get(start);
+            const unchanged = !update.final &&
+                cached?.source === source &&
+                cached.block.end === end &&
+                cached.block.complete === complete &&
+                cached.latestAttachment === update.latestAttachment;
+            const block = unchanged
+                ? cached.block
+                : compileUiBlock(source, {
+                    ...this.options,
+                    ...update,
+                    id: `${this.options.id}:ui:${start}`,
+                    final: complete
+                });
+            nodes += nodeCount(block.nodes);
+            if (nodes > UI_REPLY_LIMITS.nodes) {
+                blocks.push(rejected(start, codeStart, codeEnd, end, complete));
+                exhausted = true;
+                return;
+            }
+            block.start = start;
+            block.end = end;
+            blocks.push(block);
+            next.set(start, { source, block, latestAttachment: update.latestAttachment });
+        };
+        while (position < text.length && !exhausted) {
+            const newline = text.indexOf('\n', position);
+            const end = newline === -1 ? text.length : newline + 1;
+            const line = text.slice(position, end);
+            const opening = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)/.exec(line);
+            if (!fence && opening) {
+                fence = {
+                    marker: opening[1][0],
+                    length: opening[1].length,
+                    start: position,
+                    codeStart: position + line.length,
+                    ui: opening[2].trim() === UI_FENCE_LANGUAGE
+                };
+            }
+            else if (fence && opening && opening[1][0] === fence.marker && opening[1].length >= fence.length && !opening[2].trim()) {
+                if (fence.ui) {
+                    append(fence.start, fence.codeStart, position, position + line.length, true);
+                }
+                fence = null;
+            }
+            position = end;
+        }
+        if (fence?.ui) {
+            append(fence.start, fence.codeStart, text.length, text.length, false);
         }
-        position += line.length;
+        this.cache = next;
+        return blocks;
     }
-    if (fence?.ui) {
-        const block = compileUiBlock(text.slice(fence.codeStart), { ...options, id: `${options.id}:ui:${fence.start}` });
-        block.start = fence.start;
-        block.end = text.length;
-        blocks.push(block);
+    clear() {
+        this.cache.clear();
     }
-    return blocks;
+}
+export function compileUi(text, options) {
+    return new UiCompiler(options).compile(text, options);
 }

package/dist/index.d.ts

@@ -2,7 +2,10 @@ export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent,
 export { UI_LIMITS, UiBudget, UiFailure, safeKey, type UiLimits } from './budget.ts';
 export { copyUiValue, evaluateUiExpression, parseUiExpression, type UiExpression, type UiValue } from './expression.ts';
 export { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntax, type UiSyntaxNode } from './syntax.ts';
-export { UI_FENCE_LANGUAGE, compileUi, compileUiBlock, type UiBlock, type UiCompileOptions, type UiNode, type UiQuery } from './compiler.ts';
-export { evaluateUiBlock, UiState, type UiBinding, type UiEvaluation, type UiViewNode } from './runtime.ts';
+export { UI_FENCE_LANGUAGE, UI_REPLY_LIMITS, UiCompiler, compileUi, compileUiBlock, type UiCompilerOptions, type UiCompileUpdate, type UiBlock, type UiCompileOptions, type UiNode, type UiQuery } from './compiler.ts';
+export { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice, type UiChoiceSelection, type UiBinding, type UiEvaluation, type UiViewNode } from './runtime.ts';
+export { uiValidatedState, uiQueryArguments, uiQueryFallback } from './query.ts';
 export { UiNodeSchema, UiDiagnosticSchema, UiBlockSchema, UiBlocksSchema } from './protocol.ts';
 export { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText } from './text.ts';
+export { UI_STREAM_INTERVAL_MS, UiStream, type UiStreamClock, type UiStreamOptions, type UiStreamPreview } from './stream.ts';
+export { UiLinkTargetSchema, UiLinkResolutionSchema, uiLinkTargets, type UiLinkTarget, type UiLinkResolution } from './links.ts';

package/dist/index.js

@@ -2,7 +2,10 @@ export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent,
 export { UI_LIMITS, UiBudget, UiFailure, safeKey } from './budget.js';
 export { copyUiValue, evaluateUiExpression, parseUiExpression } from './expression.js';
 export { parseUiSyntax, uiDiagnostic } from './syntax.js';
-export { UI_FENCE_LANGUAGE, compileUi, compileUiBlock } from './compiler.js';
-export { evaluateUiBlock, UiState } from './runtime.js';
+export { UI_FENCE_LANGUAGE, UI_REPLY_LIMITS, UiCompiler, compileUi, compileUiBlock } from './compiler.js';
+export { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice } from './runtime.js';
+export { uiValidatedState, uiQueryArguments, uiQueryFallback } from './query.js';
 export { UiNodeSchema, UiDiagnosticSchema, UiBlockSchema, UiBlocksSchema } from './protocol.js';
 export { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText } from './text.js';
+export { UI_STREAM_INTERVAL_MS, UiStream } from './stream.js';
+export { UiLinkTargetSchema, UiLinkResolutionSchema, uiLinkTargets } from './links.js';

package/dist/links.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { UiBlock } from './compiler.ts';
+export declare const UiLinkTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"File">;
+    path: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"Diff">;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"Commit">;
+    sha: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"Node">;
+    id: z.ZodString;
+}, z.core.$strict>], "type">;
+export type UiLinkTarget = z.infer<typeof UiLinkTargetSchema>;
+export declare const UiLinkResolutionSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        chip: "chip";
+        plain: "plain";
+    }>;
+    target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"File">;
+        path: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"Diff">;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"Commit">;
+        sha: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"Node">;
+        id: z.ZodString;
+    }, z.core.$strict>], "type">>;
+    cwd: z.ZodOptional<z.ZodString>;
+    viewId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    staged: z.ZodOptional<z.ZodBoolean>;
+    conflicted: z.ZodOptional<z.ZodBoolean>;
+    relativePath: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UiLinkResolution = z.infer<typeof UiLinkResolutionSchema>;
+export declare function uiLinkTargets(block: UiBlock, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>): Record<string, UiLinkTarget>;

package/dist/links.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { evaluateUiBlock } from './runtime.js';
+import { uiValidatedState } from './query.js';
+export const UiLinkTargetSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('File'), path: z.string().min(1).max(4096), line: z.number().int().positive().optional() }).strict(),
+    z.object({ type: z.literal('Diff'), path: z.string().min(1).max(4096) }).strict(),
+    z.object({ type: z.literal('Commit'), sha: z.string().regex(/^[a-f\d]{7,64}$/i) }).strict(),
+    z.object({ type: z.literal('Node'), id: z.string().min(1).max(256) }).strict()
+]);
+export const UiLinkResolutionSchema = z.object({
+    state: z.enum(['chip', 'plain']),
+    target: UiLinkTargetSchema.optional(),
+    cwd: z.string().optional(),
+    viewId: z.string().optional(),
+    projectId: z.string().optional(),
+    staged: z.boolean().optional(),
+    conflicted: z.boolean().optional(),
+    relativePath: z.string().optional(),
+    label: z.string().optional(),
+    reason: z.string().optional()
+});
+export function uiLinkTargets(block, input = {}, queries = {}) {
+    const state = uiValidatedState(block, input, queries);
+    const targets = Object.create(null);
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.error || !node.complete) {
+                continue;
+            }
+            const checked = UiLinkTargetSchema.safeParse({ type: node.type, ...node.props });
+            if (checked.success) {
+                targets[node.id] = checked.data;
+            }
+            visit(node.children);
+        }
+    };
+    visit(evaluateUiBlock(block, state).nodes);
+    return targets;
+}

package/dist/protocol.js

@@ -25,11 +25,12 @@ export const UiDiagnosticSchema = z.object({
 export const UiBlockSchema = z.object({
     id: z.string(),
     catalogVersion: position,
+    revision: z.string().min(1).optional(),
     start: position,
     end: position,
     complete: z.boolean(),
     defaults: values,
-    queries: z.record(z.string(), z.object({ source: z.string(), args: values })),
+    queries: z.record(z.string(), z.object({ source: z.string(), args: values, expression: z.unknown().optional() })),
     nodes: z.array(UiNodeSchema),
     diagnostics: z.array(UiDiagnosticSchema),
     fallback: z.string()

package/dist/query.d.ts

@@ -0,0 +1,6 @@
+import type { UiBlock } from './compiler.ts';
+import { type UiValue } from './expression.ts';
+import { UiState } from './runtime.ts';
+export declare function uiValidatedState(block: UiBlock, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>): UiState;
+export declare function uiQueryArguments(block: UiBlock, name: string, input?: Readonly<Record<string, unknown>>): Record<string, UiValue>;
+export declare function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string, unknown>>): string;

package/dist/query.js

@@ -0,0 +1,115 @@
+import { UI_CATALOG_VERSION } from './catalog.js';
+import { UiBudget, UiFailure } from './budget.js';
+import { copyUiValue, evaluateUiExpression } from './expression.js';
+import { evaluateUiBlock, uiInputValues, UiState } from './runtime.js';
+function findBinding(nodes, id, prop) {
+    for (const node of nodes) {
+        if (node.id === id) {
+            return node.bindings[prop];
+        }
+        const found = findBinding(node.children, id, prop);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+export function uiValidatedState(block, input = {}, queries = {}) {
+    if (!block.complete || block.catalogVersion !== UI_CATALOG_VERSION) {
+        throw new UiFailure('invalid_block', 'Only completed supported blocks can resolve input.');
+    }
+    const values = copyUiValue(input, new UiBudget());
+    const state = new UiState(block);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const allowed = uiInputValues(block, state);
+    for (const [key, value] of Object.entries(values)) {
+        if (!Object.hasOwn(allowed, key)) {
+            throw new UiFailure('refused_binding', 'Only declared input bindings can be submitted.');
+        }
+        state.set(key, value);
+    }
+    const visible = new Set();
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.error || !node.complete) {
+                continue;
+            }
+            let valid = true;
+            if (node.type === 'Segmented') {
+                valid = node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
+            }
+            if (node.type === 'Checklist') {
+                const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
+                valid = node.props.value.every((value) => options.includes(value));
+            }
+            if (valid) {
+                for (const [key, binding] of Object.entries(node.bindings)) {
+                    const original = findBinding(block.nodes, node.sourceId ?? node.id, key);
+                    if (original && binding) {
+                        visible.add(original);
+                    }
+                }
+            }
+            visit(node.children);
+        }
+    };
+    const evaluated = evaluateUiBlock(block, state);
+    if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
+        throw new UiFailure('budget_exceeded', 'The query inputs exceeded their evaluation budget.');
+    }
+    visit(evaluated.nodes);
+    for (const [key, value] of Object.entries(values)) {
+        if (JSON.stringify(value) !== JSON.stringify(allowed[key]) && !visible.has(key)) {
+            throw new UiFailure('invalid_value', 'An input value is outside the visible control’s allowed values.');
+        }
+    }
+    return state;
+}
+export function uiQueryArguments(block, name, input = {}) {
+    if (!Object.hasOwn(block.queries, name)) {
+        throw new UiFailure('invalid_query', 'This block does not declare that query.');
+    }
+    const state = uiValidatedState(block, input);
+    const query = block.queries[name];
+    return query.expression
+        ? evaluateUiExpression(query.expression, state.scope(), new UiBudget())
+        : copyUiValue(query.args, new UiBudget());
+}
+export function uiQueryFallback(block, queries) {
+    const state = new UiState(block);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const plain = (value) => (value == null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value));
+    const text = (nodes) => nodes
+        .map((node) => {
+        if (node.error) {
+            return node.fallback;
+        }
+        if (node.type === '$text') {
+            return plain(node.props.text);
+        }
+        const props = node.props;
+        const children = text(node.children);
+        if (node.type === 'Stat') {
+            return `${plain(props.label)}: ${plain(props.value)}${props.unit ? ` ${plain(props.unit)}` : ''}\n`;
+        }
+        if (node.type === 'Table') {
+            return `${plain(props.rows)}\n`;
+        }
+        if (node.type === 'Chart') {
+            return `${plain(props.data)}\n`;
+        }
+        if (node.type === 'Source') {
+            return `${plain(props.label)}: ${plain(props.url)}\n`;
+        }
+        if (node.type === 'Image') {
+            return node.fallback;
+        }
+        return `${(props.label ?? props.title) ? `${plain(props.label ?? props.title)}: ` : ''}${plain(props.path ?? props.sha ?? (node.type === 'Node' ? props.id : null))}${children}${props.context ? `\n${plain(props.context)}` : ''}${node.type === 'Tag' ? '' : '\n'}`;
+    })
+        .join('');
+    return text(evaluateUiBlock(block, state).nodes).trim() || block.fallback;
+}

package/dist/runtime.d.ts

@@ -8,6 +8,7 @@ export interface UiBinding<Value> {
 }
 export interface UiViewNode<Props = Record<string, unknown>> {
     id: string;
+    sourceId?: string;
     type: string;
     props: Props;
     bindings: Readonly<Record<string, UiBinding<unknown>>>;
@@ -39,3 +40,10 @@ export declare class UiState {
     private changed;
 }
 export declare function evaluateUiBlock(block: UiBlock, state?: UiState, limits?: Partial<UiLimits>): UiEvaluation;
+export interface UiChoiceSelection {
+    label: string;
+    context: string;
+    values: Record<string, UiValue>;
+}
+export declare function uiInputValues(block: UiBlock, state: UiState): Record<string, UiValue>;
+export declare function resolveUiChoice(block: UiBlock, choiceId: string, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>): UiChoiceSelection;

package/dist/runtime.js

@@ -119,6 +119,7 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
     const visit = (node, variables, depth, suffix = '') => {
         const view = {
             id: `${node.id}${suffix}`,
+            sourceId: node.id,
             type: node.type,
             props: {},
             bindings: {},
@@ -212,3 +213,107 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
     }
     return result;
 }
+export function uiInputValues(block, state) {
+    const scope = state.scope();
+    const values = Object.create(null);
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (isUiComponent(node.type) && !node.error && node.complete) {
+                const entry = UI_CATALOG[node.type];
+                for (const [prop, name] of Object.entries(node.bindings)) {
+                    if ('binding' in entry && entry.binding === prop && Object.hasOwn(block.defaults, name) && !Object.hasOwn(block.queries, name)) {
+                        values[name] = scope[name];
+                    }
+                }
+            }
+            visit(node.children);
+        }
+    };
+    visit(block.nodes);
+    return values;
+}
+/* The host supplies its stored block; client data can change only declared input bindings. */
+export function resolveUiChoice(block, choiceId, input = {}, queries = {}) {
+    if (!block.complete || block.catalogVersion !== UI_CATALOG_VERSION) {
+        throw new UiFailure('refused_choice', 'Only a completed supported block can send a choice.');
+    }
+    const values = copyUiValue(input, new UiBudget());
+    const state = new UiState(block);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const allowed = uiInputValues(block, state);
+    const changed = new Set();
+    for (const [name, value] of Object.entries(values)) {
+        if (!Object.hasOwn(allowed, name)) {
+            throw new UiFailure('refused_binding', 'Only declared input bindings can be submitted.');
+        }
+        if (JSON.stringify(value) !== JSON.stringify(allowed[name])) {
+            state.set(name, value);
+            changed.add(name);
+        }
+    }
+    const evaluated = evaluateUiBlock(block, state);
+    if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
+        throw new UiFailure('budget_exceeded', 'The choice exceeded its evaluation budget.');
+    }
+    const validInputs = new Set();
+    let choice;
+    const written = new Map();
+    const remember = (nodes) => {
+        for (const node of nodes) {
+            written.set(node.id, node);
+            remember(node.children);
+        }
+    };
+    remember(block.nodes);
+    const visit = (nodes, parent) => {
+        for (const node of nodes) {
+            const source = written.get(node.sourceId ?? node.id);
+            if (node.error && source && Object.values(source.bindings).some((name) => changed.has(name))) {
+                throw new UiFailure('invalid_value', 'An input value does not match its control.');
+            }
+            if (node.error || !node.complete) {
+                continue;
+            }
+            let valid = true;
+            if (node.type === 'Segmented') {
+                valid = node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
+            }
+            else if (node.type === 'Checklist') {
+                const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
+                valid = node.props.value.every((value) => options.includes(value));
+            }
+            if (valid && source) {
+                for (const prop of Object.keys(node.bindings)) {
+                    validInputs.add(source.bindings[prop]);
+                }
+            }
+            if (node.id === choiceId && node.type === 'Choice' && parent === 'Choices' && node.props.disabled !== true) {
+                choice = node;
+            }
+            visit(node.children, node.type);
+        }
+    };
+    visit(evaluated.nodes);
+    if ([...changed].some((name) => !validInputs.has(name))) {
+        throw new UiFailure('invalid_value', 'An input value is outside the visible control’s allowed values.');
+    }
+    if (!choice) {
+        throw new UiFailure('refused_choice', 'This choice is not available in the current block.');
+    }
+    const text = (nodes) => nodes.map((node) => (node.type === '$text' ? String(node.props.text ?? '') : text(node.children))).join('');
+    const hasError = (nodes) => nodes.some((node) => node.error !== undefined || hasError(node.children));
+    if (hasError(choice.children)) {
+        throw new UiFailure('refused_choice', 'The choice label could not be fully read.');
+    }
+    const label = text(choice.children).replace(/\s+/g, ' ').trim();
+    if (!label) {
+        throw new UiFailure('refused_choice', 'A choice needs a visible label.');
+    }
+    return {
+        label,
+        values: uiInputValues(block, state),
+        context: typeof choice.props.context === 'string' && choice.props.context.trim() ? choice.props.context : label
+    };
+}