@drip-apex/sdk 0.1.0 → 0.3.0

package/src/replay.test.ts

@@ -0,0 +1,764 @@
+// @vitest-environment jsdom
+import { deflateSync, inflateSync, strFromU8 } from "fflate";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { REPLAY_MAX_BLOCKS } from "@drip/event-schema/replay-contract";
+import type { Assignment, Experiment } from "./types";
+import {
+  REPLAY_FLUSH_INTERVAL_MS,
+  REPLAY_MAX_COMPRESSED_BYTES,
+  REPLAY_MAX_DURATION_MS,
+  REPLAY_PROGRESS_KEY_PREFIX,
+  resolveReplayAssignments,
+  resolveReplayRecorderUrl,
+  startReplayCapture,
+  type ReplayRecorderApi,
+  type ReplayRecorderEmission,
+  type ReplaySignals,
+} from "./replay";
+
+const rrwebMock = vi.hoisted(() => {
+  const stop = vi.fn();
+  const record = Object.assign(vi.fn(() => stop), {
+    mirror: { getNode: vi.fn() },
+  });
+  return { record, stop };
+});
+
+vi.mock("rrweb", () => ({ record: rrwebMock.record }));
+
+const assignment: Assignment = {
+  experimentId: "exp_1",
+  variationId: "var_1",
+  index: 1,
+  mutations: [],
+  isControl: false,
+  hashValue: "0.25",
+};
+
+function experiment(overrides: Partial<Experiment> = {}): Experiment {
+  return {
+    id: "exp_1",
+    status: "running",
+    replayCapture: { enabled: true, sampleRate: 1 },
+    variations: [],
+    ...overrides,
+  };
+}
+
+function emptySignals(): ReplaySignals {
+  return {
+    clicks: [],
+    nav: [],
+    errors: [],
+    form_focus: [],
+    form_submit: [],
+    scroll_max_pct: 0,
+  };
+}
+
+function fakeRecorder(overrides: Partial<ReplayRecorderApi> = {}) {
+  let emit: ((emission: ReplayRecorderEmission) => void) | null = null;
+  const stop = vi.fn();
+  const recorder: ReplayRecorderApi = {
+    version: "2.1.1",
+    start: vi.fn((options) => {
+      emit = options.emit;
+      return stop;
+    }),
+    compress: vi.fn(async (bytes) => deflateSync(bytes)),
+    compressSync: vi.fn((bytes) => deflateSync(bytes)),
+    takeSignals: vi.fn(() => emptySignals()),
+    ...overrides,
+  };
+  return {
+    recorder,
+    stop,
+    emit(emission: ReplayRecorderEmission) {
+      if (!emit) throw new Error("recorder not started");
+      emit(emission);
+    },
+  };
+}
+
+function replayOptions(recorder: ReplayRecorderApi, blocked: () => boolean) {
+  return {
+    assignments: [assignment],
+    experiments: [experiment()],
+    recorderUrl: "https://events.example.test/sdk/1/drip.replay-recorder.js",
+    endpoint: "https://events.example.test/events",
+    shopId: "shop_1",
+    visitorId: "visitor_1",
+    sessionId: "session_1",
+    environment: "production",
+    qaMode: true,
+    qaSessionId: "qa_1",
+    sdkVersion: "0.1.0+test",
+    ingestSignature: "signature_1",
+    isTrackingBlocked: blocked,
+    loadRecorder: vi.fn(async () => recorder),
+  };
+}
+
+describe("session replay capture", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    sessionStorage.clear();
+    history.replaceState(null, "", "/products/example");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+    delete (globalThis as typeof globalThis & { __dripReplayRecorder?: ReplayRecorderApi }).__dripReplayRecorder;
+  });
+
+  it("records dispatched form submits while active and removes the listener on stop", async () => {
+    vi.resetModules();
+    rrwebMock.record.mockClear();
+    rrwebMock.stop.mockClear();
+    document.body.innerHTML = `
+      <form id="checkout-form"><input id="email" /></form>
+      <form id="after-stop-form"><input /></form>
+    `;
+    const input = document.querySelector("#email")!;
+    rrwebMock.record.mirror.getNode.mockReturnValue(input);
+
+    await import("./replay-recorder-entry");
+    const recorder = (globalThis as typeof globalThis & { __dripReplayRecorder?: ReplayRecorderApi })
+      .__dripReplayRecorder!;
+    const stop = recorder.start({ emit: vi.fn() });
+    const rrwebEmit = rrwebMock.record.mock.calls[0]?.[0]?.emit;
+    rrwebEmit?.({ type: 3, timestamp: 1_000, data: { source: 2, type: 5, id: 7 } });
+
+    document.querySelector("#checkout-form")!.dispatchEvent(new Event("submit", { bubbles: true }));
+
+    expect(recorder.takeSignals()).toMatchObject({
+      form_focus: [{ ts: 1_000, selector: "form#checkout-form" }],
+      form_submit: [{ selector: "form#checkout-form" }],
+    });
+
+    stop();
+    document.querySelector("#after-stop-form")!.dispatchEvent(new Event("submit", { bubbles: true }));
+
+    expect(recorder.takeSignals().form_submit).toHaveLength(1);
+    expect(rrwebMock.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the per-assignment sample decision stable for the session", () => {
+    const random = vi.spyOn(Math, "random").mockReturnValueOnce(0.25).mockReturnValue(0.9);
+    const sampledExperiment = experiment({ replayCapture: { enabled: true, sampleRate: 0.5 } });
+
+    expect(resolveReplayAssignments([assignment], [sampledExperiment])).toEqual([
+      { experiment_id: "exp_1", variation_id: "var_1" },
+    ]);
+    expect(resolveReplayAssignments([assignment], [sampledExperiment])).toEqual([
+      { experiment_id: "exp_1", variation_id: "var_1" },
+    ]);
+    expect(sessionStorage.getItem("drip_rp:exp_1:var_1")).toBe("1");
+    expect(resolveReplayAssignments([assignment], [
+      experiment({ replayCapture: { enabled: true, sampleRate: 0 } }),
+    ])).toHaveLength(1);
+    expect(random).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not load or post when consent blocks tracking", async () => {
+    const fake = fakeRecorder();
+    const options = replayOptions(fake.recorder, () => true);
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(startReplayCapture(options)).resolves.toBeNull();
+    expect(options.loadRecorder).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("does not start recording when consent is revoked while the recorder loads", async () => {
+    let blocked = false;
+    let finishLoad: ((recorder: ReplayRecorderApi) => void) | undefined;
+    const fake = fakeRecorder();
+    const options = replayOptions(fake.recorder, () => blocked);
+    options.loadRecorder = vi.fn(() => new Promise((resolve) => {
+      finishLoad = resolve;
+    }));
+
+    const start = startReplayCapture(options);
+    blocked = true;
+    finishLoad?.(fake.recorder);
+
+    await expect(start).resolves.toBeNull();
+    expect(fake.recorder.start).not.toHaveBeenCalled();
+  });
+
+  it("does not start recording when SPA navigation enters checkout while the recorder loads", async () => {
+    let finishLoad: ((recorder: ReplayRecorderApi) => void) | undefined;
+    const fake = fakeRecorder();
+    const options = replayOptions(fake.recorder, () => false);
+    options.loadRecorder = vi.fn(() => new Promise((resolve) => {
+      finishLoad = resolve;
+    }));
+
+    const start = startReplayCapture(options);
+    history.pushState(null, "", "/checkout");
+    finishLoad?.(fake.recorder);
+
+    await expect(start).resolves.toBeNull();
+    expect(fake.recorder.start).not.toHaveBeenCalled();
+  });
+
+  it("does not start on checkout paths", async () => {
+    history.replaceState(null, "", "/checkouts/order-token");
+    const fake = fakeRecorder();
+    const options = replayOptions(fake.recorder, () => false);
+
+    await expect(startReplayCapture(options)).resolves.toBeNull();
+    expect(options.loadRecorder).not.toHaveBeenCalled();
+  });
+
+  it("resolves the recorder beside immutable and alias SDK assets", () => {
+    expect(resolveReplayRecorderUrl({
+      scriptSrc: "https://events.example.test/sdk/0.1.0%2Babc/drip.live.js?x=1",
+    })).toBe("https://events.example.test/sdk/0.1.0%2Babc/drip.replay-recorder.js");
+    expect(resolveReplayRecorderUrl({
+      scriptSrc: "https://sdk.example.test/drip.js",
+    })).toBe("https://sdk.example.test/drip.replay-recorder.js");
+    expect(resolveReplayRecorderUrl({
+      scriptSrc: "https://events.example.test/sdk/1/drip.live.js?cache=1#fragment",
+    })).toBe("https://events.example.test/sdk/1/drip.replay-recorder.js");
+  });
+
+  it("prefers a configured recorder URL and rejects unknown script paths", () => {
+    expect(resolveReplayRecorderUrl({
+      configuredUrl: "https://assets.example.test/custom-recorder.js",
+      scriptSrc: "https://events.example.test/sdk/1/drip.live.js",
+    })).toBe("https://assets.example.test/custom-recorder.js");
+    expect(resolveReplayRecorderUrl({
+      configuredUrl: "://malformed",
+      scriptSrc: "https://events.example.test/sdk/1/drip.live.js",
+      pageUrl: "https://shop.example.test/products/example",
+    })).toBe("https://events.example.test/sdk/1/drip.replay-recorder.js");
+    expect(resolveReplayRecorderUrl({
+      scriptSrc: "https://events.example.test/s/shop.js",
+    })).toBeNull();
+  });
+
+  it("posts a contract-v1 deflate envelope with replay auth and QA fields", async () => {
+    const fake = fakeRecorder({
+      takeSignals: vi.fn(() => ({
+        ...emptySignals(),
+        clicks: [{ ts: 1_000, selector: "button#buy", x: 20, y: 30, mut_ms: 120 }],
+      })),
+    });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+    expect(controller).not.toBeNull();
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: { href: location.href } } });
+    fake.emit({ event: { type: 3, timestamp: 1_120, data: { source: 0, adds: [] } } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://events.example.test/replay-blocks");
+    expect(init).toMatchObject({
+      method: "POST",
+      keepalive: false,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Drip-Shop": "shop_1",
+        "X-Drip-Signature": "signature_1",
+      },
+    });
+    const envelope = JSON.parse(String(init?.body));
+    expect(envelope).toMatchObject({
+      contract: 1,
+      shop_id: "shop_1",
+      visitor_id: "visitor_1",
+      session_id: "session_1",
+      seq: 0,
+      first_ts: 1_000,
+      last_ts: 1_120,
+      event_count: 2,
+      url: "http://localhost:3000/products/example",
+      environment: "production",
+      qa_mode: 1,
+      qa_session_id: "qa_1",
+      sdk_version: "0.1.0+test",
+      assignments: [{ experiment_id: "exp_1", variation_id: "var_1" }],
+      codec: "deflate",
+      signals: expect.objectContaining({ clicks: [expect.objectContaining({ mut_ms: 120 })] }),
+    });
+    const compressed = Uint8Array.from(atob(envelope.payload_b64), (character) => character.charCodeAt(0));
+    expect(JSON.parse(strFromU8(inflateSync(compressed)))).toHaveLength(2);
+    controller?.stop(true);
+  });
+
+  it("uses keepalive for a small pagehide block", async () => {
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    window.dispatchEvent(new Event("pagehide"));
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[1]?.keepalive).toBe(true);
+    controller?.stop(true);
+  });
+
+  it("posts an oversized pagehide block without keepalive", async () => {
+    const fake = fakeRecorder({
+      compressSync: vi.fn(() => new Uint8Array(45_000)),
+    });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    window.dispatchEvent(new Event("pagehide"));
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(String(fetchMock.mock.calls[0]?.[1]?.body).length).toBeGreaterThan(60_000);
+    expect(fetchMock.mock.calls[0]?.[1]?.keepalive).toBe(false);
+    controller?.stop(true);
+  });
+
+  it("disables keepalive when multibyte signal text makes the body exceed 60KB", async () => {
+    const multibyteClicks = Array.from({ length: 20 }, (_, index) => ({
+      ts: index + 1,
+      selector: `button[data-label="${"é".repeat(480)}-${index}"]`,
+      x: index,
+      y: index,
+    }));
+    const fake = fakeRecorder({
+      compressSync: vi.fn(() => new Uint8Array(32_000)),
+      takeSignals: vi.fn(() => ({ ...emptySignals(), clicks: multibyteClicks })),
+    });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    window.dispatchEvent(new Event("pagehide"));
+
+    const body = String(fetchMock.mock.calls[0]?.[1]?.body);
+    expect(body.length).toBeLessThan(60_000);
+    expect(new TextEncoder().encode(body).length).toBeGreaterThanOrEqual(60_000);
+    expect(fetchMock.mock.calls[0]?.[1]?.keepalive).toBe(false);
+    controller?.stop(true);
+  });
+
+  it("caps replay envelope URLs before and after a block flush", async () => {
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    history.replaceState(null, "", `/products/${"a".repeat(2_100)}`);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(REPLAY_FLUSH_INTERVAL_MS);
+    history.replaceState(null, "", `/collections/${"b".repeat(2_100)}`);
+    fake.emit({ event: { type: 4, timestamp: 2_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(REPLAY_FLUSH_INTERVAL_MS);
+
+    const urls = fetchMock.mock.calls.map((call) => JSON.parse(String(call[1]?.body)).url);
+    expect(urls).toHaveLength(2);
+    expect(urls[0]).toHaveLength(2_000);
+    expect(urls[1]).toHaveLength(2_000);
+    controller?.stop(true);
+  });
+
+  it("uses keepalive for a small visibilitychange-hidden block and persists progress", async () => {
+    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("hidden");
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    vi.setSystemTime(new Date("2026-01-01T00:00:02.000Z"));
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[1]?.keepalive).toBe(true);
+    expect(fake.recorder.compressSync).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ elapsedMs: 2_000, nextSeq: 1, terminal: false });
+    controller?.stop(true);
+  });
+
+  it("mirrors an edge-routed events endpoint at /_drip/replay-blocks", async () => {
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const options = replayOptions(fake.recorder, () => false);
+    options.endpoint = "https://shop.example.test/_drip/events";
+    const controller = await startReplayCapture(options);
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://shop.example.test/_drip/replay-blocks",
+    );
+    controller?.stop(true);
+  });
+
+  it("keeps every replay-sampled assignment seen during the session", async () => {
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+    const secondAssignment = {
+      ...assignment,
+      experimentId: "exp_2",
+      variationId: "var_2",
+    };
+    controller?.update(
+      [secondAssignment],
+      [experiment({ id: "exp_2" })],
+    );
+    controller?.update([], []);
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body)).assignments).toEqual([
+      { experiment_id: "exp_1", variation_id: "var_1" },
+      { experiment_id: "exp_2", variation_id: "var_2" },
+    ]);
+    expect(fake.stop).not.toHaveBeenCalled();
+    controller?.stop(true);
+  });
+
+  it("stops without posting when a compressed block exceeds the payload cap", async () => {
+    const oversized = new Uint8Array(750_001);
+    const fake = fakeRecorder({
+      compress: vi.fn(async () => oversized),
+      compressSync: vi.fn(() => oversized),
+    });
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ nextSeq: 1, terminal: false });
+  });
+
+  it("flushes when uncompressed JSON reaches 512KB", async () => {
+    const fake = fakeRecorder({
+      compress: vi.fn(async () => new Uint8Array([1])),
+    });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({
+      event: { type: 4, timestamp: 1_000, data: { text: "x".repeat(512 * 1024) } },
+    });
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("continues queued flushes after a compression rejection", async () => {
+    const compress = vi.fn()
+      .mockRejectedValueOnce(new Error("compression failed"))
+      .mockResolvedValue(new Uint8Array([1]));
+    const fake = fakeRecorder({ compress });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+    fake.emit({ event: { type: 4, timestamp: 2_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(compress).toHaveBeenCalledTimes(2);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body)).seq).toBe(1);
+    controller?.stop(true);
+  });
+
+  it("reserves the next sequence before compression and resumes after reload", async () => {
+    const first = fakeRecorder({
+      compress: vi.fn(async () => {
+        throw new Error("compression failed");
+      }),
+    });
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(null, { status: 204 })));
+    const firstController = await startReplayCapture(replayOptions(first.recorder, () => false));
+
+    first.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    const second = fakeRecorder();
+    const secondController = await startReplayCapture(replayOptions(second.recorder, () => false));
+    second.emit({ event: { type: 4, timestamp: 2_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    const fetchMock = vi.mocked(fetch);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body)).seq).toBe(1);
+    firstController?.stop(true);
+    secondController?.stop(true);
+  });
+
+  it("resumes with the next sequence after consent revoke and re-grant", async () => {
+    let blocked = false;
+    const first = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const options = replayOptions(first.recorder, () => blocked);
+    const firstController = await startReplayCapture(options);
+
+    first.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(REPLAY_FLUSH_INTERVAL_MS);
+    blocked = true;
+    firstController?.update([assignment], [experiment()]);
+
+    expect(firstController?.isStopped()).toBe(true);
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ nextSeq: 1, terminal: false });
+
+    blocked = false;
+    const second = fakeRecorder();
+    const secondController = await startReplayCapture({
+      ...options,
+      loadRecorder: vi.fn(async () => second.recorder),
+    });
+    second.emit({ event: { type: 4, timestamp: 2_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(REPLAY_FLUSH_INTERVAL_MS);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls.map((call) => JSON.parse(String(call[1]?.body)).seq))
+      .toEqual([0, 1]);
+    secondController?.stop(true);
+  });
+
+  it("restores compressed-byte progress and blocks a cross-page overrun", async () => {
+    const compressed = new Uint8Array(700_000);
+    sessionStorage.setItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`, JSON.stringify({
+      nextSeq: 5,
+      totalCompressedBytes: REPLAY_MAX_COMPRESSED_BYTES - 699_999,
+      elapsedMs: 0,
+      terminal: false,
+      form_focus: [],
+      form_submit: [],
+    }));
+    const fake = fakeRecorder({
+      compress: vi.fn(async () => compressed),
+    });
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ nextSeq: 6, terminal: true });
+  });
+
+  it("uses the remaining persisted duration and records empty pagehide progress", async () => {
+    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+    const first = fakeRecorder();
+    const firstController = await startReplayCapture(replayOptions(first.recorder, () => false));
+    await vi.advanceTimersByTimeAsync(5 * 60 * 1_000);
+    window.dispatchEvent(new Event("pagehide"));
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ elapsedMs: 5 * 60 * 1_000, terminal: false });
+
+    const second = fakeRecorder();
+    const secondController = await startReplayCapture(replayOptions(second.recorder, () => false));
+    await vi.advanceTimersByTimeAsync(REPLAY_MAX_DURATION_MS - 5 * 60 * 1_000 - 1);
+    expect(second.stop).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(second.stop).toHaveBeenCalledTimes(1);
+    firstController?.stop(true);
+    secondController?.stop(true);
+  });
+
+  it("normalizes and hands the full persisted signal track to the recorder", async () => {
+    sessionStorage.setItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`, JSON.stringify({
+      clicks: [{ ts: 1, selector: " button#buy ", x: 10, y: 20, mut_ms: 120 }],
+      nav: [{ ts: 2, url: "https://shop.example.test/entry" }],
+      errors: [{ ts: 3, message: "Window error" }],
+      form_focus: [
+        { ts: 10, selector: " form#checkout " },
+        { ts: 11, selector: "form#checkout" },
+        { ts: null, selector: "form#invalid" },
+      ],
+      form_submit: [{ ts: 20, selector: "form#checkout" }],
+      scroll_max_pct: 75,
+    }));
+    const fake = fakeRecorder();
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    expect(fake.recorder.start).toHaveBeenCalledWith(expect.objectContaining({
+      signalState: {
+        clicks: [{ ts: 1, selector: "button#buy", x: 10, y: 20, mut_ms: 120 }],
+        nav: [{ ts: 2, url: "https://shop.example.test/entry" }],
+        errors: [{ ts: 3, message: "Window error" }],
+        form_focus: [{ ts: 10, selector: "form#checkout" }],
+        form_submit: [{ ts: 20, selector: "form#checkout" }],
+        scroll_max_pct: 75,
+      },
+    }));
+    controller?.stop(true);
+  });
+
+  it("persists the full cumulative signal track from recorder snapshots", async () => {
+    const fake = fakeRecorder({
+      takeSignals: vi.fn(() => ({
+        clicks: [{ ts: 1, selector: "button#buy", x: 10, y: 20, mut_ms: 120 }],
+        nav: [{ ts: 2, url: "https://shop.example.test/entry" }],
+        errors: [{ ts: 3, message: "Window error" }],
+        form_focus: [{ ts: 10, selector: "form#checkout" }],
+        form_submit: [{ ts: 20, selector: "form#checkout" }],
+        scroll_max_pct: 75,
+      })),
+    });
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({
+        clicks: [{ ts: 1, selector: "button#buy", x: 10, y: 20, mut_ms: 120 }],
+        nav: [{ ts: 2, url: "https://shop.example.test/entry" }],
+        errors: [{ ts: 3, message: "Window error" }],
+        form_focus: [{ ts: 10, selector: "form#checkout" }],
+        form_submit: [{ ts: 20, selector: "form#checkout" }],
+        scroll_max_pct: 75,
+      });
+    controller?.stop(true);
+  });
+
+  it("degrades to page-local capture when session storage is unavailable", async () => {
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new DOMException("blocked", "SecurityError");
+    });
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new DOMException("quota", "QuotaExceededError");
+    });
+    const fake = fakeRecorder();
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    expect(controller).not.toBeNull();
+    expect(fake.recorder.start).toHaveBeenCalledTimes(1);
+    expect(() => controller?.stop(true)).not.toThrow();
+  });
+
+  it("refuses to reload a terminal replay session", async () => {
+    const first = fakeRecorder();
+    const controller = await startReplayCapture(replayOptions(first.recorder, () => false));
+    controller?.stop();
+
+    const second = fakeRecorder();
+    const options = replayOptions(second.recorder, () => false);
+    await expect(startReplayCapture(options)).resolves.toBeNull();
+    expect(options.loadRecorder).not.toHaveBeenCalled();
+    expect(second.recorder.start).not.toHaveBeenCalled();
+  });
+
+  it("stops before total compressed data exceeds 4MB", async () => {
+    const compressed = new Uint8Array(700_000);
+    const fake = fakeRecorder({
+      compress: vi.fn(async () => compressed),
+      compressSync: vi.fn(() => compressed),
+    });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    for (let seq = 0; seq < 6; seq += 1) {
+      fake.emit({ event: { type: 4, timestamp: seq + 1, data: {} } });
+      window.dispatchEvent(new Event("pagehide"));
+    }
+
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops emission at the shared replay block cap", async () => {
+    const fake = fakeRecorder({
+      compress: vi.fn(async () => new Uint8Array([1])),
+      compressSync: vi.fn(() => new Uint8Array([1])),
+    });
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    for (let seq = 0; seq <= REPLAY_MAX_BLOCKS; seq += 1) {
+      fake.emit({ event: { type: 4, timestamp: seq + 1, data: {} } });
+      window.dispatchEvent(new Event("pagehide"));
+    }
+
+    expect(fetchMock).toHaveBeenCalledTimes(REPLAY_MAX_BLOCKS);
+    expect(JSON.parse(String(fetchMock.mock.calls.at(-1)?.[1]?.body)).seq)
+      .toBe(REPLAY_MAX_BLOCKS - 1);
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("flushes and stops at the 15-minute duration cap", async () => {
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+    await vi.advanceTimersByTimeAsync(15 * 60 * 1_000);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops and discards buffered events when consent is revoked", async () => {
+    let blocked = false;
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => blocked));
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: {} } });
+
+    blocked = true;
+    controller?.update([assignment], [experiment()]);
+    await vi.advanceTimersByTimeAsync(20_000);
+
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(controller?.isStopped()).toBe(true);
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ terminal: false });
+  });
+
+  it("stops and discards the partial block after SPA navigation into checkout", async () => {
+    const fake = fakeRecorder();
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const controller = await startReplayCapture(replayOptions(fake.recorder, () => false));
+
+    fake.emit({ event: { type: 4, timestamp: 1_000, data: { href: location.href } } });
+    history.pushState(null, "", "/checkout");
+    fake.emit({ event: { type: 4, timestamp: 1_150, data: { href: location.href } } });
+    await vi.advanceTimersByTimeAsync(20_000);
+
+    expect(fake.stop).toHaveBeenCalledTimes(1);
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(controller?.isStopped()).toBe(true);
+    expect(JSON.parse(sessionStorage.getItem(`${REPLAY_PROGRESS_KEY_PREFIX}session_1`)!))
+      .toMatchObject({ terminal: false });
+  });
+});