@stapel/chat-react 0.1.0

package/src/i18n/ru.ts

@@ -0,0 +1,98 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { chatI18nBundleEn } from "./keys.js";
+import { chatErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+export { chatErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+/**
+ * Russian bundle for chat-react — the pair's `ru` locale, shipped as the
+ * `@stapel/chat-react/i18n/ru` subpath (i18n-shipping.md §2) so the locale is
+ * opt-in: hosts that don't register it never carry these strings (the main
+ * entry does not import this module — gated by size-limit + the bundle-purity
+ * test).
+ *
+ * TWO SOURCES, ON PURPOSE. The generated `chatErrorBundleRu` covers the 42
+ * cross-cutting keys stapel-core owns and localizes. The 12 keys stapel-chat
+ * owns are NOT in it, and cannot be: the module ships no `translations/`
+ * directory at all, so the generator emits a `Partial` bundle and says so in
+ * its own header (`ERRORS_LOCALE_EXEMPT_OWNERS`, the stapel-forms precedent).
+ * They are authored below, beside the UI copy. When upstream ships
+ * `translations/errors.ru.json`, these twelve lines are deleted and the
+ * generated bundle covers them — the keys and the texts do not move.
+ */
+export const chatI18nBundleRu: I18nDictionary = {
+  // Backend error codes — generated ru texts for every key core owns.
+  ...chatErrorBundleRu,
+
+  // Backend error codes stapel-chat owns — authored here (see the note above).
+  "error.400.chat_attachments_disabled": "Вложения отключены в этой установке",
+  "error.400.chat_body_too_long": "Сообщение длиннее допустимого предела",
+  "error.400.chat_empty_message":
+    "В сообщении должен быть текст или хотя бы одно вложение",
+  "error.400.chat_invalid_direct":
+    "В личной переписке должен быть ровно один собеседник",
+  "error.400.chat_invalid_kind": "Неизвестный тип диалога",
+  "error.400.chat_invalid_reply":
+    "Сообщение, на которое вы отвечаете, не из этого диалога",
+  "error.400.chat_kind_disabled": "Этот тип диалога отключён в этой установке",
+  "error.400.chat_not_support":
+    "Это действие применимо только к обращениям в поддержку",
+  "error.403.chat_not_operator":
+    "Это действие доступно только оператору поддержки",
+  "error.403.chat_not_participant": "Вы не участник этого диалога",
+  "error.404.chat_conversation_not_found": "Диалог не найден",
+  "error.409.chat_already_assigned": "Это обращение уже взято в работу",
+
+  // chat-react UI (hand-written ru mirror of the en copy in keys.ts)
+  "chat.error.unknown": "Что-то пошло не так. Попробуйте ещё раз.",
+
+  "chat.list.title": "Сообщения",
+  "chat.list.empty": "Диалогов пока нет.",
+  "chat.list.loading": "Загрузка диалогов…",
+  "chat.list.load_more": "Показать ещё",
+  "chat.list.end": "Это все диалоги.",
+  "chat.list.retry": "Повторить",
+  "chat.list.unread": "Непрочитанных: {count}",
+  "chat.list.open": "Открыть",
+
+  "chat.kind.direct": "Личная переписка",
+  "chat.kind.group": "Групповой диалог",
+  "chat.kind.support": "Поддержка",
+
+  "chat.thread.loading": "Загрузка сообщений…",
+  "chat.thread.empty": "Сообщений пока нет. Напишите первым.",
+  "chat.thread.retry": "Повторить",
+  "chat.thread.load_older": "Показать более ранние",
+  "chat.thread.beginning": "Это начало переписки.",
+  "chat.thread.system": "Системное сообщение",
+
+  "chat.composer.placeholder": "Напишите сообщение…",
+  "chat.composer.send": "Отправить",
+  "chat.composer.sending": "Отправка…",
+  "chat.composer.blocked.empty": "Сначала напишите текст.",
+  "chat.composer.blocked.too_long":
+    "Это длиннее {max} символов — немного сократите.",
+
+  "chat.start.button": "Написать продавцу",
+  "chat.start.starting": "Открываем…",
+  "chat.start.blocked.self": "Это ваше собственное объявление.",
+  "chat.start.blocked.unknown_seller": "У этого объявления не указан продавец.",
+
+  "chat.transport.live": "На связи",
+  "chat.transport.polling": "Обновляется каждые несколько секунд",
+  "chat.transport.idle": "Приостановлено",
+
+  "chat.nav.conversations": "Сообщения",
+};
+
+/**
+ * Register the pair's `ru` locale into a core i18n engine (call once at
+ * startup, after {@link registerChatI18n}). Layers per the merge-priority
+ * convention (i18n-shipping.md §3): the en floor is registered UNDER the ru
+ * texts inside the `ru` locale, so a key the ru bundle ever misses degrades to
+ * its English text — never to a raw key.
+ */
+export function registerChatI18nRu(engine: I18nEngine): void {
+  engine.registerBundle("ru", chatI18nBundleEn);
+  engine.registerBundle("ru", chatI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,189 @@
+/**
+ * `@stapel/chat-react` — the headless React pair for stapel-chat
+ * (frontend-standard §2). Business + state only, zero visual opinion. Built on
+ * `@stapel/core`'s StapelClient (verification-403 interception, token refresh,
+ * i18n, analytics, query layer).
+ *
+ * WHAT IS DIFFERENT ABOUT THIS PAIR. Its backend has two ways to deliver the
+ * same journal: the REST history, and its own resumable WebSocket protocol
+ * (`ws/chat/<conversation_id>` — hello{last_seq} → welcome → replay →
+ * replay_done → live). Both are wired here, behind ONE seam
+ * (`useChatFreshness`), and no component above that seam can tell which is
+ * running. Writes go over REST in either case. See `flows/freshness.ts` for
+ * the seam and the criterion under which `@stapel/realtime` replaces its
+ * insides.
+ *
+ * Layers: api → model → realtime → flows → headless → i18n. Generated
+ * surfaces (error map, manifest, llms.txt) are produced by the monorepo
+ * `gen:*` drivers and stand under drift gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createChatApi } from "./api/chatApi.js";
+export type { ChatApi } from "./api/chatApi.js";
+export type {
+  Schemas,
+  AnchorDirection,
+  ChatMessage,
+  Conversation,
+  ConversationKind,
+  ConversationListParams,
+  ConversationPage,
+  CreateConversationRequest,
+  MarkReadRequest,
+  MessageHistoryParams,
+  MessageKind,
+  MessagePage,
+  Participant,
+  ParticipantRole,
+  SendMessageRequest,
+  SupportStatus,
+} from "./api/types.js";
+
+// ── realtime (the module's own socket protocol, typed) ───────────────────────
+// Exported because a host may want to render the connection state or inject a
+// transport; NOTHING above `flows/freshness.ts` inside this package uses it,
+// which is what keeps the substrate migration to one file.
+export {
+  CHAT_WS_CLOSE_NOT_PARTICIPANT,
+  CHAT_WS_CLOSE_UNAUTHENTICATED,
+  CHAT_WS_REPLAY_LIMIT,
+  CHAT_WS_RESYNC,
+  decodeServerFrame,
+  parseServerFrame,
+} from "./realtime/frames.js";
+export type {
+  ChatAckFrame,
+  ChatClientFrame,
+  ChatErrorFrame,
+  ChatHelloFrame,
+  ChatMessageFrame,
+  ChatPingFrame,
+  ChatPongFrame,
+  ChatReplayDoneFrame,
+  ChatSendFrame,
+  ChatServerFrame,
+  ChatWelcomeFrame,
+} from "./realtime/frames.js";
+export {
+  browserWebSocketFactory,
+  canOpenWebSocket,
+  createChatSocket,
+} from "./realtime/chatSocket.js";
+export type {
+  ChatConnectionState,
+  ChatReconnectOptions,
+  ChatSocket,
+  ChatSocketConnection,
+  ChatSocketHandlers,
+  ChatSocketOptions,
+  ChatSocketRefusal,
+  ChatSocketStatus,
+  ChatWebSocketFactory,
+} from "./realtime/chatSocket.js";
+export {
+  chatConversationStream,
+  chatInboxStream,
+  chatSocketUrl,
+  chatStreamId,
+  deriveChatSocketBase,
+} from "./realtime/streams.js";
+export type {
+  ChatConversationStream,
+  ChatInboxStream,
+  ChatStreamKey,
+} from "./realtime/streams.js";
+
+// ── flows (the transport seam + the error fold) ──────────────────────────────
+export { createFlowMachine, useFlow, isErrorCode } from "@stapel/core";
+export type {
+  FlowMachine,
+  FlowMachineOptions,
+  FlowStateBase,
+  FlowError,
+} from "@stapel/core";
+export { toFlowError } from "./flows/errors.js";
+export { CHAT_FLOWS, flowEndpoints } from "./flows/registry.js";
+export type { ChatFlowId, ChatFlowSpec, FlowEndpoint } from "./flows/registry.js";
+export {
+  CONVERSATION_LIST_INTERVAL_MS,
+  THREAD_INTERVAL_MS,
+  useChatFreshness,
+} from "./flows/freshness.js";
+export type {
+  ChatFreshness,
+  ChatFreshnessOptions,
+  ChatSignal,
+  ChatSignalKeyMap,
+  ChatTransport,
+} from "./flows/freshness.js";
+
+// ── model (runtime wiring, query keys, context, the thread store) ────────────
+export { createChatRuntime } from "./model/runtime.js";
+export type {
+  ChatRealtimeConfig,
+  ChatRealtimeOptions,
+  ChatRuntime,
+  CreateChatRuntimeOptions,
+} from "./model/runtime.js";
+export {
+  ChatRuntimeContext,
+  useChatRuntime,
+  useChatApi,
+  useChatAnalytics,
+} from "./model/context.js";
+export { chatQueryKeys } from "./model/queryKeys.js";
+export { THREAD_PAGE, useConversation, useConversations, useThread } from "./model/queries.js";
+export {
+  useLoadOlderMessages,
+  useMarkRead,
+  useSendMessage,
+  useStartDirectChat,
+} from "./model/mutations.js";
+export type {
+  SendMessageVariables,
+  StartDirectChatVariables,
+} from "./model/mutations.js";
+export { CHAT_DEFAULT_MAX_BODY_LENGTH } from "./model/limits.js";
+export { nextReadMarker } from "./model/readMarker.js";
+export {
+  EMPTY_THREAD_WINDOW,
+  mergeMessage,
+  mergeNewerPage,
+  mergeOlderPage,
+  threadFirstSeq,
+  threadLastSeq,
+  threadWindowFromPage,
+} from "./model/threadWindow.js";
+export type { ChatThreadWindow, ThreadMergeResult } from "./model/threadWindow.js";
+
+// ── headless (renderless components) ─────────────────────────────────────────
+export { ChatProvider } from "./headless/ChatProvider.js";
+export { ConversationList } from "./headless/ConversationList.js";
+export type { ConversationListBag } from "./headless/ConversationList.js";
+export { ConversationThread } from "./headless/ConversationThread.js";
+export type { ConversationThreadBag } from "./headless/ConversationThread.js";
+export { MessageComposer } from "./headless/MessageComposer.js";
+export type { MessageComposerBag } from "./headless/MessageComposer.js";
+export { StartDirectChat } from "./headless/StartDirectChat.js";
+export type { StartDirectChatBag } from "./headless/StartDirectChat.js";
+
+// ── nav ──────────────────────────────────────────────────────────────────────
+export { navEntries } from "./nav/manifest.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export { CHAT_I18N_KEYS, chatI18nBundleEn, registerChatI18n } from "./i18n/keys.js";
+export type { ChatI18nKey } from "./i18n/keys.js";
+
+// ── errors map (code → status/params/remediation/en; generated) ──────────────
+export {
+  CHAT_ERRORS,
+  CHAT_ERROR_CODES,
+  chatErrorBundleEn,
+  explainChatError,
+} from "./i18n/errorsMap.js";
+export type {
+  ChatErrorCode,
+  ChatErrorSpec,
+  Remediation,
+} from "./i18n/errorsMap.js";

package/src/model/context.tsx

@@ -0,0 +1,25 @@
+import type { Context } from "react";
+import { createModuleContext } from "@stapel/core";
+import type { Analytics, ModuleContextKit } from "@stapel/core";
+import type { ChatApi } from "../api/chatApi.js";
+import type { ChatRuntime } from "./runtime.js";
+
+/**
+ * The wired ChatRuntime shared through React context by `<ChatProvider>`.
+ * Hooks in `model/`, `flows/` and `headless/` read the singletons from here.
+ * One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`, slim wave §21/S2); this module binds it under the
+ * pair's public names.
+ */
+const kit: ModuleContextKit<ChatRuntime> = createModuleContext<ChatRuntime>("Chat");
+
+export const ChatRuntimeContext: Context<ChatRuntime | null> = kit.RuntimeContext;
+
+export const useChatRuntime: () => ChatRuntime = kit.useRuntime;
+
+export const useChatApi: () => ChatApi = kit.useApi;
+
+export const useChatAnalytics: () => Analytics | null = kit.useAnalytics;
+
+/** @internal Re-exported as `<ChatProvider>` from `headless/`. */
+export const ModuleProvider: ModuleContextKit<ChatRuntime>["Provider"] = kit.Provider;

package/src/model/limits.ts

@@ -0,0 +1,11 @@
+/**
+ * Mirrors of the backend's CONFIGURABLE limits — axes, not constants.
+ *
+ * `STAPEL_CHAT.MAX_BODY_LENGTH` (`stapel_chat/conf.py`, surfaced in
+ * `docs/capabilities.json`) defaults to 4000 characters and a deployment may
+ * narrow it. The server stays authoritative and answers
+ * `error.400.chat_body_too_long`; the mirror exists so a person is told before
+ * they lose what they typed, not after. A host that changed the axis passes
+ * its own value to `<MessageComposer maxLength=…>`.
+ */
+export const CHAT_DEFAULT_MAX_BODY_LENGTH = 4000;

package/src/model/mutations.ts

@@ -0,0 +1,208 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type {
+  QueryClient,
+  UseMutationOptions,
+  UseMutationResult,
+} from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type { ChatMessage, Conversation } from "../api/types.js";
+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";
+import type { ChatThreadWindow } 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: QueryClient,
+  conversationId: string,
+  message: ChatMessage
+): void {
+  const key = chatQueryKeys.thread(conversationId);
+  const window = queryClient.getQueryData<ChatThreadWindow>(key);
+  if (!window) return;
+  const merged = mergeMessage(window, message);
+  if (merged.gap) {
+    void queryClient.invalidateQueries({ queryKey: key });
+    return;
+  }
+  queryClient.setQueryData(key, merged.window);
+}
+
+/** Variables for {@link useSendMessage}. */
+export interface SendMessageVariables {
+  readonly body: string;
+  /** Quoted message id; must belong to this conversation. */
+  readonly replyTo?: string;
+}
+
+/**
+ * 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: string
+): UseMutationResult<ChatMessage, StapelApiError, SendMessageVariables> {
+  const api = useChatApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    ChatMessage,
+    StapelApiError,
+    SendMessageVariables
+  > = {
+    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: string
+): UseMutationResult<number | null, StapelApiError, number> {
+  const api = useChatApi();
+  const queryClient = useQueryClient();
+  const markerKey = chatQueryKeys.readMarker(conversationId);
+  const options: UseMutationOptions<number | null, StapelApiError, number> = {
+    mutationFn: async (candidate) => {
+      const known = queryClient.getQueryData<number>(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);
+}
+
+/** Variables for {@link useStartDirectChat}. */
+export interface StartDirectChatVariables {
+  /** The other person — the seller, on a listing page. */
+  readonly userId: string;
+}
+
+/**
+ * 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(): UseMutationResult<
+  Conversation,
+  StapelApiError,
+  StartDirectChatVariables
+> {
+  const api = useChatApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    Conversation,
+    StapelApiError,
+    StartDirectChatVariables
+  > = {
+    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: string,
+  limit: number = THREAD_PAGE
+): UseMutationResult<ChatThreadWindow | null, StapelApiError, void> {
+  const api = useChatApi();
+  const queryClient = useQueryClient();
+  const key = chatQueryKeys.thread(conversationId);
+  const options: UseMutationOptions<
+    ChatThreadWindow | null,
+    StapelApiError,
+    void
+  > = {
+    mutationFn: async () => {
+      const window = queryClient.getQueryData<ChatThreadWindow>(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);
+}

package/src/model/queries.ts

@@ -0,0 +1,120 @@
+import { useInfiniteQuery, useQuery, useQueryClient } from "@tanstack/react-query";
+import type {
+  InfiniteData,
+  UseInfiniteQueryResult,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import { useActiveSessionReady } from "@stapel/core";
+import type { StapelApiError } from "@stapel/core";
+import type { Conversation, ConversationPage } from "../api/types.js";
+import { useChatApi } from "./context.js";
+import { chatQueryKeys } from "./queryKeys.js";
+import {
+  mergeNewerPage,
+  threadLastSeq,
+  threadWindowFromPage,
+} from "./threadWindow.js";
+import type { ChatThreadWindow } 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: string
+): UseQueryResult<Conversation, StapelApiError> {
+  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: number = CONVERSATIONS_PAGE
+): UseInfiniteQueryResult<
+  InfiniteData<ConversationPage, string | undefined>,
+  StapelApiError
+> {
+  const api = useChatApi();
+  const sessionReady = useActiveSessionReady();
+  return useInfiniteQuery({
+    queryKey: chatQueryKeys.conversations(),
+    queryFn: ({ pageParam }) =>
+      api.conversations({
+        direction: "next",
+        limit,
+        ...(pageParam !== undefined ? { anchor: pageParam } : {}),
+      }),
+    initialPageParam: undefined as string | 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: string,
+  limit: number = THREAD_PAGE
+): UseQueryResult<ChatThreadWindow, StapelApiError> {
+  const api = useChatApi();
+  const queryClient = useQueryClient();
+  const sessionReady = useActiveSessionReady();
+  const queryKey = chatQueryKeys.thread(conversationId);
+  return useQuery({
+    queryKey,
+    queryFn: async () => {
+      const previous = queryClient.getQueryData<ChatThreadWindow>(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,
+  });
+}

package/src/model/queryKeys.ts

@@ -0,0 +1,32 @@
+/**
+ * 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" as const;
+
+export 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];
+} = {
+  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],
+};