@adecore/agents-react 0.20.1 → 0.21.1

package/dist/chat/ui/intelligent-ui/UiFallbackPart.d.ts

@@ -0,0 +1,10 @@
+export type UiFallbackProblem = {
+    kind: 'unknown';
+    component: string;
+} | {
+    kind: 'failed';
+};
+export declare function UiFallbackPart({ fallback, problem }: {
+    fallback: string;
+    problem: UiFallbackProblem;
+}): import("react").JSX.Element;

package/dist/chat/ui/intelligent-ui/UiFallbackPart.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from 'react-i18next';
+import { Markdown } from '../Markdown.js';
+/*
+ * One part of a block as the markdown it stands for, in a quiet surface with a line that says why.
+ * A person sees it as a repair, never as an error, so nothing here is red.
+ */
+export function UiFallbackPart({ fallback, problem }) {
+    const { t } = useTranslation('agent-chat');
+    return (_jsxs("div", { className: "flex flex-col gap-1 rounded-md bg-surface-hover p-2", children: [_jsx("span", { className: "text-xs text-text-faint", children: problem.kind === 'unknown' ? t('blocks.unknownComponent', { component: problem.component }) : t('blocks.renderFailed') }), fallback !== '' && _jsx(Markdown, { text: fallback, fileLinks: false })] }));
+}

package/dist/chat/ui/intelligent-ui/UiReply.d.ts

@@ -0,0 +1,15 @@
+import { type ComponentProps, type ReactNode } from 'react';
+import { type UiBlock } from '@adecore/intelligent-ui';
+import type { ChatUiAnswer, ChatUiQueryState } from '@adecore/agent-contracts';
+import { ReplyMarkdown } from '../Markdown.js';
+import type { UiRenderContext } from './render-context.js';
+type UiBlockIdentity = Pick<UiRenderContext, 'scopeId' | 'chatId' | 'itemId' | 'blockId' | 'phase'>;
+export declare function UiReply({ text, blocks, context, answers, queries, reply }: {
+    text: string;
+    blocks: readonly UiBlock[];
+    context: Omit<UiBlockIdentity, 'blockId'>;
+    answers?: Readonly<Record<string, ChatUiAnswer>>;
+    queries?: ChatUiQueryState;
+    reply?: ComponentProps<typeof ReplyMarkdown>['reply'];
+}): ReactNode;
+export {};

package/dist/chat/ui/intelligent-ui/UiReply.js

@@ -0,0 +1,329 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, createContext, Fragment, memo, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import ReactMarkdown, {} from 'react-markdown';
+import { useTranslation } from 'react-i18next';
+import { evaluateUiBlock, uiInputValues, isUiComponent, UI_CATALOG_VERSION, UiState } from '@adecore/intelligent-ui';
+import { ErrorBoundary, Tooltip } from '@adecore/ui';
+import { chatHost } from '../../../host.js';
+import { UiReplyNavigationContext } from '../reply-context.js';
+import { ReplyMarkdown } from '../Markdown.js';
+import { rehypeFadeWords } from '../rehype-fade.js';
+import { UI_RENDERERS } from './registry.js';
+import { UiPageMemory } from './block-local.js';
+import { UiBlockFrame } from './UiBlockFrame.js';
+import { UiFallbackPart } from './UiFallbackPart.js';
+import { useUiLinks } from './use-ui-links.js';
+import { useUiQueries, useUiLiveValues } from './use-ui-queries.js';
+import { UiSourceCitation } from './renderers/content.js';
+import { uiChildrenOf, revealUiSource, uiLiveChoiceReason, uiUrlDomain } from './node-text.js';
+import { uiReplyParts } from './reply-parts.js';
+const localStates = new UiPageMemory(64);
+function localState(key, block, answered) {
+    let state = localStates.get(key);
+    if (!state) {
+        state = new UiState(block);
+        if (answered && answered.revision === block.revision) {
+            for (const [name, value] of Object.entries(answered.values ?? {})) {
+                state.set(name, value);
+            }
+        }
+        localStates.set(key, state);
+    }
+    return state;
+}
+/* The block itself, as the parent of its top-level nodes. */
+const BLOCK = '$block';
+/*
+ * Parents whose text is read as written: code, a short tag, and the labels of controls, whose
+ * accessible name and sent text are that same string.
+ */
+const LITERAL_PARENTS = new Set(['CodeBlock', 'Tag', 'Choice', 'Item', 'Switch', 'Slider', 'Segmented', 'Option', 'Button', 'Column']);
+/* Parents that stack their children, where a run of text and inline nodes is one paragraph. */
+const PARAGRAPHS = {
+    [BLOCK]: 'px-2 text-xs text-text',
+    Tab: 'px-2 text-xs text-text',
+    Section: 'text-xs text-text-muted'
+};
+const LINKS = new Set(['File', 'Diff', 'Commit', 'Node']);
+/* Constructs that would start a block or load an image stay text; without GFM a table never forms. */
+const BLOCK_CONSTRUCTS = [
+    'blockQuote',
+    'codeFenced',
+    'codeIndented',
+    'definition',
+    'headingAtx',
+    'htmlFlow',
+    'htmlText',
+    'labelStartImage',
+    'list',
+    'setextUnderline',
+    'thematicBreak'
+];
+/* Prose between the tags of a block is inline: only emphasis, code and links are Markdown, and a blank line is a line break. */
+function remarkInlineProse() {
+    // The field remark-parse reads its syntax extensions from, as remark-gfm adds its own.
+    const data = this.data();
+    data.micromarkExtensions = [...(data.micromarkExtensions ?? []), { disable: { null: BLOCK_CONSTRUCTS } }];
+    return (tree) => {
+        tree.children = [
+            {
+                type: 'paragraph',
+                children: (tree.children ?? []).flatMap((paragraph, index) => [...(index > 0 ? [{ type: 'break' }] : []), ...(paragraph.children ?? [])])
+            }
+        ];
+    };
+}
+function remarkCitations() {
+    return (tree) => {
+        const visit = (parent) => {
+            if (['link', 'inlineCode', 'code'].includes(parent.type)) {
+                return;
+            }
+            parent.children = parent.children?.flatMap((child) => {
+                if (child.type !== 'text' || !child.value) {
+                    visit(child);
+                    return [child];
+                }
+                const parts = [];
+                let start = 0;
+                for (const match of child.value.matchAll(/\[(\d{1,3})\]/g)) {
+                    parts.push({ type: 'text', value: child.value.slice(start, match.index) });
+                    parts.push({
+                        type: 'citation',
+                        data: { hName: 'span', hProperties: { 'data-ui-citation': match[1] } },
+                        children: [{ type: 'text', value: match[0] }]
+                    });
+                    start = match.index + match[0].length;
+                }
+                parts.push({ type: 'text', value: child.value.slice(start) });
+                return parts;
+            });
+        };
+        visit(tree);
+    };
+}
+const CitationContext = createContext({ sources: new Map() });
+function ProseCitation({ number, children }) {
+    const { sources, reveal } = useContext(CitationContext);
+    const source = sources.get(number);
+    return source ? _jsx(UiSourceCitation, { number: number, title: source.title, url: source.url, onReveal: reveal ? () => reveal(source) : undefined }) : children;
+}
+function sourceTargets(nodes) {
+    const lists = [];
+    const visit = (nodes, ancestors = []) => {
+        for (const node of nodes) {
+            const path = ['Tab', 'Section'].includes(node.type) ? [...ancestors, node.id] : ancestors;
+            if (node.type === 'Sources') {
+                lists.push(uiChildrenOf(node, 'Source').map((source) => ({ id: source.id, title: source.props.title, url: source.props.url, ancestors: path })));
+            }
+            visit(node.children, path);
+        }
+    };
+    visit(nodes);
+    // Numbers restart in each Sources list, so multiple lists have no unambiguous prose target.
+    return new Map(lists.length === 1 ? lists[0].map((source, index) => [index + 1, source]) : []);
+}
+const PROSE_PLUGINS = [remarkInlineProse, remarkCitations];
+const PROSE_ELEMENTS = ['p', 'br', 'strong', 'em', 'code', 'a', 'span'];
+const FADE_PLUGINS = [rehypeFadeWords];
+const NO_PLUGINS = [];
+const ProseUrlContext = createContext(undefined);
+/* Through the host only, like a Source: the address is the model's, so nothing here navigates by itself. */
+function ProseLink({ href, children }) {
+    const openUrl = useContext(ProseUrlContext);
+    if (openUrl === undefined || href === undefined || !/^https?:\/\//i.test(href)) {
+        return children;
+    }
+    return (_jsx(Tooltip, { label: uiUrlDomain(href), children: _jsx("button", { type: "button", className: "cursor-pointer text-accent underline underline-offset-2 select-text", onClick: () => openUrl(href), children: children }) }));
+}
+const PROSE_COMPONENTS = {
+    p: ({ children }) => children,
+    code: ({ children }) => _jsx("code", { className: "rounded-sm bg-surface-sunken px-1 py-px font-mono text-code", children: children }),
+    a: ({ href, children }) => _jsx(ProseLink, { href: href, children: children }),
+    span: ({ node, children, className }) => node?.properties['data-ui-citation'] !== undefined ? (_jsx(ProseCitation, { number: Number(node.properties['data-ui-citation']), children: children })) : (_jsx("span", { className: className, children: children }))
+};
+/*
+ * Text an agent wrote in a block, as inline Markdown without raw HTML. Markdown trims a paragraph,
+ * so the whitespace at either end stays text: it is the space between a word and the tag beside it.
+ * While the block streams every new word fades in, as in the prose of the reply around it.
+ */
+const UiProse = memo(function UiProse({ text, fade, openUrl }) {
+    const [, lead = '', body = '', trail = ''] = /^(\s*)([\s\S]*?)(\s*)$/.exec(text) ?? [];
+    if (body === '') {
+        return text;
+    }
+    return (_jsxs(ProseUrlContext, { value: openUrl, children: [lead, _jsx(ReactMarkdown, { remarkPlugins: PROSE_PLUGINS, rehypePlugins: fade ? FADE_PLUGINS : NO_PLUGINS, allowedElements: PROSE_ELEMENTS, unwrapDisallowed: true, components: PROSE_COMPONENTS, children: body }), trail] }));
+});
+/* Which text nodes of a block the agent wrote out, by id; the value of an expression is data and stays as it is. */
+function writtenTexts(nodes, into = new Map()) {
+    for (const node of nodes) {
+        if (node.type === '$text') {
+            into.set(node.id, node.expressions.text === undefined);
+        }
+        writtenTexts(node.children, into);
+    }
+    return into;
+}
+function isInline(node) {
+    if (node.type === '$text') {
+        return true;
+    }
+    return node.error === undefined && (node.type === 'Tag' || (LINKS.has(node.type) && node.children.length === 0));
+}
+function isBlank(node) {
+    return node.type === '$text' && String(node.props.text ?? '').trim() === '';
+}
+/* The children of one parent, each in its own boundary. Where the parent stacks them, a run of text and inline nodes becomes a paragraph. */
+function UiNodes({ nodes, parent, texts, context }) {
+    const drawn = (node) => (_jsx(UiNodeBoundary, { node: node, children: _jsx(UiNodeBody, { node: node, parent: parent, texts: texts, context: context }) }, node.id));
+    const paragraph = PARAGRAPHS[parent];
+    if (parent === 'Choices') {
+        // A primary choice stands first in the order a keyboard and a screen reader meet it too, not only on screen.
+        return [...nodes].sort((a, b) => Number(b.props.primary === true) - Number(a.props.primary === true)).map(drawn);
+    }
+    if (paragraph === undefined) {
+        return nodes.map(drawn);
+    }
+    const output = [];
+    let run = [];
+    const close = () => {
+        if (run.some((node) => !isBlank(node))) {
+            output.push(_jsx("div", { className: paragraph, children: run.map(drawn) }, `run:${run[0].id}`));
+        }
+        run = [];
+    };
+    for (const node of nodes) {
+        if (isInline(node)) {
+            run.push(node);
+            continue;
+        }
+        close();
+        output.push(drawn(node));
+    }
+    close();
+    return output;
+}
+class UiNodeBoundary extends Component {
+    state = { failed: false, node: this.props.node };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    static getDerivedStateFromProps(props, state) {
+        return props.node === state.node ? null : { failed: false, node: props.node };
+    }
+    render() {
+        return this.state.failed ? _jsx(UiFallbackPart, { fallback: this.props.node.fallback, problem: { kind: 'failed' } }) : this.props.children;
+    }
+}
+function UiNodeBody({ node, parent, texts, context }) {
+    if (node.type === '$text') {
+        const text = String(node.props.text ?? '');
+        return LITERAL_PARENTS.has(parent) || texts.get(node.sourceId ?? node.id) !== true ? (text) : (_jsx(UiProse, { text: text, fade: context.phase === 'streaming', openUrl: context.openUrl }));
+    }
+    if (node.error !== undefined) {
+        return _jsx(UiFallbackPart, { fallback: node.fallback, problem: { kind: 'failed' } });
+    }
+    if (!isUiComponent(node.type)) {
+        return _jsx(UiFallbackPart, { fallback: node.fallback, problem: { kind: 'unknown', component: node.type } });
+    }
+    const Renderer = UI_RENDERERS[node.type];
+    if (Renderer === null) {
+        return null;
+    }
+    return (_jsx(Renderer, { node: node, context: context, children: _jsx(UiNodes, { nodes: node.children, parent: node.type, texts: texts, context: context }) }));
+}
+function UiBlockBody({ block, context, answered, frozen }) {
+    const { t } = useTranslation('agent-chat');
+    const key = JSON.stringify([context.scopeId, context.chatId, context.itemId, block.id]);
+    const [state] = useState(() => localState(key, block, answered));
+    state.sync(block);
+    const stateRevision = useSyncExternalStore((listener) => state.subscribe(listener), () => state.snapshot(), () => state.snapshot());
+    const [optimistic, setOptimistic] = useState(null);
+    const [failedChoiceId, setFailedChoiceId] = useState(null);
+    const pending = useRef(false);
+    useEffect(() => {
+        if (answered && answered.revision === block.revision && answered.values) {
+            for (const [name, value] of Object.entries(answered.values)) {
+                state.set(name, value);
+            }
+        }
+    }, [state, answered, block.revision]);
+    const answer = answered && answered.revision === block.revision
+        ? { choiceId: answered.choiceId, state: answered.queued ? 'queued' : 'sent' }
+        : optimistic?.revision === block.revision
+            ? optimistic
+            : null;
+    const [element, setElement] = useState(null);
+    const navigation = useContext(UiReplyNavigationContext);
+    const flash = navigation?.flash;
+    const flashing = navigation?.chatId === context.chatId && flash?.itemId === context.itemId && flash.blockId === block.id && flash.revision === block.revision;
+    const queries = useUiQueries(block, state, context, element, frozen);
+    const links = useUiLinks(block, state, context, queries.reads, frozen);
+    // The state changes in place, so its revision is what tells this evaluation it went stale.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    const evaluation = useMemo(() => evaluateUiBlock(block, state), [block, state, stateRevision]);
+    const texts = useMemo(() => writtenTexts(block.nodes), [block]);
+    const sources = useMemo(() => sourceTargets(evaluation.nodes), [evaluation]);
+    const citations = useMemo(() => ({
+        sources,
+        reveal: element
+            ? (source) => {
+                void revealUiSource(element, source.id, source.ancestors);
+            }
+            : undefined
+    }), [sources, element]);
+    const liveValue = useUiLiveValues(block, evaluation.nodes, queries.currentReadings);
+    const sendChoice = chatHost().intelligentUi?.sendChoice;
+    const rendering = {
+        ...context,
+        ...links,
+        answer,
+        failedChoiceId,
+        live: queries.live,
+        liveValue,
+        choiceReason: uiLiveChoiceReason(t, queries.live),
+        onChoose: !queries.ready || queries.reading
+            ? undefined
+            : sendChoice && block.revision && block.complete && context.phase === 'final'
+                ? (choiceId) => {
+                    if (pending.current || answer || queries.reading) {
+                        return;
+                    }
+                    const values = uiInputValues(block, state);
+                    const reads = queries.readsFor(values);
+                    if (reads === null) {
+                        return;
+                    }
+                    pending.current = true;
+                    setFailedChoiceId(null);
+                    const revision = block.revision;
+                    setOptimistic({ revision, choiceId, state: 'sending' });
+                    void sendChoice(context.scopeId, {
+                        chatId: context.chatId,
+                        itemId: context.itemId,
+                        blockId: block.id,
+                        revision,
+                        choiceId,
+                        reads,
+                        values
+                    })
+                        .then((state) => setOptimistic({ revision, choiceId, state }))
+                        .catch(() => {
+                        setOptimistic(null);
+                        setFailedChoiceId(choiceId);
+                    })
+                        .finally(() => {
+                        pending.current = false;
+                    });
+                }
+                : undefined
+    };
+    const unknown = block.catalogVersion !== UI_CATALOG_VERSION;
+    const failed = !unknown && !block.nodes.length && block.diagnostics.length > 0;
+    const shownAsText = unknown ? t('blocks.unreadable') : failed ? block.diagnostics[0].message : undefined;
+    return (_jsxs("div", { ref: setElement, className: "relative", "data-ui-block": block.id, "data-ui-revision": block.revision, tabIndex: -1, children: [flashing && _jsx("span", { className: "chat-flash pointer-events-none absolute inset-0 rounded-lg", "aria-hidden": true }, flash.nonce), _jsx(UiBlockFrame, { live: queries.live, nodes: evaluation.nodes, phase: context.phase, fixes: [...block.diagnostics, ...evaluation.diagnostics], shownAsText: shownAsText, answered: answered, children: unknown || failed ? (_jsx(ReplyMarkdown, { text: block.fallback, streaming: false })) : (_jsx(CitationContext, { value: citations, children: _jsx(UiNodes, { nodes: evaluation.nodes, parent: BLOCK, texts: texts, context: rendering }) })) })] }));
+}
+/* Prose and cards a block gap apart, as the rows of a turn are; text that is only the newline between two fences draws nothing. */
+export function UiReply({ text, blocks, context, answers, queries, reply }) {
+    return (_jsx("div", { className: "flex flex-col gap-(--chat-block-gap)", children: uiReplyParts(text, blocks, context.phase === 'streaming').map((part, index) => part.kind === 'text' ? (part.text.trim() !== '' && (_jsx(Fragment, { children: _jsx(ReplyMarkdown, { text: part.text, streaming: context.phase === 'streaming', reply: reply }) }, `text:${index}`))) : (_jsx(ErrorBoundary, { label: "UI block", children: _jsx(UiBlockBody, { block: part.block, frozen: queries?.blocks[part.block.id], answered: answers?.[part.block.id], context: { scopeId: context.scopeId, chatId: context.chatId, itemId: context.itemId, phase: context.phase, blockId: part.block.id } }) }, JSON.stringify([context.scopeId, context.chatId, context.itemId, part.block.id])))) }));
+}

package/dist/chat/ui/intelligent-ui/block-local.d.ts

@@ -0,0 +1,11 @@
+import type { UiRenderContext } from './render-context.js';
+export declare class UiPageMemory<Value> {
+    private readonly entries;
+    private readonly limit;
+    constructor(limit: number);
+    has(key: string): boolean;
+    get(key: string): Value | undefined;
+    set(key: string, value: Value): void;
+    get size(): number;
+}
+export declare function useBlockLocal<Value>(context: UiRenderContext, nodeId: string, initial: () => Value): [Value, (next: Value) => void];

package/dist/chat/ui/intelligent-ui/block-local.js

@@ -0,0 +1,42 @@
+import { useState } from 'react';
+/* Values that last as long as the page, past `limit` forgetting the one used longest ago. */
+export class UiPageMemory {
+    entries = new Map();
+    limit;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    has(key) {
+        return this.entries.has(key);
+    }
+    /* Reading a value counts as using it. */
+    get(key) {
+        const value = this.entries.get(key);
+        if (value !== undefined) {
+            this.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        if (this.entries.size > this.limit) {
+            this.entries.delete(this.entries.keys().next().value);
+        }
+    }
+    get size() {
+        return this.entries.size;
+    }
+}
+// Which tab or section a person opened, so a block the thread unmounts while scrolling comes back as they left it.
+const remembered = new UiPageMemory(512);
+/* State of one node that lasts as long as the page, such as a fold; local input state belongs to the runtime instead. */
+export function useBlockLocal(context, nodeId, initial) {
+    const key = `${context.scopeId}\n${context.chatId}\n${context.itemId}\n${context.blockId}\n${nodeId}`;
+    const [value, setValue] = useState(() => (remembered.has(key) ? remembered.get(key) : initial()));
+    const set = (next) => {
+        remembered.set(key, next);
+        setValue(next);
+    };
+    return [value, set];
+}

package/dist/chat/ui/intelligent-ui/chart-data.d.ts

@@ -0,0 +1,16 @@
+import type { UiProps } from '@adecore/intelligent-ui';
+export declare const UI_CHART_SERIES = 6;
+export declare const UI_CHART_ROWS = 60;
+export interface UiChartSeries {
+    key: string;
+    values: (number | null)[];
+}
+export interface UiChartData {
+    labels: string[];
+    series: UiChartSeries[];
+    min: number;
+    max: number;
+    truncated: boolean;
+}
+export declare function uiChartData(data: UiProps<'Chart'>['data'], kind: UiProps<'Chart'>['kind']): UiChartData | null;
+export declare function niceCeiling(value: number): number;

package/dist/chat/ui/intelligent-ui/chart-data.js

@@ -0,0 +1,46 @@
+/* The catalog promises up to six series, one per chart color. */
+export const UI_CHART_SERIES = 6;
+/* Categories a chart draws; more would not fit a column of a thread. */
+export const UI_CHART_ROWS = 60;
+/*
+ * The series a chart can draw: every key besides `label` with a finite number in some row, the
+ * first six of them. A value that is missing or no finite number is a gap. Null when there is no
+ * row or no series, which draws the fallback.
+ */
+export function uiChartData(data, kind) {
+    const rows = data.slice(0, UI_CHART_ROWS);
+    const keys = [];
+    for (const row of rows) {
+        for (const [key, value] of Object.entries(row)) {
+            if (key !== 'label' && !keys.includes(key) && keys.length < UI_CHART_SERIES && typeof value === 'number' && Number.isFinite(value)) {
+                keys.push(key);
+            }
+        }
+    }
+    if (rows.length === 0 || keys.length === 0) {
+        return null;
+    }
+    const series = keys.map((key) => ({
+        key,
+        values: rows.map((row) => {
+            const value = row[key];
+            return typeof value === 'number' && Number.isFinite(value) ? value : null;
+        })
+    }));
+    const labels = rows.map((row) => (typeof row.label === 'string' || typeof row.label === 'number' ? String(row.label) : ''));
+    const extents = kind === 'stacked'
+        ? labels.map((_, index) => series.reduce((sum, { values }) => sum + Math.max(0, values[index] ?? 0), 0))
+        : series.flatMap(({ values }) => values.filter((value) => value !== null));
+    const min = Math.min(0, ...extents);
+    const max = Math.max(0, ...extents);
+    return { labels, series, min, max: max === min ? min + 1 : max, truncated: data.length > rows.length };
+}
+/* A round number at or above `value`, for the top of an axis: 1, 2, 2.5 or 5 times a power of ten. */
+export function niceCeiling(value) {
+    if (value <= 0) {
+        return 0;
+    }
+    const power = 10 ** Math.floor(Math.log10(value));
+    const step = [1, 2, 2.5, 5, 10].find((factor) => factor * power >= value) ?? 10;
+    return step * power;
+}

package/dist/chat/ui/intelligent-ui/node-text.d.ts

@@ -0,0 +1,15 @@
+import type { TFunction } from 'i18next';
+import type { UiComponentName, UiProps, UiViewNode } from '@adecore/intelligent-ui';
+import type { UiLiveStatus } from './render-context.js';
+export declare function uiNodeText(node: UiViewNode): string;
+export declare function uiNodeLabel(node: UiViewNode): string;
+export declare function uiChildrenOf<Name extends UiComponentName>(node: UiViewNode, type: Name): UiViewNode<UiProps<Name>>[];
+export declare function uiBlockHead(nodes: readonly UiViewNode[]): {
+    id: string;
+    label: string;
+} | null;
+export declare function revealUiSource(root: ParentNode, nodeId: string, ancestors?: readonly string[]): Promise<boolean>;
+export declare function uiReasonText(t: TFunction<'agent-chat'>, code: string | undefined, reason: string | undefined): string | undefined;
+export declare function uiWithUnit(text: string, unit: string | undefined): string;
+export declare function uiLiveChoiceReason(t: TFunction<'agent-chat'>, live: UiLiveStatus | null | undefined): string | null;
+export declare function uiUrlDomain(url: string): string;

package/dist/chat/ui/intelligent-ui/node-text.js

@@ -0,0 +1,106 @@
+/* The text a node holds, every `$text` below it joined as written, such as the code of a CodeBlock. */
+export function uiNodeText(node) {
+    return node.children.map((child) => (child.type === '$text' ? String(child.props.text ?? '') : uiNodeText(child))).join('');
+}
+/* The same text on one line, for a name a control or a screen reader needs as a string. */
+export function uiNodeLabel(node) {
+    return uiNodeText(node).replace(/\s+/g, ' ').trim();
+}
+/* The valid children of one kind, which a parent reads as metadata: the columns of a table, the tabs of a strip. */
+export function uiChildrenOf(node, type) {
+    return node.children.filter((child) => child.type === type && child.error === undefined);
+}
+/* A Summary draws its text as inline Markdown, so the name it gives its block leaves out the code ticks, the strong marks and the address of a link. */
+function withoutMarks(text) {
+    return text
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/\*\*|`/g, '')
+        .trim();
+}
+/* The Summary that heads a block, which is its first node; a Summary further down is a subheading. */
+export function uiBlockHead(nodes) {
+    const first = nodes[0];
+    if (first === undefined || first.type !== 'Summary' || first.error !== undefined) {
+        return null;
+    }
+    return { id: first.id, label: withoutMarks(uiNodeLabel(first)) };
+}
+/*
+ * Scrolls the Source row of `nodeId` under `root` into view and focuses it, which lights the row once.
+ * Opens enclosing tabs and sections first; false when the source is absent.
+ */
+export async function revealUiSource(root, nodeId, ancestors = []) {
+    for (const id of ancestors) {
+        const control = [...root.querySelectorAll('[data-ui-reveal]')].find((element) => element.dataset.uiReveal === id);
+        if (control && (control.getAttribute('aria-expanded') === 'false' || control.getAttribute('aria-selected') === 'false')) {
+            control.click();
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+    const row = [...root.querySelectorAll('[data-ui-source]')].find((element) => element.dataset.uiSource === nodeId);
+    if (row === undefined) {
+        return false;
+    }
+    // The light runs when focus arrives, so a row that already has it lets go first.
+    if (row.ownerDocument.activeElement === row) {
+        row.blur();
+    }
+    row.focus({ preventScroll: true });
+    const reduced = row.ownerDocument.defaultView?.matchMedia('(prefers-reduced-motion: reduce)').matches === true;
+    row.scrollIntoView({ block: 'nearest', behavior: reduced ? 'auto' : 'smooth' });
+    return true;
+}
+/* The reason codes this version says in its own words; any other code reads as the reason the machine gave. */
+const UI_REASON_CODES = new Set([
+    'access-unavailable',
+    'block-stale',
+    'busy',
+    'link-unchecked',
+    'link-unsupported',
+    'links-unsupported',
+    'no-unique-match',
+    'outside-project',
+    'query-undeclared',
+    'refresh-limit',
+    'result-too-large',
+    'snapshot-too-large',
+    'source-unregistered',
+    'stale-read',
+    'target-unavailable',
+    'timed-out',
+    'unreadable'
+]);
+/* Why a reading failed or a link stayed plain, in the person's language where the code is known. */
+export function uiReasonText(t, code, reason) {
+    return code !== undefined && UI_REASON_CODES.has(code) ? t(`blocks.live.reasons.${code}`) : reason;
+}
+/*
+ * A number with its unit, where a percent sign hugs the number and every other unit stands apart
+ * from it, by a space that never lets the two wrap apart.
+ */
+export function uiWithUnit(text, unit) {
+    if (unit === undefined || unit === '') {
+        return text;
+    }
+    return unit === '%' ? `${text}${unit}` : `${text}\u00a0${unit}`;
+}
+/* Why the choices of a live block are closed: its data is still being read, or the reason a reading failed. Null while nothing live holds them. */
+export function uiLiveChoiceReason(t, live) {
+    if (live === null || live === undefined || live.state === 'fresh') {
+        return null;
+    }
+    if (live.state === 'reading') {
+        return t('blocks.choice.reading');
+    }
+    const source = live.source ?? live.sources[0] ?? '';
+    return uiReasonText(t, live.code, live.reason) ?? t(live.state === 'failed' ? 'blocks.live.failed' : 'blocks.live.refused', { source });
+}
+/* The host of an address without its `www.`, which is how a source or a link in prose says where it goes. */
+export function uiUrlDomain(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return url;
+    }
+}

package/dist/chat/ui/intelligent-ui/registry.d.ts

@@ -0,0 +1,2 @@
+import type { UiRenderers } from './render-context.js';
+export declare const UI_RENDERERS: UiRenderers;