From 2f0d9bc6cb2190ef597bc1edf41334556eef1882 Mon Sep 17 00:00:00 2001
From: BilalG1 <bg2002@gmail.com>
Date: Tue, 30 Jun 2026 13:13:11 -0700
Subject: [PATCH] fix(session-replay): gzip replay batches so large rrweb
 snapshots aren't dropped (#1675)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Session replay batches are uploaded as **raw, uncompressed JSON**. A
single large rrweb full snapshot (>900 KB) is dropped client-side in
`SessionRecorder._flush`, and any batch near the server's 1 MB body
limit is rejected. Meanwhile the **analytics events** path right next
door already gzips on the wire (`encodeAnalyticsBody` + a server-side
gunzip with zip-bomb guards) — replays just never got the same
treatment.

Notably, `dev` was already **red** on the SDK test `sends a single
oversized event alone without dropping it` (the code dropped at 900 KB
while the test expected the event to be sent). This change makes that
test pass.

## What this does

Ports the proven analytics compression pattern to session replays:

- **`packages/shared` (client transport):** generalize
`encodeAnalyticsBody` → `encodeGzipJsonBody` and wire it into
`sendSessionReplayBatch`. Replays now gzip via native
`CompressionStream` (`application/octet-stream`), with the same
fallbacks: keepalive flushes send plain JSON (so the request survives
page teardown), and a missing/throwing `CompressionStream` (Safari <
16.4) degrades to plain JSON.
- **`packages/template` (SDK recorder):** replace the 900 KB hard-drop
with `MAX_SINGLE_EVENT_BYTES = 8 MB`, kept in sync with the server's
decompressed cap. The wire is gzipped downstream, so an oversized single
event is now sent compressed instead of discarded; only an event that
could never fit *decompressed* is dropped.
- **`apps/backend` (route):** add `maybeDecodeBinaryBody` (gunzip with a
1 MB compressed cap + 8 MB `maxOutputLength` zip-bomb guard) via a
`.transform` on the batch route body schema. Plain-JSON bodies pass
through untouched.

## Why gzip / CompressionStream

Benchmarked on a real rrweb capture (Puppeteer, rrweb 1.1.3): a **1.09
MiB full snapshot → 134 KiB gzip (~8×) in ~6.6 ms**. Native
`CompressionStream` adds **0 bundle bytes** and was faster than fflate.
This mirrors what PostHog (gzip, native `CompressionStream` + fflate
fallback) and Sentry (fflate deflate in a worker) both ship — both rely
on compression, not splitting, as the primary mechanism for large
events.

## Tests

- **Client SDK** (`client-interface.test.ts`): gzip+octet-stream on
non-keepalive (round-trip + size assert), plain JSON on keepalive, and
both `CompressionStream`-unavailable fallbacks.
- **SDK recorder** (`session-replay.test.ts`): existing oversized-event
test now passes; new test that a >8 MB event is dropped while a
following normal event still sends.
- **Backend e2e** (`session-replays.test.ts`): gzipped happy path
(`compressed < 1MB < raw`), invalid gzip → 400, oversized compressed →
413, zip-bomb → 400. Verified passing against a live local backend.

## Verification notes

- `@hexclave/shared` + `@hexclave/template` typecheck pass; touched
files lint clean; SDK unit tests pass.
- Two **pre-existing, unrelated** local failures (each confirmed by
stashing this change and re-running on clean `dev`): a backend typecheck
error in `oauth/ssrf-protection.test.ts` (`NODE_ENV` read-only), and 3
session-replay **quota** e2e tests failing in the payments
`setSessionReplayItemQuantity` setup helper.

## Follow-up (out of scope)

The keepalive/unload path still sends uncompressed (64 KB browser
keepalive cap), so a very large final batch on page exit can still be
lost — not addressed here.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Gzip session replay batches so large rrweb snapshots are sent instead of
dropped. Keepalive flushes cap single-event size to avoid 413s on page
unload, and limits now include a 1 KiB envelope margin to match server
caps.

- **Bug Fixes**
- Client (`@hexclave/shared`): generalized `encodeAnalyticsBody` →
`encodeGzipJsonBody`; gzip via native `CompressionStream` for
`/session-replays/batch`; keepalive and missing/throwing
`CompressionStream` fall back to JSON.
- SDK recorder (`@hexclave/template`): normal flushes allow a single
event up to `MAX_SINGLE_EVENT_BYTES = 8 MiB - 1 KiB`; keepalive flushes
cap single-event size at `MAX_BATCH_UNCOMPRESSED_BYTES = 900 KB`; send
oversized events alone and rely on gzip; drop only above those
thresholds; log a distinct 413 warning with the count of buffered events
dropped and stop the loop.
- Backend: gunzip `application/octet-stream` bodies with caps (`1 MB`
compressed, `8 MiB` decompressed); invalid gzip → 400; oversized
compressed → 413; plain JSON passes through.
- Tests: added client encoding tests for session replays; SDK tests for
>8 MiB drop, keepalive drop, and 413 warning; backend e2e for gzip,
invalid gzip, oversized compressed, and zip-bomb. The oversized-event
SDK test now passes.

- **Refactors**
  - Hoisted shared test helpers and trimmed comments.

<sup>Written for commit 855cdb052eac5c0abd4166d7157273ee53136009.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1675?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Session replay batch uploads can now be automatically gzipped (when
supported) to reduce request size; analytics batch uploads use the same
behavior.
* **Bug Fixes**
* Improved handling of gzipped upload bodies, with stricter validation
and safer size/decompression limits to reject invalid payloads and “zip
bomb” scenarios.
* Updated session replay buffering so oversized events are dropped only
when they exceed decompression constraints, while allowing later events
to upload.
* **Tests**
* Added client, server, and end-to-end coverage for gzip/keepalive
behavior and limit enforcement.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../latest/session-replays/batch/route.tsx    |  33 +++-
 .../endpoints/api/v1/session-replays.test.ts  | 109 +++++++++++-
 .../src/interface/client-interface.test.ts    |  89 ++++++++--
 .../shared/src/interface/client-interface.ts  |  18 +-
 .../implementations/session-replay.test.ts    | 161 +++++++++++++++++-
 .../apps/implementations/session-replay.ts    |  50 ++++--
 6 files changed, 423 insertions(+), 37 deletions(-)

diff --git a/apps/backend/src/app/api/latest/session-replays/batch/route.tsx b/apps/backend/src/app/api/latest/session-replays/batch/route.tsx
index 02e3798fd..2c5955384 100644
--- a/apps/backend/src/app/api/latest/session-replays/batch/route.tsx
+++ b/apps/backend/src/app/api/latest/session-replays/batch/route.tsx
@@ -11,7 +11,7 @@ import { adaptSchema, clientOrHigherAuthTypeSchema, yupArray, yupMixed, yupNumbe
 import { StatusError } from "@hexclave/shared/dist/utils/errors";
 import { randomUUID } from "node:crypto";
 import { promisify } from "node:util";
-import { gzip as gzipCb } from "node:zlib";
+import { gzip as gzipCb, gunzipSync } from "node:zlib";
 
 const gzip = promisify(gzipCb);
 
@@ -19,6 +19,35 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0
 
 const MAX_BODY_BYTES = 1_000_000;
 const MAX_EVENTS = 5_000;
+// Zip-bomb guard; keep in sync with the client's MAX_SINGLE_EVENT_BYTES.
+const MAX_DECOMPRESSED_BYTES = 8 * 1024 * 1024;
+
+// Gunzips application/octet-stream bodies (the client gzips large batches);
+// plain application/json bodies pass through untouched.
+function maybeDecodeBinaryBody(value: unknown): unknown {
+  let bytes: Uint8Array | undefined;
+  if (value instanceof ArrayBuffer) {
+    bytes = new Uint8Array(value);
+  } else if (value instanceof Uint8Array) {
+    bytes = value;
+  }
+  if (!bytes) return value;
+
+  if (bytes.byteLength > MAX_BODY_BYTES) {
+    throw new StatusError(StatusError.PayloadTooLarge, `Encoded session replay body too large (max ${MAX_BODY_BYTES} bytes)`);
+  }
+  let decompressed: Buffer;
+  try {
+    decompressed = gunzipSync(bytes, { maxOutputLength: MAX_DECOMPRESSED_BYTES });
+  } catch {
+    throw new StatusError(StatusError.BadRequest, "Invalid encoded session replay body");
+  }
+  try {
+    return JSON.parse(decompressed.toString("utf-8"));
+  } catch {
+    throw new StatusError(StatusError.BadRequest, "Invalid encoded session replay body");
+  }
+}
 
 function extractEventTimesMs(events: unknown[], fallbackMs: number) {
   let minTs = Infinity;
@@ -60,7 +89,7 @@ export const POST = createSmartRouteHandler({
       started_at_ms: yupNumber().defined().integer().min(0),
       sent_at_ms: yupNumber().defined().integer().min(0),
       events: yupArray(yupMixed().defined()).defined(),
-    }).defined(),
+    }).defined().transform((_value, originalValue) => maybeDecodeBinaryBody(originalValue)),
   }),
   response: yupObject({
     statusCode: yupNumber().oneOf([200]).defined(),
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/session-replays.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/session-replays.test.ts
index 351d2f6b4..abaccc8ad 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/session-replays.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/session-replays.test.ts
@@ -1,4 +1,5 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
+import { gzipSync } from "node:zlib";
 import { PLAN_LIMITS } from "@hexclave/shared/dist/plans";
 import { wait } from "@hexclave/shared/dist/utils/promises";
 import { it } from "../../../../helpers";
@@ -162,6 +163,112 @@ it("stores session replay batch metadata and dedupes by (session_replay_id, batc
   expect(second.body?.session_replay_id).toBe(recordingId);
 });
 
+it("accepts a gzipped binary body (compressed large-payload encoding)", async ({ expect }) => {
+  await Project.createAndSwitch({ config: { magic_link_enabled: true } });
+  await Project.updateConfig({ apps: { installed: { analytics: { enabled: true } } } });
+  await Auth.Otp.signIn();
+
+  const now = Date.now();
+  const payload = {
+    browser_session_id: randomUUID(),
+    session_replay_segment_id: randomUUID(),
+    batch_id: randomUUID(),
+    started_at_ms: now,
+    sent_at_ms: now + 500,
+    // Large full snapshot: exceeds the 1MB raw wire limit but gzips under it.
+    events: [{ timestamp: now + 100, type: 2, data: { html: "x".repeat(2_000_000) } }],
+  };
+  const compressed = gzipSync(Buffer.from(JSON.stringify(payload), "utf-8"));
+  // Sanity: the raw payload exceeds the wire limit, the compressed one doesn't.
+  expect(compressed.byteLength).toBeLessThan(1_000_000);
+
+  const res = await niceBackendFetch("/api/v1/session-replays/batch", {
+    method: "POST",
+    accessType: "client",
+    rawBody: compressed,
+  });
+
+  expect(res).toMatchInlineSnapshot(`
+    NiceResponse {
+      "status": 200,
+      "body": {
+        "batch_id": "<stripped UUID>",
+        "deduped": false,
+        "s3_key": "session-replays/<stripped UUID>/main/<stripped UUID>/<stripped UUID>.json.gz",
+        "session_replay_id": "<stripped UUID>",
+      },
+      "headers": Headers { <some fields may have been hidden> },
+    }
+  `);
+});
+
+it("rejects a binary body that isn't valid gzip", async ({ expect }) => {
+  await Project.createAndSwitch({ config: { magic_link_enabled: true } });
+  await Project.updateConfig({ apps: { installed: { analytics: { enabled: true } } } });
+  await Auth.Otp.signIn();
+
+  const res = await niceBackendFetch("/api/v1/session-replays/batch", {
+    method: "POST",
+    accessType: "client",
+    rawBody: new Uint8Array([0, 1, 2, 3, 4, 5]),
+  });
+
+  expect(res).toMatchInlineSnapshot(`
+    NiceResponse {
+      "status": 400,
+      "body": "Invalid encoded session replay body",
+      "headers": Headers { <some fields may have been hidden> },
+    }
+  `);
+});
+
+it("rejects a binary body larger than the compressed size cap", async ({ expect }) => {
+  await Project.createAndSwitch({ config: { magic_link_enabled: true } });
+  await Project.updateConfig({ apps: { installed: { analytics: { enabled: true } } } });
+  await Auth.Otp.signIn();
+
+  // Random bytes don't compress, so the byteLength check fires before gunzip.
+  // 1.1 MB > the 1 MB MAX_BODY_BYTES cap.
+  const oversized = new Uint8Array(randomBytes(Math.floor(1.1 * 1024 * 1024)));
+
+  const res = await niceBackendFetch("/api/v1/session-replays/batch", {
+    method: "POST",
+    accessType: "client",
+    rawBody: oversized,
+  });
+
+  expect(res).toMatchInlineSnapshot(`
+    NiceResponse {
+      "status": 413,
+      "body": "Encoded session replay body too large (max 1000000 bytes)",
+      "headers": Headers { <some fields may have been hidden> },
+    }
+  `);
+});
+
+it("rejects a gzipped body that decompresses past the server size cap", async ({ expect }) => {
+  await Project.createAndSwitch({ config: { magic_link_enabled: true } });
+  await Project.updateConfig({ apps: { installed: { analytics: { enabled: true } } } });
+  await Auth.Otp.signIn();
+
+  // 9 MB of zeros gzips to ~9 KB but decompresses past the 8 MB server cap.
+  const bomb = gzipSync(Buffer.alloc(9 * 1024 * 1024));
+
+  const res = await niceBackendFetch("/api/v1/session-replays/batch", {
+    method: "POST",
+    accessType: "client",
+    rawBody: bomb,
+  });
+
+  expect(res).toMatchInlineSnapshot(`
+    NiceResponse {
+      "status": 400,
+      "body": "Invalid encoded session replay body",
+      "headers": Headers { <some fields may have been hidden> },
+    }
+  `);
+});
+
 it("rejects empty events", async ({ expect }) => {
   await Project.createAndSwitch({ config: { magic_link_enabled: true } });
   await Project.updateConfig({ apps: { installed: { analytics: { enabled: true } } } });
diff --git a/packages/shared/src/interface/client-interface.test.ts b/packages/shared/src/interface/client-interface.test.ts
index aa8f5ba7c..ed341e60b 100644
--- a/packages/shared/src/interface/client-interface.test.ts
+++ b/packages/shared/src/interface/client-interface.test.ts
@@ -689,6 +689,18 @@ describe("_withFallback", () => {
   });
 });
 
+function getRequestInit(fetchMock: { mock: { calls: unknown[][] } }): RequestInit {
+  const init = fetchMock.mock.calls[0]?.[1];
+  if (init == null || typeof init !== "object") throw new Error("expected RequestInit");
+  return init as RequestInit;
+}
+
+async function gunzipToText(body: unknown): Promise<string> {
+  if (!(body instanceof Uint8Array)) throw new Error("expected Uint8Array body");
+  const stream = new Blob([body as BlobPart]).stream().pipeThrough(new DecompressionStream("gzip"));
+  return await new Response(stream).text();
+}
+
 describe("sendAnalyticsEventBatch encoding", () => {
   function captureFetch() {
     const fetchMock = vi.fn(async () => createJsonResponse({ inserted: 0 }));
@@ -696,18 +708,6 @@ describe("sendAnalyticsEventBatch encoding", () => {
     return fetchMock;
   }
 
-  function getRequestInit(fetchMock: { mock: { calls: unknown[][] } }): RequestInit {
-    const init = fetchMock.mock.calls[0]?.[1];
-    if (init == null || typeof init !== "object") throw new Error("expected RequestInit");
-    return init as RequestInit;
-  }
-
-  async function gunzipToText(body: unknown): Promise<string> {
-    if (!(body instanceof Uint8Array)) throw new Error("expected Uint8Array body");
-    const stream = new Blob([body as BlobPart]).stream().pipeThrough(new DecompressionStream("gzip"));
-    return await new Response(stream).text();
-  }
-
   it("gzips body and sends application/octet-stream when keepalive is false", async () => {
     const fetchMock = captureFetch();
     const iface = createClientInterface();
@@ -763,3 +763,68 @@ describe("sendAnalyticsEventBatch encoding", () => {
     expect(init.body).toBe(payload);
   });
 });
+
+describe("sendSessionReplayBatch encoding", () => {
+  function captureFetch() {
+    const fetchMock = vi.fn(async () => createJsonResponse({ session_replay_id: "r", batch_id: "b", s3_key: "k", deduped: false }));
+    vi.stubGlobal("fetch", fetchMock);
+    return fetchMock;
+  }
+
+  it("gzips body and sends application/octet-stream when keepalive is false", async () => {
+    const fetchMock = captureFetch();
+    const iface = createClientInterface();
+    // A large, highly-compressible payload — the case the wire-limit drop used to lose.
+    const payload = JSON.stringify({ batch_id: "abc", events: [{ type: 2, data: "x".repeat(1_000_000) }] });
+
+    await iface.sendSessionReplayBatch(payload, null, { keepalive: false });
+
+    const init = getRequestInit(fetchMock);
+    expect(new Headers(init.headers).get("Content-Type")).toBe("application/octet-stream");
+    expect(init.body).toBeInstanceOf(Uint8Array);
+    // The compressed body is far smaller than the 1MB+ raw payload.
+    expect((init.body as Uint8Array).byteLength).toBeLessThan(100_000);
+    await expect(gunzipToText(init.body)).resolves.toBe(payload);
+  });
+
+  it("falls back to plain JSON when keepalive is true (avoids racing pagehide tear-down)", async () => {
+    const fetchMock = captureFetch();
+    const iface = createClientInterface();
+    const payload = JSON.stringify({ batch_id: "abc", events: [] });
+
+    await iface.sendSessionReplayBatch(payload, null, { keepalive: true });
+
+    const init = getRequestInit(fetchMock);
+    expect(new Headers(init.headers).get("Content-Type")).toBe("application/json");
+    expect(init.body).toBe(payload);
+  });
+
+  it("falls back to plain JSON when CompressionStream is unavailable", async () => {
+    vi.stubGlobal("CompressionStream", undefined);
+    const fetchMock = captureFetch();
+    const iface = createClientInterface();
+    const payload = JSON.stringify({ batch_id: "abc", events: [] });
+
+    await iface.sendSessionReplayBatch(payload, null, { keepalive: false });
+
+    const init = getRequestInit(fetchMock);
+    expect(new Headers(init.headers).get("Content-Type")).toBe("application/json");
+    expect(init.body).toBe(payload);
+  });
+
+  it("falls back to plain JSON when CompressionStream throws at runtime", async () => {
+    class ThrowingCompressionStream {
+      constructor() { throw new Error("compression unsupported"); }
+    }
+    vi.stubGlobal("CompressionStream", ThrowingCompressionStream);
+    const fetchMock = captureFetch();
+    const iface = createClientInterface();
+    const payload = JSON.stringify({ batch_id: "abc", events: [] });
+
+    await iface.sendSessionReplayBatch(payload, null, { keepalive: false });
+
+    const init = getRequestInit(fetchMock);
+    expect(new Headers(init.headers).get("Content-Type")).toBe("application/json");
+    expect(init.body).toBe(payload);
+  });
+});
diff --git a/packages/shared/src/interface/client-interface.ts b/packages/shared/src/interface/client-interface.ts
index 6b9a37a9c..bcde0191c 100644
--- a/packages/shared/src/interface/client-interface.ts
+++ b/packages/shared/src/interface/client-interface.ts
@@ -130,13 +130,13 @@ function getBotChallengeRequestFields(botChallenge: BotChallengeInput | undefine
   };
 }
 
-async function encodeAnalyticsBody(
+async function encodeGzipJsonBody(
   jsonBody: string,
   options: { keepalive: boolean },
 ): Promise<{ body: BodyInit, contentType: string }> {
-  // pagehide/visibilitychange flushes use keepalive: true. The browser must
-  // dispatch the fetch before tearing the page down — awaiting async gzip
-  // first lets the request slip past tear-down and never start.
+  // Used by analytics-event and session-replay batch uploads; the server
+  // gunzips application/octet-stream bodies before schema validation.
+  // keepalive flushes must dispatch before page tear-down, so skip async gzip.
   if (options.keepalive) {
     return { body: jsonBody, contentType: "application/json" };
   }
@@ -150,8 +150,7 @@ async function encodeAnalyticsBody(
     const buffer = await new Response(stream).arrayBuffer();
     return { body: new Uint8Array(buffer), contentType: "application/octet-stream" };
   } catch {
-    // Partial/broken CompressionStream support: fall back to plain JSON so
-    // EventTracker._flush() doesn't drop the batch via Result.error.
+    // Broken CompressionStream (e.g. Safari < 16.4): fall back to plain JSON.
     return { body: jsonBody, contentType: "application/json" };
   }
 }
@@ -551,12 +550,13 @@ export class HexclaveClientInterface {
     options: { keepalive: boolean },
   ): Promise<Result<Response, Error>> {
     try {
+      const encoded = await encodeGzipJsonBody(body, { keepalive: options.keepalive });
       const response = await this.sendClientRequest(
         "/session-replays/batch",
         {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body,
+          headers: { "Content-Type": encoded.contentType },
+          body: encoded.body,
           keepalive: options.keepalive,
         },
         session,
@@ -576,7 +576,7 @@ export class HexclaveClientInterface {
     options: { keepalive: boolean },
   ): Promise<Result<Response, Error>> {
     try {
-      const encoded = await encodeAnalyticsBody(body, { keepalive: options.keepalive });
+      const encoded = await encodeGzipJsonBody(body, { keepalive: options.keepalive });
       const response = await this.sendClientRequest(
         "/analytics/events/batch",
         {
diff --git a/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.test.ts b/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.test.ts
index 2ca190db5..cc7231051 100644
--- a/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.test.ts
+++ b/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.test.ts
@@ -2,6 +2,7 @@
 
 import { KnownErrors } from "@hexclave/shared/dist/known-errors";
 import { describe, expect, it, vi } from "vitest";
+import * as errors from "@hexclave/shared/dist/utils/errors";
 import { Result } from "@hexclave/shared/dist/utils/results";
 import { analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions, SessionRecorder } from "./session-replay";
 
@@ -199,7 +200,7 @@ describe("SessionRecorder flush", () => {
       (recorder as any)._tick();
       await vi.advanceTimersByTimeAsync(0);
 
-      // Should still send the event (the server may reject it, but we don't drop it client-side)
+      // Sent (not dropped): the transport gzips it under the wire limit.
       expect(sentBodies).toHaveLength(1);
       const batch = JSON.parse(sentBodies[0]);
       expect(batch.events).toHaveLength(1);
@@ -210,6 +211,164 @@ describe("SessionRecorder flush", () => {
     }
   });
 
+  it("drops a single event that exceeds the server's decompressed budget", async () => {
+    vi.useFakeTimers();
+
+    const storageKey = `hexclave:session-replay:v1:test-project`;
+    localStorage.setItem(storageKey, JSON.stringify({
+      session_id: "test-session",
+      created_at_ms: Date.now(),
+      last_activity_ms: Date.now(),
+    }));
+
+    const sentBodies: string[] = [];
+    const recorder = new SessionRecorder(
+      {
+        projectId: "test-project",
+        sendBatch: async (body) => {
+          sentBodies.push(body);
+          return Result.ok(new Response("ok", { status: 200 }));
+        },
+      },
+      {},
+    );
+
+    try {
+      // >8MB (MAX_SINGLE_EVENT_BYTES) is dropped; the next event still sends.
+      const hugeEvent = { type: 2, timestamp: Date.now(), data: "z".repeat(9_000_000) };
+      const smallEvent = { type: 3, timestamp: Date.now(), data: "ok" };
+      const sizeOf = (e: unknown) => JSON.stringify(e).length;
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._events = [hugeEvent, smallEvent];
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._eventSizes = [sizeOf(hugeEvent), sizeOf(smallEvent)];
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._approxBytes = sizeOf(hugeEvent) + sizeOf(smallEvent);
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+      (recorder as any)._tick();
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(sentBodies).toHaveLength(1);
+      const batch = JSON.parse(sentBodies[0]);
+      expect(batch.events).toHaveLength(1);
+      expect(batch.events[0].type).toBe(3);
+    } finally {
+      recorder.stop();
+      localStorage.removeItem(storageKey);
+      vi.useRealTimers();
+    }
+  });
+
+  it("on a keepalive flush, drops an event over the uncompressed batch target (it can't be gzipped before page tear-down)", async () => {
+    vi.useFakeTimers();
+
+    const storageKey = `hexclave:session-replay:v1:test-project`;
+    localStorage.setItem(storageKey, JSON.stringify({
+      session_id: "test-session",
+      created_at_ms: Date.now(),
+      last_activity_ms: Date.now(),
+    }));
+
+    const sentBodies: string[] = [];
+    const recorder = new SessionRecorder(
+      {
+        projectId: "test-project",
+        sendBatch: async (body) => {
+          sentBodies.push(body);
+          return Result.ok(new Response("ok", { status: 200 }));
+        },
+      },
+      {},
+    );
+
+    try {
+      // ~2MB is under the 8MB gzipped ceiling but over the 900KB uncompressed
+      // batch target. Keepalive flushes skip gzip, so this event would 413 the
+      // server's ~1MB raw body limit; it must be dropped, but the next event
+      // (small enough to send raw) still goes out.
+      const midEvent = { type: 2, timestamp: Date.now(), data: "z".repeat(2_000_000) };
+      const smallEvent = { type: 3, timestamp: Date.now(), data: "ok" };
+      const sizeOf = (e: unknown) => new TextEncoder().encode(JSON.stringify(e)).byteLength;
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._events = [midEvent, smallEvent];
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._eventSizes = [sizeOf(midEvent), sizeOf(smallEvent)];
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._approxBytes = sizeOf(midEvent) + sizeOf(smallEvent);
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+      await (recorder as any)._flush({ keepalive: true });
+
+      expect(sentBodies).toHaveLength(1);
+      const batch = JSON.parse(sentBodies[0]);
+      expect(batch.events).toHaveLength(1);
+      expect(batch.events[0].type).toBe(3);
+    } finally {
+      recorder.stop();
+      localStorage.removeItem(storageKey);
+      vi.useRealTimers();
+    }
+  });
+
+  it("logs a distinct 413 warning and drops the buffered events when the server rejects a batch as too large", async () => {
+    vi.useFakeTimers();
+    const captureWarningSpy = vi.spyOn(errors, "captureWarning").mockImplementation(() => {});
+
+    const storageKey = `hexclave:session-replay:v1:test-project`;
+    localStorage.setItem(storageKey, JSON.stringify({
+      session_id: "test-session",
+      created_at_ms: Date.now(),
+      last_activity_ms: Date.now(),
+    }));
+
+    let calls = 0;
+    const recorder = new SessionRecorder(
+      {
+        projectId: "test-project",
+        sendBatch: async () => {
+          calls += 1;
+          // A poorly-compressible event can clear the client-side caps yet still
+          // exceed the server's body limit after gzip → 413.
+          return Result.ok(new Response("payload too large", { status: 413 }));
+        },
+      },
+      {},
+    );
+
+    try {
+      const eventA = { type: 3, timestamp: Date.now(), data: "a" };
+      const eventB = { type: 3, timestamp: Date.now(), data: "b" };
+      const sizeOf = (e: unknown) => new TextEncoder().encode(JSON.stringify(e)).byteLength;
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._events = [eventA, eventB];
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._eventSizes = [sizeOf(eventA), sizeOf(eventB)];
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      (recorder as any)._approxBytes = sizeOf(eventA) + sizeOf(eventB);
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+      await (recorder as any)._flush({ keepalive: false });
+
+      // The 413 stops the loop; no retry of the rejected batch.
+      expect(calls).toBe(1);
+      expect(captureWarningSpy).toHaveBeenCalledTimes(1);
+      const warned = captureWarningSpy.mock.calls[0]?.[1];
+      expect(warned).toBeInstanceOf(Error);
+      expect((warned as Error).message).toContain("413");
+      // Both buffered events are reported as dropped.
+      expect((warned as Error).message).toContain("2 buffered event");
+    } finally {
+      recorder.stop();
+      localStorage.removeItem(storageKey);
+      captureWarningSpy.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
   it("silently disables when client interface returns ANALYTICS_NOT_ENABLED as an error", async () => {
     vi.useFakeTimers();
 
diff --git a/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.ts b/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.ts
index fc9c6c7b4..db3294260 100644
--- a/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.ts
+++ b/packages/template/src/lib/hexclave-app/apps/implementations/session-replay.ts
@@ -106,9 +106,16 @@ const IDLE_TTL_MS = 3 * 60 * 1000;
 const FLUSH_INTERVAL_MS = 5_000;
 const MAX_EVENTS_PER_BATCH = 200;
 const MAX_APPROX_BYTES_PER_BATCH = 512_000;
-// The server rejects payloads > 1MB. Stay well under to account for JSON
-// envelope overhead (browser_session_id, timestamps, wrapper keys, etc.).
-const MAX_FLUSH_PAYLOAD_BYTES = 900_000;
+// Uncompressed per-batch target; the transport gzips before sending.
+const MAX_BATCH_UNCOMPRESSED_BYTES = 900_000;
+// The server gunzips the whole batch (envelope + events) and rejects anything
+// whose decompressed size exceeds MAX_DECOMPRESSED_BYTES (8 MiB) in the backend
+// route. Since a single oversized event is sent alone, reserve headroom for the
+// JSON envelope (session/batch ids, timestamps, wrapper keys) so an event that
+// passes this check can't render a batch that trips the server's cap by a few
+// hundred bytes. Keep the server's MAX_DECOMPRESSED_BYTES >= this + the margin.
+const BATCH_ENVELOPE_OVERHEAD_BYTES = 1024;
+const MAX_SINGLE_EVENT_BYTES = 8 * 1024 * 1024 - BATCH_ENVELOPE_OVERHEAD_BYTES;
 
 // Reused across the emit hot path to avoid per-event allocation.
 const textEncoder = new TextEncoder();
@@ -281,20 +288,25 @@ export class SessionRecorder {
     this._eventSizes = [];
     this._approxBytes = 0;
 
+    // Non-keepalive flushes gzip before sending, so a single event up to the
+    // server's decompressed budget can be sent alone. Keepalive flushes
+    // (pagehide/visibilitychange/stop) skip async gzip to dispatch before page
+    // tear-down, so they're bound by the server's raw ~1MB body limit; cap their
+    // single-event size at the uncompressed batch target so an oversized event
+    // is dropped rather than 413-ing the flush and losing the events behind it.
+    const maxSingleEventBytes = options.keepalive ? MAX_BATCH_UNCOMPRESSED_BYTES : MAX_SINGLE_EVENT_BYTES;
+
     this._flushInProgress = true;
     try {
       let offset = 0;
       while (offset < allEvents.length) {
-        // Build a batch that fits under the server's payload limit.
-        // When _flushInProgress blocked earlier flushes, events can accumulate
-        // well past MAX_APPROX_BYTES_PER_BATCH; sending them all at once would
-        // exceed the server's 1MB body limit (413).
-        // A single event over the limit can't be sent (rrweb events aren't splittable); drop it and move on.
+        // A single event over the limit can't be sent (rrweb events aren't
+        // splittable); drop it and move on to the rest of the buffer.
         const firstSize = allSizes[offset] ?? throwErr("_eventSizes out of sync with _events — this should never happen");
-        if (firstSize > MAX_FLUSH_PAYLOAD_BYTES) {
+        if (firstSize > maxSingleEventBytes) {
           captureWarning(
             "SessionRecorder.flush",
-            new Error(`Dropping oversized session replay event (${firstSize} bytes > ${MAX_FLUSH_PAYLOAD_BYTES} byte limit); it cannot be sent without a 413.`),
+            new Error(`Dropping oversized session replay event (${firstSize} bytes > ${maxSingleEventBytes} byte limit); it cannot be sent without exceeding the server's body limit.`),
           );
           offset += 1;
           continue;
@@ -304,7 +316,7 @@ export class SessionRecorder {
         let batchEnd = offset;
         for (let i = offset; i < allEvents.length; i++) {
           const nextSize = allSizes[i] ?? throwErr("_eventSizes out of sync with _events — this should never happen");
-          if (batchBytes + nextSize > MAX_FLUSH_PAYLOAD_BYTES && batchEnd > offset) break;
+          if (batchBytes + nextSize > MAX_BATCH_UNCOMPRESSED_BYTES && batchEnd > offset) break;
           batchBytes += nextSize;
           batchEnd = i + 1;
         }
@@ -342,7 +354,21 @@ export class SessionRecorder {
         }
 
         if (!res.data.ok) {
-          captureWarning("SessionRecorder.flush", new Error(`SessionRecorder flush failed: ${res.data.status} ${await res.data.text()}`));
+          // On any non-2xx we stop the loop, so this batch and every event still
+          // buffered behind it are dropped (not retried). Count them for the log.
+          const droppedCount = batchEvents.length + (allEvents.length - offset);
+          if (res.data.status === 413) {
+            // The payload exceeded the server's body limit despite the client-side
+            // size caps — most likely a single poorly-compressible event (e.g. an
+            // embedded image/canvas) that gzipped above the wire limit. Distinct
+            // from other failures because the caps are supposed to prevent it.
+            captureWarning(
+              "SessionRecorder.flush",
+              new Error(`Session replay batch rejected with 413 (payload too large) despite client-side size caps; dropping ${droppedCount} buffered event(s). A poorly-compressible event likely exceeded the server's body limit after gzip.`),
+            );
+            return;
+          }
+          captureWarning("SessionRecorder.flush", new Error(`SessionRecorder flush failed (dropping ${droppedCount} buffered event(s)): ${res.data.status} ${await res.data.text()}`));
           return;
         }
       }