tui-cap 0.1.0

package/dist/web/app.js

@@ -0,0 +1,3312 @@
+// GHCP Capture GUI — vanilla front-end over the local capture/render API.
+
+import {
+  PLAYBACK_MIN_MS,
+  UNIFORM_FRAME_MS,
+  effectiveDurations as modelEffectiveDurations,
+  rawDurationMs as modelRawDurationMs,
+  cfrCount,
+  playbackHold,
+} from './timing-model.js';
+
+const $ = (id) => document.getElementById(id);
+
+const els = {
+  library: $('library'),
+  libStatus: $('libStatus'),
+  libEmpty: $('libEmpty'),
+  libLoading: $('libLoading'),
+  openFolderBtn: $('openFolderBtn'),
+  preview: $('preview'),
+  previewWrap: $('previewWrap'),
+  previewEmpty: $('previewEmpty'),
+  goStartBtn: $('goStartBtn'),
+  prevBtn: $('prevBtn'),
+  nextBtn: $('nextBtn'),
+  goEndBtn: $('goEndBtn'),
+  frameLabel: $('frameLabel'),
+  selGroup: $('selGroup'),
+  selLen: $('selLen'),
+  selLenLabel: $('selLenLabel'),
+  selReset: $('selReset'),
+  selDelete: $('selDelete'),
+  zoom: $('zoom'),
+  fitBtn: $('fitBtn'),
+  hideSkippedBtn: $('hideSkippedBtn'),
+  timelineScroll: $('timelineScroll'),
+  timelineRuler: $('timelineRuler'),
+  timelineTrack: $('timelineTrack'),
+  timelineEmpty: $('timelineEmpty'),
+  title: $('title'),
+  chrome: $('chrome'),
+  cursor: $('cursor'),
+  chromeStyle: $('chromeStyle'),
+  fontSize: $('fontSize'),
+  fontSizeVal: $('fontSizeVal'),
+  lineHeight: $('lineHeight'),
+  lineHeightVal: $('lineHeightVal'),
+  resetType: $('resetType'),
+  recordedSize: $('recordedSize'),
+  downloadBtn: $('downloadBtn'),
+  downloadPngBtn: $('downloadPngBtn'),
+  pngScale: $('pngScale'),
+  playBtn: $('playBtn'),
+  animStatus: $('animStatus'),
+  animNote: $('animNote'),
+  animFps: $('animFps'),
+  animScale: $('animScale'),
+  idleCap: $('idleCap'),
+  idleCapVal: $('idleCapVal'),
+  speed: $('speed'),
+  speedVal: $('speedVal'),
+  smoothTyping: $('smoothTyping'),
+  typingCps: $('typingCps'),
+  typingCpsVal: $('typingCpsVal'),
+  animLen: $('animLen'),
+  clearOverrides: $('clearOverrides'),
+  hud: $('hud'),
+  hudClose: $('hudClose'),
+  timingDebugLink: $('timingDebugLink'),
+  selfTestBtn: $('selfTestBtn'),
+  selfTestResult: $('selfTestResult'),
+  exportMp4Btn: $('exportMp4Btn'),
+  exportProgress: $('exportProgress'),
+  exportBar: $('exportBar'),
+  exportPct: $('exportPct'),
+  newRecBtn: $('newRecBtn'),
+  zoomFitBtn: $('zoomFitBtn'),
+  zoom100Btn: $('zoom100Btn'),
+  zoomRange: $('zoomRange'),
+  zoomPct: $('zoomPct'),
+  recDialog: $('recDialog'),
+  recCmd: $('recCmd'),
+  recName: $('recName'),
+  recOut: $('recOut'),
+  recCopy: $('recCopy'),
+  updateBanner: $('updateBanner'),
+  updateMsg: $('updateMsg'),
+  updateBtn: $('updateBtn'),
+  updateDismiss: $('updateDismiss'),
+  toast: $('toast'),
+};
+
+const state = {
+  name: null,
+  frames: [],
+  index: 0,
+  recordings: [],
+  hasTiming: false,
+  animationEnd: 0,
+  animCanvas: null,
+  // Timeline view state (ephemeral — not persisted with the recording).
+  zoom: 0, // pixels per second
+  hideSkipped: true, // collapse deleted/skipped frames out of the timeline (hidden by default)
+  viewMode: 'fit', // canvas scale: 'fit' (zoom to fit) | 'zoom' (explicit zoomScale)
+  zoomScale: 1, // canvas zoom factor when viewMode === 'zoom' (1 = 100%)
+  selection: new Set(),
+  anchor: 0,
+  blocks: [], // per-frame { el, head, handle, img, left, width }
+  boundaries: [], // cumulative px boundary positions, length frames+1
+  skipped: new Set(),
+  settings: { fps: 30, scale: 2, idleCapMs: 1500, speed: 1, overrides: {}, skipped: [], smoothTyping: false, typingCps: 30 },
+  // Monotonic content-edits revision (from the server). Used as an SVG cache-buster
+  // so the browser re-fetches edited frames instead of serving a stale image.
+  editsRevision: 0,
+};
+
+// Pixels-per-second zoom bounds (the slider maps onto this range on a log scale).
+const MIN_PPS = 2;
+const MAX_PPS = 1200;
+// A block must be at least this wide before it mounts the (relatively heavy) SVG
+// preview; narrower blocks render as a plain colored band. Matches the old card
+// width so previews stay legible.
+const PREVIEW_MIN_PX = 96;
+
+// Fallback per-frame hold when a capture has no timing sidecar.
+// UNIFORM_FRAME_MS is imported from ./timing-model.js (single source of truth).
+
+// Inline Octicon-style glyphs for the per-recording library actions.
+const ICON = {
+  reveal:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M0 1.75C0 .784.784 0 1.75 0h3.5c.55 0 1.07.26 1.4.7l.9 1.2a.25.25 0 0 0 .2.1h5.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 13.25 15H1.75A1.75 1.75 0 0 1 0 13.25Zm1.75-.25a.25.25 0 0 0-.25.25v11.5c0 .138.112.25.25.25h11.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25H7.5c-.55 0-1.07-.26-1.4-.7l-.9-1.2a.25.25 0 0 0-.2-.1Z"></path></svg>',
+  trash:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M11 1.75V3h2.25a.75.75 0 0 1 0 1.5H2.75a.75.75 0 0 1 0-1.5H5V1.75C5 .784 5.784 0 6.75 0h2.5C10.216 0 11 .784 11 1.75ZM4.496 6.675l.66 6.6a.25.25 0 0 0 .249.225h5.19a.25.25 0 0 0 .249-.225l.66-6.6a.75.75 0 0 1 1.492.149l-.66 6.6A1.748 1.748 0 0 1 10.595 15h-5.19a1.75 1.75 0 0 1-1.741-1.575l-.66-6.6a.75.75 0 1 1 1.492-.15ZM6.5 1.75V3h3V1.75a.25.25 0 0 0-.25-.25h-2.5a.25.25 0 0 0-.25.25Z"></path></svg>',
+  // Folder for the library-wide "open captures folder" action.
+  folder:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75Zm0 1.5h3.25a.25.25 0 0 1 .2.1l.9 1.2c.33.44.85.7 1.4.7h6.75a.25.25 0 0 1 .25.25v8.5a.25.25 0 0 1-.25.25H1.75a.25.25 0 0 1-.25-.25V2.75a.25.25 0 0 1 .25-.25Z"></path></svg>',
+  // Pencil for the per-recording rename action.
+  pencil:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M11.013 1.427a1.75 1.75 0 0 1 2.474 0l1.086 1.086a1.75 1.75 0 0 1 0 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 0 1-.927-.928l.929-3.25c.081-.286.235-.547.445-.758l8.61-8.61Zm1.414 1.06a.25.25 0 0 0-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 0 0 0-.354l-1.086-1.086ZM11.189 6.25 9.75 4.81l-6.286 6.287a.25.25 0 0 0-.064.108l-.558 1.953 1.953-.558a.249.249 0 0 0 .108-.064L11.189 6.25Z"></path></svg>',
+  // Transport controls. Each glyph is geometrically distinct so Play (lone
+  // triangle), step (single triangle + bar) and skip (double triangle + bar)
+  // never read the same at a glance.
+  goStart:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M2.8 3.4h1.7v9.2H2.8zM9 3.4v9.2L4.8 8zM13.4 3.4v9.2L9.2 8z"></path></svg>',
+  prev:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M3.6 3.4h2v9.2h-2zM12.8 3.4v9.2L6.4 8z"></path></svg>',
+  play:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M5 3.4v9.2l7.2-4.6z"></path></svg>',
+  pause:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M4.6 3.4h2.4v9.2H4.6zM9 3.4h2.4v9.2H9z"></path></svg>',
+  next:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M3.2 3.4v9.2l6.4-4.6zM10.4 3.4h2v9.2h-2z"></path></svg>',
+  goEnd:
+    '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">' +
+    '<path d="M2.6 3.4v9.2L6.8 8zM7 3.4v9.2L11.2 8zM11.5 3.4h1.7v9.2h-1.7z"></path></svg>',
+};
+
+/* ----------------------------------------------------------------- helpers */
+
+function debounce(fn, ms) {
+  let t;
+  return (...args) => {
+    clearTimeout(t);
+    t = setTimeout(() => fn(...args), ms);
+  };
+}
+
+async function apiJson(path) {
+  const res = await fetch(path);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+/** Combined query: render options (replay dims come from the recording itself). */
+function query() {
+  const p = new URLSearchParams();
+  p.set('title', els.title.value);
+  p.set('chrome', els.chrome.checked ? '1' : '0');
+  p.set('cursor', els.cursor.checked ? '1' : '0');
+  p.set('chromeStyle', els.chromeStyle.value);
+  p.set('fontSize', els.fontSize.value);
+  p.set('lineHeight', els.lineHeight.value);
+  // Bumped whenever content edits change so edited frames get a fresh URL and the
+  // browser re-fetches them instead of serving a stale (pre-edit) cached image.
+  p.set('rev', String(state.editsRevision || 0));
+  return p;
+}
+
+/**
+ * Tight, per-frame render: the renderer auto-fits to this frame's own inked
+ * content (trailing background bleed trimmed). Used ONLY for the timeline
+ * filmstrip thumbnails, where a snug crop per frame reads better in the strip.
+ */
+function svgUrl(index, download = false) {
+  const p = query();
+  if (download) p.set('download', '1');
+  return `/api/recordings/${encodeURIComponent(state.name)}/frames/${index}/svg?${p}`;
+}
+
+/**
+ * Canonical render params: the full (untrimmed) grid pinned to the recording's
+ * uniform animation canvas via fixedCols/fixedRows, so every frame renders at
+ * identical pixel dimensions no matter how sparse it is (the renderer otherwise
+ * auto-fits each frame to its own content). Shared by the main preview, the
+ * still SVG/PNG exports, the MP4 export, AND the editor's /cells geometry, so the
+ * window never resizes between frames and the overlay always lines up with what
+ * is shown.
+ */
+function fullParams() {
+  const p = query();
+  p.set('trim', '0');
+  if (state.animCanvas) {
+    p.set('fixedCols', String(state.animCanvas.cols));
+    p.set('fixedRows', String(state.animCanvas.rows));
+  }
+  return p;
+}
+
+function svgUrlFull(index) {
+  return `/api/recordings/${encodeURIComponent(state.name)}/frames/${index}/svg?${fullParams()}`;
+}
+
+/* --------------------------------------------------------- timeline math */
+
+/** Raw on-screen hold for a frame, before caps/speed/overrides. */
+function rawDurationMs(i) {
+  return modelRawDurationMs(state.frames[i]);
+}
+
+/**
+ * Effective per-frame durations (ms) across the whole frame list, applying the
+ * current settings. A per-frame override wins outright (bypasses cap + speed);
+ * otherwise the raw hold is capped at idleCapMs then divided by the speed.
+ * Delegates to the shared, parity-tested timing model (src/web/timing-model.js).
+ */
+function effectiveDurations() {
+  return modelEffectiveDurations(state.frames, state.settings);
+}
+
+/** True when frame `i` is marked skipped (excluded from playback + export). */
+function isSkipped(i) {
+  return state.skipped.has(i);
+}
+
+/**
+ * Indices that make up the animation: frames [0..animationEnd], minus any the
+ * user has skipped. Drives the play loop, the length readout, and MP4 export.
+ */
+function animRange() {
+  const last = Math.min(state.animationEnd, state.frames.length - 1);
+  const out = [];
+  for (let i = 0; i <= last; i++) if (!isSkipped(i)) out.push(i);
+  return out;
+}
+
+// Manual navigation (transport buttons, Home/End/arrows, scrub) should land on
+// the frames the user can actually see. While skipped frames are collapsed out
+// of the timeline they have zero width and must be hopped over, otherwise "go to
+// start" would surface a deleted opening frame instead of the first kept one.
+
+/** First frame the user can land on: the first non-skipped frame while skipped
+ *  frames are hidden, otherwise frame 0. */
+function firstVisibleIndex() {
+  if (state.hideSkipped) {
+    for (let i = 0; i < state.frames.length; i++) if (!isSkipped(i)) return i;
+  }
+  return 0;
+}
+/** Last frame the user can land on (symmetric with firstVisibleIndex). */
+function lastVisibleIndex() {
+  const n = state.frames.length;
+  if (state.hideSkipped) {
+    for (let i = n - 1; i >= 0; i--) if (!isSkipped(i)) return i;
+  }
+  return n - 1;
+}
+/** Step from `from` by `dir` (±1) to the next landable frame, hopping over
+ *  frames collapsed out of the timeline. Stays put at the visible edge. */
+function stepVisibleIndex(from, dir) {
+  for (let i = from + dir; i >= 0 && i < state.frames.length; i += dir) {
+    if (!state.hideSkipped || !isSkipped(i)) return i;
+  }
+  return from;
+}
+
+/** CFR repeat count for a frame held `ms` at `fps` — imported from the shared
+ *  timing model (src/web/timing-model.js); see `cfrCount` in the import block. */
+
+/* ----------------------------------------------------- idle-cap slider map */
+
+// The idle-cap slider runs in 60fps-frame units: position 1 = one frame
+// (1000/60 ≈ 16.67ms, the smallest cap) up through IDLE_CAP_MAX_FRAMES, plus one
+// extra position past that = ∞ (no cap), stored as idleCapMs = 0 so an idle frame
+// keeps its real recorded hold. Working in frame units lets the far-left land
+// exactly on a single 60fps frame and the far-right be a clean ∞ stop, while
+// state.settings.idleCapMs stays the source of truth (0 ⇒ ∞ / use real time).
+const IDLE_FRAME_MS = 1000 / 60;
+const IDLE_CAP_MAX_FRAMES = 300; // top finite cap ≈ 5.0s
+const IDLE_CAP_INF = IDLE_CAP_MAX_FRAMES + 1; // slider max → ∞ (no cap)
+
+/** Map an idle-cap (ms; 0 ⇒ ∞) to its slider position (frame units). */
+function idleCapToSlider(ms) {
+  if (!(ms > 0)) return IDLE_CAP_INF;
+  return Math.max(1, Math.min(IDLE_CAP_MAX_FRAMES, Math.round(ms / IDLE_FRAME_MS)));
+}
+
+/** Map a slider position back to an idle-cap (ms); the top stop ⇒ 0 (∞). */
+function sliderToIdleCap(pos) {
+  return pos >= IDLE_CAP_INF ? 0 : pos * IDLE_FRAME_MS;
+}
+
+/** Compact idle-cap label: ∞ for no cap, else 1.5s / 100ms / 16.7ms. */
+function fmtIdleCap(ms) {
+  if (!(ms > 0)) return '∞';
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms >= 100) return `${Math.round(ms)}ms`;
+  return `${Math.round(ms * 10) / 10}ms`;
+}
+
+/* ----------------------------------------------------------- zoom mapping */
+
+// The zoom slider is 0..1000; map it onto [MIN_PPS, MAX_PPS] on a log scale so
+// low and high zoom both get usable resolution.
+function sliderToPps(v) {
+  const t = Math.max(0, Math.min(1, Number(v) / 1000));
+  return MIN_PPS * Math.pow(MAX_PPS / MIN_PPS, t);
+}
+function ppsToSlider(pps) {
+  const clamped = Math.max(MIN_PPS, Math.min(MAX_PPS, pps));
+  const t = Math.log(clamped / MIN_PPS) / Math.log(MAX_PPS / MIN_PPS);
+  return Math.round(t * 1000);
+}
+/** Clamp a pixels-per-second zoom value to the supported range. */
+function clampPps(pps) {
+  return Math.max(MIN_PPS, Math.min(MAX_PPS, pps));
+}
+
+function relTime(ms) {
+  const diff = Date.now() - ms;
+  const s = Math.round(diff / 1000);
+  if (s < 45) return 'just now';
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.round(h / 24);
+  if (d < 7) return `${d}d ago`;
+  return new Date(ms).toLocaleDateString();
+}
+
+let toastTimer;
+function toast(msg) {
+  els.toast.textContent = msg;
+  els.toast.classList.remove('hidden');
+  clearTimeout(toastTimer);
+  toastTimer = setTimeout(() => els.toast.classList.add('hidden'), 2400);
+}
+
+/* --------------------------------------------------------------- library */
+
+// The first library scan parses every capture to count frames, so a large
+// library can take a moment. Show a spinner on that initial load only — later
+// SSE/poll refreshes happen in the background and must not flash it.
+let libraryLoaded = false;
+
+async function loadLibrary({ keepSelection = false } = {}) {
+  const firstLoad = !libraryLoaded;
+  if (firstLoad) {
+    els.libLoading.classList.remove('hidden');
+    els.libEmpty.classList.add('hidden');
+    els.libStatus.textContent = 'Loading…';
+  }
+  let data;
+  try {
+    data = await apiJson('/api/recordings');
+  } catch (e) {
+    els.libStatus.textContent = 'error';
+    els.libLoading.classList.add('hidden');
+    return;
+  } finally {
+    libraryLoaded = true;
+  }
+  els.libLoading.classList.add('hidden');
+  state.recordings = data.recordings;
+  els.libStatus.textContent = `${data.recordings.length} item${data.recordings.length === 1 ? '' : 's'}`;
+  els.library.innerHTML = '';
+  els.libEmpty.classList.toggle('hidden', data.recordings.length > 0);
+
+  for (const rec of data.recordings) {
+    const li = document.createElement('li');
+    li.className = 'rec-item';
+    li.dataset.name = rec.name;
+    if (rec.name === state.name) li.classList.add('active');
+
+    const main = document.createElement('div');
+    main.className = 'rec-main';
+    main.innerHTML =
+      `<span class="name">${rec.name}</span>` +
+      `<span class="meta"><span>${relTime(rec.mtime)}</span>` +
+      `<span>${rec.frames} frame${rec.frames === 1 ? '' : 's'}</span></span>`;
+    main.addEventListener('click', () => selectRecording(rec.name));
+
+    const actions = document.createElement('div');
+    actions.className = 'rec-actions';
+
+    const revealBtn = document.createElement('button');
+    revealBtn.className = 'rec-act';
+    revealBtn.type = 'button';
+    revealBtn.title = 'Reveal in Finder';
+    revealBtn.setAttribute('aria-label', `Reveal ${rec.name} in Finder`);
+    revealBtn.innerHTML = ICON.reveal;
+    revealBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      revealRecording(rec.name);
+    });
+
+    const renameBtn = document.createElement('button');
+    renameBtn.className = 'rec-act';
+    renameBtn.type = 'button';
+    renameBtn.title = 'Rename recording';
+    renameBtn.setAttribute('aria-label', `Rename ${rec.name}`);
+    renameBtn.innerHTML = ICON.pencil;
+    renameBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      renameRecording(rec.name);
+    });
+
+    const delBtn = document.createElement('button');
+    delBtn.className = 'rec-act danger';
+    delBtn.type = 'button';
+    delBtn.title = 'Delete recording';
+    delBtn.setAttribute('aria-label', `Delete ${rec.name}`);
+    delBtn.innerHTML = ICON.trash;
+    delBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      deleteRecording(rec.name);
+    });
+
+    actions.append(revealBtn, renameBtn, delBtn);
+    li.append(main, actions);
+    els.library.appendChild(li);
+  }
+
+  const stillThere = data.recordings.some((r) => r.name === state.name);
+  if (!keepSelection || !stillThere) {
+    if (data.recordings.length > 0) selectRecording(data.recordings[0].name);
+    else clearPreview();
+  }
+}
+
+function markActiveRecording() {
+  for (const li of els.library.children) {
+    li.classList.toggle('active', li.dataset.name === state.name);
+  }
+}
+
+async function revealRecording(name) {
+  try {
+    const res = await fetch(`/api/recordings/${encodeURIComponent(name)}/reveal`, {
+      method: 'POST',
+    });
+    if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.statusText);
+    toast('Revealed in Finder');
+  } catch (e) {
+    toast(`Reveal failed: ${e.message}`);
+  }
+}
+
+async function openCapturesFolder() {
+  try {
+    const res = await fetch('/api/open-folder', { method: 'POST' });
+    if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.statusText);
+    toast('Opened captures folder');
+  } catch (e) {
+    toast(`Open folder failed: ${e.message}`);
+  }
+}
+
+/* --------------------------------------------------------------- updates */
+
+// Filled in by checkForUpdate() so the update button knows the install kind and
+// the exact command to fall back to if an in-place update can't run.
+let updateInfo = null;
+
+// Check npm (via the local server) for a newer release on launch, and surface a
+// banner when one exists. Silent on any failure — an offline machine just won't
+// see the prompt.
+async function checkForUpdate() {
+  try {
+    updateInfo = await apiJson('/api/version');
+  } catch {
+    return;
+  }
+  if (!updateInfo || !updateInfo.updateAvailable || !updateInfo.latest) return;
+  showUpdateBanner();
+}
+
+function showUpdateBanner() {
+  const { current, latest, installKind } = updateInfo;
+  if (installKind === 'npx') {
+    // Nothing to update in place — npx always fetches the latest on demand.
+    els.updateMsg.textContent =
+      `tui-cap v${latest} is available (you're on v${current}). ` +
+      `You're running via npx — re-run \`npx tui-cap@latest\` to upgrade.`;
+    els.updateBtn.classList.add('hidden');
+  } else {
+    els.updateMsg.textContent = `A new version of tui-cap is available — v${current} → v${latest}.`;
+    els.updateBtn.classList.remove('hidden');
+  }
+  els.updateBanner.classList.remove('hidden');
+}
+
+function fallbackUpdateCommand() {
+  return (updateInfo && updateInfo.updateCommand) || 'npm install -g tui-cap@latest';
+}
+
+async function doUpdate() {
+  els.updateBtn.disabled = true;
+  els.updateBtn.textContent = 'Updating…';
+  els.updateMsg.textContent = 'Updating tui-cap… this can take up to a minute.';
+  let data = {};
+  try {
+    const res = await fetch('/api/update', { method: 'POST' });
+    data = await res.json().catch(() => ({}));
+    if (res.ok && data.ok) {
+      els.updateBtn.classList.add('hidden');
+      els.updateDismiss.textContent = 'Dismiss';
+      els.updateMsg.textContent =
+        `Updated to v${data.latest || ''} ✓  Quit tui-cap (Ctrl+C in its terminal) ` +
+        `and run it again to use the new version.`;
+      return;
+    }
+    if (data.skipped) {
+      els.updateBtn.classList.add('hidden');
+      els.updateDismiss.textContent = 'Dismiss';
+      els.updateMsg.textContent = data.message || `Re-run \`${data.command}\`.`;
+      return;
+    }
+  } catch {
+    // network error talking to the local server — fall through to manual path
+  }
+  failUpdate();
+}
+
+function failUpdate() {
+  els.updateBtn.disabled = false;
+  els.updateBtn.textContent = 'Retry';
+  const cmd = fallbackUpdateCommand();
+  els.updateMsg.textContent = `Couldn't update automatically. Run this in your terminal:  ${cmd}`;
+  toast('Update failed — copy the command shown');
+}
+
+
+async function renameRecording(name) {
+  const current = name.replace(/\.ans$/i, '');
+  const input = window.prompt(`Rename ${name} to:`, current);
+  if (input === null) return;
+  const trimmed = input.trim();
+  if (!trimmed) return;
+  const target = /\.ans$/i.test(trimmed) ? trimmed : `${trimmed}.ans`;
+  if (target === name) return;
+  const wasActive = state.name === name;
+  try {
+    const res = await fetch(`/api/recordings/${encodeURIComponent(name)}/rename`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ to: trimmed }),
+    });
+    if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.statusText);
+    const data = await res.json().catch(() => ({}));
+    const finalName = data.to || target;
+    if (wasActive) state.name = finalName;
+    await loadLibrary({ keepSelection: true });
+    if (wasActive) selectRecording(finalName);
+    toast(`Renamed to ${finalName}`);
+  } catch (e) {
+    toast(`Rename failed: ${e.message}`);
+  }
+}
+
+async function deleteRecording(name) {
+  if (!window.confirm(`Delete ${name}? This removes the capture file from your library.`)) {
+    return;
+  }
+  try {
+    const res = await fetch(`/api/recordings/${encodeURIComponent(name)}`, { method: 'DELETE' });
+    if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.statusText);
+    if (state.name === name) {
+      state.name = null;
+      clearPreview();
+    }
+    toast(`Deleted ${name}`);
+    loadLibrary({ keepSelection: true });
+  } catch (e) {
+    toast(`Delete failed: ${e.message}`);
+  }
+}
+
+/* ----------------------------------------------------------------- frames */
+
+async function selectRecording(name) {
+  state.name = name;
+  markActiveRecording();
+  await loadFrames();
+}
+
+async function loadFrames() {
+  if (!state.name) return;
+  let data;
+  try {
+    data = await apiJson(`/api/recordings/${encodeURIComponent(state.name)}/frames`);
+  } catch (e) {
+    toast(`Failed to read frames: ${e.message}`);
+    return;
+  }
+  state.frames = data.frames;
+  state.editsRevision = typeof data.editsRevision === 'number' ? data.editsRevision : 0;
+  state.hasTiming = Boolean(data.hasTiming);
+  state.animationEnd =
+    typeof data.animationEnd === 'number' ? data.animationEnd : data.frames.length - 1;
+  state.animCanvas =
+    data.animCanvas && data.animCanvas.cols && data.animCanvas.rows ? data.animCanvas : null;
+  if (data.cols && data.rows) {
+    els.recordedSize.textContent = `${data.cols} × ${data.rows}`;
+  }
+  await loadAnimationSettings();
+  state.selection = new Set();
+  buildTimeline();
+  fitTimeline();
+  setIndex(data.defaultIndex ?? state.frames.length - 1);
+  selectSingle(state.index);
+  await onRecordingEdits();
+}
+
+/* -------------------------------------------------------------- timeline */
+
+/**
+ * Build the timeline DOM once per recording: one absolutely-positioned block
+ * per frame (with a header strip and a right-edge resize handle) plus a single
+ * playhead. Positions and the SVG previews are filled in by `layoutTimeline`.
+ */
+function buildTimeline() {
+  els.timelineTrack.innerHTML = '';
+  els.timelineRuler.innerHTML = '';
+  state.blocks = [];
+
+  state.frames.forEach((f, i) => {
+    const el = document.createElement('div');
+    el.className = 'tl-frame';
+    if (f.isTyping) el.classList.add('is-typing');
+    el.dataset.index = String(i);
+
+    const head = document.createElement('div');
+    head.className = 'tl-head';
+    head.textContent = String(i + 1);
+    el.appendChild(head);
+
+    const handle = document.createElement('div');
+    handle.className = 'tl-handle';
+    handle.title = 'Drag to change this frame’s length';
+    handle.addEventListener('pointerdown', (e) => startResize(e, i));
+    el.appendChild(handle);
+
+    el.addEventListener('click', (e) => onBlockClick(e, i));
+
+    els.timelineTrack.appendChild(el);
+    state.blocks.push({ el, head, handle, img: null });
+  });
+
+  const playhead = document.createElement('div');
+  playhead.className = 'tl-playhead';
+  playhead.style.display = 'none';
+  els.timelineTrack.appendChild(playhead);
+  state.playhead = playhead;
+
+  els.timelineEmpty.classList.toggle('hidden', state.frames.length > 0);
+}
+
+/** Cumulative px boundaries for the current zoom: boundaries[i]..boundaries[i+1]. */
+function computeBoundaries() {
+  const eff = effectiveDurations();
+  const pps = state.zoom > 0 ? state.zoom : sliderToPps(0);
+  const b = new Array(state.frames.length + 1);
+  b[0] = 0;
+  let cum = 0;
+  for (let i = 0; i < state.frames.length; i++) {
+    const hidden = state.hideSkipped && isSkipped(i);
+    cum += hidden ? 0 : Math.max(0, eff[i]) / 1000;
+    b[i + 1] = Math.round(cum * pps);
+  }
+  return b;
+}
+
+/** Position every block + handle, redraw the ruler, refresh previews + playhead. */
+function layoutTimeline() {
+  if (state.frames.length === 0) return;
+  const b = computeBoundaries();
+  state.boundaries = b;
+  const total = b[b.length - 1];
+  els.timelineTrack.style.width = `${total}px`;
+  els.timelineRuler.style.width = `${total}px`;
+
+  state.blocks.forEach((blk, i) => {
+    const hidden = state.hideSkipped && isSkipped(i);
+    const left = b[i];
+    const width = Math.max(1, b[i + 1] - b[i]);
+    blk.el.style.display = hidden ? 'none' : '';
+    blk.el.style.left = `${left}px`;
+    blk.el.style.width = `${width}px`;
+    blk.width = hidden ? 0 : width;
+  });
+
+  renderRuler(total);
+  updatePreviews();
+  positionPlayhead();
+}
+
+/** Draw second/sub-second tick marks at a "nice" interval for the current zoom. */
+function renderRuler(total) {
+  const pps = state.zoom > 0 ? state.zoom : sliderToPps(0);
+  els.timelineRuler.innerHTML = '';
+  if (!isFinite(pps) || pps <= 0) return;
+  const steps = [0.05, 0.1, 0.2, 0.25, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600];
+  const targetPx = 80;
+  let step = steps[steps.length - 1];
+  for (const s of steps) {
+    if (s * pps >= targetPx) {
+      step = s;
+      break;
+    }
+  }
+  const totalSec = total / pps;
+  const frag = document.createDocumentFragment();
+  for (let t = 0; t <= totalSec + 1e-6; t += step) {
+    const x = Math.round(t * pps);
+    if (x > total) break;
+    const tick = document.createElement('div');
+    tick.className = 'tl-tick';
+    tick.style.left = `${x}px`;
+    const span = document.createElement('span');
+    span.textContent = step < 1 ? `${t.toFixed(2).replace(/0+$/, '').replace(/\.$/, '')}s` : `${Math.round(t)}s`;
+    tick.appendChild(span);
+    frag.appendChild(tick);
+  }
+  els.timelineRuler.appendChild(frag);
+}
+
+/**
+ * Mount an SVG preview inside a block only when it's wide enough to be legible
+ * and near the visible scroll window; remove previews that fall out of those
+ * bounds so we never hold hundreds of SVGs at once.
+ */
+function updatePreviews() {
+  if (state.frames.length === 0) return;
+  const scroll = els.timelineScroll;
+  const viewLeft = scroll.scrollLeft - scroll.clientWidth;
+  const viewRight = scroll.scrollLeft + scroll.clientWidth * 2;
+  state.blocks.forEach((blk, i) => {
+    const left = state.boundaries[i];
+    const right = state.boundaries[i + 1];
+    const visible = right >= viewLeft && left <= viewRight;
+    const wide = (blk.width || 0) >= PREVIEW_MIN_PX;
+    if (wide && visible) {
+      if (!blk.img) {
+        const img = document.createElement('img');
+        img.className = 'tl-prev';
+        img.loading = 'lazy';
+        img.alt = `Frame ${i + 1}`;
+        img.src = svgUrl(i);
+        blk.el.appendChild(img);
+        blk.img = img;
+      }
+    } else if (blk.img) {
+      blk.img.remove();
+      blk.img = null;
+    }
+  });
+}
+
+const onTimelineScroll = () => updatePreviews();
+
+/** X (track px) -> frame index, via binary search over the boundaries. */
+function frameAtX(x) {
+  const b = state.boundaries;
+  if (!b || b.length < 2) return 0;
+  // Clamp into the track, then find the rightmost boundary at or left of x.
+  // Collapsed (skipped) frames share a boundary with their visible neighbour, so
+  // the search naturally prefers the visible frame at a shared edge — except a
+  // run of skipped frames at the very end, which we walk back off below.
+  const xc = Math.max(0, Math.min(x, b[b.length - 1]));
+  let lo = 0;
+  let hi = b.length - 2;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (b[mid] <= xc) lo = mid;
+    else hi = mid - 1;
+  }
+  if (state.hideSkipped && isSkipped(lo)) {
+    while (lo > 0 && isSkipped(lo)) lo--;
+  }
+  return lo;
+}
+
+function setIndex(i) {
+  const n = state.frames.length;
+  if (n === 0) return clearPreview();
+  state.index = Math.max(0, Math.min(n - 1, i));
+
+  const frame = state.frames[state.index];
+  // Always the uniform canvas (not only during playback) so the window never
+  // changes size as you scrub onto a sparse frame — e.g. the tabs-only opening
+  // frames or the teardown summary. Matches the video + exports exactly.
+  els.preview.src = svgUrlFull(state.index);
+  els.preview.classList.remove('hidden');
+  els.previewEmpty.classList.add('hidden');
+
+  els.downloadBtn.disabled = false;
+  els.downloadPngBtn.disabled = false;
+  els.pngScale.disabled = false;
+  els.playBtn.disabled = false;
+  els.exportMp4Btn.disabled = false;
+  if (els.selfTestBtn) els.selfTestBtn.disabled = false;
+  els.goStartBtn.disabled = false;
+  els.prevBtn.disabled = false;
+  els.nextBtn.disabled = false;
+  els.goEndBtn.disabled = false;
+  els.zoom.disabled = false;
+  els.fitBtn.disabled = false;
+  els.hideSkippedBtn.disabled = false;
+  syncHideSkippedBtn();
+  updateViewScaleButtons();
+
+  state.blocks.forEach((blk, idx) => blk.el.classList.toggle('current', idx === state.index));
+  scrollFrameIntoView(state.index);
+  positionPlayhead();
+  updateFrameLabel();
+
+  // Keep the content-edit overlay in sync with the newly shown frame: close any
+  // open inline editor and re-measure cells for the new frame's grid/text.
+  if (ed.on && !play.on) {
+    closePopover();
+    fetchCells(state.index).then(positionOverlay);
+  }
+}
+
+/** Keep the given frame within the horizontal scroll viewport. */
+function scrollFrameIntoView(i) {
+  const b = state.boundaries;
+  if (!b || b.length < 2) return;
+  const scroll = els.timelineScroll;
+  const left = b[i];
+  const right = b[i + 1];
+  if (left < scroll.scrollLeft) scroll.scrollLeft = Math.max(0, left - 16);
+  else if (right > scroll.scrollLeft + scroll.clientWidth) {
+    scroll.scrollLeft = right - scroll.clientWidth + 16;
+  }
+}
+
+/** Place the playhead at a px position (defaults to the current frame's start). */
+function positionPlayhead(px) {
+  if (!state.playhead || state.frames.length === 0) return;
+  const b = state.boundaries;
+  const x = typeof px === 'number' ? px : b && b.length ? b[state.index] : 0;
+  state.playhead.style.display = '';
+  state.playhead.style.left = `${x}px`;
+}
+
+function updateFrameLabel() {
+  const n = state.frames.length;
+  if (n === 0) {
+    els.frameLabel.textContent = '—';
+    return;
+  }
+  els.frameLabel.textContent =
+    state.selection.size > 1
+      ? `${state.selection.size} selected`
+      : `Frame ${state.index + 1} of ${n}`;
+}
+
+/* ------------------------------------------------------------- scrub */
+
+/**
+ * Click or drag on the ruler to scrub: moves the playhead to the cursor and
+ * updates the current frame + big preview live. Pure navigation — it interrupts
+ * playback but deliberately leaves the multi-frame selection untouched.
+ */
+function startScrub(e) {
+  if (state.frames.length === 0) return;
+  e.preventDefault();
+  stopPlay();
+  els.timelineScroll.classList.add('dragging');
+
+  let lastIdx = -1;
+  const seekToClientX = (clientX) => {
+    const x = clientX - els.timelineRuler.getBoundingClientRect().left;
+    const i = frameAtX(x);
+    if (i !== lastIdx) {
+      setIndex(i);
+      lastIdx = i;
+    }
+    positionPlayhead(Math.max(0, x));
+  };
+  seekToClientX(e.clientX);
+
+  const onMove = (ev) => seekToClientX(ev.clientX);
+  const onUp = () => {
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', onUp);
+    els.timelineScroll.classList.remove('dragging');
+    positionPlayhead(); // settle the playhead onto the frame's start boundary
+  };
+  window.addEventListener('pointermove', onMove);
+  window.addEventListener('pointerup', onUp);
+}
+
+/* ----------------------------------------------------------- selection */
+
+function onBlockClick(e, i) {
+  // Ignore the click that can follow a drag-resize. Using a short time window
+  // (rather than a sticky flag) means a drag whose pointerup lands off the block
+  // — so no click fires to clear the flag — can never eat a later real click.
+  if (Date.now() - (state.dragEndedAt || 0) < 250) return;
+  e.preventDefault();
+  if (e.shiftKey) selectRange(state.anchor, i);
+  else if (e.metaKey || e.ctrlKey) selectToggle(i);
+  else selectSingle(i);
+}
+
+function selectSingle(i) {
+  stopPlay();
+  state.selection = new Set([i]);
+  state.anchor = i;
+  setIndex(i);
+  updateFrameStates();
+  updateSelectionUI();
+}
+
+function selectToggle(i) {
+  stopPlay();
+  if (state.selection.has(i)) {
+    state.selection.delete(i);
+    if (state.selection.size === 0) state.selection.add(i);
+  } else {
+    state.selection.add(i);
+  }
+  state.anchor = i;
+  setIndex(i);
+  updateFrameStates();
+  updateSelectionUI();
+}
+
+function selectRange(a, b) {
+  stopPlay();
+  const lo = Math.min(a, b);
+  const hi = Math.max(a, b);
+  state.selection = new Set();
+  for (let i = lo; i <= hi; i++) state.selection.add(i);
+  setIndex(b);
+  updateFrameStates();
+  updateSelectionUI();
+}
+
+/** Sorted array of the currently selected frame indices. */
+function selectedIndices() {
+  return Array.from(state.selection).sort((a, b) => a - b);
+}
+
+/* ------------------------------------------------------ marquee select */
+
+/**
+ * Shift + drag across the track brush-selects every frame the pointer sweeps
+ * over, deliberately bypassing the per-frame resize handles so frames stay
+ * selectable when zoomed out (where each block is mostly handle). A shift+click
+ * with no drag instead extends the selection from the previously-anchored frame
+ * to the one clicked — the classic "click one frame, scroll elsewhere, shift-
+ * click another to grab the whole span" gesture — so both gestures coexist.
+ */
+function startMarquee(e) {
+  stopPlay();
+  const trackLeft = () => els.timelineTrack.getBoundingClientRect().left;
+  const startIdx = frameAtX(e.clientX - trackLeft());
+  // Preserve the prior anchor up front: we don't yet know if this is a click or
+  // a drag, and a shift+CLICK must extend from the last-anchored frame. Touching
+  // the selection now (as the old code did via selectSingle) would clobber that
+  // anchor and collapse the range to a single frame.
+  const rangeAnchor = state.selection.size > 0 ? state.anchor : startIdx;
+  els.timelineScroll.classList.add('selecting');
+  let moved = false;
+  let lastEnd = startIdx;
+
+  const onMove = (ev) => {
+    const idx = frameAtX(ev.clientX - trackLeft());
+    // Frame-quantised drag threshold: ignore jitter until the pointer actually
+    // leaves the start frame, so a shaky shift+click isn't misread as a one-
+    // frame marquee (which would drop the extend-from-anchor behaviour).
+    if (!moved && idx === startIdx) return;
+    if (!moved) {
+      moved = true;
+      state.anchor = startIdx; // a real drag re-anchors at where it began
+    }
+    if (idx === lastEnd) return;
+    lastEnd = idx;
+    selectRange(startIdx, idx); // brush from the drag origin to the pointer
+  };
+  const onUp = () => {
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', onUp);
+    els.timelineScroll.classList.remove('selecting');
+    if (moved) {
+      // A drag happened: suppress the click it spawns so it can't collapse the
+      // brush selection (onBlockClick ignores clicks within 250ms of this).
+      state.dragEndedAt = Date.now();
+    } else {
+      // No drag → shift+click range-select from the preserved anchor to here.
+      // Done here (not left to onBlockClick) so it also works when the pointer
+      // up lands in a gap between blocks; the duplicate block click is swallowed
+      // via dragEndedAt. The anchor stays put so further shift+clicks re-extend.
+      selectRange(rangeAnchor, startIdx);
+      state.anchor = rangeAnchor;
+      state.dragEndedAt = Date.now();
+    }
+  };
+  window.addEventListener('pointermove', onMove);
+  window.addEventListener('pointerup', onUp);
+}
+
+/** Toolbar selection group: visibility, the length input, and its label. */
+function updateSelectionUI() {
+  const sel = selectedIndices();
+  els.selGroup.classList.toggle('hidden', sel.length === 0);
+  updateFrameLabel();
+  if (sel.length === 0) return;
+
+  const eff = effectiveDurations();
+  const vals = sel.map((i) => Math.round(eff[i]));
+  const allSame = vals.every((v) => v === vals[0]);
+  if (document.activeElement !== els.selLen) {
+    els.selLen.value = allSame ? String(vals[0]) : '';
+    els.selLen.placeholder = allSame ? '' : 'multiple';
+  }
+  els.selLenLabel.textContent = sel.length > 1 ? `Length ×${sel.length}` : 'Length';
+
+  const anySkipped = sel.some((i) => isSkipped(i));
+  els.selDelete.textContent = anySkipped ? 'Restore' : 'Delete';
+}
+
+/* ------------------------------------------------------- frame editing */
+
+function setOverrideFor(i, ms) {
+  state.settings.overrides[String(i)] = Math.max(0, Math.min(600000, Math.round(ms)));
+}
+
+/** Apply a single length (ms) to every selected frame as an override. */
+function applyLengthToSelection(ms) {
+  const sel = selectedIndices();
+  if (sel.length === 0 || !isFinite(ms)) return;
+  for (const i of sel) setOverrideFor(i, ms);
+  updateAnimUI();
+  saveAnimationSettings();
+}
+
+/** Clear duration overrides on the selection (back to captured timing). */
+function resetSelection() {
+  for (const i of selectedIndices()) delete state.settings.overrides[String(i)];
+  updateAnimUI();
+  saveAnimationSettings();
+}
+
+/** Toggle skip on the selection: skip all, or restore if any are already skipped. */
+function toggleSkipSelection() {
+  const sel = selectedIndices();
+  if (sel.length === 0) return;
+  const anySkipped = sel.some((i) => isSkipped(i));
+  for (const i of sel) {
+    if (anySkipped) state.skipped.delete(i);
+    else state.skipped.add(i);
+  }
+  state.settings.skipped = Array.from(state.skipped).sort((a, b) => a - b);
+  stopPlay();
+  updateAnimUI();
+  saveAnimationSettings();
+}
+
+/* ------------------------------------------------------------- zoom */
+
+/**
+ * Re-zoom the timeline, keeping one focal point fixed on screen so the content
+ * appears to scale around it. Pass either:
+ *   - { anchorPx, anchorScreenX }: pin the track px `anchorPx` (measured under
+ *     the CURRENT zoom) at `anchorScreenX` px from the viewport's left edge.
+ *     Used to anchor on the playhead (slider) or the cursor (wheel/pinch).
+ *   - { anchorRatio }: keep the time under a viewport-relative point fixed.
+ */
+function setZoom(pps, { anchorRatio = null, anchorPx = null, anchorScreenX = null } = {}) {
+  const scroll = els.timelineScroll;
+  const oldZoom = state.zoom;
+  // Resolve the focal point to a (trackPx, screenX) pair under the old zoom.
+  let trackPx = null;
+  let screenX = null;
+  if (anchorPx != null) {
+    trackPx = anchorPx;
+    screenX = anchorScreenX != null ? anchorScreenX : anchorPx - scroll.scrollLeft;
+  } else if (anchorRatio != null) {
+    screenX = scroll.clientWidth * anchorRatio;
+    trackPx = scroll.scrollLeft + screenX;
+  }
+  const focusTime = trackPx != null && oldZoom > 0 ? trackPx / oldZoom : null;
+
+  state.zoom = clampPps(pps);
+  els.zoom.value = String(ppsToSlider(state.zoom));
+  layoutTimeline();
+
+  if (focusTime != null) {
+    scroll.scrollLeft = Math.max(0, focusTime * state.zoom - screenX);
+    updatePreviews();
+  }
+}
+
+/**
+ * Zoom focal point that keeps the playhead pinned where it currently sits on
+ * screen, so slider zoom stays centred on the scrub position. Falls back to the
+ * viewport centre when the playhead has been scrolled out of view.
+ */
+function playheadZoomAnchor() {
+  const scroll = els.timelineScroll;
+  const b = state.boundaries;
+  if (!b || b.length < 2 || !(state.zoom > 0)) return { anchorRatio: 0.5 };
+  const px = b[state.index];
+  const screenX = px - scroll.scrollLeft;
+  if (screenX < 0 || screenX > scroll.clientWidth) {
+    return { anchorPx: px, anchorScreenX: scroll.clientWidth / 2 };
+  }
+  return { anchorPx: px, anchorScreenX: screenX };
+}
+
+// Pinch (trackpad) and ⌘/Ctrl + wheel over the timeline zoom toward the cursor.
+const ZOOM_WHEEL_SENS = 0.0025;
+function onTimelineWheel(e) {
+  if (state.frames.length === 0) return;
+  if (!(e.ctrlKey || e.metaKey)) return; // plain scroll stays horizontal scroll
+  e.preventDefault();
+  const scroll = els.timelineScroll;
+  let dy = e.deltaY;
+  if (e.deltaMode === 1) dy *= 16; // lines → ~px
+  else if (e.deltaMode === 2) dy *= scroll.clientHeight; // pages → ~px
+  const cur = state.zoom > 0 ? state.zoom : sliderToPps(Number(els.zoom.value));
+  const next = clampPps(cur * Math.exp(-dy * ZOOM_WHEEL_SENS));
+  if (next === cur) return;
+  const screenX = e.clientX - scroll.getBoundingClientRect().left;
+  setZoom(next, { anchorPx: scroll.scrollLeft + screenX, anchorScreenX: screenX });
+}
+
+/** Set zoom so the whole timeline fits the visible width. */
+function fitTimeline() {
+  const eff = effectiveDurations();
+  const totalSec = eff.reduce((a, d) => a + Math.max(0, d), 0) / 1000;
+  const w = Math.max(40, els.timelineScroll.clientWidth - 4);
+  const pps = totalSec > 0 ? w / totalSec : MAX_PPS;
+  els.timelineScroll.scrollLeft = 0;
+  setZoom(pps);
+}
+
+/* ------------------------------------------------------- drag to resize */
+
+/**
+ * Drag a block's right edge to change that single frame's length. Converts the
+ * horizontal drag distance to ms via the current zoom and writes it as a
+ * duration override (overrides bypass the cap/speed — an explicit user length).
+ */
+function startResize(e, i) {
+  if (e.shiftKey) return; // shift = marquee select, not resize (see startMarquee)
+  e.preventDefault();
+  e.stopPropagation();
+  stopPlay();
+  // Grabbing a frame's edge makes it the active single selection so the header
+  // length readout tracks the frame being resized.
+  if (!(state.selection.size === 1 && state.selection.has(i))) selectSingle(i);
+  const eff = effectiveDurations();
+  const startMs = eff[i];
+  const startX = e.clientX;
+  const pps = state.zoom > 0 ? state.zoom : sliderToPps(0);
+  els.timelineScroll.classList.add('dragging');
+  let moved = false;
+
+  const onMove = (ev) => {
+    const deltaMs = ((ev.clientX - startX) / pps) * 1000;
+    if (Math.abs(ev.clientX - startX) > 2) moved = true;
+    setOverrideFor(i, Math.max(0, startMs + deltaMs));
+    layoutTimeline();
+    updateFrameStates();
+    updateSelectionUI();
+  };
+  const onUp = () => {
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', onUp);
+    els.timelineScroll.classList.remove('dragging');
+    // Mark the drag end so the click it may spawn is ignored (see onBlockClick).
+    if (moved) state.dragEndedAt = Date.now();
+    saveAnimationSettings();
+  };
+  window.addEventListener('pointermove', onMove);
+  window.addEventListener('pointerup', onUp);
+}
+
+function clearPreview() {
+  stopPlay();
+  state.frames = [];
+  state.index = 0;
+  state.hasTiming = false;
+  state.animationEnd = 0;
+  state.animCanvas = null;
+  state.blocks = [];
+  state.boundaries = [];
+  state.selection = new Set();
+  state.skipped = new Set();
+  els.preview.classList.add('hidden');
+  els.preview.removeAttribute('src');
+  els.previewEmpty.classList.remove('hidden');
+  els.frameLabel.textContent = '—';
+  els.timelineTrack.innerHTML = '';
+  els.timelineRuler.innerHTML = '';
+  els.timelineTrack.style.width = '';
+  els.timelineRuler.style.width = '';
+  els.timelineEmpty.classList.remove('hidden');
+  els.selGroup.classList.add('hidden');
+  els.downloadBtn.disabled = true;
+  els.downloadPngBtn.disabled = true;
+  els.pngScale.disabled = true;
+  els.playBtn.disabled = true;
+  els.exportMp4Btn.disabled = true;
+  if (els.selfTestBtn) els.selfTestBtn.disabled = true;
+  els.goStartBtn.disabled = true;
+  els.prevBtn.disabled = true;
+  els.nextBtn.disabled = true;
+  els.goEndBtn.disabled = true;
+  els.zoom.disabled = true;
+  els.fitBtn.disabled = true;
+  // Reset the canvas back to Zoom-to-Fit and disable the scale controls.
+  state.viewMode = 'fit';
+  state.zoomScale = 1;
+  els.previewWrap.classList.remove('scaled');
+  els.preview.style.width = '';
+  els.preview.style.height = '';
+  els.zoomFitBtn.setAttribute('aria-pressed', 'true');
+  els.zoom100Btn.setAttribute('aria-pressed', 'false');
+  els.zoomFitBtn.disabled = true;
+  els.zoom100Btn.disabled = true;
+  els.zoomRange.disabled = true;
+  els.zoomRange.value = '100';
+  els.zoomPct.textContent = '100%';
+  els.recordedSize.textContent = '—';
+  els.animLen.textContent = '—';
+  els.animStatus.textContent = '';
+  els.animNote.classList.add('hidden');
+  els.clearOverrides.classList.add('hidden');
+
+  // Tear down any content-edit overlay/popover for the (now absent) recording.
+  ed.cells = null;
+  closePopover();
+  edEls.overlay.classList.add('hidden');
+  edEls.hover.classList.add('hidden');
+  edEls.section.classList.add('hidden');
+}
+
+/* ------------------------------------------------------- canvas view scale */
+
+// Canvas zoom bounds (factors). The slider is expressed in whole percent.
+const ZOOM_MIN = 0.1;
+const ZOOM_MAX = 4;
+const clampZoom = (s) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, s));
+
+/** Natural (1:1) pixel size of the rendered canvas, or null until it loads. */
+function previewBaseSize() {
+  const img = els.preview;
+  const w = img.naturalWidth;
+  const h = img.naturalHeight;
+  return w && h ? { w, h } : null;
+}
+
+/** The scale Zoom-to-Fit resolves to (how `contain` sizes the canvas; ≤ 1). */
+function computeFitScale() {
+  const base = previewBaseSize();
+  if (!base) return 1;
+  const wrap = els.previewWrap;
+  const cs = getComputedStyle(wrap);
+  const padX = parseFloat(cs.paddingLeft) + parseFloat(cs.paddingRight);
+  const padY = parseFloat(cs.paddingTop) + parseFloat(cs.paddingBottom);
+  const availW = wrap.clientWidth - padX;
+  const availH = wrap.clientHeight - padY;
+  if (availW <= 0 || availH <= 0) return 1;
+  return Math.min(availW / base.w, availH / base.h, 1);
+}
+
+/** The scale currently shown on the canvas (explicit zoom, or the fit scale). */
+function currentScale() {
+  return state.viewMode === 'zoom' ? state.zoomScale : computeFitScale();
+}
+
+/** Sync the zoom slider + percentage label to the active scale. */
+function updateZoomReadout() {
+  const pct = Math.round(currentScale() * 100);
+  els.zoomPct.textContent = `${pct}%`;
+  // Don't fight the user mid-drag; the slider is the source of truth then.
+  if (document.activeElement !== els.zoomRange) {
+    const clamped = Math.round(clampZoom(pct / 100) * 100);
+    els.zoomRange.value = String(clamped);
+  }
+}
+
+/** Reflect the active scale mode on the canvas, header buttons, and slider. */
+function applyViewMode() {
+  const zoom = state.viewMode === 'zoom';
+  els.previewWrap.classList.toggle('scaled', zoom);
+  const img = els.preview;
+  if (zoom) {
+    const base = previewBaseSize();
+    if (base) {
+      img.style.width = `${Math.round(base.w * state.zoomScale)}px`;
+      img.style.height = `${Math.round(base.h * state.zoomScale)}px`;
+    }
+  } else {
+    img.style.width = '';
+    img.style.height = '';
+  }
+  els.zoomFitBtn.setAttribute('aria-pressed', zoom ? 'false' : 'true');
+  els.zoom100Btn.setAttribute('aria-pressed', zoom && Math.abs(state.zoomScale - 1) < 1e-3 ? 'true' : 'false');
+  updateZoomReadout();
+  // Keep the content-edit overlay aligned with the resized image.
+  if (ed.on) positionOverlay();
+}
+
+/** Zoom-to-Fit: let the canvas shrink to fit the viewport (no scroll). */
+function fitCanvas() {
+  state.viewMode = 'fit';
+  applyViewMode();
+}
+
+/** Zoom to an explicit factor, keeping the viewport centre stable. */
+function setCanvasZoom(scale, { center = false } = {}) {
+  state.zoomScale = clampZoom(scale);
+  state.viewMode = 'zoom';
+  const wrap = els.previewWrap;
+  // Remember the content point under the viewport centre so the zoom feels
+  // anchored there rather than jumping to the top-left.
+  const cx = (wrap.scrollLeft + wrap.clientWidth / 2) / Math.max(1, wrap.scrollWidth);
+  const cy = (wrap.scrollTop + wrap.clientHeight / 2) / Math.max(1, wrap.scrollHeight);
+  applyViewMode();
+  if (center) {
+    wrap.scrollLeft = Math.max(0, (wrap.scrollWidth - wrap.clientWidth) / 2);
+    wrap.scrollTop = Math.max(0, (wrap.scrollHeight - wrap.clientHeight) / 2);
+  } else {
+    wrap.scrollLeft = cx * wrap.scrollWidth - wrap.clientWidth / 2;
+    wrap.scrollTop = cy * wrap.scrollHeight - wrap.clientHeight / 2;
+  }
+}
+
+/** Scale controls are usable only while a frame is on the canvas. */
+function updateViewScaleButtons() {
+  const has = state.frames.length > 0;
+  els.zoomFitBtn.disabled = !has;
+  els.zoom100Btn.disabled = !has;
+  els.zoomRange.disabled = !has;
+}
+
+/** Re-fetch images after a render-only option change (preview + mounted blocks). */
+function refreshImages() {
+  if (state.frames.length === 0) return;
+  els.preview.src = svgUrlFull(state.index);
+  state.blocks.forEach((blk, i) => {
+    if (blk.img) blk.img.src = svgUrl(i);
+  });
+  if (ed.on) {
+    // Geometry (font size, chrome, spacing) may have changed — re-measure cells.
+    fetchCells(state.index).then(positionOverlay);
+  }
+}
+
+/* ----------------------------------------------------------------- export */
+
+/**
+ * Save a blob to disk. Prefers the File System Access "Save As" dialog so the
+ * user chooses the folder and filename; falls back to a normal anchor download
+ * (the browser's default location) where that API isn't available, e.g. Firefox
+ * or Safari. Returns false only when the user explicitly cancels the dialog.
+ */
+async function saveBlob(blob, suggestedName, types) {
+  if (window.showSaveFilePicker) {
+    try {
+      const handle = await window.showSaveFilePicker({ suggestedName, types });
+      const writable = await handle.createWritable();
+      await writable.write(blob);
+      await writable.close();
+      return true;
+    } catch (e) {
+      if (e && e.name === 'AbortError') return false; // user cancelled
+      // Any other failure (permissions, etc.) falls through to a plain download.
+    }
+  }
+  triggerDownload(blob, suggestedName);
+  return true;
+}
+
+/** Fetch the current frame's SVG and save it via the Save As dialog. */
+async function downloadSvg() {
+  if (!state.name) return;
+  els.downloadBtn.disabled = true;
+  try {
+    const res = await fetch(svgUrlFull(state.index));
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    const svgText = await res.text();
+    const blob = new Blob([svgText], { type: 'image/svg+xml' });
+    const filename = `${exportBaseName()}.svg`;
+    const saved = await saveBlob(blob, filename, [
+      { description: 'SVG image', accept: { 'image/svg+xml': ['.svg'] } },
+    ]);
+    if (saved) toast(`Saved ${filename}`);
+  } catch (e) {
+    toast(`SVG export failed: ${e.message}`);
+  } finally {
+    els.downloadBtn.disabled = state.frames.length === 0;
+  }
+}
+
+/** Filesystem-safe base name for an export, e.g. "copilot-capture_12-frame64". */
+function exportBaseName() {
+  const stem = (state.name || 'capture').replace(/\.ans$/i, '');
+  return `${stem}-frame${state.index + 1}`;
+}
+
+function triggerDownload(blob, filename) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/**
+ * Rasterize the current frame's SVG to a PNG entirely in the browser, at the
+ * chosen pixel scale, and download it. Going through the same SVG the preview
+ * shows keeps the PNG byte-for-byte consistent with what's on screen; the SVG
+ * references only system monospace fonts, so an offscreen <canvas> renders it
+ * faithfully without tainting (same-origin, no external resources).
+ */
+async function downloadPng() {
+  if (!state.name) return;
+  const scale = Number(els.pngScale.value) || 2;
+  els.downloadPngBtn.disabled = true;
+  let blobUrl;
+  try {
+    const res = await fetch(svgUrlFull(state.index));
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    const svgText = await res.text();
+    blobUrl = URL.createObjectURL(new Blob([svgText], { type: 'image/svg+xml' }));
+
+    const img = new Image();
+    await new Promise((resolve, reject) => {
+      img.onload = resolve;
+      img.onerror = () => reject(new Error('could not rasterize the SVG'));
+      img.src = blobUrl;
+    });
+
+    // Prefer the SVG's declared px dimensions; fall back to the loaded image.
+    const dims = svgText.match(/<svg[^>]*\bwidth="(\d+(?:\.\d+)?)"[^>]*\bheight="(\d+(?:\.\d+)?)"/);
+    const w = dims ? Number(dims[1]) : img.naturalWidth;
+    const h = dims ? Number(dims[2]) : img.naturalHeight;
+    if (!w || !h) throw new Error('unknown SVG size');
+
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.round(w * scale);
+    canvas.height = Math.round(h * scale);
+    const ctx = canvas.getContext('2d');
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+
+    const pngBlob = await new Promise((resolve, reject) => {
+      canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('PNG encode failed'))), 'image/png');
+    });
+    const filename = `${exportBaseName()}@${scale}x.png`;
+    const saved = await saveBlob(pngBlob, filename, [
+      { description: 'PNG image', accept: { 'image/png': ['.png'] } },
+    ]);
+    if (saved) toast(`Saved ${filename} (${scale}×, ${canvas.width}×${canvas.height})`);
+  } catch (e) {
+    toast(`PNG export failed: ${e.message}`);
+  } finally {
+    if (blobUrl) URL.revokeObjectURL(blobUrl);
+    els.downloadPngBtn.disabled = state.frames.length === 0;
+  }
+}
+
+/* --------------------------------------------------------- animation */
+
+/** Manual navigation that should interrupt playback and update the selection. */
+function userSeek(i) {
+  if (state.frames.length === 0) return;
+  selectSingle(Math.max(0, Math.min(state.frames.length - 1, i)));
+}
+
+async function loadAnimationSettings() {
+  const fallback = { fps: 30, scale: 2, idleCapMs: 1500, speed: 1, overrides: {}, skipped: [], smoothTyping: false, typingCps: 30 };
+  let s = fallback;
+  try {
+    const data = await apiJson(`/api/recordings/${encodeURIComponent(state.name)}/animation`);
+    if (data && data.settings) s = data.settings;
+  } catch {
+    /* keep fallback */
+  }
+  state.settings = {
+    fps: s.fps ?? 30,
+    scale: s.scale ?? 2,
+    idleCapMs: s.idleCapMs ?? 1500,
+    speed: s.speed ?? 1,
+    overrides: s.overrides && typeof s.overrides === 'object' ? { ...s.overrides } : {},
+    skipped: Array.isArray(s.skipped) ? s.skipped.slice() : [],
+    smoothTyping: typeof s.smoothTyping === 'boolean' ? s.smoothTyping : false,
+    typingCps: s.typingCps ?? 30,
+  };
+  state.skipped = new Set(state.settings.skipped);
+  applySettingsToControls();
+}
+
+const saveAnimationSettings = debounce(async () => {
+  if (!state.name) return;
+  try {
+    await fetch(`/api/recordings/${encodeURIComponent(state.name)}/animation`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(state.settings),
+    });
+  } catch {
+    /* settings autosave is best-effort */
+  }
+}, 400);
+
+function applySettingsToControls() {
+  const s = state.settings;
+  els.animFps.value = String(s.fps);
+  els.animScale.value = String(s.scale);
+  els.idleCap.value = String(idleCapToSlider(s.idleCapMs));
+  els.idleCapVal.textContent = fmtIdleCap(s.idleCapMs);
+  els.speed.value = String(s.speed);
+  els.speedVal.textContent = `${Number(s.speed).toFixed(2).replace(/0$/, '')}×`;
+  els.smoothTyping.checked = !!s.smoothTyping;
+  els.typingCps.value = String(s.typingCps);
+  els.typingCpsVal.textContent = `${s.typingCps} cps`;
+  els.typingCps.disabled = !s.smoothTyping;
+}
+
+/** Reset all per-frame edits: duration overrides AND skips. */
+function clearAllOverrides() {
+  state.settings.overrides = {};
+  state.skipped = new Set();
+  state.settings.skipped = [];
+  updateAnimUI();
+  saveAnimationSettings();
+}
+
+/** Per-block visual states + the animation readouts (length, note, status). */
+function updateFrameStates() {
+  if (state.frames.length === 0) return;
+  const overrides = state.settings.overrides;
+  let overrideCount = 0;
+  state.blocks.forEach((blk, i) => {
+    const has = Object.prototype.hasOwnProperty.call(overrides, String(i));
+    if (has) overrideCount++;
+    blk.el.classList.toggle('overridden', has);
+    blk.el.classList.toggle('excluded', i > state.animationEnd);
+    blk.el.classList.toggle('skipped', isSkipped(i));
+    blk.el.classList.toggle('selected', state.selection.has(i));
+    blk.el.classList.toggle('current', i === state.index);
+  });
+
+  const eff = effectiveDurations();
+  const range = animRange();
+  const totalMs = range.reduce((sum, i) => sum + eff[i], 0);
+  els.animLen.textContent = `${(totalMs / 1000).toFixed(1)}s · ${range.length} frame${range.length === 1 ? '' : 's'}`;
+  els.clearOverrides.classList.toggle('hidden', overrideCount === 0 && state.skipped.size === 0);
+
+  if (!state.hasTiming) {
+    els.animNote.textContent = `No timing captured — using a uniform ${UNIFORM_FRAME_MS / 1000}s per frame. Re-record to capture real timing.`;
+    els.animNote.classList.remove('hidden');
+  } else {
+    els.animNote.classList.add('hidden');
+  }
+  els.animStatus.textContent = state.settings.scale ? `${state.settings.scale}× · ${state.settings.fps}fps` : '';
+}
+
+/** Full refresh after a timing/zoom/skip change: re-layout, re-state, re-select. */
+function updateAnimUI() {
+  if (state.frames.length === 0) return;
+  layoutTimeline();
+  updateFrameStates();
+  updateSelectionUI();
+}
+
+/* ------------------------------------------------------ play controller */
+
+/** Format ms compactly: 38ms / 1.24s. */
+function fmtMs(ms) {
+  if (!isFinite(ms)) return '—';
+  const a = Math.abs(ms);
+  if (a >= 1000) return `${(ms / 1000).toFixed(2)}s`;
+  return `${Math.round(ms)}ms`;
+}
+
+/** Signed ms for the drift line: +123ms / -40ms / 0ms. */
+function fmtSigned(ms) {
+  if (!isFinite(ms)) return '—';
+  const r = Math.round(ms);
+  return `${r > 0 ? '+' : ''}${r}ms`;
+}
+
+/**
+ * Paint the live timing HUD from the current telemetry. Null-guarded so the play
+ * loop can call it whether or not the HUD markup is present / enabled. `rec` is
+ * the frame that just swapped in (null when playback stops).
+ */
+function renderHud(rec) {
+  const hud = document.getElementById('hud');
+  if (!hud || hud.classList.contains('hidden')) return;
+  const tel = play.telemetry;
+  const set = (id, txt) => {
+    const el = document.getElementById(id);
+    if (el) el.textContent = txt;
+  };
+
+  set('hudState', play.on ? '● playing' : '⏸ paused');
+  const hs = document.getElementById('hudState');
+  if (hs) hs.classList.toggle('live', play.on);
+
+  if (!tel || tel.records.length === 0) {
+    ['hudFrame', 'hudThis', 'hudActual', 'hudFps', 'hudElapsed', 'hudDrift'].forEach((id) =>
+      set(id, '—'),
+    );
+  } else {
+    const recs = tel.records;
+    const cur = rec || recs[recs.length - 1];
+    const total = tel.rangeLen || recs.length;
+    set('hudFrame', `#${cur.idx}  (${cur.pos % total}/${total})`);
+    set('hudThis', `raw ${fmtMs(cur.raw)} · eff ${fmtMs(cur.eff)} · hold ${fmtMs(cur.hold)}`);
+
+    const done = recs.filter((r) => r.shownMs != null);
+    const last = done[done.length - 1];
+    set('hudActual', last ? `${fmtMs(last.shownMs)} (target ${fmtMs(last.hold)})` : '—');
+
+    // Rolling FPS over the last 12 completed frames.
+    const win = done.slice(-12);
+    const winMs = win.reduce((a, r) => a + r.shownMs, 0);
+    set('hudFps', win.length && winMs > 0 ? `${((win.length / winMs) * 1000).toFixed(1)} fps` : '—');
+
+    const actual = done.reduce((a, r) => a + r.shownMs, 0);
+    const expected = done.reduce((a, r) => a + r.hold, 0);
+    set('hudElapsed', `${fmtMs(actual)} actual / ${fmtMs(expected)} target`);
+    const drift = actual - expected;
+    set('hudDrift', `${fmtSigned(drift)}${expected > 0 ? ` (${((drift / expected) * 100).toFixed(1)}%)` : ''}`);
+    const hd = document.getElementById('hudDrift');
+    if (hd) hd.classList.toggle('warn', Math.abs(drift) > 250 && expected > 0);
+  }
+
+  const s = state.settings;
+  set(
+    'hudSettings',
+    `speed ${s.speed}× · idle-cap ${fmtIdleCap(s.idleCapMs)} · ${s.fps}fps · floor ${PLAYBACK_MIN_MS}ms`,
+  );
+}
+
+const play = {
+  on: false,
+  timer: null,
+  raf: null,
+  telemetry: null, // per-run frame timing log, read by the HUD + window.__timing
+  stopAtEnd: false, // self-test: stop after one full pass instead of looping
+  onComplete: null,
+};
+
+function updatePlayBtn() {
+  els.playBtn.innerHTML = play.on ? ICON.pause : ICON.play;
+  els.playBtn.classList.toggle('playing', play.on);
+  els.playBtn.title = play.on ? 'Pause (space)' : 'Play animation (space)';
+  els.playBtn.setAttribute('aria-label', play.on ? 'Pause' : 'Play animation');
+}
+
+/** Finalize the on-screen duration of the frame currently showing (called when
+ *  the next frame swaps in, and when playback stops). */
+function closeTelemetryFrame(now) {
+  const tel = play.telemetry;
+  if (!tel || tel.records.length === 0) return;
+  const last = tel.records[tel.records.length - 1];
+  if (last.shownMs == null) last.shownMs = now - last.shownAt;
+}
+
+/** Aggregate the recorded run into the numbers the HUD + tests assert on. */
+function timingSummary(tel) {
+  if (!tel) return null;
+  const recs = tel.records.filter((r) => r.shownMs != null);
+  const n = recs.length;
+  const actualMs = recs.reduce((a, r) => a + r.shownMs, 0);
+  const expectedMs = recs.reduce((a, r) => a + r.hold, 0); // floored playback target
+  const readoutMs = recs.reduce((a, r) => a + r.eff, 0); // raw effective (the length readout)
+  let worst = 0;
+  for (const r of recs) {
+    const d = r.shownMs - r.hold;
+    if (Math.abs(d) > Math.abs(worst)) worst = d;
+  }
+  return {
+    frames: n,
+    actualMs,
+    expectedMs,
+    readoutMs,
+    driftMs: actualMs - expectedMs,
+    worstFrameMs: worst,
+    fps: actualMs > 0 ? (n / actualMs) * 1000 : 0,
+    loops: tel.loops,
+    settings: {
+      idleCapMs: state.settings.idleCapMs,
+      speed: state.settings.speed,
+      fps: state.settings.fps,
+    },
+  };
+}
+
+async function startPlay() {
+  if (play.on || state.frames.length === 0) return;
+  const range = animRange();
+  if (range.length === 0) return;
+  play.on = true;
+  updatePlayBtn();
+
+  // Preload the untrimmed frames so swaps during playback are instant.
+  await Promise.all(
+    range.map(
+      (i) =>
+        new Promise((res) => {
+          const im = new Image();
+          im.onload = im.onerror = res;
+          im.src = svgUrlFull(i);
+        }),
+    ),
+  );
+  if (!play.on) return; // stopped while preloading
+
+  const eff = effectiveDurations();
+  play.telemetry = {
+    records: [],
+    loops: 0,
+    startedAt: 0,
+    fps: state.settings.fps,
+    rangeLen: range.length,
+  };
+  let k = range.indexOf(state.index);
+  if (k < 0) k = 0;
+
+  // Deadline-based scheduling: each frame has an absolute deadline measured from
+  // the pass start (Σ holds so far). The next timer sleeps only until that
+  // deadline, so a slow render/swap eats into the FOLLOWING delay instead of
+  // pushing the whole timeline out — cumulative drift can't accumulate. (The old
+  // loop re-armed setTimeout(hold) after each swap, so every render's latency
+  // compounded and playback ran progressively slow.)
+  let playStart = 0;
+  let targetElapsed = 0;
+
+  const step = () => {
+    if (!play.on) return;
+    const now = performance.now();
+    closeTelemetryFrame(now);
+    if (playStart === 0) {
+      playStart = now;
+      play.telemetry.startedAt = now;
+    }
+    const idx = range[k % range.length];
+    setIndex(idx);
+
+    const eMs = Math.max(0, eff[idx]);
+    const hold = playbackHold(eMs);
+    const rec = {
+      pos: play.telemetry.records.length,
+      idx,
+      raw: rawDurationMs(idx),
+      eff: eMs,
+      hold,
+      shownAt: now,
+      shownMs: null,
+    };
+    play.telemetry.records.push(rec);
+    renderHud(rec);
+
+    // Animate the playhead across this block for the duration of its hold.
+    const b = state.boundaries;
+    const from = b && b.length > idx ? b[idx] : 0;
+    const to = b && b.length > idx + 1 ? b[idx + 1] : from;
+    const startT = now;
+    const tick = (t) => {
+      if (!play.on) return;
+      const frac = Math.min(1, (t - startT) / hold);
+      positionPlayhead(from + (to - from) * frac);
+      if (frac < 1) play.raf = requestAnimationFrame(tick);
+    };
+    cancelAnimationFrame(play.raf);
+    play.raf = requestAnimationFrame(tick);
+
+    targetElapsed += hold;
+    const delay = Math.max(0, playStart + targetElapsed - performance.now());
+    play.timer = setTimeout(() => {
+      k++;
+      if (k >= range.length) {
+        if (play.stopAtEnd) {
+          const cb = play.onComplete;
+          closeTelemetryFrame(performance.now());
+          stopPlay();
+          if (cb) cb();
+          return;
+        }
+        // Loop: rebase the deadline clock so a long run doesn't accumulate.
+        k = 0;
+        playStart = 0;
+        targetElapsed = 0;
+        play.telemetry.loops++;
+      }
+      step();
+    }, delay);
+  };
+  step();
+}
+
+function stopPlay() {
+  if (!play.on) return;
+  play.on = false;
+  closeTelemetryFrame(performance.now());
+  clearTimeout(play.timer);
+  play.timer = null;
+  cancelAnimationFrame(play.raf);
+  play.raf = null;
+  positionPlayhead();
+  updatePlayBtn();
+  renderHud(null);
+}
+
+function togglePlay() {
+  if (play.on) stopPlay();
+  else startPlay();
+}
+
+/**
+ * Play the full animation range once from the start, then resolve with the
+ * measured timing summary. Backs the HUD "self-test" button and is exposed on
+ * window.__timing for e2e harnesses.
+ */
+function runTimingSelfTest() {
+  return new Promise((resolve) => {
+    if (state.frames.length === 0) {
+      resolve(null);
+      return;
+    }
+    stopPlay();
+    const range = animRange();
+    state.index = range.length ? range[0] : 0;
+    setIndex(state.index);
+    play.stopAtEnd = true;
+    play.onComplete = () => {
+      play.stopAtEnd = false;
+      play.onComplete = null;
+      resolve(timingSummary(play.telemetry));
+    };
+    startPlay();
+  });
+}
+
+/** Show or hide the timing HUD overlay; paint it immediately when enabled. */
+function setHudVisible(on) {
+  if (!els.hud) return;
+  els.hud.classList.toggle('hidden', !on);
+  els.hud.setAttribute('aria-hidden', on ? 'false' : 'true');
+  if (on) renderHud(null);
+}
+
+/** Drive the HUD's "Run timing test" button: play the range once and report
+ *  expected-vs-actual-vs-readout so the user can see playback honors its target. */
+async function runSelfTestUI() {
+  if (!els.selfTestBtn || els.selfTestBtn.disabled) return;
+  const out = els.selfTestResult;
+  els.selfTestBtn.disabled = true;
+  const prevLabel = els.selfTestBtn.textContent;
+  els.selfTestBtn.textContent = 'Running…';
+  if (out) {
+    out.classList.remove('hidden', 'ok', 'warn');
+    out.textContent = 'Playing range once…';
+  }
+  // Make sure the HUD is visible so the run is watchable.
+  setHudVisible(true);
+  try {
+    const s = await runTimingSelfTest();
+    if (out) {
+      if (!s || s.frames === 0) {
+        out.classList.add('warn');
+        out.textContent = 'No frames to test.';
+      } else {
+        const pct = s.expectedMs > 0 ? (s.driftMs / s.expectedMs) * 100 : 0;
+        const ok = Math.abs(pct) <= 2 && Math.abs(s.driftMs) <= 250;
+        out.classList.add(ok ? 'ok' : 'warn');
+        out.textContent =
+          `${s.frames} frames · actual ${fmtMs(s.actualMs)} vs target ${fmtMs(s.expectedMs)} ` +
+          `(drift ${fmtSigned(s.driftMs)}, ${pct.toFixed(1)}%)\n` +
+          `readout ${fmtMs(s.readoutMs)} · worst frame ${fmtSigned(s.worstFrameMs)} · ` +
+          `${s.fps.toFixed(1)} fps`;
+      }
+    }
+  } catch (err) {
+    if (out) {
+      out.classList.add('warn');
+      out.textContent = `Self-test failed: ${err && err.message ? err.message : err}`;
+    }
+  } finally {
+    els.selfTestBtn.textContent = prevLabel;
+    els.selfTestBtn.disabled = state.frames.length === 0;
+  }
+}
+window.__timing = {
+  get: () => timingSummary(play.telemetry),
+  records: () => (play.telemetry ? play.telemetry.records.slice() : []),
+  reset: () => {
+    if (play.telemetry) {
+      play.telemetry.records = [];
+      play.telemetry.loops = 0;
+    }
+  },
+  isPlaying: () => play.on,
+  runSelfTest: runTimingSelfTest,
+};
+
+
+/* ----------------------------------------------------------- mp4 export */
+
+function showProgress(frac) {
+  els.exportProgress.classList.remove('hidden');
+  const pct = Math.max(0, Math.min(100, Math.round(frac * 100)));
+  els.exportBar.style.width = `${pct}%`;
+  els.exportPct.textContent = `${pct}%`;
+}
+
+function hideProgress() {
+  els.exportProgress.classList.add('hidden');
+  els.exportBar.style.width = '0%';
+}
+
+function bitrateFor(w, h, fps) {
+  return Math.min(40_000_000, Math.max(1_000_000, Math.round(w * h * fps * 0.12)));
+}
+
+async function pickH264Codec(w, h, fps) {
+  const candidates = [
+    'avc1.640034',
+    'avc1.640033',
+    'avc1.640032',
+    'avc1.64002A',
+    'avc1.640028',
+    'avc1.4D0028',
+    'avc1.42E01E',
+    'avc1.42001E',
+  ];
+  for (const codec of candidates) {
+    try {
+      const support = await VideoEncoder.isConfigSupported({
+        codec,
+        width: w,
+        height: h,
+        framerate: fps,
+        bitrate: bitrateFor(w, h, fps),
+      });
+      if (support && support.supported) return codec;
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+/** Rasterize one full-size frame SVG onto an opaque canvas at the output size. */
+async function rasterizeFrame(index, w, h, bg) {
+  const res = await fetch(svgUrlFull(index));
+  if (!res.ok) throw new Error(`frame ${index + 1} fetch failed`);
+  const svgText = await res.text();
+  const blobUrl = URL.createObjectURL(new Blob([svgText], { type: 'image/svg+xml' }));
+  try {
+    const img = new Image();
+    await new Promise((resolve, reject) => {
+      img.onload = resolve;
+      img.onerror = () => reject(new Error('could not rasterize frame'));
+      img.src = blobUrl;
+    });
+    const canvas = document.createElement('canvas');
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext('2d');
+    ctx.fillStyle = bg;
+    ctx.fillRect(0, 0, w, h);
+    ctx.drawImage(img, 0, 0, w, h);
+    return canvas;
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+}
+
+function waitForQueue(encoder, limit) {
+  return new Promise((resolve) => {
+    const check = () => {
+      if (encoder.encodeQueueSize <= limit) resolve();
+      else setTimeout(check, 8);
+    };
+    check();
+  });
+}
+
+async function exportMp4() {
+  if (!state.name) return;
+  if (typeof window.VideoEncoder === 'undefined') {
+    toast('MP4 export needs a Chromium or Safari 16.4+ browser (WebCodecs).');
+    return;
+  }
+  stopPlay();
+  const range = animRange();
+  if (range.length === 0) {
+    toast('Nothing to export');
+    return;
+  }
+
+  const fps = state.settings.fps;
+  const scale = state.settings.scale;
+  els.exportMp4Btn.disabled = true;
+  showProgress(0);
+
+  try {
+    const { Muxer, ArrayBufferTarget } = await import('./vendor/mp4-muxer.js');
+
+    // Base dimensions from a full (untrimmed) frame so all frames match.
+    const firstSvg = await (await fetch(svgUrlFull(range[0]))).text();
+    const dims = firstSvg.match(/<svg[^>]*\bwidth="(\d+(?:\.\d+)?)"[^>]*\bheight="(\d+(?:\.\d+)?)"/);
+    if (!dims) throw new Error('could not read frame size');
+    const baseW = Number(dims[1]);
+    const baseH = Number(dims[2]);
+    // H.264 requires even dimensions.
+    const outW = Math.max(2, Math.round(baseW * scale) & ~1);
+    const outH = Math.max(2, Math.round(baseH * scale) & ~1);
+
+    const codec = await pickH264Codec(outW, outH, fps);
+    if (!codec) throw new Error('no supported H.264 encoder configuration for these dimensions');
+
+    const target = new ArrayBufferTarget();
+    const muxer = new Muxer({
+      target,
+      video: { codec: 'avc', width: outW, height: outH },
+      fastStart: 'in-memory',
+    });
+
+    let encoderError = null;
+    const encoder = new VideoEncoder({
+      output: (chunk, meta) => muxer.addVideoChunk(chunk, meta),
+      error: (e) => {
+        encoderError = e;
+      },
+    });
+    encoder.configure({
+      codec,
+      width: outW,
+      height: outH,
+      framerate: fps,
+      bitrate: bitrateFor(outW, outH, fps),
+    });
+
+    const bg =
+      getComputedStyle(document.documentElement).getPropertyValue('--bg').trim() || '#0d1117';
+    const eff = effectiveDurations();
+    const counts = range.map((idx) => cfrCount(eff[idx], fps));
+    const totalOut = counts.reduce((a, b) => a + b, 0);
+    const usPerFrame = 1_000_000 / fps;
+    const keyInterval = Math.max(1, Math.round(fps * 2));
+
+    let outIndex = 0;
+    for (let r = 0; r < range.length; r++) {
+      if (encoderError) throw encoderError;
+      const canvas = await rasterizeFrame(range[r], outW, outH, bg);
+      for (let n = 0; n < counts[r]; n++) {
+        const frame = new VideoFrame(canvas, {
+          timestamp: Math.round(outIndex * usPerFrame),
+          duration: Math.round(usPerFrame),
+        });
+        encoder.encode(frame, { keyFrame: outIndex % keyInterval === 0 });
+        frame.close();
+        outIndex++;
+        if (outIndex % 4 === 0) showProgress((outIndex / totalOut) * 0.92);
+        if (encoder.encodeQueueSize > 24) await waitForQueue(encoder, 8);
+      }
+    }
+
+    await encoder.flush();
+    if (encoderError) throw encoderError;
+    muxer.finalize();
+    showProgress(0.98);
+
+    const blob = new Blob([target.buffer], { type: 'video/mp4' });
+    const stem = (state.name || 'capture').replace(/\.ans$/i, '');
+    const filename = `${stem}@${scale}x.mp4`;
+    const saved = await saveBlob(blob, filename, [
+      { description: 'MP4 video', accept: { 'video/mp4': ['.mp4'] } },
+    ]);
+    showProgress(1);
+    if (saved) toast(`Saved ${filename} (${outW}×${outH}, ${fps}fps)`);
+  } catch (e) {
+    toast(`MP4 export failed: ${e.message}`);
+  } finally {
+    els.exportMp4Btn.disabled = state.frames.length === 0;
+    setTimeout(hideProgress, 700);
+  }
+}
+
+/* -------------------------------------------------------- new recording */
+
+function updateRecCommand() {
+  const cmd = els.recCmd.value.trim() || '<command>';
+  let name = els.recName.value.trim();
+  if (name && !/\.ans$/i.test(name)) name += '.ans';
+  const outFlag = name ? `-o ${name} ` : '';
+  els.recOut.textContent = `tui-cap record ${outFlag}-- ${cmd}`;
+}
+
+/* --------------------------------------------------------------- wiring */
+
+const debouncedRefresh = debounce(refreshImages, 180);
+
+els.chrome.addEventListener('change', () => {
+  els.chromeStyle.disabled = !els.chrome.checked;
+  refreshImages();
+});
+els.chromeStyle.addEventListener('change', refreshImages);
+els.cursor.addEventListener('change', refreshImages);
+els.title.addEventListener('input', debouncedRefresh);
+els.fontSize.addEventListener('input', () => {
+  els.fontSizeVal.textContent = `${els.fontSize.value}px`;
+  debouncedRefresh();
+});
+els.lineHeight.addEventListener('input', () => {
+  els.lineHeightVal.textContent = Number(els.lineHeight.value).toFixed(2);
+  debouncedRefresh();
+});
+
+// Restore font size + line spacing to their HTML default values.
+function resetTypography() {
+  els.fontSize.value = els.fontSize.defaultValue;
+  els.lineHeight.value = els.lineHeight.defaultValue;
+  els.fontSizeVal.textContent = `${els.fontSize.value}px`;
+  els.lineHeightVal.textContent = Number(els.lineHeight.value).toFixed(2);
+  refreshImages();
+}
+els.resetType.addEventListener('click', resetTypography);
+
+els.goStartBtn.addEventListener('click', () => userSeek(firstVisibleIndex()));
+els.prevBtn.addEventListener('click', () => userSeek(stepVisibleIndex(state.index, -1)));
+els.nextBtn.addEventListener('click', () => userSeek(stepVisibleIndex(state.index, 1)));
+els.goEndBtn.addEventListener('click', () => userSeek(lastVisibleIndex()));
+els.downloadBtn.addEventListener('click', downloadSvg);
+els.downloadPngBtn.addEventListener('click', downloadPng);
+
+// Timeline view controls.
+els.zoom.addEventListener('input', () => setZoom(sliderToPps(Number(els.zoom.value)), playheadZoomAnchor()));
+els.fitBtn.addEventListener('click', fitTimeline);
+
+// Canvas scale controls (header): Zoom-to-Fit, an arbitrary-zoom slider, and 100%.
+els.zoomFitBtn.addEventListener('click', () => fitCanvas());
+els.zoom100Btn.addEventListener('click', () => setCanvasZoom(1, { center: true }));
+els.zoomRange.addEventListener('input', () => setCanvasZoom(Number(els.zoomRange.value) / 100));
+els.timelineScroll.addEventListener('scroll', onTimelineScroll, { passive: true });
+// Pinch / ⌘|Ctrl + wheel over the timeline zooms (toward the cursor).
+els.timelineScroll.addEventListener('wheel', onTimelineWheel, { passive: false });
+// Click or drag the ruler to scrub the playhead through the timeline.
+els.timelineRuler.addEventListener('pointerdown', startScrub);
+// Shift + pointer-drag on the track brush-selects frames. Capture phase so it
+// pre-empts the per-frame resize handles' own pointerdown handlers.
+els.timelineTrack.addEventListener(
+  'pointerdown',
+  (e) => {
+    if (state.frames.length === 0 || !e.shiftKey) return;
+    e.preventDefault();
+    e.stopPropagation();
+    startMarquee(e);
+  },
+  true,
+);
+// While Shift is held, the timeline is in brush-select mode: reflect that with a
+// marquee cursor (so the frame edges no longer read as resize handles).
+const syncShiftCursor = (down) => els.timelineScroll.classList.toggle('shift-select', down);
+window.addEventListener('keydown', (e) => {
+  if (e.key === 'Shift') syncShiftCursor(true);
+});
+window.addEventListener('keyup', (e) => {
+  if (e.key === 'Shift') syncShiftCursor(false);
+});
+window.addEventListener('blur', () => syncShiftCursor(false));
+
+// Toggle showing/hiding deleted (skipped) frames in the timeline view. Deleted
+// frames are hidden by default, so the label is action-oriented: it names what a
+// click will do ("Show deleted" while hidden, "Hide deleted" while shown). The
+// pressed/active styling marks the non-default "deleted visible" override.
+function syncHideSkippedBtn() {
+  const showing = !state.hideSkipped; // are deleted frames currently visible?
+  els.hideSkippedBtn.textContent = showing ? 'Hide deleted' : 'Show deleted';
+  els.hideSkippedBtn.title = showing
+    ? 'Hide deleted frames from the timeline'
+    : 'Show deleted frames in the timeline';
+  els.hideSkippedBtn.classList.toggle('active', showing);
+  els.hideSkippedBtn.setAttribute('aria-pressed', showing ? 'true' : 'false');
+}
+
+els.hideSkippedBtn.addEventListener('click', () => {
+  state.hideSkipped = !state.hideSkipped;
+  syncHideSkippedBtn();
+  updateAnimUI();
+});
+
+// Selection length + skip/delete (operate on the whole selection).
+els.selLen.addEventListener('change', () => applyLengthToSelection(els.selLen.value));
+els.selLen.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') {
+    applyLengthToSelection(els.selLen.value);
+    els.selLen.blur();
+  }
+});
+els.selReset.addEventListener('click', resetSelection);
+els.selDelete.addEventListener('click', toggleSkipSelection);
+
+let resizeRaf = null;
+window.addEventListener('resize', () => {
+  cancelAnimationFrame(resizeRaf);
+  resizeRaf = requestAnimationFrame(() => {
+    if (state.frames.length > 0) layoutTimeline();
+  });
+});
+
+// Animation controls — each change updates settings, refreshes the timeline
+// readouts, and autosaves to the .anim.json sidecar.
+els.animFps.addEventListener('change', () => {
+  state.settings.fps = Number(els.animFps.value) || 30;
+  updateAnimUI();
+  saveAnimationSettings();
+});
+els.animScale.addEventListener('change', () => {
+  state.settings.scale = Number(els.animScale.value) || 2;
+  updateAnimUI();
+  saveAnimationSettings();
+});
+els.idleCap.addEventListener('input', () => {
+  state.settings.idleCapMs = sliderToIdleCap(Number(els.idleCap.value));
+  els.idleCapVal.textContent = fmtIdleCap(state.settings.idleCapMs);
+  updateAnimUI();
+  saveAnimationSettings();
+});
+els.speed.addEventListener('input', () => {
+  state.settings.speed = Number(els.speed.value) || 1;
+  els.speedVal.textContent = `${Number(state.settings.speed).toFixed(2).replace(/0$/, '')}×`;
+  updateAnimUI();
+  saveAnimationSettings();
+});
+els.smoothTyping.addEventListener('change', () => {
+  state.settings.smoothTyping = els.smoothTyping.checked;
+  els.typingCps.disabled = !state.settings.smoothTyping;
+  updateAnimUI();
+  saveAnimationSettings();
+});
+els.typingCps.addEventListener('input', () => {
+  const cps = Math.max(10, Math.min(60, Number(els.typingCps.value) || 30));
+  state.settings.typingCps = cps;
+  els.typingCpsVal.textContent = `${cps} cps`;
+  updateAnimUI();
+  saveAnimationSettings();
+});
+els.clearOverrides.addEventListener('click', clearAllOverrides);
+els.playBtn.addEventListener('click', togglePlay);
+els.exportMp4Btn.addEventListener('click', exportMp4);
+if (els.timingDebugLink) els.timingDebugLink.addEventListener('click', () => setHudVisible(true));
+if (els.hudClose) els.hudClose.addEventListener('click', () => setHudVisible(false));
+if (els.selfTestBtn) els.selfTestBtn.addEventListener('click', runSelfTestUI);
+els.goStartBtn.innerHTML = ICON.goStart;
+els.prevBtn.innerHTML = ICON.prev;
+els.nextBtn.innerHTML = ICON.next;
+els.goEndBtn.innerHTML = ICON.goEnd;
+updatePlayBtn();
+
+els.openFolderBtn.innerHTML = ICON.folder;
+els.openFolderBtn.addEventListener('click', openCapturesFolder);
+
+els.newRecBtn.addEventListener('click', () => {
+  updateRecCommand();
+  els.recDialog.showModal();
+});
+els.recCmd.addEventListener('input', updateRecCommand);
+els.recName.addEventListener('input', updateRecCommand);
+els.recCopy.addEventListener('click', async () => {
+  try {
+    await navigator.clipboard.writeText(els.recOut.textContent);
+    toast('Command copied');
+  } catch {
+    toast('Copy failed — select and copy manually');
+  }
+});
+
+els.updateBtn.addEventListener('click', doUpdate);
+els.updateDismiss.addEventListener('click', () => els.updateBanner.classList.add('hidden'));
+
+document.addEventListener('keydown', (e) => {
+  const tag = (document.activeElement?.tagName || '').toLowerCase();
+  if (tag === 'input' || tag === 'select' || tag === 'textarea') return;
+  if (els.recDialog.open) return;
+  if (e.key === 'ArrowLeft') {
+    userSeek(stepVisibleIndex(state.index, -1));
+    e.preventDefault();
+  } else if (e.key === 'ArrowRight') {
+    userSeek(stepVisibleIndex(state.index, 1));
+    e.preventDefault();
+  } else if (e.key === 'Home') {
+    userSeek(firstVisibleIndex());
+    e.preventDefault();
+  } else if (e.key === 'End') {
+    userSeek(lastVisibleIndex());
+    e.preventDefault();
+  } else if (e.key === 'Delete' || e.key === 'Backspace') {
+    if (state.selection.size > 0) {
+      toggleSkipSelection();
+      e.preventDefault();
+    }
+  } else if (e.key === ' ') {
+    if (state.frames.length > 0) togglePlay();
+    e.preventDefault();
+  }
+});
+
+// Live library refresh when new captures land (SSE, with the browser's own
+// auto-reconnect as the fallback).
+try {
+  const es = new EventSource('/api/events');
+  es.addEventListener('recordings', () => loadLibrary({ keepSelection: true }));
+} catch {
+  setInterval(() => loadLibrary({ keepSelection: true }), 4000);
+}
+
+/* =====================================================================
+ * Content edits — non-destructive, cross-frame text + colour + spacing.
+ * Anchors selected runs to their text content (server `edits.ts`) so an
+ * edit follows its line across every frame, persisted to `<name>.edits.json`.
+ * ===================================================================== */
+
+const ed = {
+  on: false,
+  cells: null, // GET /cells response for the current frame
+  palette: null, // GET /api/palette
+  theme: 'dark', // GUI renders the dark theme by default
+  doc: { schemaVersion: 1, revision: 0, edits: [] },
+  undo: [],
+  redo: [],
+  sel: null, // active selection / popover target
+  editing: false, // inline in-canvas editor active
+  drag: null, // in-progress drag selection
+  eyedrop: false, // eyedropper armed: next canvas click samples a char's colour
+  fetchToken: 0,
+};
+
+const edEls = {
+  toggle: $('editToggle'),
+  hint: $('editHint'),
+  tools: $('editTools'),
+  undoBtn: $('undoBtn'),
+  redoBtn: $('redoBtn'),
+  count: $('editCount'),
+  reset: $('resetEdits'),
+  overlay: $('selOverlay'),
+  hover: $('selHover'),
+  rect: $('selRect'),
+  section: $('editsSection'),
+  listCount: $('editsCount'),
+  empty: $('editsEmpty'),
+  list: $('editsList'),
+  pop: $('editPopover'),
+  selected: $('epSelected'),
+  budget: $('epBudget'),
+  fg: $('epFg'),
+  fgPick: $('epFgPick'),
+  bg: $('epBg'),
+  all: $('epAll'),
+  spaceRemove: $('epSpaceRemove'),
+  spaceVal: $('epSpaceVal'),
+  spaceAdd: $('epSpaceAdd'),
+  remove: $('epRemove'),
+  cancel: $('epCancel'),
+  apply: $('epApply'),
+  editor: $('selEditor'),
+  editGhost: $('selEditGhost'),
+  editText: $('selEditText'),
+  caret: $('selCaret'),
+  input: $('selInput'),
+};
+
+/* ----------------------------------------------- grapheme + column helpers */
+// Mirrors the column math in src/edits.ts so anchors captured here line up with
+// what the server matches/applies (terminal columns, wide glyphs = 2 columns).
+
+const GSEG =
+  typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : null;
+function graphemes(s) {
+  return GSEG ? Array.from(GSEG.segment(s), (x) => x.segment) : Array.from(s);
+}
+const WIDE_RE =
+  /[\u1100-\u115F\u2329\u232A\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6]/;
+const PICTO_RE = /\p{Extended_Pictographic}/u;
+function gWidth(g) {
+  const cp = g.codePointAt(0);
+  if (cp === undefined) return 1;
+  if (cp >= 0x1f300 || PICTO_RE.test(g) || WIDE_RE.test(g)) return 2;
+  return 1;
+}
+function strToCells(text) {
+  const cells = [];
+  let col = 0;
+  for (const g of graphemes(text)) {
+    const w = gWidth(g);
+    cells.push({ char: g, col, width: w });
+    col += w;
+  }
+  return cells;
+}
+function contentWidth(text) {
+  let col = 0;
+  for (const g of graphemes(text)) col += gWidth(g);
+  return col;
+}
+/** [start,end) columns of a row's text, space-padded; matches edits.ts columnSlice. */
+function columnSlice(text, start, end) {
+  const out = [];
+  for (let c = start; c < end; c++) out.push(' ');
+  for (const cell of strToCells(text)) {
+    const w = Math.max(1, cell.width);
+    if (cell.col + w <= start || cell.col >= end) continue;
+    const idx = cell.col - start;
+    if (idx >= 0 && idx < out.length) out[idx] = cell.char;
+    for (let k = 1; k < w; k++) {
+      const j = idx + k;
+      if (j >= 0 && j < out.length) out[j] = '';
+    }
+  }
+  return out.join('');
+}
+const trimEnd = (s) => String(s == null ? '' : s).replace(/\s+$/, '');
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
+  );
+}
+let edIdCounter = 0;
+function freshEditId() {
+  edIdCounter += 1;
+  return `e${Date.now().toString(36)}${edIdCounter.toString(36)}`;
+}
+const encName = () => encodeURIComponent(state.name);
+
+/* --------------------------------------------------------------- geometry */
+
+function geom() {
+  return ed.cells && ed.cells.geometry;
+}
+/** Map a pointer event to a grid {col,row} via the rendered image's geometry. */
+function eventToCell(e) {
+  const g = geom();
+  if (!g) return null;
+  const r = edEls.overlay.getBoundingClientRect();
+  const scale = r.width / g.width || 1;
+  const px = (e.clientX - r.left) / scale;
+  const py = (e.clientY - r.top) / scale;
+  let col = Math.floor((px - g.contentLeft) / g.cellW);
+  let row = Math.floor((py - g.contentTop) / g.cellH);
+  col = Math.max(0, Math.min(g.cols - 1, col));
+  row = Math.max(0, Math.min(ed.cells.rows.length - 1, row));
+  return { col, row };
+}
+/** Position the selection overlay exactly over the rendered <img>. */
+function positionOverlay() {
+  const img = els.preview;
+  if (!ed.on || !ed.cells || !img.getAttribute('src') || img.classList.contains('hidden')) {
+    edEls.overlay.classList.add('hidden');
+    return;
+  }
+  edEls.overlay.style.left = `${img.offsetLeft}px`;
+  edEls.overlay.style.top = `${img.offsetTop}px`;
+  edEls.overlay.style.width = `${img.offsetWidth}px`;
+  edEls.overlay.style.height = `${img.offsetHeight}px`;
+  edEls.overlay.classList.remove('hidden');
+  if (ed.sel) {
+    if (ed.editing) renderInlineEditor();
+    else drawSelectionRect();
+  }
+}
+/** Default terminal background / foreground for the active theme (for masking). */
+function themeBg() {
+  return (ed.palette && ed.palette[ed.theme] && ed.palette[ed.theme].background) || '#0d1117';
+}
+function themeFg() {
+  return (ed.palette && ed.palette[ed.theme] && ed.palette[ed.theme].foreground) || '#e6edf3';
+}
+function fontPx() {
+  return Number(els.fontSize.value) || 14;
+}
+/** Draw a highlight box at [startCol,endCol) on a display row, in overlay px. */
+function cellBox(el, row, startCol, endCol) {
+  const g = geom();
+  const r = edEls.overlay.getBoundingClientRect();
+  const scale = r.width / g.width || 1;
+  el.style.left = `${(g.contentLeft + startCol * g.cellW) * scale}px`;
+  el.style.top = `${(g.contentTop + row * g.cellH) * scale}px`;
+  el.style.width = `${Math.max(1, endCol - startCol) * g.cellW * scale}px`;
+  el.style.height = `${g.cellH * scale}px`;
+  el.classList.remove('hidden');
+}
+/** Snap clicked columns out to whole glyphs and clamp to the row's content. */
+function snapSpan(displayRow, c0, c1) {
+  const row = ed.cells.rows[displayRow];
+  const cells = strToCells(row ? row.text : '');
+  const contentEnd = cells.length ? cells[cells.length - 1].col + cells[cells.length - 1].width : 0;
+  let lo = Math.min(c0, c1);
+  let hi = Math.max(c0, c1);
+  const cover = (col) => cells.find((ce) => col >= ce.col && col < ce.col + ce.width);
+  const loCell = cover(lo);
+  if (loCell) lo = loCell.col;
+  const hiCell = cover(hi);
+  let end = hiCell ? hiCell.col + hiCell.width : hi + 1;
+  lo = Math.max(0, lo);
+  end = Math.min(Math.max(end, lo + 1), Math.max(contentEnd, lo + 1));
+  return { startCol: lo, endCol: end };
+}
+
+/* ----------------------------------------------------------- data fetching */
+
+async function loadPalette() {
+  try {
+    ed.palette = await apiJson('/api/palette');
+  } catch {
+    ed.palette = null;
+  }
+}
+async function fetchCells(index) {
+  if (!state.name) return;
+  const token = ++ed.fetchToken;
+  try {
+    const data = await apiJson(`/api/recordings/${encName()}/frames/${index}/cells?${fullParams()}`);
+    if (token !== ed.fetchToken) return; // a newer fetch superseded this one
+    ed.cells = data;
+  } catch {
+    if (token === ed.fetchToken) ed.cells = null;
+  }
+}
+
+/* --------------------------------------------------------- edits lifecycle */
+
+async function onRecordingEdits() {
+  closePopover();
+  ed.doc = { schemaVersion: 1, revision: 0, edits: [] };
+  try {
+    const data = await apiJson(`/api/recordings/${encName()}/edits`);
+    if (data && data.edits) ed.doc = data.edits;
+  } catch {
+    /* default empty doc */
+  }
+  state.editsRevision = ed.doc && typeof ed.doc.revision === 'number' ? ed.doc.revision : 0;
+  restoreHistory();
+  renderEditsList();
+  updateUndoButtons();
+  if (ed.on) {
+    await fetchCells(state.index);
+    positionOverlay();
+  }
+}
+
+async function toggleEditMode() {
+  ed.on = !ed.on;
+  edEls.toggle.setAttribute('aria-pressed', ed.on ? 'true' : 'false');
+  edEls.hint.classList.toggle('hidden', !ed.on);
+  edEls.tools.classList.toggle('hidden', !ed.on);
+  if (ed.on) {
+    stopPlay();
+    if (!ed.palette) await loadPalette();
+    await fetchCells(state.index);
+    positionOverlay();
+  } else {
+    closePopover();
+    edEls.overlay.classList.add('hidden');
+    edEls.hover.classList.add('hidden');
+    edEls.rect.classList.add('hidden');
+  }
+  updateEditsSectionVisibility();
+}
+
+/* ------------------------------------------------------------- selection UI */
+
+edEls.overlay.addEventListener('pointerdown', (e) => {
+  if (!ed.on) return;
+  // A click inside the open inline editor must edit its text (focus + native
+  // caret placement), not start a brand-new selection. The real <input> is a
+  // descendant of this overlay, so its pointerdown bubbles up here — let it pass
+  // through untouched so the input keeps focus and positions the caret. (During
+  // eyedrop the editor is pointer-events:none, so the target is never the editor
+  // and colour sampling still falls through to the overlay as before.)
+  if (ed.editing && ed.sel && !ed.eyedrop && edEls.editor.contains(e.target)) return;
+  const c = eventToCell(e);
+  if (!c) return;
+  e.preventDefault();
+  if (ed.eyedrop) {
+    sampleColorAt(c.row, c.col);
+    return;
+  }
+  closePopover();
+  try {
+    edEls.overlay.setPointerCapture(e.pointerId);
+  } catch {
+    /* not all pointer types support capture */
+  }
+  ed.drag = { row: c.row, c0: c.col, c1: c.col };
+  drawDragRect();
+});
+edEls.overlay.addEventListener('pointermove', (e) => {
+  if (!ed.on) return;
+  const c = eventToCell(e);
+  if (ed.drag) {
+    if (c) ed.drag.c1 = c.col;
+    drawDragRect();
+  } else if (c) {
+    const span = snapSpan(c.row, c.col, c.col);
+    cellBox(edEls.hover, c.row, span.startCol, span.endCol);
+  }
+});
+edEls.overlay.addEventListener('pointerup', (e) => {
+  if (!ed.on || !ed.drag) return;
+  try {
+    edEls.overlay.releasePointerCapture(e.pointerId);
+  } catch {
+    /* ignore */
+  }
+  const d = ed.drag;
+  ed.drag = null;
+  const span = snapSpan(d.row, d.c0, d.c1);
+  openPopoverForSelection(d.row, span.startCol, span.endCol);
+});
+edEls.overlay.addEventListener('pointerleave', () => {
+  if (!ed.drag) edEls.hover.classList.add('hidden');
+});
+function drawDragRect() {
+  const span = snapSpan(ed.drag.row, ed.drag.c0, ed.drag.c1);
+  edEls.hover.classList.add('hidden');
+  cellBox(edEls.rect, ed.drag.row, span.startCol, span.endCol);
+}
+function drawSelectionRect() {
+  if (ed.sel) cellBox(edEls.rect, ed.sel.displayRow, ed.sel.startCol, ed.sel.endCol);
+}
+
+/* --------------------------------------------------------------- popover */
+
+function openPopoverForSelection(displayRow, startCol, endCol) {
+  const rowObj = ed.cells.rows[displayRow];
+  if (!rowObj || rowObj.sourceRow === null) {
+    toast('Pick a line that has text.');
+    edEls.rect.classList.add('hidden');
+    return;
+  }
+  const rawLineText = rowObj.rawLineText;
+  const anchorText = columnSlice(rawLineText, startCol, endCol);
+  const existing = ed.doc.edits.find(
+    (e) =>
+      e.kind === 'text' &&
+      e.srcRow === rowObj.sourceRow &&
+      e.startCol === startCol &&
+      e.endCol === endCol &&
+      e.rawLineText === rawLineText,
+  );
+  const spacing = ed.doc.edits.find(
+    (e) => e.kind === 'spacing' && e.srcRow === rowObj.sourceRow && e.rawLineText === rawLineText,
+  );
+  ed.sel = {
+    displayRow,
+    sourceRow: rowObj.sourceRow,
+    startCol,
+    endCol, // current block end — grows as the user types
+    originalEnd: endCol, // the dragged span end; the block never shrinks below it
+    rawLineText,
+    anchorText,
+    originalText: anchorText, // the underlying glyphs, shown dimmed beneath the live text
+    existingTextId: existing ? existing.id : null,
+    fg: existing ? existing.fg : null,
+    bg: existing ? existing.bg : null,
+    spacing: spacing ? spacing.blankLines : 0,
+  };
+  ed.editing = true;
+  edEls.hover.classList.add('hidden');
+  edEls.rect.classList.add('hidden'); // the inline editor box replaces the rect
+  edEls.selected.textContent = anchorText || '(spaces)';
+  edEls.all.checked = existing ? Boolean(existing.applyToAll) : false;
+  edEls.spaceVal.textContent = String(ed.sel.spacing);
+  renderSwatches();
+  edEls.remove.classList.toggle('hidden', !existing && !spacing);
+  // Seed the in-canvas editor: an existing edit reopens with its replacement
+  // text; a fresh selection starts empty so the first keystroke overwrites the
+  // (dimmed) original rather than inserting in front of it. Caret goes to the end
+  // of whatever we seed (the first cell of the block for a fresh, empty edit).
+  edEls.input.value =
+    existing && existing.text !== null && existing.text !== undefined ? existing.text : '';
+  edEls.editor.classList.remove('hidden');
+  renderInlineEditor();
+  showPopoverNear();
+  edEls.input.focus();
+  try {
+    const end = edEls.input.value.length;
+    edEls.input.setSelectionRange(end, end);
+  } catch {
+    /* some inputs disallow programmatic selection */
+  }
+  pokeCaret();
+  renderInlineEditor();
+}
+
+/** Current block width in columns, growing rightward with the typed text. */
+function blockColsNow() {
+  const g = geom();
+  const sel = ed.sel;
+  if (!g || !sel) return Math.max(1, sel ? sel.originalEnd - sel.startCol : 1);
+  const remaining = g.cols - sel.startCol;
+  const minSpan = Math.min(remaining, sel.originalEnd - sel.startCol);
+  const typedW = contentWidth(edEls.input.value);
+  return Math.max(1, Math.min(remaining, Math.max(minSpan, typedW)));
+}
+
+let caretTimer = null;
+/** Keep the caret solid briefly after activity, then resume blinking. */
+function pokeCaret() {
+  edEls.caret.classList.add('solid');
+  if (caretTimer) clearTimeout(caretTimer);
+  caretTimer = setTimeout(() => edEls.caret.classList.remove('solid'), 520);
+}
+
+/** Draw the live editor (mask + per-cell glyphs + caret) over the selection. */
+function renderInlineEditor() {
+  const g = geom();
+  const sel = ed.sel;
+  if (!g || !sel || !ed.editing) {
+    edEls.editor.classList.add('hidden');
+    return;
+  }
+  const r = edEls.overlay.getBoundingClientRect();
+  const scale = r.width / g.width || 1;
+  const cw = g.cellW * scale; // display px per terminal column
+  const ch = g.cellH * scale;
+  const fpx = fontPx() * scale;
+  const value = edEls.input.value;
+  const remaining = g.cols - sel.startCol;
+  const blockCols = blockColsNow();
+  const fg = sel.fg || themeFg();
+
+  const box = edEls.editor;
+  box.style.left = `${(g.contentLeft + sel.startCol * g.cellW) * scale}px`;
+  box.style.top = `${(g.contentTop + sel.displayRow * g.cellH) * scale}px`;
+  box.style.width = `${blockCols * cw}px`;
+  box.style.height = `${ch}px`;
+  box.style.background = sel.bg || themeBg();
+  box.classList.remove('hidden');
+
+  edEls.editText.style.color = fg;
+  edEls.editText.style.fontSize = `${fpx}px`;
+
+  // Dimmed ghost of the original glyphs, pinned to the original span, so typing
+  // visibly overwrites the old content in place instead of pushing it aside.
+  let ghostHtml = '';
+  let gcol = 0;
+  for (const gch of graphemes(sel.originalText || '')) {
+    const gw = gWidth(gch);
+    if (gcol + gw > remaining) break;
+    ghostHtml += `<span class="sel-edit-char" style="left:${gcol * cw}px;width:${gw * cw}px;height:${ch}px;line-height:${ch}px">${escapeHtml(gch)}</span>`;
+    gcol += gw;
+  }
+  edEls.editGhost.innerHTML = ghostHtml;
+  edEls.editGhost.style.fontSize = `${fpx}px`;
+  edEls.editGhost.style.color = themeFg();
+
+  let html = '';
+  let col = 0;
+  for (const gch of graphemes(value)) {
+    const gw = gWidth(gch);
+    if (col + gw > remaining) break; // clip at the end of the line
+    html += `<span class="sel-edit-char" style="left:${col * cw}px;width:${gw * cw}px;height:${ch}px;line-height:${ch}px">${escapeHtml(gch)}</span>`;
+    col += gw;
+  }
+  edEls.editText.innerHTML = html;
+
+  const selStart =
+    typeof edEls.input.selectionStart === 'number' ? edEls.input.selectionStart : value.length;
+  const caretCol = Math.max(0, Math.min(remaining, contentWidth(value.slice(0, selStart))));
+  edEls.caret.style.left = `${caretCol * cw}px`;
+  edEls.caret.style.height = `${ch}px`;
+  edEls.caret.style.color = fg;
+
+  edEls.input.style.fontSize = `${fpx}px`;
+  edEls.input.style.lineHeight = `${ch}px`;
+  updateBudget();
+}
+
+function updateBudget() {
+  if (!ed.sel) return;
+  const g = geom();
+  const remaining = g ? g.cols - ed.sel.startCol : ed.sel.endCol - ed.sel.startCol;
+  const used = contentWidth(edEls.input.value);
+  edEls.budget.textContent = `${Math.min(used, remaining)}/${remaining} cols${used > remaining ? ' · clipped' : ''}`;
+}
+
+function renderSwatches() {
+  const pal = (ed.palette && ed.palette[ed.theme]) || { ansi: [] };
+  buildSwatchRow(edEls.fg, pal, ed.sel.fg, (hex) => {
+    ed.sel.fg = hex;
+    renderSwatches();
+    if (ed.editing) renderInlineEditor(); // colour previews live in the canvas
+  });
+  buildSwatchRow(edEls.bg, pal, ed.sel.bg, (hex) => {
+    ed.sel.bg = hex;
+    renderSwatches();
+    if (ed.editing) renderInlineEditor();
+  });
+}
+function buildSwatchRow(container, pal, current, onPick) {
+  container.innerHTML = '';
+  const clear = document.createElement('button');
+  clear.type = 'button';
+  clear.className = `swatch clear${current == null ? ' selected' : ''}`;
+  clear.title = 'Default (no override)';
+  clear.addEventListener('click', () => onPick(null));
+  container.appendChild(clear);
+  for (const hex of pal.ansi || []) {
+    const b = document.createElement('button');
+    b.type = 'button';
+    const on = current && current.toLowerCase() === hex.toLowerCase();
+    b.className = `swatch${on ? ' selected' : ''}`;
+    b.style.background = hex;
+    b.title = hex;
+    b.addEventListener('click', () => onPick(hex));
+    container.appendChild(b);
+  }
+}
+
+/* --------------------------------------------------------------- eyedropper */
+
+/** Arm/disarm the eyedropper: while armed, the next canvas click samples the
+ *  glyph colour under the pointer into the selection's text colour. */
+function toggleEyedrop() {
+  if (ed.eyedrop) exitEyedrop();
+  else enterEyedrop();
+}
+function enterEyedrop() {
+  if (!ed.sel) return;
+  ed.eyedrop = true;
+  edEls.overlay.classList.add('eyedrop');
+  edEls.fgPick.setAttribute('aria-pressed', 'true');
+  edEls.hover.classList.add('hidden');
+  toast('Eyedropper: click a character to pick its colour · Esc to cancel');
+}
+function exitEyedrop() {
+  ed.eyedrop = false;
+  edEls.overlay.classList.remove('eyedrop');
+  edEls.fgPick.setAttribute('aria-pressed', 'false');
+}
+/** Resolved foreground colour of the glyph covering (row, col), or null. */
+function fgColorAt(displayRow, col) {
+  const row = ed.cells && ed.cells.rows[displayRow];
+  if (!row || !row.fg) return null;
+  const cells = strToCells(row.text);
+  const cover = cells.find((ce) => col >= ce.col && col < ce.col + ce.width);
+  const key = cover ? cover.col : col;
+  const hex = row.fg[key] ?? row.fg[String(key)];
+  return hex || null;
+}
+/** Sample the glyph colour at a cell and apply it to the selection's fg. */
+function sampleColorAt(displayRow, col) {
+  const hex = fgColorAt(displayRow, col);
+  if (!hex) {
+    toast('No character there to sample — click a letter or symbol.');
+    return;
+  }
+  exitEyedrop();
+  if (!ed.sel) return;
+  ed.sel.fg = hex;
+  renderSwatches();
+  if (ed.editing) {
+    renderInlineEditor();
+    edEls.input.focus();
+  }
+  toast(`Picked text colour ${hex}`);
+}
+
+function showPopoverNear() {
+  edEls.pop.classList.remove('hidden');
+  const anchorEl = ed.editing ? edEls.editor : edEls.rect;
+  const r = anchorEl.getBoundingClientRect();
+  const pw = edEls.pop.offsetWidth;
+  const ph = edEls.pop.offsetHeight;
+  let top = r.bottom + 8;
+  if (top + ph > window.innerHeight - 8) top = Math.max(8, r.top - ph - 8);
+  const left = Math.max(8, Math.min(r.left, window.innerWidth - pw - 8));
+  edEls.pop.style.left = `${left}px`;
+  edEls.pop.style.top = `${top}px`;
+}
+function closePopover() {
+  exitEyedrop();
+  edEls.pop.classList.add('hidden');
+  edEls.rect.classList.add('hidden');
+  edEls.editor.classList.add('hidden');
+  ed.editing = false;
+  ed.sel = null;
+}
+
+/* --------------------------------------------------------- mutate + persist */
+
+function anchorFields(sel) {
+  return {
+    rawLineText: sel.rawLineText,
+    startCol: sel.startCol,
+    endCol: sel.endCol,
+    anchorText: sel.anchorText,
+    leftContext: columnSlice(sel.rawLineText, Math.max(0, sel.startCol - 3), sel.startCol),
+    rightContext: columnSlice(sel.rawLineText, sel.endCol, sel.endCol + 3),
+    lineAbove: trimEnd(neighborRaw(sel.displayRow - 1)),
+    lineBelow: trimEnd(neighborRaw(sel.displayRow + 1)),
+    srcFrame: state.index,
+    srcRow: sel.sourceRow,
+  };
+}
+function neighborRaw(displayRow) {
+  const r = ed.cells && ed.cells.rows[displayRow];
+  return r ? r.rawLineText : '';
+}
+
+function applyFromPopover() {
+  const sel = ed.sel;
+  if (!sel) return;
+  const g = geom();
+  const value = edEls.input.value;
+  // Resolve the grown block extent: it overwrites rightward up to the end of the
+  // line, but never shrinks below the originally selected span (layout-preserving).
+  const remaining = g ? g.cols - sel.startCol : sel.originalEnd - sel.startCol;
+  const minSpan = Math.min(remaining, sel.originalEnd - sel.startCol);
+  const blockCols = Math.max(1, Math.min(remaining, Math.max(minSpan, contentWidth(value))));
+  const grownEnd = sel.startCol + blockCols;
+  // Anchor/apply span follow the grown block so the matcher and overwrite agree.
+  sel.endCol = grownEnd;
+  sel.anchorText = columnSlice(sel.rawLineText, sel.startCol, grownEnd);
+  // Empty (nothing typed) or unchanged content → colour-only edit, never blank
+  // out the original by committing an empty replacement.
+  const text = value === '' || value === sel.anchorText ? null : value;
+  const fg = sel.fg ?? null;
+  const bg = sel.bg ?? null;
+  pushHistory();
+  let edits = ed.doc.edits.slice();
+  if (sel.existingTextId) edits = edits.filter((e) => e.id !== sel.existingTextId);
+  if (text !== null || fg !== null || bg !== null) {
+    edits.push({
+      ...anchorFields(sel),
+      id: sel.existingTextId || freshEditId(),
+      kind: 'text',
+      text,
+      fg,
+      bg,
+      applyToAll: edEls.all.checked,
+    });
+  }
+  ed.doc.edits = edits;
+  commitEdits();
+  closePopover();
+}
+
+function changeSpacing(delta) {
+  const sel = ed.sel;
+  if (!sel) return;
+  let edits = ed.doc.edits.slice();
+  const idx = edits.findIndex(
+    (e) => e.kind === 'spacing' && e.srcRow === sel.sourceRow && e.rawLineText === sel.rawLineText,
+  );
+  const prevId = idx >= 0 ? edits[idx].id : null;
+  let next = (idx >= 0 ? edits[idx].blankLines : 0) + delta;
+  next = Math.max(-10, Math.min(20, next));
+  pushHistory();
+  if (idx >= 0) edits.splice(idx, 1);
+  if (next !== 0) {
+    edits.push({
+      ...anchorFields(sel),
+      id: prevId || freshEditId(),
+      kind: 'spacing',
+      blankLines: next,
+      applyToAll: edEls.all.checked,
+    });
+  }
+  ed.doc.edits = edits;
+  sel.spacing = next;
+  edEls.spaceVal.textContent = String(next);
+  edEls.remove.classList.remove('hidden');
+  commitEdits();
+}
+
+function removeCurrent() {
+  const sel = ed.sel;
+  if (!sel) return;
+  pushHistory();
+  ed.doc.edits = ed.doc.edits.filter((e) => {
+    if (e.kind === 'text' && e.id === sel.existingTextId) return false;
+    if (e.kind === 'spacing' && e.srcRow === sel.sourceRow && e.rawLineText === sel.rawLineText)
+      return false;
+    return true;
+  });
+  commitEdits();
+  closePopover();
+}
+function removeById(id) {
+  pushHistory();
+  ed.doc.edits = ed.doc.edits.filter((e) => e.id !== id);
+  commitEdits();
+}
+async function resetAllEdits() {
+  if (ed.doc.edits.length === 0) return;
+  if (!window.confirm('Remove all content edits for this recording?')) return;
+  pushHistory();
+  ed.doc.edits = [];
+  await commitEdits();
+}
+
+/** Persist + re-render everything after an edits mutation. */
+async function commitEdits() {
+  renderEditsList();
+  updateUndoButtons();
+  await saveEditsNow();
+  refreshImages();
+  await refreshFramesMeta();
+  await fetchCells(state.index);
+  positionOverlay();
+}
+async function saveEditsNow() {
+  if (!state.name) return;
+  try {
+    const res = await fetch(`/api/recordings/${encName()}/edits`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ schemaVersion: 1, edits: ed.doc.edits }),
+    });
+    if (res.ok) {
+      const data = await res.json();
+      ed.doc = data.edits;
+      if (ed.doc && typeof ed.doc.revision === 'number') state.editsRevision = ed.doc.revision;
+    }
+  } catch {
+    /* best-effort autosave */
+  }
+  persistHistory();
+}
+/** Refresh just the uniform animation canvas (spacing edits can grow it). */
+async function refreshFramesMeta() {
+  try {
+    const data = await apiJson(`/api/recordings/${encName()}/frames`);
+    if (typeof data.editsRevision === 'number') state.editsRevision = data.editsRevision;
+    if (data.animCanvas && data.animCanvas.cols && data.animCanvas.rows) {
+      state.animCanvas = data.animCanvas;
+    }
+    if (data.cols && data.rows) els.recordedSize.textContent = `${data.cols} × ${data.rows}`;
+  } catch {
+    /* leave the previous canvas in place */
+  }
+}
+
+/* ----------------------------------------------------------- undo / redo */
+
+function snapshot() {
+  return JSON.stringify(ed.doc.edits);
+}
+function pushHistory() {
+  ed.undo.push(snapshot());
+  ed.redo.length = 0;
+}
+async function undoEdit() {
+  if (ed.undo.length === 0) return;
+  ed.redo.push(snapshot());
+  ed.doc.edits = JSON.parse(ed.undo.pop());
+  closePopover();
+  await commitEdits();
+}
+async function redoEdit() {
+  if (ed.redo.length === 0) return;
+  ed.undo.push(snapshot());
+  ed.doc.edits = JSON.parse(ed.redo.pop());
+  closePopover();
+  await commitEdits();
+}
+function updateUndoButtons() {
+  edEls.undoBtn.disabled = ed.undo.length === 0;
+  edEls.redoBtn.disabled = ed.redo.length === 0;
+}
+function histKey() {
+  return `ghcp-edits-history:${state.name}`;
+}
+function persistHistory() {
+  try {
+    sessionStorage.setItem(
+      histKey(),
+      JSON.stringify({ revision: ed.doc.revision, undo: ed.undo, redo: ed.redo }),
+    );
+  } catch {
+    /* sessionStorage may be unavailable */
+  }
+  updateUndoButtons();
+}
+function restoreHistory() {
+  ed.undo = [];
+  ed.redo = [];
+  try {
+    const raw = sessionStorage.getItem(histKey());
+    if (!raw) return;
+    const h = JSON.parse(raw);
+    // Discard history built on a different sidecar revision (out-of-band change).
+    if (h && h.revision === ed.doc.revision) {
+      ed.undo = Array.isArray(h.undo) ? h.undo : [];
+      ed.redo = Array.isArray(h.redo) ? h.redo : [];
+    }
+  } catch {
+    /* ignore corrupt history */
+  }
+}
+
+/* ------------------------------------------------------------- edits list */
+
+function updateEditsSectionVisibility() {
+  const show = ed.on || ed.doc.edits.length > 0;
+  edEls.section.classList.toggle('hidden', !show);
+}
+async function jumpToEdit(edit) {
+  if (state.frames.length === 0) return;
+  // Re-selecting an edit needs the editor overlay + per-frame cell geometry, so
+  // turn edit mode on (when off) before navigating and reopening the dialog.
+  if (!ed.on) await toggleEditMode();
+  // Land on the exact frame the edit was authored on — even if it's skipped — so
+  // its source row and raw line match what was anchored.
+  const target =
+    typeof edit.srcFrame === 'number' && edit.srcFrame >= 0 && edit.srcFrame < state.frames.length
+      ? edit.srcFrame
+      : state.index;
+  userSeek(target);
+  // setIndex() (via userSeek) closes any open popover and starts its own cells
+  // fetch; await a fresh one so ed.cells is guaranteed to describe the target
+  // frame before we resolve the source row.
+  await fetchCells(target);
+  positionOverlay();
+  reopenEditPopover(edit);
+}
+
+/** Reopen the content dialog on the display row that carries an edit's anchor.
+ *  openPopoverForSelection() re-discovers the edit by (srcRow, startCol, endCol,
+ *  rawLineText) and seeds existingTextId/colours, so applying changes updates
+ *  that same edit in place instead of creating a duplicate. */
+function reopenEditPopover(edit) {
+  const rows = ed.cells && ed.cells.rows;
+  if (!rows) {
+    toast('Could not open this edit.');
+    return;
+  }
+  let displayRow = rows.findIndex(
+    (r) => r.sourceRow === edit.srcRow && r.rawLineText === edit.rawLineText,
+  );
+  if (displayRow < 0) displayRow = rows.findIndex((r) => r.sourceRow === edit.srcRow);
+  if (displayRow < 0) {
+    toast('This edit’s line is no longer on its source frame.');
+    return;
+  }
+  openPopoverForSelection(displayRow, edit.startCol, edit.endCol);
+}
+function renderEditsList() {
+  const edits = ed.doc.edits;
+  const label = edits.length ? `${edits.length} edit${edits.length === 1 ? '' : 's'}` : '';
+  edEls.count.textContent = label;
+  edEls.listCount.textContent = label;
+  edEls.reset.classList.toggle('hidden', edits.length === 0);
+  edEls.empty.classList.toggle('hidden', edits.length > 0);
+  edEls.list.innerHTML = '';
+  for (const e of edits) {
+    const li = document.createElement('li');
+    li.className = 'edit-item';
+    const main = document.createElement('div');
+    main.className = 'ei-main';
+    main.title = 'Click to reopen this edit';
+    if (e.kind === 'spacing') {
+      const n = e.blankLines;
+      main.innerHTML =
+        `<span class="ei-kind">space</span>` +
+        `<span class="ei-text">${n > 0 ? '+' : ''}${n} line${Math.abs(n) === 1 ? '' : 's'} · ${escapeHtml(trimEnd(e.rawLineText) || '(blank)')}</span>`;
+    } else {
+      const labelText = e.text !== null && e.text !== undefined ? e.text : trimEnd(e.anchorText) || '(recolor)';
+      let sw = '';
+      if (e.fg) sw += `<span class="ei-swatch" style="background:${escapeHtml(e.fg)}"></span>`;
+      if (e.bg) sw += `<span class="ei-swatch" style="background:${escapeHtml(e.bg)}"></span>`;
+      main.innerHTML =
+        `<span class="ei-kind">text</span>` +
+        `<span class="ei-text">${escapeHtml(labelText)}</span>${sw}`;
+    }
+    main.addEventListener('click', () => jumpToEdit(e));
+    const rm = document.createElement('button');
+    rm.className = 'ei-remove';
+    rm.type = 'button';
+    rm.title = 'Remove edit';
+    rm.textContent = '×';
+    rm.addEventListener('click', (ev) => {
+      ev.stopPropagation();
+      removeById(e.id);
+    });
+    li.append(main, rm);
+    edEls.list.appendChild(li);
+  }
+  updateEditsSectionVisibility();
+}
+
+/* --------------------------------------------------------------- wiring */
+
+edEls.toggle.addEventListener('click', toggleEditMode);
+edEls.undoBtn.addEventListener('click', undoEdit);
+edEls.redoBtn.addEventListener('click', redoEdit);
+edEls.reset.addEventListener('click', resetAllEdits);
+edEls.apply.addEventListener('click', applyFromPopover);
+edEls.cancel.addEventListener('click', closePopover);
+edEls.remove.addEventListener('click', removeCurrent);
+edEls.spaceAdd.addEventListener('click', () => changeSpacing(1));
+edEls.spaceRemove.addEventListener('click', () => changeSpacing(-1));
+edEls.fgPick.addEventListener('click', toggleEyedrop);
+
+// Live in-canvas editing: the hidden input is the keystroke source of truth; we
+// mirror its value + caret into the on-canvas glyph layer on every change.
+edEls.input.addEventListener('input', () => {
+  pokeCaret();
+  renderInlineEditor();
+});
+edEls.input.addEventListener('keyup', () => renderInlineEditor());
+edEls.input.addEventListener('click', () => {
+  pokeCaret();
+  renderInlineEditor();
+});
+edEls.input.addEventListener('select', () => renderInlineEditor());
+edEls.input.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') {
+    e.preventDefault();
+    applyFromPopover();
+  } else if (e.key === 'Escape') {
+    e.preventDefault();
+    if (ed.eyedrop) exitEyedrop();
+    else closePopover();
+  } else {
+    pokeCaret();
+  }
+});
+
+document.addEventListener('keydown', (e) => {
+  if (!ed.on) return;
+  if (e.key === 'Escape') {
+    if (ed.eyedrop) exitEyedrop();
+    else if (!edEls.pop.classList.contains('hidden')) closePopover();
+    return;
+  }
+  if (!(e.metaKey || e.ctrlKey)) return;
+  const k = e.key.toLowerCase();
+  if (k === 'z') {
+    if (document.activeElement === edEls.input) return; // let native text-undo run
+    e.preventDefault();
+    if (e.shiftKey) redoEdit();
+    else undoEdit();
+  } else if (k === 'y') {
+    if (document.activeElement === edEls.input) return;
+    e.preventDefault();
+    redoEdit();
+  }
+});
+
+els.preview.addEventListener('load', () => {
+  // The canvas size can change between renders (new recording, font/spacing
+  // tweaks). Re-apply the active scale so explicit zoom keeps the right pixel
+  // size and the Zoom-to-Fit readout reflects the new dimensions.
+  applyViewMode();
+});
+window.addEventListener('resize', () => {
+  // Zoom-to-Fit depends on the viewport, so keep its readout in sync.
+  if (state.frames.length > 0) updateZoomReadout();
+  if (ed.on) {
+    positionOverlay();
+    if (!edEls.pop.classList.contains('hidden')) showPopoverNear();
+  }
+});
+
+/* --------------------------------------------------------------- bootstrap */
+
+clearPreview();
+loadLibrary();
+checkForUpdate();