@adecore/intelligent-ui 0.0.0 → 0.21.1

package/dist/expression.js

@@ -230,6 +230,22 @@ class ExpressionParser {
 export function parseUiExpression(source, budget = new UiBudget()) {
     return new ExpressionParser(source, budget).parse();
 }
+/* Deep equality of two values, regardless of the order their record keys were written in. */
+export function sameUiValue(first, second) {
+    if (first === second) {
+        return true;
+    }
+    if (first === null || second === null || typeof first !== 'object' || typeof second !== 'object' || Array.isArray(first) !== Array.isArray(second)) {
+        return false;
+    }
+    if (Array.isArray(first) && Array.isArray(second)) {
+        return first.length === second.length && first.every((item, i) => sameUiValue(item, second[i]));
+    }
+    const left = first;
+    const right = second;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && sameUiValue(left[key], right[key]));
+}
 export function copyUiValue(value, budget = new UiBudget(), depth = 0) {
     budget.depth(depth);
     if (value === null || typeof value === 'boolean') {

package/dist/fallback.d.ts

@@ -0,0 +1,2 @@
+export declare function uiPlainText(value: unknown): string;
+export declare function uiNodeFallback(type: string, props: Readonly<Record<string, unknown>>, children: string): string;

package/dist/fallback.js

@@ -0,0 +1,25 @@
+export function uiPlainText(value) {
+    return value == null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+/* The readable text a node leaves behind where it cannot be drawn, from its props and its children's text. */
+export function uiNodeFallback(type, props, children) {
+    const label = props.label ?? props.title;
+    switch (type) {
+        case '$text':
+            return uiPlainText(props.text);
+        case 'Stat':
+            return `${uiPlainText(label)}: ${uiPlainText(props.value)}${props.unit ? ` ${uiPlainText(props.unit)}` : ''}\n`;
+        case 'Source':
+            return `${uiPlainText(label)}: ${uiPlainText(props.url)}\n`;
+        case 'Table':
+            return `${uiPlainText(props.rows ?? [])}\n`;
+        case 'Chart':
+            return `${uiPlainText(props.data ?? [])}\n`;
+        case 'Image':
+            return `[Image: ${uiPlainText(props.alt ?? props.attachment ?? props.generated ?? 'unavailable')}]${children}\n`;
+    }
+    const target = props.path ?? props.sha ?? (type === 'Node' ? props.id : undefined);
+    const context = props.context ? `\n${uiPlainText(props.context)}` : '';
+    const text = `${label !== undefined ? `${uiPlainText(label)}: ` : ''}${target !== undefined ? `${uiPlainText(target)} ` : ''}${children}${context}`;
+    return type === 'Tag' || text.endsWith('\n') ? text : `${text}\n`;
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent, uiCatalogText, type UiComponentName, type UiProps, type UiTone } from './catalog.ts';
 export { UI_LIMITS, UiBudget, UiFailure, safeKey, type UiLimits } from './budget.ts';
-export { copyUiValue, evaluateUiExpression, parseUiExpression, type UiExpression, type UiValue } from './expression.ts';
+export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue, 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_HOST_LIMITS, UI_REPLY_LIMITS, UiCompiler, compileUi, compileUiBlock, uiHasFence, uiMayReferenceHost, 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 { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText, type UiTextOptions } 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

@@ -1,8 +1,11 @@
 export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent, uiCatalogText } from './catalog.js';
 export { UI_LIMITS, UiBudget, UiFailure, safeKey } from './budget.js';
-export { copyUiValue, evaluateUiExpression, parseUiExpression } from './expression.js';
+export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue } 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_HOST_LIMITS, UI_REPLY_LIMITS, UiCompiler, compileUi, compileUiBlock, uiHasFence, uiMayReferenceHost } 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/inputs.d.ts

@@ -0,0 +1,5 @@
+import type { UiBlock, UiNode } from './compiler.ts';
+import { type UiValue } from './expression.ts';
+import type { UiViewNode } from './runtime.ts';
+export declare function uiCompiledNodes(nodes: readonly UiNode[], into?: Map<string, UiNode>): Map<string, UiNode>;
+export declare function uiVisibleInputs(block: UiBlock, nodes: readonly UiViewNode[], scope: Readonly<Record<string, UiValue>>): Set<string>;

package/dist/inputs.js

@@ -0,0 +1,69 @@
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
+import { evaluateUiExpression, sameUiValue } from './expression.js';
+export function uiCompiledNodes(nodes, into = new Map()) {
+    for (const node of nodes) {
+        into.set(node.id, node);
+        uiCompiledNodes(node.children, into);
+    }
+    return into;
+}
+/* Whether a control's value is one its own visible options offer. */
+function offered(node) {
+    if (node.type === 'Segmented') {
+        return 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);
+        return node.props.value.every((value) => options.includes(value));
+    }
+    return true;
+}
+/*
+ * The value pressing a Button sets its target to, or undefined when it sets none. A Button's @Set takes
+ * a literal only, so the value never depends on the state it was pressed in.
+ */
+function actionValue(action, block) {
+    try {
+        const target = uiActionTarget(action, uiLocalState(block));
+        if (target === null || action.kind !== 'call') {
+            return undefined;
+        }
+        return { target, value: action.name === 'Set' ? evaluateUiExpression(action.args[1], {}) : block.defaults[target] };
+    }
+    catch {
+        return undefined;
+    }
+}
+/*
+ * The variables whose current value a visible, complete control of the evaluated tree accounts for: a bound
+ * control holding it within what it offers, or an enabled Button that sets exactly that value. A submitted
+ * value outside this set, and unequal to its default, is one no person could have produced on the screen.
+ */
+export function uiVisibleInputs(block, nodes, scope) {
+    const written = uiCompiledNodes(block.nodes);
+    const inputs = new Set();
+    const visit = (views) => {
+        for (const node of views) {
+            if (node.error || !node.complete) {
+                continue;
+            }
+            const source = written.get(node.sourceId ?? node.id);
+            if (source && offered(node)) {
+                for (const prop of Object.keys(node.bindings)) {
+                    if (source.bindings[prop]) {
+                        inputs.add(source.bindings[prop]);
+                    }
+                }
+            }
+            const actionProp = uiActionProp(node.type);
+            const action = source && actionProp ? source.expressions[actionProp] : undefined;
+            const pressed = action && node.props.disabled !== true ? actionValue(action, block) : undefined;
+            if (pressed && sameUiValue(pressed.value, scope[pressed.target])) {
+                inputs.add(pressed.target);
+            }
+            visit(node.children);
+        }
+    };
+    visit(nodes);
+    return inputs;
+}

package/dist/links.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import type { UiLimits } from './budget.ts';
+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>;
+    code: 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>>, limits?: Partial<UiLimits>): Record<string, UiLinkTarget>;

package/dist/links.js

@@ -0,0 +1,42 @@
+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()
+]);
+// `state` is a frozen set: native clients validate these payloads whole, so a new state would fail them.
+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(),
+    // A code that names the reason across versions; open, so a new one fails nobody.
+    code: z.string().optional(),
+    reason: z.string().optional()
+});
+export function uiLinkTargets(block, input = {}, queries = {}, limits = {}) {
+    const state = uiValidatedState(block, input, queries, limits);
+    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, limits).nodes);
+    return targets;
+}

package/dist/prop-list.d.ts

@@ -0,0 +1,7 @@
+import type { z } from 'zod';
+export declare function uiPropList(entry: {
+    readonly schema: {
+        readonly shape: Readonly<Record<string, z.ZodType>>;
+    };
+    readonly action?: string;
+}): string[];

package/dist/prop-list.js

@@ -0,0 +1,5 @@
+/* The props a catalog entry accepts, its action first and an optional one marked with `?`. */
+export function uiPropList(entry) {
+    const props = Object.entries(entry.schema.shape).map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`);
+    return entry.action ? [entry.action, ...props] : props;
+}

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,7 @@
+import { type UiLimits } from './budget.ts';
+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>>, limits?: Partial<UiLimits>): UiState;
+export declare function uiQueryArguments(block: UiBlock, name: string, input?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>): Record<string, UiValue>;
+export declare function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string, unknown>>): string;

package/dist/query.js

@@ -0,0 +1,52 @@
+import { UI_CATALOG_VERSION } from './catalog.js';
+import { UiBudget, UiFailure } from './budget.js';
+import { uiVisibleInputs } from './inputs.js';
+import { uiNodeFallback } from './fallback.js';
+import { copyUiValue, evaluateUiExpression, sameUiValue } from './expression.js';
+import { evaluateUiBlock, uiInputValues, UiState } from './runtime.js';
+export function uiValidatedState(block, input = {}, queries = {}, limits = {}) {
+    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(limits));
+    const state = new UiState(block, limits);
+    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 evaluated = evaluateUiBlock(block, state, limits);
+    if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
+        throw new UiFailure('budget_exceeded', 'The query inputs exceeded their evaluation budget.');
+    }
+    const visible = uiVisibleInputs(block, evaluated.nodes, state.scope());
+    for (const [key, value] of Object.entries(values)) {
+        if (!sameUiValue(value, 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 = {}, limits = {}) {
+    if (!Object.hasOwn(block.queries, name)) {
+        throw new UiFailure('invalid_query', 'This block does not declare that query.');
+    }
+    const state = uiValidatedState(block, input, {}, limits);
+    const query = block.queries[name];
+    return query.expression
+        ? evaluateUiExpression(query.expression, state.scope(), new UiBudget(limits))
+        : copyUiValue(query.args, new UiBudget(limits));
+}
+export function uiQueryFallback(block, queries) {
+    const state = new UiState(block);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const text = (nodes) => nodes.map((node) => (node.error ? node.fallback : uiNodeFallback(node.type, node.props, text(node.children)))).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>>>;
@@ -15,6 +16,7 @@ export interface UiViewNode<Props = Record<string, unknown>> {
     complete: boolean;
     fallback: string;
     error?: string;
+    onAction?(): void;
 }
 export interface UiEvaluation {
     nodes: UiViewNode[];
@@ -28,7 +30,8 @@ export declare class UiState {
     private querySignatures;
     private readonly listeners;
     private revision;
-    constructor(block: UiBlock);
+    private readonly limits;
+    constructor(block: UiBlock, limits?: Partial<UiLimits>);
     sync(block: UiBlock): void;
     snapshot(): number;
     subscribe(listener: () => void): () => void;
@@ -39,3 +42,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>>, limits?: Partial<UiLimits>): UiChoiceSelection;

package/dist/runtime.js

@@ -1,7 +1,9 @@
-import { copyUiValue, evaluateUiExpression } from './expression.js';
+import { copyUiValue, evaluateUiExpression, sameUiValue } from './expression.js';
 import { UiBudget, UiFailure } from './budget.js';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.js';
 import {} from './compiler.js';
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
+import { uiCompiledNodes, uiVisibleInputs } from './inputs.js';
 import { uiDiagnostic } from './syntax.js';
 export class UiState {
     id = '';
@@ -11,17 +13,19 @@ export class UiState {
     querySignatures = Object.create(null);
     listeners = new Set();
     revision = 0;
-    constructor(block) {
+    limits;
+    constructor(block, limits = {}) {
+        this.limits = limits;
         this.sync(block);
     }
     sync(block) {
-        const defaults = copyUiValue(block.defaults);
+        const defaults = copyUiValue(block.defaults, new UiBudget(this.limits));
         if (this.id !== block.id) {
             this.values = Object.create(null);
             this.queries = Object.create(null);
         }
         for (const [name, value] of Object.entries(defaults)) {
-            if (this.id !== block.id || !Object.hasOwn(this.defaults, name) || JSON.stringify(this.defaults[name]) !== JSON.stringify(value)) {
+            if (this.id !== block.id || !Object.hasOwn(this.defaults, name) || !sameUiValue(this.defaults[name], value)) {
                 this.values[name] = value;
             }
         }
@@ -50,13 +54,13 @@ export class UiState {
         return () => this.listeners.delete(listener);
     }
     scope() {
-        return copyUiValue({ ...this.values, ...this.queries });
+        return copyUiValue({ ...this.values, ...this.queries }, new UiBudget(this.limits));
     }
     set(name, value) {
         if (!Object.hasOwn(this.defaults, name)) {
             throw new UiFailure('refused_binding', 'Only declared local state can be changed.');
         }
-        const next = copyUiValue(value);
+        const next = copyUiValue(value, new UiBudget(this.limits));
         const initial = this.defaults[name];
         if (Array.isArray(next) !== Array.isArray(initial) || typeof next !== typeof initial || (next === null) !== (initial === null)) {
             throw new UiFailure('invalid_value', 'The state type cannot change.');
@@ -68,30 +72,20 @@ export class UiState {
         if (block.id !== this.id || !Object.hasOwn(block.queries, name) || this.querySignatures[name] !== JSON.stringify(block.queries[name])) {
             throw new UiFailure('refused_query', 'The query must belong to this block.');
         }
-        this.queries[name] = copyUiValue(value);
+        this.queries[name] = copyUiValue(value, new UiBudget(this.limits));
         this.changed();
     }
     run(action) {
-        if (action.kind !== 'call' || !['Set', 'Reset'].includes(action.name)) {
-            throw new UiFailure('refused_action', 'Expected @Set or @Reset.');
-        }
-        if (action.name === 'Reset' && action.args.length === 0) {
-            this.values = copyUiValue(this.defaults);
+        const target = uiActionTarget(action, (name) => Object.hasOwn(this.defaults, name));
+        if (target === null) {
+            this.values = copyUiValue(this.defaults, new UiBudget(this.limits));
             this.changed();
-            return;
-        }
-        const reference = action.args[0];
-        if (!reference || reference.kind !== 'reference' || !Object.hasOwn(this.defaults, reference.name)) {
-            throw new UiFailure('refused_binding', 'The action needs a local state variable.');
-        }
-        if (action.name === 'Set' && action.args.length === 2) {
-            this.set(reference.name, evaluateUiExpression(action.args[1], this.scope()));
         }
-        else if (action.name === 'Reset' && action.args.length === 1) {
-            this.set(reference.name, this.defaults[reference.name]);
+        else if (action.kind === 'call' && action.name === 'Set') {
+            this.set(target, evaluateUiExpression(action.args[1], this.scope(), new UiBudget(this.limits)));
         }
         else {
-            throw new UiFailure('refused_action', 'Invalid state action arguments.');
+            this.set(target, this.defaults[target]);
         }
     }
     changed() {
@@ -119,6 +113,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: {},
@@ -133,8 +128,11 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
                 throw new UiFailure(node.error ?? 'unknown_catalog', 'This part uses an unsupported UI definition.');
             }
             const props = copyUiValue(node.props, budget);
+            const actionProp = uiActionProp(node.type);
             for (const [key, expression] of Object.entries(node.expressions)) {
-                props[key] = evaluateUiExpression(expression, variables, budget);
+                if (key !== actionProp) {
+                    props[key] = evaluateUiExpression(expression, variables, budget);
+                }
             }
             if (node.type === '$text') {
                 if (typeof props.text !== 'string' && typeof props.text !== 'number' && typeof props.text !== 'boolean' && props.text !== null) {
@@ -173,7 +171,7 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
             }
             const bindings = Object.create(null);
             for (const [key, name] of Object.entries(node.bindings)) {
-                if (!('binding' in entry) || entry.binding !== key || !Object.hasOwn(block.defaults, name) || Object.hasOwn(block.queries, name)) {
+                if (!('binding' in entry) || entry.binding !== key || !uiLocalState(block)(name)) {
                     throw new UiFailure('refused_binding', 'The binding must target declared local input state.');
                 }
                 bindings[key] = {
@@ -190,6 +188,24 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
                 };
             }
             view.bindings = bindings;
+            const action = actionProp === undefined ? undefined : node.expressions[actionProp];
+            if (action) {
+                uiActionTarget(action, uiLocalState(block));
+                view.onAction = () => {
+                    if (!node.complete || props.disabled === true) {
+                        return;
+                    }
+                    try {
+                        state.run(action);
+                    }
+                    catch (error) {
+                        // An action that cannot apply to the current state leaves it as it was.
+                        if (!(error instanceof UiFailure)) {
+                            throw error;
+                        }
+                    }
+                };
+            }
             view.children = children(node.children, variables, depth + 1, suffix);
             return [view];
         }
@@ -212,3 +228,101 @@ 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 local = uiLocalState(block);
+    const actionTarget = (action) => {
+        try {
+            return uiActionTarget(action, local);
+        }
+        catch {
+            return 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 && local(name)) {
+                        values[name] = scope[name];
+                    }
+                }
+                const actionProp = uiActionProp(node.type);
+                const target = actionProp && node.expressions[actionProp] ? actionTarget(node.expressions[actionProp]) : null;
+                if (target !== null) {
+                    values[target] = scope[target];
+                }
+            }
+            visit(node.children);
+        }
+    };
+    visit(block.nodes);
+    return values;
+}
+/* The host supplies its stored block; client data can change only declared inputs and Button targets. */
+export function resolveUiChoice(block, choiceId, input = {}, queries = {}, limits = {}) {
+    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(limits));
+    const state = new UiState(block, limits);
+    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 (!sameUiValue(value, allowed[name])) {
+            state.set(name, value);
+            changed.add(name);
+        }
+    }
+    const evaluated = evaluateUiBlock(block, state, limits);
+    if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
+        throw new UiFailure('budget_exceeded', 'The choice exceeded its evaluation budget.');
+    }
+    let choice;
+    const written = uiCompiledNodes(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;
+            }
+            if (node.id === choiceId && node.type === 'Choice' && parent === 'Choices' && node.props.disabled !== true) {
+                choice = node;
+            }
+            visit(node.children, node.type);
+        }
+    };
+    visit(evaluated.nodes);
+    const validInputs = uiVisibleInputs(block, evaluated.nodes, state.scope());
+    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
+    };
+}

package/dist/stream.d.ts

@@ -0,0 +1,28 @@
+import { type UiBlock, type UiCompilerOptions } from './compiler.ts';
+export declare const UI_STREAM_INTERVAL_MS = 250;
+export interface UiStreamClock {
+    now(): number;
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface UiStreamPreview {
+    textLength: number;
+    blocks: UiBlock[];
+}
+export interface UiStreamOptions extends UiCompilerOptions {
+    clock: UiStreamClock;
+    emit(preview: UiStreamPreview): void;
+}
+export declare class UiStream {
+    private readonly compiler;
+    private readonly options;
+    private pending;
+    private timer;
+    private lastCompiledAt;
+    private closed;
+    constructor(options: UiStreamOptions);
+    update(text: string, latestAttachment?: string): void;
+    finish(text: string, latestAttachment?: string): UiBlock[];
+    dispose(): void;
+    private flush;
+}