@hachej/boring-ui-kit 0.4.24 → 0.4.26

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

@@ -0,0 +1,25 @@
+export type ConversationControllerState<C> = {
+    readonly status: 'connecting';
+} | {
+    readonly status: 'offline';
+    readonly error: unknown;
+} | {
+    readonly status: 'ready';
+    readonly controller: C;
+};
+export interface ControllerPerConversationOptions<C extends {
+    readonly dispose: () => unknown;
+}> {
+    /** Stable selection identity, including source/owner and relevant options. Undefined acquires nothing. */
+    readonly key: unknown;
+    readonly create: () => C | Promise<C>;
+    readonly connect?: ((controller: C) => Promise<void>) | undefined;
+    /** Defaults to the concrete controller's dispose. Must release only resources created by this binding. */
+    readonly dispose?: ((controller: C) => unknown) | undefined;
+    readonly retryMs?: number | undefined;
+}
+/** Owns only the selected adapter, never its borrowed Harness/source. Late acquisitions are released, not published. */
+export declare function useControllerPerConversation<C extends {
+    readonly dispose: () => unknown;
+}>(options: ControllerPerConversationOptions<C>): ConversationControllerState<C>;
+//# sourceMappingURL=chat-react-controller.d.ts.map

package/dist/chat-react-controller.js

@@ -0,0 +1,72 @@
+'use client';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+/** Owns only the selected adapter, never its borrowed Harness/source. Late acquisitions are released, not published. */
+export function useControllerPerConversation(options) {
+    const { key, retryMs = 1000 } = options;
+    const binding = useMemo(() => ({ key }), [key, retryMs]);
+    const latest = useRef(options);
+    useLayoutEffect(() => { latest.current = options; });
+    const [stored, setStored] = useState();
+    useEffect(() => {
+        if (key === undefined)
+            return;
+        // Capture ownership callbacks for this selection; later renders must not redirect its teardown.
+        const { create, connect, dispose } = latest.current;
+        let off = false, owned, retiring;
+        let timer, wake;
+        const publish = (state) => { if (!off)
+            setStored({ binding, state }); };
+        const retire = () => {
+            if (retiring)
+                return retiring;
+            const controller = owned;
+            owned = undefined;
+            if (!controller)
+                return Promise.resolve();
+            retiring = Promise.resolve().then(() => dispose ? dispose(controller) : controller.dispose()).then(() => { });
+            return retiring;
+        };
+        void (async () => {
+            while (!off) {
+                try {
+                    owned = await create();
+                    if (off) {
+                        await retire();
+                        return;
+                    }
+                    await connect?.(owned);
+                    if (off) {
+                        await retire();
+                        return;
+                    }
+                    publish({ status: 'ready', controller: owned });
+                    return;
+                }
+                catch (error) {
+                    try {
+                        await retire();
+                    }
+                    catch (teardownError) {
+                        console.error('Chat controller teardown failed', teardownError);
+                    }
+                    retiring = undefined;
+                    if (off)
+                        return;
+                    publish({ status: 'offline', error });
+                    await new Promise(resolve => { wake = resolve; timer = setTimeout(resolve, retryMs); });
+                    wake = undefined;
+                    timer = undefined;
+                }
+            }
+        })();
+        return () => {
+            off = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            wake?.();
+            void retire().catch(error => console.error('Chat controller teardown failed', error));
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- binding owns the selection; callback identity alone must not reconnect
+    }, [binding, retryMs]);
+    return stored?.binding === binding ? stored.state : { status: 'connecting' };
+}

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

@@ -0,0 +1,40 @@
+export interface ConversationItem {
+    readonly id: string;
+    readonly title?: string | undefined;
+    readonly updatedAt?: number | string | Date | undefined;
+    readonly lastMessage?: string | null | undefined;
+    readonly archived?: boolean | undefined;
+}
+/** Headless list/actions; row menus and other presentation extensions stay with the registry. */
+export interface ConversationsClient {
+    readonly items: readonly ConversationItem[];
+    readonly activeId: string | undefined;
+    readonly reload: () => Promise<void>;
+    readonly onSelect: (id: string) => void;
+    readonly onNew: () => void;
+    readonly search: (query: string, options: {
+        readonly archived: boolean;
+    }, signal: AbortSignal) => Promise<readonly ConversationItem[]>;
+    readonly rename: (id: string, title: string) => Promise<void>;
+    readonly archive: (id: string, archived: boolean) => Promise<void>;
+    readonly remove: (id: string) => Promise<void>;
+    readonly fork: (atEntryId: string) => Promise<void>;
+}
+export interface ConversationsClientOptions {
+    readonly endpoint: string | URL | undefined;
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly activeId: string | undefined;
+    readonly onSelect: (id: string) => void;
+    readonly onChange?: (() => void | Promise<void>) | undefined;
+    readonly pollMs?: number;
+}
+/**
+ * The sessions list over the host's conversations handler (`createConversationsHandler` of `@hachej/boring-agent/conversations`, mounted at
+ * `endpoint`): the active list (polled every `pollMs` while mounted), server-side search with the Archived filter, New, rename, archive,
+ * delete and fork. New and fork select the conversation they made through `onSelect`. `onChange` runs after every change the person made
+ * (the host may reload what depends on the list). `fetch` is the host's authenticated fetch. Returns `undefined` until the first list arrives.
+ */
+export declare function useConversationsClient({ endpoint, fetch, activeId, onSelect, onChange, pollMs }: ConversationsClientOptions): ConversationsClient | undefined;
+/** Compatibility spelling retained for one release. */
+export declare const useConversations: typeof useConversationsClient;
+//# sourceMappingURL=chat-react-conversations.d.ts.map

package/dist/chat-react-conversations.js

@@ -0,0 +1,68 @@
+'use client';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+const item = (served) => ({ id: String(served.id), title: served.title ?? undefined, updatedAt: served.updatedAt, lastMessage: served.lastMessage, archived: served.archived });
+/**
+ * The sessions list over the host's conversations handler (`createConversationsHandler` of `@hachej/boring-agent/conversations`, mounted at
+ * `endpoint`): the active list (polled every `pollMs` while mounted), server-side search with the Archived filter, New, rename, archive,
+ * delete and fork. New and fork select the conversation they made through `onSelect`. `onChange` runs after every change the person made
+ * (the host may reload what depends on the list). `fetch` is the host's authenticated fetch. Returns `undefined` until the first list arrives.
+ */
+export function useConversationsClient({ endpoint, fetch, activeId, onSelect, onChange, pollMs = 4000 }) {
+    const [items, setItems] = useState();
+    const latest = useRef({ fetch, onSelect, onChange, activeId });
+    useLayoutEffect(() => { latest.current = { fetch, onSelect, onChange, activeId }; });
+    const base = endpoint === undefined ? undefined : String(endpoint);
+    const call = useCallback(async (params, body, signal) => {
+        if (base === undefined)
+            throw new Error('No conversations endpoint');
+        const url = new URL(base, globalThis.location?.href);
+        for (const [key, value] of Object.entries(params))
+            url.searchParams.set(key, value);
+        const init = body === undefined ? { ...(signal ? { signal } : {}) } : { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), ...(signal ? { signal } : {}) };
+        const response = await latest.current.fetch(new Request(url, init));
+        if (!response.ok)
+            throw new Error(`Conversations: ${response.status}`);
+        return await response.json();
+    }, [base]);
+    const reload = useCallback(async () => { const result = await call({}); setItems((result.conversations ?? []).map(item)); }, [call]);
+    // Another endpoint (another owner's list) starts empty; switching conversations only reloads.
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- a new endpoint clears the old owner's list once, after commit
+    useEffect(() => { setItems(undefined); }, [base]);
+    useEffect(() => {
+        if (base === undefined)
+            return;
+        let off = false;
+        const load = () => call({}).then(result => { if (!off)
+            setItems((result.conversations ?? []).map(item)); }).catch(() => { });
+        void load();
+        const timer = setInterval(load, pollMs);
+        return () => { off = true; clearInterval(timer); };
+    }, [base, call, pollMs, activeId]);
+    return useMemo(() => {
+        if (!items)
+            return undefined;
+        const changed = async () => { await reload().catch(() => { }); await latest.current.onChange?.(); };
+        const op = (name, body) => call({ op: name }, body);
+        return {
+            items, activeId, reload,
+            onSelect: (id) => latest.current.onSelect(id),
+            onNew: () => { void op('create', {}).then(async (result) => { await changed(); if (result.conversationId !== undefined)
+                latest.current.onSelect(String(result.conversationId)); }).catch(() => { }); },
+            search: async (query, { archived }, signal) => ((await call({ ...(query ? { q: query } : {}), ...(archived ? { archived: '1' } : {}) }, undefined, signal)).conversations ?? []).map(item),
+            rename: async (id, title) => { await op('rename', { conversationId: id, title }); await changed(); },
+            archive: async (id, archived) => { await op('archive', { conversationId: id, archived }); await changed(); },
+            remove: async (id) => { await op('delete', { conversationId: id }); await changed(); },
+            fork: async (at) => {
+                const from = latest.current.activeId;
+                if (from === undefined)
+                    return;
+                const { conversationId } = await op('fork', { conversationId: from, at });
+                await changed();
+                if (conversationId !== undefined)
+                    latest.current.onSelect(String(conversationId));
+            },
+        };
+    }, [items, activeId, call, reload]);
+}
+/** Compatibility spelling retained for one release. */
+export const useConversations = useConversationsClient;

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

@@ -0,0 +1,11 @@
+import type { ChatController } from './native-chat.js';
+/**
+ * Keeps the composer's half-typed message (the controller's draft) per conversation in localStorage, so it survives a reload and shows in
+ * every tab on the same conversation (the `storage` event). The draft is emptied when a message is sent, and a refused send puts the text back,
+ * which is written again. Without `key` nothing happens. Storage that is missing or throws only means the draft is not kept.
+ *
+ * On mount the conversation's saved draft replaces the composer's text; text already in the composer and not yet saved is written at once.
+ * On a change of `key` (same controller) the composer shows the new conversation's saved draft, or an empty one, so no text moves across.
+ */
+export declare function useChatDraft(controller: ChatController, key: string | undefined): void;
+//# sourceMappingURL=chat-react-draft.d.ts.map

package/dist/chat-react-draft.js

@@ -0,0 +1,91 @@
+'use client';
+import { useEffect, useRef } from 'react';
+const PREFIX = 'pi-chat:draft:';
+/** The stored draft: a string, `null` when the key is missing, `undefined` when storage is unavailable (missing, blocked or throwing). */
+function read(storageKey) {
+    try {
+        const storage = globalThis.localStorage;
+        return storage ? storage.getItem(storageKey) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function write(storageKey, text) {
+    try {
+        if (text)
+            globalThis.localStorage?.setItem(storageKey, text);
+        else
+            globalThis.localStorage?.removeItem(storageKey);
+    }
+    catch { /* the composer still holds the text */ }
+}
+/**
+ * Keeps the composer's half-typed message (the controller's draft) per conversation in localStorage, so it survives a reload and shows in
+ * every tab on the same conversation (the `storage` event). The draft is emptied when a message is sent, and a refused send puts the text back,
+ * which is written again. Without `key` nothing happens. Storage that is missing or throws only means the draft is not kept.
+ *
+ * On mount the conversation's saved draft replaces the composer's text; text already in the composer and not yet saved is written at once.
+ * On a change of `key` (same controller) the composer shows the new conversation's saved draft, or an empty one, so no text moves across.
+ */
+export function useChatDraft(controller, key) {
+    // The key the hook last loaded; a different key on a later run is a conversation switch, not a first mount.
+    const loaded = useRef(undefined);
+    useEffect(() => {
+        if (key === undefined || controller.getSnapshot().disposed)
+            return;
+        const storageKey = PREFIX + key;
+        const switched = loaded.current !== undefined && loaded.current !== key;
+        loaded.current = key;
+        const stored = read(storageKey);
+        const current = controller.getSnapshot().draft.text;
+        // The text last known to be in storage; a write happens only when the composer's text differs from it.
+        let saved;
+        if (stored) {
+            if (stored !== current)
+                controller.setText(stored);
+            saved = stored;
+        }
+        else if (switched) {
+            // The new conversation has no saved draft (or storage is unavailable): the old conversation's text must not stay.
+            if (current)
+                controller.setText('');
+            saved = '';
+        }
+        else {
+            saved = current;
+            if (stored === null && current)
+                write(storageKey, current);
+        }
+        const persist = () => {
+            if (controller.getSnapshot().disposed)
+                return;
+            const text = controller.getSnapshot().draft.text;
+            if (text === saved)
+                return;
+            saved = text;
+            write(storageKey, text);
+        };
+        const unsubscribe = controller.subscribe(persist);
+        // Another tab changed this conversation's draft (or cleared all storage: `key` is null). Adopting it does not write it back.
+        // Unavailable storage is not a missing draft: the composer keeps its text.
+        const onStorage = (event) => {
+            if (event.key !== null && event.key !== storageKey)
+                return;
+            if (controller.getSnapshot().disposed)
+                return;
+            const next = read(storageKey);
+            if (next === undefined)
+                return;
+            const text = next ?? '';
+            saved = text;
+            if (text !== controller.getSnapshot().draft.text)
+                controller.setText(text);
+        };
+        globalThis.addEventListener?.('storage', onStorage);
+        return () => {
+            unsubscribe();
+            globalThis.removeEventListener?.('storage', onStorage);
+        };
+    }, [controller, key]);
+}

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

@@ -0,0 +1,33 @@
+import type { ChatController, ChatIdentity, NativeChatController } from './native-chat.js';
+import type { RemoteChat, RemoteChatOptions } from './remote-chat.js';
+export type ChatPlacement = 'docked' | 'floating';
+/** Reports the placement of the chat showing `controller` while the caller is mounted. */
+export declare function useChatPlacement(controller: ChatController, placement: ChatPlacement): void;
+export declare function readChatPlacement(controller: ChatController | undefined): ChatPlacement | undefined;
+export type RemoteChatState = {
+    readonly status: 'connecting';
+    readonly conversationId: string | undefined;
+} | {
+    readonly status: 'offline';
+    readonly conversationId: string | undefined;
+    readonly error: string;
+} | {
+    readonly status: 'ready';
+    readonly conversationId: string;
+    readonly controller: NativeChatController;
+    readonly actions: Partial<Pick<RemoteChat, 'answer' | 'withdraw'>>;
+    readonly configure: RemoteChat['configure'];
+};
+export interface RemoteChatHookOptions {
+    readonly conversationId: string | undefined;
+    readonly endpoint: (conversationId: string) => string | URL;
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly identity: ChatIdentity | undefined;
+    /** Read at each submit; placement is merged alongside the host's unchanged screen context. Advisory, never authority. */
+    readonly requestContext?: () => Readonly<Record<string, unknown>> | undefined;
+    readonly transport?: RemoteChatOptions['transport'];
+    readonly webSocket?: RemoteChatOptions['webSocket'];
+}
+/** One owned native controller per selection; the remote transport itself reopens dropped streams. Failed acquisition retries each second. */
+export declare function useRemoteChat({ conversationId, endpoint, fetch, identity, requestContext, transport, webSocket }: RemoteChatHookOptions): RemoteChatState;
+//# sourceMappingURL=chat-react-remote.d.ts.map

package/dist/chat-react-remote.js

@@ -0,0 +1,72 @@
+'use client';
+import { useLayoutEffect, useMemo, useRef } from 'react';
+import { createNativeChatController } from './native-chat.js';
+import { createRemoteChat } from './remote-chat.js';
+import { useControllerPerConversation } from './chat-react-controller.js';
+// Keyed by controller (a page can hold several chats; floating or docking keeps the controller, PLACE-3). Each mounted presenter has its own
+// registration, so unmounting one never clears another's; the latest surviving registration wins.
+const placements = new WeakMap();
+/** Reports the placement of the chat showing `controller` while the caller is mounted. */
+export function useChatPlacement(controller, placement) {
+    useLayoutEffect(() => {
+        const entry = { placement };
+        const list = placements.get(controller) ?? [];
+        placements.set(controller, [...list, entry]);
+        return () => {
+            const rest = (placements.get(controller) ?? []).filter(item => item !== entry);
+            if (rest.length)
+                placements.set(controller, rest);
+            else
+                placements.delete(controller);
+        };
+    }, [controller, placement]);
+}
+export function readChatPlacement(controller) {
+    return controller ? placements.get(controller)?.at(-1)?.placement : undefined;
+}
+/** One owned native controller per selection; the remote transport itself reopens dropped streams. Failed acquisition retries each second. */
+export function useRemoteChat({ conversationId, endpoint, fetch, identity, requestContext, transport, webSocket }) {
+    const url = conversationId === undefined ? undefined : String(endpoint(conversationId));
+    const key = identity && conversationId !== undefined ? JSON.stringify([conversationId, url, identity.runtimeId, identity.scopeId, identity.principalId, transport]) : undefined;
+    const latest = useRef({ fetch, requestContext, webSocket });
+    useLayoutEffect(() => { latest.current = { fetch, requestContext, webSocket }; });
+    // Transport ownership stays with the controller that acquired it, including when connect or selection changes race.
+    const remotes = useMemo(() => new WeakMap(), []);
+    const selected = useControllerPerConversation({ key,
+        create: async () => {
+            let controller;
+            const remote = await createRemoteChat({ endpoint: url, fetch: request => latest.current.fetch(request),
+                requestContext: () => {
+                    const placement = readChatPlacement(controller), screen = latest.current.requestContext?.();
+                    return placement || screen ? { ...screen, ...(placement && { placement }) } : undefined;
+                }, ...(transport ? { transport } : {}), ...(latest.current.webSocket ? { webSocket: latest.current.webSocket } : {}) });
+            try {
+                controller = createNativeChatController({ identity: identity, ...remote });
+                remotes.set(controller, remote);
+                return controller;
+            }
+            catch (error) {
+                await remote.close();
+                throw error;
+            }
+        },
+        connect: controller => controller.connect(),
+        dispose: async (controller) => {
+            // Start both: closing a transport may release a pending native watch opening.
+            const pending = controller.dispose();
+            try {
+                await remotes.get(controller)?.close();
+            }
+            finally {
+                await pending;
+                remotes.delete(controller);
+            }
+        }, });
+    if (selected.status === 'ready' && conversationId !== undefined) {
+        const remote = remotes.get(selected.controller);
+        const actions = { ...(typeof remote.answer === 'function' ? { answer: remote.answer } : {}),
+            ...(typeof remote.withdraw === 'function' ? { withdraw: remote.withdraw } : {}) };
+        return { status: 'ready', conversationId, controller: selected.controller, actions, configure: remote.configure };
+    }
+    return selected.status === 'offline' ? { status: 'offline', conversationId, error: String(selected.error?.message ?? selected.error) } : { status: 'connecting', conversationId };
+}

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,60 @@
+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;
+};
+//# sourceMappingURL=chat-react.d.ts.map