cyborg-hunter 0.5.0 → 0.7.0

package/src/cli/init.js

@@ -16,7 +16,7 @@ export async function runInit() {
 
   // Minimal config — just the fields every project needs to set.
   // filePattern defaults to JSON-or-CSV because jsPsych's `.csv()` save is
-  // the most common format we see in the wild (rule-gallery uses JSON; most
+  // the most common format we see in the wild (Shape-2 producers use JSON; most
   // jsPsych setups use CSV).
   const config = {
     dataDir: './data',

package/src/cli/renderers/event-log.js

@@ -12,41 +12,40 @@ export async function renderEventLog(participants, config) {
   const rows = [];
 
   for (const p of participants) {
+    // Collect this participant's events with their session-absolute timestamp,
+    // then sort chronologically before serializing. All event timestamps are on
+    // the same performance.now() clock (copy/paste/drop/synthetic use `e.t`,
+    // tab-aways use `e.start`), so a single numeric sort interleaves them
+    // correctly. Without this the rows came out in loop/category order
+    // (all pastes, then all copies, …), contradicting the "chronological" docs.
+    const pEvents = [];
     for (const trial of p.trials) {
       const trialId = trial.trialId || trial.ruleId || '?';
 
-      // Paste events
       for (const e of (trial.pasteEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'paste', e.t, '', e.text));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'paste', e.t, '', e.text) });
       }
-
-      // Copy events
       for (const e of (trial.copyEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'copy', e.t, '', ''));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'copy', e.t, '', '') });
       }
-
-      // Drop events
       for (const e of (trial.dropEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'drop', e.t, '', e.text));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'drop', e.t, '', e.text) });
       }
-
-      // Synthetic insertions (text appeared without keystrokes)
       for (const e of (trial.syntheticInsertions || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'synthetic', e.t, '', e.text));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'synthetic', e.t, '', e.text) });
       }
-
-      // Tab-away events. timestamp uses the session-absolute `start` (same
-      // performance.now() clock the copy/paste `t` field uses), so all rows
-      // in this CSV share one chronological scale. The `text` column carries
-      // the tab-away type (windowBlur / visibilityChange / etc.) so analysts
-      // can filter by trigger.
+      // Tab-away timestamp uses the session-absolute `start` (the `text` column
+      // carries the trigger type — windowBlur / visibilityChange / etc. — so
+      // analysts can filter by trigger).
       for (const e of (trial.tabAwayEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'tabAway', e.start, e.duration_ms, e.type || ''));
+        pEvents.push({ ts: e.start, row: formatRow(p.participantId, trialId, 'tabAway', e.start, e.duration_ms, e.type || '') });
       }
     }
+    // Stable chronological sort; events with no usable timestamp sort last.
+    pEvents.sort((a, b) => (a.ts ?? Infinity) - (b.ts ?? Infinity));
+    for (const e of pEvents) rows.push(e.row);
   }
 
-  // Sort chronologically within each participant
   const csv = [header, ...rows].join('\n') + '\n';
   const outPath = join(config.outputDir, 'event-log.csv');
   writeFileSync(outPath, csv);

package/src/cli/renderers/extensions.js

@@ -5,6 +5,7 @@
 
 import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { countSidebarOpenings } from '../analyzers/summary.js';
 
 export async function renderExtensions(participants, config) {
   const header = 'participantId,detectionType,name,details';
@@ -20,9 +21,17 @@ export async function renderExtensions(participants, config) {
       rows.push(`${pid},extension,${escapeCSV(name)},`);
     }
 
-    // Sidebar detection
-    const hasSidebar = p.trials.some(t => (t.sidebarGapPx || 0) > 0);
-    if (hasSidebar) {
+    // Sidebar detection. Prefer the current library's session-level
+    // sidebarEvents (the monitor records sidebars session-scoped, not per-trial);
+    // fall back to the legacy per-trial sidebarGapPx only when no session events
+    // exist (pre-session / Shape-2 legacy data). countSidebarOpenings() counts
+    // distinct openings (collapsing the paired open/close records and the
+    // innerWidth_delta + layout_compression double-detection), matching the
+    // summary/triage count.
+    const sidebarOpens = countSidebarOpenings(p.session?.sidebarEvents);
+    if (sidebarOpens > 0) {
+      rows.push(`${pid},sidebar,browser_sidebar,${sidebarOpens} open event${sidebarOpens === 1 ? '' : 's'}`);
+    } else if (p.trials.some(t => (t.sidebarGapPx || 0) > 0)) {
       const maxGap = Math.max(...p.trials.map(t => t.sidebarGapPx || 0));
       rows.push(`${pid},sidebar,browser_sidebar,${maxGap}px gap`);
     }

package/src/cli/renderers/html-index.js

@@ -11,14 +11,22 @@
 //
 // References linked images in images/ (not base64-embedded). Works offline.
 
-import { writeFileSync } from 'fs';
+import { writeFileSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { VERSION } from '../../shared/constants.js';
+import { VERSION, sanitizeId } from '../../shared/constants.js';
 import { decomposeScore } from '../analyzers/triage.js';
+import { getByPath } from '../ingest.js';
+
+// The replay viewer client is developed as a real JS file (linted, syntax-
+// highlighted) and embedded verbatim at render time — same file://-safe
+// output as the inline IIFE, without string-blob development pain.
+const REPLAY_CLIENT_SRC = readFileSync(
+  new URL('./replay-viewer.client.js', import.meta.url), 'utf8');
 
 export async function renderHtmlIndex(summaries, triage, participants, config, visualsRendered) {
   // Cohort counts for filter chips and totals footer. The triage array is
-  // already sorted descending by score by triage.js — we don't re-sort here.
+  // already sorted tier-first (hard → soft → clean, score-desc within tier) by
+  // triage.js — we don't re-sort here; the default "Tier" sort matches it.
   const hard  = triage.filter(t => t.hardTriggered).length;
   const soft  = triage.filter(t => !t.hardTriggered && t.softFlagged).length;
   const clean = triage.length - hard - soft;
@@ -33,7 +41,7 @@ export async function renderHtmlIndex(summaries, triage, participants, config, v
   // exercised by the second smoke test.
   const detailHtml = triage.map((t, i) => {
     const participant = participants.find(p => p.participantId === t.participantId);
-    return renderDetail(t, participant, visualsRendered, /* defaultVisible */ i === 0);
+    return renderDetail(t, participant, config, visualsRendered, /* defaultVisible */ i === 0);
   }).join('\n');
 
   const html = `<!DOCTYPE html>
@@ -420,12 +428,12 @@ export async function renderHtmlIndex(summaries, triage, participants, config, v
           <tr><td>copy</td>              <td>Clipboard copy from the page (soft signal).</td></tr>
           <tr><td>drop</td>              <td>Drag-and-drop into the response field (hard signal).</td></tr>
           <tr><td>tab-away &ge;10s</td>  <td>Left the page for &ge;10 seconds; counts toward soft score.</td></tr>
-          <tr><td>tab-away 3&ndash;10s</td><td>Left the page briefly; counts toward soft score.</td></tr>
-          <tr><td>flicker &lt;3s</td>    <td>Very brief blur; reported but not scored.</td></tr>
+          <tr><td>tab-away (mid)</td>    <td>Longer than the participant's tab-away threshold (3s by default, 5s strict) and under 10s; counts toward soft score.</td></tr>
+          <tr><td>flicker</td>           <td>At or below the tab-away threshold (3s by default); reported but not scored.</td></tr>
           <tr><td>sidebar event</td>     <td>Viewport width shrank suddenly &mdash; likely AI sidebar opened.</td></tr>
           <tr><td>AI extension</td>      <td>Browser extension known for AI assistance detected.</td></tr>
           <tr><td>kb shortcut</td>       <td>DevTools-adjacent keyboard shortcut used.</td></tr>
-          <tr><td>layout shift</td>      <td>Viewport layout changed substantially.</td></tr>
+          <tr><td>viewport shift</td>    <td>Viewport width changed substantially (recorded as "layout shift" before 0.6.1).</td></tr>
           <tr><td>zoom change</td>       <td>Browser zoom level changed.</td></tr>
           <tr><td>synthetic insertion</td><td>Text appeared without matching keystrokes.</td></tr>
           <tr><td>foreign input</td>     <td>Keystroke outside the response field.</td></tr>
@@ -665,6 +673,79 @@ export async function renderHtmlIndex(summaries, triage, participants, config, v
       });
     })();
   </script>
+  <style>
+    /* Replay viewer (see replay-viewer.client.js) — matches report house style */
+    .replay-header { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; margin: 8px 0; }
+    .replay-badge { font-size: 11px; font-weight: 600; padding: 2px 8px; border-radius: 10px;
+                    background: var(--ink); color: var(--surface); }
+    .replay-badge[data-tier="trace"] { background: var(--surface); color: var(--ink);
+                    border: 1px solid var(--line); }
+    .replay-stage { position: relative; overflow: hidden; background: var(--surface);
+                    border: 1px solid var(--line); border-radius: 4px; }
+    .replay-frame { position: absolute; top: 0; left: 0; border: 0; }
+    .replay-overlay { position: absolute; top: 0; left: 0; pointer-events: none; }
+    .replay-neutral { background: #e8e6e0; }
+    .replay-neutral-label { position: absolute; top: 50%; left: 50%; transform: translate(-50%,-50%);
+                            color: var(--dim); font-size: 13px; }
+    .replay-lane { display: block; margin-top: 6px; border-radius: 2px; }
+    .replay-scrub { display: block; margin: 2px 0 4px; }
+    .replay-ticker { font: 12px/1.3 ui-monospace, SFMono-Regular, 'IBM Plex Mono', monospace;
+                     color: var(--dim); font-variant-numeric: tabular-nums;
+                     height: 1.4em; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+    .replay-note { font-size: 12px; color: var(--dim); }
+    .replay-warn { color: var(--hard); }
+    /* Controls share the report's flat, line-bordered button style */
+    .replay-play, .replay-load-btn, .replay-css-btn, .replay-trial-select, .replay-speed {
+      padding: 4px 10px; border: 1px solid var(--line); background: var(--surface);
+      color: var(--ink); border-radius: 4px; cursor: pointer; font-size: 13px; }
+    .replay-play:hover, .replay-load-btn:hover, .replay-css-btn:hover { background: var(--bg); }
+    .replay-play:disabled, .replay-load-btn:disabled { opacity: 0.6; cursor: default; }
+    .replay-css-btn { font-size: 12px; padding: 2px 8px; }
+    .replay-clock { font: 12px/1.3 ui-monospace, SFMono-Regular, 'IBM Plex Mono', monospace;
+                    font-variant-numeric: tabular-nums; }
+  </style>
+  <script>
+${REPLAY_CLIENT_SRC}
+  </script>
+  <script>
+    // Lazy loader: replay models are heavy (dom tier ≈ MBs), so each
+    // participant's model script loads only when the analyst asks for it.
+    // Script-tag injection works under file:// where fetch() is blocked.
+    (function () {
+      document.addEventListener('click', function (e) {
+        const btn = e.target.closest('.replay-load-btn');
+        if (!btn) return;
+        const block = btn.closest('.replay-block');
+        const src = block.dataset.replaySrc;
+        const pid = block.dataset.pid;
+        const mount = block.querySelector('.replay-mount');
+        btn.disabled = true;
+        btn.textContent = 'Loading…';
+        mount.setAttribute('aria-busy', 'true');
+        const fail = function (msg) {
+          mount.removeAttribute('aria-busy');
+          const p = document.createElement('p');
+          p.className = 'replay-note replay-warn';
+          p.textContent = msg;
+          mount.textContent = '';
+          mount.appendChild(p);
+        };
+        const s = document.createElement('script');
+        s.src = src;
+        s.onload = function () {
+          mount.removeAttribute('aria-busy');
+          const model = (window.__chReplay || {})[pid];
+          if (!model) { fail('Replay data failed to load (' + src + ').'); return; }
+          mount.textContent = '';
+          window.initChReplayViewer(mount, model);
+        };
+        s.onerror = function () {
+          fail('Replay asset missing (' + src + ') — was the report generated with the replay artifacts present?');
+        };
+        document.body.appendChild(s);
+      });
+    })();
+  </script>
 </body>
 </html>`;
 
@@ -692,17 +773,17 @@ const SIGNALS = [
   { key: 'totalCopyEvents',          label: 'Copy',            tone: 'warn',     hint: 'Clipboard copy events from the task' },
   { key: 'totalDropEvents',          label: 'Drop',            tone: 'critical', hint: 'Drag-and-drop into inputs' },
   { key: 'tabAwayLongCount',         label: 'Tab-away ≥10s',   tone: 'critical', hint: 'Window blurred for 10+ seconds' },
-  { key: 'tabAwayMediumCount',       label: 'Tab-away 3–10s',  tone: 'warn',     hint: 'Short tab-aways — often a peek' },
-  { key: 'tabAwayFlickerCount',      label: 'Flicker <3s',     tone: 'muted',    hint: 'Very short visibility flickers' },
+  { key: 'tabAwayMediumCount',       label: 'Tab-away (mid)',  tone: 'warn',     hint: 'Above the tab-away threshold (3s default, 5s strict), under 10s' },
+  { key: 'tabAwayFlickerCount',      label: 'Flicker',         tone: 'muted',    hint: 'At or below the tab-away threshold (3s default) — not scored' },
   { key: 'trialsWithFastTyping',     label: 'Fast typing',     tone: 'warn',     hint: 'Trials typed faster than the preset cps threshold' },
   { key: 'totalSyntheticInsertions', label: 'Synthetic',       tone: 'warn',     hint: 'Text appeared without preceding keystrokes' },
   { key: 'totalForeignInputEvents',  label: 'Foreign input',   tone: 'warn',     hint: 'Typing landed outside the experiment container' },
   { key: 'sidebarEventCount',        label: 'Sidebar',         tone: 'warn',     hint: 'innerWidth shrank — side panel opened' },
   { key: 'aiExtensionsCount',        label: 'AI extensions',   tone: 'critical', hint: 'Known AI extension selectors found in DOM' },
-  { key: 'keyboardShortcutCount',    label: 'Kb shortcuts',    tone: 'warn',     hint: 'Cmd/Ctrl-C/V / AI-specific keys' },
-  { key: 'layoutShiftCount',         label: 'Layout shifts',   tone: 'muted',    hint: 'Inferred layout compression events' },
+  { key: 'keyboardShortcutCount',    label: 'Kb shortcuts',    tone: 'warn',     hint: 'DevTools hotkeys: Ctrl/Cmd+Shift+I/J/C, F12' },
+  { key: 'layoutShiftCount',         label: 'Viewport shifts', tone: 'muted',    hint: 'Viewport-width change events (recorded as layoutShifts before 0.6.1)' },
   { key: 'zoomChangeCount',          label: 'Zoom changes',    tone: 'muted',    hint: 'Browser zoom level changed during task' },
-  { key: 'devToolsEventCount',       label: 'DevTools',        tone: 'muted',    hint: 'DevTools opened or related shortcut' },
+  { key: 'devToolsEventCount',       label: 'DevTools',        tone: 'muted',    hint: 'Reserved (always 0) — DevTools opens are counted under Kb shortcuts' },
   { key: 'edgeExitCount',            label: 'Edge exits',      tone: 'muted',    hint: 'Mouse exited window through a screen edge' }
 ];
 
@@ -753,9 +834,9 @@ function renderCohortList(triage, cohortCounts) {
   <div class="sort-wrap">
     <label>Sort:
       <select name="sort">
+        <option value="tier" selected>Tier (hard first)</option>
         <option value="score">Score &darr;</option>
         <option value="id">ID</option>
-        <option value="tier">Tier</option>
       </select>
     </label>
   </div>
@@ -824,13 +905,14 @@ function sanitize(name) {
 // signals, paste evidence, and images. The `hidden` attribute is omitted on the
 // first pane so the report has a default selection on load; client JS toggles
 // `hidden` on the others when the user clicks a different cohort row.
-function renderDetail(t, participant, visualsRendered, defaultVisible) {
+function renderDetail(t, participant, config, visualsRendered, defaultVisible) {
   const sanitized = sanitize(t.participantId);
   const tier = tierOf(t);
   const s = t.summary || {};
 
-  // Image sections — three .image-block wrappers (tab timeline, typing profile,
-  // mouse trajectories). The renderers in tab-timeline.js / typing-profile.js /
+  // Image sections — three .image-block wrappers (session timeline, typing
+  // profile, mouse trajectories). The renderers in session-timeline.js /
+  // typing-profile.js /
   // trajectories.js skip participants under various conditions, so not every
   // participant has every image. The wrapper exists so onerror can hide both
   // the heading and the image together — without it, a missing PNG would leave
@@ -849,9 +931,9 @@ function renderDetail(t, participant, visualsRendered, defaultVisible) {
       </a>
     </div>
     <div class="image-block">
-      <h4 class="section-heading">Tab timeline</h4>
-      <a href="images/tab_timeline_${sanitized}.png" class="zoomable">
-        <img src="images/tab_timeline_${sanitized}.png" alt="Tab timeline"
+      <h4 class="section-heading">Session timeline</h4>
+      <a href="images/session_timeline_${sanitized}.png" class="zoomable">
+        <img src="images/session_timeline_${sanitized}.png" alt="Session timeline"
              onerror="this.closest('.image-block').style.display='none'">
       </a>
     </div>
@@ -867,16 +949,59 @@ function renderDetail(t, participant, visualsRendered, defaultVisible) {
   }
 
   return `<section class="participant" id="p-${sanitized}"${defaultVisible ? '' : ' hidden'}>
-    ${renderDetailHeader(t, tier)}
+    ${renderDetailHeader(t, tier, participant, config)}
     ${renderSignalGrid(s, t)}
     ${renderScoreBreakdown(t)}
     ${renderReasonQuote(t)}
     ${renderSessionBlock(s, participant)}
     ${renderPasteEvidence(participant)}
     ${imagesHtml}
+    ${renderReplaySection(participant, sanitized)}
   </section>`;
 }
 
+// Renders the per-participant "Session replay" section in one of three
+// states: loadable (artifact attached), corrupted, or absent (with the
+// saved_to reason from integrityReplayMeta when one exists, so the analyst
+// can tell "never recorded" from "went to the participant's Downloads").
+function renderReplaySection(participant, sanitized) {
+  const replay = participant?.replay;
+  if (replay && replay.recording) {
+    const tier = replay.recording.metadata?.tier || 'trace';
+    // assetPath is stamped by replay-assets.js (collision-deduped filename)
+    // and must be preferred — recomputing from the sanitized pid here would
+    // resurrect the lossy-name collision the assets renderer just resolved.
+    // Fallback uses the SHARED sanitizer (persistence/ingest/assets),
+    // not this file's image-oriented sanitize (which truncates + strips
+    // dots and would miss the asset filename for long/dotted pids).
+    const assetPath = replay.assetPath || `replay/${sanitizeId(participant.participantId)}.replay.js`;
+    return `<div class="image-block replay-block" data-pid="${esc(participant.participantId)}"
+         data-replay-src="${esc(assetPath)}">
+      <h4 class="section-heading">Session replay <span class="replay-note">(${esc(tier)} tier)</span></h4>
+      <div class="replay-mount">
+        <button class="replay-load-btn" type="button">Load replay</button>
+      </div>
+    </div>`;
+  }
+  if (replay && replay.error) {
+    return `<div class="image-block replay-block">
+      <h4 class="section-heading">Session replay</h4>
+      <p class="replay-note replay-warn">Replay artifact corrupted (${esc(replay.reason || replay.error)}) — file: ${esc(replay.file || 'unknown')}</p>
+    </div>`;
+  }
+  const meta = participant?.trials?.[0]?.integrityReplayMeta;
+  if (meta) {
+    return `<div class="image-block replay-block">
+      <h4 class="section-heading">Session replay</h4>
+      <p class="replay-note">No replay artifact on disk. The session reported saved_to: <strong>${esc(String(meta.saved_to))}</strong>${meta.saved_to === 'download' ? ' — the file went to the participant’s machine and is not recoverable' : ''}.</p>
+    </div>`;
+  }
+  return `<div class="image-block replay-block">
+      <h4 class="section-heading">Session replay</h4>
+      <p class="replay-note">No replay artifact (recording was not enabled for this session).</p>
+    </div>`;
+}
+
 // Renders the participant's screenout reason as a left-bordered pull-quote.
 // `t.reason` is set by triage.js; falls back to "clean" when absent. Always
 // renders a quote (even for clean participants) so the visual rhythm is consistent.
@@ -955,12 +1080,26 @@ function formatSidebar(ev) {
 }
 
 // Header strip: full participant id (mono), tier pill, big score number on the
-// top row; "{n} trials · {cps} cps · {off-task}" subline below.
-function renderDetailHeader(t, tier) {
+// top row; "{n} trials · {cps} cps · {off-task}" subline below. When BOTH
+// config.platformIdField is mapped AND config.showPlatformId is true, a
+// second subline shows the platform (Prolific/MTurk) ID — OFF by default
+// because reports circulate among collaborators more freely than raw data,
+// and the platform ID is the piece that re-identifies a participant.
+function renderDetailHeader(t, tier, participant, config) {
   const s = t.summary || {};
   const cps = (s.meanTypingSpeed || 0).toFixed(1);
   const offTask = formatDuration(s.totalTabAwayDuration_ms || 0);
   const tierLabel = tier === 'clean' ? 'clean' : tier.toUpperCase();
+  let platformLine = '';
+  if (config?.showPlatformId && config?.platformIdField) {
+    const value = getByPath(participant?.metadata, config.platformIdField)
+      ?? getByPath(participant, config.platformIdField)
+      ?? getByPath(participant?.trials?.[0], config.platformIdField);
+    if (value != null && value !== '') {
+      platformLine = `
+    <div class="detail-header-sub mono">platform ID: ${esc(String(value))}</div>`;
+    }
+  }
   return `<div class="detail-header">
     <div class="detail-header-top">
       <span class="mono pid-full">${esc(t.participantId)}</span>
@@ -969,7 +1108,7 @@ function renderDetailHeader(t, tier) {
     </div>
     <div class="detail-header-sub">
       ${s.trialCount ?? 0} trials · ${cps} cps · ${offTask} off-task
-    </div>
+    </div>${platformLine}
   </div>`;
 }
 
@@ -1012,7 +1151,7 @@ function formatDuration(ms) {
 // Task 11's client JS will wire up to swap the preview for the full text.
 function renderPasteEvidence(participant) {
   // Flatten across trials, keeping [trialId] context for each paste. Match the
-  // event-log.csv convention: prefer trialId, fall back to ruleId (rule-gallery
+  // event-log.csv convention: prefer trialId, fall back to ruleId (Shape-2
   // legacy data), then to '?' as a last resort. Paste text is coerced to string
   // because some malformed sources have non-string values.
   const pastes = [];

package/src/cli/renderers/replay-assets.js

@@ -0,0 +1,177 @@
+// src/cli/renderers/replay-assets.js
+// Emits per-participant replay assets into <outputDir>/replay/ as
+// JSONP-style scripts: window.__chReplay['<pid>'] = <viewer model>.
+//
+// Why script files instead of JSON + fetch(): the HTML report is opened
+// via file:// where fetch() of local files is CORS-blocked, but <script>
+// tags load fine. The report injects the script lazily when the analyst
+// opens a participant's Replay section.
+//
+// This module is also the wire→viewer time conversion (the second of the
+// two allowed conversion points): SessionRecording carries ms since
+// session start; the viewer speaks trial-relative ms.
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+import { sanitizeId as sanitize } from '../../shared/constants.js';
+
+/**
+ * Wire SessionRecording → viewer model. Times become trial-relative
+ * (t − t_load); null anchors (standalone implicit trials) degrade to the
+ * first event's time so durations are always finite.
+ */
+export function buildViewerModel(recording) {
+  const md = recording.metadata || {};
+  const ext = recording.ch_extensions || {};
+
+  // ── Camera seeding (central, per Sol round-1 finding 8) ──
+  // New recordings carry a per-trial view_state seed. Legacy recordings
+  // don't — but the full event stream is present, so each trial's starting
+  // camera is reconstructed by folding all PRIOR trials' window-scroll and
+  // resize events over the session-start viewport. Initial scroll is assumed
+  // 0 (a recording that starts pre-scrolled with no scroll events is
+  // unrecoverable — that's what the viewer's legacy banner covers).
+  const vp = recording.viewport || {};
+  const vv = vp.visual_viewport || {};
+  // Scrollbar delta: legacy resize events carry only innerWidth/Height; the
+  // layout (client) width is estimated as w minus the session-start delta
+  // between innerWidth and the layout width (visual_viewport.width).
+  const sbW = (vp.width && (vp.client_width || vv.width))
+    ? vp.width - (vp.client_width || vv.width) : 0;
+  const sbH = (vp.height && (vp.client_height || vv.height))
+    ? vp.height - (vp.client_height || vv.height) : 0;
+  let foldState = {
+    x: 0, y: 0,
+    w: vp.width || null, h: vp.height || null,
+    cw: vp.client_width || vv.width || vp.width || null,
+    ch: vp.client_height || vv.height || vp.height || null,
+    dpr: vp.dpr || 1
+  };
+  const foldEvent = (state, e) => {
+    if (e.kind === 'scroll' && e.el == null && e.redacted == null) {
+      state.x = Number(e.x) || 0;
+      state.y = Number(e.y) || 0;
+    } else if (e.kind === 'resize') {
+      state.w = e.w != null ? e.w : state.w;
+      state.h = e.h != null ? e.h : state.h;
+      state.cw = e.cw != null ? e.cw : (e.w != null ? e.w - sbW : state.cw);
+      state.ch = e.ch != null ? e.ch : (e.h != null ? e.h - sbH : state.ch);
+      if (e.dpr != null) state.dpr = e.dpr;
+    }
+    return state;
+  };
+
+  // Defensive against malformed/truncated artifacts (a hand-edited or
+  // partially-written recording): non-array trials/events and null entries must
+  // degrade to empty rather than throw and abort the whole cohort report.
+  const rawTrials = Array.isArray(recording.trials) ? recording.trials : [];
+  const trials = rawTrials.map((trial) => {
+    trial = trial || {};
+    // Sort by absolute time before anchoring. RAF-coalesced input events flush
+    // with an EARLIER timestamp than events pushed after they were enqueued, so
+    // the recorded array is not strictly time-ordered; the viewer scrubs by
+    // scanning until the first future event and would otherwise mis-apply an
+    // out-of-order event on a seek. Stable sort keeps equal-time order.
+    const events = (Array.isArray(trial.events) ? trial.events : [])
+      .filter((e) => e && typeof e === 'object')
+      .slice()
+      .sort((a, b) => (Number(a.t) || 0) - (Number(b.t) || 0));
+    const anchor = trial.t_load != null ? trial.t_load
+      : (events.length > 0 ? events[0].t : 0);
+    const lastT = events.length > 0 ? events[events.length - 1].t : anchor;
+    const end = trial.t_end != null ? trial.t_end : lastT;
+    // Camera seed for THIS trial: recorded view_state, else the folded state
+    // as of the end of the previous trial. A recorded view_state also
+    // RESYNCS the fold — in a mixed recording (some trials seeded, some
+    // not: truncation, version mixes) a later unseeded trial must inherit
+    // real observed state, not a fold that ignored every observation.
+    if (trial.view_state) foldState = Object.assign({}, foldState, trial.view_state);
+    const camera = trial.view_state
+      ? Object.assign({}, trial.view_state, { source: 'view_state' })
+      : Object.assign({}, foldState, { source: 'folded' });
+    // Advance the fold across this trial's events for the NEXT trial's seed.
+    events.forEach((e) => foldEvent(foldState, e));
+    return {
+      index: trial.trial_index,
+      id: trial.trial_id,
+      plugin: trial.plugin,
+      durMs: Math.max(0, Math.round((end - anchor) * 10) / 10),
+      initialDom: trial.initial_dom || '',
+      camera,
+      events: events.map((e) => {
+        const out = Object.assign({}, e);
+        out.t = Math.max(0, Math.round(((Number(e.t) || 0) - anchor) * 10) / 10);
+        return out;
+      })
+    };
+  });
+
+  return {
+    pid: md.participant_id != null ? String(md.participant_id) : 'unknown',
+    tier: md.tier || 'trace',
+    keys: md.keys || null,
+    startTime: md.start_time || null,
+    endReason: md.end_reason || null,
+    recorder: md.recorder || null,
+    viewport: recording.viewport || null,
+    // Legacy = ANY trial lacks a view_state seed (all-legacy recordings and
+    // mixed/truncated ones alike): those trials replay on folded camera
+    // state, so the reduced-guarantees banner must show.
+    legacy: !rawTrials.every((t) => t && t.view_state),
+    markerAttr: ext.marker_attr || null,
+    // Session scrollbar delta (innerWidth − layout width): the viewer uses
+    // the same fallback chain as the folding above for legacy resize events.
+    scrollbar: { w: sbW, h: sbH },
+    stylesheets: (recording.stylesheets && recording.stylesheets.initial) || [],
+    scoring: ext.scoring || null,
+    guardViolations: ext.guard_violations || [],
+    captureStopped: !!ext.capture_stopped,
+    captureFailures: (ext.capture_failures || []).map((f) => f.channel),
+    trials
+  };
+}
+
+/**
+ * Writes replay/<sanitizedPid>.replay.js for every participant with an
+ * attached recording. Returns { count, totalBytes } so report.js can print
+ * an honest size line (replay assets dominate report size at dom tier).
+ */
+export function renderReplayAssets(participants, outputDir) {
+  let count = 0;
+  let totalBytes = 0;
+  const withReplay = participants.filter((p) => p.replay && p.replay.recording);
+  if (withReplay.length === 0) return { count, totalBytes };
+
+  const replayDir = join(outputDir, 'replay');
+  mkdirSync(replayDir, { recursive: true });
+
+  // Sanitization is lossy ('a/b' and 'a_b' both map to a_b) — dedupe with a
+  // stable numeric suffix so a later write can never overwrite an earlier
+  // participant's asset. The actual path is stamped on the participant
+  // (replay.assetPath) and consumed by html-index, which must not recompute.
+  const usedNames = new Set();
+  for (const p of withReplay) {
+    const model = buildViewerModel(p.replay.recording);
+    // The store is keyed by the RAW participant id (what the report's
+    // loader passes); the filename uses the sanitized form.
+    // Null-prototype store: participant ids are untrusted, and a pid like
+    // "__proto__" on a plain object would mutate the store's prototype
+    // instead of creating an entry (prototype pollution).
+    const src =
+      'window.__chReplay = window.__chReplay || Object.create(null);\n' +
+      'window.__chReplay[' + JSON.stringify(String(p.participantId)) + '] = ' +
+      JSON.stringify(model).replace(/</g, '\\u003c') + ';\n';
+    let base = sanitize(p.participantId);
+    let name = base + '.replay.js';
+    for (let n = 2; usedNames.has(name.toLowerCase()); n++) {
+      name = base + '~' + n + '.replay.js';
+    }
+    usedNames.add(name.toLowerCase());
+    writeFileSync(join(replayDir, name), src);
+    p.replay.assetPath = 'replay/' + name;
+    count++;
+    totalBytes += Buffer.byteLength(src);
+  }
+  return { count, totalBytes };
+}