@lightworkai.official/debug-capture 0.11.2 → 0.12.1

package/src/capture/replayRedact.ts

@@ -0,0 +1,69 @@
+/**
+ * The widget's URL policy, applied to the replay.
+ *
+ * rrweb records the page as it is, and a page is full of URLs: every link's
+ * href, every image's src, the address bar in the Meta event. The network
+ * log and the action trail already mask the query keys that carry secrets
+ * (`redactUrl` — tokens, signatures, one-time codes); a replay that kept
+ * them would undo that in the one file nobody reads by eye.
+ *
+ * Every URL-bearing attribute in the full snapshot and in every mutation is
+ * passed through the same function. Text is untouched: what the page SAYS
+ * is what a replay is for, and a host whose text is itself the secret has
+ * `maskText`.
+ */
+import { redactUrl } from "./redact";
+import type { ReplayEvent } from "../types";
+
+const META = 4;
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+const MUTATION = 0;
+
+const URL_ATTRIBUTES = new Set(["href", "src", "action", "formaction", "xlink:href", "data", "poster", "srcset"]);
+
+interface SerializedNode {
+  attributes?: Record<string, unknown>;
+  childNodes?: SerializedNode[];
+}
+
+function redactAttributes(attributes: Record<string, unknown> | undefined): void {
+  if (!attributes) return;
+  for (const key of Object.keys(attributes)) {
+    const value = attributes[key];
+    if (typeof value !== "string" || !URL_ATTRIBUTES.has(key) || !value.includes("?")) continue;
+    attributes[key] = redactUrl(value);
+  }
+}
+
+function walk(node: SerializedNode | undefined): void {
+  if (!node) return;
+  redactAttributes(node.attributes);
+  for (const child of node.childNodes ?? []) walk(child);
+}
+
+/**
+ * In place, on a copy: the recorder's buffers are live and a report may be
+ * filed again, so the events handed in are cloned before anything is masked.
+ */
+export function redactReplay(events: readonly ReplayEvent[]): ReplayEvent[] {
+  // A JSON round trip rather than structuredClone: the events are JSON by
+  // construction, and this is the one clone every browser the widget runs in
+  // can make.
+  const out: ReplayEvent[] = JSON.parse(JSON.stringify(events)) as ReplayEvent[];
+  for (const event of out) {
+    const data = event.data as Record<string, unknown> | null;
+    if (!data || typeof data !== "object") continue;
+    if (event.type === META && typeof data.href === "string") {
+      data.href = redactUrl(data.href);
+    } else if (event.type === FULL_SNAPSHOT) {
+      walk(data.node as SerializedNode | undefined);
+    } else if (event.type === INCREMENTAL && data.source === MUTATION) {
+      for (const add of (data.adds as Array<{ node?: SerializedNode }> | undefined) ?? []) walk(add.node);
+      for (const change of (data.attributes as Array<{ attributes?: Record<string, unknown> }> | undefined) ?? []) {
+        redactAttributes(change.attributes);
+      }
+    }
+  }
+  return out;
+}

package/src/config.ts

@@ -114,6 +114,27 @@ export interface DebugCaptureConfig {
   capture?: CaptureOptions;
   redact?: RedactOptions;
 
+  /**
+   * Keep a replay of the last minute and attach it to a report.
+   *
+   * Off unless set. What is kept is the DOM, not pixels — rrweb records a
+   * snapshot of the page and every change to it after that, and the desk plays
+   * it back as the page the person was looking at, with their clicks, scrolls
+   * and typing (masked) on top. It is the difference between "I pressed save
+   * and it broke" and watching them press save and it break.
+   *
+   * It is also the screen, which is why it is opt-in and why the defaults hide
+   * everything they can: every input's value is masked before it is recorded,
+   * and anything under `blockSelector` is recorded as a grey box of the same
+   * size. Mark the parts of your app that must never leave the browser —
+   * document viewers, a citizen's record — with `data-lw-private`, and set
+   * `maskText` if the text on your screens is itself the secret.
+   *
+   *   replay: true                       // 60 s, masked inputs
+   *   replay: { seconds: 90, maskText: true }
+   */
+  replay?: boolean | ReplayOptions;
+
   /**
    * A DOM-rendering screenshot fallback, for browsers without the Screen
    * Capture API. Supplied by the host so this package never names a dependency
@@ -181,6 +202,25 @@ export interface CaptureOptions {
   overlaySelectors?: string[];
 }
 
+export interface ReplayOptions {
+  /** How much history to send with a report. Default 60. */
+  seconds?: number;
+  /**
+   * Elements never recorded — drawn as a box of their size, contents and all
+   * changes inside them dropped. Default `[data-lw-private]`; the widget's own
+   * dialog and toasts are always excluded.
+   */
+  blockSelector?: string;
+  /** Mask every piece of text too, not only what is typed. Default false. */
+  maskText?: boolean;
+  /**
+   * The most a replay may weigh once compressed. A report still files when its
+   * replay is over this; the replay is left out and the desk is told why.
+   * Default 4 MB, under the host's 5 MB per-file cap.
+   */
+  maxBytes?: number;
+}
+
 export interface RedactOptions {
   /** Extra header names to mask. Matched case-insensitively, as whole names. */
   headers?: string[];
@@ -301,6 +341,28 @@ export function overlaySelectors(): string[] {
   return current?.capture?.overlaySelectors ?? [];
 }
 
+const REPLAY_DEFAULTS: Required<ReplayOptions> = {
+  seconds: 60,
+  blockSelector: "[data-lw-private]",
+  maskText: false,
+  maxBytes: 4_000_000,
+};
+
+/** The replay settings, filled in — or null when the host did not ask for one. */
+export function replayOptions(): Required<ReplayOptions> | null {
+  const set = current?.replay;
+  if (!set) return null;
+  const given = set === true ? {} : set;
+  const seconds = typeof given.seconds === "number" && given.seconds > 0 ? given.seconds : REPLAY_DEFAULTS.seconds;
+  const maxBytes = typeof given.maxBytes === "number" && given.maxBytes > 0 ? given.maxBytes : REPLAY_DEFAULTS.maxBytes;
+  return {
+    seconds,
+    blockSelector: given.blockSelector?.trim() || REPLAY_DEFAULTS.blockSelector,
+    maskText: given.maskText === true,
+    maxBytes,
+  };
+}
+
 /**
  * Whether a response body from this URL may be stored.
  *

package/src/embed.ts

@@ -8,16 +8,31 @@
  *           data-app-name="ระบบสารบรรณ"
  *           data-app-version="1.4.2"
  *           data-environment="production"
- *           data-modules='{"/saraban":"งานสารบรรณ","/asset":"งานพัสดุ"}'></script>
+ *           data-modules='{"/saraban":"งานสารบรรณ","/asset":"งานพัสดุ"}'
+ *           data-replay="60"></script>
+ *
+ * `data-replay` records the last N seconds of the page for a report (see
+ * `replay` in config.ts). The recorder is `rrweb-record.mjs`, shipped beside
+ * this file and fetched only when asked for — keep the two together.
  */
 import { configureDebugCapture } from "./config";
 import { moduleResolver, type ModuleMap } from "./modules";
 import { installDebugCapture } from "./install";
 import { launch } from "./reporter";
+import { setRecorderLoader } from "./capture/replay";
 
 const script = document.currentScript as HTMLScriptElement | null;
 const data = script?.dataset ?? {};
 
+/*
+ * Beside this script, wherever the host put it. A bare `import("@rrweb/record")`
+ * means nothing to a browser without a bundler, and inlining the recorder
+ * here would nearly triple this file for every host, most of whom never turn
+ * the replay on.
+ */
+const RECORDER_FILE = "rrweb-record.mjs";
+setRecorderLoader(() => import(/* @vite-ignore */ new URL(RECORDER_FILE, script?.src ?? location.href).href));
+
 /**
  * Bad JSON becomes an empty map, not an exception.
  *
@@ -49,6 +64,7 @@ if (data.host && data.realmKey) {
     // A declared map, because a data- attribute carries text and not a function.
     module: moduleResolver(parseModules(data.modules)),
     locale: data.locale === "en" ? "en" : "th",
+    ...(data.replay !== undefined ? { replay: { seconds: Number(data.replay) || undefined } } : {}),
   });
   installDebugCapture();
 }

package/src/index.ts

@@ -12,7 +12,7 @@
 export { configureDebugCapture, isConfigured, getConfig, appInfo } from "./config";
 export { moduleResolver } from "./modules";
 export type { ModuleMap } from "./modules";
-export type { DebugCaptureConfig, CaptureOptions, RedactOptions, ToastNotice } from "./config";
+export type { DebugCaptureConfig, CaptureOptions, RedactOptions, ReplayOptions, ToastNotice } from "./config";
 
 export { installDebugCapture } from "./install";
 export type { InstallOptions } from "./install";
@@ -29,6 +29,8 @@ export { captureScreen } from "./screenshot";
 export { getNetworkLog } from "./capture/networkBuffer";
 export { getConsoleLog } from "./capture/consoleBuffer";
 export { getActionTrail, actionCountSuffix } from "./capture/actionTrail";
+export { takeReplay, isReplayRecording, stopReplay } from "./capture/replay";
+export { packReplay, REPLAY_FILENAME } from "./replayPack";
 export { correlateActionTrail, isQuietStep, isFailedRequest, requestPath, formatDuration } from "./capture/stepCorrelation";
 export type { StepActivity } from "./capture/stepCorrelation";
 export { redactBody, redactHeaders, redactLabel, redactUrl, REDACTED } from "./capture/redact";

package/src/install.ts

@@ -7,6 +7,7 @@ import { installActionTrail } from "./capture/actionTrail";
 import { installConsoleCapture } from "./capture/consoleBuffer";
 import { installCrashWatcher } from "./capture/crashWatcher";
 import { installNetworkCapture } from "./capture/networkBuffer";
+import { installReplay } from "./capture/replay";
 import { getConfig, isConfigured } from "./config";
 import { launch, onCrash } from "./reporter";
 import { strings } from "./ui/strings";
@@ -34,6 +35,8 @@ export function installDebugCapture(options: InstallOptions = {}): void {
   installConsoleCapture();
   installActionTrail();
   installCrashWatcher();
+  // Only when asked for, and only once the page has settled — see the module.
+  installReplay();
 
   if (options.ui === false) return;
 

package/src/replayPack.ts

@@ -0,0 +1,66 @@
+/**
+ * A replay, made into the attachment that carries it.
+ *
+ * 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.
+ *
+ * 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
+ * the JSON bundle is opened by whoever reads the network log. A megabyte of
+ * DOM belongs in neither.
+ */
+import { toBase64 } from "./base64";
+import { redactReplay } from "./capture/replayRedact";
+import type { ReplayCapture, ReplaySummary } from "./types";
+
+/** The name the desk looks for. Changing it here changes it nowhere else. */
+export const REPLAY_FILENAME = "session-replay.json.gz";
+const PLAIN_FILENAME = "session-replay.json";
+
+export interface PackedReplay {
+  dataUri: string;
+  filename: string;
+  summary: ReplaySummary;
+}
+
+/** 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);
+}
+
+async function gzip(bytes: Uint8Array): Promise<Uint8Array | null> {
+  if (typeof CompressionStream === "undefined") return null;
+  try {
+    const stream = new Blob([bytes as BlobPart]).stream().pipeThrough(new CompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+export async function packReplay(replay: ReplayCapture | null | undefined, maxBytes: number): 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.
+  const plain = new TextEncoder().encode(JSON.stringify({ events: redactReplay(replay.events) }));
+  const zipped = await gzip(plain);
+  const bytes = zipped ?? plain;
+  if (bytes.byteLength > maxBytes) return { summary: { ...base, bytes: bytes.byteLength, omitted: "too-large" } };
+  const compressed = zipped !== null;
+  return {
+    dataUri: `data:${compressed ? "application/gzip" : "application/json"};base64,${toBase64(bytes)}`,
+    filename: compressed ? REPLAY_FILENAME : PLAIN_FILENAME,
+    summary: { ...base, bytes: bytes.byteLength, compressed },
+  };
+}

package/src/styles.css

@@ -147,7 +147,7 @@
    reasonable because the full size is one click away, and `zoom-in` says so
    before you try. Matches the app's own thread. */
 .lw-body img {
-  margin: 4px 0; max-height: 160px; max-width: 100%; width: auto; height: auto;
+  margin: 4px 0; max-height: 128px; max-width: 100%; width: auto; height: auto;
   object-fit: contain; border: 1px solid var(--lw-border); border-radius: 8px;
   cursor: zoom-in;
 }

package/src/submit.ts

@@ -7,10 +7,12 @@
  * cookie, and nothing here that a reader of the bundle could not already see.
  */
 import { compressScreenshot } from "./screenshot";
-import { appInfo, getConfig } from "./config";
+import { appInfo, getConfig, replayOptions } from "./config";
 import { errorSignature } from "./signature";
 import { trimToBudget, BUNDLE_BUDGET_BYTES } from "./budget";
-import type { DebugBundle } from "./types";
+import { toBase64 } from "./base64";
+import { packReplay } from "./replayPack";
+import type { DebugBundle, ReplaySummary } from "./types";
 
 export interface FiledTicket {
   id: string;
@@ -18,26 +20,7 @@ export interface FiledTicket {
   status: string;
 }
 
-/**
- * Base64 for a payload of any size.
- *
- * This was `btoa(String.fromCharCode(...bytes))`, which spreads every byte into
- * the argument list — and an argument list has a hard limit. It worked on the
- * tiny bundles a test produces and threw "Maximum call stack size exceeded" on
- * a real one, at the last possible moment: the user has written the report,
- * drawn on the screenshot, and pressed send.
- *
- * Chunked, so the argument count is bounded no matter how large the bundle is.
- */
-const CHUNK = 0x8000;
-
-export function toBase64(bytes: Uint8Array): string {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i += CHUNK) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
-  }
-  return btoa(binary);
-}
+export { toBase64 } from "./base64";
 
 /**
  * A data URI for the JSON bundle, so the bulk lands in object storage.
@@ -51,7 +34,9 @@ export function toBase64(bytes: Uint8Array): string {
  * (`budget.ts`), which is what made the duplication invisible.
  */
 export function bundleAttachment(bundle: DebugBundle): { dataUri: string; filename: string } {
-  const { screenshotDataUrl: _sentSeparately, ...rest } = bundle;
+  // The replay too: it is the largest thing in a report by an order of
+  // magnitude, and it has its own file (replayPack.ts).
+  const { screenshotDataUrl: _sentSeparately, replay: _alsoSeparately, ...rest } = bundle;
   // btoa is latin1-only and a bundle is full of Thai. Encode to bytes first.
   const base64 = toBase64(new TextEncoder().encode(JSON.stringify(rest)));
   return { dataUri: `data:application/json;base64,${base64}`, filename: "debug-bundle.json" };
@@ -90,6 +75,20 @@ export async function submitBundle(title: string, bundle: DebugBundle): Promise<
   }
   attachments.push(bundleAttachment(trimmed));
 
+  /*
+   * The replay, when there is one, as the third file. Taken the way the
+   * network and console logs are — it is the support team's debug log, not
+   * a question put to the reporter — and when a recording host has none to
+   * send, the desk is told why rather than left to wonder.
+   */
+  let replay: ReplaySummary | undefined;
+  const recording = replayOptions();
+  if (recording) {
+    const packed = await packReplay(trimmed.replay, recording.maxBytes);
+    replay = packed.summary;
+    if ("dataUri" in packed) attachments.push({ dataUri: packed.dataUri, filename: packed.filename });
+  }
+
   /*
    * `context` is a jsonb column on the ticket row, read back by every query that
    * returns the ticket — so it gets the SUMMARY, not the bundle. The full thing
@@ -154,6 +153,7 @@ export async function submitBundle(title: string, bundle: DebugBundle): Promise<
         actions: trimmed.actionTrail.length,
       },
       screenshotMethod: trimmed.screenshotMethod,
+      ...(replay ? { replay } : {}),
     },
     attachments,
   };

package/src/types.ts

@@ -154,6 +154,50 @@ export interface DebugContext {
 
 export type ScreenshotMethod = "display-media" | "html-to-image" | "none" | "cancelled";
 
+/**
+ * One rrweb event. Typed by shape rather than imported from `@rrweb/types`,
+ * so a host that reads a bundle needs nothing of rrweb's to do it — the
+ * recorder is loaded on demand and its types stay its own.
+ */
+export interface ReplayEvent {
+  type: number;
+  timestamp: number;
+  data: unknown;
+}
+
+/**
+ * The last stretch of the session, as the desk will play it back.
+ *
+ * Always begins with a full snapshot of the page: rrweb can only replay from
+ * one, so the window is cut at a checkpoint and never mid-stream. That is why
+ * `durationMs` is at least the configured length and can be up to half as
+ * much again.
+ */
+export interface ReplayCapture {
+  events: ReplayEvent[];
+  startedAt: string;
+  endedAt: string;
+  durationMs: number;
+}
+
+/**
+ * What the ticket says about its replay, without the replay: the summary that
+ * travels in `context` and lets the desk label the play button before the
+ * attachment loads — or say why there is none.
+ */
+export interface ReplaySummary {
+  /** Whole seconds covered, when one was attached. */
+  seconds?: number;
+  events?: number;
+  startedAt?: string;
+  endedAt?: string;
+  /** Size of the attachment as sent, and whether it is gzip. */
+  bytes?: number;
+  compressed?: boolean;
+  /** Present when the host records but this report carries no replay. */
+  omitted?: "too-large" | "empty";
+}
+
 export interface DebugBundle {
   context: DebugContext;
   reason: DebugReason;
@@ -165,5 +209,11 @@ export interface DebugBundle {
   /** PNG data URL, or null if capture failed / was skipped. */
   screenshotDataUrl: string | null;
   screenshotMethod: ScreenshotMethod;
+  /**
+   * The session replay, when the host records one. Its own attachment on the
+   * way out, like the screenshot — never inside the JSON bundle. Absent (or
+   * null) when nothing was recorded.
+   */
+  replay?: ReplayCapture | null;
   meta: { generatedBy: string; schemaVersion: number };
 }

package/src/ui/element.ts

@@ -183,9 +183,17 @@ function createReporterClass(): CustomElementConstructor {
         // environment became optional, and it was telling the person filing the
         // report something only the person reading it needs — both still travel
         // with the bundle.
+        //
+        // The replay counts as one more thing captured, listed with the rest.
+        // It is the support team's debug log, taken the way the network and
+        // console logs are — not a choice put to the reporter. There was a
+        // tick box here once; the platform owner's call was that a report
+        // should always carry what makes it reproducible.
         [
           t.captured,
-          `${bundle.network.length} network · ${bundle.console.length} console · ${bundle.actionTrail.length} actions`,
+          `${bundle.network.length} network · ${bundle.console.length} console · ${bundle.actionTrail.length} actions${
+            bundle.replay ? ` · ${t.replay} ${Math.round(bundle.replay.durationMs / 1000)}s` : ""
+          }`,
         ],
       ] as [string, string][]) {
         const row = document.createElement("div");

package/src/ui/strings.ts

@@ -38,6 +38,8 @@ export interface Strings {
   captured: string;
   reporter: string;
   page: string;
+  /** In the captured row: "… · replay 14s". */
+  replay: string;
   /** The hand-off dialog, shown before leaving for the support portal. */
   handoffTitle: string;
   handoffBody: string;
@@ -80,6 +82,7 @@ const th: Strings = {
   captured: "เก็บข้อมูลแล้ว",
   reporter: "ผู้แจ้ง",
   page: "หน้า",
+  replay: "บันทึกหน้าจอ",
   handoffTitle: "กำลังพาไปที่ระบบแจ้งปัญหา",
   handoffBody: "ระบบจะลงชื่อเข้าใช้ให้อัตโนมัติ เพื่อดูเรื่องที่คุณแจ้งไว้",
   handoffGo: "ไปเลย",
@@ -121,6 +124,7 @@ const en: Strings = {
   captured: "Captured",
   reporter: "Reporter",
   page: "Page",
+  replay: "replay",
   handoffTitle: "Opening the support portal",
   handoffBody: "You will be signed in automatically to see what you reported",
   handoffGo: "Go now",