@hachej/boring-ui-kit 0.4.25 → 0.4.27

package/dist/chat-react-session.js

@@ -0,0 +1,367 @@
+'use client';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { derive, isFileBlock, object, queuedMessages, waitingForAnswer as waitsForAnswer } from './chat-view.js';
+import { appendToDraft, displayName, kindMentionDraft, looksLikeMarkdown, mentionKind, mentionToken, pieces, prependToDraft, withoutKindMentions, writeKindMentionDraft } from './chat-text.js';
+/** Headless session over the public native controller snapshot/commands. Borrows it; cleanup only aborts this hook's uploads. */
+export function useChatSession(options) {
+    const { controller, activeController: active, mode, presentation, actions, renderEntry, hideLine, renderTool: catchAll, toolRenderers, groupTool, subagent, onOpenImage, onFiles, mentions, slash, attachments, model, effort, artifacts, afterSend, feedback, onOpenFile, onPickFiles, commandMentions, onFocus, labels } = options;
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const [error, setError] = useState(null);
+    const [uploading, setUploading] = useState(0);
+    const [picked, setPicked] = useState([]);
+    const [pending, setPending] = useState([]);
+    const [changing, setChanging] = useState(null);
+    const [changeError, setChangeError] = useState(null);
+    const [optimistic, setOptimistic] = useState({});
+    const uploadIds = useRef(0);
+    const uploads = useRef(new Set()), mounted = useRef(false);
+    const current = () => mounted.current && active.current === controller && !controller.getSnapshot().disposed;
+    // The latest text, for a connection failure that lands after the labels changed.
+    const latestLabels = useRef(labels);
+    useLayoutEffect(() => { latestLabels.current = labels; });
+    useEffect(() => {
+        mounted.current = true;
+        const live = uploads.current;
+        // A controller disposed before mount throws synchronously; the chat then renders its disposed state.
+        if (!controller.getSnapshot().disposed)
+            void controller.connect().catch(cause => {
+                if (mounted.current && active.current === controller && !controller.getSnapshot().disposed)
+                    setError(cause instanceof Error ? cause.message : latestLabels.current.connectionFailed);
+            });
+        return () => { mounted.current = false; for (const upload of live)
+            upload.abort(); live.clear(); };
+    }, [controller, active]);
+    const natural = presentation === 'natural';
+    // A tool's own renderer comes first; `renderTool` stays the catch-all.
+    const renderTool = useMemo(() => toolRenderers ? (call, result) => (Object.hasOwn(toolRenderers, call.name) ? toolRenderers[call.name]?.(call, result) : undefined) ?? catchAll?.(call, result) : catchAll, [toolRenderers, catchAll]);
+    const developer = mode === 'developer' && !natural;
+    // Only the recogniser takes part in deriving rows; which card is open changes without rebuilding them.
+    const recognise = artifacts?.recognise, detect = artifacts?.detect;
+    const artifactDetect = useMemo(() => recognise ? { recognise, detect } : undefined, [recognise, detect]);
+    const derived = useMemo(() => derive(state.view, { mode, presentation, hideLine, renderEntry, renderTool, groupTool, artifacts: artifactDetect, subagent }), [state.view, mode, presentation, hideLine, renderEntry, renderTool, groupTool, artifactDetect, subagent]);
+    const queued = useMemo(() => queuedMessages(state.view), [state.view]);
+    const { run } = derived;
+    const earlier = useMemo(() => {
+        if (!state.view || !('entries' in state.history))
+            return [];
+        const activeIds = new Set(state.view.entries.map(entry => entry.id));
+        const entries = state.history.entries.filter(entry => !activeIds.has(entry.id));
+        return derive({ ...state.view, entries, docs: {} }, { mode, presentation, hideLine, renderEntry: undefined, renderTool: undefined, groupTool: undefined, artifacts: artifactDetect, subagent }).rows
+            .map(row => ({ ...row, key: `history:${row.key}`, historical: true }));
+    }, [state.view, state.history, mode, presentation, hideLine, artifactDetect, subagent]);
+    const rows = useMemo(() => [...earlier, ...derived.rows], [earlier, derived.rows]);
+    const files = useMemo(() => {
+        const found = new Map();
+        const open = onOpenFile ?? mentions?.open;
+        const add = (path) => {
+            if (mentionKind(path, mentions))
+                return;
+            const normalized = path.replace(/^\.\//, '');
+            const id = `file:${normalized}`;
+            if (!found.has(id))
+                found.set(id, { id, name: displayName(normalized), open: open ? () => open(normalized) : undefined });
+        };
+        for (const path of picked)
+            add(path);
+        for (const item of state.draft.attachments)
+            found.set(`draft:${item.id}`, { id: `draft:${item.id}`, name: item.name, open: onOpenImage ? () => onOpenImage(item.content) : undefined });
+        for (const row of derived.rows) {
+            if (row.type === 'user') {
+                const content = typeof row.message.content === 'string' ? [{ type: 'text', text: row.message.content }] : row.message.content;
+                for (const [index, part] of content.entries()) {
+                    if (part.type === 'text' && !isFileBlock(part.text))
+                        for (const piece of pieces(part.text, { mentions: true, skills: [] })) {
+                            if (piece.kind === 'mention' && piece.value)
+                                add(piece.value);
+                        }
+                    if (part.type === 'image') {
+                        const id = `image:${row.key}:${index}`;
+                        found.set(id, { id, name: labels.imageAttachment, open: onOpenImage ? () => onOpenImage(part) : undefined });
+                    }
+                }
+            }
+            if (row.type !== 'assistant')
+                continue;
+            for (const part of row.parts) {
+                if (part.kind === 'artifact' && part.artifact.state === 'ready' && part.artifact.path !== undefined) {
+                    const descriptor = part.artifact.descriptor, id = `file:${part.artifact.path.replace(/^\.\//, '')}`;
+                    found.set(id, { id, name: displayName(part.artifact.path), open: artifacts?.open ? () => artifacts.open?.(descriptor) : undefined });
+                }
+                if (!natural && part.kind === 'tool' && part.entry.result && !part.entry.result.isError && ['read', 'write', 'edit'].includes(part.entry.call.name)) {
+                    const path = part.entry.call.arguments['path'];
+                    if (typeof path === 'string')
+                        add(path);
+                }
+            }
+        }
+        return [...found.values()];
+    }, [derived.rows, natural, picked, state.draft.attachments, artifacts, onOpenFile, mentions, onOpenImage, labels.imageAttachment]);
+    const report = (cause) => { if (current())
+        setError(cause instanceof Error ? cause.message : labels.actionFailedShort); };
+    const act = (action) => {
+        setError(null);
+        try {
+            void action().catch(report);
+        }
+        catch (cause) {
+            report(cause);
+        }
+    };
+    // A send being confirmed does not block the next one: the controller empties the composer at once and queues the next message behind it.
+    // Only a submission whose outcome is unknown blocks, until it is checked or retried.
+    const unconfirmed = state.send.kind === 'unknown';
+    const connected = state.connection.kind === 'connected';
+    const sendBlocked = uploading > 0 || state.disposed || !connected || unconfirmed;
+    /** Puts a message back into the composer ahead of whatever is there now (nothing is dropped). */
+    const putBack = (text, images) => {
+        if (controller.getSnapshot().disposed)
+            return;
+        const draft = controller.getSnapshot().draft;
+        controller.setText(prependToDraft(draft.text, withoutKindMentions(text, mentions)));
+        if (images.length)
+            controller.setAttachments([...images, ...draft.attachments.filter(item => !images.some(image => image.id === item.id))]);
+    };
+    const working = Boolean(run);
+    const waitingForAnswer = waitsForAnswer(derived.rows);
+    const send = () => {
+        if (sendBlocked || !current())
+            return;
+        const attach = feedback && feedback.count > 0 ? feedback.attach : undefined;
+        if (attach) {
+            // The pending feedback goes with this message: the host attaches it to the text, then the native send reads the draft.
+            act(async () => {
+                // Like any send, the composer empties at once; the person's own text comes back if the feedback or the message is refused.
+                const typed = controller.getSnapshot().draft;
+                controller.setText('');
+                controller.setAttachments([]);
+                let attached;
+                try {
+                    attached = await attach(typed.text);
+                }
+                catch (cause) {
+                    putBack(typed.text, typed.attachments);
+                    throw cause;
+                }
+                if (attached.kind === 'refused') {
+                    putBack(typed.text, typed.attachments);
+                    throw new Error(attached.reason);
+                }
+                if (!current()) {
+                    putBack(typed.text, typed.attachments);
+                    return;
+                }
+                try {
+                    const submission = await controller.send('followUp', { text: attached.text, attachments: typed.attachments, restore: { text: withoutKindMentions(typed.text, mentions), attachments: typed.attachments } });
+                    if (submission)
+                        feedback?.sent();
+                }
+                catch (cause) {
+                    putBack(typed.text, typed.attachments);
+                    throw cause;
+                }
+            });
+            afterSend?.();
+            onFocus?.();
+            return;
+        }
+        const typed = controller.getSnapshot().draft;
+        const words = withoutKindMentions(typed.text, mentions);
+        if (words !== typed.text) {
+            controller.setText('');
+            controller.setAttachments([]);
+            act(async () => {
+                try {
+                    await controller.send('followUp', { text: typed.text, attachments: typed.attachments, restore: { text: words, attachments: typed.attachments } });
+                }
+                catch (cause) {
+                    putBack(words, typed.attachments);
+                    throw cause;
+                }
+            });
+        }
+        else
+            act(() => controller.send('followUp'));
+        afterSend?.();
+        onFocus?.();
+    };
+    // A queued message is taken back (withdrawn) before it is edited or steered; if Pi already placed it, that is reported and nothing is lost.
+    async function takeBack(item) {
+        if (!actions?.withdraw)
+            throw new Error(labels.queueLocked);
+        const outcome = await actions.withdraw(item.id);
+        if (outcome === 'already_placed' || outcome === 'settled')
+            throw new Error(labels.tooLate);
+    }
+    const queuedContent = (item) => {
+        const parts = Array.isArray(item.content) ? item.content : [];
+        const text = typeof item.content === 'string' ? item.content : parts.flatMap(part => part?.type === 'text' && typeof part.text === 'string' && !isFileBlock(part.text) ? [part.text] : []).join('\n');
+        const images = parts.flatMap((part, index) => part?.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string'
+            ? [{ id: `queued-${String(item.id)}-${index}`, name: `image-${index + 1}`, content: { type: 'image', data: part.data, mimeType: part.mimeType } }] : []);
+        return { text, images };
+    };
+    const queueActions = actions?.withdraw ? {
+        edit: async (item) => {
+            await takeBack(item);
+            const { text, images } = queuedContent(item), draft = controller.getSnapshot().draft;
+            controller.setText(prependToDraft(draft.text, text));
+            if (images.length)
+                controller.setAttachments([...draft.attachments, ...images]);
+            onFocus?.();
+        },
+        steer: async (item) => {
+            if (sendBlocked)
+                throw new Error(labels.waitToSteer);
+            await takeBack(item);
+            const { text, images } = queuedContent(item);
+            // Sent as explicit content, so the person's own draft is never touched; a refused steer comes back into the composer (the controller
+            // puts it back), an unknown one is held for checking.
+            try {
+                const submission = await controller.send('steer', { text, attachments: images });
+                if (!submission && current() && controller.getSnapshot().send.kind === 'blocked')
+                    setError(labels.steerRefused);
+            }
+            catch (cause) {
+                putBack(text, images);
+                if (current())
+                    setError(cause instanceof Error ? cause.message : labels.steerFailed);
+            }
+        },
+    } : undefined;
+    const addMentions = (paths) => {
+        const text = controller.getSnapshot().draft.text;
+        controller.setText(`${appendToDraft(text, paths.map(mentionToken).join(' '))} `);
+        setPicked(value => [...new Set([...value, ...paths])]);
+    };
+    /** Uploads files; `restore` (a pasted text) is what their pending cards undo: it abandons the upload and puts the text back. */
+    async function upload(files, paste) {
+        if (!files.length || !current())
+            return;
+        if (onPickFiles) {
+            onPickFiles(files);
+            return;
+        }
+        if (!onFiles && !attachments)
+            return;
+        const abort = new AbortController();
+        uploads.current.add(abort);
+        setUploading(value => value + 1);
+        const ids = files.map(() => `upload-${++uploadIds.current}`);
+        const settle = (failure) => setPending(items => failure === undefined ? items.filter(item => !ids.includes(item.id))
+            : items.map(item => ids.includes(item.id) ? { ...item, state: 'failed', error: failure } : item));
+        const cancel = paste && (() => { abort.abort(); setPending(items => items.filter(item => !ids.includes(item.id))); paste.restore(); });
+        setPending(items => [...items, ...files.map((file, index) => ({ id: ids[index], name: file.name, state: 'uploading',
+                ...(cancel && paste ? { cancel, restoreWhile: paste.after } : {}) }))]);
+        try {
+            let added = [];
+            let paths = [];
+            if (attachments) {
+                for (const result of await attachments.upload([...files], abort.signal)) {
+                    if (result.image)
+                        added = [...added, { id: `image-${Date.now()}-${++uploadIds.current}`, name: result.name, content: { type: 'image', data: result.image.data, mimeType: result.image.mimeType } }];
+                    else if (result.path)
+                        paths = [...paths, result.path];
+                }
+            }
+            else
+                added = await onFiles(files, { identity: state.identity, conversationId: state.conversationId, signal: abort.signal });
+            if (current() && !abort.signal.aborted) {
+                if (added.length)
+                    controller.setAttachments([...controller.getSnapshot().draft.attachments, ...added]);
+                if (paths.length)
+                    addMentions(paths);
+                settle();
+            }
+        }
+        catch (cause) {
+            if (!abort.signal.aborted) {
+                settle(cause instanceof Error ? cause.message : labels.uploadFailedShort);
+                if (!attachments)
+                    report(cause);
+            }
+        }
+        finally {
+            uploads.current.delete(abort);
+            if (current())
+                setUploading(value => value - 1);
+        }
+    }
+    /** A paste the composer took: saved as a file under `uploads/` (Send then references it). Cancelling puts the text back where it was pasted. */
+    const pasteText = (paste) => {
+        if (!attachments || !current())
+            return;
+        const at = new Date(), two = (value) => String(value).padStart(2, '0');
+        const stamp = `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())} ${two(at.getHours())}-${two(at.getMinutes())}-${two(at.getSeconds())}`;
+        const markdown = looksLikeMarkdown(paste.text);
+        const file = new File([paste.text], `${labels.pastedFileName(stamp)}${markdown ? '.md' : '.txt'}`, { type: markdown ? 'text/markdown' : 'text/plain' });
+        // The pasted text replaces its selection when the paste is accepted, so the draft shows what is left. Restoring inserts the text at
+        // the same place and deletes nothing: whatever was typed since stays.
+        const draft = kindMentionDraft(controller.getSnapshot().draft.text, mentions);
+        const start = Math.max(0, Math.min(paste.start, draft.text.length)), end = Math.min(Math.max(paste.end, start), draft.text.length);
+        const after = writeKindMentionDraft(`${draft.text.slice(0, start)}${draft.text.slice(end)}`, draft.tokens, slash?.skills?.map(skill => skill.name));
+        controller.setText(after);
+        const restore = () => {
+            if (!current())
+                return;
+            const now = kindMentionDraft(controller.getSnapshot().draft.text, mentions);
+            const at = Math.min(start, now.text.length);
+            controller.setText(writeKindMentionDraft(`${now.text.slice(0, at)}${paste.text}${now.text.slice(at)}`, now.tokens, slash?.skills?.map(skill => skill.name)));
+            onFocus?.();
+        };
+        void upload([file], { restore, after });
+    };
+    const agentDoc = object(state.view?.docs['pi.agent']);
+    const currentModel = object(agentDoc?.['model']);
+    const viewModel = typeof currentModel?.['provider'] === 'string' && typeof currentModel['modelId'] === 'string' ? { provider: currentModel['provider'], modelId: currentModel['modelId'] } : undefined;
+    const viewEffort = typeof agentDoc?.['thinkingLevel'] === 'string' ? agentDoc['thinkingLevel'] : undefined;
+    // Show the accepted choice until the watch delivers it, so the label does not flicker back.
+    useEffect(() => {
+        const same = optimistic.model && viewModel && optimistic.model.provider === viewModel.provider && optimistic.model.modelId === viewModel.modelId;
+        // eslint-disable-next-line react-hooks/set-state-in-effect -- drops the optimistic choice once the watch delivers it; runs only when it matches, so it settles
+        if (same || (optimistic.effort !== undefined && optimistic.effort === viewEffort))
+            setOptimistic(value => ({ ...(same ? {} : value.model ? { model: value.model } : {}), ...(optimistic.effort === viewEffort ? {} : value.effort ? { effort: value.effort } : {}) }));
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- viewModel is rebuilt every render; its provider and modelId are what it compares
+    }, [optimistic, viewModel?.provider, viewModel?.modelId, viewEffort]);
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- cleared text drops the picked mentions once, after commit; the updater keeps an empty list as is
+    useEffect(() => { if (!state.draft.text)
+        setPicked(value => value.length ? [] : value); }, [state.draft.text]);
+    async function change(kind, apply, accepted, rejected) {
+        if (changing || !current())
+            return;
+        setChanging(kind);
+        setChangeError(null);
+        try {
+            await apply();
+            if (current())
+                accepted();
+        }
+        catch (cause) {
+            if (current()) {
+                rejected();
+                setChangeError(cause instanceof Error && cause.message ? cause.message : labels.changeRefused);
+            }
+        }
+        finally {
+            if (current())
+                setChanging(null);
+        }
+    }
+    const activateMention = (command) => {
+        if (!current() || controller.getSnapshot().connection.kind !== 'connected')
+            return;
+        const catalog = commandMentions;
+        const selected = catalog?.commands.find(item => item.name === command.name && item.behavior === command.behavior);
+        if (catalog && selected)
+            act(async () => catalog.onActivate({ name: selected.name, behavior: selected.behavior }));
+    };
+    const empty = connected && !state.view?.entries.length && !rows.length;
+    const loading = (state.connection.kind === 'idle' || state.connection.kind === 'connecting') && !state.view;
+    return { state, derived, rows, queued, queueActions, working, waitingForAnswer, connected, sendBlocked, error, setError, report, act, current,
+        files, empty, loading, developer, natural, send, putBack, upload, pasteText, picked, pending, uploading, activateMention,
+        pickMention: (path) => setPicked(value => value.includes(path) ? value : [...value, path]),
+        dismissUpload: (id) => setPending(items => items.filter(item => item.id !== id)),
+        currentModel: optimistic.model ?? viewModel, currentEffort: optimistic.effort ?? viewEffort,
+        changing, changeError, dismissChangeError: () => setChangeError(null),
+        changeModel: (next) => change('model', () => model.change(next), () => setOptimistic(value => ({ ...value, model: next })), () => { }),
+        changeEffort: (next) => change('effort', () => effort.change(next), () => setOptimistic(value => ({ ...value, effort: next })), () => { }),
+    };
+}

package/dist/chat-react-transcript.d.ts

@@ -0,0 +1,39 @@
+import type { ChatHistoryState } from './native-chat.js';
+export interface ChatPaging {
+    readonly first?: number;
+    readonly more?: number;
+}
+export declare const PAGE_FIRST = 60, PAGE_MORE = 40, CHUNK = 20;
+/**
+ * Rows grouped into runs of at most `size` keys, kept stable across renders. Rows already placed never change run: rows revealed
+ * above form new runs (the run nearest the old top is the full one), rows added below fill the last run, then start new ones.
+ */
+export declare function chunkKeys(previous: readonly (readonly string[])[], keys: readonly string[], size?: number): string[][];
+/**
+ * The scroller measures every one of its items on each scroll event and frame (@shadcn/react 0.3.1), so a long transcript gives it
+ * runs of `CHUNK` rows instead of single rows: 500 messages are 25 measurements, not 500. A run keeps its element while rows are
+ * revealed above it, so the scroller's prepend anchor still holds; a run's array is reused while its rows are unchanged.
+ */
+export declare function useRowChunks<T extends {
+    readonly key: string;
+}>(rows: readonly T[], size?: number): readonly (readonly T[])[];
+/** One scroll root for current and archived rows. Native paging stays in the borrowed controller. */
+export declare function useTranscriptWindow(rows: readonly {
+    readonly key: string;
+}[], page?: number, more?: number, history?: {
+    readonly state: ChatHistoryState;
+    readonly connected: boolean;
+    readonly load: () => Promise<void>;
+}, automatic?: boolean): {
+    scrollRef: import("react").Dispatch<import("react").SetStateAction<HTMLDivElement | null>>;
+    hidden: number;
+    reveal: () => void;
+    revealTo: (key: string) => void;
+    sentinelRef: import("react").Dispatch<import("react").SetStateAction<HTMLDivElement | null>>;
+    loaded: number;
+    visible: <T>(items: readonly T[]) => readonly T[];
+    reset: () => void;
+};
+/** Compatibility spelling for headless consumers; presentation supplies the actual scroll owner. */
+export declare const useTranscript: typeof useTranscriptWindow;
+//# sourceMappingURL=chat-react-transcript.d.ts.map

package/dist/chat-react-transcript.js

@@ -0,0 +1,123 @@
+'use client';
+import { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+export const PAGE_FIRST = 60, PAGE_MORE = 40, CHUNK = 20;
+/**
+ * Rows grouped into runs of at most `size` keys, kept stable across renders. Rows already placed never change run: rows revealed
+ * above form new runs (the run nearest the old top is the full one), rows added below fill the last run, then start new ones.
+ */
+export function chunkKeys(previous, keys, size = CHUNK) {
+    const owner = new Map();
+    previous.forEach((run, index) => { for (const key of run)
+        owner.set(key, index); });
+    const known = keys.findIndex(key => owner.has(key));
+    const lead = known < 0 ? keys.length : known;
+    const runs = [];
+    for (let end = lead; end > 0; end -= size)
+        runs.unshift(keys.slice(Math.max(0, end - size), end));
+    let current = [], from;
+    for (const key of keys.slice(lead)) {
+        const placed = owner.get(key);
+        if (!current.length || (placed !== undefined ? placed !== from : current.length >= size)) {
+            current = [];
+            runs.push(current);
+            from = placed;
+        }
+        current.push(key);
+    }
+    return runs;
+}
+/**
+ * The scroller measures every one of its items on each scroll event and frame (@shadcn/react 0.3.1), so a long transcript gives it
+ * runs of `CHUNK` rows instead of single rows: 500 messages are 25 measurements, not 500. A run keeps its element while rows are
+ * revealed above it, so the scroller's prepend anchor still holds; a run's array is reused while its rows are unchanged.
+ */
+export function useRowChunks(rows, size = CHUNK) {
+    // A derived cache of the last runs, read and replaced inside the memo only: the same rows always give the same runs.
+    const previous = useRef({ keys: [], runs: new Map() });
+    return useMemo(() => {
+        const byKey = new Map(rows.map(row => [row.key, row]));
+        // eslint-disable-next-line react-hooks/refs -- reads the run cache to keep run boundaries and arrays stable; no setState, no render loop
+        const keys = chunkKeys(previous.current.keys, rows.map(row => row.key), size);
+        // eslint-disable-next-line react-hooks/refs -- the mapper reuses the cached array of an unchanged run (see above)
+        const runs = keys.map(run => {
+            const items = run.map(key => byKey.get(key));
+            const before = previous.current.runs.get(run[0]);
+            return before && before.length === items.length && before.every((item, index) => item === items[index]) ? before : items;
+        });
+        // eslint-disable-next-line react-hooks/refs -- stores the runs for the next rows; a cache write, not state, so it triggers no render
+        previous.current = { keys, runs: new Map(runs.map(run => [run[0].key, run])) };
+        return runs;
+    }, [rows, size]);
+}
+/** One scroll root for current and archived rows. Native paging stays in the borrowed controller. */
+export function useTranscriptWindow(rows, page = PAGE_FIRST, more = PAGE_MORE, history, automatic = true) {
+    if (!Number.isSafeInteger(page) || page < 1)
+        throw new TypeError('Chat displayLimit must be a positive integer');
+    if (!Number.isSafeInteger(more) || more < 1)
+        throw new TypeError('Chat paging.more must be a positive integer');
+    const [limit, setLimit] = useState(page);
+    const [sentinel, setSentinel] = useState(null);
+    const [loaded, setLoaded] = useState(0);
+    const pending = useRef(false);
+    const anchor = useRef(undefined);
+    const [scroller, setScroller] = useState(null);
+    const hidden = Math.max(0, rows.length - limit);
+    const historyState = history?.state, historyConnected = history?.connected, historyLoad = history?.load;
+    const reveal = useCallback(() => {
+        if (pending.current || anchor.current)
+            return;
+        const state = historyState;
+        if (hidden === 0 && (!historyConnected || !state || state.kind === 'disabled' || state.kind === 'loading' || state.kind === 'ready' && !state.hasMore))
+            return;
+        anchor.current = { length: rows.length, limit };
+        // A revealed page renders as a transition: React mounts it in small slices, so scrolling stays responsive meanwhile.
+        if (hidden > 0)
+            startTransition(() => setLimit(value => value + more));
+        else if (historyLoad) {
+            pending.current = true;
+            void Promise.resolve().then(historyLoad).catch(() => { anchor.current = undefined; }).finally(() => { pending.current = false; });
+        }
+    }, [hidden, historyState, historyConnected, historyLoad, rows.length, limit, more]);
+    useLayoutEffect(() => {
+        const saved = anchor.current;
+        if (!scroller || !saved || history?.state.kind === 'loading')
+            return;
+        const added = Math.max(0, rows.length - saved.length);
+        if (limit < saved.limit + added) {
+            startTransition(() => setLimit(saved.limit + added));
+            return;
+        }
+        anchor.current = undefined;
+        setLoaded(count => count + Math.max(0, Math.min(rows.length, limit) - Math.min(saved.length, saved.limit)));
+    }, [rows, limit, scroller, history?.state]);
+    // Automatic paging: the sentinel near the top, once the reader has been away from the top (so the mount, which starts at the
+    // top before the scroller settles at the end, loads nothing). A fast scroll lands on 0 before the sentinel is seen: the scroll
+    // listener and every new observer (after each page) check again, instead of the reader's distance at that one moment.
+    const near = useRef(false), away = useRef(false), revealNow = useRef(reveal);
+    useLayoutEffect(() => { revealNow.current = reveal; });
+    useEffect(() => {
+        if (!automatic || !scroller)
+            return;
+        const onScroll = () => { if (scroller.scrollTop > 8)
+            away.current = true; if (near.current && away.current)
+            revealNow.current(); };
+        scroller.addEventListener('scroll', onScroll, { passive: true });
+        return () => scroller.removeEventListener('scroll', onScroll);
+    }, [automatic, scroller]);
+    useEffect(() => {
+        if (!automatic || !scroller || !sentinel || typeof IntersectionObserver === 'undefined' || history?.state.kind === 'loading' || history?.state.kind === 'error')
+            return;
+        const observer = new IntersectionObserver(entries => {
+            near.current = entries.at(-1)?.isIntersecting ?? near.current;
+            if (near.current && (scroller.scrollHeight <= scroller.clientHeight || away.current))
+                reveal();
+        }, { root: scroller, rootMargin: '240px 0px 0px' });
+        observer.observe(sentinel);
+        return () => { observer.disconnect(); near.current = false; };
+    }, [automatic, scroller, sentinel, reveal, history?.state]);
+    const revealTo = (key) => { const index = rows.findIndex(row => row.key === key); if (index >= 0)
+        setLimit(value => Math.max(value, rows.length - index)); };
+    return { scrollRef: setScroller, hidden, reveal, revealTo, sentinelRef: setSentinel, loaded, visible: (items) => hidden ? items.slice(hidden) : items, reset: () => { anchor.current = undefined; setLimit(page); } };
+}
+/** Compatibility spelling for headless consumers; presentation supplies the actual scroll owner. */
+export const useTranscript = useTranscriptWindow;

package/dist/chat-react.d.ts

@@ -0,0 +1,62 @@
+import type { ChatController } from './native-chat.js';
+import type { ArtifactDescriptor, ArtifactDetect, PresentAcksHost } from './chat-view.js';
+export { useChatDraft } from './chat-react-draft.js';
+export { useControllerPerConversation } from './chat-react-controller.js';
+export type { ControllerPerConversationOptions, ConversationControllerState } from './chat-react-controller.js';
+export { chunkKeys, useRowChunks, useTranscript, useTranscriptWindow, PAGE_FIRST, PAGE_MORE, CHUNK } from './chat-react-transcript.js';
+export type { ChatPaging } from './chat-react-transcript.js';
+export { useChatPlacement, readChatPlacement, useRemoteChat } from './chat-react-remote.js';
+export type { ChatPlacement, RemoteChatState, RemoteChatHookOptions } from './chat-react-remote.js';
+export { useConversationsClient, useConversations } from './chat-react-conversations.js';
+export type { ConversationItem, ConversationsClient, ConversationsClientOptions } from './chat-react-conversations.js';
+import type { NotificationStore, RunNotificationOptions, RunNotificationSource } from './run-notifications.js';
+export { createNotificationStore, watchConversation } from './run-notifications.js';
+export type { AgentNotification, NewNotification, NotificationKind, NotificationStore, RunNotificationOptions, RunNotificationSource } from './run-notifications.js';
+/** The foreground adapter of watchConversation, with the same connected-only transition rules and borrowed lifecycle. */
+export declare function useRunNotifications(controller: RunNotificationSource, store: NotificationStore, options: RunNotificationOptions): void;
+/** Selects the authorized native view using the controller's own cached snapshot and subscription. Borrows its lifetime. */
+export declare function useChatView<T>(controller: ChatController | undefined, select: (view: ReturnType<ChatController['getSnapshot']>['view']) => T): T;
+export interface ArtifactSelection {
+    readonly descriptor: ArtifactDescriptor;
+    readonly follow: boolean;
+}
+export interface ArtifactShown {
+    readonly path: string;
+    readonly revision: string;
+    readonly hidden?: true;
+}
+export interface ArtifactFailed {
+    readonly path: string;
+    readonly revision: string;
+    readonly reason: string;
+}
+export interface ArtifactFollowOptions {
+    readonly controller: ChatController | undefined;
+    readonly conversationId?: string | undefined;
+    readonly detect?: ArtifactDetect | undefined;
+    readonly active: ArtifactSelection | null;
+    readonly onOpen: (selection: ArtifactSelection) => void;
+    readonly autoOpen?: boolean | undefined;
+    /** Host presentation guards are read when an effect or action considers opening, never during render. */
+    readonly unsaved?: (() => boolean) | undefined;
+    readonly narrow?: (() => boolean) | undefined;
+    readonly showing: (path: string) => boolean;
+    readonly openPresent: (path: string) => boolean;
+    readonly answer?: PresentAcksHost['answer'] | undefined;
+}
+/** One version/follow/auto-open and present-ack rule for every chat surface. Mount evidence must come from the viewer. */
+export declare function useArtifactFollow(options: ArtifactFollowOptions): {
+    versions: ArtifactDescriptor[];
+    turn: number;
+    known: ArtifactDescriptor[];
+    shown: ArtifactDescriptor | undefined;
+    open: (descriptor: ArtifactDescriptor) => void;
+    isOpen: (descriptor: ArtifactDescriptor) => boolean;
+    select: (version: ArtifactDescriptor | "latest") => void;
+    recordClosed: () => void;
+    onShown: (shown: ArtifactShown) => void;
+    onFailed: (failed: ArtifactFailed) => void;
+};
+export { useChatSession } from './chat-react-session.js';
+export type { ChatSession, ChatSessionOptions, ChatSessionLabels, ChatSessionFeedback, ConversationFile, ModelRef, PastedText, UploadResult, PendingUpload, FilesHandler, QueueActions } from './chat-react-session.js';
+//# sourceMappingURL=chat-react.d.ts.map