@rei-standard/amsg-client 2.5.0-next.0 → 2.6.0

package/README.md

@@ -165,6 +165,8 @@ interface DeliverOptions {
 
   timeoutMs: number;                                       // 总预算（含 transport + grace）
   onChunk?: (payload: unknown) => Promise<void> | void;    // 可选 SSE 每帧钩子，抛错被吞
+  onRawRead?: (meta: RawReadMeta) => void;                 // 可选 SSE 原始读遥测，排查链路用；抛错被吞
+                                                            // 每次 reader.read() 后触发，保留 ':' 注释行
   postTransportGraceMs?: number;                           // transport 结束后等观察的 grace
                                                             // 默认 = min(remaining, max(5000, timeoutMs * 0.1))
                                                             // cancel 路径下生效的是 grace / 2
@@ -183,8 +185,20 @@ interface ObservedDeliveryReceipt {
   sessionId?: string;        // ↑
   channel?: string;          // 'sw' / 'ipc' / 'native' / 'poll' / 任意诊断 label
 }
+
+interface RawReadMeta {
+  ts: number;                // Date.now()
+  byteLength: number;        // 本次 reader.read() 拿到的字节数
+  done: boolean;             // 流是否结束
+  textPreview: string;       // 本次数据解码后的前 120 字符，保留 ':' keepalive 注释行
+  status?: number;           // 仅首帧带：响应状态码
+  contentEncoding?: string | null;  // 仅首帧带：响应 Content-Encoding（查是否被边缘压缩）
+  contentType?: string | null;      // 仅首帧带
+}
 ```
 
+> `onRawRead` 是诊断钩子：SSE 解析层默认丢弃 `:` 注释行（含每秒一发的 keepalive），出问题时无从判断「静默期里到底有没有字节到达」。挂上它就能在 raw `reader.read()` 这一层看到每次读到的原始字节与 keepalive 帧。不传则零开销、行为不变。
+
 ### `delivery.mode` 必须显式选
 
 | mode | 何时用 | outcome 取值 |

package/dist/index.cjs

@@ -19,21 +19,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
-  MESSAGE_KIND: () => import_amsg_shared.MESSAGE_KIND,
-  MESSAGE_TYPE: () => import_amsg_shared.MESSAGE_TYPE,
-  PUSH_SOURCE: () => import_amsg_shared.PUSH_SOURCE,
+  MESSAGE_KIND: () => import_amsg_shared2.MESSAGE_KIND,
+  MESSAGE_TYPE: () => import_amsg_shared2.MESSAGE_TYPE,
+  PUSH_SOURCE: () => import_amsg_shared2.PUSH_SOURCE,
   ReiClient: () => ReiClient,
-  buildContentPush: () => import_amsg_shared.buildContentPush,
-  buildErrorPush: () => import_amsg_shared.buildErrorPush,
-  buildReasoningPush: () => import_amsg_shared.buildReasoningPush,
-  buildToolRequestPush: () => import_amsg_shared.buildToolRequestPush,
-  isContentPush: () => import_amsg_shared.isContentPush,
-  isErrorPush: () => import_amsg_shared.isErrorPush,
-  isReasoningPush: () => import_amsg_shared.isReasoningPush,
-  isToolRequestPush: () => import_amsg_shared.isToolRequestPush
+  buildContentPush: () => import_amsg_shared2.buildContentPush,
+  buildErrorPush: () => import_amsg_shared2.buildErrorPush,
+  buildReasoningPush: () => import_amsg_shared2.buildReasoningPush,
+  buildToolRequestPush: () => import_amsg_shared2.buildToolRequestPush,
+  isContentPush: () => import_amsg_shared2.isContentPush,
+  isErrorPush: () => import_amsg_shared2.isErrorPush,
+  isReasoningPush: () => import_amsg_shared2.isReasoningPush,
+  isToolRequestPush: () => import_amsg_shared2.isToolRequestPush
 });
 module.exports = __toCommonJS(src_exports);
 var import_amsg_shared = require("@rei-standard/amsg-shared");
+var import_amsg_shared2 = require("@rei-standard/amsg-shared");
+var TEXT_ENCODER = new TextEncoder();
 var AVATAR_URL_MAX_LENGTH = 2048;
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
@@ -187,11 +189,11 @@ var ReiClient = class {
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string, expectsBackupPush?: boolean }} [opts]
    *   - `authorization`: optional auth header to forward.
-   *   - `expectsBackupPush`: opt-in flag for the dev warning. Set to `true`
-   *     to log a one-shot console.warn confirming you understand the
-   *     "200 ≠ delivered" pitfall and have your own out-of-band check
-   *     (or migrated to `deliver()`). Set to `false` to explicitly silence
-   *     the warning (you have read this contract).
+   *   - `expectsBackupPush`: opt-in dev reminder. Set to `true` to log a
+   *     one-shot console.warn that this is a low-level transport and
+   *     "HTTP 200 ≠ delivery confirmation" once the worker has backup
+   *     push enabled (amsg-instant 0.9.0+ default). Default (omitted) is
+   *     silent.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
@@ -201,6 +203,7 @@ var ReiClient = class {
       endpointPath,
       { authorization: opts.authorization, methodName: "sendInstant" }
     );
+    headers["Accept"] = "application/json";
     const res = await fetch(url, { method: "POST", headers, body });
     return res.json();
   }
@@ -231,10 +234,10 @@ var ReiClient = class {
    * @param {(error: unknown) => void} [options.onError]
    * @param {() => void} [options.onDone]
    * @param {AbortSignal} [options.signal]
-   * @param {boolean} [options.expectsBackupPush] - Opt-in flag for the dev warning.
-   *   Set to `true` to log a one-shot console.warn confirming you understand the
-   *   "rejection ≠ delivery failure" pitfall and have your own check (or migrated
-   *   to `deliver()`). Set to `false` to explicitly silence the warning.
+   * @param {boolean} [options.expectsBackupPush] - Opt-in dev reminder. Set
+   *   to `true` to log a one-shot console.warn that "rejection ≠ delivery
+   *   failure" once the worker has backup push enabled (amsg-instant 0.9.0+
+   *   default). Default (omitted) is silent.
    * @returns {Promise<void>}
    */
   async consumeInstantStream(payload, endpointPath = "/instant", options = {}) {
@@ -312,7 +315,8 @@ var ReiClient = class {
       signal,
       headers,
       authorization,
-      endpointPath
+      endpointPath,
+      onRawRead
     } = opts;
     if (!delivery || typeof delivery !== "object") {
       throw new TypeError("[rei-standard-amsg-client] deliver() requires opts.delivery (discriminated union)");
@@ -373,7 +377,8 @@ var ReiClient = class {
       try {
         const result = await this._runInstantTransport(built, {
           signal: internalAbort.signal,
-          onChunk: wrappedOnChunk
+          onChunk: wrappedOnChunk,
+          onRawRead
         });
         if (finalized) return;
         transportEnded = true;
@@ -551,7 +556,7 @@ var ReiClient = class {
   async subscribePush(vapidPublicKey, registration) {
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
-      applicationServerKey: this._urlBase64ToUint8Array(vapidPublicKey)
+      applicationServerKey: (0, import_amsg_shared.base64UrlToBytes)(vapidPublicKey)
     });
     return subscription;
   }
@@ -599,7 +604,7 @@ var ReiClient = class {
    */
   _assertPayloadSize(bodyJson, methodName) {
     if (this._maxPayloadBytes == null) return;
-    const bytes = new TextEncoder().encode(bodyJson).length;
+    const bytes = TEXT_ENCODER.encode(bodyJson).length;
     if (bytes > this._maxPayloadBytes) {
       throw makeLocalError(
         "PAYLOAD_TOO_LARGE_LOCAL",
@@ -652,11 +657,12 @@ var ReiClient = class {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk } = opts;
+    const { signal, onChunk, onRawRead } = opts;
     const { url, headers, body } = built;
     const res = await fetch(url, { method: "POST", headers, body, signal });
     if (!res.ok) {
@@ -669,7 +675,15 @@ var ReiClient = class {
     const kind = classifyContentType(contentType);
     if (kind === "sse") {
       if (!res.body) throw new Error("Response body is null");
-      await this._consumeSseStream(res, { onPayload: onChunk });
+      await this._consumeSseStream(res, {
+        onPayload: onChunk,
+        onRawRead,
+        responseMeta: {
+          status: res.status,
+          contentEncoding: res.headers.get("content-encoding"),
+          contentType: res.headers.get("content-type")
+        }
+      });
       return { kind: "sse" };
     }
     if (kind === "json") {
@@ -686,15 +700,47 @@ var ReiClient = class {
    *
    * @private
    * @param {Response} res
-   * @param {{ onPayload?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{
+   *   onPayload?: (p: unknown) => Promise<void> | void,
+   *   onRawRead?: (meta: RawReadMeta) => void,
+   *   responseMeta?: { status?: number, contentEncoding?: string | null, contentType?: string | null }
+   * }} opts
+   *   `onRawRead` (if supplied) fires once per `reader.read()` before any SSE parsing/filtering — it sees
+   *   raw bytes including `: keepalive` comment frames. Throws from it are swallowed. `responseMeta` is
+   *   attached to the FIRST `onRawRead` call only. See `DeliverOptions.onRawRead`.
    * @returns {Promise<void>}
    */
   async _consumeSseStream(res, opts) {
-    const { onPayload } = opts;
+    const { onPayload, onRawRead, responseMeta } = opts;
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
     let thrown;
+    const previewDecoder = onRawRead ? new TextDecoder() : null;
+    let rawReadFired = false;
+    const emitRawRead = (done, value) => {
+      if (!onRawRead) return;
+      try {
+        let textPreview = "";
+        if (value && value.byteLength) {
+          textPreview = previewDecoder.decode(value).slice(0, 120);
+        }
+        const meta = {
+          ts: Date.now(),
+          byteLength: value && value.byteLength ? value.byteLength : 0,
+          done: !!done,
+          textPreview
+        };
+        if (!rawReadFired) {
+          meta.status = responseMeta ? responseMeta.status : void 0;
+          meta.contentEncoding = responseMeta ? responseMeta.contentEncoding : void 0;
+          meta.contentType = responseMeta ? responseMeta.contentType : void 0;
+        }
+        rawReadFired = true;
+        onRawRead(meta);
+      } catch {
+      }
+    };
     const processFrame = async (part) => {
       if (!part.trim()) return null;
       let eventName = "message";
@@ -736,6 +782,7 @@ ${piece}` : piece;
     try {
       while (true) {
         const { done, value } = await reader.read();
+        emitRawRead(done, value);
         if (done) {
           buffer += decoder.decode();
           const finalNormalized = buffer.replace(SSE_LINE_NORMALIZE, "\n");
@@ -871,10 +918,10 @@ ${piece}` : piece;
     return Math.min(defaultGrace, remainingMs);
   }
   /**
-   * One-shot dev warning for low-level instant APIs. The warning is opt-in
-   * per call via `opts.expectsBackupPush === true`, and can be explicitly
-   * silenced via `opts.expectsBackupPush === false`. Fires at most once per
-   * ReiClient instance per method name.
+   * One-shot dev reminder for low-level instant APIs. The warning is opt-in
+   * per call via `opts.expectsBackupPush === true` and fires at most once
+   * per ReiClient instance per method name. Default (omitted or `false`)
+   * is silent.
    *
    * @private
    * @param {string} methodName
@@ -886,7 +933,7 @@ ${piece}` : piece;
     this._lowLevelWarned.add(methodName);
     const verdict = methodName === "sendInstant" ? "HTTP 200 \u2260 delivery confirmation" : "rejection \u2260 delivery failure";
     console.warn(
-      `[rei-standard-amsg-client] ${methodName} is a low-level transport \u2014 ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict. Pass expectsBackupPush: false to silence this warning.`
+      `[rei-standard-amsg-client] ${methodName} is a low-level transport \u2014 ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict.`
     );
   }
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
@@ -900,7 +947,7 @@ ${piece}` : piece;
     if (!this._userKey) throw new Error("[rei-standard-amsg-client] Not initialised. Call init() first.");
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const key = await crypto.subtle.importKey("raw", this._userKey, { name: "AES-GCM" }, false, ["encrypt"]);
-    const encoded = new TextEncoder().encode(plaintext);
+    const encoded = TEXT_ENCODER.encode(plaintext);
     const cipherBuf = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);
     const cipherArr = new Uint8Array(cipherBuf);
     const encryptedData = cipherArr.slice(0, cipherArr.length - 16);
@@ -953,15 +1000,6 @@ ${piece}` : piece;
     }
     return arr;
   }
-  /** @private */
-  _urlBase64ToUint8Array(base64String) {
-    const padding = "=".repeat((4 - base64String.length % 4) % 4);
-    const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
-    const raw = atob(base64);
-    const arr = new Uint8Array(raw.length);
-    for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
-    return arr;
-  }
 };
 function normalizeMaxPayloadBytes(value) {
   if (value === void 0 || value === null) return null;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { base64UrlToBytes } from '@rei-standard/amsg-shared';
 export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPush, buildReasoningPush, buildToolRequestPush, isContentPush, isErrorPush, isReasoningPush, isToolRequestPush } from '@rei-standard/amsg-shared';
 
 /**
@@ -30,6 +31,11 @@ export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPu
  *   await client.scheduleMessage({ ... });
  */
 
+
+// `TextEncoder` is stateless — hoist once instead of allocating a fresh
+// instance for every encrypt + payload-size check.
+const TEXT_ENCODER = new TextEncoder();
+
 /** @typedef {import('@rei-standard/amsg-shared').MessageKind} MessageKind */
 /** @typedef {import('@rei-standard/amsg-shared').MessageType} MessageType */
 /** @typedef {import('@rei-standard/amsg-shared').PushSource} PushSource */
@@ -189,6 +195,29 @@ export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPu
  *   `deliver()` don't silently drop the header.
  * @property {string}   [endpointPath='/instant']  - Path under the resolved instant base URL. Pass
  *   `'/continue'` for tool-result resume on amsg-instant 0.9.0+.
+ * @property {(meta: RawReadMeta) => void} [onRawRead] - Optional raw-read telemetry hook for the
+ *   foreground SSE transport. Fires once per `reader.read()` BEFORE any SSE parsing/filtering, so it
+ *   sees every byte that reached the client — including `: keepalive` comment frames that the parser
+ *   silently drops. Use it to tell "connection alive but no business data" apart from "no bytes flowing
+ *   at all" when diagnosing stalled streams. Purely observational: throws are swallowed and never affect
+ *   transport. Not invoked for the JSON transport.
+ */
+
+/**
+ * Metadata for a single raw `reader.read()` on the SSE body, passed to
+ * `DeliverOptions.onRawRead`. The response-meta fields
+ * (`status` / `contentEncoding` / `contentType`) are only populated on the
+ * first invocation; later calls omit them.
+ *
+ * @typedef {Object} RawReadMeta
+ * @property {number}  ts                       - `Date.now()` at the moment the read resolved.
+ * @property {number}  byteLength               - Bytes in this chunk (`value?.byteLength ?? 0`).
+ * @property {boolean} done                     - The `done` flag from `reader.read()`.
+ * @property {string}  textPreview              - First ~120 chars of this chunk decoded as UTF-8,
+ *   WITHOUT any keepalive/comment filtering (so `:`-prefixed lines stay visible).
+ * @property {string|null} [contentEncoding]    - `res.headers.get('content-encoding')`. First call only.
+ * @property {string|null} [contentType]        - `res.headers.get('content-type')`. First call only.
+ * @property {number}  [status]                 - `res.status`. First call only.
  */
 
 /**
@@ -400,11 +429,11 @@ class ReiClient {
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string, expectsBackupPush?: boolean }} [opts]
    *   - `authorization`: optional auth header to forward.
-   *   - `expectsBackupPush`: opt-in flag for the dev warning. Set to `true`
-   *     to log a one-shot console.warn confirming you understand the
-   *     "200 ≠ delivered" pitfall and have your own out-of-band check
-   *     (or migrated to `deliver()`). Set to `false` to explicitly silence
-   *     the warning (you have read this contract).
+   *   - `expectsBackupPush`: opt-in dev reminder. Set to `true` to log a
+   *     one-shot console.warn that this is a low-level transport and
+   *     "HTTP 200 ≠ delivery confirmation" once the worker has backup
+   *     push enabled (amsg-instant 0.9.0+ default). Default (omitted) is
+   *     silent.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = '/instant', opts = {}) {
@@ -415,6 +444,10 @@ class ReiClient {
       endpointPath,
       { authorization: opts.authorization, methodName: 'sendInstant' }
     );
+    // Pin the response shape: amsg-instant routes the JSON `{ success, data }`
+    // envelope only when the caller asked exclusively for it. Omitting Accept
+    // gets the SSE branch and `res.json()` then throws on the SSE bytes.
+    headers['Accept'] = 'application/json';
 
     const res = await fetch(url, { method: 'POST', headers, body });
     return res.json();
@@ -447,10 +480,10 @@ class ReiClient {
    * @param {(error: unknown) => void} [options.onError]
    * @param {() => void} [options.onDone]
    * @param {AbortSignal} [options.signal]
-   * @param {boolean} [options.expectsBackupPush] - Opt-in flag for the dev warning.
-   *   Set to `true` to log a one-shot console.warn confirming you understand the
-   *   "rejection ≠ delivery failure" pitfall and have your own check (or migrated
-   *   to `deliver()`). Set to `false` to explicitly silence the warning.
+   * @param {boolean} [options.expectsBackupPush] - Opt-in dev reminder. Set
+   *   to `true` to log a one-shot console.warn that "rejection ≠ delivery
+   *   failure" once the worker has backup push enabled (amsg-instant 0.9.0+
+   *   default). Default (omitted) is silent.
    * @returns {Promise<void>}
    */
   async consumeInstantStream(payload, endpointPath = '/instant', options = {}) {
@@ -526,7 +559,7 @@ class ReiClient {
     }
     const {
       delivery, timeoutMs, onChunk, postTransportGraceMs,
-      signal, headers, authorization, endpointPath,
+      signal, headers, authorization, endpointPath, onRawRead,
     } = opts;
 
     if (!delivery || typeof delivery !== 'object') {
@@ -619,6 +652,7 @@ class ReiClient {
         const result = await this._runInstantTransport(built, {
           signal: internalAbort.signal,
           onChunk: wrappedOnChunk,
+          onRawRead,
         });
         if (finalized) return;
         transportEnded = true;
@@ -860,7 +894,7 @@ class ReiClient {
   async subscribePush(vapidPublicKey, registration) {
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
-      applicationServerKey: this._urlBase64ToUint8Array(vapidPublicKey)
+      applicationServerKey: base64UrlToBytes(vapidPublicKey)
     });
     return subscription;
   }
@@ -911,7 +945,7 @@ class ReiClient {
    */
   _assertPayloadSize(bodyJson, methodName) {
     if (this._maxPayloadBytes == null) return;
-    const bytes = new TextEncoder().encode(bodyJson).length;
+    const bytes = TEXT_ENCODER.encode(bodyJson).length;
     if (bytes > this._maxPayloadBytes) {
       throw makeLocalError(
         'PAYLOAD_TOO_LARGE_LOCAL',
@@ -971,11 +1005,12 @@ class ReiClient {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk } = opts;
+    const { signal, onChunk, onRawRead } = opts;
     const { url, headers, body } = built;
 
     const res = await fetch(url, { method: 'POST', headers, body, signal });
@@ -991,7 +1026,15 @@ class ReiClient {
     const kind = classifyContentType(contentType);
     if (kind === 'sse') {
       if (!res.body) throw new Error('Response body is null');
-      await this._consumeSseStream(res, { onPayload: onChunk });
+      await this._consumeSseStream(res, {
+        onPayload: onChunk,
+        onRawRead,
+        responseMeta: {
+          status: res.status,
+          contentEncoding: res.headers.get('content-encoding'),
+          contentType: res.headers.get('content-type'),
+        },
+      });
       return { kind: 'sse' };
     }
     if (kind === 'json') {
@@ -1009,16 +1052,54 @@ class ReiClient {
    *
    * @private
    * @param {Response} res
-   * @param {{ onPayload?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{
+   *   onPayload?: (p: unknown) => Promise<void> | void,
+   *   onRawRead?: (meta: RawReadMeta) => void,
+   *   responseMeta?: { status?: number, contentEncoding?: string | null, contentType?: string | null }
+   * }} opts
+   *   `onRawRead` (if supplied) fires once per `reader.read()` before any SSE parsing/filtering — it sees
+   *   raw bytes including `: keepalive` comment frames. Throws from it are swallowed. `responseMeta` is
+   *   attached to the FIRST `onRawRead` call only. See `DeliverOptions.onRawRead`.
    * @returns {Promise<void>}
    */
   async _consumeSseStream(res, opts) {
-    const { onPayload } = opts;
+    const { onPayload, onRawRead, responseMeta } = opts;
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
     let thrown;
 
+    // Raw read-loop telemetry (opt-in via onRawRead). Kept completely
+    // separate from the parsing path: a one-shot decoder for the preview so
+    // it never perturbs the streaming `decoder` above, and the first call
+    // carries response meta (status / encoding / content-type).
+    const previewDecoder = onRawRead ? new TextDecoder() : null;
+    let rawReadFired = false;
+    const emitRawRead = (done, value) => {
+      if (!onRawRead) return;
+      try {
+        let textPreview = '';
+        if (value && value.byteLength) {
+          // One-shot decode (no { stream: true }) so we don't carry state
+          // between calls and disturb the main buffer's decoder.
+          textPreview = previewDecoder.decode(value).slice(0, 120);
+        }
+        const meta = {
+          ts: Date.now(),
+          byteLength: value && value.byteLength ? value.byteLength : 0,
+          done: !!done,
+          textPreview,
+        };
+        if (!rawReadFired) {
+          meta.status = responseMeta ? responseMeta.status : undefined;
+          meta.contentEncoding = responseMeta ? responseMeta.contentEncoding : undefined;
+          meta.contentType = responseMeta ? responseMeta.contentType : undefined;
+        }
+        rawReadFired = true;
+        onRawRead(meta);
+      } catch { /* telemetry must never break the transport */ }
+    };
+
     // Parse one SSE frame body (lines between two terminators). Returns
     // `'done'` if the frame signals end-of-stream so the caller can
     // unwind without consuming further frames. Throws on `event: error`.
@@ -1061,6 +1142,7 @@ class ReiClient {
     try {
       while (true) {
         const { done, value } = await reader.read();
+        emitRawRead(done, value);
         if (done) {
           // Flush any tail bytes the decoder held back (partial UTF-8
           // sequences split across the final chunk boundary).
@@ -1204,10 +1286,10 @@ class ReiClient {
   }
 
   /**
-   * One-shot dev warning for low-level instant APIs. The warning is opt-in
-   * per call via `opts.expectsBackupPush === true`, and can be explicitly
-   * silenced via `opts.expectsBackupPush === false`. Fires at most once per
-   * ReiClient instance per method name.
+   * One-shot dev reminder for low-level instant APIs. The warning is opt-in
+   * per call via `opts.expectsBackupPush === true` and fires at most once
+   * per ReiClient instance per method name. Default (omitted or `false`)
+   * is silent.
    *
    * @private
    * @param {string} methodName
@@ -1221,7 +1303,7 @@ class ReiClient {
       ? 'HTTP 200 ≠ delivery confirmation'
       : 'rejection ≠ delivery failure';
     console.warn(
-      `[rei-standard-amsg-client] ${methodName} is a low-level transport — ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict. Pass expectsBackupPush: false to silence this warning.`
+      `[rei-standard-amsg-client] ${methodName} is a low-level transport — ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict.`
     );
   }
 
@@ -1238,7 +1320,7 @@ class ReiClient {
 
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const key = await crypto.subtle.importKey('raw', this._userKey, { name: 'AES-GCM' }, false, ['encrypt']);
-    const encoded = new TextEncoder().encode(plaintext);
+    const encoded = TEXT_ENCODER.encode(plaintext);
     const cipherBuf = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, encoded);
 
     // Web Crypto appends the 16-byte auth tag at the end of the ciphertext
@@ -1302,15 +1384,6 @@ class ReiClient {
     return arr;
   }
 
-  /** @private */
-  _urlBase64ToUint8Array(base64String) {
-    const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
-    const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
-    const raw = atob(base64);
-    const arr = new Uint8Array(raw.length);
-    for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
-    return arr;
-  }
 }
 
 function normalizeMaxPayloadBytes(value) {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { base64UrlToBytes } from '@rei-standard/amsg-shared';
 export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPush, buildReasoningPush, buildToolRequestPush, isContentPush, isErrorPush, isReasoningPush, isToolRequestPush } from '@rei-standard/amsg-shared';
 
 /**
@@ -30,6 +31,11 @@ export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPu
  *   await client.scheduleMessage({ ... });
  */
 
+
+// `TextEncoder` is stateless — hoist once instead of allocating a fresh
+// instance for every encrypt + payload-size check.
+const TEXT_ENCODER = new TextEncoder();
+
 /** @typedef {import('@rei-standard/amsg-shared').MessageKind} MessageKind */
 /** @typedef {import('@rei-standard/amsg-shared').MessageType} MessageType */
 /** @typedef {import('@rei-standard/amsg-shared').PushSource} PushSource */
@@ -189,6 +195,29 @@ export { MESSAGE_KIND, MESSAGE_TYPE, PUSH_SOURCE, buildContentPush, buildErrorPu
  *   `deliver()` don't silently drop the header.
  * @property {string}   [endpointPath='/instant']  - Path under the resolved instant base URL. Pass
  *   `'/continue'` for tool-result resume on amsg-instant 0.9.0+.
+ * @property {(meta: RawReadMeta) => void} [onRawRead] - Optional raw-read telemetry hook for the
+ *   foreground SSE transport. Fires once per `reader.read()` BEFORE any SSE parsing/filtering, so it
+ *   sees every byte that reached the client — including `: keepalive` comment frames that the parser
+ *   silently drops. Use it to tell "connection alive but no business data" apart from "no bytes flowing
+ *   at all" when diagnosing stalled streams. Purely observational: throws are swallowed and never affect
+ *   transport. Not invoked for the JSON transport.
+ */
+
+/**
+ * Metadata for a single raw `reader.read()` on the SSE body, passed to
+ * `DeliverOptions.onRawRead`. The response-meta fields
+ * (`status` / `contentEncoding` / `contentType`) are only populated on the
+ * first invocation; later calls omit them.
+ *
+ * @typedef {Object} RawReadMeta
+ * @property {number}  ts                       - `Date.now()` at the moment the read resolved.
+ * @property {number}  byteLength               - Bytes in this chunk (`value?.byteLength ?? 0`).
+ * @property {boolean} done                     - The `done` flag from `reader.read()`.
+ * @property {string}  textPreview              - First ~120 chars of this chunk decoded as UTF-8,
+ *   WITHOUT any keepalive/comment filtering (so `:`-prefixed lines stay visible).
+ * @property {string|null} [contentEncoding]    - `res.headers.get('content-encoding')`. First call only.
+ * @property {string|null} [contentType]        - `res.headers.get('content-type')`. First call only.
+ * @property {number}  [status]                 - `res.status`. First call only.
  */
 
 /**
@@ -400,11 +429,11 @@ class ReiClient {
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string, expectsBackupPush?: boolean }} [opts]
    *   - `authorization`: optional auth header to forward.
-   *   - `expectsBackupPush`: opt-in flag for the dev warning. Set to `true`
-   *     to log a one-shot console.warn confirming you understand the
-   *     "200 ≠ delivered" pitfall and have your own out-of-band check
-   *     (or migrated to `deliver()`). Set to `false` to explicitly silence
-   *     the warning (you have read this contract).
+   *   - `expectsBackupPush`: opt-in dev reminder. Set to `true` to log a
+   *     one-shot console.warn that this is a low-level transport and
+   *     "HTTP 200 ≠ delivery confirmation" once the worker has backup
+   *     push enabled (amsg-instant 0.9.0+ default). Default (omitted) is
+   *     silent.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = '/instant', opts = {}) {
@@ -415,6 +444,10 @@ class ReiClient {
       endpointPath,
       { authorization: opts.authorization, methodName: 'sendInstant' }
     );
+    // Pin the response shape: amsg-instant routes the JSON `{ success, data }`
+    // envelope only when the caller asked exclusively for it. Omitting Accept
+    // gets the SSE branch and `res.json()` then throws on the SSE bytes.
+    headers['Accept'] = 'application/json';
 
     const res = await fetch(url, { method: 'POST', headers, body });
     return res.json();
@@ -447,10 +480,10 @@ class ReiClient {
    * @param {(error: unknown) => void} [options.onError]
    * @param {() => void} [options.onDone]
    * @param {AbortSignal} [options.signal]
-   * @param {boolean} [options.expectsBackupPush] - Opt-in flag for the dev warning.
-   *   Set to `true` to log a one-shot console.warn confirming you understand the
-   *   "rejection ≠ delivery failure" pitfall and have your own check (or migrated
-   *   to `deliver()`). Set to `false` to explicitly silence the warning.
+   * @param {boolean} [options.expectsBackupPush] - Opt-in dev reminder. Set
+   *   to `true` to log a one-shot console.warn that "rejection ≠ delivery
+   *   failure" once the worker has backup push enabled (amsg-instant 0.9.0+
+   *   default). Default (omitted) is silent.
    * @returns {Promise<void>}
    */
   async consumeInstantStream(payload, endpointPath = '/instant', options = {}) {
@@ -526,7 +559,7 @@ class ReiClient {
     }
     const {
       delivery, timeoutMs, onChunk, postTransportGraceMs,
-      signal, headers, authorization, endpointPath,
+      signal, headers, authorization, endpointPath, onRawRead,
     } = opts;
 
     if (!delivery || typeof delivery !== 'object') {
@@ -619,6 +652,7 @@ class ReiClient {
         const result = await this._runInstantTransport(built, {
           signal: internalAbort.signal,
           onChunk: wrappedOnChunk,
+          onRawRead,
         });
         if (finalized) return;
         transportEnded = true;
@@ -860,7 +894,7 @@ class ReiClient {
   async subscribePush(vapidPublicKey, registration) {
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
-      applicationServerKey: this._urlBase64ToUint8Array(vapidPublicKey)
+      applicationServerKey: base64UrlToBytes(vapidPublicKey)
     });
     return subscription;
   }
@@ -911,7 +945,7 @@ class ReiClient {
    */
   _assertPayloadSize(bodyJson, methodName) {
     if (this._maxPayloadBytes == null) return;
-    const bytes = new TextEncoder().encode(bodyJson).length;
+    const bytes = TEXT_ENCODER.encode(bodyJson).length;
     if (bytes > this._maxPayloadBytes) {
       throw makeLocalError(
         'PAYLOAD_TOO_LARGE_LOCAL',
@@ -971,11 +1005,12 @@ class ReiClient {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk } = opts;
+    const { signal, onChunk, onRawRead } = opts;
     const { url, headers, body } = built;
 
     const res = await fetch(url, { method: 'POST', headers, body, signal });
@@ -991,7 +1026,15 @@ class ReiClient {
     const kind = classifyContentType(contentType);
     if (kind === 'sse') {
       if (!res.body) throw new Error('Response body is null');
-      await this._consumeSseStream(res, { onPayload: onChunk });
+      await this._consumeSseStream(res, {
+        onPayload: onChunk,
+        onRawRead,
+        responseMeta: {
+          status: res.status,
+          contentEncoding: res.headers.get('content-encoding'),
+          contentType: res.headers.get('content-type'),
+        },
+      });
       return { kind: 'sse' };
     }
     if (kind === 'json') {
@@ -1009,16 +1052,54 @@ class ReiClient {
    *
    * @private
    * @param {Response} res
-   * @param {{ onPayload?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{
+   *   onPayload?: (p: unknown) => Promise<void> | void,
+   *   onRawRead?: (meta: RawReadMeta) => void,
+   *   responseMeta?: { status?: number, contentEncoding?: string | null, contentType?: string | null }
+   * }} opts
+   *   `onRawRead` (if supplied) fires once per `reader.read()` before any SSE parsing/filtering — it sees
+   *   raw bytes including `: keepalive` comment frames. Throws from it are swallowed. `responseMeta` is
+   *   attached to the FIRST `onRawRead` call only. See `DeliverOptions.onRawRead`.
    * @returns {Promise<void>}
    */
   async _consumeSseStream(res, opts) {
-    const { onPayload } = opts;
+    const { onPayload, onRawRead, responseMeta } = opts;
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
     let thrown;
 
+    // Raw read-loop telemetry (opt-in via onRawRead). Kept completely
+    // separate from the parsing path: a one-shot decoder for the preview so
+    // it never perturbs the streaming `decoder` above, and the first call
+    // carries response meta (status / encoding / content-type).
+    const previewDecoder = onRawRead ? new TextDecoder() : null;
+    let rawReadFired = false;
+    const emitRawRead = (done, value) => {
+      if (!onRawRead) return;
+      try {
+        let textPreview = '';
+        if (value && value.byteLength) {
+          // One-shot decode (no { stream: true }) so we don't carry state
+          // between calls and disturb the main buffer's decoder.
+          textPreview = previewDecoder.decode(value).slice(0, 120);
+        }
+        const meta = {
+          ts: Date.now(),
+          byteLength: value && value.byteLength ? value.byteLength : 0,
+          done: !!done,
+          textPreview,
+        };
+        if (!rawReadFired) {
+          meta.status = responseMeta ? responseMeta.status : undefined;
+          meta.contentEncoding = responseMeta ? responseMeta.contentEncoding : undefined;
+          meta.contentType = responseMeta ? responseMeta.contentType : undefined;
+        }
+        rawReadFired = true;
+        onRawRead(meta);
+      } catch { /* telemetry must never break the transport */ }
+    };
+
     // Parse one SSE frame body (lines between two terminators). Returns
     // `'done'` if the frame signals end-of-stream so the caller can
     // unwind without consuming further frames. Throws on `event: error`.
@@ -1061,6 +1142,7 @@ class ReiClient {
     try {
       while (true) {
         const { done, value } = await reader.read();
+        emitRawRead(done, value);
         if (done) {
           // Flush any tail bytes the decoder held back (partial UTF-8
           // sequences split across the final chunk boundary).
@@ -1204,10 +1286,10 @@ class ReiClient {
   }
 
   /**
-   * One-shot dev warning for low-level instant APIs. The warning is opt-in
-   * per call via `opts.expectsBackupPush === true`, and can be explicitly
-   * silenced via `opts.expectsBackupPush === false`. Fires at most once per
-   * ReiClient instance per method name.
+   * One-shot dev reminder for low-level instant APIs. The warning is opt-in
+   * per call via `opts.expectsBackupPush === true` and fires at most once
+   * per ReiClient instance per method name. Default (omitted or `false`)
+   * is silent.
    *
    * @private
    * @param {string} methodName
@@ -1221,7 +1303,7 @@ class ReiClient {
       ? 'HTTP 200 ≠ delivery confirmation'
       : 'rejection ≠ delivery failure';
     console.warn(
-      `[rei-standard-amsg-client] ${methodName} is a low-level transport — ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict. Pass expectsBackupPush: false to silence this warning.`
+      `[rei-standard-amsg-client] ${methodName} is a low-level transport — ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict.`
     );
   }
 
@@ -1238,7 +1320,7 @@ class ReiClient {
 
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const key = await crypto.subtle.importKey('raw', this._userKey, { name: 'AES-GCM' }, false, ['encrypt']);
-    const encoded = new TextEncoder().encode(plaintext);
+    const encoded = TEXT_ENCODER.encode(plaintext);
     const cipherBuf = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, encoded);
 
     // Web Crypto appends the 16-byte auth tag at the end of the ciphertext
@@ -1302,15 +1384,6 @@ class ReiClient {
     return arr;
   }
 
-  /** @private */
-  _urlBase64ToUint8Array(base64String) {
-    const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
-    const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
-    const raw = atob(base64);
-    const arr = new Uint8Array(raw.length);
-    for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
-    return arr;
-  }
 }
 
 function normalizeMaxPayloadBytes(value) {

package/dist/index.mjs

@@ -1,4 +1,5 @@
 // src/index.js
+import { base64UrlToBytes } from "@rei-standard/amsg-shared";
 import {
   MESSAGE_KIND,
   MESSAGE_TYPE,
@@ -12,6 +13,7 @@ import {
   isToolRequestPush,
   isErrorPush
 } from "@rei-standard/amsg-shared";
+var TEXT_ENCODER = new TextEncoder();
 var AVATAR_URL_MAX_LENGTH = 2048;
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
@@ -165,11 +167,11 @@ var ReiClient = class {
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
    * @param {{ authorization?: string, expectsBackupPush?: boolean }} [opts]
    *   - `authorization`: optional auth header to forward.
-   *   - `expectsBackupPush`: opt-in flag for the dev warning. Set to `true`
-   *     to log a one-shot console.warn confirming you understand the
-   *     "200 ≠ delivered" pitfall and have your own out-of-band check
-   *     (or migrated to `deliver()`). Set to `false` to explicitly silence
-   *     the warning (you have read this contract).
+   *   - `expectsBackupPush`: opt-in dev reminder. Set to `true` to log a
+   *     one-shot console.warn that this is a low-level transport and
+   *     "HTTP 200 ≠ delivery confirmation" once the worker has backup
+   *     push enabled (amsg-instant 0.9.0+ default). Default (omitted) is
+   *     silent.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
@@ -179,6 +181,7 @@ var ReiClient = class {
       endpointPath,
       { authorization: opts.authorization, methodName: "sendInstant" }
     );
+    headers["Accept"] = "application/json";
     const res = await fetch(url, { method: "POST", headers, body });
     return res.json();
   }
@@ -209,10 +212,10 @@ var ReiClient = class {
    * @param {(error: unknown) => void} [options.onError]
    * @param {() => void} [options.onDone]
    * @param {AbortSignal} [options.signal]
-   * @param {boolean} [options.expectsBackupPush] - Opt-in flag for the dev warning.
-   *   Set to `true` to log a one-shot console.warn confirming you understand the
-   *   "rejection ≠ delivery failure" pitfall and have your own check (or migrated
-   *   to `deliver()`). Set to `false` to explicitly silence the warning.
+   * @param {boolean} [options.expectsBackupPush] - Opt-in dev reminder. Set
+   *   to `true` to log a one-shot console.warn that "rejection ≠ delivery
+   *   failure" once the worker has backup push enabled (amsg-instant 0.9.0+
+   *   default). Default (omitted) is silent.
    * @returns {Promise<void>}
    */
   async consumeInstantStream(payload, endpointPath = "/instant", options = {}) {
@@ -290,7 +293,8 @@ var ReiClient = class {
       signal,
       headers,
       authorization,
-      endpointPath
+      endpointPath,
+      onRawRead
     } = opts;
     if (!delivery || typeof delivery !== "object") {
       throw new TypeError("[rei-standard-amsg-client] deliver() requires opts.delivery (discriminated union)");
@@ -351,7 +355,8 @@ var ReiClient = class {
       try {
         const result = await this._runInstantTransport(built, {
           signal: internalAbort.signal,
-          onChunk: wrappedOnChunk
+          onChunk: wrappedOnChunk,
+          onRawRead
         });
         if (finalized) return;
         transportEnded = true;
@@ -529,7 +534,7 @@ var ReiClient = class {
   async subscribePush(vapidPublicKey, registration) {
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
-      applicationServerKey: this._urlBase64ToUint8Array(vapidPublicKey)
+      applicationServerKey: base64UrlToBytes(vapidPublicKey)
     });
     return subscription;
   }
@@ -577,7 +582,7 @@ var ReiClient = class {
    */
   _assertPayloadSize(bodyJson, methodName) {
     if (this._maxPayloadBytes == null) return;
-    const bytes = new TextEncoder().encode(bodyJson).length;
+    const bytes = TEXT_ENCODER.encode(bodyJson).length;
     if (bytes > this._maxPayloadBytes) {
       throw makeLocalError(
         "PAYLOAD_TOO_LARGE_LOCAL",
@@ -630,11 +635,12 @@ var ReiClient = class {
    *
    * @private
    * @param {{ url: string, headers: Record<string, string>, body: string }} built
-   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void, onRawRead?: (meta: RawReadMeta) => void }} opts
+   *   `onRawRead` is forwarded to the SSE consumer for raw read-loop telemetry (see `DeliverOptions.onRawRead`).
    * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
    */
   async _runInstantTransport(built, opts) {
-    const { signal, onChunk } = opts;
+    const { signal, onChunk, onRawRead } = opts;
     const { url, headers, body } = built;
     const res = await fetch(url, { method: "POST", headers, body, signal });
     if (!res.ok) {
@@ -647,7 +653,15 @@ var ReiClient = class {
     const kind = classifyContentType(contentType);
     if (kind === "sse") {
       if (!res.body) throw new Error("Response body is null");
-      await this._consumeSseStream(res, { onPayload: onChunk });
+      await this._consumeSseStream(res, {
+        onPayload: onChunk,
+        onRawRead,
+        responseMeta: {
+          status: res.status,
+          contentEncoding: res.headers.get("content-encoding"),
+          contentType: res.headers.get("content-type")
+        }
+      });
       return { kind: "sse" };
     }
     if (kind === "json") {
@@ -664,15 +678,47 @@ var ReiClient = class {
    *
    * @private
    * @param {Response} res
-   * @param {{ onPayload?: (p: unknown) => Promise<void> | void }} opts
+   * @param {{
+   *   onPayload?: (p: unknown) => Promise<void> | void,
+   *   onRawRead?: (meta: RawReadMeta) => void,
+   *   responseMeta?: { status?: number, contentEncoding?: string | null, contentType?: string | null }
+   * }} opts
+   *   `onRawRead` (if supplied) fires once per `reader.read()` before any SSE parsing/filtering — it sees
+   *   raw bytes including `: keepalive` comment frames. Throws from it are swallowed. `responseMeta` is
+   *   attached to the FIRST `onRawRead` call only. See `DeliverOptions.onRawRead`.
    * @returns {Promise<void>}
    */
   async _consumeSseStream(res, opts) {
-    const { onPayload } = opts;
+    const { onPayload, onRawRead, responseMeta } = opts;
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
     let thrown;
+    const previewDecoder = onRawRead ? new TextDecoder() : null;
+    let rawReadFired = false;
+    const emitRawRead = (done, value) => {
+      if (!onRawRead) return;
+      try {
+        let textPreview = "";
+        if (value && value.byteLength) {
+          textPreview = previewDecoder.decode(value).slice(0, 120);
+        }
+        const meta = {
+          ts: Date.now(),
+          byteLength: value && value.byteLength ? value.byteLength : 0,
+          done: !!done,
+          textPreview
+        };
+        if (!rawReadFired) {
+          meta.status = responseMeta ? responseMeta.status : void 0;
+          meta.contentEncoding = responseMeta ? responseMeta.contentEncoding : void 0;
+          meta.contentType = responseMeta ? responseMeta.contentType : void 0;
+        }
+        rawReadFired = true;
+        onRawRead(meta);
+      } catch {
+      }
+    };
     const processFrame = async (part) => {
       if (!part.trim()) return null;
       let eventName = "message";
@@ -714,6 +760,7 @@ ${piece}` : piece;
     try {
       while (true) {
         const { done, value } = await reader.read();
+        emitRawRead(done, value);
         if (done) {
           buffer += decoder.decode();
           const finalNormalized = buffer.replace(SSE_LINE_NORMALIZE, "\n");
@@ -849,10 +896,10 @@ ${piece}` : piece;
     return Math.min(defaultGrace, remainingMs);
   }
   /**
-   * One-shot dev warning for low-level instant APIs. The warning is opt-in
-   * per call via `opts.expectsBackupPush === true`, and can be explicitly
-   * silenced via `opts.expectsBackupPush === false`. Fires at most once per
-   * ReiClient instance per method name.
+   * One-shot dev reminder for low-level instant APIs. The warning is opt-in
+   * per call via `opts.expectsBackupPush === true` and fires at most once
+   * per ReiClient instance per method name. Default (omitted or `false`)
+   * is silent.
    *
    * @private
    * @param {string} methodName
@@ -864,7 +911,7 @@ ${piece}` : piece;
     this._lowLevelWarned.add(methodName);
     const verdict = methodName === "sendInstant" ? "HTTP 200 \u2260 delivery confirmation" : "rejection \u2260 delivery failure";
     console.warn(
-      `[rei-standard-amsg-client] ${methodName} is a low-level transport \u2014 ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict. Pass expectsBackupPush: false to silence this warning.`
+      `[rei-standard-amsg-client] ${methodName} is a low-level transport \u2014 ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict.`
     );
   }
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
@@ -878,7 +925,7 @@ ${piece}` : piece;
     if (!this._userKey) throw new Error("[rei-standard-amsg-client] Not initialised. Call init() first.");
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const key = await crypto.subtle.importKey("raw", this._userKey, { name: "AES-GCM" }, false, ["encrypt"]);
-    const encoded = new TextEncoder().encode(plaintext);
+    const encoded = TEXT_ENCODER.encode(plaintext);
     const cipherBuf = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);
     const cipherArr = new Uint8Array(cipherBuf);
     const encryptedData = cipherArr.slice(0, cipherArr.length - 16);
@@ -931,15 +978,6 @@ ${piece}` : piece;
     }
     return arr;
   }
-  /** @private */
-  _urlBase64ToUint8Array(base64String) {
-    const padding = "=".repeat((4 - base64String.length % 4) % 4);
-    const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
-    const raw = atob(base64);
-    const arr = new Uint8Array(raw.length);
-    for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
-    return arr;
-  }
 };
 function normalizeMaxPayloadBytes(value) {
   if (value === void 0 || value === null) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-client",
-  "version": "2.5.0-next.0",
+  "version": "2.6.0",
   "description": "ReiStandard Active Messaging browser client SDK — also re-exports shared push types, builders, and guards from @rei-standard/amsg-shared",
   "repository": {
     "type": "git",