@ttt-productions/chat-react 0.12.12 → 0.12.14

package/dist/realtime/diagnostics.js

@@ -0,0 +1,135 @@
+// OPT-IN structured client diagnostics for the realtime chat transport.
+//
+// The E2E/browser harness can already capture the raw WebSocket frames; what it
+// cannot see is what the CLIENT DECIDED about them — which frame it applied,
+// which it dropped and why, what resume cursor it sent, whether an attachment
+// row mutated in place, and whether a send was reconciled or failed. This module
+// is that missing half: a bounded, structured, opt-in decision log.
+//
+// Rules this module exists to enforce:
+//   - OFF BY DEFAULT and zero behavior change. When the option is absent the
+//     factory returns `null`, every call site is `this.diag?.(...)`, and JS
+//     optional-call short-circuiting means the payload object is never even
+//     constructed. The cost when off is one nullish check.
+//   - NEVER user content. Ids, seqs, states, counts, codes, booleans only —
+//     never message text, captions, filenames, URLs, tokens, or previews. The
+//     INBOX events go one step further and log SIZES only: a `channelRef` names
+//     one specific conversation, so registry/unread lines carry counts and
+//     deltas, never the refs themselves.
+//   - STABLE event names (`chat_client_*`) suitable for log queries and later
+//     alert metrics; one line per DECISION, never per render or per heartbeat.
+//   - A diagnostics sink can never break the client: every emit is wrapped, so a
+//     throwing sink is swallowed rather than turned into a transport failure.
+/**
+ * Stable event names. These are a QUERY CONTRACT — Cloud Logging filters, E2E
+ * console greps, and any later alert metric key on them, so a name is added or
+ * retired deliberately, never renamed in place.
+ */
+export const CHAT_CLIENT_DIAGNOSTIC_EVENTS = {
+    /** A socket open is being attempted (per attempt, with the reconnect cause). */
+    CONNECT_ATTEMPT: 'chat_client_connect_attempt',
+    /** The grant mint failed before a socket existed (terminal vs. retryable). */
+    GRANT_FAILED: 'chat_client_grant_failed',
+    /** The socket reached OPEN (the point the resume cursor is sent from). */
+    SOCKET_OPEN: 'chat_client_socket_open',
+    /** The socket closed, with the code and what the client decided to do next. */
+    SOCKET_CLOSE: 'chat_client_socket_close',
+    /** A reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */
+    RECONNECT_SCHEDULED: 'chat_client_reconnect_scheduled',
+    /** The resume cursor sent to the DO. */
+    RESUME_REQUEST: 'chat_client_resume_request',
+    /** The DO's snapshot answer + how the cursor moved because of it. */
+    RESUME_RESULT: 'chat_client_resume_result',
+    /** A `resync: true` snapshot dropped the local tail (removal, not upsert). */
+    RESYNC_DROPPED_TAIL: 'chat_client_resync_dropped_tail',
+    /** A frame was applied to UI state (insert / replace-by-seq / optimistic reconcile). */
+    FRAME_APPLIED: 'chat_client_frame_applied',
+    /** A frame was NOT applied, with the reason. */
+    FRAME_DROPPED: 'chat_client_frame_dropped',
+    /** An attachment lifecycle change AS SEEN BY THE CLIENT: seq, old -> new state. */
+    ATTACHMENT_TRANSITION: 'chat_client_attachment_transition',
+    /** A moderation revision overlay was recorded (and whether a loaded row re-rendered). */
+    REVISION_APPLIED: 'chat_client_revision_applied',
+    /** A history page was requested (cursor + limit). */
+    HISTORY_REQUEST: 'chat_client_history_request',
+    /** A history page was applied: size, seq range, cursor advance. */
+    HISTORY_PAGE: 'chat_client_history_page',
+    /** An optimistic send was rendered and its frame written. */
+    SEND_OPTIMISTIC: 'chat_client_send_optimistic',
+    /** A send was acked by the server (seq assigned). */
+    SEND_ACK: 'chat_client_send_ack',
+    /** A correlated `send-rejected` (or its legacy uncorrelated form) was handled. */
+    SEND_REJECTED: 'chat_client_send_rejected',
+    /** A send was re-emitted (reconnect resume / scheduled hint / manual retry). */
+    SEND_RETRY: 'chat_client_send_retry',
+    /** A send reached its visible failed state, with the reason. */
+    SEND_FAILED: 'chat_client_send_failed',
+    /** An uncorrelated server `error` frame code. */
+    ERROR_FRAME: 'chat_client_error_frame',
+    // ---- inbox socket (one per USER, separate from the per-thread channel socket) ----
+    /** An inbox socket open is being attempted (per attempt, with the reconnect cause). */
+    INBOX_CONNECT_ATTEMPT: 'chat_client_inbox_connect_attempt',
+    /** The inbox grant mint failed before a socket existed (terminal vs. retryable). */
+    INBOX_GRANT_FAILED: 'chat_client_inbox_grant_failed',
+    /** The inbox socket reached OPEN (the point `resume` is sent from). */
+    INBOX_SOCKET_OPEN: 'chat_client_inbox_socket_open',
+    /** The inbox socket closed, with the code and what the client decided to do next. */
+    INBOX_SOCKET_CLOSE: 'chat_client_inbox_socket_close',
+    /** An inbox reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */
+    INBOX_RECONNECT_SCHEDULED: 'chat_client_inbox_reconnect_scheduled',
+    /** The cursorless inbox `resume` was sent (the DO answers with a full snapshot). */
+    INBOX_RESUME_REQUEST: 'chat_client_inbox_resume_request',
+    /** An authoritative inbox snapshot was applied — registry SIZES only, never refs. */
+    INBOX_SNAPSHOT_APPLIED: 'chat_client_inbox_snapshot_applied',
+    /** The unread projection actually CHANGED (dock dot and/or per-row dot count). */
+    INBOX_UNREAD_UPDATED: 'chat_client_inbox_unread_updated',
+    /** An inbox frame was NOT applied, with the reason. */
+    INBOX_FRAME_DROPPED: 'chat_client_inbox_frame_dropped',
+    /** A mark-read was written to the socket (no optimistic local clear). */
+    INBOX_MARK_READ: 'chat_client_inbox_mark_read',
+};
+/** Max length of a server-supplied label (frame type, error code) we echo into a log line. */
+const MAX_LABEL_LEN = 48;
+/**
+ * Clamp a server-supplied label before it enters a log line. Frame types and
+ * error codes are protocol tokens, not user content, but they arrive from the
+ * wire — bound them so a hostile/buggy peer cannot emit an unbounded line.
+ */
+export function safeDiagnosticLabel(raw) {
+    if (typeof raw !== 'string')
+        return 'unknown';
+    const trimmed = raw.slice(0, MAX_LABEL_LEN);
+    return trimmed.length > 0 ? trimmed : 'unknown';
+}
+/**
+ * The default sink: ONE `console.debug` line per decision, shaped
+ * `chat_client_<event> {"compact":"json"}` so a browser console capture or a log
+ * query can filter on the stable prefix and parse the payload without a
+ * multi-line join.
+ */
+const consoleDebugSink = (event, data) => {
+    if (typeof console === 'undefined' || typeof console.debug !== 'function')
+        return;
+    console.debug(`${event} ${JSON.stringify(data)}`);
+};
+/**
+ * Build the emitter for a `diagnostics` config value. Returns `null` when
+ * diagnostics are off so call sites can use `this.diag?.(...)` — with optional
+ * call syntax the argument object is not constructed at all on the off path.
+ */
+export function createDiagnosticsEmitter(option) {
+    if (option == null || option === false)
+        return null;
+    const sink = option === true ? consoleDebugSink : option;
+    return (event, data) => {
+        // Diagnostics observe; they must never alter transport behavior — a sink that
+        // throws (or a payload that cannot be serialized) is swallowed here.
+        try {
+            sink(event, data);
+        }
+        catch {
+            /* diagnostics are never allowed to fail the client */
+        }
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/realtime/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/realtime/diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["// OPT-IN structured client diagnostics for the realtime chat transport.\n//\n// The E2E/browser harness can already capture the raw WebSocket frames; what it\n// cannot see is what the CLIENT DECIDED about them — which frame it applied,\n// which it dropped and why, what resume cursor it sent, whether an attachment\n// row mutated in place, and whether a send was reconciled or failed. This module\n// is that missing half: a bounded, structured, opt-in decision log.\n//\n// Rules this module exists to enforce:\n//   - OFF BY DEFAULT and zero behavior change. When the option is absent the\n//     factory returns `null`, every call site is `this.diag?.(...)`, and JS\n//     optional-call short-circuiting means the payload object is never even\n//     constructed. The cost when off is one nullish check.\n//   - NEVER user content. Ids, seqs, states, counts, codes, booleans only —\n//     never message text, captions, filenames, URLs, tokens, or previews. The\n//     INBOX events go one step further and log SIZES only: a `channelRef` names\n//     one specific conversation, so registry/unread lines carry counts and\n//     deltas, never the refs themselves.\n//   - STABLE event names (`chat_client_*`) suitable for log queries and later\n//     alert metrics; one line per DECISION, never per render or per heartbeat.\n//   - A diagnostics sink can never break the client: every emit is wrapped, so a\n//     throwing sink is swallowed rather than turned into a transport failure.\n\n/**\n * A structured diagnostic sink. `event` is one of the stable\n * {@link CHAT_CLIENT_DIAGNOSTIC_EVENTS} names; `data` is a compact, content-free\n * payload (ids/seqs/states/counts/codes only). Supplying a sink lets the app\n * route entries into its own logger; `true` uses the console.debug default.\n */\nexport type ChatClientDiagnosticsSink = (event: string, data: Record<string, unknown>) => void;\n\n/**\n * The additive `diagnostics` config value: `false`/absent = off (the default and\n * the only production posture), `true` = the single-line `console.debug` sink,\n * or a custom {@link ChatClientDiagnosticsSink}.\n */\nexport type ChatClientDiagnosticsOption = boolean | ChatClientDiagnosticsSink;\n\n/** The bound emitter, or `null` when diagnostics are off (the zero-overhead path). */\nexport type ChatClientDiagnosticsEmitter = ChatClientDiagnosticsSink | null;\n\n/**\n * Stable event names. These are a QUERY CONTRACT — Cloud Logging filters, E2E\n * console greps, and any later alert metric key on them, so a name is added or\n * retired deliberately, never renamed in place.\n */\nexport const CHAT_CLIENT_DIAGNOSTIC_EVENTS = {\n  /** A socket open is being attempted (per attempt, with the reconnect cause). */\n  CONNECT_ATTEMPT: 'chat_client_connect_attempt',\n  /** The grant mint failed before a socket existed (terminal vs. retryable). */\n  GRANT_FAILED: 'chat_client_grant_failed',\n  /** The socket reached OPEN (the point the resume cursor is sent from). */\n  SOCKET_OPEN: 'chat_client_socket_open',\n  /** The socket closed, with the code and what the client decided to do next. */\n  SOCKET_CLOSE: 'chat_client_socket_close',\n  /** A reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */\n  RECONNECT_SCHEDULED: 'chat_client_reconnect_scheduled',\n  /** The resume cursor sent to the DO. */\n  RESUME_REQUEST: 'chat_client_resume_request',\n  /** The DO's snapshot answer + how the cursor moved because of it. */\n  RESUME_RESULT: 'chat_client_resume_result',\n  /** A `resync: true` snapshot dropped the local tail (removal, not upsert). */\n  RESYNC_DROPPED_TAIL: 'chat_client_resync_dropped_tail',\n  /** A frame was applied to UI state (insert / replace-by-seq / optimistic reconcile). */\n  FRAME_APPLIED: 'chat_client_frame_applied',\n  /** A frame was NOT applied, with the reason. */\n  FRAME_DROPPED: 'chat_client_frame_dropped',\n  /** An attachment lifecycle change AS SEEN BY THE CLIENT: seq, old -> new state. */\n  ATTACHMENT_TRANSITION: 'chat_client_attachment_transition',\n  /** A moderation revision overlay was recorded (and whether a loaded row re-rendered). */\n  REVISION_APPLIED: 'chat_client_revision_applied',\n  /** A history page was requested (cursor + limit). */\n  HISTORY_REQUEST: 'chat_client_history_request',\n  /** A history page was applied: size, seq range, cursor advance. */\n  HISTORY_PAGE: 'chat_client_history_page',\n  /** An optimistic send was rendered and its frame written. */\n  SEND_OPTIMISTIC: 'chat_client_send_optimistic',\n  /** A send was acked by the server (seq assigned). */\n  SEND_ACK: 'chat_client_send_ack',\n  /** A correlated `send-rejected` (or its legacy uncorrelated form) was handled. */\n  SEND_REJECTED: 'chat_client_send_rejected',\n  /** A send was re-emitted (reconnect resume / scheduled hint / manual retry). */\n  SEND_RETRY: 'chat_client_send_retry',\n  /** A send reached its visible failed state, with the reason. */\n  SEND_FAILED: 'chat_client_send_failed',\n  /** An uncorrelated server `error` frame code. */\n  ERROR_FRAME: 'chat_client_error_frame',\n\n  // ---- inbox socket (one per USER, separate from the per-thread channel socket) ----\n\n  /** An inbox socket open is being attempted (per attempt, with the reconnect cause). */\n  INBOX_CONNECT_ATTEMPT: 'chat_client_inbox_connect_attempt',\n  /** The inbox grant mint failed before a socket existed (terminal vs. retryable). */\n  INBOX_GRANT_FAILED: 'chat_client_inbox_grant_failed',\n  /** The inbox socket reached OPEN (the point `resume` is sent from). */\n  INBOX_SOCKET_OPEN: 'chat_client_inbox_socket_open',\n  /** The inbox socket closed, with the code and what the client decided to do next. */\n  INBOX_SOCKET_CLOSE: 'chat_client_inbox_socket_close',\n  /** An inbox reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */\n  INBOX_RECONNECT_SCHEDULED: 'chat_client_inbox_reconnect_scheduled',\n  /** The cursorless inbox `resume` was sent (the DO answers with a full snapshot). */\n  INBOX_RESUME_REQUEST: 'chat_client_inbox_resume_request',\n  /** An authoritative inbox snapshot was applied — registry SIZES only, never refs. */\n  INBOX_SNAPSHOT_APPLIED: 'chat_client_inbox_snapshot_applied',\n  /** The unread projection actually CHANGED (dock dot and/or per-row dot count). */\n  INBOX_UNREAD_UPDATED: 'chat_client_inbox_unread_updated',\n  /** An inbox frame was NOT applied, with the reason. */\n  INBOX_FRAME_DROPPED: 'chat_client_inbox_frame_dropped',\n  /** A mark-read was written to the socket (no optimistic local clear). */\n  INBOX_MARK_READ: 'chat_client_inbox_mark_read',\n} as const;\n\nexport type ChatClientDiagnosticEventName =\n  (typeof CHAT_CLIENT_DIAGNOSTIC_EVENTS)[keyof typeof CHAT_CLIENT_DIAGNOSTIC_EVENTS];\n\n/** Max length of a server-supplied label (frame type, error code) we echo into a log line. */\nconst MAX_LABEL_LEN = 48;\n\n/**\n * Clamp a server-supplied label before it enters a log line. Frame types and\n * error codes are protocol tokens, not user content, but they arrive from the\n * wire — bound them so a hostile/buggy peer cannot emit an unbounded line.\n */\nexport function safeDiagnosticLabel(raw: unknown): string {\n  if (typeof raw !== 'string') return 'unknown';\n  const trimmed = raw.slice(0, MAX_LABEL_LEN);\n  return trimmed.length > 0 ? trimmed : 'unknown';\n}\n\n/**\n * The default sink: ONE `console.debug` line per decision, shaped\n * `chat_client_<event> {\"compact\":\"json\"}` so a browser console capture or a log\n * query can filter on the stable prefix and parse the payload without a\n * multi-line join.\n */\nconst consoleDebugSink: ChatClientDiagnosticsSink = (event, data) => {\n  if (typeof console === 'undefined' || typeof console.debug !== 'function') return;\n  console.debug(`${event} ${JSON.stringify(data)}`);\n};\n\n/**\n * Build the emitter for a `diagnostics` config value. Returns `null` when\n * diagnostics are off so call sites can use `this.diag?.(...)` — with optional\n * call syntax the argument object is not constructed at all on the off path.\n */\nexport function createDiagnosticsEmitter(\n  option: ChatClientDiagnosticsOption | undefined,\n): ChatClientDiagnosticsEmitter {\n  if (option == null || option === false) return null;\n  const sink = option === true ? consoleDebugSink : option;\n  return (event, data) => {\n    // Diagnostics observe; they must never alter transport behavior — a sink that\n    // throws (or a payload that cannot be serialized) is swallowed here.\n    try {\n      sink(event, data);\n    } catch {\n      /* diagnostics are never allowed to fail the client */\n    }\n  };\n}\n"]}

package/dist/realtime/inbox-client.d.ts

@@ -1,6 +1,7 @@
 import { type WireRegistryEntry } from './wire.js';
 import type { SocketFactory } from './socket.js';
 import type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js';
+import { type ChatClientDiagnosticsOption } from './diagnostics.js';
 export interface InboxClientState {
     status: RealtimeStatus;
     /** Active (non-tombstoned) channel/invite registry entries — inbox-view visibility. */
@@ -33,6 +34,16 @@ export interface InboxClientConfig {
         maxAttempts?: number | null;
         random?: () => number;
     };
+    /**
+     * OPT-IN structured client diagnostics — the SAME option type and emitter the
+     * channel client uses (one owner, `./diagnostics.ts`). Default OFF: absent or
+     * `false` changes nothing and costs one nullish check. `true` emits one
+     * single-line `console.debug` entry per decision under the stable
+     * `chat_client_inbox_*` names; a function routes them to the app's logger.
+     * Inbox payloads are SIZES ONLY — registry/unread counts and deltas, never a
+     * `channelRef` (which names one specific conversation).
+     */
+    diagnostics?: ChatClientDiagnosticsOption;
 }
 export declare class InboxClient {
     private readonly config;
@@ -44,6 +55,14 @@ export declare class InboxClient {
     private reauthAttempted;
     private reconnectTimer;
     private closedByUs;
+    /** Structured diagnostics emitter, or null when off (the default, zero-overhead). */
+    private readonly diag;
+    /** Monotonic socket-open attempt counter (diagnostics correlation only). */
+    private connectAttempt;
+    /** Why the CURRENT connect attempt is happening (diagnostics only). */
+    private reconnectCause;
+    /** The last close code observed, carried into the next attempt's cause line. */
+    private lastCloseCode;
     constructor(config: InboxClientConfig);
     getState(): InboxClientState;
     subscribe(fn: (s: InboxClientState) => void): () => void;

package/dist/realtime/inbox-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-client.d.ts","sourceRoot":"","sources":["../../src/realtime/inbox-client.ts"],"names":[],"mappings":"AAWA,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,uFAAuF;IACvF,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;CAC/G;AAID,qBAAa,WAAW;IAUV,OAAO,CAAC,QAAQ,CAAC,MAAM;IATnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,UAAU,CAAS;gBAEE,MAAM,EAAE,iBAAiB;IAKtD,QAAQ,IAAI,gBAAgB;IAI5B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD,OAAO,CAAC,QAAQ;IAKV,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAOhB,UAAU;IA2BxB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,OAAO;IAqBf;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,SAAS;IAMjB,yEAAyE;IACzE,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIrC,kEAAkE;IAClE,KAAK,IAAI,IAAI;CAad"}
+{"version":3,"file":"inbox-client.d.ts","sourceRoot":"","sources":["../../src/realtime/inbox-client.ts"],"names":[],"mappings":"AAWA,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EAKL,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,uFAAuF;IACvF,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;IAC9G;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAID,qBAAa,WAAW;IAkBV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAjBnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,UAAU,CAAS;IAC3B,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,4EAA4E;IAC5E,OAAO,CAAC,cAAc,CAAK;IAC3B,uEAAuE;IACvE,OAAO,CAAC,cAAc,CAA6E;IACnG,gFAAgF;IAChF,OAAO,CAAC,aAAa,CAAuB;gBAEf,MAAM,EAAE,iBAAiB;IAMtD,QAAQ,IAAI,gBAAgB;IAI5B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD,OAAO,CAAC,QAAQ;IAKV,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAQhB,UAAU;IAqCxB,OAAO,CAAC,MAAM;IAiBd,OAAO,CAAC,OAAO;IA4Bf;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,SAAS;IAwCjB,OAAO,CAAC,aAAa;IAuCrB,OAAO,CAAC,SAAS;IAMjB,yEAAyE;IACzE,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAQrC,kEAAkE;IAClE,KAAK,IAAI,IAAI;CAad"}

package/dist/realtime/inbox-client.js

@@ -10,6 +10,7 @@
 import { createReconnectController } from '@ttt-productions/realtime-core';
 import { CLIENT_FRAME, CHAT_CLOSE_CODES, buildFrame, parseFrame, isInboxSnapshot, } from './wire.js';
 import { defaultTimers, isChatAccessDeniedError } from './shared.js';
+import { createDiagnosticsEmitter, safeDiagnosticLabel, CHAT_CLIENT_DIAGNOSTIC_EVENTS as DIAG, } from './diagnostics.js';
 const INITIAL = { status: 'idle', registry: [], hasUnread: false, unreadChannelRefs: [], lastErrorCode: null };
 export class InboxClient {
     config;
@@ -21,10 +22,19 @@ export class InboxClient {
     reauthAttempted = false;
     reconnectTimer = null;
     closedByUs = false;
+    /** Structured diagnostics emitter, or null when off (the default, zero-overhead). */
+    diag;
+    /** Monotonic socket-open attempt counter (diagnostics correlation only). */
+    connectAttempt = 0;
+    /** Why the CURRENT connect attempt is happening (diagnostics only). */
+    reconnectCause = 'initial';
+    /** The last close code observed, carried into the next attempt's cause line. */
+    lastCloseCode = null;
     constructor(config) {
         this.config = config;
         this.timers = config.timers ?? defaultTimers;
         this.controller = createReconnectController(config.reconnect ?? {});
+        this.diag = createDiagnosticsEmitter(config.diagnostics);
     }
     getState() {
         return this.state;
@@ -40,11 +50,19 @@ export class InboxClient {
     }
     async connect() {
         this.closedByUs = false;
+        this.reconnectCause = 'initial';
         this.controller.start();
         this.setState({ status: 'connecting' });
         await this.openSocket();
     }
     async openSocket() {
+        this.connectAttempt += 1;
+        this.diag?.(DIAG.INBOX_CONNECT_ATTEMPT, {
+            attempt: this.connectAttempt,
+            cause: this.reconnectCause,
+            closeCode: this.lastCloseCode,
+            registryCount: this.state.registry.length,
+        });
         let grantToken;
         try {
             grantToken = await this.config.grantProvider();
@@ -55,8 +73,11 @@ export class InboxClient {
             // package-owned ChatAccessDeniedError) must NOT reconnect: the next mint would
             // just re-deny, reconnect-looping forever and warning every cycle. Every other
             // mint failure (network/transient) stays retryable and backs off as before.
-            if (isChatAccessDeniedError(err))
+            const terminal = isChatAccessDeniedError(err);
+            this.diag?.(DIAG.INBOX_GRANT_FAILED, { attempt: this.connectAttempt, terminal });
+            if (terminal)
                 return this.denyAccessTerminally();
+            this.reconnectCause = 'grant-error';
             return this.scheduleReconnect();
         }
         if (this.closedByUs)
@@ -77,17 +98,30 @@ export class InboxClient {
         this.controller.onOpen();
         this.reauthAttempted = false;
         this.setState({ status: 'open' });
+        this.diag?.(DIAG.INBOX_SOCKET_OPEN, {
+            attempt: this.connectAttempt,
+            cause: this.reconnectCause,
+            registryCount: this.state.registry.length,
+            hasUnread: this.state.hasUnread,
+        });
         // The DO sends a snapshot on accept; a `resume` re-requests it after a reconnect gap.
-        this.sendFrame(CLIENT_FRAME.RESUME, {});
+        const sent = this.sendFrame(CLIENT_FRAME.RESUME, {});
+        // The inbox resume is CURSORLESS by contract (the DO always answers with a full
+        // authoritative snapshot) — there is no `afterSeq` half to record here.
+        this.diag?.(DIAG.INBOX_RESUME_REQUEST, { attempt: this.connectAttempt, cursorless: true, sent });
     }
     onClose(code, _reason) {
         this.socket = null;
+        this.lastCloseCode = code;
         if (this.closedByUs) {
+            this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: true, outcome: 'closed' });
             this.setState({ status: 'closed' });
             return;
         }
         if (code === CHAT_CLOSE_CODES.AUTH_EXPIRED && !this.reauthAttempted) {
             this.reauthAttempted = true;
+            this.reconnectCause = 'auth-expired';
+            this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 're-grant' });
             this.setState({ status: 'reconnecting' });
             void this.openSocket();
             return;
@@ -95,9 +129,12 @@ export class InboxClient {
         if (code === CHAT_CLOSE_CODES.REVOKED) {
             this.closedByUs = true;
             this.controller.close();
+            this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 'revoked' });
             this.setState({ status: 'closed', lastErrorCode: 'revoked' });
             return;
         }
+        this.reconnectCause = 'transient-close';
+        this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 'reconnect' });
         this.scheduleReconnect();
     }
     /**
@@ -115,6 +152,11 @@ export class InboxClient {
     }
     scheduleReconnect() {
         const delay = this.controller.onClose();
+        this.diag?.(DIAG.INBOX_RECONNECT_SCHEDULED, {
+            delayMs: delay,
+            cause: this.reconnectCause,
+            attempt: this.connectAttempt,
+        });
         if (delay == null) {
             this.setState({ status: 'closed' });
             return;
@@ -129,22 +171,46 @@ export class InboxClient {
     }
     onMessage(data) {
         const frame = parseFrame(data);
-        if (!frame || !frame.payload)
+        if (!frame || !frame.payload) {
+            this.diag?.(DIAG.INBOX_FRAME_DROPPED, { kind: 'unparseable', reason: 'bad-envelope' });
             return;
+        }
         // The inbox DO pushes a full `snapshot`; a future lightweight `unread` push
         // carries either a full snapshot or a `{ hasUnread }` dock-dot patch. Route both
         // instead of silently dropping the `unread` type (C-M2).
-        if (frame.type !== 'snapshot' && frame.type !== 'unread')
+        if (frame.type !== 'snapshot' && frame.type !== 'unread') {
+            this.diag?.(DIAG.INBOX_FRAME_DROPPED, { kind: safeDiagnosticLabel(frame.type), reason: 'unknown-type' });
             return;
+        }
         const payload = frame.payload;
         if (isInboxSnapshot(payload)) {
-            this.applySnapshot(payload);
+            this.applySnapshot(payload, frame.type);
         }
         else if (frame.type === 'unread' && typeof payload.hasUnread === 'boolean') {
-            this.setState({ hasUnread: Boolean(payload.hasUnread) });
+            const hasUnread = Boolean(payload.hasUnread);
+            const before = this.state.hasUnread;
+            this.setState({ hasUnread });
+            if (before !== hasUnread) {
+                this.diag?.(DIAG.INBOX_UNREAD_UPDATED, {
+                    source: 'unread-patch',
+                    hasUnreadBefore: before,
+                    hasUnreadAfter: hasUnread,
+                    unreadCountBefore: this.state.unreadChannelRefs.length,
+                    unreadCountAfter: this.state.unreadChannelRefs.length,
+                    unreadCountDelta: 0,
+                });
+            }
+        }
+        else {
+            // A stray CHANNEL snapshot ({ lastMessageSeq, readSeq }) on the inbox socket —
+            // deliberately inert, but never silently invisible under diagnostics.
+            this.diag?.(DIAG.INBOX_FRAME_DROPPED, {
+                kind: safeDiagnosticLabel(frame.type),
+                reason: 'not-an-inbox-payload',
+            });
         }
     }
-    applySnapshot(snap) {
+    applySnapshot(snap, source) {
         // Keep every non-tombstoned entry — including ARCHIVED rows — so the inbox view can
         // render both the active list and the Archived toggle. `archived` is a distinct
         // dimension from `tombstoned`; archived rows are still `state: 'active'`.
@@ -152,11 +218,35 @@ export class InboxClient {
         // The DO's `hasUnread` is the authoritative dock dot. Per-row dots are derived from
         // the same projection but exclude ARCHIVED rows (archive = done — an archived row
         // never shows a dot). The DO clears unread on archive, so this is belt-and-braces.
-        this.setState({
-            registry,
-            hasUnread: Boolean(snap.hasUnread),
-            unreadChannelRefs: deriveUnreadRefs(snap),
+        const unreadChannelRefs = deriveUnreadRefs(snap);
+        const hasUnread = Boolean(snap.hasUnread);
+        const before = this.state;
+        this.setState({ registry, hasUnread, unreadChannelRefs });
+        if (!this.diag)
+            return;
+        // SIZES ONLY — a channelRef names one specific conversation and never enters a
+        // diagnostic line.
+        this.diag(DIAG.INBOX_SNAPSHOT_APPLIED, {
+            source: safeDiagnosticLabel(source),
+            received: snap.registry.length,
+            // `received - active` is the tombstoned count the client filtered out.
+            active: registry.length,
+            archived: registry.filter((e) => e.archived === true).length,
+            hasUnread,
+            unreadCount: unreadChannelRefs.length,
+            registryDelta: registry.length - before.registry.length,
         });
+        const unreadChanged = before.hasUnread !== hasUnread || before.unreadChannelRefs.length !== unreadChannelRefs.length;
+        if (unreadChanged) {
+            this.diag(DIAG.INBOX_UNREAD_UPDATED, {
+                source: safeDiagnosticLabel(source),
+                hasUnreadBefore: before.hasUnread,
+                hasUnreadAfter: hasUnread,
+                unreadCountBefore: before.unreadChannelRefs.length,
+                unreadCountAfter: unreadChannelRefs.length,
+                unreadCountDelta: unreadChannelRefs.length - before.unreadChannelRefs.length,
+            });
+        }
     }
     sendFrame(type, payload) {
         if (!this.socket || !this.socket.isOpen)
@@ -177,7 +267,11 @@ export class InboxClient {
      * Returns false when the socket is not open (the caller may surface a retry).
      */
     markRead(channelRef) {
-        return this.sendFrame(CLIENT_FRAME.MARK_READ, { channelRef });
+        const sent = this.sendFrame(CLIENT_FRAME.MARK_READ, { channelRef });
+        // The ref itself is never logged — only that a mark-read was written and what the
+        // unread projection looked like at that moment (the DO's snapshot is what clears it).
+        this.diag?.(DIAG.INBOX_MARK_READ, { sent, unreadCount: this.state.unreadChannelRefs.length });
+        return sent;
     }
     /** Permanently close (auth-user switch / unmount). Idempotent. */
     close() {

package/dist/realtime/inbox-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-client.js","sourceRoot":"","sources":["../../src/realtime/inbox-client.ts"],"names":[],"mappings":"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","sourcesContent":["// The Inbox realtime client: a SEPARATE WebSocket (scope `inbox`) to the user's\n// inbox DO. It maintains the channel/invite registry + unread projection that\n// drives the inbox view — DOTS ONLY, no counts (Contract C / \"Unread + inbox\").\n//\n// The inbox DO pushes a full `snapshot` ({ registry, hasUnread }) on connect, on\n// `resume`, and on every live delta (a projection apply). This client just\n// mirrors the latest snapshot into an observable store + a per-channel unread set.\n// Same connection lifecycle as the channel client (subprotocol auth, reconnect,\n// 4401 re-grant once, 4403 stop, auth-switch teardown).\n\nimport { createReconnectController, type ReconnectController } from '@ttt-productions/realtime-core';\nimport {\n  CLIENT_FRAME,\n  CHAT_CLOSE_CODES,\n  buildFrame,\n  parseFrame,\n  isInboxSnapshot,\n  type WireInboxSnapshot,\n  type WireRegistryEntry,\n} from './wire.js';\nimport type { RealtimeSocket, SocketFactory } from './socket.js';\nimport type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js';\nimport { defaultTimers, isChatAccessDeniedError } from './shared.js';\n\nexport interface InboxClientState {\n  status: RealtimeStatus;\n  /** Active (non-tombstoned) channel/invite registry entries — inbox-view visibility. */\n  registry: WireRegistryEntry[];\n  /** True if ANY active channel/invite has unread (drives the dock dot). */\n  hasUnread: boolean;\n  /** The set of channelRefs that currently carry an unread dot (per-row dots). */\n  unreadChannelRefs: string[];\n  /**\n   * The last TERMINAL error code (mirrors `ChannelClientState.lastErrorCode`):\n   * `'access-denied'` when the inbox grant provider throws `ChatAccessDeniedError`\n   * (a genuine, terminal policy \"no\" — e.g. a banned/suspended account), and\n   * `'revoked'` on a 4403 REVOKED close. Null while healthy and across transient\n   * reconnects. The app subscribes to inbox state directly (there is no inbox React\n   * hook in this package), so this stable code is the surface — it invents no new UI.\n   */\n  lastErrorCode: string | null;\n}\n\nexport interface InboxClientConfig {\n  endpoint: string;\n  /** The authenticated uid (the inbox owner; the DO serves no one else's data). */\n  currentUserId: string;\n  /** Mints/refreshes an INBOX-scope grant (scope `{ kind:'inbox', uid }`). */\n  grantProvider: GrantProvider;\n  socketFactory: SocketFactory;\n  timers?: TransportTimers;\n  reconnect?: { baseDelayMs?: number; maxDelayMs?: number; maxAttempts?: number | null; random?: () => number };\n}\n\nconst INITIAL: InboxClientState = { status: 'idle', registry: [], hasUnread: false, unreadChannelRefs: [], lastErrorCode: null };\n\nexport class InboxClient {\n  private readonly timers: TransportTimers;\n  private readonly controller: ReconnectController;\n  private socket: RealtimeSocket | null = null;\n  private state: InboxClientState = INITIAL;\n  private readonly listeners = new Set<(s: InboxClientState) => void>();\n  private reauthAttempted = false;\n  private reconnectTimer: ReturnType<TransportTimers['setTimeout']> | null = null;\n  private closedByUs = false;\n\n  constructor(private readonly config: InboxClientConfig) {\n    this.timers = config.timers ?? defaultTimers;\n    this.controller = createReconnectController(config.reconnect ?? {});\n  }\n\n  getState(): InboxClientState {\n    return this.state;\n  }\n\n  subscribe(fn: (s: InboxClientState) => void): () => void {\n    this.listeners.add(fn);\n    return () => this.listeners.delete(fn);\n  }\n\n  private setState(patch: Partial<InboxClientState>): void {\n    this.state = { ...this.state, ...patch };\n    for (const fn of this.listeners) fn(this.state);\n  }\n\n  async connect(): Promise<void> {\n    this.closedByUs = false;\n    this.controller.start();\n    this.setState({ status: 'connecting' });\n    await this.openSocket();\n  }\n\n  private async openSocket(): Promise<void> {\n    let grantToken: string;\n    try {\n      grantToken = await this.config.grantProvider();\n    } catch (err) {\n      // A TERMINAL access denial (the app translated an authoritative policy \"no\"\n      // — e.g. Firebase `permission-denied` for a banned/suspended account — into the\n      // package-owned ChatAccessDeniedError) must NOT reconnect: the next mint would\n      // just re-deny, reconnect-looping forever and warning every cycle. Every other\n      // mint failure (network/transient) stays retryable and backs off as before.\n      if (isChatAccessDeniedError(err)) return this.denyAccessTerminally();\n      return this.scheduleReconnect();\n    }\n    if (this.closedByUs) return;\n    const url = `${this.config.endpoint.replace(/\\/$/, '')}/inbox`;\n    this.socket = this.config.socketFactory({\n      url,\n      grantToken,\n      handlers: {\n        onOpen: () => this.onOpen(),\n        onMessage: (data) => this.onMessage(data),\n        onClose: (code, reason) => this.onClose(code, reason),\n        onError: () => undefined,\n      },\n    });\n  }\n\n  private onOpen(): void {\n    this.controller.onOpen();\n    this.reauthAttempted = false;\n    this.setState({ status: 'open' });\n    // The DO sends a snapshot on accept; a `resume` re-requests it after a reconnect gap.\n    this.sendFrame(CLIENT_FRAME.RESUME, {});\n  }\n\n  private onClose(code: number, _reason: string): void {\n    this.socket = null;\n    if (this.closedByUs) {\n      this.setState({ status: 'closed' });\n      return;\n    }\n    if (code === CHAT_CLOSE_CODES.AUTH_EXPIRED && !this.reauthAttempted) {\n      this.reauthAttempted = true;\n      this.setState({ status: 'reconnecting' });\n      void this.openSocket();\n      return;\n    }\n    if (code === CHAT_CLOSE_CODES.REVOKED) {\n      this.closedByUs = true;\n      this.controller.close();\n      this.setState({ status: 'closed', lastErrorCode: 'revoked' });\n      return;\n    }\n    this.scheduleReconnect();\n  }\n\n  /**\n   * Terminal access denial surfaced by the inbox grant provider\n   * (`ChatAccessDeniedError`). Same terminal posture as the 4403 REVOKED close: mark\n   * closed-by-us, close the reconnect controller, and surface the stable\n   * `access-denied` code. The inbox client tracks NO optimistic/pending sends\n   * (mark-read is fire-and-forget with no local pending state), so — unlike\n   * ChannelClient — there is nothing to fail here; only the lifecycle stops.\n   */\n  private denyAccessTerminally(): void {\n    this.closedByUs = true;\n    this.controller.close();\n    this.setState({ status: 'closed', lastErrorCode: 'access-denied' });\n  }\n\n  private scheduleReconnect(): void {\n    const delay = this.controller.onClose();\n    if (delay == null) {\n      this.setState({ status: 'closed' });\n      return;\n    }\n    this.setState({ status: 'reconnecting' });\n    this.reconnectTimer = this.timers.setTimeout(() => {\n      this.reconnectTimer = null;\n      if (this.closedByUs) return;\n      void this.openSocket();\n    }, delay);\n  }\n\n  private onMessage(data: string): void {\n    const frame = parseFrame(data);\n    if (!frame || !frame.payload) return;\n    // The inbox DO pushes a full `snapshot`; a future lightweight `unread` push\n    // carries either a full snapshot or a `{ hasUnread }` dock-dot patch. Route both\n    // instead of silently dropping the `unread` type (C-M2).\n    if (frame.type !== 'snapshot' && frame.type !== 'unread') return;\n    const payload = frame.payload as unknown as WireInboxSnapshot | { hasUnread: boolean };\n    if (isInboxSnapshot(payload as WireInboxSnapshot)) {\n      this.applySnapshot(payload as WireInboxSnapshot);\n    } else if (frame.type === 'unread' && typeof (payload as { hasUnread?: unknown }).hasUnread === 'boolean') {\n      this.setState({ hasUnread: Boolean((payload as { hasUnread: boolean }).hasUnread) });\n    }\n  }\n\n  private applySnapshot(snap: WireInboxSnapshot): void {\n    // Keep every non-tombstoned entry — including ARCHIVED rows — so the inbox view can\n    // render both the active list and the Archived toggle. `archived` is a distinct\n    // dimension from `tombstoned`; archived rows are still `state: 'active'`.\n    const registry = snap.registry.filter((e) => e.state === 'active');\n    // The DO's `hasUnread` is the authoritative dock dot. Per-row dots are derived from\n    // the same projection but exclude ARCHIVED rows (archive = done — an archived row\n    // never shows a dot). The DO clears unread on archive, so this is belt-and-braces.\n    this.setState({\n      registry,\n      hasUnread: Boolean(snap.hasUnread),\n      unreadChannelRefs: deriveUnreadRefs(snap),\n    });\n  }\n\n  private sendFrame(type: string, payload: Record<string, unknown>): boolean {\n    if (!this.socket || !this.socket.isOpen) return false;\n    this.socket.send(buildFrame(type, payload));\n    return true;\n  }\n\n  /** True if a specific channel/invite currently carries an unread dot. */\n  channelHasUnread(channelRef: string): boolean {\n    return this.state.unreadChannelRefs.includes(channelRef);\n  }\n\n  /**\n   * Clear a channel/invite's unread WITHOUT opening it (the inbox-view mark-read\n   * controls). Sends `mark-read` on the inbox socket; the inbox DO advances the\n   * member's read cursor to tail on the channel DO and then pushes a fresh\n   * authoritative snapshot, which is what removes the row — there is NO optimistic\n   * local clear, so a failed mark-read honestly leaves the dot in place.\n   * Returns false when the socket is not open (the caller may surface a retry).\n   */\n  markRead(channelRef: string): boolean {\n    return this.sendFrame(CLIENT_FRAME.MARK_READ, { channelRef });\n  }\n\n  /** Permanently close (auth-user switch / unmount). Idempotent. */\n  close(): void {\n    this.closedByUs = true;\n    this.controller.close();\n    if (this.reconnectTimer != null) {\n      this.timers.clearTimeout(this.reconnectTimer);\n      this.reconnectTimer = null;\n    }\n    if (this.socket) {\n      this.socket.close(1000, 'client teardown');\n      this.socket = null;\n    }\n    this.setState({ status: 'closed' });\n  }\n}\n\n/**\n * Derive the per-channel unread set from a snapshot. The current inbox DO snapshot\n * exposes a single `hasUnread` boolean (dock dot) + the active registry; it does\n * NOT yet enumerate which entries are unread. We surface a per-entry `unread`\n * field when the DO provides it (forward-compatible), else fall back to empty\n * per-row dots (the dock dot still lights). See the ASSUMPTIONS note in the docs.\n *\n * ARCHIVED rows are excluded from the unread roll-up (archive = done — the DO clears\n * unread on archive; the client also never counts them).\n */\nfunction deriveUnreadRefs(snap: WireInboxSnapshot): string[] {\n  const refs: string[] = [];\n  for (const e of snap.registry) {\n    if (e.state !== 'active') continue;\n    if (e.archived === true) continue;\n    if (e.unread === true) refs.push(e.channelRef);\n  }\n  return refs;\n}\n"]}
+{"version":3,"file":"inbox-client.js","sourceRoot":"","sources":["../../src/realtime/inbox-client.ts"],"names":[],"mappings":"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","sourcesContent":["// The Inbox realtime client: a SEPARATE WebSocket (scope `inbox`) to the user's\n// inbox DO. It maintains the channel/invite registry + unread projection that\n// drives the inbox view — DOTS ONLY, no counts (Contract C / \"Unread + inbox\").\n//\n// The inbox DO pushes a full `snapshot` ({ registry, hasUnread }) on connect, on\n// `resume`, and on every live delta (a projection apply). This client just\n// mirrors the latest snapshot into an observable store + a per-channel unread set.\n// Same connection lifecycle as the channel client (subprotocol auth, reconnect,\n// 4401 re-grant once, 4403 stop, auth-switch teardown).\n\nimport { createReconnectController, type ReconnectController } from '@ttt-productions/realtime-core';\nimport {\n  CLIENT_FRAME,\n  CHAT_CLOSE_CODES,\n  buildFrame,\n  parseFrame,\n  isInboxSnapshot,\n  type WireInboxSnapshot,\n  type WireRegistryEntry,\n} from './wire.js';\nimport type { RealtimeSocket, SocketFactory } from './socket.js';\nimport type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js';\nimport { defaultTimers, isChatAccessDeniedError } from './shared.js';\nimport {\n  createDiagnosticsEmitter,\n  safeDiagnosticLabel,\n  CHAT_CLIENT_DIAGNOSTIC_EVENTS as DIAG,\n  type ChatClientDiagnosticsEmitter,\n  type ChatClientDiagnosticsOption,\n} from './diagnostics.js';\n\nexport interface InboxClientState {\n  status: RealtimeStatus;\n  /** Active (non-tombstoned) channel/invite registry entries — inbox-view visibility. */\n  registry: WireRegistryEntry[];\n  /** True if ANY active channel/invite has unread (drives the dock dot). */\n  hasUnread: boolean;\n  /** The set of channelRefs that currently carry an unread dot (per-row dots). */\n  unreadChannelRefs: string[];\n  /**\n   * The last TERMINAL error code (mirrors `ChannelClientState.lastErrorCode`):\n   * `'access-denied'` when the inbox grant provider throws `ChatAccessDeniedError`\n   * (a genuine, terminal policy \"no\" — e.g. a banned/suspended account), and\n   * `'revoked'` on a 4403 REVOKED close. Null while healthy and across transient\n   * reconnects. The app subscribes to inbox state directly (there is no inbox React\n   * hook in this package), so this stable code is the surface — it invents no new UI.\n   */\n  lastErrorCode: string | null;\n}\n\nexport interface InboxClientConfig {\n  endpoint: string;\n  /** The authenticated uid (the inbox owner; the DO serves no one else's data). */\n  currentUserId: string;\n  /** Mints/refreshes an INBOX-scope grant (scope `{ kind:'inbox', uid }`). */\n  grantProvider: GrantProvider;\n  socketFactory: SocketFactory;\n  timers?: TransportTimers;\n  reconnect?: { baseDelayMs?: number; maxDelayMs?: number; maxAttempts?: number | null; random?: () => number };\n  /**\n   * OPT-IN structured client diagnostics — the SAME option type and emitter the\n   * channel client uses (one owner, `./diagnostics.ts`). Default OFF: absent or\n   * `false` changes nothing and costs one nullish check. `true` emits one\n   * single-line `console.debug` entry per decision under the stable\n   * `chat_client_inbox_*` names; a function routes them to the app's logger.\n   * Inbox payloads are SIZES ONLY — registry/unread counts and deltas, never a\n   * `channelRef` (which names one specific conversation).\n   */\n  diagnostics?: ChatClientDiagnosticsOption;\n}\n\nconst INITIAL: InboxClientState = { status: 'idle', registry: [], hasUnread: false, unreadChannelRefs: [], lastErrorCode: null };\n\nexport class InboxClient {\n  private readonly timers: TransportTimers;\n  private readonly controller: ReconnectController;\n  private socket: RealtimeSocket | null = null;\n  private state: InboxClientState = INITIAL;\n  private readonly listeners = new Set<(s: InboxClientState) => void>();\n  private reauthAttempted = false;\n  private reconnectTimer: ReturnType<TransportTimers['setTimeout']> | null = null;\n  private closedByUs = false;\n  /** Structured diagnostics emitter, or null when off (the default, zero-overhead). */\n  private readonly diag: ChatClientDiagnosticsEmitter;\n  /** Monotonic socket-open attempt counter (diagnostics correlation only). */\n  private connectAttempt = 0;\n  /** Why the CURRENT connect attempt is happening (diagnostics only). */\n  private reconnectCause: 'initial' | 'auth-expired' | 'transient-close' | 'grant-error' = 'initial';\n  /** The last close code observed, carried into the next attempt's cause line. */\n  private lastCloseCode: number | null = null;\n\n  constructor(private readonly config: InboxClientConfig) {\n    this.timers = config.timers ?? defaultTimers;\n    this.controller = createReconnectController(config.reconnect ?? {});\n    this.diag = createDiagnosticsEmitter(config.diagnostics);\n  }\n\n  getState(): InboxClientState {\n    return this.state;\n  }\n\n  subscribe(fn: (s: InboxClientState) => void): () => void {\n    this.listeners.add(fn);\n    return () => this.listeners.delete(fn);\n  }\n\n  private setState(patch: Partial<InboxClientState>): void {\n    this.state = { ...this.state, ...patch };\n    for (const fn of this.listeners) fn(this.state);\n  }\n\n  async connect(): Promise<void> {\n    this.closedByUs = false;\n    this.reconnectCause = 'initial';\n    this.controller.start();\n    this.setState({ status: 'connecting' });\n    await this.openSocket();\n  }\n\n  private async openSocket(): Promise<void> {\n    this.connectAttempt += 1;\n    this.diag?.(DIAG.INBOX_CONNECT_ATTEMPT, {\n      attempt: this.connectAttempt,\n      cause: this.reconnectCause,\n      closeCode: this.lastCloseCode,\n      registryCount: this.state.registry.length,\n    });\n    let grantToken: string;\n    try {\n      grantToken = await this.config.grantProvider();\n    } catch (err) {\n      // A TERMINAL access denial (the app translated an authoritative policy \"no\"\n      // — e.g. Firebase `permission-denied` for a banned/suspended account — into the\n      // package-owned ChatAccessDeniedError) must NOT reconnect: the next mint would\n      // just re-deny, reconnect-looping forever and warning every cycle. Every other\n      // mint failure (network/transient) stays retryable and backs off as before.\n      const terminal = isChatAccessDeniedError(err);\n      this.diag?.(DIAG.INBOX_GRANT_FAILED, { attempt: this.connectAttempt, terminal });\n      if (terminal) return this.denyAccessTerminally();\n      this.reconnectCause = 'grant-error';\n      return this.scheduleReconnect();\n    }\n    if (this.closedByUs) return;\n    const url = `${this.config.endpoint.replace(/\\/$/, '')}/inbox`;\n    this.socket = this.config.socketFactory({\n      url,\n      grantToken,\n      handlers: {\n        onOpen: () => this.onOpen(),\n        onMessage: (data) => this.onMessage(data),\n        onClose: (code, reason) => this.onClose(code, reason),\n        onError: () => undefined,\n      },\n    });\n  }\n\n  private onOpen(): void {\n    this.controller.onOpen();\n    this.reauthAttempted = false;\n    this.setState({ status: 'open' });\n    this.diag?.(DIAG.INBOX_SOCKET_OPEN, {\n      attempt: this.connectAttempt,\n      cause: this.reconnectCause,\n      registryCount: this.state.registry.length,\n      hasUnread: this.state.hasUnread,\n    });\n    // The DO sends a snapshot on accept; a `resume` re-requests it after a reconnect gap.\n    const sent = this.sendFrame(CLIENT_FRAME.RESUME, {});\n    // The inbox resume is CURSORLESS by contract (the DO always answers with a full\n    // authoritative snapshot) — there is no `afterSeq` half to record here.\n    this.diag?.(DIAG.INBOX_RESUME_REQUEST, { attempt: this.connectAttempt, cursorless: true, sent });\n  }\n\n  private onClose(code: number, _reason: string): void {\n    this.socket = null;\n    this.lastCloseCode = code;\n    if (this.closedByUs) {\n      this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: true, outcome: 'closed' });\n      this.setState({ status: 'closed' });\n      return;\n    }\n    if (code === CHAT_CLOSE_CODES.AUTH_EXPIRED && !this.reauthAttempted) {\n      this.reauthAttempted = true;\n      this.reconnectCause = 'auth-expired';\n      this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 're-grant' });\n      this.setState({ status: 'reconnecting' });\n      void this.openSocket();\n      return;\n    }\n    if (code === CHAT_CLOSE_CODES.REVOKED) {\n      this.closedByUs = true;\n      this.controller.close();\n      this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 'revoked' });\n      this.setState({ status: 'closed', lastErrorCode: 'revoked' });\n      return;\n    }\n    this.reconnectCause = 'transient-close';\n    this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 'reconnect' });\n    this.scheduleReconnect();\n  }\n\n  /**\n   * Terminal access denial surfaced by the inbox grant provider\n   * (`ChatAccessDeniedError`). Same terminal posture as the 4403 REVOKED close: mark\n   * closed-by-us, close the reconnect controller, and surface the stable\n   * `access-denied` code. The inbox client tracks NO optimistic/pending sends\n   * (mark-read is fire-and-forget with no local pending state), so — unlike\n   * ChannelClient — there is nothing to fail here; only the lifecycle stops.\n   */\n  private denyAccessTerminally(): void {\n    this.closedByUs = true;\n    this.controller.close();\n    this.setState({ status: 'closed', lastErrorCode: 'access-denied' });\n  }\n\n  private scheduleReconnect(): void {\n    const delay = this.controller.onClose();\n    this.diag?.(DIAG.INBOX_RECONNECT_SCHEDULED, {\n      delayMs: delay,\n      cause: this.reconnectCause,\n      attempt: this.connectAttempt,\n    });\n    if (delay == null) {\n      this.setState({ status: 'closed' });\n      return;\n    }\n    this.setState({ status: 'reconnecting' });\n    this.reconnectTimer = this.timers.setTimeout(() => {\n      this.reconnectTimer = null;\n      if (this.closedByUs) return;\n      void this.openSocket();\n    }, delay);\n  }\n\n  private onMessage(data: string): void {\n    const frame = parseFrame(data);\n    if (!frame || !frame.payload) {\n      this.diag?.(DIAG.INBOX_FRAME_DROPPED, { kind: 'unparseable', reason: 'bad-envelope' });\n      return;\n    }\n    // The inbox DO pushes a full `snapshot`; a future lightweight `unread` push\n    // carries either a full snapshot or a `{ hasUnread }` dock-dot patch. Route both\n    // instead of silently dropping the `unread` type (C-M2).\n    if (frame.type !== 'snapshot' && frame.type !== 'unread') {\n      this.diag?.(DIAG.INBOX_FRAME_DROPPED, { kind: safeDiagnosticLabel(frame.type), reason: 'unknown-type' });\n      return;\n    }\n    const payload = frame.payload as unknown as WireInboxSnapshot | { hasUnread: boolean };\n    if (isInboxSnapshot(payload as WireInboxSnapshot)) {\n      this.applySnapshot(payload as WireInboxSnapshot, frame.type);\n    } else if (frame.type === 'unread' && typeof (payload as { hasUnread?: unknown }).hasUnread === 'boolean') {\n      const hasUnread = Boolean((payload as { hasUnread: boolean }).hasUnread);\n      const before = this.state.hasUnread;\n      this.setState({ hasUnread });\n      if (before !== hasUnread) {\n        this.diag?.(DIAG.INBOX_UNREAD_UPDATED, {\n          source: 'unread-patch',\n          hasUnreadBefore: before,\n          hasUnreadAfter: hasUnread,\n          unreadCountBefore: this.state.unreadChannelRefs.length,\n          unreadCountAfter: this.state.unreadChannelRefs.length,\n          unreadCountDelta: 0,\n        });\n      }\n    } else {\n      // A stray CHANNEL snapshot ({ lastMessageSeq, readSeq }) on the inbox socket —\n      // deliberately inert, but never silently invisible under diagnostics.\n      this.diag?.(DIAG.INBOX_FRAME_DROPPED, {\n        kind: safeDiagnosticLabel(frame.type),\n        reason: 'not-an-inbox-payload',\n      });\n    }\n  }\n\n  private applySnapshot(snap: WireInboxSnapshot, source: string): void {\n    // Keep every non-tombstoned entry — including ARCHIVED rows — so the inbox view can\n    // render both the active list and the Archived toggle. `archived` is a distinct\n    // dimension from `tombstoned`; archived rows are still `state: 'active'`.\n    const registry = snap.registry.filter((e) => e.state === 'active');\n    // The DO's `hasUnread` is the authoritative dock dot. Per-row dots are derived from\n    // the same projection but exclude ARCHIVED rows (archive = done — an archived row\n    // never shows a dot). The DO clears unread on archive, so this is belt-and-braces.\n    const unreadChannelRefs = deriveUnreadRefs(snap);\n    const hasUnread = Boolean(snap.hasUnread);\n    const before = this.state;\n    this.setState({ registry, hasUnread, unreadChannelRefs });\n    if (!this.diag) return;\n    // SIZES ONLY — a channelRef names one specific conversation and never enters a\n    // diagnostic line.\n    this.diag(DIAG.INBOX_SNAPSHOT_APPLIED, {\n      source: safeDiagnosticLabel(source),\n      received: snap.registry.length,\n      // `received - active` is the tombstoned count the client filtered out.\n      active: registry.length,\n      archived: registry.filter((e) => e.archived === true).length,\n      hasUnread,\n      unreadCount: unreadChannelRefs.length,\n      registryDelta: registry.length - before.registry.length,\n    });\n    const unreadChanged =\n      before.hasUnread !== hasUnread || before.unreadChannelRefs.length !== unreadChannelRefs.length;\n    if (unreadChanged) {\n      this.diag(DIAG.INBOX_UNREAD_UPDATED, {\n        source: safeDiagnosticLabel(source),\n        hasUnreadBefore: before.hasUnread,\n        hasUnreadAfter: hasUnread,\n        unreadCountBefore: before.unreadChannelRefs.length,\n        unreadCountAfter: unreadChannelRefs.length,\n        unreadCountDelta: unreadChannelRefs.length - before.unreadChannelRefs.length,\n      });\n    }\n  }\n\n  private sendFrame(type: string, payload: Record<string, unknown>): boolean {\n    if (!this.socket || !this.socket.isOpen) return false;\n    this.socket.send(buildFrame(type, payload));\n    return true;\n  }\n\n  /** True if a specific channel/invite currently carries an unread dot. */\n  channelHasUnread(channelRef: string): boolean {\n    return this.state.unreadChannelRefs.includes(channelRef);\n  }\n\n  /**\n   * Clear a channel/invite's unread WITHOUT opening it (the inbox-view mark-read\n   * controls). Sends `mark-read` on the inbox socket; the inbox DO advances the\n   * member's read cursor to tail on the channel DO and then pushes a fresh\n   * authoritative snapshot, which is what removes the row — there is NO optimistic\n   * local clear, so a failed mark-read honestly leaves the dot in place.\n   * Returns false when the socket is not open (the caller may surface a retry).\n   */\n  markRead(channelRef: string): boolean {\n    const sent = this.sendFrame(CLIENT_FRAME.MARK_READ, { channelRef });\n    // The ref itself is never logged — only that a mark-read was written and what the\n    // unread projection looked like at that moment (the DO's snapshot is what clears it).\n    this.diag?.(DIAG.INBOX_MARK_READ, { sent, unreadCount: this.state.unreadChannelRefs.length });\n    return sent;\n  }\n\n  /** Permanently close (auth-user switch / unmount). Idempotent. */\n  close(): void {\n    this.closedByUs = true;\n    this.controller.close();\n    if (this.reconnectTimer != null) {\n      this.timers.clearTimeout(this.reconnectTimer);\n      this.reconnectTimer = null;\n    }\n    if (this.socket) {\n      this.socket.close(1000, 'client teardown');\n      this.socket = null;\n    }\n    this.setState({ status: 'closed' });\n  }\n}\n\n/**\n * Derive the per-channel unread set from a snapshot. The current inbox DO snapshot\n * exposes a single `hasUnread` boolean (dock dot) + the active registry; it does\n * NOT yet enumerate which entries are unread. We surface a per-entry `unread`\n * field when the DO provides it (forward-compatible), else fall back to empty\n * per-row dots (the dock dot still lights). See the ASSUMPTIONS note in the docs.\n *\n * ARCHIVED rows are excluded from the unread roll-up (archive = done — the DO clears\n * unread on archive; the client also never counts them).\n */\nfunction deriveUnreadRefs(snap: WireInboxSnapshot): string[] {\n  const refs: string[] = [];\n  for (const e of snap.registry) {\n    if (e.state !== 'active') continue;\n    if (e.archived === true) continue;\n    if (e.unread === true) refs.push(e.channelRef);\n  }\n  return refs;\n}\n"]}

package/dist/realtime/index.d.ts

@@ -6,6 +6,8 @@ export type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js
 export { defaultTimers, ChatAccessDeniedError, isChatAccessDeniedError, HEARTBEAT_MS, TYPING_COALESCE_MS, HISTORY_PAGE_MAX, } from './shared.js';
 export { wireRowToMessage, optimisticMessage, seqToMessageId, applyModerationOverlay, overlayFromRow, MODERATION_REDACTED_TEXT, } from './map.js';
 export type { ModerationOverlay } from './map.js';
+export { CHAT_CLIENT_DIAGNOSTIC_EVENTS } from './diagnostics.js';
+export type { ChatClientDiagnosticsOption, ChatClientDiagnosticsSink, ChatClientDiagnosticEventName, } from './diagnostics.js';
 export { ChannelClient } from './channel-client.js';
 export type { ChannelClientState, ChannelClientConfig } from './channel-client.js';
 export { InboxClient } from './inbox-client.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACjE,YAAY,EACV,2BAA2B,EAC3B,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/realtime/index.js

@@ -7,6 +7,7 @@ export { CHAT_SUBPROTOCOL, CHAT_WIRE_VERSION, CHAT_CLOSE_CODES, CLIENT_FRAME, SE
 export { browserSocketFactory } from './socket.js';
 export { defaultTimers, ChatAccessDeniedError, isChatAccessDeniedError, HEARTBEAT_MS, TYPING_COALESCE_MS, HISTORY_PAGE_MAX, } from './shared.js';
 export { wireRowToMessage, optimisticMessage, seqToMessageId, applyModerationOverlay, overlayFromRow, MODERATION_REDACTED_TEXT, } from './map.js';
+export { CHAT_CLIENT_DIAGNOSTIC_EVENTS } from './diagnostics.js';
 export { ChannelClient } from './channel-client.js';
 export { InboxClient } from './inbox-client.js';
 export { createRealtimeChatClient, createInboxClient, } from './transport.js';

package/dist/realtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,sEAAsE;AACtE,uEAAuE;AACvE,mCAAmC;AAEnC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAC;AAanB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["// The realtime (Cloudflare Durable Object) chat transport — the client half of\n// the chat Worker wire protocol (Contract A connection + Contract C wire). The\n// FIRESTORE transport stays the unchanged default; this is opt-in via\n// `ChatCoreConfig.transport === 'realtime'` + a `realtime.client` from\n// `createRealtimeChatClient(...)`.\n\nexport {\n  CHAT_SUBPROTOCOL,\n  CHAT_WIRE_VERSION,\n  CHAT_CLOSE_CODES,\n  CLIENT_FRAME,\n  SERVER_FRAME,\n  buildFrame,\n  parseFrame,\n  isInboxSnapshot,\n} from './wire.js';\nexport type {\n  ChannelRefTuple,\n  ChatCloseCode,\n  WireMessageRow,\n  WireChannelSnapshot,\n  WireInboxSnapshot,\n  WireRegistryEntry,\n  ServerFrame,\n  RevisionKind,\n} from './wire.js';\n\nexport type { RealtimeSocket, SocketFactory, SocketHandlers } from './socket.js';\nexport { browserSocketFactory } from './socket.js';\n\nexport type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js';\nexport {\n  defaultTimers,\n  ChatAccessDeniedError,\n  isChatAccessDeniedError,\n  HEARTBEAT_MS,\n  TYPING_COALESCE_MS,\n  HISTORY_PAGE_MAX,\n} from './shared.js';\n\nexport {\n  wireRowToMessage,\n  optimisticMessage,\n  seqToMessageId,\n  applyModerationOverlay,\n  overlayFromRow,\n  MODERATION_REDACTED_TEXT,\n} from './map.js';\nexport type { ModerationOverlay } from './map.js';\n\nexport { ChannelClient } from './channel-client.js';\nexport type { ChannelClientState, ChannelClientConfig } from './channel-client.js';\nexport { InboxClient } from './inbox-client.js';\nexport type { InboxClientState, InboxClientConfig } from './inbox-client.js';\n\nexport {\n  createRealtimeChatClient,\n  createInboxClient,\n} from './transport.js';\nexport type { RealtimeChatClient, RealtimeTransportConfig } from './transport.js';\n\nexport { useRealtimeChatMessages } from './useRealtimeChatMessages.js';\nexport type { UseRealtimeChatMessagesResult } from './useRealtimeChatMessages.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,sEAAsE;AACtE,uEAAuE;AACvE,mCAAmC;AAEnC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAC;AAanB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAOjE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["// The realtime (Cloudflare Durable Object) chat transport — the client half of\n// the chat Worker wire protocol (Contract A connection + Contract C wire). The\n// FIRESTORE transport stays the unchanged default; this is opt-in via\n// `ChatCoreConfig.transport === 'realtime'` + a `realtime.client` from\n// `createRealtimeChatClient(...)`.\n\nexport {\n  CHAT_SUBPROTOCOL,\n  CHAT_WIRE_VERSION,\n  CHAT_CLOSE_CODES,\n  CLIENT_FRAME,\n  SERVER_FRAME,\n  buildFrame,\n  parseFrame,\n  isInboxSnapshot,\n} from './wire.js';\nexport type {\n  ChannelRefTuple,\n  ChatCloseCode,\n  WireMessageRow,\n  WireChannelSnapshot,\n  WireInboxSnapshot,\n  WireRegistryEntry,\n  ServerFrame,\n  RevisionKind,\n} from './wire.js';\n\nexport type { RealtimeSocket, SocketFactory, SocketHandlers } from './socket.js';\nexport { browserSocketFactory } from './socket.js';\n\nexport type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js';\nexport {\n  defaultTimers,\n  ChatAccessDeniedError,\n  isChatAccessDeniedError,\n  HEARTBEAT_MS,\n  TYPING_COALESCE_MS,\n  HISTORY_PAGE_MAX,\n} from './shared.js';\n\nexport {\n  wireRowToMessage,\n  optimisticMessage,\n  seqToMessageId,\n  applyModerationOverlay,\n  overlayFromRow,\n  MODERATION_REDACTED_TEXT,\n} from './map.js';\nexport type { ModerationOverlay } from './map.js';\n\nexport { CHAT_CLIENT_DIAGNOSTIC_EVENTS } from './diagnostics.js';\nexport type {\n  ChatClientDiagnosticsOption,\n  ChatClientDiagnosticsSink,\n  ChatClientDiagnosticEventName,\n} from './diagnostics.js';\n\nexport { ChannelClient } from './channel-client.js';\nexport type { ChannelClientState, ChannelClientConfig } from './channel-client.js';\nexport { InboxClient } from './inbox-client.js';\nexport type { InboxClientState, InboxClientConfig } from './inbox-client.js';\n\nexport {\n  createRealtimeChatClient,\n  createInboxClient,\n} from './transport.js';\nexport type { RealtimeChatClient, RealtimeTransportConfig } from './transport.js';\n\nexport { useRealtimeChatMessages } from './useRealtimeChatMessages.js';\nexport type { UseRealtimeChatMessagesResult } from './useRealtimeChatMessages.js';\n"]}

package/dist/realtime/transport.d.ts

@@ -2,6 +2,7 @@ import { ChannelClient, type ChannelClientConfig, type ChannelClientState } from
 import { InboxClient, type InboxClientConfig, type InboxClientState } from './inbox-client.js';
 import { type SocketFactory } from './socket.js';
 import type { GrantProvider, TransportTimers } from './shared.js';
+import type { ChatClientDiagnosticsOption } from './diagnostics.js';
 import type { ChannelRefTuple } from './wire.js';
 /**
  * Everything the channel transport needs. The app supplies `grantProvider`
@@ -17,6 +18,14 @@ 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`.
@@ -43,6 +52,8 @@ 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;
 export type { ChannelClientState, InboxClientState };
 //# sourceMappingURL=transport.d.ts.map