@stapel/chat-react 0.1.0

package/dist/flows/freshness.js

@@ -0,0 +1,227 @@
+/**
+ * THE TRANSPORT SEAM. One hook, two transports, and no screen that knows
+ * which one is running.
+ *
+ * ── What changed since the spec ─────────────────────────────────────────────
+ *
+ * `tasks/darom-storefront-design.md` §3.6 ruled polling-by-seq for chat v1,
+ * and it was right about the fleet it surveyed: stapel-chat had the resumable
+ * consumer but `routing.py` exported nothing, so no host could mount it.
+ * stapel-chat 0.2.2 ships that mount (`ws/chat/<uuid:conversation_id>`) and
+ * the darom fleet runs it. So the pair carries BOTH transports and picks at
+ * runtime — a deployment without sockets (WSGI, no channel layer, a
+ * misconfigured proxy) is not a broken chat, it is a chat that refreshes on a
+ * timer.
+ *
+ * ── The shape, and why it is this shape ─────────────────────────────────────
+ *
+ * `useChatFreshness(streamKey, mapToQueryKeys, { fallbackRefetchInterval })`
+ * is deliberately the signature §3.6 specified and the realtime substrate
+ * spec (§7) reserves for `useSignalInvalidate`: a signal maps to query keys,
+ * the keys are refetched, and the fallback interval turns the same interface
+ * into polling. Both halves therefore end in the same place — a refetch of
+ * the thread query, whose query function advances the window BY SEQ
+ * (`model/queries.ts`). A socket frame does not carry its payload into the
+ * cache; it says "there is something after your tip", and the store goes and
+ * gets it. That is resync-by-refetch as a first-class construction, and it is
+ * why the tests below hold for both transports without a branch.
+ *
+ * ── The replacement criterion, stated up front ──────────────────────────────
+ *
+ * When `@stapel/realtime` phase 1 lands, THIS FILE is the migration: `createChatSocket`
+ * goes away, `useSignalInvalidate` takes its place, and the pair's tests must
+ * stay green with no edits. Nothing above this file imports `realtime/`, so
+ * the blast radius is checkable rather than promised. There is no
+ * "TODO: replace with sockets" comment anywhere in this package — there is a
+ * seam with one consumer and a written criterion.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useChatRuntime } from "../model/context.js";
+import { chatQueryKeys } from "../model/queryKeys.js";
+import { threadLastSeq } from "../model/threadWindow.js";
+import { createChatSocket } from "../realtime/chatSocket.js";
+import { CHAT_WS_RESYNC } from "../realtime/frames.js";
+import { chatSocketUrl } from "../realtime/streams.js";
+/**
+ * The polling periods the storefront spec fixes (§3.6): an open thread 3 s,
+ * the inbox 15 s. They live here, beside the transport that uses them, rather
+ * than in the components — the numbers are a property of the seam.
+ */
+export const THREAD_INTERVAL_MS = 3_000;
+export const CONVERSATION_LIST_INTERVAL_MS = 15_000;
+/** Frames arriving in a burst (a replay) collapse into one refetch. */
+const FLUSH_DELAY_MS = 40;
+/** Backoff ceiling: interval × 2^4 (3s → 48s) before it stops growing. */
+const MAX_BACKOFF_STEPS = 4;
+const IDLE_STATUS = {
+    state: "closed",
+    refusal: undefined,
+    attempt: 0,
+};
+function documentVisible() {
+    return typeof document === "undefined" || document.visibilityState !== "hidden";
+}
+export function useChatFreshness(stream, mapToQueryKeys, options) {
+    const runtime = useChatRuntime();
+    const queryClient = useQueryClient();
+    const enabled = options?.enabled ?? true;
+    const socketEnabled = options?.socketEnabled ?? true;
+    const interval = options?.fallbackRefetchInterval ?? 0;
+    // Both are plain values, compared by value in the dependency lists below —
+    // no memo needed, and no memo to forget to update.
+    const socketUrl = chatSocketUrl(runtime.realtime.socketBase, stream);
+    const conversationId = stream.kind === "conversation" ? stream.conversationId : null;
+    // The mapping function is a call-site lambda; keeping it in a ref is what
+    // stops every render from tearing down the socket.
+    const mapRef = useRef(mapToQueryKeys);
+    useEffect(() => {
+        mapRef.current = mapToQueryKeys;
+    });
+    const failuresRef = useRef(0);
+    const [status, setStatus] = useState(IDLE_STATUS);
+    const [visible, setVisible] = useState(documentVisible);
+    /** Refetch everything the signals touch. Resolves `true` if any read failed. */
+    const refresh = useCallback(async (signals) => {
+        const seen = new Set();
+        const keys = [];
+        for (const signal of signals) {
+            for (const key of mapRef.current(signal)) {
+                const id = JSON.stringify(key);
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                keys.push(key);
+            }
+        }
+        if (keys.length === 0)
+            return false;
+        await Promise.all(keys.map((queryKey) => queryClient.refetchQueries({ queryKey, type: "active" })));
+        return keys.some((queryKey) => queryClient
+            .getQueryCache()
+            .findAll({ queryKey })
+            .some((query) => query.state.status === "error"));
+    }, [queryClient]);
+    const pollNow = useCallback(() => {
+        void refresh([{ kind: "tick" }]);
+    }, [refresh]);
+    // ── the socket half ────────────────────────────────────────────────────────
+    const socketFactory = runtime.realtime.webSocket;
+    const reconnect = runtime.realtime.reconnect;
+    useEffect(() => {
+        if (!enabled || !socketEnabled || socketUrl === null || conversationId === null) {
+            setStatus(IDLE_STATUS);
+            return;
+        }
+        let buffered = [];
+        let flushHandle;
+        const flush = () => {
+            const signals = buffered;
+            buffered = [];
+            flushHandle = undefined;
+            void refresh(signals);
+        };
+        const push = (signal) => {
+            buffered.push(signal);
+            if (flushHandle === undefined)
+                flushHandle = setTimeout(flush, FLUSH_DELAY_MS);
+        };
+        const socket = createChatSocket({
+            url: socketUrl,
+            // Read at every connect: the store keeps advancing by REST while the
+            // socket is down, and resuming from a stale cursor is how a reconnect
+            // turns into a duplicate storm.
+            lastSeq: () => {
+                const window = queryClient.getQueryData(chatQueryKeys.thread(conversationId));
+                return window ? threadLastSeq(window) : 0;
+            },
+            onFrame: (frame) => {
+                if (frame.type === "message") {
+                    push({ kind: "message", conversationId, seq: frame.seq });
+                    return;
+                }
+                if (frame.type === "error" && frame.code === CHAT_WS_RESYNC) {
+                    // The gap is wider than the replay window. The journal is the
+                    // truth; go and read it.
+                    push({ kind: "resync", conversationId });
+                }
+                // `welcome`, `replay_done` and `pong` carry no news the store needs:
+                // every message they bracket arrives as its own frame.
+            },
+            onStatus: setStatus,
+            ...(socketFactory !== undefined ? { webSocket: socketFactory } : {}),
+            ...(reconnect !== undefined ? { reconnect } : {}),
+        });
+        return () => {
+            if (flushHandle !== undefined)
+                clearTimeout(flushHandle);
+            socket.close();
+        };
+    }, [
+        enabled,
+        socketEnabled,
+        socketUrl,
+        conversationId,
+        queryClient,
+        refresh,
+        socketFactory,
+        reconnect,
+    ]);
+    // ── the polling half ───────────────────────────────────────────────────────
+    //
+    // Runs whenever the socket is NOT carrying the stream — including the
+    // inbox, which has no socket at all — and never while the tab is in the
+    // background (nobody is reading; the catch-up happens on the way back).
+    const polling = enabled && interval > 0 && visible && status.state !== "open";
+    useEffect(() => {
+        if (!polling)
+            return;
+        let cancelled = false;
+        let handle;
+        const arm = (delay) => {
+            handle = setTimeout(() => {
+                void refresh([{ kind: "tick" }]).then((failed) => {
+                    if (cancelled)
+                        return;
+                    // Consecutive failures back off exponentially; one success resets
+                    // it. A backend that is down must not be asked twenty times a
+                    // minute by every open tab.
+                    failuresRef.current = failed
+                        ? Math.min(failuresRef.current + 1, MAX_BACKOFF_STEPS)
+                        : 0;
+                    arm(interval * 2 ** failuresRef.current);
+                });
+            }, delay);
+        };
+        arm(interval * 2 ** failuresRef.current);
+        return () => {
+            cancelled = true;
+            if (handle !== undefined)
+                clearTimeout(handle);
+        };
+    }, [polling, interval, refresh]);
+    // ── visibility ─────────────────────────────────────────────────────────────
+    useEffect(() => {
+        if (typeof document === "undefined")
+            return;
+        const onVisibility = () => {
+            const nowVisible = document.visibilityState !== "hidden";
+            setVisible(nowVisible);
+            // Coming back is the moment the reader most wants the truth.
+            if (nowVisible)
+                void refresh([{ kind: "tick" }]);
+        };
+        document.addEventListener("visibilitychange", onVisibility);
+        return () => {
+            document.removeEventListener("visibilitychange", onVisibility);
+        };
+    }, [refresh]);
+    const transport = status.state === "open" ? "socket" : polling ? "polling" : "idle";
+    return useMemo(() => ({
+        transport,
+        connection: status.state,
+        refusal: status.refusal,
+        pollNow,
+    }), [transport, status.state, status.refusal, pollNow]);
+}
+//# sourceMappingURL=freshness.js.map

package/dist/flows/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../src/flows/freshness.ts"],"names":[],"mappings":"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"}

package/dist/flows/registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Zero-flow registry shim (slim wave §21/S3). stapel-chat annotates no
+ * `@flow_step`: its `docs/flows.json` is an empty array, so `gen:flows` skips
+ * emission for this pair (no `flows/generated/`). This hand-written shim
+ * preserves the pair's public flow-registry surface at its zero-flow shape.
+ *
+ * That is not an oversight upstream, and worth saying once: chat's
+ * multi-step-ness lives in the TRANSPORT (resume, replay, resync), not in a
+ * server-declared funnel of endpoints. `flows/freshness.ts` is where this
+ * pair's real state machine is.
+ *
+ * When the backend annotates flows, `pnpm gen:flows` emits
+ * `./generated/flows.gen.ts` again — replace these exports with re-exports
+ * from it (the shapes match by construction) and delete this file.
+ */
+export declare const CHAT_FLOWS: {};
+/** Canonical flow ids present in flows.json (none yet — see above). */
+export type ChatFlowId = keyof typeof CHAT_FLOWS;
+export type ChatFlowSpec = (typeof CHAT_FLOWS)[ChatFlowId];
+export interface FlowEndpoint {
+    readonly method: string;
+    readonly path: string;
+}
+/** All HTTP endpoints a flow touches, in step order (for the contract test / MSW). */
+export declare function flowEndpoints(id: ChatFlowId): readonly FlowEndpoint[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/flows/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/flows/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,IAAc,CAAC;AAEtC,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,UAAU,CAAC,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,SAAS,YAAY,EAAE,CAOrE"}

package/dist/flows/registry.js

@@ -0,0 +1,24 @@
+/**
+ * Zero-flow registry shim (slim wave §21/S3). stapel-chat annotates no
+ * `@flow_step`: its `docs/flows.json` is an empty array, so `gen:flows` skips
+ * emission for this pair (no `flows/generated/`). This hand-written shim
+ * preserves the pair's public flow-registry surface at its zero-flow shape.
+ *
+ * That is not an oversight upstream, and worth saying once: chat's
+ * multi-step-ness lives in the TRANSPORT (resume, replay, resync), not in a
+ * server-declared funnel of endpoints. `flows/freshness.ts` is where this
+ * pair's real state machine is.
+ *
+ * When the backend annotates flows, `pnpm gen:flows` emits
+ * `./generated/flows.gen.ts` again — replace these exports with re-exports
+ * from it (the shapes match by construction) and delete this file.
+ */
+export const CHAT_FLOWS = {};
+/** All HTTP endpoints a flow touches, in step order (for the contract test / MSW). */
+export function flowEndpoints(id) {
+    // Same widened body as the generated registry's — valid for the zero-flow
+    // shape AND correct once flows exist.
+    const spec = CHAT_FLOWS[id];
+    return spec ? spec.steps.flatMap((s) => s.endpoints) : [];
+}
+//# sourceMappingURL=registry.js.map

package/dist/flows/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/flows/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,EAAW,CAAC;AAYtC,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,EAAc;IAC1C,0EAA0E;IAC1E,sCAAsC;IACtC,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAEb,CAAC;IACd,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5D,CAAC"}

package/dist/headless/ChatProvider.d.ts

@@ -0,0 +1,22 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ChatRuntime } from "../model/runtime.js";
+/**
+ * Provides the wired {@link ChatRuntime} to every chat hook and headless
+ * component below it. Bring your own visual shell — this component renders
+ * nothing of its own.
+ *
+ * ```tsx
+ * const runtime = createChatRuntime({
+ *   baseUrl: "/chat/api/v1",
+ *   // sockets are derived from baseUrl's origin; pass `{ socketUrl: null }`
+ *   // on a WSGI deployment to go straight to polling.
+ * });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <ChatProvider runtime={runtime}>{app}</ChatProvider>
+ * ```
+ */
+export declare const ChatProvider: (props: {
+    runtime: ChatRuntime;
+    children: ReactNode;
+}) => ReactElement;
+//# sourceMappingURL=ChatProvider.d.ts.map

package/dist/headless/ChatProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatProvider.d.ts","sourceRoot":"","sources":["../../src/headless/ChatProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,KAAK,EAAE;IACjC,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,SAAS,CAAC;CACrB,KAAK,YAA6B,CAAC"}

package/dist/headless/ChatProvider.js

@@ -0,0 +1,18 @@
+import { ModuleProvider } from "../model/context.js";
+/**
+ * Provides the wired {@link ChatRuntime} to every chat hook and headless
+ * component below it. Bring your own visual shell — this component renders
+ * nothing of its own.
+ *
+ * ```tsx
+ * const runtime = createChatRuntime({
+ *   baseUrl: "/chat/api/v1",
+ *   // sockets are derived from baseUrl's origin; pass `{ socketUrl: null }`
+ *   // on a WSGI deployment to go straight to polling.
+ * });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <ChatProvider runtime={runtime}>{app}</ChatProvider>
+ * ```
+ */
+export const ChatProvider = ModuleProvider;
+//# sourceMappingURL=ChatProvider.js.map

package/dist/headless/ChatProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatProvider.js","sourceRoot":"","sources":["../../src/headless/ChatProvider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAGJ,cAAc,CAAC"}

package/dist/headless/ConversationList.d.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from "react";
+import type { LoadState } from "@stapel/core";
+import type { Conversation } from "../api/types.js";
+import type { ChatTransport } from "../flows/freshness.js";
+/** Render-prop bag for {@link ConversationList}. */
+export interface ConversationListBag {
+    /**
+     * The list, as a state a skin cannot flatten: `loading` / `ready` with the
+     * conversations loaded so far (most recent activity first) / `failed`.
+     * Render it with core's `matchList`.
+     */
+    readonly state: LoadState<readonly Conversation[]>;
+    /**
+     * Unread messages across the LOADED pages, as its own load state — a badge
+     * must not read "0" while the list is failing to load. Server-computed per
+     * conversation (`unread_count`), summed here; a host that pages deeper sees
+     * the number grow, which is honest for a badge over a paginated list.
+     */
+    readonly unreadTotal: LoadState<number>;
+    readonly hasNextPage: boolean;
+    readonly isFetchingNextPage: boolean;
+    fetchNextPage(): void;
+    refetch(): void;
+    /** Which transport is keeping this list fresh (always polling — the module
+     * mounts no socket for the inbox; see `realtime/streams.ts`). */
+    readonly transport: ChatTransport;
+}
+/**
+ * Headless conversation list — a renderless load-more list over
+ * `GET /chat/api/v1/conversations`, kept fresh through the transport seam.
+ *
+ * ```tsx
+ * <ConversationList>
+ *   {({ state }) =>
+ *     matchList(state, {
+ *       loading: () => <Spinner />,
+ *       failed: (error) => <ErrorPanel error={error} />,
+ *       empty: () => <NothingYet />,
+ *       ready: (rows) => <List rows={rows} />,
+ *     })
+ *   }
+ * </ConversationList>
+ * ```
+ */
+export declare function ConversationList(props: {
+    limit?: number;
+    /** Poll period in ms; `0` turns the list's own freshness off entirely. */
+    refreshIntervalMs?: number;
+    children: (bag: ConversationListBag) => ReactNode;
+}): ReactNode;
+//# sourceMappingURL=ConversationList.d.ts.map

package/dist/headless/ConversationList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationList.d.ts","sourceRoot":"","sources":["../../src/headless/ConversationList.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAOpD,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGvE,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,aAAa,IAAI,IAAI,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;IAChB;qEACiE;IACjE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,SAAS,CAAC;CACnD,GAAG,SAAS,CA+BZ"}

package/dist/headless/ConversationList.js

@@ -0,0 +1,47 @@
+import { useCallback } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import { useConversations } from "../model/queries.js";
+import { chatQueryKeys } from "../model/queryKeys.js";
+import { CONVERSATION_LIST_INTERVAL_MS, useChatFreshness, } from "../flows/freshness.js";
+import { chatInboxStream } from "../realtime/streams.js";
+/**
+ * Headless conversation list — a renderless load-more list over
+ * `GET /chat/api/v1/conversations`, kept fresh through the transport seam.
+ *
+ * ```tsx
+ * <ConversationList>
+ *   {({ state }) =>
+ *     matchList(state, {
+ *       loading: () => <Spinner />,
+ *       failed: (error) => <ErrorPanel error={error} />,
+ *       empty: () => <NothingYet />,
+ *       ready: (rows) => <List rows={rows} />,
+ *     })
+ *   }
+ * </ConversationList>
+ * ```
+ */
+export function ConversationList(props) {
+    const query = useConversations(props.limit);
+    const mapKeys = useCallback((_signal) => [chatQueryKeys.conversations()], []);
+    const freshness = useChatFreshness(chatInboxStream(), mapKeys, {
+        fallbackRefetchInterval: props.refreshIntervalMs ?? CONVERSATION_LIST_INTERVAL_MS,
+    });
+    // Pages are flattened INSIDE the ready arm — a failed or not-yet-run read
+    // never produces a list at all.
+    const state = mapLoad(loadStateFromQuery(query), (data) => data.pages.flatMap((page) => page.items));
+    return props.children({
+        state,
+        unreadTotal: mapLoad(state, (rows) => rows.reduce((total, row) => total + row.unread_count, 0)),
+        hasNextPage: query.hasNextPage,
+        isFetchingNextPage: query.isFetchingNextPage,
+        fetchNextPage: () => {
+            void query.fetchNextPage();
+        },
+        refetch: () => {
+            void query.refetch();
+        },
+        transport: freshness.transport,
+    });
+}
+//# sourceMappingURL=ConversationList.js.map

package/dist/headless/ConversationList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationList.js","sourceRoot":"","sources":["../../src/headless/ConversationList.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EACL,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA0BzD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAKhC;IACC,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,OAAmB,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,EAAE,CAAC,EACxD,EAAE,CACH,CAAC;IACF,MAAM,SAAS,GAAG,gBAAgB,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE;QAC7D,uBAAuB,EAAE,KAAK,CAAC,iBAAiB,IAAI,6BAA6B;KAClF,CAAC,CAAC;IAEH,0EAA0E;IAC1E,gCAAgC;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CACxD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CACzC,CAAC;IAEF,OAAO,KAAK,CAAC,QAAQ,CAAC;QACpB,KAAK;QACL,WAAW,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACnC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CACzD;QACD,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;QAC5C,aAAa,EAAE,GAAG,EAAE;YAClB,KAAK,KAAK,CAAC,aAAa,EAAE,CAAC;QAC7B,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;QACD,SAAS,EAAE,SAAS,CAAC,SAAS;KAC/B,CAAC,CAAC;AACL,CAAC"}

package/dist/headless/ConversationThread.d.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+import type { LoadState } from "@stapel/core";
+import type { ChatMessage } from "../api/types.js";
+import type { ChatTransport } from "../flows/freshness.js";
+import type { ChatConnectionState } from "../realtime/chatSocket.js";
+/** Render-prop bag for {@link ConversationThread}. */
+export interface ConversationThreadBag {
+    /**
+     * The thread, ascending by `seq`, as a state a skin cannot flatten. The
+     * messages are a contiguous run: a hole is never rendered, it is healed by
+     * a re-read (see `model/threadWindow.ts`).
+     */
+    readonly state: LoadState<readonly ChatMessage[]>;
+    /** Older history exists before the first loaded message. */
+    readonly hasOlder: boolean;
+    readonly isLoadingOlder: boolean;
+    /** Page one window of older history onto the front. */
+    loadOlder(): void;
+    refetch(): void;
+    /** The tip — the highest `seq` loaded. 0 for an empty or unloaded thread. */
+    readonly lastSeq: number;
+    /** Which transport is carrying this thread right now. */
+    readonly transport: ChatTransport;
+    readonly connection: ChatConnectionState;
+}
+/**
+ * Headless conversation thread: replay plus live tail, over whichever
+ * transport this deployment has.
+ *
+ * The socket subscription starts only once the window is loaded, and that is
+ * deliberate: `hello{last_seq}` with a cursor of 0 asks the server to replay
+ * the entire thread over the socket, which the store would then throw away
+ * and re-read by REST. Loading first makes the resume carry a real cursor.
+ *
+ * The read marker advances automatically to the tip while the thread is
+ * mounted (`autoMarkRead`, on by default): the person is looking at these
+ * messages. It only ever moves forward — `useMarkRead` drops a candidate at
+ * or below what was already reported, so a remount or a re-render costs
+ * nothing.
+ */
+export declare function ConversationThread(props: {
+    conversationId: string;
+    limit?: number;
+    /** Poll period in ms while the socket is not carrying this thread. */
+    refreshIntervalMs?: number;
+    /** Advance the read marker to the tip while mounted. Default `true`. */
+    autoMarkRead?: boolean;
+    children: (bag: ConversationThreadBag) => ReactNode;
+}): ReactNode;
+//# sourceMappingURL=ConversationThread.d.ts.map

package/dist/headless/ConversationThread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationThread.d.ts","sourceRoot":"","sources":["../../src/headless/ConversationThread.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IAClD,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,uDAAuD;IACvD,SAAS,IAAI,IAAI,CAAC;IAClB,OAAO,IAAI,IAAI,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,SAAS,CAAC;CACrD,GAAG,SAAS,CAgDZ"}

package/dist/headless/ConversationThread.js

@@ -0,0 +1,64 @@
+import { useCallback, useEffect } from "react";
+import { isLoadReady, loadStateFromQuery, mapLoad } from "@stapel/core";
+import { useThread } from "../model/queries.js";
+import { useLoadOlderMessages, useMarkRead } from "../model/mutations.js";
+import { chatQueryKeys } from "../model/queryKeys.js";
+import { threadLastSeq } from "../model/threadWindow.js";
+import { THREAD_INTERVAL_MS, useChatFreshness } from "../flows/freshness.js";
+import { chatConversationStream } from "../realtime/streams.js";
+/**
+ * Headless conversation thread: replay plus live tail, over whichever
+ * transport this deployment has.
+ *
+ * The socket subscription starts only once the window is loaded, and that is
+ * deliberate: `hello{last_seq}` with a cursor of 0 asks the server to replay
+ * the entire thread over the socket, which the store would then throw away
+ * and re-read by REST. Loading first makes the resume carry a real cursor.
+ *
+ * The read marker advances automatically to the tip while the thread is
+ * mounted (`autoMarkRead`, on by default): the person is looking at these
+ * messages. It only ever moves forward — `useMarkRead` drops a candidate at
+ * or below what was already reported, so a remount or a re-render costs
+ * nothing.
+ */
+export function ConversationThread(props) {
+    const { conversationId } = props;
+    const query = useThread(conversationId, props.limit);
+    const older = useLoadOlderMessages(conversationId, props.limit);
+    const markRead = useMarkRead(conversationId);
+    const mapKeys = useCallback((_signal) => [
+        chatQueryKeys.thread(conversationId),
+        // A new message also moves this thread up the list and changes its
+        // unread badge — one signal, two reads.
+        chatQueryKeys.conversations(),
+    ], [conversationId]);
+    const windowState = loadStateFromQuery(query);
+    const loaded = isLoadReady(windowState);
+    const freshness = useChatFreshness(chatConversationStream(conversationId), mapKeys, {
+        socketEnabled: loaded,
+        fallbackRefetchInterval: props.refreshIntervalMs ?? THREAD_INTERVAL_MS,
+    });
+    const lastSeq = isLoadReady(windowState) ? threadLastSeq(windowState.data) : 0;
+    const autoMarkRead = props.autoMarkRead ?? true;
+    const markReadMutate = markRead.mutate;
+    useEffect(() => {
+        if (!autoMarkRead || lastSeq === 0)
+            return;
+        markReadMutate(lastSeq);
+    }, [autoMarkRead, lastSeq, markReadMutate]);
+    return props.children({
+        state: mapLoad(windowState, (window) => window.messages),
+        hasOlder: isLoadReady(windowState) ? windowState.data.hasOlder : false,
+        isLoadingOlder: older.isPending,
+        loadOlder: () => {
+            older.mutate();
+        },
+        refetch: () => {
+            void query.refetch();
+        },
+        lastSeq,
+        transport: freshness.transport,
+        connection: freshness.connection,
+    });
+}
+//# sourceMappingURL=ConversationThread.js.map

package/dist/headless/ConversationThread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationThread.js","sourceRoot":"","sources":["../../src/headless/ConversationThread.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAuBhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAQlC;IACC,MAAM,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IACjC,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,oBAAoB,CAAC,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;IAE7C,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,OAAmB,EAAE,EAAE,CAAC;QACvB,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC;QACpC,mEAAmE;QACnE,wCAAwC;QACxC,aAAa,CAAC,aAAa,EAAE;KAC9B,EACD,CAAC,cAAc,CAAC,CACjB,CAAC;IACF,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,gBAAgB,CAChC,sBAAsB,CAAC,cAAc,CAAC,EACtC,OAAO,EACP;QACE,aAAa,EAAE,MAAM;QACrB,uBAAuB,EAAE,KAAK,CAAC,iBAAiB,IAAI,kBAAkB;KACvE,CACF,CAAC;IAEF,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC;IAChD,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC;IACvC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,YAAY,IAAI,OAAO,KAAK,CAAC;YAAE,OAAO;QAC3C,cAAc,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;IAE5C,OAAO,KAAK,CAAC,QAAQ,CAAC;QACpB,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;QACxD,QAAQ,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK;QACtE,cAAc,EAAE,KAAK,CAAC,SAAS;QAC/B,SAAS,EAAE,GAAG,EAAE;YACd,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;QACD,OAAO;QACP,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,UAAU,EAAE,SAAS,CAAC,UAAU;KACjC,CAAC,CAAC;AACL,CAAC"}

package/dist/headless/MessageComposer.d.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+import type { ActionAvailability } from "@stapel/core";
+/** Render-prop bag for {@link MessageComposer}. */
+export interface MessageComposerBag {
+    readonly value: string;
+    setValue(next: string): void;
+    /**
+     * Whether the message can be sent, and — when it cannot — why, as an i18n
+     * key a skin renders as TEXT beside the control (`useActionGate`). There is
+     * no way to spell "disabled, reason unknown".
+     */
+    readonly availability: ActionAvailability;
+    readonly isSending: boolean;
+    /** The thrown value from the last failed send, for the error dialect. */
+    readonly error: unknown;
+    /** Send the current value; clears it on success. No-op while blocked. */
+    send(): void;
+    readonly maxLength: number;
+    /**
+     * The length the SERVER counts. Python's `len()` over a `str` counts code
+     * points, and JavaScript's `String.length` counts UTF-16 code units — so a
+     * single emoji is 1 there and 2 here. Counting code points is what keeps
+     * the mirror from refusing a message the backend would have accepted.
+     */
+    readonly length: number;
+}
+/**
+ * Headless composer over `POST /chat/api/v1/conversations/{id}/messages`.
+ * REST, always — the socket's `send` frame refuses with codes that carry no
+ * i18n key (`realtime/frames.ts`).
+ */
+export declare function MessageComposer(props: {
+    conversationId: string;
+    maxLength?: number;
+    /** Called with the persisted message after a successful send. */
+    onSent?: (seq: number) => void;
+    children: (bag: MessageComposerBag) => ReactNode;
+}): ReactNode;
+//# sourceMappingURL=MessageComposer.d.ts.map

package/dist/headless/MessageComposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageComposer.d.ts","sourceRoot":"","sources":["../../src/headless/MessageComposer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAKvD,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,QAAQ,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,SAAS,CAAC;CAClD,GAAG,SAAS,CAyCZ"}