@adecore/agents-react 0.20.0 → 0.21.0

package/src/chat/ui/intelligent-ui/UiReply.tsx

@@ -0,0 +1,531 @@
+import {
+    Component,
+    createContext,
+    Fragment,
+    memo,
+    useContext,
+    useEffect,
+    useRef,
+    useState,
+    useSyncExternalStore,
+    type ComponentProps,
+    type ReactNode
+} from 'react';
+import ReactMarkdown, { type Components } from 'react-markdown';
+import { useTranslation } from 'react-i18next';
+import {
+    evaluateUiBlock,
+    uiInputValues,
+    isUiComponent,
+    UI_CATALOG_VERSION,
+    UiState,
+    type UiBlock,
+    type UiNode,
+    type UiViewNode
+} from '@adecore/intelligent-ui';
+import { ErrorBoundary } from '@adecore/ui';
+import type { ChatUiAnswer, ChatUiQueryState } from '@adecore/agent-contracts';
+import { chatHost } from '../../../host';
+import { UiReplyNavigationContext } from '../reply-context';
+import { ReplyMarkdown } from '../Markdown';
+import { rehypeFadeWords } from '../rehype-fade';
+import { UI_RENDERERS } from './registry';
+import type { UiRenderContext, UiRenderer } from './render-context';
+import { UiBlockFrame } from './UiBlockFrame';
+import { UiFallbackPart } from './UiFallbackPart';
+import { useUiLinks } from './use-ui-links';
+import { useUiQueries, useUiLiveValues } from './use-ui-queries';
+import { UiSourceCitation } from './renderers/content';
+import { uiChildrenOf, revealUiSource } from './node-text';
+import { uiReplyParts } from './reply-parts';
+
+const localStates = new Map<string, UiState>();
+const LOCAL_STATE_LIMIT = 64;
+
+function localState(key: string, block: UiBlock, answered?: ChatUiAnswer): UiState {
+    let state = localStates.get(key);
+    localStates.delete(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);
+    if (localStates.size > LOCAL_STATE_LIMIT) {
+        localStates.delete(localStates.keys().next().value!);
+    }
+    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', 'Column']);
+
+/* Parents that stack their children, where a run of text and inline nodes is one paragraph. */
+const PARAGRAPHS: Readonly<Record<string, string>> = {
+    [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'
+];
+
+interface ProseTree {
+    type: string;
+    children?: ProseTree[];
+    value?: string;
+    data?: unknown;
+}
+
+/* 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(this: { data(): object }) {
+    // The field remark-parse reads its syntax extensions from, as remark-gfm adds its own.
+    const data = this.data() as { micromarkExtensions?: unknown[] };
+    data.micromarkExtensions = [...(data.micromarkExtensions ?? []), { disable: { null: BLOCK_CONSTRUCTS } }];
+    return (tree: ProseTree) => {
+        tree.children = [
+            {
+                type: 'paragraph',
+                children: (tree.children ?? []).flatMap((paragraph, index) => [...(index > 0 ? [{ type: 'break' }] : []), ...(paragraph.children ?? [])])
+            }
+        ];
+    };
+}
+
+function remarkCitations() {
+    return (tree: ProseTree) => {
+        const visit = (parent: ProseTree) => {
+            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: ProseTree[] = [];
+                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);
+    };
+}
+
+interface CitationTarget {
+    id: string;
+    title: string;
+    url: string;
+    ancestors: string[];
+}
+const CitationContext = createContext<{ sources: ReadonlyMap<number, CitationTarget>; reveal?: (source: CitationTarget) => void }>({ sources: new Map() });
+
+function ProseCitation({ number, children }: { number: number; children?: ReactNode }) {
+    const { sources, reveal } = useContext(CitationContext);
+    const source = sources.get(number);
+    return source ? <UiSourceCitation number={number} title={source.title} url={source.url} onReveal={reveal ? () => reveal(source) : undefined} /> : children;
+}
+
+function sourceTargets(nodes: readonly UiViewNode[]): Map<number, CitationTarget> {
+    const lists: CitationTarget[][] = [];
+    const visit = (nodes: readonly UiViewNode[], ancestors: string[] = []) => {
+        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'];
+// Raw HTML never parses here, so the only spans are the words the fade wraps.
+const FADING_PROSE_ELEMENTS = [...PROSE_ELEMENTS, 'span'];
+const FADE_PLUGINS = [rehypeFadeWords];
+const NO_PLUGINS: typeof FADE_PLUGINS = [];
+
+const ProseUrlContext = createContext<((url: string) => void) | undefined>(undefined);
+
+/* Through the host only, like a Source: the address is the model's, so nothing here navigates by itself. */
+function ProseLink({ href, children }: { href?: string; children?: ReactNode }) {
+    const openUrl = useContext(ProseUrlContext);
+    if (openUrl === undefined || href === undefined || !/^https?:\/\//i.test(href)) {
+        return children;
+    }
+    return (
+        <button type="button" className="cursor-pointer text-accent underline underline-offset-2 select-text" onClick={() => openUrl(href)}>
+            {children}
+        </button>
+    );
+}
+
+const PROSE_COMPONENTS: Components = {
+    p: ({ children }) => children,
+    code: ({ children }) => <code className="rounded-sm bg-surface-sunken px-1 py-px font-mono text-code">{children}</code>,
+    a: ({ href, children }) => <ProseLink href={href}>{children}</ProseLink>,
+    span: ({ node, children, className }) =>
+        node?.properties['data-ui-citation'] !== undefined ? (
+            <ProseCitation number={Number(node.properties['data-ui-citation'])}>{children}</ProseCitation>
+        ) : (
+            <span className={className}>{children}</span>
+        )
+};
+
+/*
+ * 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 }: { text: string; fade: boolean; openUrl?: (url: string) => void }) {
+    const [, lead = '', body = '', trail = ''] = /^(\s*)([\s\S]*?)(\s*)$/.exec(text) ?? [];
+    if (body === '') {
+        return text;
+    }
+    return (
+        <ProseUrlContext value={openUrl}>
+            {lead}
+            <ReactMarkdown
+                remarkPlugins={PROSE_PLUGINS}
+                rehypePlugins={fade ? FADE_PLUGINS : NO_PLUGINS}
+                allowedElements={fade ? FADING_PROSE_ELEMENTS : PROSE_ELEMENTS}
+                unwrapDisallowed
+                components={PROSE_COMPONENTS}
+            >
+                {body}
+            </ReactMarkdown>
+            {trail}
+        </ProseUrlContext>
+    );
+});
+
+/* 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: readonly UiNode[], into = new Map<string, boolean>()): Map<string, boolean> {
+    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: UiViewNode): boolean {
+    if (node.type === '$text') {
+        return true;
+    }
+    return node.error === undefined && (node.type === 'Tag' || (LINKS.has(node.type) && node.children.length === 0));
+}
+
+function isBlank(node: UiViewNode): boolean {
+    return node.type === '$text' && String(node.props.text ?? '').trim() === '';
+}
+
+interface UiNodesProps {
+    nodes: readonly UiViewNode[];
+    parent: string;
+    texts: ReadonlyMap<string, boolean>;
+    context: UiRenderContext;
+}
+
+/* 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 }: UiNodesProps): ReactNode {
+    const drawn = (node: UiViewNode) => (
+        <UiNodeBoundary key={node.id} node={node}>
+            <UiNodeBody node={node} parent={parent} texts={texts} context={context} />
+        </UiNodeBoundary>
+    );
+    const paragraph = PARAGRAPHS[parent];
+    if (paragraph === undefined) {
+        return nodes.map(drawn);
+    }
+    const output: ReactNode[] = [];
+    let run: UiViewNode[] = [];
+    const close = () => {
+        if (run.some((node) => !isBlank(node))) {
+            output.push(
+                <div key={`run:${run[0]!.id}`} className={paragraph}>
+                    {run.map(drawn)}
+                </div>
+            );
+        }
+        run = [];
+    };
+    for (const node of nodes) {
+        if (isInline(node)) {
+            run.push(node);
+            continue;
+        }
+        close();
+        output.push(drawn(node));
+    }
+    close();
+    return output;
+}
+
+interface UiNodeBoundaryProps {
+    node: UiViewNode;
+    children: ReactNode;
+}
+
+interface UiNodeBoundaryState {
+    failed: boolean;
+    node: UiViewNode;
+}
+
+class UiNodeBoundary extends Component<UiNodeBoundaryProps, UiNodeBoundaryState> {
+    state = { failed: false, node: this.props.node };
+
+    static getDerivedStateFromError(): { failed: boolean } {
+        return { failed: true };
+    }
+
+    static getDerivedStateFromProps(props: UiNodeBoundaryProps, state: UiNodeBoundaryState): UiNodeBoundaryState | null {
+        return props.node === state.node ? null : { failed: false, node: props.node };
+    }
+
+    render(): ReactNode {
+        return this.state.failed ? <UiFallbackPart fallback={this.props.node.fallback} problem={{ kind: 'failed' }} /> : this.props.children;
+    }
+}
+
+function UiNodeBody({
+    node,
+    parent,
+    texts,
+    context
+}: {
+    node: UiViewNode;
+    parent: string;
+    texts: ReadonlyMap<string, boolean>;
+    context: UiRenderContext;
+}): ReactNode {
+    if (node.type === '$text') {
+        const text = String(node.props.text ?? '');
+        return LITERAL_PARENTS.has(parent) || texts.get(node.sourceId ?? node.id) !== true ? (
+            text
+        ) : (
+            <UiProse text={text} fade={context.phase === 'streaming'} openUrl={context.openUrl} />
+        );
+    }
+    if (node.error !== undefined) {
+        return <UiFallbackPart fallback={node.fallback} problem={{ kind: 'failed' }} />;
+    }
+    if (!isUiComponent(node.type)) {
+        return <UiFallbackPart fallback={node.fallback} problem={{ kind: 'unknown', component: node.type }} />;
+    }
+    const Renderer = UI_RENDERERS[node.type] as UiRenderer<Record<string, unknown>> | null;
+    if (Renderer === null) {
+        return null;
+    }
+    return (
+        <Renderer node={node} context={context}>
+            <UiNodes nodes={node.children} parent={node.type} texts={texts} context={context} />
+        </Renderer>
+    );
+}
+
+function UiBlockBody({
+    block,
+    context,
+    answered,
+    frozen
+}: {
+    block: UiBlock;
+    context: UiRenderContext;
+    answered?: ChatUiAnswer;
+    frozen?: ChatUiQueryState['blocks'][string];
+}): ReactNode {
+    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);
+    useSyncExternalStore(
+        (listener) => state.subscribe(listener),
+        () => state.snapshot(),
+        () => state.snapshot()
+    );
+    const [optimistic, setOptimistic] = useState<{ revision: string; choiceId: string; state: 'sending' | 'sent' | 'queued' } | null>(null);
+    const [failedChoiceId, setFailedChoiceId] = useState<string | null>(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' as const) : ('sent' as const) }
+            : optimistic?.revision === block.revision
+              ? optimistic
+              : context.answer;
+    const [element, setElement] = useState<HTMLDivElement | null>(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);
+    const evaluation = evaluateUiBlock(block, state);
+    const liveValue = useUiLiveValues(block, evaluation.nodes, queries.currentReadings);
+    const sendChoice = chatHost().intelligentUi?.sendChoice;
+    const rendering: UiRenderContext = {
+        ...context,
+        ...links,
+        answer,
+        failedChoiceId,
+        live: queries.live ?? context.live,
+        liveValue: liveValue ?? context.liveValue,
+        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;
+                            });
+                    }
+                  : context.onChoose
+    };
+    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 (
+        <div ref={setElement} className="relative" data-ui-block={block.id} data-ui-revision={block.revision} tabIndex={-1}>
+            {flashing && <span key={flash.nonce} className="chat-flash pointer-events-none absolute inset-0 rounded-lg" aria-hidden />}
+            <UiBlockFrame
+                live={queries.live}
+                nodes={evaluation.nodes}
+                phase={context.phase}
+                fixes={[...block.diagnostics, ...evaluation.diagnostics]}
+                shownAsText={shownAsText}
+                answered={answered}
+            >
+                {unknown || failed ? (
+                    <ReplyMarkdown text={block.fallback} streaming={false} />
+                ) : (
+                    <CitationContext
+                        value={{
+                            sources: sourceTargets(evaluation.nodes),
+                            reveal: element
+                                ? (source) => {
+                                      void revealUiSource(element, source.id, source.ancestors);
+                                  }
+                                : undefined
+                        }}
+                    >
+                        <UiNodes nodes={evaluation.nodes} parent={BLOCK} texts={writtenTexts(block.nodes)} context={rendering} />
+                    </CitationContext>
+                )}
+            </UiBlockFrame>
+        </div>
+    );
+}
+
+/* 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
+}: {
+    text: string;
+    blocks: readonly UiBlock[];
+    context: Omit<UiRenderContext, 'blockId'>;
+    answers?: Readonly<Record<string, ChatUiAnswer>>;
+    queries?: ChatUiQueryState;
+    reply?: ComponentProps<typeof ReplyMarkdown>['reply'];
+}): ReactNode {
+    return (
+        <div className="flex flex-col gap-(--chat-block-gap)">
+            {uiReplyParts(text, blocks, context.phase === 'streaming').map((part, index) =>
+                part.kind === 'text' ? (
+                    part.text.trim() !== '' && (
+                        <Fragment key={`text:${index}`}>
+                            <ReplyMarkdown text={part.text} streaming={context.phase === 'streaming'} reply={reply} />
+                        </Fragment>
+                    )
+                ) : (
+                    <ErrorBoundary key={part.block.id} label="UI block" resetKeys={[context.scopeId, context.chatId, context.itemId, part.block.id]}>
+                        <UiBlockBody
+                            key={JSON.stringify([context.scopeId, context.chatId, context.itemId, part.block.id])}
+                            block={part.block}
+                            frozen={queries?.blocks[part.block.id]}
+                            answered={answers?.[part.block.id]}
+                            context={{ ...context, blockId: part.block.id }}
+                        />
+                    </ErrorBoundary>
+                )
+            )}
+        </div>
+    );
+}

package/src/chat/ui/intelligent-ui/block-local.ts

@@ -0,0 +1,16 @@
+import { useState } from 'react';
+import type { UiRenderContext } from './render-context';
+
+// Which tab or section a person opened, so a block the thread unmounts while scrolling comes back as they left it.
+const remembered = new Map<string, unknown>();
+
+/* 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<Value>(context: UiRenderContext, nodeId: string, initial: () => Value): [Value, (next: Value) => void] {
+    const key = `${context.scopeId}\n${context.chatId}\n${context.itemId}\n${context.blockId}\n${nodeId}`;
+    const [value, setValue] = useState<Value>(() => (remembered.has(key) ? (remembered.get(key) as Value) : initial()));
+    const set = (next: Value): void => {
+        remembered.set(key, next);
+        setValue(next);
+    };
+    return [value, set];
+}

package/src/chat/ui/intelligent-ui/chart-data.ts

@@ -0,0 +1,67 @@
+import type { UiProps } from '@adecore/intelligent-ui';
+
+/* 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;
+
+export interface UiChartSeries {
+    key: string;
+    /* One per label, null where a row has no number for this series. */
+    values: (number | null)[];
+}
+
+export interface UiChartData {
+    labels: string[];
+    series: UiChartSeries[];
+    /* The range the axis covers, from zero or below it, never empty. */
+    min: number;
+    max: number;
+    /* Whether rows past `UI_CHART_ROWS` were left out. */
+    truncated: boolean;
+}
+
+/*
+ * 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: UiProps<'Chart'>['data'], kind: UiProps<'Chart'>['kind']): UiChartData | null {
+    const rows = data.slice(0, UI_CHART_ROWS);
+    const keys: string[] = [];
+    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: number): number {
+    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/src/chat/ui/intelligent-ui/node-text.ts

@@ -0,0 +1,59 @@
+import type { UiComponentName, UiProps, UiViewNode } from '@adecore/intelligent-ui';
+
+/* The text a node holds, every `$text` below it joined as written, such as the code of a CodeBlock. */
+export function uiNodeText(node: UiViewNode): string {
+    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: UiViewNode): string {
+    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<Name extends UiComponentName>(node: UiViewNode, type: Name): UiViewNode<UiProps<Name>>[] {
+    return node.children.filter((child) => child.type === type && child.error === undefined) as UiViewNode<UiProps<Name>>[];
+}
+
+/* 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: string): string {
+    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: readonly UiViewNode[]): { id: string; label: string } | null {
+    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: ParentNode, nodeId: string, ancestors: readonly string[] = []): Promise<boolean> {
+    for (const id of ancestors) {
+        const control = [...root.querySelectorAll<HTMLButtonElement>('[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<void>((resolve) => setTimeout(resolve, 0));
+        }
+    }
+    const row = [...root.querySelectorAll<HTMLElement>('[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;
+}