@adecore/agents-react 0.20.0 → 0.21.0

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

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { Circle, CircleCheck, CircleDot, CircleMinus, CircleX } from 'lucide-react';
+import { Icon, Meter, Pill, Spinner } from '@adecore/ui';
+import { formatNumber, formatPercent } from '@adecore/ui/format';
+import { UiHeadContext } from '../render-context.js';
+import { uiNodeLabel } from '../node-text.js';
+import { UI_TONE_ICONS, UI_TONE_PILL, UI_TONE_SURFACE, UI_TONE_TEXT } from '../tones.js';
+const STEP_ICONS = {
+    done: CircleCheck,
+    pending: Circle,
+    failed: CircleX,
+    skipped: CircleMinus
+};
+const STEP_TONES = {
+    done: 'text-status-idle',
+    running: 'text-accent',
+    pending: 'text-text-faint',
+    failed: 'text-status-error',
+    skipped: 'text-text-faint'
+};
+/* Whether the block still changes: while it streams, or while it reads live data. Only then does anything spin. */
+function isLive(context) {
+    return context.phase === 'streaming' || (context.live !== undefined && context.live !== null && context.live.state !== 'refused');
+}
+/* The head of the block when it is the first node, a subheading without an icon further down. */
+export function SummaryRenderer({ node, children }) {
+    const headId = useContext(UiHeadContext);
+    const head = headId === undefined || headId === node.id;
+    const { tone, badge } = node.props;
+    return (_jsxs("div", { className: "flex items-start gap-2 px-2", children: [head && tone !== undefined && _jsx(Icon, { icon: UI_TONE_ICONS[tone], size: 16, className: clsx('mt-0.75 shrink-0', UI_TONE_TEXT[tone]) }), _jsx("div", { className: "min-w-0 grow text-sm font-semibold text-balance text-text", children: children }), badge !== undefined && badge !== '' && (_jsx(Pill, { shape: "tag", tone: tone === undefined ? 'muted' : UI_TONE_PILL[tone], className: "shrink-0", children: badge }))] }));
+}
+export function CalloutRenderer({ node, children }) {
+    const { tone, title } = node.props;
+    return (_jsxs("div", { className: clsx('flex gap-2 rounded-md p-2 text-sm', UI_TONE_SURFACE[tone]), children: [_jsx(Icon, { icon: UI_TONE_ICONS[tone], size: 16, className: clsx('mt-0.75 shrink-0', UI_TONE_TEXT[tone]) }), _jsxs("div", { className: "min-w-0 grow", children: [title !== undefined && title !== '' && _jsx("div", { className: "font-medium text-text", children: title }), _jsx("div", { className: "text-text-muted", children: children })] })] }));
+}
+export function TagRenderer({ node, children }) {
+    const { tone } = node.props;
+    return (_jsx(Pill, { shape: "tag", size: "sm", tone: tone === undefined ? 'muted' : UI_TONE_PILL[tone], children: children }));
+}
+/* Without a value the progress is indeterminate; without a max the value is a percentage. */
+export function ProgressRenderer({ node, children, context }) {
+    const { t } = useTranslation('agent-chat');
+    const { value, max } = node.props;
+    const limit = max ?? 100;
+    const reading = value === undefined ? null : limit === 100 ? formatPercent(value) : t('blocks.progress.of', { value: formatNumber(value), max: formatNumber(limit) });
+    const label = uiNodeLabel(node);
+    return (_jsxs("div", { className: "flex flex-col gap-1 px-2", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-xs", children: [_jsx("span", { className: "min-w-0 text-text", children: children }), reading !== null ? (_jsx("span", { className: "shrink-0 text-text-muted tabular-nums", children: reading })) : (isLive(context) && _jsx(Spinner, { size: 12, className: "shrink-0 self-center text-text-faint" }))] }), _jsx(Meter, { value: value ?? null, max: limit, label: label === '' ? t('blocks.progress.label') : label, valueText: reading ?? undefined })] }));
+}
+export function StepsRenderer({ children }) {
+    return _jsx("ol", { className: "chat-ui-nodes flex flex-col px-2", children: children });
+}
+/* A running step spins only while the block is live; in a quiet block it is a still dot. */
+export function StepRenderer({ node, children, context }) {
+    const { t } = useTranslation('agent-chat');
+    const { state, detail } = node.props;
+    const quiet = state === 'pending' || state === 'skipped';
+    return (_jsxs("li", { className: "flex min-h-7 items-center gap-2 text-sm", children: [_jsx("span", { className: clsx('grid size-4 shrink-0 place-items-center', STEP_TONES[state]), children: state === 'running' ? (isLive(context) ? (_jsx(Spinner, { size: 14 })) : (_jsx(Icon, { icon: CircleDot, size: 14 }))) : (_jsx(Icon, { icon: STEP_ICONS[state], size: 14 })) }), _jsx("span", { className: "sr-only", children: t(`blocks.step.${state}`) }), _jsx("span", { className: clsx('min-w-0 grow', quiet ? 'text-text-faint' : 'text-text'), children: children }), detail !== undefined && detail !== '' && _jsx("span", { className: "shrink-0 text-xs text-text-faint tabular-nums", children: detail })] }));
+}

package/dist/chat/ui/intelligent-ui/reply-parts.d.ts

@@ -0,0 +1,9 @@
+import type { UiBlock } from '@adecore/intelligent-ui';
+export type UiReplyPart = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'ui';
+    block: UiBlock;
+};
+export declare function uiReplyParts(text: string, blocks: readonly UiBlock[], streaming?: boolean): UiReplyPart[];

package/dist/chat/ui/intelligent-ui/reply-parts.js

@@ -0,0 +1,18 @@
+export function uiReplyParts(text, blocks, streaming = false) {
+    const parts = [];
+    let position = 0;
+    for (const block of [...blocks].sort((left, right) => left.start - right.start)) {
+        if (!Number.isInteger(block.start) || !Number.isInteger(block.end) || block.start < position || block.end < block.start || block.end > text.length) {
+            continue;
+        }
+        if (block.start > position) {
+            parts.push({ kind: 'text', text: text.slice(position, block.start) });
+        }
+        parts.push({ kind: 'ui', block });
+        position = streaming && !block.complete ? text.length : block.end;
+    }
+    if (position < text.length) {
+        parts.push({ kind: 'text', text: text.slice(position) });
+    }
+    return parts;
+}

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

@@ -0,0 +1,31 @@
+import type { UiProps, UiViewNode } from '@adecore/intelligent-ui';
+export type UiColumnKind = NonNullable<UiProps<'Column'>['as']>;
+export interface UiTableColumn {
+    key: string;
+    title: string;
+    unit?: string;
+    as: UiColumnKind;
+}
+export type UiTableCell = {
+    kind: 'empty';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'number';
+    as: 'number' | 'bytes' | 'duration';
+    value: number;
+} | {
+    kind: 'date';
+    at: number;
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'tag';
+    text: string;
+};
+export declare const UI_TABLE_ROWS = 50;
+export declare function isNumericColumn(column: UiTableColumn): boolean;
+export declare function uiTableColumns(node: UiViewNode<UiProps<'Table'>>): UiTableColumn[];
+export declare function uiTableCell(value: unknown, column: UiTableColumn): UiTableCell;

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

@@ -0,0 +1,79 @@
+import { uiChildrenOf } from './node-text.js';
+/* Rows shown before a person asks for all of them. */
+export const UI_TABLE_ROWS = 50;
+/* Columns a table without Column children takes from its rows. */
+const DERIVED_COLUMNS = 8;
+const NUMERIC_KINDS = new Set(['number', 'bytes', 'duration']);
+export function isNumericColumn(column) {
+    return NUMERIC_KINDS.has(column.as);
+}
+/*
+ * The columns a table can draw: its Column children whose key some row has, each key once. A table
+ * without columns takes the keys of its rows, as numbers when every value there is one. Empty when
+ * nothing is usable, which draws the fallback.
+ */
+export function uiTableColumns(node) {
+    const rows = node.props.rows;
+    const present = (key) => rows.some((row) => Object.hasOwn(row, key));
+    const declared = uiChildrenOf(node, 'Column');
+    if (declared.length > 0) {
+        const seen = new Set();
+        return declared.flatMap(({ props }) => {
+            if (seen.has(props.key) || (rows.length > 0 && !present(props.key))) {
+                return [];
+            }
+            seen.add(props.key);
+            return [{ key: props.key, title: props.title ?? props.key, unit: props.unit, as: props.as ?? 'text' }];
+        });
+    }
+    const keys = [];
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!keys.includes(key) && keys.length < DERIVED_COLUMNS) {
+                keys.push(key);
+            }
+        }
+    }
+    return keys.map((key) => {
+        const values = rows.map((row) => row[key]).filter((value) => value !== undefined && value !== null);
+        const numeric = values.length > 0 && values.every((value) => typeof value === 'number' && Number.isFinite(value));
+        return { key, title: key, as: numeric ? 'number' : 'text' };
+    });
+}
+function textOf(value) {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function numberOf(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/* A duration is in milliseconds and a date is milliseconds since the epoch or an ISO string; anything else reads as text. */
+export function uiTableCell(value, column) {
+    if (value === undefined || value === null || value === '') {
+        return { kind: 'empty' };
+    }
+    switch (column.as) {
+        case 'number':
+        case 'bytes':
+        case 'duration': {
+            const number = numberOf(value);
+            return number === null ? { kind: 'text', text: textOf(value) } : { kind: 'number', as: column.as, value: number };
+        }
+        case 'date': {
+            const at = typeof value === 'number' ? value : typeof value === 'string' ? Date.parse(value) : Number.NaN;
+            return Number.isFinite(at) ? { kind: 'date', at } : { kind: 'text', text: textOf(value) };
+        }
+        case 'file':
+            return typeof value === 'string' ? { kind: 'file', path: value } : { kind: 'text', text: textOf(value) };
+        case 'tag':
+            return { kind: 'tag', text: textOf(value) };
+        case 'text':
+            return { kind: 'text', text: textOf(value) };
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type LucideIcon } from 'lucide-react';
+import type { UiTone } from '@adecore/intelligent-ui';
+import type { PillProps } from '@adecore/ui';
+export declare const UI_TONE_ICONS: Readonly<Record<UiTone, LucideIcon>>;
+export declare const UI_TONE_TEXT: Readonly<Record<UiTone, string>>;
+export declare const UI_TONE_SURFACE: Readonly<Record<UiTone, string>>;
+export declare const UI_TONE_PILL: Readonly<Record<UiTone, NonNullable<PillProps['tone']>>>;

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

@@ -0,0 +1,31 @@
+import { CircleCheck, Info, MessageCircle, OctagonAlert, TriangleAlert } from 'lucide-react';
+/* Every tone has an icon of its own, so color is never the only thing that tells two apart. */
+export const UI_TONE_ICONS = {
+    neutral: MessageCircle,
+    info: Info,
+    success: CircleCheck,
+    warning: TriangleAlert,
+    danger: OctagonAlert
+};
+export const UI_TONE_TEXT = {
+    neutral: 'text-text-muted',
+    info: 'text-status-running',
+    success: 'text-positive',
+    warning: 'text-status-needs-you',
+    danger: 'text-status-error'
+};
+/* The tone mixed over the ground, for a surface such as a callout. */
+export const UI_TONE_SURFACE = {
+    neutral: 'bg-text/7',
+    info: 'bg-status-running/10',
+    success: 'bg-positive/10',
+    warning: 'bg-status-needs-you/12',
+    danger: 'bg-status-error/10'
+};
+export const UI_TONE_PILL = {
+    neutral: 'muted',
+    info: 'accent',
+    success: 'idle',
+    warning: 'needsYou',
+    danger: 'error'
+};

package/dist/chat/ui/intelligent-ui/use-later.d.ts

@@ -0,0 +1 @@
+export declare function useLater(on: boolean, ms: number): boolean;

package/dist/chat/ui/intelligent-ui/use-later.js

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react';
+/* True once `on` has held for `ms`, for a spinner that only shows when waiting takes long. */
+export function useLater(on, ms) {
+    const [late, setLate] = useState(false);
+    useEffect(() => {
+        if (!on) {
+            return;
+        }
+        const timer = setTimeout(() => setLate(true), ms);
+        return () => {
+            clearTimeout(timer);
+            setLate(false);
+        };
+    }, [on, ms]);
+    return on && late;
+}

package/dist/chat/ui/intelligent-ui/use-ui-links.d.ts

@@ -0,0 +1,9 @@
+import type { ChatUiQueryState } from '@adecore/agent-contracts';
+import { type UiLinkTarget } from '@adecore/intelligent-ui/links';
+import { type UiBlock, UiState } from '@adecore/intelligent-ui';
+import type { UiRenderContext } from './render-context.js';
+export declare function useUiLinks(block: UiBlock, state: UiState, context: UiRenderContext, reads: Readonly<Record<string, string>>, frozen?: ChatUiQueryState['blocks'][string]): {
+    link: ((target: UiLinkTarget) => import("./render-context.js").UiLink) | undefined;
+    openLink: ((target: UiLinkTarget) => void) | undefined;
+    openUrl: ((url: string) => void) | undefined;
+};

package/dist/chat/ui/intelligent-ui/use-ui-links.js

@@ -0,0 +1,107 @@
+import { useEffect, useState } from 'react';
+import { uiLinkTargets } from '@adecore/intelligent-ui/links';
+import { uiInputValues, UiState } from '@adecore/intelligent-ui';
+import { chatHost } from '../../../host.js';
+export function useUiLinks(block, state, context, reads, frozen) {
+    const [checked, setChecked] = useState({});
+    const host = chatHost().intelligentUi;
+    const values = uiInputValues(block, state);
+    const scope = state.scope();
+    const queryValues = Object.fromEntries(Object.keys(block.queries)
+        .filter((name) => Object.hasOwn(scope, name))
+        .map((name) => [name, scope[name]]));
+    let targets = {};
+    try {
+        if (block.complete) {
+            targets = uiLinkTargets(block, values, queryValues);
+        }
+    }
+    catch { }
+    const signature = JSON.stringify(targets);
+    const input = JSON.stringify(values);
+    const tickets = JSON.stringify(reads);
+    const link = host?.link;
+    useEffect(() => {
+        if (!link || !block.revision || context.phase !== 'final') {
+            return;
+        }
+        let stopped = false;
+        const validate = async () => {
+            for (const [nodeId, target] of Object.entries(JSON.parse(signature)).slice(0, 64)) {
+                try {
+                    const reading = await link(context.scopeId, {
+                        chatId: context.chatId,
+                        itemId: context.itemId,
+                        blockId: block.id,
+                        revision: block.revision,
+                        nodeId,
+                        values: JSON.parse(input),
+                        reads: JSON.parse(tickets)
+                    });
+                    if (stopped) {
+                        return;
+                    }
+                    setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading } }));
+                }
+                catch {
+                    if (stopped) {
+                        return;
+                    }
+                    setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading: { state: 'plain' } } }));
+                }
+            }
+        };
+        void validate();
+        return () => {
+            stopped = true;
+        };
+    }, [block.id, block.revision, context.scopeId, context.chatId, context.itemId, context.phase, signature, input, tickets, link]);
+    const idOf = (target) => Object.entries(targets).find(([, entry]) => JSON.stringify(entry) === JSON.stringify(target))?.[0];
+    const resolution = (target) => {
+        const id = idOf(target);
+        if (id === undefined) {
+            return { state: 'plain' };
+        }
+        if (checked[id]?.target === JSON.stringify(target)) {
+            return checked[id].reading;
+        }
+        if (input === JSON.stringify(uiInputValues(block, new UiState(block))) && frozen && frozen.revision === block.revision) {
+            const firstQueries = Object.fromEntries(Object.entries(frozen.readings)
+                .filter(([, reading]) => reading.state === 'fresh')
+                .map(([name, reading]) => [name, reading.value]));
+            if (JSON.stringify(queryValues) === JSON.stringify(firstQueries)) {
+                return frozen.links?.[id] ?? { state: 'plain' };
+            }
+        }
+        return { state: 'plain' };
+    };
+    const open = (target) => {
+        const nodeId = idOf(target);
+        if (!nodeId || !link || !block.revision) {
+            return;
+        }
+        void link(context.scopeId, {
+            chatId: context.chatId,
+            itemId: context.itemId,
+            blockId: block.id,
+            revision: block.revision,
+            nodeId,
+            values,
+            reads: { ...reads }
+        })
+            .then((reading) => {
+            setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading } }));
+            if (reading.state === 'chip' && reading.target) {
+                host?.openLink?.(context.scopeId, reading);
+            }
+        })
+            .catch(() => {
+            setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading: { state: 'plain' } } }));
+        });
+    };
+    return {
+        link: link ? resolution : context.link,
+        openLink: link && host?.openLink ? open : context.openLink,
+        openUrl: host?.openUrl ? (url) => host.openUrl(context.scopeId, url) : context.openUrl
+    };
+}

package/dist/chat/ui/intelligent-ui/use-ui-queries.d.ts

@@ -0,0 +1,20 @@
+import type { ChatUiQueryReading, ChatUiQueryState } from '@adecore/agent-contracts';
+import { UiState, type UiBlock, type UiViewNode } from '@adecore/intelligent-ui';
+import type { UiLiveValue, UiLiveStatus, UiRenderContext } from './render-context.js';
+export declare function useUiQueries(block: UiBlock, state: UiState, context: UiRenderContext, element: HTMLDivElement | null, frozen?: ChatUiQueryState['blocks'][string]): {
+    live: UiLiveStatus | undefined;
+    reads: Record<string, string>;
+    reading: boolean;
+    ready: boolean;
+    readsFor: (values: Readonly<Record<string, unknown>>) => Record<string, string> | null;
+    currentReadings: {
+        [k: string]: {
+            state: "failed" | "fresh" | "refused";
+            value?: unknown;
+            readId?: string | undefined;
+            readAt: number;
+            reason?: string | undefined;
+        };
+    };
+};
+export declare function useUiLiveValues(block: UiBlock, nodes: readonly UiViewNode[], readings: Readonly<Record<string, ChatUiQueryReading>>): ((id: string, prop: string, path?: readonly [number, string]) => UiLiveValue | undefined) | undefined;

package/dist/chat/ui/intelligent-ui/use-ui-queries.js

@@ -0,0 +1,259 @@
+import { useEffect, useRef, useState } from 'react';
+import { uiInputValues, UI_CATALOG_VERSION, UiState } from '@adecore/intelligent-ui';
+import { chatHost } from '../../../host.js';
+function documentVisible() {
+    return document.visibilityState !== 'hidden';
+}
+export function useUiQueries(block, state, context, element, frozen) {
+    const [readings, setReadings] = useState({});
+    const [busyInput, setBusyInput] = useState(null);
+    const lastReadAt = useRef({ identity: '', at: 0 });
+    const names = Object.keys(block.queries);
+    const inputs = JSON.stringify(uiInputValues(block, state));
+    const identity = JSON.stringify([context.scopeId, context.chatId, context.itemId, block.id, block.revision]);
+    const inputKey = JSON.stringify([identity, inputs]);
+    const reading = busyInput === inputKey;
+    const defaultInputs = JSON.stringify(uiInputValues(block, new UiState(block)));
+    const initial = frozen && frozen.revision === block.revision ? frozen.readings : {};
+    const successfulFor = (name, signature) => {
+        const local = readings[name];
+        if (local?.identity === identity && local.successful?.inputs === signature) {
+            return local.successful.reading;
+        }
+        return signature === defaultInputs && initial[name]?.state === 'fresh' ? initial[name] : undefined;
+    };
+    const readsFor = (values) => {
+        const signature = JSON.stringify(values);
+        const reads = {};
+        for (const name of names) {
+            const local = readings[name];
+            const successful = successfulFor(name, signature);
+            if (!successful?.readId || (local?.identity === identity && local.reading.state === 'refused')) {
+                return null;
+            }
+            reads[name] = successful.readId;
+        }
+        return reads;
+    };
+    const reads = readsFor(JSON.parse(inputs));
+    const ready = reads !== null;
+    const query = chatHost().intelligentUi?.query;
+    const subscribe = chatHost().intelligentUi?.subscribe;
+    useEffect(() => {
+        const scope = state.scope();
+        for (const name of names) {
+            const successful = successfulFor(name, inputs);
+            if (successful && JSON.stringify(scope[name]) !== JSON.stringify(successful.value)) {
+                state.setQuery(name, successful.value, block);
+            }
+        }
+    });
+    useEffect(() => {
+        if (!query ||
+            !element ||
+            !block.complete ||
+            block.catalogVersion !== UI_CATALOG_VERSION ||
+            !block.revision ||
+            !Object.keys(block.queries).length ||
+            context.phase !== 'final') {
+            return;
+        }
+        let stopped = false;
+        let visible = typeof IntersectionObserver === 'undefined';
+        let busy = false;
+        let timer = null;
+        const refresh = async () => {
+            if (stopped || !visible || !documentVisible() || busy) {
+                return;
+            }
+            const wait = lastReadAt.current.identity === identity ? 10_000 - (Date.now() - lastReadAt.current.at) : 0;
+            if (wait > 0) {
+                if (timer === null) {
+                    if (!visible || !documentVisible()) {
+                        return;
+                    }
+                    timer = setTimeout(() => {
+                        timer = null;
+                        void refresh();
+                    }, wait);
+                }
+                return;
+            }
+            busy = true;
+            lastReadAt.current = { identity, at: Date.now() };
+            setBusyInput(inputKey);
+            for (const name of Object.keys(block.queries).slice(0, 8)) {
+                if (!visible || !documentVisible()) {
+                    break;
+                }
+                try {
+                    const reading = await query(context.scopeId, {
+                        chatId: context.chatId,
+                        itemId: context.itemId,
+                        blockId: block.id,
+                        revision: block.revision,
+                        query: name,
+                        values: JSON.parse(inputs)
+                    });
+                    if (stopped) {
+                        return;
+                    }
+                    if (reading.state === 'fresh') {
+                        state.setQuery(name, reading.value, block);
+                    }
+                    setReadings((previous) => ({
+                        ...previous,
+                        [name]: {
+                            identity,
+                            reading,
+                            successful: reading.state === 'fresh' ? { inputs, reading } : previous[name]?.identity === identity ? previous[name].successful : undefined
+                        }
+                    }));
+                }
+                catch (error) {
+                    if (stopped) {
+                        return;
+                    }
+                    setReadings((previous) => ({
+                        ...previous,
+                        [name]: {
+                            identity,
+                            reading: { state: 'failed', readAt: Date.now(), reason: error instanceof Error ? error.message : 'This query could not be read.' },
+                            successful: previous[name]?.identity === identity ? previous[name].successful : undefined
+                        }
+                    }));
+                }
+            }
+            busy = false;
+            if (stopped) {
+                return;
+            }
+            setBusyInput(null);
+            timer = setTimeout(() => {
+                timer = null;
+                void refresh();
+            }, 10_000);
+        };
+        const observer = typeof IntersectionObserver === 'undefined'
+            ? null
+            : new IntersectionObserver((entries) => {
+                visible = entries.some((entry) => entry.isIntersecting);
+                if (visible) {
+                    void refresh();
+                }
+                else if (timer !== null) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            });
+        if (element) {
+            observer?.observe(element);
+        }
+        const focus = () => {
+            void refresh();
+        };
+        document.addEventListener('visibilitychange', focus);
+        const unsubscribe = subscribe?.(context.scopeId, context.chatId, focus);
+        void refresh();
+        return () => {
+            stopped = true;
+            observer?.disconnect();
+            unsubscribe?.();
+            document.removeEventListener('visibilitychange', focus);
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+        };
+    }, [block, state, context.scopeId, context.chatId, context.itemId, context.phase, inputs, query, subscribe, element, identity, inputKey]);
+    const currentReadings = Object.fromEntries(names.flatMap((name) => {
+        const local = readings[name];
+        const reading = local?.identity === identity ? local.reading : initial[name];
+        return reading ? [[name, reading]] : [];
+    }));
+    const failed = Object.entries(currentReadings).find(([, value]) => value.state !== 'fresh');
+    const live = names.length
+        ? {
+            state: reading || (!ready && !failed) ? 'reading' : (failed?.[1].state ?? 'fresh'),
+            sources: names.map((name) => block.queries[name].source),
+            readAt: Object.values(currentReadings)
+                .filter((reading) => reading.state === 'fresh')
+                .reduce((at, value) => (at === null ? value.readAt : Math.min(at, value.readAt)), null),
+            source: failed ? block.queries[failed[0]]?.source : undefined,
+            reason: failed?.[1].reason
+        }
+        : undefined;
+    return { live, reads: reads ?? {}, reading, ready, readsFor, currentReadings };
+}
+export function useUiLiveValues(block, nodes, readings) {
+    const [committed, setCommitted] = useState({
+        token: '',
+        values: new Map(),
+        previous: new Map()
+    });
+    const dependencies = new Map();
+    const names = new Set(Object.keys(block.queries));
+    const references = (value, into) => {
+        if (!value || typeof value !== 'object') {
+            return;
+        }
+        const expression = value;
+        if (expression.kind === 'reference' && names.has(String(expression.name))) {
+            into.add(String(expression.name));
+        }
+        for (const child of Object.values(expression)) {
+            if (Array.isArray(child)) {
+                child.forEach((item) => references(item, into));
+            }
+            else if (typeof child === 'object') {
+                references(child, into);
+            }
+        }
+    };
+    const written = (nodes, inherited = new Set()) => {
+        for (const node of nodes) {
+            const related = new Set(inherited);
+            references(node.expressions, related);
+            dependencies.set(node.id, related);
+            written(node.children, node.type === 'Each' ? related : inherited);
+        }
+    };
+    written(block.nodes);
+    const values = new Map();
+    const sources = new Map();
+    const collect = (nodes) => {
+        for (const node of nodes) {
+            const related = dependencies.get(node.sourceId ?? node.id);
+            if (related?.size && !node.error) {
+                values.set(node.id, node.props);
+                sources.set(node.id, related);
+            }
+            collect(node.children);
+        }
+    };
+    collect(nodes);
+    const token = JSON.stringify([block.revision, Object.entries(readings).map(([name, reading]) => [name, reading.state, reading.readId, reading.readAt])]);
+    const previous = committed.token === token ? committed.previous : committed.values;
+    if (committed.token !== token) {
+        setCommitted({ token, values, previous });
+    }
+    if (!names.size) {
+        return undefined;
+    }
+    return (id, prop, path) => {
+        const related = sources.get(id);
+        if (!related) {
+            return undefined;
+        }
+        const get = (props) => {
+            const value = props?.[prop];
+            return path && Array.isArray(value) ? value[path[0]]?.[path[1]] : value;
+        };
+        const before = get(previous.get(id));
+        const value = get(values.get(id));
+        return {
+            previous: before,
+            changed: before !== undefined && JSON.stringify(before) !== JSON.stringify(value),
+            stale: [...related].some((name) => readings[name]?.state === 'failed' || readings[name]?.state === 'refused')
+        };
+    };
+}