@adecore/intelligent-ui 0.21.0 → 0.21.1

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,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;
 }
 
@@ -66,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 = {
@@ -89,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,
@@ -109,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;
@@ -139,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;
@@ -149,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;
                     }
                 }
@@ -164,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) {
@@ -192,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));
         }
@@ -254,8 +263,8 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     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.');
+                    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 {
@@ -271,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('')
@@ -315,6 +324,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 +349,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 +401,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 +423,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;
+}

package/src/query.ts

@@ -1,28 +1,22 @@
 import { UI_CATALOG_VERSION } from './catalog.ts';
-import { UiBudget, UiFailure } from './budget.ts';
-import type { UiBlock, UiNode } from './compiler.ts';
-import { copyUiValue, evaluateUiExpression, type UiValue } from './expression.ts';
+import { UiBudget, UiFailure, type UiLimits } from './budget.ts';
+import type { UiBlock } from './compiler.ts';
+import { uiVisibleInputs } from './inputs.ts';
+import { uiNodeFallback } from './fallback.ts';
+import { copyUiValue, evaluateUiExpression, sameUiValue, type UiValue } from './expression.ts';
 import { evaluateUiBlock, uiInputValues, UiState, type UiViewNode } from './runtime.ts';
 
-function findBinding(nodes: readonly UiNode[], id: string, prop: string): string | undefined {
-    for (const node of nodes) {
-        if (node.id === id) {
-            return node.bindings[prop];
-        }
-        const found = findBinding(node.children, id, prop);
-        if (found) {
-            return found;
-        }
-    }
-    return undefined;
-}
-
-export function uiValidatedState(block: UiBlock, input: Readonly<Record<string, unknown>> = {}, queries: Readonly<Record<string, unknown>> = {}): UiState {
+export function uiValidatedState(
+    block: UiBlock,
+    input: Readonly<Record<string, unknown>> = {},
+    queries: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
+): UiState {
     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()) as Record<string, UiValue>;
-    const state = new UiState(block);
+    const values = copyUiValue(input, new UiBudget(limits)) as Record<string, UiValue>;
+    const state = new UiState(block, limits);
     for (const [name, value] of Object.entries(queries)) {
         state.setQuery(name, value, block);
     }
@@ -33,53 +27,33 @@ export function uiValidatedState(block: UiBlock, input: Readonly<Record<string,
         }
         state.set(key, value);
     }
-    const visible = new Set<string>();
-    const visit = (nodes: readonly UiViewNode[]) => {
-        for (const node of nodes) {
-            if (node.error || !node.complete) {
-                continue;
-            }
-            let valid = true;
-            if (node.type === 'Segmented') {
-                valid = node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
-            }
-            if (node.type === 'Checklist') {
-                const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
-                valid = (node.props.value as unknown[]).every((value) => options.includes(value));
-            }
-            if (valid) {
-                for (const [key, binding] of Object.entries(node.bindings)) {
-                    const original = findBinding(block.nodes, node.sourceId ?? node.id, key);
-                    if (original && binding) {
-                        visible.add(original);
-                    }
-                }
-            }
-            visit(node.children);
-        }
-    };
-    const evaluated = evaluateUiBlock(block, state);
+    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.');
     }
-    visit(evaluated.nodes);
+    const visible = uiVisibleInputs(block, evaluated.nodes, state.scope());
     for (const [key, value] of Object.entries(values)) {
-        if (JSON.stringify(value) !== JSON.stringify(allowed[key]) && !visible.has(key)) {
+        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: UiBlock, name: string, input: Readonly<Record<string, unknown>> = {}): Record<string, UiValue> {
+export function uiQueryArguments(
+    block: UiBlock,
+    name: string,
+    input: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
+): Record<string, UiValue> {
     if (!Object.hasOwn(block.queries, name)) {
         throw new UiFailure('invalid_query', 'This block does not declare that query.');
     }
-    const state = uiValidatedState(block, input);
+    const state = uiValidatedState(block, input, {}, limits);
     const query = block.queries[name];
     return query.expression
-        ? (evaluateUiExpression(query.expression, state.scope(), new UiBudget()) as Record<string, UiValue>)
-        : (copyUiValue(query.args, new UiBudget()) as Record<string, UiValue>);
+        ? (evaluateUiExpression(query.expression, state.scope(), new UiBudget(limits)) as Record<string, UiValue>)
+        : (copyUiValue(query.args, new UiBudget(limits)) as Record<string, UiValue>);
 }
 
 export function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string, unknown>>): string {
@@ -87,35 +61,7 @@ export function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string,
     for (const [name, value] of Object.entries(queries)) {
         state.setQuery(name, value, block);
     }
-    const plain = (value: unknown) => (value == null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value));
     const text = (nodes: readonly UiViewNode[]): string =>
-        nodes
-            .map((node) => {
-                if (node.error) {
-                    return node.fallback;
-                }
-                if (node.type === '$text') {
-                    return plain(node.props.text);
-                }
-                const props = node.props;
-                const children = text(node.children);
-                if (node.type === 'Stat') {
-                    return `${plain(props.label)}: ${plain(props.value)}${props.unit ? ` ${plain(props.unit)}` : ''}\n`;
-                }
-                if (node.type === 'Table') {
-                    return `${plain(props.rows)}\n`;
-                }
-                if (node.type === 'Chart') {
-                    return `${plain(props.data)}\n`;
-                }
-                if (node.type === 'Source') {
-                    return `${plain(props.label)}: ${plain(props.url)}\n`;
-                }
-                if (node.type === 'Image') {
-                    return node.fallback;
-                }
-                return `${(props.label ?? props.title) ? `${plain(props.label ?? props.title)}: ` : ''}${plain(props.path ?? props.sha ?? (node.type === 'Node' ? props.id : null))}${children}${props.context ? `\n${plain(props.context)}` : ''}${node.type === 'Tag' ? '' : '\n'}`;
-            })
-            .join('');
+        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;
 }