@lightworkai.official/debug-capture 0.19.8 → 0.19.9

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();
+    }
+  };
+}

package/src/submit.ts

@@ -110,7 +110,7 @@ export async function submitBundle(title: string, bundle: DebugBundle): Promise<
   let replay: ReplaySummary | undefined;
   const recording = replayOptions();
   if (recording) {
-    const packed = await packReplay(trimmed.replay, recording.maxBytes);
+    const packed = await packReplay(trimmed.replay, recording.maxBytes, { quality: recording.canvas?.quality });
     replay = packed.summary;
     if ("dataUri" in packed) attachments.push({ dataUri: packed.dataUri, filename: packed.filename });
   }

package/src/types.ts

@@ -188,7 +188,7 @@ export interface ReplayCapture {
  * attachment loads — or say why there is none.
  */
 export interface ReplaySummary {
-  /** Whole seconds covered, when one was attached. */
+  /** Whole seconds covered by what was attached (or, with `omitted`, by what was recorded). */
   seconds?: number;
   events?: number;
   startedAt?: string;
@@ -196,8 +196,20 @@ export interface ReplaySummary {
   /** Size of the attachment as sent, and whether it is gzip. */
   bytes?: number;
   compressed?: boolean;
-  /** The canvas frames were left out to fit under the size cap. */
+  /*
+   * What was given up to fit under the size cap (replayPack), each present
+   * only when it happened.
+   */
+  /** Canvas pictures left out: the canvases play blank. */
   canvasDropped?: boolean;
+  /** Large pictures embedded in the page (a `data:` image, an inlined font) left out. */
+  picturesDropped?: boolean;
+  /** Long text and styles shortened — only when not even one picture of the page fitted otherwise. */
+  simplified?: boolean;
+  /** Only part of the recording went: how long the whole was. `seconds` is what was sent. */
+  recordedSeconds?: number;
+  /** The part sent stops this many seconds before the report was made. */
+  endsEarlySeconds?: number;
   /** Present when the host records but this report carries no replay. */
   omitted?: "too-large" | "empty";
 }