@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/record.ts

@@ -0,0 +1,402 @@
+import { pageBackground } from "./page-background.js";
+
+/** A recording stops itself after this long. */
+export const RECORD_MAX_MS = 75_000;
+const MAX_BYTES = 9 * 1024 * 1024;
+const BITRATE = 4_000_000;
+const AUDIO_BITRATE = 64_000;
+const FRAME_RATE = 30;
+
+export const FRAME_WIDTH = 1920;
+export const FRAME_HEIGHT = 1080;
+
+const MIME_TYPES = ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm", "video/mp4"];
+/** With the mic: Opus in WebM, or whatever audio Safari's MP4 recorder picks. */
+const MIME_TYPES_WITH_SOUND = [
+  "video/webm;codecs=vp9,opus",
+  "video/webm;codecs=vp8,opus",
+  "video/webm",
+  "video/mp4",
+];
+
+export function recordingMime(sound = false) {
+  if (typeof MediaRecorder === "undefined") return null;
+  return (
+    (sound ? MIME_TYPES_WITH_SOUND : MIME_TYPES).find((type) =>
+      MediaRecorder.isTypeSupported(type),
+    ) ?? null
+  );
+}
+
+/**
+ * The mic for a recording's sound, so someone can explain what they show. Null when the person, the browser
+ * or the host page's policy refuses it: the recording then carries on without sound.
+ */
+async function openMicrophone(): Promise<MediaStreamTrack | null> {
+  if (!navigator.mediaDevices?.getUserMedia) return null;
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        channelCount: 1,
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+      },
+    });
+    return stream.getAudioTracks()[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatClock(ms: number) {
+  const total = Math.max(0, Math.round(ms / 1000));
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
+}
+
+type FeaturePolicy = { allowsFeature(feature: string): boolean };
+
+/** The document's capture policy. Chrome still exposes this as `featurePolicy`. */
+export function pageCapturePolicy(
+  doc:
+    | { permissionsPolicy?: FeaturePolicy | null; featurePolicy?: FeaturePolicy | null }
+    | null
+    | undefined,
+) {
+  return doc?.permissionsPolicy ?? doc?.featurePolicy ?? null;
+}
+
+/** True when this document may call getDisplayMedia. A missing policy counts as allowed. */
+export function displayCaptureAllowed(policy: FeaturePolicy | null | undefined) {
+  if (!policy) return true;
+  try {
+    return policy.allowsFeature("display-capture");
+  } catch {
+    return true;
+  }
+}
+
+/** Fit a source rectangle inside a 1920×1080 frame, scaling by at most 2. */
+export function fitFrame(sourceWidth: number, sourceHeight: number) {
+  const width = Math.max(1, sourceWidth);
+  const height = Math.max(1, sourceHeight);
+  const scale = Math.min(2, FRAME_WIDTH / width, FRAME_HEIGHT / height);
+  const drawnWidth = Math.round(width * scale);
+  const drawnHeight = Math.round(height * scale);
+  return {
+    scale,
+    x: Math.round((FRAME_WIDTH - drawnWidth) / 2),
+    y: Math.round((FRAME_HEIGHT - drawnHeight) / 2),
+    width: drawnWidth,
+    height: drawnHeight,
+  };
+}
+
+export type TabTake = {
+  stop: () => void;
+  cancel: () => void;
+  finished: Promise<Blob | null>;
+  /** The mic in the take; mute it with `enabled`. Null when sound was off or the mic was refused. */
+  microphone: MediaStreamTrack | null;
+};
+
+/** Mute or unmute the mic in this take. Returns whether it is now on. */
+export function toggleMicrophone(microphone: MediaStreamTrack): boolean {
+  microphone.enabled = !microphone.enabled;
+  return microphone.enabled;
+}
+
+export type RecordOptions = {
+  /** Record the mic too. */
+  sound: boolean;
+  /**
+   * Every second of the recording as it lands, in order; the first chunk carries the file's header, so the
+   * chunks so far always make a playable file. Lets a take be kept somewhere safe while it runs.
+   */
+  onChunk?: (chunk: Blob, index: number, mime: string) => void;
+};
+
+function recordStream(
+  video: MediaStream,
+  mime: string,
+  microphone: MediaStreamTrack | null,
+  onEnd?: () => void,
+  onChunk?: RecordOptions["onChunk"],
+): TabTake {
+  const stream = microphone ? new MediaStream([...video.getVideoTracks(), microphone]) : video;
+  const recorder = new MediaRecorder(stream, {
+    mimeType: mime,
+    videoBitsPerSecond: BITRATE,
+    ...(microphone ? { audioBitsPerSecond: AUDIO_BITRATE } : {}),
+  });
+  const chunks: Blob[] = [];
+  let bytes = 0;
+  let settled = false;
+  let mode: "stop" | "cancel" = "cancel";
+  let resolve: (blob: Blob | null) => void = () => {};
+  const finished = new Promise<Blob | null>((done) => {
+    resolve = done;
+  });
+  const finish = () => {
+    if (settled) return;
+    settled = true;
+    onEnd?.();
+    window.clearTimeout(limit);
+    for (const track of stream.getTracks()) track.stop();
+    if (mode === "cancel" || bytes === 0) {
+      resolve(null);
+      return;
+    }
+    resolve(new Blob(chunks, { type: mime.split(";")[0] }));
+  };
+  recorder.ondataavailable = (event) => {
+    if (!event.data.size || settled) return;
+    chunks.push(event.data);
+    bytes += event.data.size;
+    onChunk?.(event.data, chunks.length - 1, mime.split(";")[0]!);
+    if (bytes >= MAX_BYTES && recorder.state === "recording") {
+      mode = "stop";
+      recorder.stop();
+    }
+  };
+  recorder.onstop = finish;
+  stream.getVideoTracks()[0]?.addEventListener("ended", () => {
+    if (settled) return;
+    mode = "stop";
+    if (recorder.state === "recording") recorder.stop();
+    else finish();
+  });
+  const limit = window.setTimeout(() => {
+    if (recorder.state !== "recording") return;
+    mode = "stop";
+    recorder.stop();
+  }, RECORD_MAX_MS);
+  recorder.start(1000);
+  return {
+    stop: () => {
+      mode = "stop";
+      if (recorder.state === "recording") recorder.stop();
+      else finish();
+    },
+    cancel: () => {
+      mode = "cancel";
+      if (recorder.state === "recording") recorder.stop();
+      else finish();
+    },
+    finished,
+    microphone,
+  };
+}
+
+function frameCanvas() {
+  const canvas = document.createElement("canvas");
+  canvas.width = FRAME_WIDTH;
+  canvas.height = FRAME_HEIGHT;
+  const ctx = canvas.getContext("2d", { alpha: false });
+  if (!ctx || typeof canvas.captureStream !== "function")
+    throw new Error("Recording isn’t available in this browser.");
+  ctx.imageSmoothingEnabled = true;
+  ctx.imageSmoothingQuality = "high";
+  return { canvas, ctx };
+}
+
+function paintFrame(
+  ctx: CanvasRenderingContext2D,
+  source: CanvasImageSource,
+  sourceWidth: number,
+  sourceHeight: number,
+  background: string,
+) {
+  const fit = fitFrame(sourceWidth, sourceHeight);
+  ctx.fillStyle = background;
+  ctx.fillRect(0, 0, FRAME_WIDTH, FRAME_HEIGHT);
+  ctx.drawImage(source, fit.x, fit.y, fit.width, fit.height);
+  return fit;
+}
+
+/** Films the visible page when the host forbids tab capture. The toolbar is left out of the frames. */
+async function startViewportRecording(
+  mime: string,
+  microphone: MediaStreamTrack | null,
+  onReady?: (take: TabTake) => void,
+  onChunk?: RecordOptions["onChunk"],
+): Promise<TabTake> {
+  const { canvas, ctx } = frameCanvas();
+  const background = pageBackground();
+  ctx.fillStyle = background;
+  ctx.fillRect(0, 0, FRAME_WIDTH, FRAME_HEIGHT);
+  const stream = canvas.captureStream(FRAME_RATE);
+  let stopped = false;
+  let fit = fitFrame(document.documentElement.clientWidth, window.innerHeight);
+  const clicks: Array<{ x: number; y: number; at: number }> = [];
+  const onPointer = (event: PointerEvent) => {
+    const target = event.target;
+    if (target instanceof Element && target.closest("#cs-root")) return;
+    clicks.push({
+      x: fit.x + event.clientX * fit.scale,
+      y: fit.y + event.clientY * fit.scale,
+      at: performance.now(),
+    });
+    if (clicks.length > 12) clicks.shift();
+  };
+  document.addEventListener("pointerdown", onPointer, true);
+  const take = recordStream(
+    stream,
+    mime,
+    microphone,
+    () => {
+      stopped = true;
+      document.removeEventListener("pointerdown", onPointer, true);
+    },
+    onChunk,
+  );
+  onReady?.(take);
+  const paint = async (timeout: number) => {
+    if (stopped) return;
+    const { renderViewport } = await import("./screenshot.js");
+    const cssWidth = document.documentElement.clientWidth;
+    const cssHeight = window.innerHeight;
+    fit = fitFrame(cssWidth, cssHeight);
+    const page = await renderViewport(fit.scale, timeout);
+    if (stopped) return;
+    paintFrame(ctx, page, cssWidth, cssHeight, background);
+    const now = performance.now();
+    for (const click of clicks) {
+      const age = now - click.at;
+      if (age > 1200) continue;
+      ctx.beginPath();
+      ctx.arc(click.x, click.y, 22, 0, Math.PI * 2);
+      ctx.strokeStyle = `rgba(0, 122, 255, ${1 - age / 1200})`;
+      ctx.lineWidth = 4;
+      ctx.stroke();
+    }
+  };
+  try {
+    await paint(4000);
+  } catch {
+    take.cancel();
+    if (stopped) return take;
+    throw new Error("Couldn’t start a recording.");
+  }
+  if (stopped) return take;
+  const pump = async () => {
+    while (!stopped) {
+      try {
+        await paint(6000);
+      } catch {
+        // Keep the last good frame and try again.
+      }
+      if (stopped) return;
+      await new Promise((resolve) => window.setTimeout(resolve, 32));
+    }
+  };
+  void pump();
+  return take;
+}
+
+/**
+ * Films this tab. When the page allows screen capture, the browser asks first.
+ * When the page forbids it, the visible page is filmed instead, so the record button still works.
+ * With `sound`, the mic is asked for after the screen (the screen prompt needs the click's activation).
+ */
+export async function startTabRecording(
+  options: RecordOptions,
+  onReady?: (take: TabTake) => void,
+): Promise<TabTake> {
+  if (!recordingMime()) throw new Error("Recording isn’t available in this browser.");
+  const withSound = async () => {
+    const microphone = options.sound ? await openMicrophone() : null;
+    const mime = recordingMime(Boolean(microphone)) ?? recordingMime()!;
+    return { microphone, mime };
+  };
+  const policy =
+    typeof document === "undefined"
+      ? null
+      : pageCapturePolicy(
+          document as Document & {
+            permissionsPolicy?: FeaturePolicy;
+            featurePolicy?: FeaturePolicy;
+          },
+        );
+  if (displayCaptureAllowed(policy) && navigator.mediaDevices?.getDisplayMedia) {
+    let stream: MediaStream;
+    try {
+      stream = await navigator.mediaDevices.getDisplayMedia({
+        video: {
+          width: { ideal: FRAME_WIDTH },
+          height: { ideal: FRAME_HEIGHT },
+          frameRate: { ideal: FRAME_RATE, max: FRAME_RATE },
+        },
+        audio: false,
+        preferCurrentTab: true,
+        selfBrowserSurface: "include",
+        monitorTypeSurfaces: "exclude",
+        surfaceSwitching: "exclude",
+        systemAudio: "exclude",
+      } as DisplayMediaStreamOptions);
+    } catch (caught) {
+      if (
+        caught instanceof DOMException &&
+        (caught.name === "NotAllowedError" || caught.name === "AbortError")
+      ) {
+        throw new Error("Recording needs permission to capture this tab.");
+      }
+      throw new Error("Couldn’t start a recording.");
+    }
+    const videoTrack = stream.getVideoTracks()[0];
+    const surface = videoTrack
+      ? (videoTrack.getSettings() as MediaTrackSettings & { displaySurface?: string })
+          .displaySurface
+      : undefined;
+    if (surface && surface !== "browser") {
+      for (const track of stream.getTracks()) track.stop();
+      throw new Error("Recording stays on this tab. Choose the current tab.");
+    }
+    const { microphone, mime } = await withSound();
+    return recordDisplayStream(stream, mime, microphone, onReady, options.onChunk);
+  }
+  const { microphone, mime } = await withSound();
+  return startViewportRecording(mime, microphone, onReady, options.onChunk);
+}
+
+/** Scales a tab capture down to 1920×1080. Drawing a video frame is cheap, so this stays at 30 fps. */
+async function recordDisplayStream(
+  stream: MediaStream,
+  mime: string,
+  microphone: MediaStreamTrack | null,
+  onReady?: (take: TabTake) => void,
+  onChunk?: RecordOptions["onChunk"],
+): Promise<TabTake> {
+  const video = document.createElement("video");
+  video.srcObject = stream;
+  video.muted = true;
+  video.playsInline = true;
+  await video.play();
+  const { canvas, ctx } = frameCanvas();
+  const background = pageBackground();
+  const output = canvas.captureStream(FRAME_RATE);
+  let stopped = false;
+  let frame = 0;
+  const draw = () => {
+    if (stopped) return;
+    frame = requestAnimationFrame(draw);
+    if (video.readyState < 2 || video.videoWidth < 2) return;
+    paintFrame(ctx, video, video.videoWidth, video.videoHeight, background);
+  };
+  draw();
+  const take = recordStream(
+    output,
+    mime,
+    microphone,
+    () => {
+      stopped = true;
+      cancelAnimationFrame(frame);
+      for (const track of stream.getTracks()) track.stop();
+      video.srcObject = null;
+    },
+    onChunk,
+  );
+  stream.getVideoTracks()[0]?.addEventListener("ended", () => take.stop());
+  onReady?.(take);
+  return take;
+}

package/src/runtime/redact.ts

@@ -0,0 +1,30 @@
+const SECRET =
+  /bearer\s+[a-z0-9._~+/=-]+|\beyJ[a-zA-Z0-9_-]{8,}\.[a-zA-Z0-9_-]{8,}\.[a-zA-Z0-9_-]{8,}\b|\b(?:sk|pk|rk)_(?:live|test)_[a-zA-Z0-9]+\b/gi;
+
+/** Strips tokens and control characters from text that may be stored with a comment. */
+export function redactText(value: string) {
+  return value
+    .replace(SECRET, "[redacted]")
+    .replace(/[\u0000-\u001f]/g, "")
+    .slice(0, 240);
+}
+
+const SENSITIVE =
+  /pass(?:word|phrase|code)?|\bsecret\b|\btoken\b|credential|\bssn\b|social security|\bpin\b|\botp\b|\bauth\b|session|cookie|api[-_ ]?key|card number|cvv|cvc/i;
+
+/** True for password fields and controls whose name, id, label, or autocomplete looks like a credential. */
+export function fieldIsSensitive(field: {
+  type?: string;
+  name?: string;
+  id?: string;
+  autocomplete?: string;
+  label?: string;
+}) {
+  const type = (field.type ?? "").toLowerCase();
+  if (type === "password" || type === "hidden") return true;
+  const autocomplete = (field.autocomplete ?? "").toLowerCase();
+  if (autocomplete.includes("password") || autocomplete.startsWith("cc-")) return true;
+  return SENSITIVE.test(
+    `${field.name ?? ""} ${field.id ?? ""} ${field.label ?? ""} ${autocomplete}`,
+  );
+}

package/src/runtime/related.ts

@@ -0,0 +1,34 @@
+import type { Thread } from "./api.js";
+
+export type Related = { thread: Thread; because: string };
+
+/** The page address without a hash, so a thread link does not split two comments on the same screen. */
+function pageKey(thread: Thread) {
+  return (thread.url || thread.route).split("#")[0];
+}
+
+/**
+ * Other comments that are actually about this one.
+ * The path alone is not enough: every comment in a single-page app shares it.
+ * A match is the same page address, or the same component.
+ */
+export function relatedTo(selected: Thread, threads: Thread[]): Related[] {
+  const page = pageKey(selected);
+  const component = selected.anchor.component?.name || null;
+  const found: Related[] = [];
+  for (const thread of threads) {
+    if (thread.id === selected.id) continue;
+    const samePage = pageKey(thread) === page;
+    const sameComponent = Boolean(component) && thread.anchor.component?.name === component;
+    if (!samePage && !sameComponent) continue;
+    const because = [samePage ? "Same page" : null, sameComponent ? component : null]
+      .filter(Boolean)
+      .join(" · ");
+    found.push({ thread, because });
+  }
+  return found.sort((a, b) => {
+    const rank = (item: Related) =>
+      item.because.includes("·") ? 0 : item.because === "Same page" ? 1 : 2;
+    return rank(a) - rank(b) || Date.parse(b.thread.updatedAt) - Date.parse(a.thread.updatedAt);
+  });
+}

package/src/runtime/render-page.ts

@@ -0,0 +1,2 @@
+// Loaded with import() through this module: importing the package itself that way would bundle all of it, not just domToCanvas.
+export { domToCanvas } from "modern-screenshot";

package/src/runtime/replay-model.ts

@@ -0,0 +1,232 @@
+/**
+ * The activity replay model: event types, the rolling buffer, the `replay-*.json` file, and how each event reads.
+ * DOM-free, so native clients share it. Watching a web page for those events is `watchActivity` in `./replay.ts`.
+ */
+import { redactText } from "./redact.js";
+
+const WINDOW_MS = 60_000;
+const MAX_EVENTS = 80;
+/** Most events a file carries, however long the window that made it. */
+const MAX_FILE_EVENTS = 400;
+
+export type ReplayDraft =
+  | { type: "navigate"; path: string }
+  | { type: "click"; label: string }
+  | { type: "input"; label: string; redacted: boolean; value?: string }
+  | { type: "console"; level: "error" | "warn"; message: string }
+  /** A request the page made that failed: `status` 0 means it never got an answer. */
+  | { type: "network"; method: string; path: string; status: number }
+  /** Words the commenter said while a clip was recording, placed when that piece was spoken. */
+  | { type: "say"; text: string };
+
+export type ReplayEvent = ReplayDraft & { t: number };
+
+/** When the file goes with a recording: the clip's name and clock, so events sit on its timeline. */
+export type ReplayClip = { name: string; startedAt: number; durationMs: number };
+
+export type ReplayFile = {
+  v: 1;
+  kind: "instant-replay";
+  url: string;
+  events: ReplayEvent[];
+  clip?: ReplayClip;
+};
+
+export type ReplayBufferOptions = {
+  now?: () => number;
+  /** How far back events are kept. */
+  windowMs?: number;
+  maxEvents?: number;
+};
+
+/**
+ * What the commenter did, as a rolling window. The default minute backs the instant replay; a recording keeps a
+ * wider one for the clip's whole length. Stays in memory until it is attached.
+ */
+export class ReplayBuffer {
+  private items: ReplayEvent[] = [];
+  private readonly now: () => number;
+  private readonly windowMs: number;
+  private readonly maxEvents: number;
+
+  constructor(options: ReplayBufferOptions | (() => number) = {}) {
+    const settings = typeof options === "function" ? { now: options } : options;
+    this.now = settings.now ?? (() => Date.now());
+    this.windowMs = settings.windowMs ?? WINDOW_MS;
+    this.maxEvents = Math.min(settings.maxEvents ?? MAX_EVENTS, MAX_FILE_EVENTS);
+  }
+
+  push(event: ReplayDraft) {
+    this.pushAt(event, this.now());
+  }
+
+  /** An event that happened at `t`, not now: narration lands when it was spoken, not when it was written. */
+  pushAt(event: ReplayDraft, t: number) {
+    const now = this.now();
+    this.items.push({ ...event, t });
+    this.items.sort((a, b) => a.t - b.t);
+    const cutoff = now - this.windowMs;
+    this.items = this.items.filter((item) => item.t >= cutoff).slice(-this.maxEvents);
+  }
+
+  /** `windowMs` keeps only the events of that last stretch. */
+  snapshot(url: string, clip?: ReplayClip, windowMs?: number): ReplayFile | null {
+    const cutoff = windowMs === undefined ? -Infinity : this.now() - windowMs;
+    const kept = this.items.filter((event) => event.t >= cutoff);
+    if (!kept.length) return null;
+    return {
+      v: 1,
+      kind: "instant-replay",
+      url,
+      events: kept.map((event) => ({ ...event })),
+      ...(clip ? { clip } : {}),
+    };
+  }
+
+  /** Every event still in the window, oldest first. */
+  events(): ReplayEvent[] {
+    return this.items.map((event) => ({ ...event }));
+  }
+
+  clear() {
+    this.items = [];
+  }
+
+  get size() {
+    return this.items.length;
+  }
+}
+
+function text(value: unknown, max: number) {
+  return typeof value === "string" ? value.replace(/[\u0000-\u001f]/g, "").slice(0, max) : "";
+}
+
+/** Accepts only the replay shape the toolbar writes. Anything else is dropped. */
+export function parseReplay(value: unknown): ReplayFile | null {
+  if (!value || typeof value !== "object") return null;
+  // allow-banned-record-unknown: untrusted JSON from an attachment, each field is checked below
+  const input = value as Record<string, unknown>;
+  if (input["v"] !== 1 || input["kind"] !== "instant-replay" || !Array.isArray(input["events"]))
+    return null;
+  const url = text(input["url"], 2048);
+  if (!url) return null;
+  const events: ReplayEvent[] = [];
+  for (const item of input["events"].slice(0, MAX_FILE_EVENTS)) {
+    if (!item || typeof item !== "object") continue;
+    // allow-banned-record-unknown: untrusted JSON from an attachment, each field is checked below
+    const event = item as Record<string, unknown>;
+    const t = typeof event["t"] === "number" && Number.isFinite(event["t"]) ? event["t"] : null;
+    if (t === null) continue;
+    if (event["type"] === "navigate") {
+      const path = text(event["path"], 300);
+      if (path) events.push({ t, type: "navigate", path });
+    } else if (event["type"] === "click") {
+      const label = text(event["label"], 120);
+      if (label) events.push({ t, type: "click", label });
+    } else if (event["type"] === "input") {
+      const label = text(event["label"], 120);
+      if (!label) continue;
+      const redacted = event["redacted"] === true;
+      const entered = text(event["value"], 80);
+      events.push({
+        t,
+        type: "input",
+        label,
+        redacted,
+        ...(redacted || !entered ? {} : { value: entered }),
+      });
+    } else if (
+      event["type"] === "console" &&
+      (event["level"] === "error" || event["level"] === "warn")
+    ) {
+      const message = text(event["message"], 240);
+      if (message) events.push({ t, type: "console", level: event["level"], message });
+    } else if (event["type"] === "say") {
+      const said = text(event["text"], 400);
+      if (said) events.push({ t, type: "say", text: said });
+    } else if (event["type"] === "network") {
+      const path = text(event["path"], 300);
+      const status =
+        typeof event["status"] === "number" && Number.isFinite(event["status"])
+          ? event["status"]
+          : 0;
+      if (path)
+        events.push({
+          t,
+          type: "network",
+          method: text(event["method"], 8) || "GET",
+          path,
+          status,
+        });
+    }
+  }
+  if (!events.length) return null;
+  let clip: ReplayClip | undefined;
+  if (input["clip"] && typeof input["clip"] === "object") {
+    // allow-banned-record-unknown: untrusted JSON from an attachment, each field is checked below
+    const raw = input["clip"] as Record<string, unknown>;
+    const name = text(raw["name"], 120);
+    const startedAt =
+      typeof raw["startedAt"] === "number" && Number.isFinite(raw["startedAt"])
+        ? raw["startedAt"]
+        : null;
+    const durationMs =
+      typeof raw["durationMs"] === "number" && Number.isFinite(raw["durationMs"])
+        ? raw["durationMs"]
+        : null;
+    if (name && startedAt !== null && durationMs !== null && durationMs > 0)
+      clip = { name, startedAt, durationMs };
+  }
+  return { v: 1, kind: "instant-replay", url, events, ...(clip ? { clip } : {}) };
+}
+
+/** The clip name a replay file goes with, by the stamp both carry: `recording-<stamp>.webm` ↔ `replay-<stamp>.json`. */
+export function replayStamp(name: string) {
+  return /^(?:recording|replay)-(.+?)(?:\.cut)?\.(?:webm|mp4|json)$/.exec(name)?.[1] ?? null;
+}
+
+/** One line of a replay event, as the viewers show it. */
+export function replayLine(event: ReplayEvent) {
+  switch (event.type) {
+    case "navigate":
+      return `Went to ${event.path}`;
+    case "click":
+      return `Clicked “${event.label}”`;
+    case "input":
+      return event.redacted
+        ? `Typed in “${event.label}”`
+        : `Typed “${event.value}” in “${event.label}”`;
+    case "console":
+      return `${event.level === "error" ? "Error" : "Warning"}: ${event.message}`;
+    case "network":
+      return event.status
+        ? `${event.method} ${event.path} answered ${event.status}`
+        : `${event.method} ${event.path} got no answer`;
+    case "say":
+      return `Said “${event.text}”`;
+  }
+}
+
+/** Query keys whose values are never written down. `s` is the comment service's own signed-file signature (`/v1/files?…&s=`). */
+const SECRET_PARAM = /^s$|token|key|secret|auth|session|password|passwd|sig|code|credential/i;
+
+/** Replaces secret query values in place. The page URL stored with a comment uses this too. */
+export function redactSecretSearchParams(url: URL) {
+  for (const name of [...url.searchParams.keys()]) {
+    if (SECRET_PARAM.test(name)) url.searchParams.set(name, "[redacted]");
+  }
+}
+
+/** A console call's arguments as one redacted line. */
+export function consoleText(args: unknown[]) {
+  const message = args
+    .map((arg) => {
+      if (arg instanceof Error) return arg.message;
+      if (typeof arg === "string" || typeof arg === "number" || typeof arg === "boolean")
+        return String(arg);
+      return "";
+    })
+    .filter(Boolean)
+    .join(" ");
+  return redactText(message || "error");
+}