browser-commander 0.17.2 → 0.18.0

package/src/traces/redaction.js

@@ -0,0 +1,231 @@
+/**
+ * Redaction applied before a trace byte reaches disk (issue #87).
+ *
+ * Browser traces routinely contain credentials. Redaction therefore runs
+ * where the data is produced — inside the page for DOM and control state, and
+ * on every string this module touches for URLs, headers and messages — rather
+ * than as a pass over a file that has already been written.
+ */
+
+/** What replaces a redacted value. Recognizable, and never a valid secret. */
+export const REDACTED = '[redacted]';
+
+/** Controls whose value is a secret unless the caller says otherwise. */
+export const DEFAULT_REDACT_SELECTORS = Object.freeze([
+  'input[type=password]',
+  '[data-private]',
+  '[data-bc-redact]',
+]);
+
+/** Attributes and headers that carry credentials. */
+export const DEFAULT_REDACT_ATTRIBUTES = Object.freeze([
+  'authorization',
+  'proxy-authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'x-auth-token',
+  'x-csrf-token',
+]);
+
+/** Query parameters that carry credentials in a URL. */
+export const DEFAULT_REDACT_QUERY_PARAMS = Object.freeze([
+  'access_token',
+  'api_key',
+  'apikey',
+  'auth',
+  'code',
+  'id_token',
+  'password',
+  'refresh_token',
+  'secret',
+  'session',
+  'signature',
+  'token',
+]);
+
+function lowerSet(values) {
+  return [...new Set(values.map((value) => String(value).toLowerCase()))];
+}
+
+/**
+ * Turn the caller's `privacy` option into the shape every writer uses.
+ *
+ * @param {Object} [privacy] - Caller privacy options
+ * @returns {Object} Normalized privacy options
+ */
+export function normalizePrivacyOptions(privacy = {}) {
+  if (privacy === null || typeof privacy !== 'object') {
+    throw new Error('trace privacy options must be an object');
+  }
+
+  const {
+    redactSelectors = [],
+    redactAttributes = [],
+    redactQueryParams = [],
+    redactPatterns = [],
+    redact = null,
+    // Defaults are additive: a caller adds to the safe set rather than
+    // silently replacing it, so a new selector cannot uncover passwords.
+    useDefaults = true,
+  } = privacy;
+
+  if (redact !== null && typeof redact !== 'function') {
+    throw new Error('privacy.redact must be a function');
+  }
+
+  return {
+    redactSelectors: lowerSet([
+      ...(useDefaults ? DEFAULT_REDACT_SELECTORS : []),
+      ...redactSelectors,
+    ]),
+    redactAttributes: lowerSet([
+      ...(useDefaults ? DEFAULT_REDACT_ATTRIBUTES : []),
+      ...redactAttributes,
+    ]),
+    redactQueryParams: lowerSet([
+      ...(useDefaults ? DEFAULT_REDACT_QUERY_PARAMS : []),
+      ...redactQueryParams,
+    ]),
+    redactPatterns: redactPatterns.map((pattern) =>
+      pattern instanceof RegExp ? pattern : new RegExp(String(pattern), 'g')
+    ),
+    redact,
+  };
+}
+
+/**
+ * Apply the caller's patterns and callback to a string.
+ *
+ * @param {string} value - Text about to be persisted
+ * @param {Object} privacy - Normalized privacy options
+ * @param {Object} [context] - What the text is, passed to the callback
+ * @returns {string} Redacted text
+ */
+export function redactText(value, privacy, context = {}) {
+  if (typeof value !== 'string' || value === '') {
+    return value;
+  }
+
+  let text = value;
+  for (const pattern of privacy.redactPatterns || []) {
+    // A caller's regex may be stateful; resetting keeps one trace's output
+    // from depending on the previous record's match position.
+    pattern.lastIndex = 0;
+    text = text.replace(pattern, REDACTED);
+  }
+
+  if (privacy.redact) {
+    const replaced = privacy.redact({ ...context, value: text });
+    if (typeof replaced === 'string') {
+      text = replaced;
+    }
+  }
+
+  return text;
+}
+
+/**
+ * Redact credentials carried in a URL.
+ *
+ * `https://user:pass@host/path?token=abc` becomes a URL that still identifies
+ * the page without handing over the session it belonged to.
+ *
+ * @param {string} url - URL about to be persisted
+ * @param {Object} privacy - Normalized privacy options
+ * @returns {string} Redacted URL
+ */
+export function redactUrl(url, privacy) {
+  if (typeof url !== 'string' || url === '') {
+    return url;
+  }
+
+  let text = url;
+  try {
+    const parsed = new URL(url);
+    if (parsed.username || parsed.password) {
+      parsed.username = parsed.username ? REDACTED : '';
+      parsed.password = parsed.password ? REDACTED : '';
+    }
+    for (const key of [...parsed.searchParams.keys()]) {
+      if (privacy.redactQueryParams.includes(key.toLowerCase())) {
+        parsed.searchParams.set(key, REDACTED);
+      }
+    }
+    if (parsed.hash) {
+      // Implicit OAuth flows put the token in the fragment.
+      const fragment = new URLSearchParams(parsed.hash.slice(1));
+      let changed = false;
+      for (const key of [...fragment.keys()]) {
+        if (privacy.redactQueryParams.includes(key.toLowerCase())) {
+          fragment.set(key, REDACTED);
+          changed = true;
+        }
+      }
+      if (changed) {
+        parsed.hash = `#${fragment.toString()}`;
+      }
+    }
+    // `URL` percent-encodes whatever it is given, so the marker is put back
+    // in readable form: a trace is read by people.
+    text = parsed.toString().split(encodeURIComponent(REDACTED)).join(REDACTED);
+  } catch {
+    // A relative or malformed URL is still worth keeping, just unparsed.
+  }
+
+  return redactText(text, privacy, { kind: 'url' });
+}
+
+/**
+ * Redact a header or attribute map.
+ *
+ * @param {Object} headers - Header name/value pairs
+ * @param {Object} privacy - Normalized privacy options
+ * @returns {Object} Map with sensitive values replaced
+ */
+export function redactHeaders(headers, privacy) {
+  if (!headers || typeof headers !== 'object') {
+    return headers;
+  }
+
+  const result = {};
+  for (const [name, value] of Object.entries(headers)) {
+    result[name] = privacy.redactAttributes.includes(name.toLowerCase())
+      ? REDACTED
+      : redactText(String(value), privacy, { kind: 'header', name });
+  }
+  return result;
+}
+
+/**
+ * Redact every string in an event payload.
+ *
+ * Applied to whatever a caller or engine put in an event, because a trace is
+ * only as private as its least careful field.
+ *
+ * @param {*} value - Any JSON-compatible value
+ * @param {Object} privacy - Normalized privacy options
+ * @param {string} [key] - Field name the value was found under
+ * @returns {*} The value with strings redacted
+ */
+export function redactValue(value, privacy, key = '') {
+  if (typeof value === 'string') {
+    if (privacy.redactAttributes.includes(key.toLowerCase())) {
+      return REDACTED;
+    }
+    return /url$/i.test(key)
+      ? redactUrl(value, privacy)
+      : redactText(value, privacy, { kind: 'field', name: key });
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactValue(entry, privacy, key));
+  }
+  if (value && typeof value === 'object') {
+    const result = {};
+    for (const [name, entry] of Object.entries(value)) {
+      result[name] = redactValue(entry, privacy, name);
+    }
+    return result;
+  }
+  return value;
+}

package/src/traces/schema.js

@@ -0,0 +1,165 @@
+/**
+ * The portable browser trace format (issue #87).
+ *
+ * One engine-neutral, versioned layout is written by JavaScript and read by
+ * JavaScript, Python and Rust. Everything about the format that a reader has
+ * to agree on lives here, so a change to the layout is a change to one file.
+ */
+
+/**
+ * Schema version of the bundle.
+ *
+ * Readers refuse a major version they were not written for rather than
+ * guessing at the meaning of unknown records.
+ */
+export const TRACE_SCHEMA_VERSION = 1;
+
+/** Name every reader looks for inside a bundle. */
+export const TRACE_FILES = Object.freeze({
+  MANIFEST: 'manifest.json',
+  EVENTS: 'events.ndjson',
+  CHECKPOINTS_DIR: 'checkpoints',
+  MUTATIONS_DIR: 'mutations',
+  ARTIFACTS_DIR: 'artifacts',
+  VIEWER: 'viewer.html',
+});
+
+/** What the recorder captures. */
+export const TRACE_MODE = Object.freeze({
+  OFF: 'off',
+  CHECKPOINTS: 'checkpoints',
+  CONTINUOUS: 'continuous',
+  RETAIN_ON_FAILURE: 'retain-on-failure',
+});
+
+/** Event kinds that share the one ordered timeline. */
+export const TRACE_EVENT = Object.freeze({
+  TRACE_START: 'trace.start',
+  TRACE_STOP: 'trace.stop',
+  CHECKPOINT: 'checkpoint',
+  MUTATIONS: 'mutations',
+  NAVIGATION: 'navigation',
+  INTERACTION: 'interaction',
+  CONSOLE: 'console',
+  PAGE_ERROR: 'pageerror',
+  DIALOG: 'dialog',
+  REQUEST_FAILED: 'requestfailed',
+  DOWNLOAD: 'download',
+  /** Something could not be recorded. The run continues; the gap is visible. */
+  DROPPED: 'dropped',
+});
+
+/** Event families a caller can subscribe the recorder to. */
+export const TRACE_EVENT_SOURCES = Object.freeze([
+  'navigation',
+  'interaction',
+  'console',
+  'pageerror',
+  'dialog',
+  'requestfailed',
+  'download',
+]);
+
+/** Why a record was dropped. */
+export const TRACE_DROP_REASON = Object.freeze({
+  SIZE_LIMIT: 'size-limit',
+  WRITE_FAILED: 'write-failed',
+  CAPTURE_FAILED: 'capture-failed',
+  PAGE_CLOSED: 'page-closed',
+  TIMEOUT: 'timeout',
+});
+
+/** How a trace ended, recorded in the manifest. */
+export const TRACE_OUTCOME = Object.freeze({
+  /** `stop()` was called and every record was written. */
+  COMPLETE: 'complete',
+  /** The trace is readable but records are missing. */
+  PARTIAL: 'partial',
+  /** No manifest was ever written; readers repair this on open. */
+  TRUNCATED: 'truncated',
+});
+
+/** Default ceiling on a bundle, so a runaway page cannot fill a disk. */
+export const DEFAULT_MAX_BUNDLE_BYTES = 256 * 1024 * 1024;
+
+/** Default ceiling on any single member of a bundle. */
+export const DEFAULT_MAX_RESOURCE_BYTES = 32 * 1024 * 1024;
+
+/** How long a single capture may take before it is dropped. */
+export const DEFAULT_CAPTURE_TIMEOUT = 15000;
+
+/**
+ * Format a bundle member's sequence number.
+ *
+ * Zero padding keeps `ls` and any reader that sorts lexically in the same
+ * order as the sequence itself.
+ *
+ * @param {number} index - 1-based sequence number
+ * @returns {string} Zero-padded name, such as `0001`
+ */
+export function sequenceName(index) {
+  return String(index).padStart(4, '0');
+}
+
+/**
+ * Build the manifest of a trace.
+ *
+ * @param {Object} options - Manifest fields
+ * @returns {Object} The manifest as it is written to disk
+ */
+export function createManifest(options = {}) {
+  const {
+    mode,
+    startedAt,
+    stoppedAt = null,
+    outcome = TRACE_OUTCOME.COMPLETE,
+    commanderVersion = null,
+    engine = null,
+    browser = null,
+    platform = `${process.platform} ${process.arch}`,
+    runtime = `node ${process.versions?.node ?? 'unknown'}`,
+    counts = {},
+    limits = {},
+    privacy = {},
+    dom = {},
+    events = [],
+    dropped = 0,
+  } = options;
+
+  return {
+    schemaVersion: TRACE_SCHEMA_VERSION,
+    format: 'browser-commander-trace',
+    mode,
+    outcome,
+    startedAt,
+    stoppedAt,
+    commanderVersion,
+    engine,
+    browser,
+    platform,
+    runtime,
+    events: [...events],
+    dom: { ...dom },
+    privacy: { ...privacy },
+    limits: { ...limits },
+    counts: { checkpoints: 0, events: 0, mutationBatches: 0, ...counts },
+    dropped,
+  };
+}
+
+/**
+ * Check that a manifest can be read by this version of the format.
+ *
+ * @param {Object} manifest - Parsed manifest
+ * @throws {Error} When the bundle is not a readable trace
+ */
+export function assertReadableManifest(manifest) {
+  if (!manifest || manifest.format !== 'browser-commander-trace') {
+    throw new Error('not a Browser Commander trace bundle');
+  }
+  if (manifest.schemaVersion > TRACE_SCHEMA_VERSION) {
+    throw new Error(
+      `trace schema version ${manifest.schemaVersion} is newer than this reader (${TRACE_SCHEMA_VERSION})`
+    );
+  }
+}

package/src/traces/viewer.js

@@ -0,0 +1,302 @@
+/**
+ * The offline trace viewer (issue #87).
+ *
+ * The viewer is one static HTML file written into the bundle. It opens from
+ * the filesystem with no server, and it is inert by construction: captured
+ * markup is rendered inside a sandboxed frame that inherits a
+ * `default-src 'none'` policy, so the recorded page cannot run its scripts,
+ * submit its forms, or reach the network from a reviewer's machine.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { TRACE_FILES } from './schema.js';
+import { TRACE_FILE_MODE } from './bundle.js';
+import { diffControlState, readTrace } from './reader.js';
+
+/** How much captured HTML is embedded per checkpoint before it is elided. */
+export const DEFAULT_MAX_INLINE_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Escape a value so it can sit inside a `<script type="application/json">`.
+ *
+ * @param {*} data - JSON-compatible value
+ * @returns {string} Safe JSON text
+ */
+function embed(data) {
+  // `<` is escaped so the JSON can never close the script element, and the
+  // two Unicode line separators are escaped because they are line breaks to a
+  // JavaScript parser but not to `JSON.stringify`.
+  const LINE_SEPARATORS = new RegExp('[\u2028\u2029]', 'g');
+  return JSON.stringify(data)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(LINE_SEPARATORS, (match) =>
+      match === '\u2028' ? '\\u2028' : '\\u2029'
+    );
+}
+
+const VIEWER_STYLE = `
+  :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+  body { margin: 0; display: grid; grid-template-columns: 22rem 1fr;
+         grid-template-rows: auto 1fr; height: 100vh; }
+  header { grid-column: 1 / -1; padding: 0.5rem 1rem; border-bottom: 1px solid #8884; }
+  h1 { font-size: 1rem; margin: 0 0 0.25rem; }
+  .meta { font-size: 0.75rem; opacity: 0.75; }
+  aside { overflow: auto; border-right: 1px solid #8884; }
+  main { display: grid; grid-template-rows: auto 1fr auto; overflow: hidden; }
+  ol { list-style: none; margin: 0; padding: 0; font-size: 0.8rem; }
+  li { padding: 0.35rem 0.75rem; border-bottom: 1px solid #8882; cursor: pointer; }
+  li.selected { background: #3b82f633; }
+  li .kind { font-weight: 600; }
+  li .at { opacity: 0.6; float: right; }
+  iframe { width: 100%; height: 100%; border: 0; background: #fff; }
+  .panel { padding: 0.5rem 1rem; border-top: 1px solid #8884; max-height: 14rem;
+           overflow: auto; font-size: 0.8rem; }
+  table { border-collapse: collapse; width: 100%; }
+  td, th { text-align: left; padding: 0.15rem 0.5rem; border-bottom: 1px solid #8882;
+           font-family: ui-monospace, monospace; font-size: 0.75rem; }
+  .controls { padding: 0.5rem 1rem; display: flex; gap: 0.5rem; align-items: center; }
+  .dropped { color: #b91c1c; }
+  button { font: inherit; }
+`;
+
+const VIEWER_SCRIPT = String.raw`
+const trace = JSON.parse(document.getElementById('trace-data').textContent);
+const timeline = document.getElementById('timeline');
+const frame = document.getElementById('stage');
+const details = document.getElementById('details');
+const diffPanel = document.getElementById('diff');
+const stepLabel = document.getElementById('step');
+let selectedCheckpoint = null;
+let mutationStep = 0;
+
+function checkpointFor(event) {
+  if (event.kind === 'checkpoint') return event.index;
+  let latest = null;
+  for (const other of trace.events) {
+    if (other.sequence > event.sequence) break;
+    if (other.kind === 'checkpoint') latest = other.index;
+  }
+  return latest;
+}
+
+function renderHtml(index, html) {
+  // The captured document is handed to a sandboxed frame with no
+  // allow-scripts and no allow-forms: it is shown, never run.
+  frame.srcdoc = html == null ? '<p style="font:1rem system-ui">no HTML captured for this checkpoint</p>' : html;
+}
+
+function applyMutations(index, upTo) {
+  const html = trace.html[index];
+  if (html == null) return null;
+  const parsed = new DOMParser().parseFromString(html, 'text/html');
+  const batches = trace.mutations[index] || [];
+  let applied = 0;
+  for (const batch of batches.slice(0, upTo)) {
+    for (const record of batch.records) {
+      const target = record.target && record.target.path
+        ? parsed.querySelector(record.target.path)
+        : null;
+      if (!target) continue;
+      if (record.kind === 'attributes' && record.attribute) {
+        if (record.after == null) target.removeAttribute(record.attribute);
+        else target.setAttribute(record.attribute, record.after);
+        applied++;
+      } else if (record.kind === 'characterData') {
+        target.textContent = record.after == null ? '' : record.after;
+        applied++;
+      } else if (record.kind === 'childList') {
+        for (const added of record.added || []) {
+          if (added && added.type === 'element' && added.html) {
+            target.insertAdjacentHTML('beforeend', added.html);
+            applied++;
+          }
+        }
+      }
+      if (target.style) target.style.outline = '2px solid #f59e0b';
+    }
+  }
+  return { html: '<!DOCTYPE html>' + parsed.documentElement.outerHTML, applied };
+}
+
+function showCheckpoint(index) {
+  selectedCheckpoint = index;
+  mutationStep = 0;
+  renderHtml(index, trace.html[index]);
+  const state = trace.state[index];
+  const previous = trace.state[index - 1];
+  details.innerHTML = state
+    ? '<table><tr><th>url</th><td>' + state.url + '</td></tr>' +
+      '<tr><th>title</th><td>' + (state.title || '') + '</td></tr>' +
+      '<tr><th>controls</th><td>' + (state.controls || []).length + '</td></tr></table>'
+    : '<p>no state captured</p>';
+  const changes = trace.diffs[index] || [];
+  diffPanel.innerHTML = previous && changes.length
+    ? '<table><tr><th>control</th><th>before</th><th>after</th></tr>' +
+      changes.map((c) => '<tr><td>' + c.path + '</td><td>' + (c.before ?? '') +
+        '</td><td>' + (c.after ?? '') + '</td></tr>').join('') + '</table>'
+    : '<p>no control changes against the previous checkpoint</p>';
+  stepLabel.textContent = (trace.mutations[index] || []).length + ' mutation batches';
+}
+
+function select(event, element) {
+  for (const li of timeline.children) li.classList.remove('selected');
+  element.classList.add('selected');
+  const index = checkpointFor(event);
+  if (index != null && index !== selectedCheckpoint) showCheckpoint(index);
+  if (event.kind !== 'checkpoint') {
+    details.innerHTML = '<table>' + Object.entries(event)
+      .map(([k, v]) => '<tr><th>' + k + '</th><td>' + String(
+        typeof v === 'object' ? JSON.stringify(v) : v).slice(0, 400) + '</td></tr>')
+      .join('') + '</table>';
+  }
+}
+
+for (const event of trace.events) {
+  const li = document.createElement('li');
+  if (event.kind === 'dropped') li.className = 'dropped';
+  li.innerHTML = '<span class="kind"></span> <span class="at"></span><div class="what"></div>';
+  li.querySelector('.kind').textContent = event.kind;
+  li.querySelector('.at').textContent = (event.at || '').slice(11, 23);
+  li.querySelector('.what').textContent =
+    event.name || event.action || event.text || event.message || event.url || event.reason || '';
+  li.addEventListener('click', () => select(event, li));
+  timeline.append(li);
+}
+
+document.getElementById('play').addEventListener('click', async () => {
+  if (selectedCheckpoint == null) return;
+  const batches = trace.mutations[selectedCheckpoint] || [];
+  for (let step = 1; step <= batches.length; step++) {
+    const result = applyMutations(selectedCheckpoint, step);
+    if (result) frame.srcdoc = result.html;
+    stepLabel.textContent = 'batch ' + step + ' of ' + batches.length;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+});
+
+document.getElementById('step-forward').addEventListener('click', () => {
+  if (selectedCheckpoint == null) return;
+  const batches = trace.mutations[selectedCheckpoint] || [];
+  mutationStep = Math.min(mutationStep + 1, batches.length);
+  const result = applyMutations(selectedCheckpoint, mutationStep);
+  if (result) frame.srcdoc = result.html;
+  stepLabel.textContent = 'batch ' + mutationStep + ' of ' + batches.length;
+});
+
+document.getElementById('reset').addEventListener('click', () => {
+  if (selectedCheckpoint != null) showCheckpoint(selectedCheckpoint);
+});
+
+if (trace.checkpoints.length) showCheckpoint(trace.checkpoints[0].index);
+`;
+
+/**
+ * Collect everything the viewer embeds.
+ *
+ * @param {Object} reader - An open trace, from `readTrace()`
+ * @param {number} maxInlineBytes - Ceiling per embedded member
+ * @returns {Promise<Object>} The viewer's data
+ */
+async function collectViewerData(reader, maxInlineBytes) {
+  const html = {};
+  const state = {};
+  const mutations = {};
+  const diffs = {};
+  const elided = [];
+
+  for (const checkpoint of reader.checkpoints) {
+    const body = await reader.html(checkpoint.index);
+    if (body !== null && body.length > maxInlineBytes) {
+      elided.push(checkpoint.index);
+      html[checkpoint.index] = null;
+    } else {
+      html[checkpoint.index] = body;
+    }
+    state[checkpoint.index] = await reader.state(checkpoint.index);
+    mutations[checkpoint.index] = await reader.mutations(checkpoint.index);
+  }
+
+  for (const checkpoint of reader.checkpoints) {
+    const previous = state[checkpoint.index - 1];
+    diffs[checkpoint.index] = previous
+      ? diffControlState(previous, state[checkpoint.index])
+      : [];
+  }
+
+  return {
+    manifest: reader.manifest,
+    events: reader.events,
+    checkpoints: reader.checkpoints,
+    html,
+    state,
+    mutations,
+    diffs,
+    elided,
+  };
+}
+
+/**
+ * Render the viewer for an open trace.
+ *
+ * @param {Object} reader - An open trace, from `readTrace()`
+ * @param {Object} [options] - `{maxInlineBytes}`
+ * @returns {Promise<string>} The viewer document
+ */
+export async function renderTraceViewer(reader, options = {}) {
+  const { maxInlineBytes = DEFAULT_MAX_INLINE_BYTES } = options;
+  const data = await collectViewerData(reader, maxInlineBytes);
+  const manifest = reader.manifest;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<!-- Inert by default: no network, no captured scripts, images only from data URLs. -->
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; frame-src 'self' data:;">
+<title>Browser Commander trace</title>
+<style>${VIEWER_STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>Browser Commander trace</h1>
+  <div class="meta">
+    mode ${manifest.mode} · outcome ${manifest.outcome} · engine ${manifest.engine ?? 'unknown'} ·
+    ${manifest.counts?.checkpoints ?? 0} checkpoints · ${manifest.counts?.events ?? 0} events ·
+    ${manifest.dropped ?? 0} dropped · started ${manifest.startedAt ?? 'unknown'}
+  </div>
+</header>
+<aside><ol id="timeline"></ol></aside>
+<main>
+  <div class="controls">
+    <button id="play" type="button">Replay mutations</button>
+    <button id="step-forward" type="button">Step</button>
+    <button id="reset" type="button">Reset</button>
+    <span id="step"></span>
+  </div>
+  <iframe id="stage" sandbox referrerpolicy="no-referrer" title="captured page"></iframe>
+  <div class="panel" id="details"></div>
+  <div class="panel" id="diff"></div>
+</main>
+<script id="trace-data" type="application/json">${embed(data)}</script>
+<script>${VIEWER_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+
+/**
+ * Write the viewer into a bundle.
+ *
+ * @param {string} bundlePath - Path to the bundle directory
+ * @param {Object} [options] - `{maxInlineBytes}`
+ * @returns {Promise<string>} Path to the written viewer
+ */
+export async function writeTraceViewer(bundlePath, options = {}) {
+  const reader = await readTrace(bundlePath);
+  const document = await renderTraceViewer(reader, options);
+  const target = path.join(reader.path, TRACE_FILES.VIEWER);
+  await fs.writeFile(target, document, { mode: TRACE_FILE_MODE });
+  return target;
+}