@stapel/chat-react 0.1.0

package/dist/model/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../src/model/mutations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAMjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AA4B1D,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,cAAc,EAAE,MAAM,GACrB,iBAAiB,CAAC,WAAW,EAAE,cAAc,EAAE,oBAAoB,CAAC,CAuBtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,cAAc,EAAE,MAAM,GACrB,iBAAiB,CAAC,MAAM,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,CAsB1D;AAED,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,iBAAiB,CACrD,YAAY,EACZ,cAAc,EACd,wBAAwB,CACzB,CAoBA;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAoB,GAC1B,iBAAiB,CAAC,gBAAgB,GAAG,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,CAyBlE"}

package/dist/model/mutations.js

@@ -0,0 +1,156 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useChatApi } from "./context.js";
+import { chatQueryKeys } from "./queryKeys.js";
+import { nextReadMarker } from "./readMarker.js";
+import { THREAD_PAGE } from "./queries.js";
+import { mergeMessage, mergeOlderPage } from "./threadWindow.js";
+/**
+ * Write hooks (frontend-standard §2 — mutations invalidate on success).
+ *
+ * Sending is REST, always: the socket's `send` frame refuses with a
+ * socket-local code that has no i18n key and no remediation, while the HTTP
+ * path answers with the persisted row and a real error envelope. See
+ * `realtime/frames.ts`.
+ */
+/** Fold a freshly-known message into the cached window, or re-read on a hole. */
+function absorbMessage(queryClient, conversationId, message) {
+    const key = chatQueryKeys.thread(conversationId);
+    const window = queryClient.getQueryData(key);
+    if (!window)
+        return;
+    const merged = mergeMessage(window, message);
+    if (merged.gap) {
+        void queryClient.invalidateQueries({ queryKey: key });
+        return;
+    }
+    queryClient.setQueryData(key, merged.window);
+}
+/**
+ * Append a message to a thread. On success the persisted row (with its `seq`)
+ * is folded straight into the window, so the sender sees their own line
+ * without waiting for a poll — and the socket's fan-out copy of the same row
+ * is then a duplicate that `mergeMessage` drops.
+ *
+ * Attachments are NOT wired in this version (spec §4.5): the field exists on
+ * the wire, but shipping it would mean shipping CDN upload rights into chat,
+ * and a control that is visible but does nothing is worse than one that is
+ * absent.
+ */
+export function useSendMessage(conversationId) {
+    const api = useChatApi();
+    const queryClient = useQueryClient();
+    const options = {
+        mutationFn: (vars) => api.sendMessage(conversationId, {
+            body: vars.body,
+            ...(vars.replyTo !== undefined ? { reply_to: vars.replyTo } : {}),
+        }),
+        onSuccess: (message) => {
+            absorbMessage(queryClient, conversationId, message);
+            // The list orders by `updated_at` and carries the unread badge; both
+            // just moved.
+            void queryClient.invalidateQueries({
+                queryKey: chatQueryKeys.conversations(),
+            });
+        },
+    };
+    return useMutation(options);
+}
+/**
+ * Advance the caller's read marker to `upto_seq`.
+ *
+ * Monotonic on the client as well as on the server: a candidate at or below
+ * what this client already reported resolves without a request
+ * (`nextReadMarker`). The reported value is remembered in the query cache —
+ * see `readMarker.ts` for why it cannot be read back off the wire.
+ */
+export function useMarkRead(conversationId) {
+    const api = useChatApi();
+    const queryClient = useQueryClient();
+    const markerKey = chatQueryKeys.readMarker(conversationId);
+    const options = {
+        mutationFn: async (candidate) => {
+            const known = queryClient.getQueryData(markerKey);
+            const seq = nextReadMarker(known, candidate);
+            if (seq === null)
+                return null;
+            await api.markRead(conversationId, seq);
+            return seq;
+        },
+        onSuccess: (seq) => {
+            if (seq === null)
+                return;
+            queryClient.setQueryData(markerKey, seq);
+            // The badge is server-computed; re-read it rather than guessing.
+            void queryClient.invalidateQueries({
+                queryKey: chatQueryKeys.conversations(),
+            });
+        },
+    };
+    return useMutation(options);
+}
+/**
+ * Open the direct thread with someone, creating it only if it does not exist.
+ *
+ * The idempotency is the module's, not ours: a direct thread is keyed by an
+ * order-independent `direct_key` over the participant pair (namespaced by
+ * scope) under a unique constraint, and the create race is resolved by the
+ * constraint — the loser gets the winner's row (`MODULE.md`, "Direct
+ * idempotency"). So "message the seller" is safe to press twice, from two
+ * tabs, on two listings.
+ *
+ * TWO PEOPLE, ONE THREAD — INCLUDING ACROSS LISTINGS. The key is the pair,
+ * not the listing: a buyer who writes to the same seller about a second item
+ * lands in the same conversation. `CreateConversationRequest.scope_key` does
+ * not change that (the server ignores the field and resolves the scope
+ * itself — `api/extensions.ts`), so a host that wants the listing named must
+ * name it in the first message.
+ */
+export function useStartDirectChat() {
+    const api = useChatApi();
+    const queryClient = useQueryClient();
+    const options = {
+        mutationFn: (vars) => api.createConversation("direct", [vars.userId]),
+        onSuccess: (conversation) => {
+            queryClient.setQueryData(chatQueryKeys.conversation(conversation.id), conversation);
+            void queryClient.invalidateQueries({
+                queryKey: chatQueryKeys.conversations(),
+            });
+        },
+    };
+    return useMutation(options);
+}
+/**
+ * Backfill one page of older history onto the front of the window
+ * (`direction=next` from the window's oldest seq — "next" is OLDER here,
+ * because the history is ordered `-seq`).
+ *
+ * A mutation rather than a second query: it is an action a person takes
+ * ("show me more"), it must not re-run on focus, and its result belongs in
+ * the ONE thread cache entry rather than in a second one that would then have
+ * to be reconciled with it.
+ */
+export function useLoadOlderMessages(conversationId, limit = THREAD_PAGE) {
+    const api = useChatApi();
+    const queryClient = useQueryClient();
+    const key = chatQueryKeys.thread(conversationId);
+    const options = {
+        mutationFn: async () => {
+            const window = queryClient.getQueryData(key);
+            if (!window || !window.hasOlder || window.olderAnchor === null)
+                return null;
+            const page = await api.messages(conversationId, {
+                direction: "next",
+                anchor: window.olderAnchor,
+                limit,
+            });
+            return mergeOlderPage(window, page);
+        },
+        onSuccess: (window) => {
+            if (window === null)
+                return;
+            queryClient.setQueryData(key, window);
+        },
+    };
+    return useMutation(options);
+}
+//# sourceMappingURL=mutations.js.map

package/dist/model/mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../src/model/mutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQpE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGjE;;;;;;;GAOG;AAEH,iFAAiF;AACjF,SAAS,aAAa,CACpB,WAAwB,EACxB,cAAsB,EACtB,OAAoB;IAEpB,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,WAAW,CAAC,YAAY,CAAmB,GAAG,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;QACf,KAAK,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;QACtD,OAAO;IACT,CAAC;IACD,WAAW,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/C,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,cAAsB;IAEtB,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,MAAM,OAAO,GAIT;QACF,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CACnB,GAAG,CAAC,WAAW,CAAC,cAAc,EAAE;YAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAC;QACJ,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YACrB,aAAa,CAAC,WAAW,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;YACpD,qEAAqE;YACrE,cAAc;YACd,KAAK,WAAW,CAAC,iBAAiB,CAAC;gBACjC,QAAQ,EAAE,aAAa,CAAC,aAAa,EAAE;aACxC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;IACF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,cAAsB;IAEtB,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3D,MAAM,OAAO,GAA8D;QACzE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,CAAS,SAAS,CAAC,CAAC;YAC1D,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC7C,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC9B,MAAM,GAAG,CAAC,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YACxC,OAAO,GAAG,CAAC;QACb,CAAC;QACD,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;YACjB,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO;YACzB,WAAW,CAAC,YAAY,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACzC,iEAAiE;YACjE,KAAK,WAAW,CAAC,iBAAiB,CAAC;gBACjC,QAAQ,EAAE,aAAa,CAAC,aAAa,EAAE;aACxC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;IACF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB;IAKhC,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,MAAM,OAAO,GAIT;QACF,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrE,SAAS,EAAE,CAAC,YAAY,EAAE,EAAE;YAC1B,WAAW,CAAC,YAAY,CACtB,aAAa,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC,EAC3C,YAAY,CACb,CAAC;YACF,KAAK,WAAW,CAAC,iBAAiB,CAAC;gBACjC,QAAQ,EAAE,aAAa,CAAC,aAAa,EAAE;aACxC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;IACF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,cAAsB,EACtB,QAAgB,WAAW;IAE3B,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,OAAO,GAIT;QACF,UAAU,EAAE,KAAK,IAAI,EAAE;YACrB,MAAM,MAAM,GAAG,WAAW,CAAC,YAAY,CAAmB,GAAG,CAAC,CAAC;YAC/D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,WAAW,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC5E,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,cAAc,EAAE;gBAC9C,SAAS,EAAE,MAAM;gBACjB,MAAM,EAAE,MAAM,CAAC,WAAW;gBAC1B,KAAK;aACN,CAAC,CAAC;YACH,OAAO,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE;YACpB,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO;YAC5B,WAAW,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;KACF,CAAC;IACF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC"}

package/dist/model/queries.d.ts

@@ -0,0 +1,33 @@
+import type { InfiniteData, UseInfiniteQueryResult, UseQueryResult } from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type { Conversation, ConversationPage } from "../api/types.js";
+import type { ChatThreadWindow } from "./threadWindow.js";
+/** Default window size for a thread — one screenful of history and change. */
+export declare const THREAD_PAGE = 50;
+/** One conversation (participant-only; 403 otherwise). */
+export declare function useConversation(conversationId: string): UseQueryResult<Conversation, StapelApiError>;
+/**
+ * The caller's conversations as an infinite (load-more) list, anchored on
+ * `updated_at`. `unread_count` is computed server-side per conversation, so
+ * the badge needs no second request.
+ */
+export declare function useConversations(limit?: number): UseInfiniteQueryResult<InfiniteData<ConversationPage, string | undefined>, StapelApiError>;
+/**
+ * The thread — one cache entry holding a contiguous, seq-ordered window
+ * (`threadWindow.ts`).
+ *
+ * ITS REFETCH IS THE POLL. The query function reads the window already in the
+ * cache and asks only for what comes after it
+ * (`direction=prev&anchor=<tip>`), so `refetch()` means "advance by seq", not
+ * "read the newest page again". That is what lets the transport seam stay a
+ * signal → refetch bridge: a socket frame and a polling tick take the exact
+ * same code path, and the UI cannot tell which arrived.
+ *
+ * A tail that does not touch the tip (more messages than one page holds, or
+ * the paginator's own truncation flag) is a hole. Rather than render a thread
+ * with a hole, the window is rebuilt from the newest page — the REST twin of
+ * the socket's `error{resync}`, and the reason correctness never depends on
+ * delivery.
+ */
+export declare function useThread(conversationId: string, limit?: number): UseQueryResult<ChatThreadWindow, StapelApiError>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/model/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/model/queries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAQtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAe1D,8EAA8E;AAC9E,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,0DAA0D;AAC1D,wBAAgB,eAAe,CAC7B,cAAc,EAAE,MAAM,GACrB,cAAc,CAAC,YAAY,EAAE,cAAc,CAAC,CAQ9C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAA2B,GACjC,sBAAsB,CACvB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC,EAClD,cAAc,CACf,CAgBA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAoB,GAC1B,cAAc,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAwBlD"}

package/dist/model/queries.js

@@ -0,0 +1,93 @@
+import { useInfiniteQuery, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useActiveSessionReady } from "@stapel/core";
+import { useChatApi } from "./context.js";
+import { chatQueryKeys } from "./queryKeys.js";
+import { mergeNewerPage, threadLastSeq, threadWindowFromPage, } from "./threadWindow.js";
+/**
+ * Read hooks over the chat API. Staleness follows core's query defaults;
+ * freshness is driven by the transport seam (`flows/freshness.ts`), never by
+ * a `refetchInterval` sprinkled on a call site.
+ *
+ * Every hook is gated on {@link useActiveSessionReady}: chat is a member
+ * surface with no natural `enabled` condition of its own, and a top-level
+ * read that races a still-bootstrapping session reports "loaded, nothing
+ * here" for the length of the bootstrap.
+ */
+/** Default page size for the conversation list. */
+const CONVERSATIONS_PAGE = 20;
+/** Default window size for a thread — one screenful of history and change. */
+export const THREAD_PAGE = 50;
+/** One conversation (participant-only; 403 otherwise). */
+export function useConversation(conversationId) {
+    const api = useChatApi();
+    const sessionReady = useActiveSessionReady();
+    return useQuery({
+        queryKey: chatQueryKeys.conversation(conversationId),
+        queryFn: () => api.conversation(conversationId),
+        enabled: sessionReady && conversationId.length > 0,
+    });
+}
+/**
+ * The caller's conversations as an infinite (load-more) list, anchored on
+ * `updated_at`. `unread_count` is computed server-side per conversation, so
+ * the badge needs no second request.
+ */
+export function useConversations(limit = CONVERSATIONS_PAGE) {
+    const api = useChatApi();
+    const sessionReady = useActiveSessionReady();
+    return useInfiniteQuery({
+        queryKey: chatQueryKeys.conversations(),
+        queryFn: ({ pageParam }) => api.conversations({
+            direction: "next",
+            limit,
+            ...(pageParam !== undefined ? { anchor: pageParam } : {}),
+        }),
+        initialPageParam: undefined,
+        getNextPageParam: (last) => last.has_next ? (last.next_anchor ?? undefined) : undefined,
+        enabled: sessionReady,
+    });
+}
+/**
+ * The thread — one cache entry holding a contiguous, seq-ordered window
+ * (`threadWindow.ts`).
+ *
+ * ITS REFETCH IS THE POLL. The query function reads the window already in the
+ * cache and asks only for what comes after it
+ * (`direction=prev&anchor=<tip>`), so `refetch()` means "advance by seq", not
+ * "read the newest page again". That is what lets the transport seam stay a
+ * signal → refetch bridge: a socket frame and a polling tick take the exact
+ * same code path, and the UI cannot tell which arrived.
+ *
+ * A tail that does not touch the tip (more messages than one page holds, or
+ * the paginator's own truncation flag) is a hole. Rather than render a thread
+ * with a hole, the window is rebuilt from the newest page — the REST twin of
+ * the socket's `error{resync}`, and the reason correctness never depends on
+ * delivery.
+ */
+export function useThread(conversationId, limit = THREAD_PAGE) {
+    const api = useChatApi();
+    const queryClient = useQueryClient();
+    const sessionReady = useActiveSessionReady();
+    const queryKey = chatQueryKeys.thread(conversationId);
+    return useQuery({
+        queryKey,
+        queryFn: async () => {
+            const previous = queryClient.getQueryData(queryKey);
+            const tip = previous ? threadLastSeq(previous) : 0;
+            if (!previous || tip === 0) {
+                return threadWindowFromPage(await api.messages(conversationId, { limit }));
+            }
+            const tail = await api.messages(conversationId, {
+                direction: "prev",
+                anchor: String(tip),
+                limit,
+            });
+            const merged = mergeNewerPage(previous, tail);
+            if (!merged.gap)
+                return merged.window;
+            return threadWindowFromPage(await api.messages(conversationId, { limit }));
+        },
+        enabled: sessionReady && conversationId.length > 0,
+    });
+}
+//# sourceMappingURL=queries.js.map

package/dist/model/queries.js.map

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

package/dist/model/queryKeys.d.ts

@@ -0,0 +1,8 @@
+export declare const chatQueryKeys: {
+    readonly all: readonly ["chat"];
+    conversations(): readonly ["chat", "conversations"];
+    conversation(conversationId: string): readonly ["chat", "conversation", string];
+    thread(conversationId: string): readonly ["chat", "thread", string];
+    readMarker(conversationId: string): readonly ["chat", "read-marker", string];
+};
+//# sourceMappingURL=queryKeys.d.ts.map

package/dist/model/queryKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryKeys.d.ts","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,aAAa,EAAE;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,aAAa,IAAI,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACpD,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC;IAChF,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpE,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;CAiB9E,CAAC"}

package/dist/model/queryKeys.js

@@ -0,0 +1,26 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
+ * Everything under the `"chat"` root so a host can invalidate the whole module
+ * or match a single thread. Persist scope is per-user via core's query runtime
+ * (`setPersistUser`). Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ */
+const ROOT = "chat";
+export const chatQueryKeys = {
+    all: [ROOT],
+    // The infinite list shares one root key across pages (its pages live under
+    // a single cache entry).
+    conversations: () => [ROOT, "conversations"],
+    conversation: (conversationId) => [ROOT, "conversation", conversationId],
+    // The thread is ONE cache entry holding a merged, seq-ordered window — not
+    // a page list. Its query function reads this entry to decide what to ask
+    // for next (a tail by seq, not a blind re-read), which is what makes a
+    // plain `refetch()` mean "poll by seq" and lets the transport seam stay a
+    // signal → refetch bridge.
+    thread: (conversationId) => [ROOT, "thread", conversationId],
+    // Not a server read: the highest `upto_seq` this client has already
+    // reported. Lives in the query cache so it survives a remount and is wiped
+    // at logout with everything else (frontend-core-architecture-v2 §43.3).
+    readMarker: (conversationId) => [ROOT, "read-marker", conversationId],
+};
+//# sourceMappingURL=queryKeys.js.map

package/dist/model/queryKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryKeys.js","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,IAAI,GAAG,MAAe,CAAC;AAE7B,MAAM,CAAC,MAAM,aAAa,GAMtB;IACF,GAAG,EAAE,CAAC,IAAI,CAAC;IACX,2EAA2E;IAC3E,yBAAyB;IACzB,aAAa,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC;IAC5C,YAAY,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,cAAc,EAAE,cAAc,CAAC;IACxE,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,0EAA0E;IAC1E,2BAA2B;IAC3B,MAAM,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,cAAc,CAAC;IAC5D,oEAAoE;IACpE,2EAA2E;IAC3E,wEAAwE;IACxE,UAAU,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,cAAc,CAAC;CACtE,CAAC"}

package/dist/model/readMarker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The read marker, and the one rule that governs it: it only ever moves
+ * forward.
+ *
+ * The server already enforces that (`services.mark_read` never lowers
+ * `last_read_seq`), so a client that sends a smaller value is not corrupting
+ * anything — it is spending a request to be ignored, and, worse, telling the
+ * UI a story that the next list refresh will contradict. The guard is here so
+ * the client's own belief matches the server's.
+ *
+ * WHY THE CLIENT HAS TO REMEMBER AT ALL. `ConversationResponse.participants[]`
+ * carries `last_read_seq` — for every participant, with no marker for which
+ * one is the caller (the response has no "me"). `unread_count` is the only
+ * caller-relative number the endpoint returns. So the highest marker THIS
+ * client has reported cannot be read back off the wire; it is remembered in
+ * the query cache (`chatQueryKeys.readMarker`), which the session layer wipes
+ * at logout along with everything else.
+ */
+/**
+ * The value to send, or `null` for "already reported — send nothing".
+ *
+ * `candidate` of 0 (an empty thread) is never sent: there is no such seq.
+ */
+export declare function nextReadMarker(known: number | undefined, candidate: number): number | null;
+//# sourceMappingURL=readMarker.d.ts.map

package/dist/model/readMarker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readMarker.d.ts","sourceRoot":"","sources":["../../src/model/readMarker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAIf"}

package/dist/model/readMarker.js

@@ -0,0 +1,31 @@
+/**
+ * The read marker, and the one rule that governs it: it only ever moves
+ * forward.
+ *
+ * The server already enforces that (`services.mark_read` never lowers
+ * `last_read_seq`), so a client that sends a smaller value is not corrupting
+ * anything — it is spending a request to be ignored, and, worse, telling the
+ * UI a story that the next list refresh will contradict. The guard is here so
+ * the client's own belief matches the server's.
+ *
+ * WHY THE CLIENT HAS TO REMEMBER AT ALL. `ConversationResponse.participants[]`
+ * carries `last_read_seq` — for every participant, with no marker for which
+ * one is the caller (the response has no "me"). `unread_count` is the only
+ * caller-relative number the endpoint returns. So the highest marker THIS
+ * client has reported cannot be read back off the wire; it is remembered in
+ * the query cache (`chatQueryKeys.readMarker`), which the session layer wipes
+ * at logout along with everything else.
+ */
+/**
+ * The value to send, or `null` for "already reported — send nothing".
+ *
+ * `candidate` of 0 (an empty thread) is never sent: there is no such seq.
+ */
+export function nextReadMarker(known, candidate) {
+    if (!Number.isFinite(candidate) || candidate <= 0)
+        return null;
+    if (known !== undefined && candidate <= known)
+        return null;
+    return candidate;
+}
+//# sourceMappingURL=readMarker.js.map

package/dist/model/readMarker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readMarker.js","sourceRoot":"","sources":["../../src/model/readMarker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAyB,EACzB,SAAiB;IAEjB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,KAAK,KAAK,SAAS,IAAI,SAAS,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IAC3D,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/model/runtime.d.ts

@@ -0,0 +1,50 @@
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import type { ChatApi } from "../api/chatApi.js";
+import type { ChatReconnectOptions, ChatWebSocketFactory } from "../realtime/chatSocket.js";
+/**
+ * Host-side realtime configuration. Every field is optional and every default
+ * degrades to polling rather than to a broken socket — a host that says
+ * nothing gets the right behaviour on a WSGI deployment (no sockets at all)
+ * and on an ASGI one (sockets, if the origin can be resolved).
+ */
+export interface ChatRealtimeOptions {
+    /**
+     * Where this deployment mounts `stapel_chat.routing.websocket_urlpatterns`,
+     * e.g. `wss://darom.example/ws/chat/`. Omit to derive it from `baseUrl`
+     * (the canonical `/ws/chat/` at the API's own origin). Pass `null` to turn
+     * the socket transport OFF explicitly — a host that knows its backend runs
+     * under WSGI says so here instead of letting every tab fail a handshake
+     * six times first.
+     */
+    readonly socketUrl?: string | null;
+    /** Injectable socket transport (tests, instrumentation, React Native). */
+    readonly webSocket?: ChatWebSocketFactory;
+    /** Reconnect backoff knobs. */
+    readonly reconnect?: ChatReconnectOptions;
+    /**
+     * Origin used to resolve a relative `baseUrl`. Defaults to the browser's
+     * own; irrelevant when `baseUrl` is absolute.
+     */
+    readonly origin?: string | null;
+}
+/** The realtime configuration as the transport seam reads it. */
+export interface ChatRealtimeConfig {
+    /** `null` — this build will not open sockets; the seam polls. */
+    readonly socketBase: string | null;
+    readonly webSocket: ChatWebSocketFactory | undefined;
+    readonly reconnect: ChatReconnectOptions | undefined;
+}
+/**
+ * The wired chat runtime — core's `ModuleRuntime` bound to this pair's API,
+ * PLUS the one thing chat has and a plain REST pair does not: where its
+ * socket lives. The socket URL is runtime configuration, not module state, so
+ * it rides here rather than through a second provider.
+ */
+export type ChatRuntime = ModuleRuntime<ChatApi> & {
+    readonly realtime: ChatRealtimeConfig;
+};
+export interface CreateChatRuntimeOptions extends CreateModuleRuntimeOptions {
+    readonly realtime?: ChatRealtimeOptions;
+}
+export declare function createChatRuntime(options: CreateChatRuntimeOptions): ChatRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/model/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAGnC;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG;IACjD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC,CAAC;AAEF,MAAM,WAAW,wBAAyB,SAAQ,0BAA0B;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AA0BD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,WAAW,CAGb"}

package/dist/model/runtime.js

@@ -0,0 +1,27 @@
+import { createModuleRuntime } from "@stapel/core";
+import { createChatApi } from "../api/chatApi.js";
+import { canOpenWebSocket } from "../realtime/chatSocket.js";
+import { deriveChatSocketBase } from "../realtime/streams.js";
+function currentOrigin() {
+    return typeof location !== "undefined" ? location.origin : null;
+}
+function resolveRealtime(baseUrl, options) {
+    const explicit = options?.socketUrl;
+    const socketBase = explicit === null
+        ? null
+        : explicit !== undefined
+            ? explicit
+            : canOpenWebSocket()
+                ? deriveChatSocketBase(baseUrl, options?.origin ?? currentOrigin())
+                : null;
+    return {
+        socketBase,
+        webSocket: options?.webSocket,
+        reconnect: options?.reconnect,
+    };
+}
+export function createChatRuntime(options) {
+    const runtime = createModuleRuntime(createChatApi, options);
+    return { ...runtime, realtime: resolveRealtime(options.baseUrl, options.realtime) };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/model/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAK7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAmD9D,SAAS,aAAa;IACpB,OAAO,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAClE,CAAC;AAED,SAAS,eAAe,CACtB,OAAe,EACf,OAAwC;IAExC,MAAM,QAAQ,GAAG,OAAO,EAAE,SAAS,CAAC;IACpC,MAAM,UAAU,GACd,QAAQ,KAAK,IAAI;QACf,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,QAAQ,KAAK,SAAS;YACtB,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,gBAAgB,EAAE;gBAClB,CAAC,CAAC,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,CAAC;gBACnE,CAAC,CAAC,IAAI,CAAC;IACf,OAAO;QACL,UAAU;QACV,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,SAAS,EAAE,OAAO,EAAE,SAAS;KAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,OAAiC;IAEjC,MAAM,OAAO,GAAG,mBAAmB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;AACtF,CAAC"}

package/dist/model/threadWindow.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The thread store: a merged, `seq`-ordered window over a conversation, and
+ * the four pure functions that move it.
+ *
+ * WHY A WINDOW AND NOT A PAGE LIST. A chat thread grows at BOTH ends: older
+ * history is paged backwards on scroll, new messages arrive at the tip while
+ * the reader is looking at it. TanStack's bidirectional infinite query cannot
+ * express the second half — `getPreviousPageParam` is answered from the page
+ * the server sent, and at the tip the server correctly says "no previous
+ * page", which would freeze the tail forever. So the thread is ONE cache
+ * entry holding a contiguous run of messages, and the two directions are two
+ * merges into it.
+ *
+ * THE ORDERING RULE IS THE BACKEND'S, NOT OURS. `seq` is a gapless, total
+ * per-conversation order (`stapel-chat/MODULE.md`: "seq is gapless and total
+ * — the canonical anchor for history and the resume cursor for realtime"), and
+ * ordering by timestamp is an explicit anti-pattern there: two messages in the
+ * same millisecond still have a definite order. Everything below therefore
+ * sorts, dedupes and detects gaps by `seq` alone.
+ *
+ * ONE MORE THING THE PAGINATOR MAKES US DO. Item order depends on the
+ * DIRECTION asked for: core's `AnchorPagination` returns newest-first for
+ * `next` and reverses to oldest-first for `prev` (`pagination.py`,
+ * `items[::-1]`). Rather than remember which call produced which order, every
+ * merge sorts by `seq` — the total order is cheaper to apply than to
+ * remember.
+ */
+import type { ChatMessage, MessagePage } from "../api/types.js";
+/**
+ * A contiguous run of messages, ascending by `seq`.
+ *
+ * "Contiguous" is load-bearing: because `seq` is gapless, a window whose seqs
+ * are consecutive integers provably has no hole in it. Every merge below
+ * either preserves that or refuses the merge and reports a gap — it never
+ * quietly stitches two runs with a hole between them, which is the defect
+ * that makes a chat show yesterday's message under today's.
+ */
+export interface ChatThreadWindow {
+    /** Ascending by `seq`, no duplicates, no holes. */
+    readonly messages: readonly ChatMessage[];
+    /** Older history exists before `messages[0]`. */
+    readonly hasOlder: boolean;
+    /** Anchor for the next backfill page (`direction=next`), if any. */
+    readonly olderAnchor: string | null;
+}
+/** A merge that either advanced the window, or found a hole and refused. */
+export interface ThreadMergeResult {
+    readonly window: ChatThreadWindow;
+    /**
+     * `true` when the incoming messages do not touch the window's tip: more
+     * arrived than one page holds. The caller re-hydrates (the REST twin of the
+     * socket's `error{resync}`) rather than rendering a thread with a hole.
+     */
+    readonly gap: boolean;
+}
+export declare const EMPTY_THREAD_WINDOW: ChatThreadWindow;
+/** The tip: the highest `seq` in the window, or 0 for an empty one. */
+export declare function threadLastSeq(window: ChatThreadWindow): number;
+/** The oldest `seq` in the window, or 0 for an empty one. */
+export declare function threadFirstSeq(window: ChatThreadWindow): number;
+/**
+ * A fresh window from the newest page (`GET …/messages` with no anchor).
+ * This is also the resync path: whatever was loaded before is dropped,
+ * because a window that cannot be proven contiguous is worse than a short
+ * one.
+ */
+export declare function threadWindowFromPage(page: MessagePage): ChatThreadWindow;
+/**
+ * Merge a backfill page (`direction=next` from the window's oldest seq) onto
+ * the FRONT. Anything at or above the current oldest is dropped as a
+ * duplicate — the anchor is exclusive, so this only fires on a retry.
+ */
+export declare function mergeOlderPage(window: ChatThreadWindow, page: MessagePage): ChatThreadWindow;
+/**
+ * Merge a tail page (`direction=prev` anchored on the window's tip) onto the
+ * END — the poll-by-seq step.
+ *
+ * Two independent hole detectors, because either one alone can be fooled:
+ *  - the seq test (`first new seq === tip + 1`), which is only meaningful
+ *    because seq is gapless;
+ *  - the paginator's own `has_prev`, which is how a window that was TRUNCATED
+ *    (more messages above the anchor than `limit`) says so.
+ */
+export declare function mergeNewerPage(window: ChatThreadWindow, page: MessagePage): ThreadMergeResult;
+/**
+ * Merge ONE message onto the end — a live socket frame, or the row a `send`
+ * just returned.
+ *
+ * Already-known seq is dropped (the socket dedupes too, but the sender's own
+ * REST answer and the frame it fans out to itself are two paths to the same
+ * row, and only this rule makes them idempotent). A seq beyond the tip + 1 is
+ * a hole: the window is left untouched and the caller re-hydrates.
+ */
+export declare function mergeMessage(window: ChatThreadWindow, message: ChatMessage): ThreadMergeResult;
+//# sourceMappingURL=threadWindow.d.ts.map

package/dist/model/threadWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threadWindow.d.ts","sourceRoot":"","sources":["../../src/model/threadWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,mBAAmB,EAAE,gBAIjC,CAAC;AAMF,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAG9D;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,WAAW,GAChB,gBAAgB,CAalB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,WAAW,GAChB,iBAAiB,CAoBnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,WAAW,GACnB,iBAAiB,CAQnB"}