@adecore/intelligent-ui 0.21.0 → 0.21.2

package/README.md

@@ -1,72 +1,44 @@
 # @adecore/intelligent-ui
 
-A streaming compiler and bounded expression interpreter for UI blocks in agent replies. The catalog defines props once with Zod. Renderers consume evaluated props and input bindings; they do not evaluate model text.
+[![npm](https://img.shields.io/npm/v/@adecore/intelligent-ui)](https://www.npmjs.com/package/@adecore/intelligent-ui)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/intelligent-ui/)
 
-Chat wire integration and scheduling are provided by `@adecore/agents`; React renderers are provided by `@adecore/agents-react`. Hosts supply actions, query authorization and platform renderers. The compiler and interpreter do not authorize a query or an action.
+Lets an agent answer with a block of components instead of prose: a summary, a table, a checklist, the next steps a person picks from. The package holds the catalog, a compiler that reads blocks out of a reply while it streams, and a bounded interpreter for their state and expressions. No framework and no DOM: a renderer draws what it returns. A block cannot run code, load an address or act outside itself.
 
-```ts
-import { compileUi, evaluateUiBlock, UiState } from '@adecore/intelligent-ui';
-
-const blocks = compileUi(reply, { id: assistantItemId, final: true });
-for (const block of blocks) {
-    const state = new UiState(block);
-    const view = evaluateUiBlock(block, state);
-    render(view.nodes);
-}
-```
-
-## Compilation
-
-`compileUi(text, options)` finds blocks marked with `UI_FENCE_LANGUAGE` among Markdown, including unfinished fences. It ignores UI fences nested inside another code fence. Each `UiBlock` has its own ID, text range, catalog version, declarations, nodes, diagnostics and Markdown fallback. `compileUiBlock(source, options)` compiles one fence's contents.
-
-`UiCompileOptions.id` identifies the assistant item or block. Supply the same ID on each recompile. Node IDs include the start of their tag, so appending text preserves them. `final` reports unfinished syntax when the authoritative response arrives. `latestAttachment` resolves `Image generated="latest"` to an attachment. `limits` overrides the work budget; `now` supplies a clock for deterministic tests.
-
-The parser recovers at the next tag or line after malformed input. Open tags remain incomplete. A streamed quoted prop exposes the text already received. CodeBlock contents are literal, including angle brackets and braces. Unknown components retain their own fallback; unknown props produce `refused_prop` and are dropped. A budget failure replaces the whole compiled block with a bounded fallback and one diagnosis.
-
-`UiNode` keeps static `props` separate from `expressions` and local-variable `bindings`. Its `type` is a string so an unfamiliar component can fall back without rejecting neighboring content. `UiNodeSchema`, `UiBlockSchema`, `UiBlocksSchema` and `UiDiagnosticSchema` describe the wire envelope. Component names, props and expressions stay open, so a future catalog can be retained and shown as fallback. The optional assistant field and daemon integration still await the package's first publication setup.
+**[Documentation](https://adecore.dev/intelligent-ui/)**
 
-`parseUiSyntax` exposes the intermediate `UiSyntax` and `UiSyntaxNode` for compiler tooling. `UiDiagnostic` carries a code, message, source range and optional node ID. `uiDiagnostic` turns a caught failure into that shape.
+## Install
 
-## Catalog
-
-`UI_CATALOG` contains each component's schema, description, group and applicable parent, child or binding rule. `UI_GROUPS` contains the instructions shared by each group. `isUiComponent` recognizes a catalog name; `uiCatalogText` lists names, props and descriptions for tooling. `uiCompactCatalog` derives the short prop list from those schemas, `uiSessionNote` adds explicit tag syntax and a fenced example checked by the compiler, and `uiReferenceText` combines full descriptions with group rules. `uiFallbackText` replaces UI fences with their compiled fallback while retaining surrounding prose.
-
-`UiComponentName` is the key union. `UiProps<Name>` is inferred from that component's schema. `UiToneSchema` and `UiTone` provide neutral, info, success, warning and danger. `UI_CATALOG_VERSION` identifies this catalog.
-
-| Group | Components |
-| --- | --- |
-| Status | Summary, Callout, Tag, Progress, Steps / Step |
-| Data | Stats / Stat, EntityList / Entry, Table / Column, Chart |
-| Structure | Tabs / Tab, Sections / Section |
-| Content | CodeBlock, Image, Sources / Source |
-| Host links | File, Diff, Commit, Node |
-| Local inputs | Checklist / Item, Switch, Slider, Segmented / Option, Show, Each |
-| Choices | Choices / Choice |
-
-Image accepts exactly one of `attachment` and `generated="latest"`, plus an optional alt and caption. It never takes a URL or a filesystem path. Charts use rows with a label and numeric series; their renderer will validate usable series before drawing. A Column names a field and optionally its title, unit and presentation.
-
-## Expressions and state
+```sh
+bun add @adecore/intelligent-ui
+```
 
-`parseUiExpression(source, budget?)` returns a `UiExpression` AST. `evaluateUiExpression(ast, variables?, budget?)` returns a finite JSON `UiValue`. It supports scalar, array and object literals, variables, own field/index reads, arithmetic, strict comparisons, boolean operators and these helpers:
+## Use
 
-| Helper | Arguments |
-| --- | --- |
-| `@Count` | list or string |
-| `@Filter` | list, local name, boolean predicate, e.g. `@Filter($rows, row, row.failed)` |
-| `@Sum` | numeric list, or record list and a field name |
-| `@Join` | scalar list and optional separator |
-| `@Round` | number and optional precision from zero to six |
+```ts
+import { compileUi, evaluateUiBlock, uiSessionNote, UiState } from '@adecore/intelligent-ui';
 
-There is no JavaScript execution, general function call, assignment, network access or inherited field access. `__proto__`, `constructor` and `prototype` are refused. `copyUiValue` validates and copies JSON input without invoking accessors; class instances, nonfinite numbers, sparse arrays and cycles are refused.
+const instructions = uiSessionNote(); // tell the agent the language
 
-`UiState` belongs to one chat/item/block identity. `sync(block)` preserves edits when a declaration's default is unchanged, resets changed defaults, removes disappeared variables and clears changed query data. A reload creates a new state from defaults. `scope()` returns a safe copy. `set(name, value)` changes a declared local variable without changing its type. `run(ast)` accepts only `@Set($name, expression)`, `@Reset($name)` and `@Reset()`. `snapshot()` and `subscribe(listener)` let a renderer observe input edits.
+const blocks = compileUi(replyText, { id: replyId, final: true });
+for (const block of blocks) {
+    const state = new UiState(block);
+    render(evaluateUiBlock(block, state).nodes);
+}
+```
 
-`evaluateUiBlock(block, state?, limits?)` returns `UiEvaluation`, including `UiViewNode` objects and per-element diagnostics. View nodes contain validated evaluated props, children and `UiBinding` callbacks. A binding changes state only after its input node is complete and the new prop passes its schema. Show and Each are resolved before rendering. Repetition reserves iterations before allocating children. Unknown catalog versions and invalid elements retain their fallback.
+`@adecore/agents` compiles the blocks of a chat session, and `@adecore/agents-react` draws them with live data, links and choices.
 
-`$name = @Query("source", {literalArgs})` requires a matching schema in `UiCompileOptions.querySchemas`. It yields a read-only `UiQuery`; ordinary value evaluation never performs a query. The authorized host may supply data with `state.setQuery(name, value, block)`. Results for replaced query definitions are refused. Transport, quotas, rights, fixed versus variable arguments and visible-only refresh still belong to the upcoming host integration.
+## Documentation
 
-## Budgets and acceptance
+| Page | What it covers |
+|---|---|
+| [Getting started](https://adecore.dev/intelligent-ui/guide/getting-started) | Instructions, compilation, the wire and rendering |
+| [Security model](https://adecore.dev/intelligent-ui/guide/security) | What a block can and cannot do |
+| [Syntax](https://adecore.dev/intelligent-ui/language/syntax) | The language an agent writes |
+| [Components](https://adecore.dev/intelligent-ui/components/status) | Every component and its props |
+| [Live queries](https://adecore.dev/intelligent-ui/host/queries) | Data a host reads for a block |
 
-`UI_LIMITS` bounds characters, nesting, nodes, diagnoses, steps, iterations, string length and elapsed time. `UiLimits` describes overrides. `UiBudget` counts work inside helpers as well as ordinary evaluation. `UiFailure` carries a machine-readable refusal code; `safeKey` applies the forbidden-field rule.
+## License
 
-The tests compile ten hand-written examples and every character prefix, then exercise malformed syntax, prototype/accessor attacks, helper budgets, output expansion, query replacement and state reset. Recorded Claude/Codex responses, daemon event-loop/log measurements and iPhone JavaScriptCore parity remain acceptance work. The package does not yet render replies in an application.
+FSL-1.1-MIT, see [LICENSE](./LICENSE).

package/dist/actions.d.ts

@@ -0,0 +1,5 @@
+import type { UiBlock } from './compiler.ts';
+import type { UiExpression } from './expression.ts';
+export declare function uiActionProp(type: string): string | undefined;
+export declare function uiActionTarget(action: UiExpression, local: (name: string) => boolean): string | null;
+export declare function uiLocalState(block: Pick<UiBlock, 'defaults' | 'queries'>): (name: string) => boolean;

package/dist/actions.js

@@ -0,0 +1,34 @@
+import { UiFailure } from './budget.js';
+import { isUiComponent, UI_CATALOG } from './catalog.js';
+/* The prop of a component that holds a state action, kept unevaluated, instead of a value. */
+export function uiActionProp(type) {
+    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, local) {
+    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) {
+    return (name) => Object.hasOwn(block.defaults, name) && !Object.hasOwn(block.queries, name);
+}

package/dist/catalog.d.ts

@@ -31,7 +31,7 @@ export declare const UI_GROUPS: {
     };
     readonly inputs: {
         readonly description: 'Change local block state.';
-        readonly rules: 'Bind value={$name}. State stays local until a Choice sends visible context.';
+        readonly 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.';
     };
     readonly choices: {
         readonly description: 'Ask the person to pick a next step.';
@@ -330,6 +330,14 @@ export declare const UI_CATALOG: {
         }, z.core.$strict>;
         readonly parent: 'Segmented';
     };
+    readonly Button: {
+        readonly group: 'inputs';
+        readonly description: 'Run one local state action when pressed; children are the label.';
+        readonly schema: z.ZodObject<{
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly action: 'action';
+    };
     readonly Show: {
         readonly group: 'inputs';
         readonly description: 'Show children when the condition is true.';

package/dist/catalog.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { uiPropList } from './prop-list.js';
 export const UI_CATALOG_VERSION = 1;
 export const UiToneSchema = z.enum(['neutral', 'info', 'success', 'warning', 'danger']);
 const text = z.string().max(16384);
@@ -17,7 +18,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.'
@@ -115,6 +119,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',
@@ -134,12 +144,6 @@ export function isUiComponent(name) {
 }
 export function uiCatalogText() {
     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/dist/compiler.d.ts

@@ -2,13 +2,19 @@ import { type UiLimits } from './budget.ts';
 import { type UiExpression, type UiValue } from './expression.ts';
 import { type UiDiagnostic } from './syntax.ts';
 import { type z } from 'zod';
-export declare const UI_FENCE_LANGUAGE = "ruimte-ui";
+export declare const UI_FENCE_LANGUAGE = "ui";
 export declare const UI_REPLY_LIMITS: {
     readonly blocks: 16;
     readonly characters: 262144;
     readonly nodes: 2048;
     readonly milliseconds: 60;
 };
+export declare const UI_HOST_LIMITS: {
+    readonly queries: 8;
+    readonly links: 64;
+    readonly refreshMilliseconds: 10000;
+};
+export declare function uiMayReferenceHost(text: string): boolean;
 export interface UiNode {
     id: string;
     type: string;
@@ -46,6 +52,7 @@ export interface UiCompileOptions {
     limits?: Partial<UiLimits>;
     latestAttachment?: string;
     querySchemas?: Readonly<Record<string, z.ZodType>>;
+    fenceLanguage?: string;
     now?: () => number;
 }
 export declare function compileUiBlock(source: string, options: UiCompileOptions): UiBlock;
@@ -58,4 +65,5 @@ export declare class UiCompiler {
     compile(text: string, update?: UiCompileUpdate): UiBlock[];
     clear(): void;
 }
+export declare function uiHasFence(text: string, fenceLanguage?: string): boolean;
 export declare function compileUi(text: string, options: UiCompileOptions): UiBlock[];

package/dist/compiler.js

@@ -1,10 +1,69 @@
-import { safeKey, UiBudget, UiFailure } from './budget.js';
+import { safeKey, UI_LIMITS, UiBudget, UiFailure } from './budget.js';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.js';
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
+import { uiNodeFallback, uiPlainText } from './fallback.js';
 import { evaluateUiExpression } from './expression.js';
 import { parseUiSyntax, uiDiagnostic } from './syntax.js';
 import {} 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 };
+// 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 };
+/* 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) {
+    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);
+}
+/* A spent budget ends the whole block; every other failure only marks the node or declaration it came from. */
+function rethrowBudget(error) {
+    if (error instanceof UiFailure && error.code === 'budget_exceeded') {
+        throw error;
+    }
+}
+function isQuery(expression) {
+    return expression.kind === 'call' && expression.name === 'Query';
+}
+/* Throws when a query argument reads anything but declared local state. */
+function checkQueryReferences(part, defaults) {
+    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, block, budget, querySchemas) {
+    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) {
     switch (expression.kind) {
         case 'literal':
@@ -19,9 +78,6 @@ function isConstant(expression) {
             return false;
     }
 }
-function plain(value) {
-    return value === null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
-}
 export function compileUiBlock(source, options) {
     const budget = new UiBudget(options.limits, options.now);
     const block = {
@@ -41,8 +97,16 @@ export function compileUiBlock(source, options) {
             block.diagnostics.push(uiDiagnostic(error, start, end, nodeId));
         }
     };
-    const compile = (syntax, parent) => {
-        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) => {
+        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, depth, parent) => {
+        budget.depth(depth);
         const node = {
             id: syntax.id,
             type: syntax.type,
@@ -61,12 +125,10 @@ export function compileUiBlock(source, options) {
                 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 {
@@ -91,8 +153,13 @@ export function compileUiBlock(source, options) {
                     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;
@@ -102,11 +169,7 @@ export function compileUiBlock(source, options) {
                 }
                 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;
                     }
                 }
@@ -115,17 +178,21 @@ export function compileUiBlock(source, options) {
                 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 = { ...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;
                 }
             }
@@ -138,39 +205,13 @@ export function compileUiBlock(source, options) {
             }
         }
         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));
         }
@@ -179,41 +220,12 @@ export function compileUiBlock(source, options) {
     try {
         const syntax = parseUiSyntax(source, options.id, options.final, budget);
         block.diagnostics = syntax.diagnostics;
-        for (const [name, expression] of Object.entries(syntax.declarations).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) => {
-                        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)) {
@@ -223,13 +235,11 @@ export function compileUiBlock(source, options) {
                 }
             }
             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('')
@@ -262,6 +272,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) => items.reduce((count, node) => count + 1 + nodeCount(node.children), 0);
         const rejected = (start, codeStart, codeEnd, end, complete) => ({
@@ -285,7 +297,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)
                     ]
                 };
@@ -336,7 +348,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()) {
@@ -357,6 +369,11 @@ export class UiCompiler {
         this.cache.clear();
     }
 }
+/* A cheap test for whether `text` opens a UI fence at all, before a compiler is worth creating. */
+export function uiHasFence(text, fenceLanguage = UI_FENCE_LANGUAGE) {
+    const language = fenceLanguage.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^ {0,3}(?:\`{3,}|~{3,})[ \\t]*${language}[ \\t]*\\r?$`, 'm').test(text);
+}
 export function compileUi(text, options) {
     return new UiCompiler(options).compile(text, options);
 }

package/dist/expression.d.ts

@@ -36,5 +36,6 @@ export type UiExpression = {
     args: UiExpression[];
 };
 export declare function parseUiExpression(source: string, budget?: UiBudget): UiExpression;
+export declare function sameUiValue(first: UiValue, second: UiValue): boolean;
 export declare function copyUiValue(value: unknown, budget?: UiBudget, depth?: number): UiValue;
 export declare function evaluateUiExpression(expression: UiExpression, variables?: Readonly<Record<string, UiValue>>, budget?: UiBudget): UiValue;

package/dist/expression.js

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

package/dist/fallback.d.ts

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

package/dist/fallback.js

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

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { UI_CATALOG, UI_CATALOG_VERSION, UI_GROUPS, UiToneSchema, isUiComponent, uiCatalogText, type UiComponentName, type UiProps, type UiTone } from './catalog.ts';
 export { UI_LIMITS, UiBudget, UiFailure, safeKey, type UiLimits } from './budget.ts';
-export { copyUiValue, evaluateUiExpression, parseUiExpression, type UiExpression, type UiValue } from './expression.ts';
+export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
 export { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntax, type UiSyntaxNode } from './syntax.ts';
-export { UI_FENCE_LANGUAGE, UI_REPLY_LIMITS, UiCompiler, compileUi, compileUiBlock, type UiCompilerOptions, type UiCompileUpdate, type UiBlock, type UiCompileOptions, type UiNode, type UiQuery } from './compiler.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';