@adecore/intelligent-ui 0.0.0 → 0.21.1

package/src/compiler.ts

@@ -1,10 +1,29 @@
-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;
@@ -23,11 +42,13 @@ 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;
@@ -44,6 +65,8 @@ 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;
 }
 
@@ -62,10 +85,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 = {
@@ -85,8 +104,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,
@@ -105,7 +132,7 @@ 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;
@@ -135,8 +162,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;
@@ -145,13 +177,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;
                     }
                 }
@@ -160,10 +186,16 @@ 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) {
@@ -188,27 +220,8 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
             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));
         }
@@ -217,14 +230,29 @@ 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)) {
+        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: 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.');
                     }
@@ -235,7 +263,10 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     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 >= UI_HOST_LIMITS.queries) {
+                        throw new UiFailure('budget_exceeded', `A block may declare at most ${UI_HOST_LIMITS.queries} queries.`);
+                    }
+                    block.queries[name] = { source: querySource, args, ...(!isConstant(argument) ? { expression: argument } : {}) };
                 } else {
                     if (!isConstant(expression)) {
                         throw new UiFailure('invalid_default', 'State defaults must be literal JSON values.');
@@ -249,7 +280,7 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                 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('')
@@ -267,36 +298,137 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
     return block;
 }
 
-export function compileUi(text: string, options: UiCompileOptions): UiBlock[] {
-    const blocks: UiBlock[] = [];
-    let fence: { marker: string; length: number; start: number; codeStart: number; ui: boolean } | null = 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 type UiCompilerOptions = Omit<UiCompileOptions, 'final' | 'latestAttachment'>;
+export type UiCompileUpdate = Pick<UiCompileOptions, 'final' | 'latestAttachment'>;
+
+interface CachedUiBlock {
+    source: string;
+    block: UiBlock;
+    latestAttachment?: string;
+}
+
+export class UiCompiler {
+    private readonly options: UiCompilerOptions;
+    private cache = new Map<number, CachedUiBlock>();
+
+    constructor(options: UiCompilerOptions) {
+        this.options = options;
+    }
+
+    compile(text: string, update: UiCompileUpdate = {}): UiBlock[] {
+        const blocks: UiBlock[] = [];
+        const next = new Map<number, CachedUiBlock>();
+        let fence: { marker: string; length: number; start: number; codeStart: number; ui: boolean } | null = null;
+        let position = 0;
+        let characters = 0;
+        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 => ({
+            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: number, codeStart: number, codeEnd: number, end: number, closed: boolean) => {
+            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, diagnostics - 1),
+                        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;
+            }
+            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;
             }
-            fence = null;
+            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() === 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;
         }
-        position += line.length;
+        if (fence?.ui) {
+            append(fence.start, fence.codeStart, text.length, text.length, false);
+        }
+        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(): void {
+        this.cache.clear();
     }
-    return blocks;
+}
+
+/* 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,9 +10,37 @@ 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, 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/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

@@ -0,0 +1,54 @@
+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';
+
+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 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(),
+    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 type UiLinkResolution = z.infer<typeof UiLinkResolutionSchema>;
+
+export function uiLinkTargets(
+    block: UiBlock,
+    input: Readonly<Record<string, unknown>> = {},
+    queries: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
+): Record<string, UiLinkTarget> {
+    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) {
+            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/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;
+}

package/src/protocol.ts

@@ -32,11 +32,12 @@ export const UiDiagnosticSchema = z.object({
 export const UiBlockSchema: z.ZodType<UiBlock> = 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()