@lightworkai.official/debug-capture 0.11.0 → 0.12.0

package/src/capture/replay.ts

@@ -0,0 +1,167 @@
+/**
+ * The last minute of the page, kept in memory for the moment someone reports.
+ *
+ * rrweb records the DOM: one full snapshot, then every mutation, scroll,
+ * click and (masked) keystroke after it. A replay can only start at a
+ * snapshot, so the recorder is asked for a fresh one every half-window and
+ * the events are kept in WINDOWS, each beginning with its snapshot. A report
+ * takes whole windows from the newest back until the configured length is
+ * covered — which is why it always plays from the start and why it may run
+ * up to half as long again as asked.
+ *
+ * Three windows are retained, no more: the ones a report can use, and the one
+ * being filled. A page that mutates without pause would otherwise grow the
+ * buffer for as long as the tab stayed open. `checkoutEveryNth` is the second
+ * guard — a mutation storm cuts a new window early, and the old one ages out
+ * instead of ballooning.
+ *
+ * The recorder is loaded on demand and after the page has settled. It is a
+ * quarter of this package's weight again, and a host that did not ask for a
+ * replay never downloads it.
+ */
+import { replayOptions } from "../config";
+import type { ReplayCapture, ReplayEvent } from "../types";
+
+/** rrweb `EventType.Meta` — the first event of every full snapshot. */
+const META = 4;
+/** Windows kept: two complete, one filling. */
+const KEEP = 3;
+/** Cut a window early past this many events, whatever the clock says. */
+const MAX_EVENTS_PER_WINDOW = 4000;
+/** Our own dialog and toasts are never in the picture. */
+const OWN_UI = "[data-debug-reporter]";
+
+type Recorder = (options: Record<string, unknown>) => (() => void) | undefined;
+export interface RecorderModule {
+  record: Recorder;
+}
+
+/**
+ * Where the recorder comes from. A dynamic import of a declared dependency
+ * by default, which a host's bundler turns into a chunk of its own; the
+ * script-tag build has no bundler and points this at a file beside itself.
+ */
+let loadRecorder: () => Promise<RecorderModule> = () => import("@rrweb/record") as unknown as Promise<RecorderModule>;
+export function setRecorderLoader(load: () => Promise<RecorderModule>): void {
+  loadRecorder = load;
+}
+
+let windows: ReplayEvent[][] = [];
+let stop: (() => void) | null = null;
+let starting = false;
+
+/**
+ * Start recording, once the host asked for it and the page has had a moment.
+ *
+ * Idle-scheduled: the first thing the recorder does is walk the whole
+ * document, and doing that in the middle of the host's own start-up is how a
+ * widget gets blamed for a slow first paint.
+ */
+export function installReplay(): void {
+  if (typeof window === "undefined" || stop || starting) return;
+  const options = replayOptions();
+  if (!options) return;
+  starting = true;
+  const begin = () => void start(options);
+  if ("requestIdleCallback" in window) {
+    (window as Window & { requestIdleCallback: (cb: () => void, o?: { timeout: number }) => number }).requestIdleCallback(
+      begin,
+      { timeout: 3000 },
+    );
+  } else {
+    setTimeout(begin, 1000);
+  }
+}
+
+async function start(options: NonNullable<ReturnType<typeof replayOptions>>): Promise<void> {
+  let record: Recorder;
+  try {
+    record = (await loadRecorder()).record;
+  } catch (error) {
+    starting = false;
+    console.warn("[debug-capture] session replay could not start:", error);
+    return;
+  }
+  if (stop) return;
+  try {
+    stop =
+      record({
+        emit: (event: ReplayEvent) => push(event),
+        checkoutEveryNms: Math.max(1000, (options.seconds * 1000) / 2),
+        checkoutEveryNth: MAX_EVENTS_PER_WINDOW,
+        // Every value typed into anything, masked before it is recorded. The
+        // player shows the field being filled with asterisks.
+        maskAllInputs: true,
+        ...(options.maskText ? { maskTextSelector: "*" } : {}),
+        blockSelector: `${options.blockSelector}, ${OWN_UI}`,
+        // Scripts, comments and <meta> tags are weight the player never uses.
+        slimDOMOptions: "all",
+        // Reads the page's stylesheets in, so a replay looks like the page and
+        // not like an unstyled document — the desk cannot reach the host's CSS.
+        inlineStylesheet: true,
+        sampling: {
+          // A mouse trail every 50 ms is enough to see where they went.
+          mousemove: 50,
+          scroll: 150,
+          media: 800,
+          // The final value of a field, not every keystroke — the value is
+          // masked anyway, and a keystroke each is most of a form's events.
+          input: "last",
+        },
+        // Charts and PDFs render to canvas; a frame each is megabytes and the
+        // ticket does not need the chart, it needs what was pressed next to it.
+        recordCanvas: false,
+        errorHandler: () => true,
+      }) ?? null;
+  } catch (error) {
+    console.warn("[debug-capture] session replay could not start:", error);
+  } finally {
+    starting = false;
+  }
+}
+
+function push(event: ReplayEvent): void {
+  // A Meta event opens every full snapshot — the first, and each checkout.
+  if (event.type === META || windows.length === 0) {
+    windows.push([]);
+    if (windows.length > KEEP) windows = windows.slice(-KEEP);
+  }
+  windows[windows.length - 1]!.push(event);
+}
+
+/**
+ * The events a report should carry: whole windows, newest first, until the
+ * configured length is covered — or everything, early in a session.
+ */
+export function takeReplay(now = Date.now()): ReplayCapture | null {
+  const options = replayOptions();
+  if (!options || !windows.length) return null;
+  const cutoff = now - options.seconds * 1000;
+  let first = windows.length - 1;
+  while (first > 0 && (windows[first]![0]?.timestamp ?? now) > cutoff) first -= 1;
+  // Copied: the buffers stay live, and the report is being written while the
+  // page keeps changing underneath it.
+  const events = windows.slice(first).flat();
+  const startedAt = events[0]?.timestamp;
+  const endedAt = events[events.length - 1]?.timestamp;
+  if (startedAt === undefined || endedAt === undefined) return null;
+  return {
+    events,
+    startedAt: new Date(startedAt).toISOString(),
+    endedAt: new Date(endedAt).toISOString(),
+    durationMs: Math.max(0, endedAt - startedAt),
+  };
+}
+
+export function isReplayRecording(): boolean {
+  return stop !== null;
+}
+
+export function stopReplay(): void {
+  stop?.();
+  stop = null;
+  windows = [];
+}
+
+/** Test seam: feed events as the recorder would. */
+export const _replayInternals = { push, reset: () => void (windows = []) };

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,23 @@ export async function submitBundle(title: string, bundle: DebugBundle): Promise<
   }
   attachments.push(bundleAttachment(trimmed));
 
+  /*
+   * The replay, when there is one, as the third file. `replay: null` on a
+   * bundle from a recording host is the reporter's choice — the dialog offers
+   * a box to leave it out — and the desk is told so, rather than left to
+   * wonder why this report has none.
+   */
+  let replay: ReplaySummary | undefined;
+  const recording = replayOptions();
+  if (recording) {
+    if (trimmed.replay === null) replay = { omitted: "declined" };
+    else {
+      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 +156,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?: "declined" | "too-large" | "empty";
+}
+
 export interface DebugBundle {
   context: DebugContext;
   reason: DebugReason;
@@ -165,5 +209,13 @@ 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: nothing was recorded. `null`: there was one and the reporter
+   * chose to leave it out — the desk is told which.
+   */
+  replay?: ReplayCapture | null;
   meta: { generatedBy: string; schemaVersion: number };
 }

package/src/ui/element.ts

@@ -197,6 +197,15 @@ function createReporterClass(): CustomElementConstructor {
         meta.append(row);
       }
 
+      /*
+       * The replay is offered, not imposed. A recording of the screen is the
+       * most personal thing in a report, and the person filing it decides
+       * whether it goes — ticked by default because it is why the host turned
+       * it on, with one line saying what it is and is not.
+       */
+      const replayRow = bundle.replay ? this.replayConsent(t, bundle.replay.durationMs) : null;
+      if (replayRow) meta.append(replayRow.row);
+
       const status = el("p", "status", "");
       const submitBtn = button(t.submit, "primary");
       submitBtn.disabled = true;
@@ -222,6 +231,8 @@ function createReporterClass(): CustomElementConstructor {
           const filed = await submitBundle(summary.value.trim(), {
             ...bundle,
             note: detail.value,
+            // Null, not absent: "left out on purpose" is worth telling the desk.
+            ...(replayRow && !replayRow.box.checked ? { replay: null } : {}),
             // Take the annotated image, not the raw capture — the drawing IS the
             // report for most people.
             screenshotDataUrl: this.annotator?.hasShapes()
@@ -257,6 +268,19 @@ function createReporterClass(): CustomElementConstructor {
       summary.focus();
     }
 
+    private replayConsent(t: Strings, durationMs: number): { row: HTMLElement; box: HTMLInputElement } {
+      const row = el("label", "check");
+      const box = document.createElement("input");
+      box.type = "checkbox";
+      box.checked = true;
+      const text = el("span", "", t.replayAttach.replace("{seconds}", String(Math.round(durationMs / 1000))));
+      const what = el("small", "hint", t.replayWhat);
+      const words = el("span", "grow");
+      words.append(text, what);
+      row.append(box, words);
+      return { row, box };
+    }
+
     private screenshotSection(t: Strings, dataUrl: string): HTMLElement[] {
       const label = labelFor(t.annotateHint);
       const tools = el("div", "tools");