@lightworkai.official/debug-capture 0.19.7 → 0.19.9

package/src/replayPack.ts

@@ -4,8 +4,7 @@
  * rrweb events compress about ten to one — a full snapshot is mostly
  * repeated markup — so the browser gzips them before they travel, with the
  * stream API every current browser has. Where it is missing the JSON goes as
- * it is, if it fits; a replay is the one part of a report worth losing rather
- * than failing the report over.
+ * it is, if it fits.
  *
  * Its own file, like the screenshot and for the same reason: `context` is a
  * column on the ticket row, read by every query that returns the ticket, and
@@ -14,6 +13,7 @@
  */
 import { toBase64 } from "./base64";
 import { redactReplay } from "./capture/replayRedact";
+import { browserJpeg, hasHeavyPngs, lightenPictures, pictureStrings, type PictureEncoder } from "./replayPictures";
 import type { ReplayCapture, ReplayEvent, ReplaySummary } from "./types";
 
 /** The name the desk looks for. Changing it here changes it nowhere else. */
@@ -26,6 +26,13 @@ export interface PackedReplay {
   summary: ReplaySummary;
 }
 
+export interface PackOptions {
+  /** JPEG quality for a canvas picture the browser could only make as PNG. Default 0.5. */
+  quality?: number;
+  /** How such a picture is made lighter. Default the browser's own encoder; null skips the step. */
+  lighten?: PictureEncoder | null;
+}
+
 /** Is there something to attach, before the work of packing it. */
 export function hasReplayEvents(replay: ReplayCapture | null | undefined): replay is ReplayCapture {
   return Boolean(replay && replay.events.length > 0);
@@ -41,51 +48,249 @@ async function gzip(bytes: Uint8Array): Promise<Uint8Array | null> {
   }
 }
 
+interface Encoded {
+  bytes: Uint8Array;
+  compressed: boolean;
+}
+
+async function encode(events: ReplayEvent[]): Promise<Encoded> {
+  const plain = new TextEncoder().encode(JSON.stringify({ events }));
+  const zipped = await gzip(plain);
+  return zipped ? { bytes: zipped, compressed: true } : { bytes: plain, compressed: false };
+}
+
+/** How much of each picture the estimate reads, and from how many. A megabyte at most. */
+const SAMPLE_EACH = 65_536;
+const SAMPLE_PICTURES = 16;
+
+/**
+ * The least the canvas pictures alone will weigh compressed — without
+ * compressing them. Gzip is most of a pack's time: in WebKit 6 of 10.6
+ * seconds for an 82 MB recording, measured 2026-11-02 — and a recording that
+ * large is over the cap before it starts. A sample of the pictures is
+ * gzipped instead (Safari's PNG came out at 0.75 of its base64, but a
+ * browser's encoder is not ours to assume), and the estimate kept a tenth
+ * under what the sample says. Zero when there are none.
+ */
+async function pictureFloor(events: readonly ReplayEvent[]): Promise<number> {
+  const pictures = pictureStrings(events);
+  const total = pictures.reduce((sum, p) => sum + p.length, 0);
+  if (total === 0) return 0;
+  const step = Math.max(1, Math.floor(pictures.length / SAMPLE_PICTURES));
+  let sample = "";
+  for (let i = 0; i < pictures.length && sample.length < SAMPLE_EACH * SAMPLE_PICTURES; i += step) sample += pictures[i]!.slice(0, SAMPLE_EACH);
+  const plain = new TextEncoder().encode(sample);
+  const zipped = await gzip(plain);
+  const ratio = zipped ? zipped.byteLength / plain.byteLength : 1;
+  return total * ratio * 0.9;
+}
+
+/** What was given up to fit, said on the ticket. */
+interface Cuts {
+  canvasDropped?: true;
+  picturesDropped?: true;
+  /** Long text and styles shortened — the last resort before the snapshot itself. */
+  simplified?: true;
+  /** "start": only the latest part went. "end": not even that whole, the recording stops before the report. */
+  trimmed?: "start" | "end";
+}
+
 /**
  * Pack, or say why not. Never throws: the report goes on without it.
  *
  * The cap is applied to what is SENT — compressed bytes when compression is
  * available — because that is the number the server's per-file limit is
  * measured against.
+ *
+ * Over the cap, a report still carries a recording. Each step below is taken
+ * only when the one before it did not fit, and each gives up less than the
+ * next:
+ *
+ *   1. Safari's PNG canvas pictures saved again as JPEG (replayPictures) —
+ *      nothing visible is lost.
+ *   2. Canvas pictures kept from the latest moment that fits, the earlier
+ *      ones left out: the document as it last looked, over the whole
+ *      recording. A canvas whose picture went plays blank until it is next
+ *      drawn.
+ *   3. Every canvas picture left out: the canvases stay, blank; every
+ *      click, page and field is still there.
+ *   4. Large pictures embedded in the page itself (a `data:` image, a font
+ *      inlined in a stylesheet) swapped for an empty one.
+ *   5. The oldest part left out: the recording is kept in stretches that
+ *      each begin with a full picture of the page (capture/replay — a
+ *      checkout every half of the configured length), so the latest
+ *      stretches play on their own. As many as fit, newest first.
+ *   6. The latest stretch from its start, as far as fits — it then stops
+ *      before the report, and the ticket says by how much.
+ *   7. Long text and styles shortened, when not even the page's own picture
+ *      fits.
+ *
+ * Only a page whose single picture is over the cap after all of that goes
+ * without — millions of elements. CIB-5880 (2026-11-02) went without at
+ * step 3: the strip missed every canvas added after the snapshot, and
+ * Safari's pictures are PNG.
  */
-export async function packReplay(replay: ReplayCapture | null | undefined, maxBytes: number): Promise<PackedReplay | { summary: ReplaySummary }> {
+export async function packReplay(
+  replay: ReplayCapture | null | undefined,
+  maxBytes: number,
+  options: PackOptions = {},
+): Promise<PackedReplay | { summary: ReplaySummary }> {
   if (!hasReplayEvents(replay)) return { summary: { omitted: "empty" } };
-  const seconds = Math.round(replay.durationMs / 1000);
-  const base = { seconds, events: replay.events.length, startedAt: replay.startedAt, endedAt: replay.endedAt };
-  // The same URL policy as the network log — see capture/replayRedact.
-  let events = redactReplay(replay.events);
-  let encoded = await encode(events);
-  let canvasDropped = false;
-  /*
-   * Over the cap, the canvas frames go first: they are the one part of a
-   * replay that can be megabytes on its own (a PDF page a second), and a
-   * replay without them still shows every click. Only if that is not
-   * enough does the whole thing stay behind.
-   */
-  if (encoded.bytes.byteLength > maxBytes && hasCanvasFrames(events)) {
-    events = stripCanvas(events);
-    encoded = await encode(events);
-    canvasDropped = true;
-  }
-  const { bytes, compressed } = encoded;
-  if (bytes.byteLength > maxBytes) return { summary: { ...base, bytes: bytes.byteLength, omitted: "too-large" } };
+  const recordedSeconds = Math.round(replay.durationMs / 1000);
+  // The same URL policy as the network log — see capture/replayRedact. A copy: every step below works on it in place.
+  const events = redactReplay(replay.events);
+  const fitted = await fit(events, maxBytes, options);
+  if (!("events" in fitted)) {
+    return {
+      summary: {
+        seconds: recordedSeconds,
+        events: replay.events.length,
+        startedAt: replay.startedAt,
+        endedAt: replay.endedAt,
+        bytes: fitted.bytes,
+        omitted: "too-large",
+      },
+    };
+  }
+  const { bytes, compressed } = fitted.encoded;
+  const sent = fitted.events;
+  const first = sent[0]!.timestamp;
+  const last = sent[sent.length - 1]!.timestamp;
+  const { trimmed, ...dropped } = fitted.cuts;
+  const recordedEnd = Date.parse(replay.endedAt);
   return {
     dataUri: `data:${compressed ? "application/gzip" : "application/json"};base64,${toBase64(bytes)}`,
     filename: compressed ? REPLAY_FILENAME : PLAIN_FILENAME,
-    summary: { ...base, events: events.length, bytes: bytes.byteLength, compressed, ...(canvasDropped ? { canvasDropped } : {}) },
+    summary: {
+      seconds: Math.round((last - first) / 1000),
+      events: sent.length,
+      startedAt: new Date(first).toISOString(),
+      endedAt: new Date(last).toISOString(),
+      bytes: bytes.byteLength,
+      compressed,
+      ...dropped,
+      ...(trimmed ? { recordedSeconds } : {}),
+      ...(trimmed === "end" && !Number.isNaN(recordedEnd) ? { endsEarlySeconds: Math.round((recordedEnd - last) / 1000) } : {}),
+    },
   };
 }
 
-async function encode(events: ReplayEvent[]): Promise<{ bytes: Uint8Array; compressed: boolean }> {
-  const plain = new TextEncoder().encode(JSON.stringify({ events }));
-  const zipped = await gzip(plain);
-  return zipped ? { bytes: zipped, compressed: true } : { bytes: plain, compressed: false };
+type Fitted = { events: ReplayEvent[]; encoded: Encoded; cuts: Cuts } | { bytes: number };
+
+async function fit(events: ReplayEvent[], maxBytes: number, options: PackOptions): Promise<Fitted> {
+  const cuts: Cuts = {};
+  /** What the recording weighed whole — the summary's number when nothing fits. */
+  let whole = 0;
+  /** These events encoded, when they fit; not even encoded when their pictures alone cannot. */
+  const attempt = async (list: ReplayEvent[]): Promise<Encoded | null> => {
+    const floor = await pictureFloor(list);
+    if (floor > maxBytes) {
+      whole ||= Math.round(floor);
+      return null;
+    }
+    const encoded = await encode(list);
+    whole ||= encoded.bytes.byteLength;
+    return encoded.bytes.byteLength <= maxBytes ? encoded : null;
+  };
+  let encoded = await attempt(events);
+  if (encoded) return { events, encoded, cuts };
+
+  // 1. Safari's PNGs as JPEG.
+  const lighten = options.lighten === undefined ? browserJpeg(options.quality ?? 0.5) : options.lighten;
+  if (lighten && hasHeavyPngs(events) && (await lightenPictures(events, lighten)) > 0) {
+    encoded = await attempt(events);
+    if (encoded) return { events, encoded, cuts };
+  }
+  // 2. Canvas pictures kept from the latest moment that fits — the document as it last looked, over the whole recording.
+  const moments = [...new Set(events.filter(hasCanvasPicture).map((e) => e.timestamp))].sort((x, y) => x - y);
+  if (moments.length > 1) {
+    // Keeping from moments[0] is the whole, which did not fit; from past the last is step 3.
+    let lo = 1;
+    let hi = moments.length;
+    let best: { events: ReplayEvent[]; encoded: Encoded } | null = null;
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      const kept = picturesFrom(events, moments[mid]!);
+      const e = await attempt(kept);
+      if (e) {
+        best = { events: kept, encoded: e };
+        hi = mid;
+      } else lo = mid + 1;
+    }
+    if (best) return { ...best, cuts: { ...cuts, canvasDropped: true } };
+  }
+  // 3. Every canvas picture.
+  if (stripCanvas(events)) {
+    cuts.canvasDropped = true;
+    events = events.filter((e) => !isCanvasFrame(e));
+    encoded = await attempt(events);
+    if (encoded) return { events, encoded, cuts };
+  }
+  // 4. Pictures embedded in the page.
+  if (dropEmbedded(events)) {
+    cuts.picturesDropped = true;
+    encoded = await attempt(events);
+    if (encoded) return { events, encoded, cuts };
+  }
+
+  // 5. The oldest stretches.
+  const windows = splitWindows(events);
+  if (windows.length > 1) {
+    const sizes: number[] = [];
+    for (const w of windows) sizes.push((await encode(w)).bytes.byteLength);
+    // Newest first, as many as their sizes allow; then confirmed whole, one fewer at a time.
+    let from = windows.length;
+    let total = 0;
+    while (from > 0 && total + sizes[from - 1]! <= maxBytes) total += sizes[--from]!;
+    for (let k = Math.max(from, 1); k < windows.length; k++) {
+      const kept = windows.slice(k).flat();
+      encoded = await encode(kept);
+      if (encoded.bytes.byteLength <= maxBytes) return { events: kept, encoded, cuts: { ...cuts, trimmed: "start" } };
+    }
+  }
+
+  // 6. The latest stretch from its start, as far as fits; 7. shortened, if not even its picture does.
+  const latest = windows[windows.length - 1]!;
+  let head = await fitHead(latest, maxBytes);
+  if (!head && cutLongStrings(latest)) {
+    cuts.simplified = true;
+    head = await fitHead(latest, maxBytes);
+  }
+  if (!head) return { bytes: whole };
+  const trimmed = head.events.length < latest.length ? "end" : windows.length > 1 ? "start" : undefined;
+  return { ...head, cuts: { ...cuts, ...(trimmed ? { trimmed } : {}) } };
 }
 
-/* rrweb: a canvas frame is an IncrementalSnapshot (3) from the CanvasMutation
- * source (9); the full snapshot carries a canvas's picture as `rr_dataURL`. */
-const INCREMENTAL = 3;
+/**
+ * The longest start of one stretch that fits — never shorter than its Meta
+ * and full snapshot, without which nothing plays. Null when not even those do.
+ */
+async function fitHead(stretch: ReplayEvent[], maxBytes: number): Promise<{ events: ReplayEvent[]; encoded: Encoded } | null> {
+  // `lo` events always fit, more than `hi` never do.
+  let lo = stretch.findIndex((e) => e.type === FULL_SNAPSHOT) + 1 || 1;
+  let hi = stretch.length;
+  let best = { events: stretch.slice(0, lo), encoded: await encode(stretch.slice(0, lo)) };
+  if (best.encoded.bytes.byteLength > maxBytes) return null;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    const prefix = stretch.slice(0, mid);
+    const encoded = await encode(prefix);
+    if (encoded.bytes.byteLength <= maxBytes) {
+      lo = mid;
+      best = { events: prefix, encoded };
+    } else hi = mid - 1;
+  }
+  return best;
+}
+
+/* rrweb: a Meta (4) opens every full snapshot (2); a canvas frame is an
+ * IncrementalSnapshot (3) from the CanvasMutation source (9); a canvas's
+ * picture is `rr_dataURL`, on the full snapshot's node and on a node a
+ * Mutation (source 0) adds later. */
+const META = 4;
 const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+const MUTATION = 0;
 const CANVAS_MUTATION = 9;
 
 interface SerializedNode {
@@ -97,29 +302,149 @@ function isCanvasFrame(e: ReplayEvent): boolean {
   return e.type === INCREMENTAL && (e.data as { source?: number } | null)?.source === CANVAS_MUTATION;
 }
 
-function hasCanvasFrames(events: readonly ReplayEvent[]): boolean {
-  return events.some(isCanvasFrame) || events.some((e) => e.type === FULL_SNAPSHOT && hasDataUrl((e.data as { node?: SerializedNode }).node));
+/** Every serialized node an event carries: a snapshot's tree, a mutation's added nodes. */
+function eachNodeTree(e: ReplayEvent, visit: (node: SerializedNode | undefined) => void): void {
+  const data = e.data as Record<string, unknown> | null;
+  if (!data || typeof data !== "object") return;
+  if (e.type === FULL_SNAPSHOT) visit(data.node as SerializedNode | undefined);
+  else if (e.type === INCREMENTAL && data.source === MUTATION) {
+    for (const add of (data.adds as Array<{ node?: SerializedNode }> | undefined) ?? []) visit(add.node);
+  }
 }
 
-function hasDataUrl(node: SerializedNode | undefined): boolean {
+/** Removes every `rr_dataURL` below `node`; whether there was one. */
+function dropDataUrls(node: SerializedNode | undefined): boolean {
   if (!node) return false;
-  if (node.attributes && "rr_dataURL" in node.attributes) return true;
-  return (node.childNodes ?? []).some(hasDataUrl);
+  let found = false;
+  if (node.attributes && "rr_dataURL" in node.attributes) {
+    delete node.attributes.rr_dataURL;
+    found = true;
+  }
+  for (const child of node.childNodes ?? []) found = dropDataUrls(child) || found;
+  return found;
 }
 
-function dropDataUrls(node: SerializedNode | undefined): void {
-  if (!node) return;
-  if (node.attributes && "rr_dataURL" in node.attributes) delete node.attributes.rr_dataURL;
-  for (const child of node.childNodes ?? []) dropDataUrls(child);
+function hasDataUrl(node: SerializedNode | undefined): boolean {
+  return !!node && ((node.attributes !== undefined && "rr_dataURL" in node.attributes) || (node.childNodes ?? []).some(hasDataUrl));
 }
 
-/** The same replay with every canvas picture removed — the canvases stay, blank. */
-export function stripCanvas(events: readonly ReplayEvent[]): ReplayEvent[] {
+/** Whether an event carries a canvas picture: a frame, or a node with one. */
+function hasCanvasPicture(e: ReplayEvent): boolean {
+  if (isCanvasFrame(e)) return true;
+  let found = false;
+  eachNodeTree(e, (node) => (found ||= hasDataUrl(node)));
+  return found;
+}
+
+/** A node tree without its pictures, sharing everything else — the strings are not copied. */
+function withoutDataUrls(node: SerializedNode | undefined): SerializedNode | undefined {
+  if (!node || !hasDataUrl(node)) return node;
+  const { rr_dataURL: _picture, ...attributes } = node.attributes ?? {};
+  return { ...node, ...(node.attributes ? { attributes } : {}), ...(node.childNodes ? { childNodes: node.childNodes.map((c) => withoutDataUrls(c)!) } : {}) };
+}
+
+/**
+ * The recording with only the canvas pictures from `since` on: an earlier
+ * frame left out, an earlier snapshot's or added canvas's picture removed —
+ * those canvases play blank until they are next drawn. New events where one
+ * changes; the events handed in are not touched.
+ */
+function picturesFrom(events: readonly ReplayEvent[], since: number): ReplayEvent[] {
   const out: ReplayEvent[] = [];
   for (const e of events) {
-    if (isCanvasFrame(e)) continue;
-    if (e.type === FULL_SNAPSHOT) dropDataUrls((e.data as { node?: SerializedNode }).node);
-    out.push(e);
+    if (e.timestamp >= since || !hasCanvasPicture(e)) out.push(e);
+    else if (isCanvasFrame(e)) continue;
+    else if (e.type === FULL_SNAPSHOT) {
+      const data = e.data as { node?: SerializedNode };
+      out.push({ ...e, data: { ...data, node: withoutDataUrls(data.node) } });
+    } else {
+      const data = e.data as { adds?: Array<{ node?: SerializedNode }> };
+      out.push({ ...e, data: { ...data, adds: (data.adds ?? []).map((add) => ({ ...add, node: withoutDataUrls(add.node) })) } });
+    }
   }
   return out;
 }
+
+/**
+ * Every canvas picture removed, in place — the canvases stay, blank. The
+ * snapshot's and those on a canvas added later alike: missing the second
+ * kind is how CIB-5749 went out marked `canvasDropped` with 1.05 MB of
+ * pictures on fourteen canvases still in it. Canvas frames are dropped by
+ * the caller (`isCanvasFrame`). Whether there was anything to remove.
+ */
+export function stripCanvas(events: readonly ReplayEvent[]): boolean {
+  let found = false;
+  for (const e of events) {
+    if (isCanvasFrame(e)) found = true;
+    else eachNodeTree(e, (node) => (found = dropDataUrls(node) || found));
+  }
+  return found;
+}
+
+/** Larger than this, an embedded `data:` URL is a picture or a font rather than an icon. */
+const EMBED_LIMIT = 16_384;
+/** What a dropped picture becomes: a transparent pixel, so the element keeps its box and shows no broken-image icon. */
+const BLANK_PICTURE = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+const CSS_DATA_URL = new RegExp(`url\\(\\s*(['"]?)data:[^'")]{${EMBED_LIMIT},}\\1\\s*\\)`, "g");
+
+/** Each string in an event, through `change`, in place. Whether any changed. */
+function mapStrings(value: unknown, change: (s: string) => string): boolean {
+  if (!value || typeof value !== "object") return false;
+  let changed = false;
+  const entries = Array.isArray(value) ? value.map((v, i) => [i, v] as const) : Object.entries(value);
+  for (const [key, v] of entries) {
+    if (typeof v === "string") {
+      const next = change(v);
+      if (next !== v) {
+        (value as Record<string | number, unknown>)[key] = next;
+        changed = true;
+      }
+    } else if (v && typeof v === "object") changed = mapStrings(v, change) || changed;
+  }
+  return changed;
+}
+
+/**
+ * Large pictures the page itself holds — an `<img src="data:…">`, a font or
+ * background inlined in a stylesheet — swapped for an empty one, in place,
+ * wherever the events carry them: attributes, styles, style rules.
+ */
+export function dropEmbedded(events: readonly ReplayEvent[]): boolean {
+  let found = false;
+  for (const e of events) {
+    found =
+      mapStrings(e.data, (s) => {
+        if (s.length < EMBED_LIMIT) return s;
+        if (s.startsWith("data:")) return s.startsWith("data:image/") ? BLANK_PICTURE : "";
+        return s.includes("data:") ? s.replace(CSS_DATA_URL, "url()") : s;
+      }) || found;
+  }
+  return found;
+}
+
+/** Longer than this, a string is cut — the last resort, for a page whose own picture will not fit otherwise. */
+const STRING_LIMIT = 2_000;
+
+function cutLongStrings(stretch: readonly ReplayEvent[]): boolean {
+  let found = false;
+  for (const e of stretch) found = mapStrings(e.data, (s) => (s.length > STRING_LIMIT ? s.slice(0, STRING_LIMIT) : s)) || found;
+  return found;
+}
+
+/**
+ * The recording in its stretches, each from a Meta and full snapshot to the
+ * next — the units it can be shortened by and still play. Anything before
+ * the first Meta rides with the first stretch.
+ */
+export function splitWindows(events: readonly ReplayEvent[]): ReplayEvent[][] {
+  const windows: ReplayEvent[][] = [[]];
+  let opened = false;
+  for (const e of events) {
+    if (e.type === META) {
+      if (opened) windows.push([]);
+      opened = true;
+    }
+    windows[windows.length - 1]!.push(e);
+  }
+  return windows;
+}

package/src/replayPictures.ts

@@ -0,0 +1,200 @@
+/**
+ * Canvas pictures made lighter, for the browsers that cannot make WebP.
+ *
+ * The recorder asks for WebP (`dataURLOptions`), and Safari answers every such
+ * request with a PNG — the same bytes `toDataURL("image/png")` gives, the
+ * quality ignored. A PDF page drawn at a Retina display's size is then a
+ * megabyte or more where Chrome's WebP is a tenth of that, and PNG's bytes do
+ * not gzip. CIB-5880 (2026-11-02): a 76-second recording of signing a
+ * document in Safari was 36 MB compressed against a 4 MB cap, and the report
+ * went without it.
+ *
+ * Over the cap, each large PNG is drawn again and saved as JPEG — but only
+ * one that is opaque throughout. JPEG has no transparency, and a canvas drawn
+ * over another (a signature layer, a chart on a coloured card) would play
+ * back as a solid box hiding what was under it; such a picture stays a PNG.
+ *
+ * Two places hold a picture: a canvas's `rr_dataURL` attribute, in the full
+ * snapshot and on a canvas added after it, and a canvas frame's `drawImage`
+ * of a Blob. Both are rewritten here, on the events handed in — the caller's
+ * copy, never the recorder's buffers.
+ */
+import { toBase64 } from "./base64";
+import type { ReplayEvent } from "./types";
+
+export interface Picture {
+  base64: string;
+  type: string;
+}
+
+/** A picture as JPEG, or null to keep it as it is. */
+export type PictureEncoder = (picture: Picture) => Promise<Picture | null>;
+
+/** Below this a PNG is not worth the work: an icon, a blank-ish chart. ~22 KB of bytes. */
+const WORTH_IT = 30_000;
+
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+const MUTATION = 0;
+const CANVAS_MUTATION = 9;
+
+interface SerializedNode {
+  attributes?: Record<string, unknown>;
+  childNodes?: SerializedNode[];
+}
+
+/** One place a picture is kept, and how to put a new one there. */
+interface Slot {
+  picture: Picture;
+  put: (next: Picture) => void;
+}
+
+const DATA_URL = /^data:([^;,]+);base64,/;
+
+function attributeSlots(node: SerializedNode | undefined, out: Slot[]): void {
+  if (!node) return;
+  const attributes = node.attributes;
+  const url = attributes?.rr_dataURL;
+  if (attributes && typeof url === "string") {
+    const match = DATA_URL.exec(url);
+    if (match) {
+      out.push({
+        picture: { type: match[1]!, base64: url.slice(match[0].length) },
+        put: (next) => (attributes.rr_dataURL = `data:${next.type};base64,${next.base64}`),
+      });
+    }
+  }
+  for (const child of node.childNodes ?? []) attributeSlots(child, out);
+}
+
+interface BlobArg {
+  rr_type?: string;
+  type?: string;
+  data?: Array<{ rr_type?: string; base64?: string }>;
+  args?: unknown[];
+}
+
+function frameSlots(commands: unknown, out: Slot[]): void {
+  if (!Array.isArray(commands)) return;
+  for (const command of commands as Array<{ args?: unknown[] }>) {
+    for (const arg of command.args ?? []) {
+      const bitmap = arg as BlobArg | null;
+      if (bitmap?.rr_type !== "ImageBitmap") continue;
+      const blob = bitmap.args?.[0] as BlobArg | undefined;
+      const buffer = blob?.rr_type === "Blob" ? blob.data?.[0] : undefined;
+      if (!blob || buffer?.rr_type !== "ArrayBuffer" || typeof buffer.base64 !== "string" || typeof blob.type !== "string") continue;
+      out.push({
+        picture: { type: blob.type, base64: buffer.base64 },
+        put: (next) => {
+          blob.type = next.type;
+          buffer.base64 = next.base64;
+        },
+      });
+    }
+  }
+}
+
+/** Every canvas picture in the events, wherever the recorder put it. */
+export function pictureSlots(events: readonly ReplayEvent[]): Slot[] {
+  const out: Slot[] = [];
+  for (const event of events) {
+    const data = event.data as Record<string, unknown> | null;
+    if (!data || typeof data !== "object") continue;
+    if (event.type === FULL_SNAPSHOT) attributeSlots(data.node as SerializedNode | undefined, out);
+    else if (event.type === INCREMENTAL && data.source === MUTATION) {
+      for (const add of (data.adds as Array<{ node?: SerializedNode }> | undefined) ?? []) attributeSlots(add.node, out);
+    } else if (event.type === INCREMENTAL && data.source === CANVAS_MUTATION) frameSlots(data.commands, out);
+  }
+  return out;
+}
+
+/** Every picture's base64, as often as it occurs — gzip's 32 KB window never sees a picture's earlier copy. */
+export function pictureStrings(events: readonly ReplayEvent[]): string[] {
+  return pictureSlots(events).map((slot) => slot.picture.base64);
+}
+
+const heavyPng = (slot: Slot) => slot.picture.type === "image/png" && slot.picture.base64.length >= WORTH_IT;
+
+/** Whether there is anything for `lightenPictures` to do — before the work of decoding. */
+export function hasHeavyPngs(events: readonly ReplayEvent[]): boolean {
+  return pictureSlots(events).some(heavyPng);
+}
+
+/**
+ * Each large PNG replaced by what `encode` makes of it, when that is smaller.
+ * The same picture is encoded once however often it recurs — a page's
+ * picture is in every snapshot the recording holds. Returns how many changed.
+ * A picture the encoder fails on stays as it was: this never throws.
+ */
+export async function lightenPictures(events: ReplayEvent[], encode: PictureEncoder): Promise<number> {
+  const done = new Map<string, Picture | null>();
+  let changed = 0;
+  for (const slot of pictureSlots(events).filter(heavyPng)) {
+    const key = slot.picture.base64;
+    if (!done.has(key)) {
+      let next: Picture | null = null;
+      try {
+        next = await encode(slot.picture);
+      } catch {
+        next = null;
+      }
+      done.set(key, next && next.base64.length < key.length ? next : null);
+    }
+    const next = done.get(key);
+    if (next) {
+      slot.put(next);
+      changed += 1;
+    }
+  }
+  return changed;
+}
+
+function fromBase64(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+type AnyCanvas = OffscreenCanvas | HTMLCanvasElement;
+
+function canvasOf(width: number, height: number): AnyCanvas | null {
+  if (typeof OffscreenCanvas !== "undefined") return new OffscreenCanvas(width, height);
+  if (typeof document === "undefined") return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  return canvas;
+}
+
+function jpegOf(canvas: AnyCanvas, quality: number): Promise<Blob | null> {
+  if ("convertToBlob" in canvas) return canvas.convertToBlob({ type: "image/jpeg", quality });
+  return new Promise((resolve) => canvas.toBlob(resolve, "image/jpeg", quality));
+}
+
+/**
+ * The browser's own encoder: the PNG decoded, checked opaque pixel by pixel,
+ * and saved as JPEG at `quality`. Null where the browser lacks what it takes
+ * (no `createImageBitmap`), for a picture anything shows through, and for a
+ * browser that hands back something other than a JPEG.
+ */
+export function browserJpeg(quality: number): PictureEncoder | null {
+  if (typeof createImageBitmap !== "function" || (typeof OffscreenCanvas === "undefined" && typeof document === "undefined")) return null;
+  return async ({ base64, type }) => {
+    const bitmap = await createImageBitmap(new Blob([fromBase64(base64) as BlobPart], { type }));
+    try {
+      const { width, height } = bitmap;
+      const canvas = canvasOf(width, height);
+      const ctx = canvas?.getContext("2d", { willReadFrequently: true }) as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+      if (!canvas || !ctx) return null;
+      ctx.drawImage(bitmap, 0, 0);
+      const pixels = ctx.getImageData(0, 0, width, height).data;
+      for (let i = 3; i < pixels.length; i += 4) if (pixels[i] !== 255) return null;
+      const blob = await jpegOf(canvas, quality);
+      if (!blob || blob.type !== "image/jpeg") return null;
+      return { base64: toBase64(new Uint8Array(await blob.arrayBuffer())), type: "image/jpeg" };
+    } finally {
+      bitmap.close();
+    }
+  };
+}