@adecore/intelligent-ui 0.21.0 → 0.21.2

package/src/actions.ts

@@ -0,0 +1,39 @@
+import { UiFailure } from './budget.ts';
+import { isUiComponent, UI_CATALOG } from './catalog.ts';
+import type { UiBlock } from './compiler.ts';
+import type { UiExpression } from './expression.ts';
+
+/* The prop of a component that holds a state action, kept unevaluated, instead of a value. */
+export function uiActionProp(type: string): string | undefined {
+    if (!isUiComponent(type)) {
+        return undefined;
+    }
+    const entry = UI_CATALOG[type];
+    return 'action' in entry ? entry.action : undefined;
+}
+
+/*
+ * The variable an action writes, or null for `@Reset()`, which restores them all. Throws for anything
+ * but `@Set($name, value)`, `@Reset($name)` and `@Reset()` on a variable that `local` accepts.
+ */
+export function uiActionTarget(action: UiExpression, local: (name: string) => boolean): string | null {
+    if (action.kind !== 'call' || (action.name !== 'Set' && action.name !== 'Reset')) {
+        throw new UiFailure('refused_action', 'Expected @Set or @Reset.');
+    }
+    if (action.name === 'Reset' && action.args.length === 0) {
+        return null;
+    }
+    if (action.args.length !== (action.name === 'Set' ? 2 : 1)) {
+        throw new UiFailure('refused_action', 'Invalid state action arguments.');
+    }
+    const reference = action.args[0];
+    if (reference.kind !== 'reference' || !local(reference.name)) {
+        throw new UiFailure('refused_binding', 'The action needs a local state variable.');
+    }
+    return reference.name;
+}
+
+/* Whether `name` is local state of the block: declared with a default and never a query. */
+export function uiLocalState(block: Pick<UiBlock, 'defaults' | 'queries'>): (name: string) => boolean {
+    return (name) => Object.hasOwn(block.defaults, name) && !Object.hasOwn(block.queries, name);
+}

package/src/catalog.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { uiPropList } from './prop-list.ts';
 
 export const UI_CATALOG_VERSION = 1;
 export const UiToneSchema = z.enum(['neutral', 'info', 'success', 'warning', 'danger']);
@@ -21,7 +22,10 @@ export const UI_GROUPS = {
         rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path.'
     },
     links: { description: 'Refer to a host-owned resource.', rules: 'Targets are checked by the host. No arbitrary navigation or file reads.' },
-    inputs: { description: 'Change local block state.', rules: 'Bind value={$name}. State stays local until a Choice sends visible context.' },
+    inputs: {
+        description: 'Change local block state.',
+        rules: 'Bind value={$name}. A Button sets a literal with action={@Set($name, value)} or restores a default with {@Reset($name)} or {@Reset()}. State stays local until a Choice sends visible context.'
+    },
     choices: {
         description: 'Ask the person to pick a next step.',
         rules: 'Give a short label and precise visible context. A Choice sends once after streaming ends.'
@@ -120,6 +124,12 @@ export const UI_CATALOG = {
     },
     Segmented: { group: 'inputs', description: 'Choose one local value.', schema: z.strictObject({ value: scalar }), children: ['Option'], binding: 'value' },
     Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: 'Segmented' },
+    Button: {
+        group: 'inputs',
+        description: 'Run one local state action when pressed; children are the label.',
+        schema: z.strictObject({ disabled: z.boolean().optional() }),
+        action: 'action'
+    },
     Show: { group: 'inputs', description: 'Show children when the condition is true.', schema: z.strictObject({ when: z.boolean() }) },
     Each: {
         group: 'inputs',
@@ -144,12 +154,6 @@ export function isUiComponent(name: string): name is UiComponentName {
 
 export function uiCatalogText(): string {
     return Object.entries(UI_CATALOG)
-        .map(([name, entry]) => {
-            const shape = entry.schema.shape;
-            const props = Object.entries(shape)
-                .map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`)
-                .join(', ');
-            return `${name}(${props}): ${entry.description}`;
-        })
+        .map(([name, entry]) => `${name}(${uiPropList(entry).join(', ')}): ${entry.description}`)
         .join('\n');
 }

package/src/compiler.ts

@@ -1,13 +1,30 @@
-import { safeKey, UiBudget, UiFailure, type UiLimits } from './budget.ts';
+import { safeKey, UI_LIMITS, UiBudget, UiFailure, type UiLimits } from './budget.ts';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.ts';
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.ts';
+import { uiNodeFallback, uiPlainText } from './fallback.ts';
 import { evaluateUiExpression, type UiExpression, type UiValue } from './expression.ts';
 import { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntaxNode } from './syntax.ts';
 import { type z } from 'zod';
 
-export const UI_FENCE_LANGUAGE = 'ruimte-ui';
+// The info string a fence carries when the host names none of its own.
+export const UI_FENCE_LANGUAGE = 'ui';
 
 export const UI_REPLY_LIMITS = { blocks: 16, characters: 262144, nodes: 2048, milliseconds: 60 } as const;
 
+// What a host reads for one block: its queries, its link targets and how often a visible block reads again.
+export const UI_HOST_LIMITS = { queries: 8, links: 64, refreshMilliseconds: 10_000 } as const;
+
+/* A cheap test for whether `text` may declare a query or name a link target, before anything is read for it. */
+export function uiMayReferenceHost(text: string): boolean {
+    if (text.includes('@Query')) {
+        return true;
+    }
+    const links = Object.entries(UI_CATALOG)
+        .filter(([, entry]) => entry.group === 'links')
+        .map(([name]) => name);
+    return new RegExp(`<(?:${links.join('|')})\\b`).test(text);
+}
+
 export interface UiNode {
     id: string;
     type: string;
@@ -48,9 +65,64 @@ export interface UiCompileOptions {
     limits?: Partial<UiLimits>;
     latestAttachment?: string;
     querySchemas?: Readonly<Record<string, z.ZodType>>;
+    // The info string that marks a UI fence; `UI_FENCE_LANGUAGE` without one.
+    fenceLanguage?: string;
     now?: () => number;
 }
 
+/* A spent budget ends the whole block; every other failure only marks the node or declaration it came from. */
+function rethrowBudget(error: unknown): void {
+    if (error instanceof UiFailure && error.code === 'budget_exceeded') {
+        throw error;
+    }
+}
+
+function isQuery(expression: UiExpression): boolean {
+    return expression.kind === 'call' && expression.name === 'Query';
+}
+
+/* Throws when a query argument reads anything but declared local state. */
+function checkQueryReferences(part: unknown, defaults: Readonly<Record<string, UiValue>>): void {
+    if (!part || typeof part !== 'object') {
+        return;
+    }
+    if ('kind' in part && part.kind === 'reference' && 'name' in part && !Object.hasOwn(defaults, String(part.name))) {
+        throw new UiFailure('invalid_query', 'Query arguments may reference only declared local state.');
+    }
+    for (const value of Object.values(part)) {
+        checkQueryReferences(value, defaults);
+    }
+}
+
+function compileQuery(
+    expression: Extract<UiExpression, { kind: 'call' }>,
+    block: UiBlock,
+    budget: UiBudget,
+    querySchemas: UiCompileOptions['querySchemas']
+): UiQuery {
+    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 argument = expression.args[1];
+    checkQueryReferences(argument, block.defaults);
+    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.');
+    }
+    if (!querySchemas || !Object.hasOwn(querySchemas, querySource)) {
+        throw new UiFailure('unknown_query', 'The host did not register this query source.');
+    }
+    const checked = querySchemas[querySource].safeParse(args);
+    if (!checked.success) {
+        throw new UiFailure('invalid_query', 'Query arguments do not match the host schema.');
+    }
+    if (Object.keys(block.queries).length >= UI_HOST_LIMITS.queries) {
+        throw new UiFailure('budget_exceeded', `A block may declare at most ${UI_HOST_LIMITS.queries} queries.`);
+    }
+    return { source: querySource, args, ...(!isConstant(argument) ? { expression: argument } : {}) };
+}
+
 function isConstant(expression: UiExpression): boolean {
     switch (expression.kind) {
         case 'literal':
@@ -66,10 +138,6 @@ function isConstant(expression: UiExpression): boolean {
     }
 }
 
-function plain(value: UiValue): string {
-    return value === null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
-}
-
 export function compileUiBlock(source: string, options: UiCompileOptions): UiBlock {
     const budget = new UiBudget(options.limits, options.now);
     const block: UiBlock = {
@@ -89,8 +157,16 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
             block.diagnostics.push(uiDiagnostic(error, start, end, nodeId));
         }
     };
-    const compile = (syntax: UiSyntaxNode, parent?: string): UiNode => {
-        budget.depth(0);
+    // A pressed action must set the same value whatever state it is pressed in, so a choice can check it.
+    const checkedAction = (action: UiExpression): UiExpression => {
+        uiActionTarget(action, uiLocalState(block));
+        if (action.kind === 'call' && action.name === 'Set' && !isConstant(action.args[1])) {
+            throw new UiFailure('refused_action', '@Set in an action takes a literal value.');
+        }
+        return action;
+    };
+    const compile = (syntax: UiSyntaxNode, depth: number, parent?: string): UiNode => {
+        budget.depth(depth);
         const node: UiNode = {
             id: syntax.id,
             type: syntax.type,
@@ -109,11 +185,9 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                 if (syntax.expression) {
                     node.expressions.text = syntax.expression;
                     try {
-                        node.fallback = plain(evaluateUiExpression(syntax.expression, block.defaults, budget));
+                        node.fallback = uiPlainText(evaluateUiExpression(syntax.expression, block.defaults, budget));
                     } catch (error) {
-                        if (error instanceof UiFailure && error.code === 'budget_exceeded') {
-                            throw error;
-                        }
+                        rethrowBudget(error);
                     }
                 } else {
                     node.props.text = syntax.text ?? '';
@@ -139,8 +213,13 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     throw new UiFailure('invalid_child', `${syntax.type} is not a child of ${parent}.`);
                 }
             }
+            const actionProp = uiActionProp(syntax.type);
             for (const [key, expression] of Object.entries(syntax.props)) {
                 safeKey(key);
+                if (key === actionProp) {
+                    node.expressions[key] = checkedAction(expression);
+                    continue;
+                }
                 if (!Object.hasOwn(entry.schema.shape, key)) {
                     diagnose(new UiFailure('refused_prop', `${syntax.type} does not accept ${key}.`), syntax.start, syntax.end, syntax.id);
                     continue;
@@ -149,13 +228,7 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     node.props[key] = evaluateUiExpression(expression, {}, budget);
                 } else {
                     node.expressions[key] = expression;
-                    if (
-                        'binding' in entry &&
-                        entry.binding === key &&
-                        expression.kind === 'reference' &&
-                        Object.hasOwn(block.defaults, expression.name) &&
-                        !Object.hasOwn(block.queries, expression.name)
-                    ) {
+                    if ('binding' in entry && entry.binding === key && expression.kind === 'reference' && uiLocalState(block)(expression.name)) {
                         node.bindings[key] = expression.name;
                     }
                 }
@@ -164,16 +237,20 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                 delete node.props.generated;
                 node.props.attachment = options.latestAttachment;
             }
+            if (actionProp !== undefined && syntax.complete && !node.expressions[actionProp]) {
+                throw new UiFailure('invalid_props', `${syntax.type} needs ${actionProp}.`);
+            }
             const evaluated: Record<string, UiValue> = { ...node.props };
             fallbackProps = evaluated;
             let unresolved = false;
             for (const [key, expression] of Object.entries(node.expressions)) {
+                if (key === actionProp) {
+                    continue;
+                }
                 try {
                     evaluated[key] = evaluateUiExpression(expression, block.defaults, budget);
                 } catch (error) {
-                    if (error instanceof UiFailure && error.code === 'budget_exceeded') {
-                        throw error;
-                    }
+                    rethrowBudget(error);
                     unresolved = true;
                 }
             }
@@ -185,34 +262,13 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                 }
             }
         } catch (error) {
-            if (error instanceof UiFailure && error.code === 'budget_exceeded') {
-                throw error;
-            }
+            rethrowBudget(error);
             node.error = error instanceof UiFailure ? error.code : 'invalid_props';
             diagnose(error, syntax.start, syntax.end, syntax.id);
         }
         const effectiveParent = syntax.type === 'Show' || syntax.type === 'Each' ? parent : syntax.type;
-        node.children = syntax.children.map((child) => compile(child, effectiveParent));
-        const children = node.children.map((child) => child.fallback).join('');
-        const label = fallbackProps.label ?? fallbackProps.title;
-        const value = fallbackProps.value;
-        const target = fallbackProps.path ?? fallbackProps.sha ?? (syntax.type === 'Node' ? fallbackProps.id : undefined);
-        if (syntax.type === 'Stat') {
-            node.fallback = `${plain(label ?? '')}: ${plain(value ?? '')}${fallbackProps.unit ? ` ${plain(fallbackProps.unit)}` : ''}\n`;
-        } else if (syntax.type === 'Source') {
-            node.fallback = `${plain(label ?? '')}: ${plain(fallbackProps.url ?? '')}\n`;
-        } else if (syntax.type === 'Table') {
-            node.fallback = `${plain(fallbackProps.rows ?? [])}\n`;
-        } else if (syntax.type === 'Chart') {
-            node.fallback = `${plain(fallbackProps.data ?? [])}\n`;
-        } else if (syntax.type === 'Image') {
-            node.fallback = `[Image: ${plain(fallbackProps.alt ?? fallbackProps.attachment ?? fallbackProps.generated ?? 'unavailable')}]${children}\n`;
-        } else {
-            node.fallback = `${label !== undefined ? `${plain(label)}: ` : ''}${target !== undefined ? `${plain(target)} ` : ''}${children}${fallbackProps.context ? `\n${plain(fallbackProps.context)}` : ''}`;
-            if (syntax.type !== 'Tag' && !node.fallback.endsWith('\n')) {
-                node.fallback += '\n';
-            }
-        }
+        node.children = syntax.children.map((child) => compile(child, depth + 1, effectiveParent));
+        node.fallback = uiNodeFallback(syntax.type, fallbackProps, node.children.map((child) => child.fallback).join(''));
         if (!node.fallback.trim()) {
             node.fallback = source.slice(syntax.start, Math.min(syntax.end, syntax.start + 1024));
         }
@@ -221,43 +277,12 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
     try {
         const syntax = parseUiSyntax(source, options.id, options.final, budget);
         block.diagnostics = syntax.diagnostics;
-        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')
-        )) {
+        // Defaults first, so a query argument can read every one of them.
+        const declarations = Object.entries(syntax.declarations).sort(([, left], [, right]) => Number(isQuery(left)) - Number(isQuery(right)));
+        for (const [name, expression] of declarations) {
             try {
                 if (expression.kind === 'call' && expression.name === 'Query') {
-                    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 argument = expression.args[1];
-                    const references = (part: unknown): void => {
-                        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.');
-                    }
-                    if (!options.querySchemas || !Object.hasOwn(options.querySchemas, querySource)) {
-                        throw new UiFailure('unknown_query', 'The host did not register this query source.');
-                    }
-                    const checked = options.querySchemas[querySource].safeParse(args);
-                    if (!checked.success) {
-                        throw new UiFailure('invalid_query', 'Query arguments do not match the host schema.');
-                    }
-                    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 } : {}) };
+                    block.queries[name] = compileQuery(expression, block, budget, options.querySchemas);
                 } else {
                     if (!isConstant(expression)) {
                         throw new UiFailure('invalid_default', 'State defaults must be literal JSON values.');
@@ -265,13 +290,11 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     block.defaults[name] = evaluateUiExpression(expression, {}, budget);
                 }
             } catch (error) {
-                if (error instanceof UiFailure && error.code === 'budget_exceeded') {
-                    throw error;
-                }
+                rethrowBudget(error);
                 diagnose(error, 0, source.length);
             }
         }
-        block.nodes = syntax.nodes.map((node) => compile(node));
+        block.nodes = syntax.nodes.map((node) => compile(node, 0));
         block.fallback = block.nodes
             .map((node) => node.fallback)
             .join('')
@@ -315,6 +338,8 @@ export class UiCompiler {
         let nodes = 0;
         let exhausted = false;
         const now = this.options.now ?? Date.now;
+        const language = this.options.fenceLanguage ?? UI_FENCE_LANGUAGE;
+        const diagnostics = this.options.limits?.diagnostics ?? UI_LIMITS.diagnostics;
         const started = now();
         const nodeCount = (items: readonly UiNode[]): number => items.reduce((count, node) => count + 1 + nodeCount(node.children), 0);
         const rejected = (start: number, codeStart: number, codeEnd: number, end: number, complete: boolean): UiBlock => ({
@@ -338,7 +363,7 @@ export class UiCompiler {
                 blocks[blocks.length - 1] = {
                     ...last,
                     diagnostics: [
-                        ...last.diagnostics.slice(0, 19),
+                        ...last.diagnostics.slice(0, diagnostics - 1),
                         uiDiagnostic(new UiFailure('budget_exceeded', 'Further UI fences stay text because this reply has too many blocks.'), start, end)
                     ]
                 };
@@ -390,7 +415,7 @@ export class UiCompiler {
                     length: opening[1].length,
                     start: position,
                     codeStart: position + line.length,
-                    ui: opening[2].trim() === UI_FENCE_LANGUAGE
+                    ui: opening[2].trim() === language
                 };
             } else if (fence && opening && opening[1][0] === fence.marker && opening[1].length >= fence.length && !opening[2].trim()) {
                 if (fence.ui) {
@@ -412,6 +437,12 @@ export class UiCompiler {
     }
 }
 
+/* A cheap test for whether `text` opens a UI fence at all, before a compiler is worth creating. */
+export function uiHasFence(text: string, fenceLanguage: string = UI_FENCE_LANGUAGE): boolean {
+    const language = fenceLanguage.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^ {0,3}(?:\`{3,}|~{3,})[ \\t]*${language}[ \\t]*\\r?$`, 'm').test(text);
+}
+
 export function compileUi(text: string, options: UiCompileOptions): UiBlock[] {
     return new UiCompiler(options).compile(text, options);
 }

package/src/expression.ts

@@ -243,6 +243,23 @@ export function parseUiExpression(source: string, budget = new UiBudget()): UiEx
     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: UiValue, second: UiValue): boolean {
+    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 as Record<string, UiValue>;
+    const right = second as Record<string, UiValue>;
+    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: unknown, budget = new UiBudget(), depth = 0): UiValue {
     budget.depth(depth);
     if (value === null || typeof value === 'boolean') {

package/src/fallback.ts

@@ -0,0 +1,26 @@
+export function uiPlainText(value: unknown): string {
+    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: string, props: Readonly<Record<string, unknown>>, children: string): string {
+    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/src/index.ts

@@ -10,14 +10,17 @@ export {
     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,
+    UI_HOST_LIMITS,
     UI_REPLY_LIMITS,
     UiCompiler,
     compileUi,
     compileUiBlock,
+    uiHasFence,
+    uiMayReferenceHost,
     type UiCompilerOptions,
     type UiCompileUpdate,
     type UiBlock,
@@ -37,7 +40,7 @@ export {
 } 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/src/inputs.ts

@@ -0,0 +1,74 @@
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.ts';
+import type { UiBlock, UiNode } from './compiler.ts';
+import { evaluateUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
+import type { UiViewNode } from './runtime.ts';
+
+export function uiCompiledNodes(nodes: readonly UiNode[], into = new Map<string, UiNode>()): Map<string, UiNode> {
+    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: UiViewNode): boolean {
+    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 as unknown[]).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: UiExpression, block: UiBlock): { target: string; value: UiValue } | undefined {
+    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: UiBlock, nodes: readonly UiViewNode[], scope: Readonly<Record<string, UiValue>>): Set<string> {
+    const written = uiCompiledNodes(block.nodes);
+    const inputs = new Set<string>();
+    const visit = (views: readonly UiViewNode[]) => {
+        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/src/links.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { UiLimits } from './budget.ts';
 import type { UiBlock } from './compiler.ts';
 import { evaluateUiBlock, type UiViewNode } from './runtime.ts';
 import { uiValidatedState } from './query.ts';
@@ -11,6 +12,7 @@ export const UiLinkTargetSchema = z.discriminatedUnion('type', [
 ]);
 export type UiLinkTarget = z.infer<typeof UiLinkTargetSchema>;
 
+// `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(),
@@ -21,6 +23,8 @@ export const UiLinkResolutionSchema = z.object({
     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 type UiLinkResolution = z.infer<typeof UiLinkResolutionSchema>;
@@ -28,9 +32,10 @@ export type UiLinkResolution = z.infer<typeof UiLinkResolutionSchema>;
 export function uiLinkTargets(
     block: UiBlock,
     input: Readonly<Record<string, unknown>> = {},
-    queries: Readonly<Record<string, unknown>> = {}
+    queries: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
 ): Record<string, UiLinkTarget> {
-    const state = uiValidatedState(block, input, queries);
+    const state = uiValidatedState(block, input, queries, limits);
     const targets: Record<string, UiLinkTarget> = Object.create(null);
     const visit = (nodes: readonly UiViewNode[]) => {
         for (const node of nodes) {
@@ -44,6 +49,6 @@ export function uiLinkTargets(
             visit(node.children);
         }
     };
-    visit(evaluateUiBlock(block, state).nodes);
+    visit(evaluateUiBlock(block, state, limits).nodes);
     return targets;
 }

package/src/prop-list.ts

@@ -0,0 +1,7 @@
+import type { z } from 'zod';
+
+/* The props a catalog entry accepts, its action first and an optional one marked with `?`. */
+export function uiPropList(entry: { readonly schema: { readonly shape: Readonly<Record<string, z.ZodType>> }; readonly action?: string }): string[] {
+    const props = Object.entries(entry.schema.shape).map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`);
+    return entry.action ? [entry.action, ...props] : props;
+}