@ttt-productions/chat-react 0.13.16 → 0.13.18

package/dist/realtime/shared.js

@@ -1,36 +1,11 @@
-// Shared injected contracts + tunable constants for the realtime transport.
-//
-// The client-agreed limits (`HEARTBEAT_MS`, `TYPING_COALESCE_MS`,
-// `HISTORY_PAGE_MAX`) come from the one wire contract in
-// `@ttt-productions/chat-schemas`. The worker runtime is the authority and
-// rejects anything out of bounds, but the client uses these to coalesce and
-// paginate politely. The constants below are client-only retry policy.
-/**
- * Package-owned, Firebase-FREE terminal access-denial signal. A grant provider
- * throws this (from `GrantProvider`) when the authoritative authorization answer
- * is a genuine, terminal "no" — as opposed to a transient/retryable mint failure.
- *
- * The transport treats it specially: instead of the normal reconnect backoff it
- * STOPS reconnecting, closes the lifecycle, fails any pending optimistic sends,
- * and surfaces the stable `access-denied` error code (which the React hook maps to
- * `allowed: false` so the shell renders its no-access surface instead of an eternal
- * loader). Every other thrown error stays transient and reconnects as before.
- *
- * This is deliberately generic: the consuming app translates its own backend
- * denial (e.g. a Firebase `functions/permission-denied`) into this class at the
- * grant-provider boundary. The package never imports or names Firebase. Consumers
- * that cannot subclass may instead throw any error carrying `isChatAccessDenied:
- * true` — `isChatAccessDeniedError` recognizes both (also cross-realm safe).
- */
 export class ChatAccessDeniedError extends Error {
-    /** Duck-typed marker so detection survives module-realm / re-throw boundaries. */
+    // Duck-typed so detection survives module-realm and re-throw boundaries.
     isChatAccessDenied = true;
     constructor(message = 'Chat access denied') {
         super(message);
         this.name = 'ChatAccessDeniedError';
     }
 }
-/** True when `err` is a terminal chat access denial (class instance or duck-typed marker). */
 export function isChatAccessDeniedError(err) {
     return (err instanceof ChatAccessDeniedError ||
         (typeof err === 'object' &&
@@ -42,69 +17,20 @@ export const defaultTimers = {
     clearTimeout: (h) => clearTimeout(h),
     now: () => Date.now(),
 };
-/**
- * The TERMINAL lifecycle verdicts both realtime clients surface on
- * `lastErrorCode` — the two codes that mean "this lifecycle stopped on an
- * authoritative NO", as opposed to a transient/protocol code (`send-failed`,
- * `blocked-word`, …) that leaves the socket running.
- *
- * ONE declaration for both clients: each sets and clears the same two strings,
- * and `useRealtimeChatMessages` maps `access-denied` to `allowed: false`.
- * A terminal verdict is terminal WITHIN its lifecycle; a later explicit
- * `connect()` is a fresh attempt the authority may legitimately re-deny, so the
- * stale code is cleared there (never carried into the new lifecycle's state).
- */
 export const TERMINAL_ERROR_CODE = {
-    /** A 4403 REVOKED close: access was pulled while the socket was open. */
     REVOKED: 'revoked',
-    /** The grant provider threw `ChatAccessDeniedError` — a terminal policy "no". */
     ACCESS_DENIED: 'access-denied',
 };
-/** True when `code` is one of the terminal lifecycle verdicts above. */
 export function isTerminalErrorCode(code) {
     return code === TERMINAL_ERROR_CODE.REVOKED || code === TERMINAL_ERROR_CODE.ACCESS_DENIED;
 }
-/**
- * How long a client keeps failing to open for the first time before it reports the
- * first open as failed (`initialLoadFailed`) — so a chat or inbox that cannot connect
- * shows a failure the user can retry instead of an opening state that never ends. The
- * client keeps retrying in the background after it reports. Client policy, not a wire
- * constant.
- */
 export const CHAT_INITIAL_LOAD_FAILURE_BUDGET_MS = 15_000;
-/**
- * Max reconnect resends of one un-acked send before its optimistic row is flipped
- * to a visible failed state (retry affordance) instead of a permanent ghost. Each
- * reconnect that resumes with the pending send still un-acked counts one attempt.
- */
 export const MAX_PENDING_SEND_ATTEMPTS = 5;
-/**
- * Max wall-clock age of an un-acked pending send before it is flipped to failed on
- * the next resume, even if the attempt cap hasn't been hit (a long offline window).
- */
 export const PENDING_SEND_MAX_AGE_MS = 60_000;
-/**
- * Wall-clock budget (ms) for a SERVER-DECLARED retryable send. Once the Worker has
- * rejected a send as retryable — a correlated `send-rejected` frame OR the legacy
- * uncorrelated `error{code:'membership-pending'}` — that send keeps retrying on the
- * server's own hint until this budget elapses, and is NEVER failed by the generic
- * {@link MAX_PENDING_SEND_ATTEMPTS} cap (which governs only blind reconnect
- * resends). 90 s comfortably covers the backend projection/grant-bootstrap window
- * without stranding an optimistic bubble on "Sending…" the way the old ~10 s
- * five-attempt cap did.
- */
+// Covers the backend's projection window, which the five-attempt cap (~10 s) does not.
 export const SERVER_RETRYABLE_MAX_AGE_MS = 90_000;
-/**
- * Lower/upper clamp (ms) applied to a server `retryAfterMs` hint before scheduling a
- * resend, so a pathological (but schema-valid) hint can neither hammer the socket
- * nor park a send for minutes.
- */
 export const SEND_RETRY_MIN_DELAY_MS = 250;
 export const SEND_RETRY_MAX_DELAY_MS = 30_000;
-/**
- * A fresh client-minted id for a command the client correlates with its answer (a send's
- * `clientMessageId`, a mark-read's `requestId`). Random, so two tabs never collide.
- */
 export function newCorrelationId() {
     const c = globalThis.crypto;
     if (c?.randomUUID)

package/dist/realtime/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/realtime/shared.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,kEAAkE;AAClE,yDAAyD;AACzD,2EAA2E;AAC3E,4EAA4E;AAC5E,uEAAuE;AAWvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,kFAAkF;IACzE,kBAAkB,GAAG,IAAI,CAAC;IACnC,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,8FAA8F;AAC9F,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,OAAO,CACL,GAAG,YAAY,qBAAqB;QACpC,CAAC,OAAO,GAAG,KAAK,QAAQ;YACtB,GAAG,KAAK,IAAI;YACX,GAAwC,CAAC,kBAAkB,KAAK,IAAI,CAAC,CACzE,CAAC;AACJ,CAAC;AASD,MAAM,CAAC,MAAM,aAAa,GAAoB;IAC5C,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC;IAC1C,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IACpC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CACtB,CAAC;AAKF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,yEAAyE;IACzE,OAAO,EAAE,SAAS;IAClB,iFAAiF;IACjF,aAAa,EAAE,eAAe;CACtB,CAAC;AAIX,wEAAwE;AACxE,MAAM,UAAU,mBAAmB,CAAC,IAA+B;IACjE,OAAO,IAAI,KAAK,mBAAmB,CAAC,OAAO,IAAI,IAAI,KAAK,mBAAmB,CAAC,aAAa,CAAC;AAC5F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,CAAC,GAAI,UAAyD,CAAC,MAAM,CAAC;IAC5E,IAAI,CAAC,EAAE,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IACzC,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC","sourcesContent":["// Shared injected contracts + tunable constants for the realtime transport.\n//\n// The client-agreed limits (`HEARTBEAT_MS`, `TYPING_COALESCE_MS`,\n// `HISTORY_PAGE_MAX`) come from the one wire contract in\n// `@ttt-productions/chat-schemas`. The worker runtime is the authority and\n// rejects anything out of bounds, but the client uses these to coalesce and\n// paginate politely. The constants below are client-only retry policy.\n\n/**\n * Mints a short-lived chat grant token for the socket's scope. The app wires this\n * to its `mintChatGrant` callable (channel grant for a ChannelClient, inbox grant\n * for an InboxClient). Called on every connect AND once on a 4401 re-grant. The\n * app owns the Firestore permission check, the scope shape, caching to a React\n * Query staleTime < grant exp, and returning a FRESH token when re-invoked.\n */\nexport type GrantProvider = () => Promise<string>;\n\n/**\n * Package-owned, Firebase-FREE terminal access-denial signal. A grant provider\n * throws this (from `GrantProvider`) when the authoritative authorization answer\n * is a genuine, terminal \"no\" — as opposed to a transient/retryable mint failure.\n *\n * The transport treats it specially: instead of the normal reconnect backoff it\n * STOPS reconnecting, closes the lifecycle, fails any pending optimistic sends,\n * and surfaces the stable `access-denied` error code (which the React hook maps to\n * `allowed: false` so the shell renders its no-access surface instead of an eternal\n * loader). Every other thrown error stays transient and reconnects as before.\n *\n * This is deliberately generic: the consuming app translates its own backend\n * denial (e.g. a Firebase `functions/permission-denied`) into this class at the\n * grant-provider boundary. The package never imports or names Firebase. Consumers\n * that cannot subclass may instead throw any error carrying `isChatAccessDenied:\n * true` — `isChatAccessDeniedError` recognizes both (also cross-realm safe).\n */\nexport class ChatAccessDeniedError extends Error {\n  /** Duck-typed marker so detection survives module-realm / re-throw boundaries. */\n  readonly isChatAccessDenied = true;\n  constructor(message = 'Chat access denied') {\n    super(message);\n    this.name = 'ChatAccessDeniedError';\n  }\n}\n\n/** True when `err` is a terminal chat access denial (class instance or duck-typed marker). */\nexport function isChatAccessDeniedError(err: unknown): err is ChatAccessDeniedError {\n  return (\n    err instanceof ChatAccessDeniedError ||\n    (typeof err === 'object' &&\n      err !== null &&\n      (err as { isChatAccessDenied?: unknown }).isChatAccessDenied === true)\n  );\n}\n\n/** Injectable timers so the transport runs deterministically under fake timers in tests. */\nexport interface TransportTimers {\n  setTimeout: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;\n  clearTimeout: (h: ReturnType<typeof setTimeout>) => void;\n  now: () => number;\n}\n\nexport const defaultTimers: TransportTimers = {\n  setTimeout: (fn, ms) => setTimeout(fn, ms),\n  clearTimeout: (h) => clearTimeout(h),\n  now: () => Date.now(),\n};\n\n/** Connection status surfaced to the UI. */\nexport type RealtimeStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';\n\n/**\n * The TERMINAL lifecycle verdicts both realtime clients surface on\n * `lastErrorCode` — the two codes that mean \"this lifecycle stopped on an\n * authoritative NO\", as opposed to a transient/protocol code (`send-failed`,\n * `blocked-word`, …) that leaves the socket running.\n *\n * ONE declaration for both clients: each sets and clears the same two strings,\n * and `useRealtimeChatMessages` maps `access-denied` to `allowed: false`.\n * A terminal verdict is terminal WITHIN its lifecycle; a later explicit\n * `connect()` is a fresh attempt the authority may legitimately re-deny, so the\n * stale code is cleared there (never carried into the new lifecycle's state).\n */\nexport const TERMINAL_ERROR_CODE = {\n  /** A 4403 REVOKED close: access was pulled while the socket was open. */\n  REVOKED: 'revoked',\n  /** The grant provider threw `ChatAccessDeniedError` — a terminal policy \"no\". */\n  ACCESS_DENIED: 'access-denied',\n} as const;\n\nexport type TerminalErrorCode = (typeof TERMINAL_ERROR_CODE)[keyof typeof TERMINAL_ERROR_CODE];\n\n/** True when `code` is one of the terminal lifecycle verdicts above. */\nexport function isTerminalErrorCode(code: string | null | undefined): code is TerminalErrorCode {\n  return code === TERMINAL_ERROR_CODE.REVOKED || code === TERMINAL_ERROR_CODE.ACCESS_DENIED;\n}\n\n/**\n * How long a client keeps failing to open for the first time before it reports the\n * first open as failed (`initialLoadFailed`) — so a chat or inbox that cannot connect\n * shows a failure the user can retry instead of an opening state that never ends. The\n * client keeps retrying in the background after it reports. Client policy, not a wire\n * constant.\n */\nexport const CHAT_INITIAL_LOAD_FAILURE_BUDGET_MS = 15_000;\n\n/**\n * Max reconnect resends of one un-acked send before its optimistic row is flipped\n * to a visible failed state (retry affordance) instead of a permanent ghost. Each\n * reconnect that resumes with the pending send still un-acked counts one attempt.\n */\nexport const MAX_PENDING_SEND_ATTEMPTS = 5;\n\n/**\n * Max wall-clock age of an un-acked pending send before it is flipped to failed on\n * the next resume, even if the attempt cap hasn't been hit (a long offline window).\n */\nexport const PENDING_SEND_MAX_AGE_MS = 60_000;\n\n/**\n * Wall-clock budget (ms) for a SERVER-DECLARED retryable send. Once the Worker has\n * rejected a send as retryable — a correlated `send-rejected` frame OR the legacy\n * uncorrelated `error{code:'membership-pending'}` — that send keeps retrying on the\n * server's own hint until this budget elapses, and is NEVER failed by the generic\n * {@link MAX_PENDING_SEND_ATTEMPTS} cap (which governs only blind reconnect\n * resends). 90 s comfortably covers the backend projection/grant-bootstrap window\n * without stranding an optimistic bubble on \"Sending…\" the way the old ~10 s\n * five-attempt cap did.\n */\nexport const SERVER_RETRYABLE_MAX_AGE_MS = 90_000;\n\n/**\n * Lower/upper clamp (ms) applied to a server `retryAfterMs` hint before scheduling a\n * resend, so a pathological (but schema-valid) hint can neither hammer the socket\n * nor park a send for minutes.\n */\nexport const SEND_RETRY_MIN_DELAY_MS = 250;\nexport const SEND_RETRY_MAX_DELAY_MS = 30_000;\n\n/**\n * A fresh client-minted id for a command the client correlates with its answer (a send's\n * `clientMessageId`, a mark-read's `requestId`). Random, so two tabs never collide.\n */\nexport function newCorrelationId(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;\n  if (c?.randomUUID) return c.randomUUID();\n  return `cid-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n}\n"]}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/realtime/shared.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,yEAAyE;IAChE,kBAAkB,GAAG,IAAI,CAAC;IACnC,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,OAAO,CACL,GAAG,YAAY,qBAAqB;QACpC,CAAC,OAAO,GAAG,KAAK,QAAQ;YACtB,GAAG,KAAK,IAAI;YACX,GAAwC,CAAC,kBAAkB,KAAK,IAAI,CAAC,CACzE,CAAC;AACJ,CAAC;AAQD,MAAM,CAAC,MAAM,aAAa,GAAoB;IAC5C,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC;IAC1C,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IACpC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CACtB,CAAC;AAIF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,eAAe;CACtB,CAAC;AAIX,MAAM,UAAU,mBAAmB,CAAC,IAA+B;IACjE,OAAO,IAAI,KAAK,mBAAmB,CAAC,OAAO,IAAI,IAAI,KAAK,mBAAmB,CAAC,aAAa,CAAC;AAC5F,CAAC;AAED,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC;AAE1D,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C,uFAAuF;AACvF,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAElD,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C,MAAM,UAAU,gBAAgB;IAC9B,MAAM,CAAC,GAAI,UAAyD,CAAC,MAAM,CAAC;IAC5E,IAAI,CAAC,EAAE,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IACzC,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC","sourcesContent":["export type GrantProvider = () => Promise<string>;\n\nexport class ChatAccessDeniedError extends Error {\n  // Duck-typed so detection survives module-realm and re-throw boundaries.\n  readonly isChatAccessDenied = true;\n  constructor(message = 'Chat access denied') {\n    super(message);\n    this.name = 'ChatAccessDeniedError';\n  }\n}\n\nexport function isChatAccessDeniedError(err: unknown): err is ChatAccessDeniedError {\n  return (\n    err instanceof ChatAccessDeniedError ||\n    (typeof err === 'object' &&\n      err !== null &&\n      (err as { isChatAccessDenied?: unknown }).isChatAccessDenied === true)\n  );\n}\n\nexport interface TransportTimers {\n  setTimeout: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;\n  clearTimeout: (h: ReturnType<typeof setTimeout>) => void;\n  now: () => number;\n}\n\nexport const defaultTimers: TransportTimers = {\n  setTimeout: (fn, ms) => setTimeout(fn, ms),\n  clearTimeout: (h) => clearTimeout(h),\n  now: () => Date.now(),\n};\n\nexport type RealtimeStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';\n\nexport const TERMINAL_ERROR_CODE = {\n  REVOKED: 'revoked',\n  ACCESS_DENIED: 'access-denied',\n} as const;\n\nexport type TerminalErrorCode = (typeof TERMINAL_ERROR_CODE)[keyof typeof TERMINAL_ERROR_CODE];\n\nexport function isTerminalErrorCode(code: string | null | undefined): code is TerminalErrorCode {\n  return code === TERMINAL_ERROR_CODE.REVOKED || code === TERMINAL_ERROR_CODE.ACCESS_DENIED;\n}\n\nexport const CHAT_INITIAL_LOAD_FAILURE_BUDGET_MS = 15_000;\n\nexport const MAX_PENDING_SEND_ATTEMPTS = 5;\n\nexport const PENDING_SEND_MAX_AGE_MS = 60_000;\n\n// Covers the backend's projection window, which the five-attempt cap (~10 s) does not.\nexport const SERVER_RETRYABLE_MAX_AGE_MS = 90_000;\n\nexport const SEND_RETRY_MIN_DELAY_MS = 250;\nexport const SEND_RETRY_MAX_DELAY_MS = 30_000;\n\nexport function newCorrelationId(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;\n  if (c?.randomUUID) return c.randomUUID();\n  return `cid-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n}\n"]}

package/dist/realtime/socket.d.ts

@@ -1,33 +1,18 @@
-/** Lifecycle events a socket surfaces to its owning client. */
 export interface SocketHandlers {
     onOpen: () => void;
     onMessage: (data: string) => void;
-    /** code/reason from the close frame (4401/4403/4408/4413/4429/1013 or transport codes). */
     onClose: (code: number, reason: string) => void;
     onError: () => void;
 }
-/** The transport-neutral socket the clients use. A mock implements the same shape in tests. */
 export interface RealtimeSocket {
-    /** Queue/send a text frame. No-op if not open. */
     send(data: string): void;
-    /** Close the socket with an optional app code + reason. Idempotent. */
     close(code?: number, reason?: string): void;
-    /** True once the underlying transport is OPEN (ready to send). */
     readonly isOpen: boolean;
 }
-/**
- * A factory that opens a socket to `url`, offering the chat subprotocol + the
- * grant token, and wires the handlers. Injected into the transport so tests
- * substitute a mock. The default factory uses the global `WebSocket`.
- */
 export type SocketFactory = (args: {
     url: string;
     grantToken: string;
     handlers: SocketHandlers;
 }) => RealtimeSocket;
-/**
- * The default browser socket factory. Offers `[CHAT_SUBPROTOCOL, grantToken]` as the
- * subprotocol list so the grant rides in `Sec-WebSocket-Protocol`, never the URL.
- */
 export declare const browserSocketFactory: SocketFactory;
 //# sourceMappingURL=socket.d.ts.map

package/dist/realtime/socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AAYA,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,2FAA2F;IAC3F,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uEAAuE;IACvE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;CAC1B,KAAK,cAAc,CAAC;AAiBrB;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAyBlC,CAAC"}
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;CAC1B,KAAK,cAAc,CAAC;AAiBrB,eAAO,MAAM,oBAAoB,EAAE,aAyBlC,CAAC"}

package/dist/realtime/socket.js

@@ -1,9 +1,5 @@
 import { CHAT_SUBPROTOCOL } from '@ttt-productions/chat-schemas';
 const WS_OPEN = 1;
-/**
- * The default browser socket factory. Offers `[CHAT_SUBPROTOCOL, grantToken]` as the
- * subprotocol list so the grant rides in `Sec-WebSocket-Protocol`, never the URL.
- */
 export const browserSocketFactory = ({ url, grantToken, handlers }) => {
     const Ctor = globalThis.WebSocket;
     if (!Ctor)

package/dist/realtime/socket.js.map

@@ -1 +1 @@
-{"version":3,"file":"socket.js","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAuDjE,MAAM,OAAO,GAAG,CAAC,CAAC;AAElB;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkB,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE;IACnF,MAAM,IAAI,GAAI,UAA4C,CAAC,SAAS,CAAC;IACrE,IAAI,CAAC,IAAI;QACP,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC,CAAC;IACzD,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;IACpC,EAAE,CAAC,SAAS,GAAG,CAAC,EAAE,EAAE,EAAE,CACpB,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1D,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;IACtC,OAAO;QACL,IAAI,CAAC,IAAY;YACf,IAAI,EAAE,CAAC,UAAU,KAAK,OAAO;gBAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;QACD,KAAK,CAAC,IAAa,EAAE,MAAe;YAClC,IAAI,CAAC;gBACH,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,4BAA4B;YAC9B,CAAC;QACH,CAAC;QACD,IAAI,MAAM;YACR,OAAO,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { CHAT_SUBPROTOCOL } from '@ttt-productions/chat-schemas';\n// The minimal socket abstraction the realtime clients drive, plus the default\n// browser-WebSocket factory. Injectable so unit tests pass a MOCK socket and no\n// real network is touched.\n//\n// Contract A transport: the grant token is offered as the SECOND WebSocket\n// subprotocol — `Sec-WebSocket-Protocol: <CHAT_SUBPROTOCOL>, <grant-token>` —\n// never in the URL (tokens never appear in URLs; Contract A). The browser sets\n// that header from `new WebSocket(url, [CHAT_SUBPROTOCOL, grantToken])`. The\n// worker validates cookie + grant + Origin BEFORE accept and echoes back only\n// CHAT_SUBPROTOCOL.\n\n/** Lifecycle events a socket surfaces to its owning client. */\nexport interface SocketHandlers {\n  onOpen: () => void;\n  onMessage: (data: string) => void;\n  /** code/reason from the close frame (4401/4403/4408/4413/4429/1013 or transport codes). */\n  onClose: (code: number, reason: string) => void;\n  onError: () => void;\n}\n\n/** The transport-neutral socket the clients use. A mock implements the same shape in tests. */\nexport interface RealtimeSocket {\n  /** Queue/send a text frame. No-op if not open. */\n  send(data: string): void;\n  /** Close the socket with an optional app code + reason. Idempotent. */\n  close(code?: number, reason?: string): void;\n  /** True once the underlying transport is OPEN (ready to send). */\n  readonly isOpen: boolean;\n}\n\n/**\n * A factory that opens a socket to `url`, offering the chat subprotocol + the\n * grant token, and wires the handlers. Injected into the transport so tests\n * substitute a mock. The default factory uses the global `WebSocket`.\n */\nexport type SocketFactory = (args: {\n  url: string;\n  grantToken: string;\n  handlers: SocketHandlers;\n}) => RealtimeSocket;\n\n/** A WebSocket-like minimal surface (so we don't hard-depend on lib.dom in node-safe builds). */\ninterface MinimalWebSocket {\n  send(data: string): void;\n  close(code?: number, reason?: string): void;\n  readyState: number;\n  onopen: ((ev: unknown) => void) | null;\n  onmessage: ((ev: { data: unknown }) => void) | null;\n  onclose: ((ev: { code: number; reason: string }) => void) | null;\n  onerror: ((ev: unknown) => void) | null;\n}\n\ntype WebSocketCtor = new (url: string, protocols?: string | string[]) => MinimalWebSocket;\n\nconst WS_OPEN = 1;\n\n/**\n * The default browser socket factory. Offers `[CHAT_SUBPROTOCOL, grantToken]` as the\n * subprotocol list so the grant rides in `Sec-WebSocket-Protocol`, never the URL.\n */\nexport const browserSocketFactory: SocketFactory = ({ url, grantToken, handlers }) => {\n  const Ctor = (globalThis as { WebSocket?: WebSocketCtor }).WebSocket;\n  if (!Ctor)\n    throw new Error('[chat-realtime] no global WebSocket available; inject a SocketFactory');\n  const ws = new Ctor(url, [CHAT_SUBPROTOCOL, grantToken]);\n  ws.onopen = () => handlers.onOpen();\n  ws.onmessage = (ev) =>\n    handlers.onMessage(typeof ev.data === 'string' ? ev.data : String(ev.data));\n  ws.onclose = (ev) => handlers.onClose(ev.code, ev.reason);\n  ws.onerror = () => handlers.onError();\n  return {\n    send(data: string) {\n      if (ws.readyState === WS_OPEN) ws.send(data);\n    },\n    close(code?: number, reason?: string) {\n      try {\n        ws.close(code, reason);\n      } catch {\n        /* already closing/closed */\n      }\n    },\n    get isOpen() {\n      return ws.readyState === WS_OPEN;\n    },\n  };\n};\n"]}
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAkCjE,MAAM,OAAO,GAAG,CAAC,CAAC;AAElB,MAAM,CAAC,MAAM,oBAAoB,GAAkB,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE;IACnF,MAAM,IAAI,GAAI,UAA4C,CAAC,SAAS,CAAC;IACrE,IAAI,CAAC,IAAI;QACP,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC,CAAC;IACzD,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;IACpC,EAAE,CAAC,SAAS,GAAG,CAAC,EAAE,EAAE,EAAE,CACpB,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1D,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;IACtC,OAAO;QACL,IAAI,CAAC,IAAY;YACf,IAAI,EAAE,CAAC,UAAU,KAAK,OAAO;gBAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;QACD,KAAK,CAAC,IAAa,EAAE,MAAe;YAClC,IAAI,CAAC;gBACH,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,4BAA4B;YAC9B,CAAC;QACH,CAAC;QACD,IAAI,MAAM;YACR,OAAO,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { CHAT_SUBPROTOCOL } from '@ttt-productions/chat-schemas';\n\nexport interface SocketHandlers {\n  onOpen: () => void;\n  onMessage: (data: string) => void;\n  onClose: (code: number, reason: string) => void;\n  onError: () => void;\n}\n\nexport interface RealtimeSocket {\n  send(data: string): void;\n  close(code?: number, reason?: string): void;\n  readonly isOpen: boolean;\n}\n\nexport type SocketFactory = (args: {\n  url: string;\n  grantToken: string;\n  handlers: SocketHandlers;\n}) => RealtimeSocket;\n\n// Structural, so node-safe builds need no lib.dom.\ninterface MinimalWebSocket {\n  send(data: string): void;\n  close(code?: number, reason?: string): void;\n  readyState: number;\n  onopen: ((ev: unknown) => void) | null;\n  onmessage: ((ev: { data: unknown }) => void) | null;\n  onclose: ((ev: { code: number; reason: string }) => void) | null;\n  onerror: ((ev: unknown) => void) | null;\n}\n\ntype WebSocketCtor = new (url: string, protocols?: string | string[]) => MinimalWebSocket;\n\nconst WS_OPEN = 1;\n\nexport const browserSocketFactory: SocketFactory = ({ url, grantToken, handlers }) => {\n  const Ctor = (globalThis as { WebSocket?: WebSocketCtor }).WebSocket;\n  if (!Ctor)\n    throw new Error('[chat-realtime] no global WebSocket available; inject a SocketFactory');\n  const ws = new Ctor(url, [CHAT_SUBPROTOCOL, grantToken]);\n  ws.onopen = () => handlers.onOpen();\n  ws.onmessage = (ev) =>\n    handlers.onMessage(typeof ev.data === 'string' ? ev.data : String(ev.data));\n  ws.onclose = (ev) => handlers.onClose(ev.code, ev.reason);\n  ws.onerror = () => handlers.onError();\n  return {\n    send(data: string) {\n      if (ws.readyState === WS_OPEN) ws.send(data);\n    },\n    close(code?: number, reason?: string) {\n      try {\n        ws.close(code, reason);\n      } catch {\n        /* already closing/closed */\n      }\n    },\n    get isOpen() {\n      return ws.readyState === WS_OPEN;\n    },\n  };\n};\n"]}

package/dist/realtime/transport.d.ts

@@ -4,14 +4,8 @@ import { type SocketFactory } from './socket.js';
 import type { GrantProvider, TransportTimers } from './shared.js';
 import type { ChatClientDiagnosticsOption } from './diagnostics.js';
 import type { ChatConversationRef } from '@ttt-productions/chat-schemas';
-/**
- * Everything the channel transport needs. The app supplies `grantProvider`
- * (its `mintChatGrant` callable, channel scope) + `endpoint`; `socketFactory`
- * defaults to the real browser WebSocket and is overridden in tests.
- */
 export interface RealtimeTransportConfig {
     endpoint: string;
-    /** The conversation the socket is for, as the app maps it onto the neutral reference. */
     channelRef: ChatConversationRef;
     threadId: string;
     currentUserId: string;
@@ -19,35 +13,19 @@ export interface RealtimeTransportConfig {
     socketFactory?: SocketFactory;
     timers?: TransportTimers;
     reconnect?: ChannelClientConfig['reconnect'];
-    /**
-     * OPT-IN structured client diagnostics, forwarded to the ChannelClient. Absent
-     * or `false` (the default) changes nothing and costs one nullish check; `true`
-     * emits one single-line `console.debug` entry per client DECISION with a stable
-     * `chat_client_*` event name; a function routes those entries into the app's own
-     * logger. Content-free by construction (ids/seqs/states/counts/codes only).
-     */
     diagnostics?: ChatClientDiagnosticsOption;
 }
-/**
- * The opaque realtime client handle stored on `ChatRealtimeTransportConfig.client`.
- * The UI hook (`useRealtimeChatMessages`) drives it; the UI never reaches into the
- * socket directly.
- */
 export interface RealtimeChatClient {
     readonly channel: ChannelClient;
     readonly channelRef: ChatConversationRef;
     readonly currentUserId: string;
     connect(): Promise<void>;
-    /** Retry the connection now (the first-open failure's Retry) — see `ChannelClient.retryNow`. */
     retry(): void;
-    /** Tear down every socket (auth-user switch / unmount). Idempotent. */
     close(): void;
     getState(): ChannelClientState;
     subscribe(fn: (s: ChannelClientState) => void): () => void;
 }
-/** Create the per-thread realtime client (the value placed on `config.realtime.client`). */
 export declare function createRealtimeChatClient(config: RealtimeTransportConfig): RealtimeChatClient;
-/** Create the per-USER inbox client (mount once at the dock; not per-thread). */
 export declare function createInboxClient(config: {
     endpoint: string;
     currentUserId: string;
@@ -55,7 +33,6 @@ export declare function createInboxClient(config: {
     socketFactory?: SocketFactory;
     timers?: TransportTimers;
     reconnect?: InboxClientConfig['reconnect'];
-    /** OPT-IN structured diagnostics, forwarded to the InboxClient (default OFF). */
     diagnostics?: ChatClientDiagnosticsOption;
 }): InboxClient;
 //# sourceMappingURL=transport.d.ts.map

package/dist/realtime/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/realtime/transport.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,UAAU,EAAE,mBAAmB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,gGAAgG;IAChG,KAAK,IAAI,IAAI,CAAC;IACd,uEAAuE;IACvE,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,IAAI,kBAAkB,CAAC;IAC/B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5D;AAED,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,kBAAkB,CAsB5F;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC3C,iFAAiF;IACjF,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C,GAAG,WAAW,CAUd"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/realtime/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,mBAAmB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,IAAI,kBAAkB,CAAC;IAC/B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5D;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,kBAAkB,CAsB5F;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C,GAAG,WAAW,CAUd"}

package/dist/realtime/transport.js

@@ -1,18 +1,6 @@
-// The realtime transport HANDLE the chat-react config carries on the `realtime`
-// transport (`ChatRealtimeTransportConfig.client`). It owns:
-//   - a ChannelClient for the active thread (send/read/typing/presence/history)
-//   - the grant-mint wiring (channel scope) via the injected grantProvider
-//   - auth-user-switch teardown (close every socket before connecting as a new uid)
-//
-// The INBOX socket is created SEPARATELY (one per user, app-wide) via
-// `createInboxClient` — it is not tied to a single thread, so the app owns its
-// lifetime (mount it once at the dock, not per ChatShell). This keeps the channel
-// transport (per-thread) and the inbox transport (per-user) cleanly split, exactly
-// as the worker splits Channel DOs from the Inbox DO.
 import { ChannelClient, } from './channel-client.js';
 import { InboxClient } from './inbox-client.js';
 import { browserSocketFactory } from './socket.js';
-/** Create the per-thread realtime client (the value placed on `config.realtime.client`). */
 export function createRealtimeChatClient(config) {
     const channel = new ChannelClient({
         endpoint: config.endpoint,
@@ -35,7 +23,6 @@ export function createRealtimeChatClient(config) {
         subscribe: (fn) => channel.subscribe(fn),
     };
 }
-/** Create the per-USER inbox client (mount once at the dock; not per-thread). */
 export function createInboxClient(config) {
     return new InboxClient({
         endpoint: config.endpoint,

package/dist/realtime/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/realtime/transport.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6DAA6D;AAC7D,gFAAgF;AAChF,2EAA2E;AAC3E,oFAAoF;AACpF,EAAE;AACF,sEAAsE;AACtE,+EAA+E;AAC/E,kFAAkF;AAClF,mFAAmF;AACnF,sDAAsD;AAEtD,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAA0B,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAsB,MAAM,aAAa,CAAC;AAgDvE,4FAA4F;AAC5F,MAAM,UAAU,wBAAwB,CAAC,MAA+B;IACtE,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC;QAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,oBAAoB;QAC3D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;QAChC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;QAC/B,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;QAClC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,MASjC;IACC,OAAO,IAAI,WAAW,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,oBAAoB;QAC3D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// The realtime transport HANDLE the chat-react config carries on the `realtime`\n// transport (`ChatRealtimeTransportConfig.client`). It owns:\n//   - a ChannelClient for the active thread (send/read/typing/presence/history)\n//   - the grant-mint wiring (channel scope) via the injected grantProvider\n//   - auth-user-switch teardown (close every socket before connecting as a new uid)\n//\n// The INBOX socket is created SEPARATELY (one per user, app-wide) via\n// `createInboxClient` — it is not tied to a single thread, so the app owns its\n// lifetime (mount it once at the dock, not per ChatShell). This keeps the channel\n// transport (per-thread) and the inbox transport (per-user) cleanly split, exactly\n// as the worker splits Channel DOs from the Inbox DO.\n\nimport {\n  ChannelClient,\n  type ChannelClientConfig,\n  type ChannelClientState,\n} from './channel-client.js';\nimport { InboxClient, type InboxClientConfig } from './inbox-client.js';\nimport { browserSocketFactory, type SocketFactory } from './socket.js';\nimport type { GrantProvider, TransportTimers } from './shared.js';\nimport type { ChatClientDiagnosticsOption } from './diagnostics.js';\nimport type { ChatConversationRef } from '@ttt-productions/chat-schemas';\n\n/**\n * Everything the channel transport needs. The app supplies `grantProvider`\n * (its `mintChatGrant` callable, channel scope) + `endpoint`; `socketFactory`\n * defaults to the real browser WebSocket and is overridden in tests.\n */\nexport interface RealtimeTransportConfig {\n  endpoint: string;\n  /** The conversation the socket is for, as the app maps it onto the neutral reference. */\n  channelRef: ChatConversationRef;\n  threadId: string;\n  currentUserId: string;\n  grantProvider: GrantProvider;\n  socketFactory?: SocketFactory;\n  timers?: TransportTimers;\n  reconnect?: ChannelClientConfig['reconnect'];\n  /**\n   * OPT-IN structured client diagnostics, forwarded to the ChannelClient. Absent\n   * or `false` (the default) changes nothing and costs one nullish check; `true`\n   * emits one single-line `console.debug` entry per client DECISION with a stable\n   * `chat_client_*` event name; a function routes those entries into the app's own\n   * logger. Content-free by construction (ids/seqs/states/counts/codes only).\n   */\n  diagnostics?: ChatClientDiagnosticsOption;\n}\n\n/**\n * The opaque realtime client handle stored on `ChatRealtimeTransportConfig.client`.\n * The UI hook (`useRealtimeChatMessages`) drives it; the UI never reaches into the\n * socket directly.\n */\nexport interface RealtimeChatClient {\n  readonly channel: ChannelClient;\n  readonly channelRef: ChatConversationRef;\n  readonly currentUserId: string;\n  connect(): Promise<void>;\n  /** Retry the connection now (the first-open failure's Retry) — see `ChannelClient.retryNow`. */\n  retry(): void;\n  /** Tear down every socket (auth-user switch / unmount). Idempotent. */\n  close(): void;\n  getState(): ChannelClientState;\n  subscribe(fn: (s: ChannelClientState) => void): () => void;\n}\n\n/** Create the per-thread realtime client (the value placed on `config.realtime.client`). */\nexport function createRealtimeChatClient(config: RealtimeTransportConfig): RealtimeChatClient {\n  const channel = new ChannelClient({\n    endpoint: config.endpoint,\n    threadId: config.threadId,\n    currentUserId: config.currentUserId,\n    grantProvider: config.grantProvider,\n    socketFactory: config.socketFactory ?? browserSocketFactory,\n    timers: config.timers,\n    reconnect: config.reconnect,\n    diagnostics: config.diagnostics,\n  });\n\n  return {\n    channel,\n    channelRef: config.channelRef,\n    currentUserId: config.currentUserId,\n    connect: () => channel.connect(),\n    retry: () => channel.retryNow(),\n    close: () => channel.close(),\n    getState: () => channel.getState(),\n    subscribe: (fn) => channel.subscribe(fn),\n  };\n}\n\n/** Create the per-USER inbox client (mount once at the dock; not per-thread). */\nexport function createInboxClient(config: {\n  endpoint: string;\n  currentUserId: string;\n  grantProvider: GrantProvider;\n  socketFactory?: SocketFactory;\n  timers?: TransportTimers;\n  reconnect?: InboxClientConfig['reconnect'];\n  /** OPT-IN structured diagnostics, forwarded to the InboxClient (default OFF). */\n  diagnostics?: ChatClientDiagnosticsOption;\n}): InboxClient {\n  return new InboxClient({\n    endpoint: config.endpoint,\n    currentUserId: config.currentUserId,\n    grantProvider: config.grantProvider,\n    socketFactory: config.socketFactory ?? browserSocketFactory,\n    timers: config.timers,\n    reconnect: config.reconnect,\n    diagnostics: config.diagnostics,\n  });\n}\n"]}
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/realtime/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAA0B,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAsB,MAAM,aAAa,CAAC;AA4BvE,MAAM,UAAU,wBAAwB,CAAC,MAA+B;IACtE,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC;QAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,oBAAoB;QAC3D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;QAChC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;QAC/B,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;QAC5B,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;QAClC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAQjC;IACC,OAAO,IAAI,WAAW,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,oBAAoB;QAC3D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import {\n  ChannelClient,\n  type ChannelClientConfig,\n  type ChannelClientState,\n} from './channel-client.js';\nimport { InboxClient, type InboxClientConfig } from './inbox-client.js';\nimport { browserSocketFactory, type SocketFactory } from './socket.js';\nimport type { GrantProvider, TransportTimers } from './shared.js';\nimport type { ChatClientDiagnosticsOption } from './diagnostics.js';\nimport type { ChatConversationRef } from '@ttt-productions/chat-schemas';\n\nexport interface RealtimeTransportConfig {\n  endpoint: string;\n  channelRef: ChatConversationRef;\n  threadId: string;\n  currentUserId: string;\n  grantProvider: GrantProvider;\n  socketFactory?: SocketFactory;\n  timers?: TransportTimers;\n  reconnect?: ChannelClientConfig['reconnect'];\n  diagnostics?: ChatClientDiagnosticsOption;\n}\n\nexport interface RealtimeChatClient {\n  readonly channel: ChannelClient;\n  readonly channelRef: ChatConversationRef;\n  readonly currentUserId: string;\n  connect(): Promise<void>;\n  retry(): void;\n  close(): void;\n  getState(): ChannelClientState;\n  subscribe(fn: (s: ChannelClientState) => void): () => void;\n}\n\nexport function createRealtimeChatClient(config: RealtimeTransportConfig): RealtimeChatClient {\n  const channel = new ChannelClient({\n    endpoint: config.endpoint,\n    threadId: config.threadId,\n    currentUserId: config.currentUserId,\n    grantProvider: config.grantProvider,\n    socketFactory: config.socketFactory ?? browserSocketFactory,\n    timers: config.timers,\n    reconnect: config.reconnect,\n    diagnostics: config.diagnostics,\n  });\n\n  return {\n    channel,\n    channelRef: config.channelRef,\n    currentUserId: config.currentUserId,\n    connect: () => channel.connect(),\n    retry: () => channel.retryNow(),\n    close: () => channel.close(),\n    getState: () => channel.getState(),\n    subscribe: (fn) => channel.subscribe(fn),\n  };\n}\n\nexport function createInboxClient(config: {\n  endpoint: string;\n  currentUserId: string;\n  grantProvider: GrantProvider;\n  socketFactory?: SocketFactory;\n  timers?: TransportTimers;\n  reconnect?: InboxClientConfig['reconnect'];\n  diagnostics?: ChatClientDiagnosticsOption;\n}): InboxClient {\n  return new InboxClient({\n    endpoint: config.endpoint,\n    currentUserId: config.currentUserId,\n    grantProvider: config.grantProvider,\n    socketFactory: config.socketFactory ?? browserSocketFactory,\n    timers: config.timers,\n    reconnect: config.reconnect,\n    diagnostics: config.diagnostics,\n  });\n}\n"]}

package/dist/realtime/useRealtimeChatMessages.d.ts

@@ -8,34 +8,17 @@ export type UseRealtimeChatMessagesResult = {
     fetchOlder: () => Promise<void>;
     hasOlder: boolean;
     isFetchingOlder: boolean;
-    /** True once the first open has failed (see `ChannelClientState.initialLoadFailed`). */
     initialLoadFailed: boolean;
-    /** The channel is current (see `ChannelClientState.isSynced`): act on its terms only while true. */
     isSynced: boolean;
-    /** Retry the connection now — the first-open failure's Retry. */
     retry: () => void;
-    /** Realtime extras (not present on the firestore result) — optional for the UI. */
     status: ChannelClientState['status'];
-    /** The last structured error code the DO sent (e.g. a close reason). Drives the
-     *  disconnected-banner detail (R13). */
     lastErrorCode: string | null;
     typing: string[];
     presence: string[];
-    /** Returns false when the socket was closed and nothing was sent (C-B8) — the caller keeps the composer text. */
     send: (text: string) => boolean;
-    /** Retry a failed/un-acked send by its ORIGINAL clientMessageId (read from the
-     *  failed row's `meta.clientMessageId`) — the transport re-queues the tracked
-     *  pending send with the SAME id so the DO's send-idempotency dedups any copy
-     *  that already landed. Returns false for an unknown id (already acked/
-     *  reconciled). ChatShell wires this to MessageItemDefault's failed-bubble
-     *  retry affordance by default. */
     retrySend: (clientMessageId: string) => boolean;
-    /** Returns whether the ack frame was sent (false on a closed socket) so the caller advances its local cursor only on success (M2). */
     readAck: (readSeq: number, focused: boolean) => boolean;
     signalTyping: () => void;
-    /** Watched-only presence (R14): the UI subscribes ONLY while a member-list / online
-     *  indicator is open, and unsubscribes when it closes, so an unwatched channel runs
-     *  zero presence alarms. `presence` stays empty until subscribed. */
     presenceSubscribe: () => void;
     presenceUnsubscribe: () => void;
 };

package/dist/realtime/useRealtimeChatMessages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRealtimeChatMessages.d.ts","sourceRoot":"","sources":["../../src/realtime/useRealtimeChatMessages.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAI9D,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oGAAoG;IACpG,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,mFAAmF;IACnF,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACrC;4CACwC;IACxC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iHAAiH;IACjH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC;;;;;uCAKmC;IACnC,SAAS,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,sIAAsI;IACtI,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;IACxD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB;;yEAEqE;IACrE,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,6BAA6B,CAoFjG"}
+{"version":3,"file":"useRealtimeChatMessages.d.ts","sourceRoot":"","sources":["../../src/realtime/useRealtimeChatMessages.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAI9D,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACrC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,SAAS,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;IACxD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,6BAA6B,CAuEjG"}

package/dist/realtime/useRealtimeChatMessages.js

@@ -1,26 +1,14 @@
 'use client';
-// React hook for the REALTIME transport, returning the SAME shape as
-// `useChatMessages` (the firestore path) so `ChatShell` is transport-agnostic.
-// It SUBSCRIBES to a `RealtimeChatClient`'s observable state. It does NOT own the
-// socket lifecycle: the caller (the app hook that CREATES the client, e.g.
-// `useRealtimeChannelClient`) is the single connect/close owner (C-B7) — connecting
-// here too opened a second WebSocket. The client instance is owned by the caller
-// (passed via config) so its identity is the subscription key — a new client for a
-// new uid replaces the old one (Contract A auth-user-switch teardown happens in the
-// owning hook).
 import * as React from 'react';
 import { useOptionalChatNameResolver } from '../context/ChatNameResolverContext.js';
 import { newCorrelationId } from './shared.js';
 export function useRealtimeChatMessages(client) {
     const [state, setState] = React.useState(() => client.getState());
-    // Subscribe only; the owning hook drives connect/close (single lifecycle owner, C-B7).
-    // Re-subscribes on client identity change (auth-user switch).
     React.useEffect(() => {
         const unsub = client.subscribe(setState);
         setState(client.getState());
         return unsub;
     }, [client]);
-    // Pre-warm the name cache for visible senders (parity with the firestore hook).
     const resolverCtx = useOptionalChatNameResolver();
     const senderIds = React.useMemo(() => {
         const set = new Set();
@@ -46,19 +34,9 @@ export function useRealtimeChatMessages(client) {
     const presenceSubscribe = React.useCallback(() => client.channel.presenceSubscribe(), [client]);
     const presenceUnsubscribe = React.useCallback(() => client.channel.presenceUnsubscribe(), [client]);
     return {
-        // On the realtime transport DATA ACCESS is enforced by the DO grant, so the hook
-        // is "allowed" client-side UNLESS the grant provider surfaced a TERMINAL access
-        // denial (ChatAccessDeniedError → stable 'access-denied' code). That single case
-        // maps to allowed:false so ChatShell renders its no-access surface instead of an
-        // eternal loader; a transient close / 4403-revoke keeps allowed:true and rides the
-        // reconnect/disconnected banner. Otherwise accessMode is presentation-only here.
         allowed: state.lastErrorCode !== 'access-denied',
-        // Derive initial loading from authoritative-data completion, NOT connection status:
-        // a socket can be 'open' with no snapshot yet, and a post-load reconnect must not
-        // fall back into the opening state. `hasLoadedInitialData` encodes the full table.
         isInitialLoading: !state.hasLoadedInitialData,
         initialLoadFailed: state.initialLoadFailed,
-        // Current: open, loaded, and resynced since this socket opened (never sticky).
         isSynced: state.isSynced,
         retry,
         messages: state.messages,

package/dist/realtime/useRealtimeChatMessages.js.map

@@ -1 +1 @@
-{"version":3,"file":"useRealtimeChatMessages.js","sourceRoot":"","sources":["../../src/realtime/useRealtimeChatMessages.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\n// React hook for the REALTIME transport, returning the SAME shape as\n// `useChatMessages` (the firestore path) so `ChatShell` is transport-agnostic.\n// It SUBSCRIBES to a `RealtimeChatClient`'s observable state. It does NOT own the\n// socket lifecycle: the caller (the app hook that CREATES the client, e.g.\n// `useRealtimeChannelClient`) is the single connect/close owner (C-B7) — connecting\n// here too opened a second WebSocket. The client instance is owned by the caller\n// (passed via config) so its identity is the subscription key — a new client for a\n// new uid replaces the old one (Contract A auth-user-switch teardown happens in the\n// owning hook).\n\nimport * as React from 'react';\nimport type { ChatMessageV1 } from '@ttt-productions/chat-core';\nimport type { RealtimeChatClient } from './transport.js';\nimport type { ChannelClientState } from './channel-client.js';\nimport { useOptionalChatNameResolver } from '../context/ChatNameResolverContext.js';\nimport { newCorrelationId } from './shared.js';\n\nexport type UseRealtimeChatMessagesResult = {\n  allowed: boolean;\n  isInitialLoading: boolean;\n  messages: ChatMessageV1[];\n  fetchOlder: () => Promise<void>;\n  hasOlder: boolean;\n  isFetchingOlder: boolean;\n  /** True once the first open has failed (see `ChannelClientState.initialLoadFailed`). */\n  initialLoadFailed: boolean;\n  /** The channel is current (see `ChannelClientState.isSynced`): act on its terms only while true. */\n  isSynced: boolean;\n  /** Retry the connection now — the first-open failure's Retry. */\n  retry: () => void;\n  /** Realtime extras (not present on the firestore result) — optional for the UI. */\n  status: ChannelClientState['status'];\n  /** The last structured error code the DO sent (e.g. a close reason). Drives the\n   *  disconnected-banner detail (R13). */\n  lastErrorCode: string | null;\n  typing: string[];\n  presence: string[];\n  /** Returns false when the socket was closed and nothing was sent (C-B8) — the caller keeps the composer text. */\n  send: (text: string) => boolean;\n  /** Retry a failed/un-acked send by its ORIGINAL clientMessageId (read from the\n   *  failed row's `meta.clientMessageId`) — the transport re-queues the tracked\n   *  pending send with the SAME id so the DO's send-idempotency dedups any copy\n   *  that already landed. Returns false for an unknown id (already acked/\n   *  reconciled). ChatShell wires this to MessageItemDefault's failed-bubble\n   *  retry affordance by default. */\n  retrySend: (clientMessageId: string) => boolean;\n  /** Returns whether the ack frame was sent (false on a closed socket) so the caller advances its local cursor only on success (M2). */\n  readAck: (readSeq: number, focused: boolean) => boolean;\n  signalTyping: () => void;\n  /** Watched-only presence (R14): the UI subscribes ONLY while a member-list / online\n   *  indicator is open, and unsubscribes when it closes, so an unwatched channel runs\n   *  zero presence alarms. `presence` stays empty until subscribed. */\n  presenceSubscribe: () => void;\n  presenceUnsubscribe: () => void;\n};\n\nexport function useRealtimeChatMessages(client: RealtimeChatClient): UseRealtimeChatMessagesResult {\n  const [state, setState] = React.useState<ChannelClientState>(() => client.getState());\n\n  // Subscribe only; the owning hook drives connect/close (single lifecycle owner, C-B7).\n  // Re-subscribes on client identity change (auth-user switch).\n  React.useEffect(() => {\n    const unsub = client.subscribe(setState);\n    setState(client.getState());\n    return unsub;\n  }, [client]);\n\n  // Pre-warm the name cache for visible senders (parity with the firestore hook).\n  const resolverCtx = useOptionalChatNameResolver();\n  const senderIds = React.useMemo(() => {\n    const set = new Set<string>();\n    for (const m of state.messages) {\n      set.add(m.senderId);\n      for (const uid of m.referencedUids ?? []) set.add(uid);\n    }\n    return Array.from(set);\n  }, [state.messages]);\n\n  React.useEffect(() => {\n    if (resolverCtx?.prewarm && senderIds.length > 0) resolverCtx.prewarm(senderIds);\n  }, [resolverCtx, senderIds]);\n\n  const fetchOlder = React.useCallback(async () => {\n    client.channel.fetchOlder();\n  }, [client]);\n\n  const send = React.useCallback(\n    (text: string): boolean => client.channel.send({ clientMessageId: newCorrelationId(), text }),\n    [client],\n  );\n\n  const retrySend = React.useCallback(\n    (clientMessageId: string): boolean => client.channel.retrySend(clientMessageId),\n    [client],\n  );\n\n  const readAck = React.useCallback(\n    (readSeq: number, focused: boolean) => client.channel.readAck(readSeq, focused),\n    [client],\n  );\n\n  const signalTyping = React.useCallback(() => client.channel.typing(), [client]);\n  const retry = React.useCallback(() => client.retry(), [client]);\n  const presenceSubscribe = React.useCallback(() => client.channel.presenceSubscribe(), [client]);\n  const presenceUnsubscribe = React.useCallback(\n    () => client.channel.presenceUnsubscribe(),\n    [client],\n  );\n\n  return {\n    // On the realtime transport DATA ACCESS is enforced by the DO grant, so the hook\n    // is \"allowed\" client-side UNLESS the grant provider surfaced a TERMINAL access\n    // denial (ChatAccessDeniedError → stable 'access-denied' code). That single case\n    // maps to allowed:false so ChatShell renders its no-access surface instead of an\n    // eternal loader; a transient close / 4403-revoke keeps allowed:true and rides the\n    // reconnect/disconnected banner. Otherwise accessMode is presentation-only here.\n    allowed: state.lastErrorCode !== 'access-denied',\n    // Derive initial loading from authoritative-data completion, NOT connection status:\n    // a socket can be 'open' with no snapshot yet, and a post-load reconnect must not\n    // fall back into the opening state. `hasLoadedInitialData` encodes the full table.\n    isInitialLoading: !state.hasLoadedInitialData,\n    initialLoadFailed: state.initialLoadFailed,\n    // Current: open, loaded, and resynced since this socket opened (never sticky).\n    isSynced: state.isSynced,\n    retry,\n    messages: state.messages,\n    fetchOlder,\n    hasOlder: state.hasOlder,\n    isFetchingOlder: state.isFetchingOlder,\n    status: state.status,\n    lastErrorCode: state.lastErrorCode,\n    typing: state.typing,\n    presence: state.presence,\n    send,\n    retrySend,\n    readAck,\n    signalTyping,\n    presenceSubscribe,\n    presenceUnsubscribe,\n  };\n}\n"]}
+{"version":3,"file":"useRealtimeChatMessages.js","sourceRoot":"","sources":["../../src/realtime/useRealtimeChatMessages.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,EAAE,2BAA2B,EAAE,MAAM,uCAAuC,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAwB/C,MAAM,UAAU,uBAAuB,CAAC,MAA0B;IAChE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAqB,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEtF,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,MAAM,WAAW,GAAG,2BAA2B,EAAE,CAAC;IAClD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;QACnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC/B,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,cAAc,IAAI,EAAE;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAErB,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,IAAI,WAAW,EAAE,OAAO,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnF,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;IAE7B,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE;QAC9C,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IAC9B,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAC5B,CAAC,IAAY,EAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,eAAe,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,CAAC,EAC7F,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CACjC,CAAC,eAAuB,EAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC,EAC/E,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAC/B,CAAC,OAAe,EAAE,OAAgB,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAC/E,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChG,MAAM,mBAAmB,GAAG,KAAK,CAAC,WAAW,CAC3C,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAC1C,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,aAAa,KAAK,eAAe;QAChD,gBAAgB,EAAE,CAAC,KAAK,CAAC,oBAAoB;QAC7C,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU;QACV,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI;QACJ,SAAS;QACT,OAAO;QACP,YAAY;QACZ,iBAAiB;QACjB,mBAAmB;KACpB,CAAC;AACJ,CAAC","sourcesContent":["'use client';\n\nimport * as React from 'react';\nimport type { ChatMessageV1 } from '@ttt-productions/chat-core';\nimport type { RealtimeChatClient } from './transport.js';\nimport type { ChannelClientState } from './channel-client.js';\nimport { useOptionalChatNameResolver } from '../context/ChatNameResolverContext.js';\nimport { newCorrelationId } from './shared.js';\n\nexport type UseRealtimeChatMessagesResult = {\n  allowed: boolean;\n  isInitialLoading: boolean;\n  messages: ChatMessageV1[];\n  fetchOlder: () => Promise<void>;\n  hasOlder: boolean;\n  isFetchingOlder: boolean;\n  initialLoadFailed: boolean;\n  isSynced: boolean;\n  retry: () => void;\n  status: ChannelClientState['status'];\n  lastErrorCode: string | null;\n  typing: string[];\n  presence: string[];\n  send: (text: string) => boolean;\n  retrySend: (clientMessageId: string) => boolean;\n  readAck: (readSeq: number, focused: boolean) => boolean;\n  signalTyping: () => void;\n  presenceSubscribe: () => void;\n  presenceUnsubscribe: () => void;\n};\n\nexport function useRealtimeChatMessages(client: RealtimeChatClient): UseRealtimeChatMessagesResult {\n  const [state, setState] = React.useState<ChannelClientState>(() => client.getState());\n\n  React.useEffect(() => {\n    const unsub = client.subscribe(setState);\n    setState(client.getState());\n    return unsub;\n  }, [client]);\n\n  const resolverCtx = useOptionalChatNameResolver();\n  const senderIds = React.useMemo(() => {\n    const set = new Set<string>();\n    for (const m of state.messages) {\n      set.add(m.senderId);\n      for (const uid of m.referencedUids ?? []) set.add(uid);\n    }\n    return Array.from(set);\n  }, [state.messages]);\n\n  React.useEffect(() => {\n    if (resolverCtx?.prewarm && senderIds.length > 0) resolverCtx.prewarm(senderIds);\n  }, [resolverCtx, senderIds]);\n\n  const fetchOlder = React.useCallback(async () => {\n    client.channel.fetchOlder();\n  }, [client]);\n\n  const send = React.useCallback(\n    (text: string): boolean => client.channel.send({ clientMessageId: newCorrelationId(), text }),\n    [client],\n  );\n\n  const retrySend = React.useCallback(\n    (clientMessageId: string): boolean => client.channel.retrySend(clientMessageId),\n    [client],\n  );\n\n  const readAck = React.useCallback(\n    (readSeq: number, focused: boolean) => client.channel.readAck(readSeq, focused),\n    [client],\n  );\n\n  const signalTyping = React.useCallback(() => client.channel.typing(), [client]);\n  const retry = React.useCallback(() => client.retry(), [client]);\n  const presenceSubscribe = React.useCallback(() => client.channel.presenceSubscribe(), [client]);\n  const presenceUnsubscribe = React.useCallback(\n    () => client.channel.presenceUnsubscribe(),\n    [client],\n  );\n\n  return {\n    allowed: state.lastErrorCode !== 'access-denied',\n    isInitialLoading: !state.hasLoadedInitialData,\n    initialLoadFailed: state.initialLoadFailed,\n    isSynced: state.isSynced,\n    retry,\n    messages: state.messages,\n    fetchOlder,\n    hasOlder: state.hasOlder,\n    isFetchingOlder: state.isFetchingOlder,\n    status: state.status,\n    lastErrorCode: state.lastErrorCode,\n    typing: state.typing,\n    presence: state.presence,\n    send,\n    retrySend,\n    readAck,\n    signalTyping,\n    presenceSubscribe,\n    presenceUnsubscribe,\n  };\n}\n"]}

package/dist/realtime/wire.d.ts

@@ -1,16 +1,5 @@
 import type { ChatConversationRef, ChatMarkReadResultPayload, ChatMessageRevisionKind, ChatSendRejectedPayload } from '@ttt-productions/chat-schemas';
-/** A revision's kind (chat-schemas `ChatMessageRevisionKind`), under this package's historical name. */
 export type RevisionKind = ChatMessageRevisionKind;
-/**
- * A message row as the Channel DO stores + broadcasts it (the worker runtime's
- * message row), declared as the fields the client actually CONSUMES. The adapter
- * mapping in `map.ts` turns it into the UI `ChatMessageV1` shape.
- *
- * The row is TEXT-only: there is no attachment lifecycle on a chat message, and
- * no reply pointer — chat has no reply-authoring affordance, so the client
- * neither sends nor reads one (DJ ruling 2026-07-29). A DO that still broadcasts
- * a legacy stringified `replyTo` key is simply ignored here.
- */
 export interface WireMessageRow {
     seq: number;
     senderUid: string;
@@ -18,67 +7,25 @@ export interface WireMessageRow {
     text: string;
     createdAt: number;
     epoch: number;
-    /** Account ids a server-written row's text refers to (absent on a member's own message). */
     referencedUids?: string[];
-    /**
-     * The effective (max-`messageRevision`) moderation kind for this row, or null
-     * when never moderated. Populated by the DO's getHistory/getDeltaSince overlay
-     * merge so a hidden/deleted/edited row arrives already-moderated and its
-     * ORIGINAL text never reaches the renderer. Optional/absent on pre-overlay rows.
-     */
     moderationKind?: RevisionKind | null;
-    /**
-     * The effective `messageRevision` that `moderationKind` reflects (the DO's
-     * max-revision). Used to break ties against a live `revision` frame: a higher
-     * `messageRevision` wins; a stale/older one is ignored. Optional/absent on
-     * pre-overlay rows (treated as revision 0).
-     */
     messageRevision?: number;
 }
-/**
- * The channel resume snapshot the DO returns for a `resume` frame (Contract C).
- * `resync` / `delta` are the durable gap-repair half of the contract:
- *  - `resync: false` + `delta` = the contiguous ≤500-message backlog after the
- *    client's cursor (oldest-first); the client APPLIES the delta and advances its
- *    cursor to `lastMessageSeq` — a missed broadcast is never permanent.
- *  - `resync: true` = the gap exceeds the backlog (or the client sent no cursor);
- *    the client DROPS its local tail and re-pages history from the top.
- * Both are OPTIONAL/absent on a pre-contract DO (treated as `resync: true`, empty
- * delta — the safe re-page path) so a stale worker can't leave a client stuck.
- */
 export interface WireChannelSnapshot {
     lastMessageSeq: number;
     readSeq: number;
     resync?: boolean;
     delta?: WireMessageRow[];
 }
-/** A registry entry in the inbox snapshot (the worker runtime's registry entry). */
 export interface WireRegistryEntry {
     channelRef: string;
     kind: string;
     state: 'active' | 'tombstoned';
     registryVersion: number;
-    /**
-     * The conversation this entry is — the OPENABLE identity for the inbox view (the
-     * `channelRef` is an opaque registry key). The app maps it back to its own
-     * conversation; absent, the entry offers no open action.
-     */
     ref?: ChatConversationRef | null;
-    /**
-     * Per-entry unread flag (drives the per-row dot). Optional/absent until the inbox
-     * DO populates it; `deriveUnreadRefs` reads it as a typed field (no cast).
-     */
     unread?: boolean;
-    /**
-     * Archived state — DISTINCT from `tombstoned`. An archived row is still an ACTIVE
-     * membership (`state: 'active'`, history readable) but is grouped under the inbox
-     * view's Archived toggle instead of the active list. The client must NOT count
-     * archived rows in the unread roll-up (archive = done; the DO clears unread on
-     * archive). Optional/absent on a pre-archive DO (treated as not-archived).
-     */
     archived?: boolean;
 }
-/** The inbox snapshot payload pushed on connect / `resume` / live delta. */
 export interface WireInboxSnapshot {
     registry: WireRegistryEntry[];
     hasUnread: boolean;
@@ -139,14 +86,11 @@ export type ServerFrame = {
         messageRevision: number;
     };
 };
-/** Build an outbound `{ v, type, payload }` frame (the wire format the DO reads). */
 export declare function buildFrame(type: string, payload: Record<string, unknown>): string;
-/** Parse an inbound frame, tolerating malformed JSON. Returns null on garbage. */
 export declare function parseFrame(raw: string): {
     v?: number;
     type?: string;
     payload?: Record<string, unknown>;
 } | null;
-/** A snapshot with `registry` is an inbox snapshot; one with `lastMessageSeq` is a channel snapshot. */
 export declare function isInboxSnapshot(p: WireChannelSnapshot | WireInboxSnapshot): p is WireInboxSnapshot;
 //# sourceMappingURL=wire.d.ts.map

package/dist/realtime/wire.d.ts.map

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

package/dist/realtime/wire.js

@@ -1,22 +1,7 @@
-// Chat realtime WIRE PROTOCOL (Contract C) — the client side of the Channel +
-// Inbox Durable Object protocol. The canonical protocol declarations (subprotocol,
-// frame-kind maps, close codes, the neutral conversation reference, grant scope,
-// the send and mark-read contracts, client-agreed limits) are owned by `@ttt-productions/chat-schemas`; this file consumes them
-// and adds the client-side raw row/frame shapes the transport maps into the UI
-// message shape. The client and the worker runtime agree on the wire by both
-// importing that one contract; neither imports the other.
-//
-// Frame shape on the socket is `{ v, type, payload }` (NOT realtime-core's
-// `{ v, kind, payload }`): the worker runtime `send`/`broadcast` emit
-// `JSON.stringify({ v: 1, type, payload })` and read `env.type` + `env.payload`.
-// We keep that field name here to match; realtime-core's envelope schema is the
-// generic transport primitive, the chat protocol chose `type` for its frames.
 import { CHAT_WIRE_VERSION } from '@ttt-productions/chat-schemas';
-/** Build an outbound `{ v, type, payload }` frame (the wire format the DO reads). */
 export function buildFrame(type, payload) {
     return JSON.stringify({ v: CHAT_WIRE_VERSION, type, payload });
 }
-/** Parse an inbound frame, tolerating malformed JSON. Returns null on garbage. */
 export function parseFrame(raw) {
     try {
         const parsed = JSON.parse(raw);
@@ -28,7 +13,6 @@ export function parseFrame(raw) {
         return null;
     }
 }
-/** A snapshot with `registry` is an inbox snapshot; one with `lastMessageSeq` is a channel snapshot. */
 export function isInboxSnapshot(p) {
     return Array.isArray(p.registry);
 }