@adecore/intelligent-ui 0.22.0 → 0.22.1

package/dist/catalog.d.ts

@@ -34,8 +34,8 @@ export declare const UI_GROUPS: {
         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.';
-        readonly rules: 'Give a short label and precise visible context. A Choice sends once after streaming ends.';
+        readonly description: 'Offer optional next steps after a finished answer.';
+        readonly rules: 'Never ask for information or a decision needed before acting: use your own question tool if you have one, otherwise ask in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.';
     };
 };
 export declare const UI_CATALOG: {
@@ -355,7 +355,7 @@ export declare const UI_CATALOG: {
     };
     readonly Choices: {
         readonly group: 'choices';
-        readonly description: 'Visible next steps.';
+        readonly description: 'Optional next steps after a finished answer.';
         readonly schema: z.ZodObject<{}, z.core.$strict>;
         readonly children: readonly ['Choice'];
     };

package/dist/catalog.js

@@ -23,8 +23,8 @@ export const UI_GROUPS = {
         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.'
+        description: 'Offer optional next steps after a finished answer.',
+        rules: 'Never ask for information or a decision needed before acting: use your own question tool if you have one, otherwise ask in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.'
     }
 };
 export const UI_CATALOG = {
@@ -131,7 +131,7 @@ export const UI_CATALOG = {
         description: 'Repeat children over local data.',
         schema: z.strictObject({ items: z.array(z.unknown()).max(1000), as: name.regex(/^[A-Za-z_][A-Za-z_\d]*$/) })
     },
-    Choices: { group: 'choices', description: 'Visible next steps.', schema: empty, children: ['Choice'] },
+    Choices: { group: 'choices', description: 'Optional next steps after a finished answer.', schema: empty, children: ['Choice'] },
     Choice: {
         group: 'choices',
         description: 'Send its label and visible context once.',

package/dist/compiler.js

@@ -78,6 +78,23 @@ function isConstant(expression) {
             return false;
     }
 }
+const CHART_SERIES = 6;
+/* The keys besides `label` that hold a finite number in some row of a chart's data. */
+function chartSeries(data) {
+    const keys = new Set();
+    for (const row of Array.isArray(data) ? data : []) {
+        for (const [key, value] of Object.entries((row ?? {}))) {
+            if (key !== 'label' && typeof value === 'number' && Number.isFinite(value)) {
+                keys.add(key);
+            }
+        }
+    }
+    return keys.size;
+}
+/* Whether a child can give a Choice words: a component, an expression, or text that is more than whitespace. */
+function isLabelSource(child) {
+    return child.type !== '$text' || child.expression !== undefined || (child.text ?? '').trim() !== '';
+}
 export function compileUiBlock(source, options) {
     const budget = new UiBudget(options.limits, options.now);
     const block = {
@@ -203,15 +220,35 @@ export function compileUiBlock(source, options) {
                     throw new UiFailure('invalid_props', parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '));
                 }
             }
+            // The catalog promises six series, one per chart color; more still reach the values a person can open.
+            if (!unresolved && syntax.complete && syntax.type === 'Chart' && chartSeries(evaluated.data) > CHART_SERIES) {
+                diagnose(new UiFailure('too_many_series', `Chart draws up to ${CHART_SERIES} numeric series; the rest are only in its values.`), syntax.start, syntax.end, syntax.id);
+            }
+            // A Choice sends its label, so one without a label can never send; whether it closed is only known once final.
+            if (syntax.type === 'Choice' && syntax.complete && !syntax.children.some(isLabelSource)) {
+                throw new UiFailure('invalid_props', 'A choice needs a visible label.');
+            }
         }
         catch (error) {
             rethrowBudget(error);
             node.error = error instanceof UiFailure ? error.code : 'invalid_props';
             diagnose(error, syntax.start, syntax.end, syntax.id);
         }
+        // The parser already diagnosed both, so they only decide how the node draws.
+        if (node.error === undefined && syntax.invalid) {
+            node.error = 'invalid_syntax';
+        }
+        if (node.error === undefined && syntax.type === 'Choice' && options.final && !syntax.complete) {
+            node.error = 'unclosed_tag';
+        }
         const effectiveParent = syntax.type === 'Show' || syntax.type === 'Each' ? parent : syntax.type;
         node.children = syntax.children.map((child) => compile(child, depth + 1, effectiveParent));
-        node.fallback = uiNodeFallback(syntax.type, fallbackProps, node.children.map((child) => child.fallback).join(''));
+        const childText = node.children.map((child) => child.fallback).join('');
+        node.fallback = uiNodeFallback(syntax.type, fallbackProps, childText);
+        // A part drawn as its text keeps the words written inside it, also where its kind reads only props.
+        if (node.error !== undefined && childText.trim() !== '' && !node.fallback.includes(childText.trim())) {
+            node.fallback += childText;
+        }
         if (!node.fallback.trim()) {
             node.fallback = source.slice(syntax.start, Math.min(syntax.end, syntax.start + 1024));
         }

package/dist/fallback.js

@@ -1,24 +1,48 @@
 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. */
+function given(value) {
+    return value !== undefined && value !== null && value !== '';
+}
+/*
+ * The readable text a node leaves behind where it cannot be drawn, from its props and its children's text.
+ * Another agent reads a reply through it too, so every prop that says something (a state, a detail, a
+ * badge, a unit) is in it; only props that style a node or drive local state are left out.
+ */
 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 'Summary':
+            return `${children.trimEnd()}${given(props.badge) ? ` (${uiPlainText(props.badge)})` : ''}\n`;
+        case 'Step':
+            return `${children.trimEnd()}${given(props.state) ? ` (${uiPlainText(props.state)})` : ''}${given(props.detail) ? `: ${uiPlainText(props.detail)}` : ''}\n`;
+        case 'Progress':
+            return given(props.value) ? `${children.trimEnd()}: ${uiPlainText(props.value)} of ${uiPlainText(props.max ?? 100)}\n` : `${children.trimEnd()}\n`;
+        case 'Stat': {
+            const unit = given(props.unit) ? ` ${uiPlainText(props.unit)}` : '';
+            const previous = given(props.previous) ? ` (was ${uiPlainText(props.previous)}${unit})` : '';
+            return `${uiPlainText(label)}: ${uiPlainText(props.value)}${unit}${previous}\n`;
+        }
         case 'Source':
             return `${uiPlainText(label)}: ${uiPlainText(props.url)}\n`;
-        case 'Table':
-            return `${uiPlainText(props.rows ?? [])}\n`;
+        case 'Column':
+            return `${uiPlainText(props.title ?? props.key)}${given(props.unit) ? ` (${uiPlainText(props.unit)})` : ''}\n`;
+        case 'Table': {
+            const columns = children
+                .split('\n')
+                .map((column) => column.trim())
+                .filter(Boolean);
+            return `${columns.length > 0 ? `Columns: ${columns.join(', ')}\n` : ''}${uiPlainText(props.rows ?? [])}\n`;
+        }
         case 'Chart':
-            return `${uiPlainText(props.data ?? [])}\n`;
+            return `${uiPlainText(props.data ?? [])}${given(props.unit) ? ` (${uiPlainText(props.unit)})` : ''}\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 path = given(props.path) && given(props.line) ? `${uiPlainText(props.path)}:${uiPlainText(props.line)}` : props.path;
+    const target = 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

@@ -3,7 +3,7 @@ export { UI_LIMITS, UiBudget, UiFailure, safeKey, type UiLimits } from './budget
 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, 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 { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice, uiChoiceLabel, 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, type UiTextOptions } from './text.ts';

package/dist/index.js

@@ -3,7 +3,7 @@ export { UI_LIMITS, UiBudget, UiFailure, safeKey } from './budget.js';
 export { copyUiValue, evaluateUiExpression, parseUiExpression, sameUiValue } from './expression.js';
 export { parseUiSyntax, uiDiagnostic } from './syntax.js';
 export { UI_FENCE_LANGUAGE, UI_HOST_LIMITS, UI_REPLY_LIMITS, UiCompiler, compileUi, compileUiBlock, uiHasFence, uiMayReferenceHost } from './compiler.js';
-export { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice } from './runtime.js';
+export { evaluateUiBlock, UiState, uiInputValues, resolveUiChoice, uiChoiceLabel } from './runtime.js';
 export { uiValidatedState, uiQueryArguments, uiQueryFallback } from './query.js';
 export { UiNodeSchema, UiDiagnosticSchema, UiBlockSchema, UiBlocksSchema } from './protocol.js';
 export { uiCompactCatalog, uiSessionNote, uiReferenceText, uiFallbackText } from './text.js';

package/dist/runtime.d.ts

@@ -48,4 +48,5 @@ export interface UiChoiceSelection {
     values: Record<string, UiValue>;
 }
 export declare function uiInputValues(block: UiBlock, state: UiState): Record<string, UiValue>;
+export declare function uiChoiceLabel(choice: UiViewNode): string | null;
 export declare function resolveUiChoice(block: UiBlock, choiceId: string, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>): UiChoiceSelection;

package/dist/runtime.js

@@ -262,6 +262,22 @@ export function uiInputValues(block, state) {
     return values;
 }
 /* The host supplies its stored block; client data can change only declared inputs and Button targets. */
+function hasError(nodes) {
+    return nodes.some((node) => node.error !== undefined || hasError(node.children));
+}
+function labelText(nodes) {
+    return nodes.map((node) => (node.type === '$text' ? String(node.props.text ?? '') : labelText(node.children))).join('');
+}
+/*
+ * The label an evaluated Choice sends, on one line, or null when it can never send: it failed, never
+ * closed, part of its label could not be read, or the label is empty. A page draws no open row for null.
+ */
+export function uiChoiceLabel(choice) {
+    if (choice.error !== undefined || !choice.complete || hasError(choice.children)) {
+        return null;
+    }
+    return labelText(choice.children).replace(/\s+/g, ' ').trim() || null;
+}
 export function resolveUiChoice(block, choiceId, input = {}, queries = {}, limits = {}) {
     if (!block.complete || block.catalogVersion !== UI_CATALOG_VERSION) {
         throw new UiFailure('refused_choice', 'Only a completed supported block can send a choice.');
@@ -311,14 +327,9 @@ export function resolveUiChoice(block, choiceId, input = {}, queries = {}, limit
     if (!choice) {
         throw new UiFailure('refused_choice', 'This choice is not available in the current block.');
     }
-    const text = (nodes) => nodes.map((node) => (node.type === '$text' ? String(node.props.text ?? '') : text(node.children))).join('');
-    const hasError = (nodes) => nodes.some((node) => node.error !== undefined || hasError(node.children));
-    if (hasError(choice.children)) {
-        throw new UiFailure('refused_choice', 'The choice label could not be fully read.');
-    }
-    const label = text(choice.children).replace(/\s+/g, ' ').trim();
-    if (!label) {
-        throw new UiFailure('refused_choice', 'A choice needs a visible label.');
+    const label = uiChoiceLabel(choice);
+    if (label === null) {
+        throw new UiFailure('refused_choice', hasError(choice.children) ? 'The choice label could not be fully read.' : 'A choice needs a visible label.');
     }
     return {
         label,

package/dist/syntax.d.ts

@@ -15,6 +15,7 @@ export interface UiSyntaxNode {
     text?: string;
     expression?: UiExpression;
     complete: boolean;
+    invalid?: boolean;
     start: number;
     end: number;
 }

package/dist/syntax.js

@@ -209,82 +209,146 @@ class UiParser {
                     node.end = this.position;
                     return;
                 }
+                // A tag that lost a prop and has no closing tag anywhere after it was meant to close itself.
+                if (node.invalid && this.final && !this.closesLater(node.type)) {
+                    node.complete = true;
+                    node.end = this.position;
+                    return;
+                }
                 this.stack.push(node);
                 return;
             }
-            const prop = /^[A-Za-z_][A-Za-z_\d]*/.exec(this.source.slice(this.position));
-            if (!prop) {
-                if (this.position === this.source.length && !this.final) {
+            const propStart = this.position;
+            try {
+                if (!this.prop(node)) {
                     return;
                 }
-                throw new UiFailure('invalid_prop', 'Expected a named prop.');
             }
-            const name = safeKey(prop[0]);
-            this.position += name.length;
-            this.whitespace();
-            if (!this.finish('=')) {
-                return;
+            catch (error) {
+                if (error instanceof UiFailure && error.code === 'budget_exceeded') {
+                    throw error;
+                }
+                this.diagnose(error, propStart, node.id);
+                node.invalid = true;
+                this.skipToken();
             }
-            this.whitespace();
-            let value;
-            if (this.source[this.position] === '{') {
-                const body = this.balanced();
-                if (!body.complete) {
-                    return;
+        }
+        node.end = this.position;
+        if (this.final) {
+            this.diagnose(new UiFailure('unclosed_tag', `The ${node.type} tag is incomplete.`), start, node.id);
+        }
+    }
+    /* Reads one prop into the node; false while a streaming prop waits for more text. */
+    prop(node) {
+        // At the end of the text the tag waits while it streams, and is reported incomplete once final.
+        if (this.position === this.source.length) {
+            return false;
+        }
+        const prop = /^[A-Za-z_][A-Za-z_\d]*/.exec(this.source.slice(this.position));
+        if (!prop) {
+            throw new UiFailure('invalid_prop', 'Expected a named prop.');
+        }
+        const name = safeKey(prop[0]);
+        this.position += name.length;
+        this.whitespace();
+        if (this.position === this.source.length && !this.final) {
+            return false;
+        }
+        if (this.source[this.position] !== '=') {
+            // A bare name is true, as in JSX.
+            if (Object.hasOwn(node.props, name)) {
+                throw new UiFailure('duplicate_prop', `Duplicate prop ${name}.`);
+            }
+            node.props[name] = parseUiExpression('true', this.budget);
+            return true;
+        }
+        this.position += 1;
+        this.whitespace();
+        let value;
+        if (this.source[this.position] === '{') {
+            const body = this.balanced();
+            if (!body.complete) {
+                return false;
+            }
+            value = body.value;
+        }
+        else {
+            const quote = this.source[this.position];
+            if (quote !== '"' && quote !== "'") {
+                if (!this.final && this.position === this.source.length) {
+                    return false;
                 }
-                value = body.value;
+                throw new UiFailure('invalid_prop', 'Use a quoted string or a braced expression.');
             }
-            else {
-                const quote = this.source[this.position];
-                if (quote !== '"' && quote !== "'") {
-                    if (!this.final && this.position === this.source.length) {
-                        return;
-                    }
-                    throw new UiFailure('invalid_prop', 'Use a quoted string or a braced expression.');
+            const valueStart = this.position++;
+            let escaped = false;
+            let closed = false;
+            while (this.position < this.source.length) {
+                this.budget.step();
+                const character = this.source[this.position++];
+                if (escaped) {
+                    escaped = false;
                 }
-                const valueStart = this.position++;
-                let escaped = false;
-                let closed = false;
-                while (this.position < this.source.length) {
-                    this.budget.step();
-                    const character = this.source[this.position++];
-                    if (escaped) {
-                        escaped = false;
-                    }
-                    else if (character === '\\') {
-                        escaped = true;
-                    }
-                    else if (character === quote) {
-                        closed = true;
-                        break;
-                    }
+                else if (character === '\\') {
+                    escaped = true;
                 }
-                if (!closed && !this.final) {
-                    value = this.source.slice(valueStart, this.position);
-                    if (escaped) {
-                        value = value.slice(0, -1);
-                    }
-                    try {
-                        node.props[name] = parseUiExpression(`${value}${quote}`, this.budget);
-                    }
-                    catch (error) {
-                        if (error instanceof UiFailure && error.code === 'budget_exceeded') {
-                            throw error;
-                        }
-                    }
-                    node.end = this.position;
-                    return;
+                else if (character === quote) {
+                    closed = true;
+                    break;
                 }
-                value = this.source.slice(valueStart, this.position);
             }
-            if (Object.hasOwn(node.props, name)) {
-                throw new UiFailure('duplicate_prop', `Duplicate prop ${name}.`);
+            if (!closed && !this.final) {
+                value = this.source.slice(valueStart, this.position);
+                if (escaped) {
+                    value = value.slice(0, -1);
+                }
+                try {
+                    node.props[name] = parseUiExpression(`${value}${quote}`, this.budget);
+                }
+                catch (error) {
+                    if (error instanceof UiFailure && error.code === 'budget_exceeded') {
+                        throw error;
+                    }
+                }
+                node.end = this.position;
+                return false;
             }
-            node.props[name] = parseUiExpression(value, this.budget);
+            value = this.source.slice(valueStart, this.position);
         }
-        node.end = this.position;
-        if (this.final) {
-            this.diagnose(new UiFailure('unclosed_tag', `The ${node.type} tag is incomplete.`), start, node.id);
+        if (Object.hasOwn(node.props, name)) {
+            throw new UiFailure('duplicate_prop', `Duplicate prop ${name}.`);
+        }
+        node.props[name] = parseUiExpression(value, this.budget);
+        return true;
+    }
+    /* Skips a prop that could not be read, up to the next space or the end of its tag, so only that prop is lost. */
+    skipToken() {
+        let quote = '';
+        let depth = 0;
+        while (this.position < this.source.length) {
+            this.budget.step();
+            const character = this.source[this.position];
+            if (quote) {
+                if (character === '\\') {
+                    this.position += 1;
+                }
+                else if (character === quote) {
+                    quote = '';
+                }
+            }
+            else if (character === '"' || character === "'") {
+                quote = character;
+            }
+            else if (character === '{') {
+                depth += 1;
+            }
+            else if (character === '}') {
+                depth = Math.max(0, depth - 1);
+            }
+            else if (depth === 0 && (/\s/.test(character) || character === '>' || this.source.startsWith('/>', this.position))) {
+                break;
+            }
+            this.position += 1;
         }
     }
     balanced() {
@@ -322,6 +386,12 @@ class UiParser {
         }
         return { value: this.source.slice(start), complete: false };
     }
+    /* Whether a closing tag for this type follows, written the way `tag` accepts one: whitespace may stand before its `>`. */
+    closesLater(type) {
+        const closing = new RegExp(`</${type}\\s*>`, 'g');
+        closing.lastIndex = this.position;
+        return closing.test(this.source);
+    }
     whitespace() {
         while (this.position < this.source.length && /\s/.test(this.source[this.position])) {
             this.position += 1;

package/dist/text.js

@@ -24,7 +24,7 @@ function uiExample(language) {
     ].join('\n');
 }
 export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE } = {}) {
-    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
+    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choices only offer optional next steps after a finished answer; ask for information or a decision needed before acting with your own question tool if you have one, otherwise in prose. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
 }
 export function uiReferenceText({ fenceLanguage = UI_FENCE_LANGUAGE } = {}) {
     const groups = Object.entries(UI_GROUPS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/intelligent-ui",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "A streaming UI catalog, compiler and bounded expression interpreter without a framework or DOM.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",

package/src/catalog.ts

@@ -27,8 +27,8 @@ export const UI_GROUPS = {
         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.'
+        description: 'Offer optional next steps after a finished answer.',
+        rules: 'Never ask for information or a decision needed before acting: use your own question tool if you have one, otherwise ask in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.'
     }
 } as const;
 
@@ -136,7 +136,7 @@ export const UI_CATALOG = {
         description: 'Repeat children over local data.',
         schema: z.strictObject({ items: z.array(z.unknown()).max(1000), as: name.regex(/^[A-Za-z_][A-Za-z_\d]*$/) })
     },
-    Choices: { group: 'choices', description: 'Visible next steps.', schema: empty, children: ['Choice'] },
+    Choices: { group: 'choices', description: 'Optional next steps after a finished answer.', schema: empty, children: ['Choice'] },
     Choice: {
         group: 'choices',
         description: 'Send its label and visible context once.',

package/src/compiler.ts

@@ -138,6 +138,26 @@ function isConstant(expression: UiExpression): boolean {
     }
 }
 
+const CHART_SERIES = 6;
+
+/* The keys besides `label` that hold a finite number in some row of a chart's data. */
+function chartSeries(data: unknown): number {
+    const keys = new Set<string>();
+    for (const row of Array.isArray(data) ? data : []) {
+        for (const [key, value] of Object.entries((row ?? {}) as Record<string, unknown>)) {
+            if (key !== 'label' && typeof value === 'number' && Number.isFinite(value)) {
+                keys.add(key);
+            }
+        }
+    }
+    return keys.size;
+}
+
+/* Whether a child can give a Choice words: a component, an expression, or text that is more than whitespace. */
+function isLabelSource(child: UiSyntaxNode): boolean {
+    return child.type !== '$text' || child.expression !== undefined || (child.text ?? '').trim() !== '';
+}
+
 export function compileUiBlock(source: string, options: UiCompileOptions): UiBlock {
     const budget = new UiBudget(options.limits, options.now);
     const block: UiBlock = {
@@ -261,14 +281,39 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     throw new UiFailure('invalid_props', parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '));
                 }
             }
+            // The catalog promises six series, one per chart color; more still reach the values a person can open.
+            if (!unresolved && syntax.complete && syntax.type === 'Chart' && chartSeries(evaluated.data) > CHART_SERIES) {
+                diagnose(
+                    new UiFailure('too_many_series', `Chart draws up to ${CHART_SERIES} numeric series; the rest are only in its values.`),
+                    syntax.start,
+                    syntax.end,
+                    syntax.id
+                );
+            }
+            // A Choice sends its label, so one without a label can never send; whether it closed is only known once final.
+            if (syntax.type === 'Choice' && syntax.complete && !syntax.children.some(isLabelSource)) {
+                throw new UiFailure('invalid_props', 'A choice needs a visible label.');
+            }
         } catch (error) {
             rethrowBudget(error);
             node.error = error instanceof UiFailure ? error.code : 'invalid_props';
             diagnose(error, syntax.start, syntax.end, syntax.id);
         }
+        // The parser already diagnosed both, so they only decide how the node draws.
+        if (node.error === undefined && syntax.invalid) {
+            node.error = 'invalid_syntax';
+        }
+        if (node.error === undefined && syntax.type === 'Choice' && options.final && !syntax.complete) {
+            node.error = 'unclosed_tag';
+        }
         const effectiveParent = syntax.type === 'Show' || syntax.type === 'Each' ? parent : syntax.type;
         node.children = syntax.children.map((child) => compile(child, depth + 1, effectiveParent));
-        node.fallback = uiNodeFallback(syntax.type, fallbackProps, node.children.map((child) => child.fallback).join(''));
+        const childText = node.children.map((child) => child.fallback).join('');
+        node.fallback = uiNodeFallback(syntax.type, fallbackProps, childText);
+        // A part drawn as its text keeps the words written inside it, also where its kind reads only props.
+        if (node.error !== undefined && childText.trim() !== '' && !node.fallback.includes(childText.trim())) {
+            node.fallback += childText;
+        }
         if (!node.fallback.trim()) {
             node.fallback = source.slice(syntax.start, Math.min(syntax.end, syntax.start + 1024));
         }

package/src/fallback.ts

@@ -2,24 +2,49 @@ 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. */
+function given(value: unknown): boolean {
+    return value !== undefined && value !== null && value !== '';
+}
+
+/*
+ * The readable text a node leaves behind where it cannot be drawn, from its props and its children's text.
+ * Another agent reads a reply through it too, so every prop that says something (a state, a detail, a
+ * badge, a unit) is in it; only props that style a node or drive local state are left out.
+ */
 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 'Summary':
+            return `${children.trimEnd()}${given(props.badge) ? ` (${uiPlainText(props.badge)})` : ''}\n`;
+        case 'Step':
+            return `${children.trimEnd()}${given(props.state) ? ` (${uiPlainText(props.state)})` : ''}${given(props.detail) ? `: ${uiPlainText(props.detail)}` : ''}\n`;
+        case 'Progress':
+            return given(props.value) ? `${children.trimEnd()}: ${uiPlainText(props.value)} of ${uiPlainText(props.max ?? 100)}\n` : `${children.trimEnd()}\n`;
+        case 'Stat': {
+            const unit = given(props.unit) ? ` ${uiPlainText(props.unit)}` : '';
+            const previous = given(props.previous) ? ` (was ${uiPlainText(props.previous)}${unit})` : '';
+            return `${uiPlainText(label)}: ${uiPlainText(props.value)}${unit}${previous}\n`;
+        }
         case 'Source':
             return `${uiPlainText(label)}: ${uiPlainText(props.url)}\n`;
-        case 'Table':
-            return `${uiPlainText(props.rows ?? [])}\n`;
+        case 'Column':
+            return `${uiPlainText(props.title ?? props.key)}${given(props.unit) ? ` (${uiPlainText(props.unit)})` : ''}\n`;
+        case 'Table': {
+            const columns = children
+                .split('\n')
+                .map((column) => column.trim())
+                .filter(Boolean);
+            return `${columns.length > 0 ? `Columns: ${columns.join(', ')}\n` : ''}${uiPlainText(props.rows ?? [])}\n`;
+        }
         case 'Chart':
-            return `${uiPlainText(props.data ?? [])}\n`;
+            return `${uiPlainText(props.data ?? [])}${given(props.unit) ? ` (${uiPlainText(props.unit)})` : ''}\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 path = given(props.path) && given(props.line) ? `${uiPlainText(props.path)}:${uiPlainText(props.line)}` : props.path;
+    const target = 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

@@ -33,6 +33,7 @@ export {
     UiState,
     uiInputValues,
     resolveUiChoice,
+    uiChoiceLabel,
     type UiChoiceSelection,
     type UiBinding,
     type UiEvaluation,

package/src/runtime.ts

@@ -299,6 +299,25 @@ export function uiInputValues(block: UiBlock, state: UiState): Record<string, Ui
 }
 
 /* The host supplies its stored block; client data can change only declared inputs and Button targets. */
+function hasError(nodes: readonly UiViewNode[]): boolean {
+    return nodes.some((node) => node.error !== undefined || hasError(node.children));
+}
+
+function labelText(nodes: readonly UiViewNode[]): string {
+    return nodes.map((node) => (node.type === '$text' ? String(node.props.text ?? '') : labelText(node.children))).join('');
+}
+
+/*
+ * The label an evaluated Choice sends, on one line, or null when it can never send: it failed, never
+ * closed, part of its label could not be read, or the label is empty. A page draws no open row for null.
+ */
+export function uiChoiceLabel(choice: UiViewNode): string | null {
+    if (choice.error !== undefined || !choice.complete || hasError(choice.children)) {
+        return null;
+    }
+    return labelText(choice.children).replace(/\s+/g, ' ').trim() || null;
+}
+
 export function resolveUiChoice(
     block: UiBlock,
     choiceId: string,
@@ -354,15 +373,9 @@ export function resolveUiChoice(
     if (!choice) {
         throw new UiFailure('refused_choice', 'This choice is not available in the current block.');
     }
-    const text = (nodes: readonly UiViewNode[]): string =>
-        nodes.map((node) => (node.type === '$text' ? String(node.props.text ?? '') : text(node.children))).join('');
-    const hasError = (nodes: readonly UiViewNode[]): boolean => nodes.some((node) => node.error !== undefined || hasError(node.children));
-    if (hasError(choice.children)) {
-        throw new UiFailure('refused_choice', 'The choice label could not be fully read.');
-    }
-    const label = text(choice.children).replace(/\s+/g, ' ').trim();
-    if (!label) {
-        throw new UiFailure('refused_choice', 'A choice needs a visible label.');
+    const label = uiChoiceLabel(choice);
+    if (label === null) {
+        throw new UiFailure('refused_choice', hasError(choice.children) ? 'The choice label could not be fully read.' : 'A choice needs a visible label.');
     }
     return {
         label,

package/src/syntax.ts

@@ -17,6 +17,8 @@ export interface UiSyntaxNode {
     text?: string;
     expression?: UiExpression;
     complete: boolean;
+    /* Set when a prop could not be read, so the node draws as its text even though its tag closed. */
+    invalid?: boolean;
     start: number;
     end: number;
 }
@@ -230,78 +232,138 @@ class UiParser {
                     node.end = this.position;
                     return;
                 }
+                // A tag that lost a prop and has no closing tag anywhere after it was meant to close itself.
+                if (node.invalid && this.final && !this.closesLater(node.type)) {
+                    node.complete = true;
+                    node.end = this.position;
+                    return;
+                }
                 this.stack.push(node);
                 return;
             }
-            const prop = /^[A-Za-z_][A-Za-z_\d]*/.exec(this.source.slice(this.position));
-            if (!prop) {
-                if (this.position === this.source.length && !this.final) {
+            const propStart = this.position;
+            try {
+                if (!this.prop(node)) {
                     return;
                 }
-                throw new UiFailure('invalid_prop', 'Expected a named prop.');
+            } catch (error) {
+                if (error instanceof UiFailure && error.code === 'budget_exceeded') {
+                    throw error;
+                }
+                this.diagnose(error, propStart, node.id);
+                node.invalid = true;
+                this.skipToken();
             }
-            const name = safeKey(prop[0]);
-            this.position += name.length;
-            this.whitespace();
-            if (!this.finish('=')) {
-                return;
+        }
+        node.end = this.position;
+        if (this.final) {
+            this.diagnose(new UiFailure('unclosed_tag', `The ${node.type} tag is incomplete.`), start, node.id);
+        }
+    }
+
+    /* Reads one prop into the node; false while a streaming prop waits for more text. */
+    private prop(node: UiSyntaxNode): boolean {
+        // At the end of the text the tag waits while it streams, and is reported incomplete once final.
+        if (this.position === this.source.length) {
+            return false;
+        }
+        const prop = /^[A-Za-z_][A-Za-z_\d]*/.exec(this.source.slice(this.position));
+        if (!prop) {
+            throw new UiFailure('invalid_prop', 'Expected a named prop.');
+        }
+        const name = safeKey(prop[0]);
+        this.position += name.length;
+        this.whitespace();
+        if (this.position === this.source.length && !this.final) {
+            return false;
+        }
+        if (this.source[this.position] !== '=') {
+            // A bare name is true, as in JSX.
+            if (Object.hasOwn(node.props, name)) {
+                throw new UiFailure('duplicate_prop', `Duplicate prop ${name}.`);
             }
-            this.whitespace();
-            let value: string;
-            if (this.source[this.position] === '{') {
-                const body = this.balanced();
-                if (!body.complete) {
-                    return;
+            node.props[name] = parseUiExpression('true', this.budget);
+            return true;
+        }
+        this.position += 1;
+        this.whitespace();
+        let value: string;
+        if (this.source[this.position] === '{') {
+            const body = this.balanced();
+            if (!body.complete) {
+                return false;
+            }
+            value = body.value;
+        } else {
+            const quote = this.source[this.position];
+            if (quote !== '"' && quote !== "'") {
+                if (!this.final && this.position === this.source.length) {
+                    return false;
                 }
-                value = body.value;
-            } else {
-                const quote = this.source[this.position];
-                if (quote !== '"' && quote !== "'") {
-                    if (!this.final && this.position === this.source.length) {
-                        return;
-                    }
-                    throw new UiFailure('invalid_prop', 'Use a quoted string or a braced expression.');
+                throw new UiFailure('invalid_prop', 'Use a quoted string or a braced expression.');
+            }
+            const valueStart = this.position++;
+            let escaped = false;
+            let closed = false;
+            while (this.position < this.source.length) {
+                this.budget.step();
+                const character = this.source[this.position++];
+                if (escaped) {
+                    escaped = false;
+                } else if (character === '\\') {
+                    escaped = true;
+                } else if (character === quote) {
+                    closed = true;
+                    break;
                 }
-                const valueStart = this.position++;
-                let escaped = false;
-                let closed = false;
-                while (this.position < this.source.length) {
-                    this.budget.step();
-                    const character = this.source[this.position++];
-                    if (escaped) {
-                        escaped = false;
-                    } else if (character === '\\') {
-                        escaped = true;
-                    } else if (character === quote) {
-                        closed = true;
-                        break;
-                    }
+            }
+            if (!closed && !this.final) {
+                value = this.source.slice(valueStart, this.position);
+                if (escaped) {
+                    value = value.slice(0, -1);
                 }
-                if (!closed && !this.final) {
-                    value = this.source.slice(valueStart, this.position);
-                    if (escaped) {
-                        value = value.slice(0, -1);
+                try {
+                    node.props[name] = parseUiExpression(`${value}${quote}`, this.budget);
+                } catch (error) {
+                    if (error instanceof UiFailure && error.code === 'budget_exceeded') {
+                        throw error;
                     }
-                    try {
-                        node.props[name] = parseUiExpression(`${value}${quote}`, this.budget);
-                    } catch (error) {
-                        if (error instanceof UiFailure && error.code === 'budget_exceeded') {
-                            throw error;
-                        }
-                    }
-                    node.end = this.position;
-                    return;
                 }
-                value = this.source.slice(valueStart, this.position);
-            }
-            if (Object.hasOwn(node.props, name)) {
-                throw new UiFailure('duplicate_prop', `Duplicate prop ${name}.`);
+                node.end = this.position;
+                return false;
             }
-            node.props[name] = parseUiExpression(value, this.budget);
+            value = this.source.slice(valueStart, this.position);
         }
-        node.end = this.position;
-        if (this.final) {
-            this.diagnose(new UiFailure('unclosed_tag', `The ${node.type} tag is incomplete.`), start, node.id);
+        if (Object.hasOwn(node.props, name)) {
+            throw new UiFailure('duplicate_prop', `Duplicate prop ${name}.`);
+        }
+        node.props[name] = parseUiExpression(value, this.budget);
+        return true;
+    }
+
+    /* Skips a prop that could not be read, up to the next space or the end of its tag, so only that prop is lost. */
+    private skipToken(): void {
+        let quote = '';
+        let depth = 0;
+        while (this.position < this.source.length) {
+            this.budget.step();
+            const character = this.source[this.position];
+            if (quote) {
+                if (character === '\\') {
+                    this.position += 1;
+                } else if (character === quote) {
+                    quote = '';
+                }
+            } else if (character === '"' || character === "'") {
+                quote = character;
+            } else if (character === '{') {
+                depth += 1;
+            } else if (character === '}') {
+                depth = Math.max(0, depth - 1);
+            } else if (depth === 0 && (/\s/.test(character) || character === '>' || this.source.startsWith('/>', this.position))) {
+                break;
+            }
+            this.position += 1;
         }
     }
 
@@ -336,6 +398,13 @@ class UiParser {
         return { value: this.source.slice(start), complete: false };
     }
 
+    /* Whether a closing tag for this type follows, written the way `tag` accepts one: whitespace may stand before its `>`. */
+    private closesLater(type: string): boolean {
+        const closing = new RegExp(`</${type}\\s*>`, 'g');
+        closing.lastIndex = this.position;
+        return closing.test(this.source);
+    }
+
     private whitespace(): void {
         while (this.position < this.source.length && /\s/.test(this.source[this.position])) {
             this.position += 1;

package/src/text.ts

@@ -33,7 +33,7 @@ function uiExample(language: string): string {
 }
 
 export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE }: UiTextOptions = {}): string {
-    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
+    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choices only offer optional next steps after a finished answer; ask for information or a decision needed before acting with your own question tool if you have one, otherwise in prose. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
 }
 
 export function uiReferenceText({ fenceLanguage = UI_FENCE_LANGUAGE }: UiTextOptions = {}): string {