cyborg-hunter 0.7.0 → 0.7.3

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

@@ -7,130 +7,20 @@
 // 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.
+// The wire→viewer time conversion (the second of the two allowed conversion
+// points) lives in replay/viewer-model.js (0.7.2 extraction, pure/no Node
+// APIs so a browser demo can bundle it); this module re-exports it below.
 
 import { writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 
 import { sanitizeId as sanitize } from '../../shared/constants.js';
+import { buildViewerModel } from '../../replay/viewer-model.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
-  };
-}
+// Load-bearing re-export: renderReplayAssets (below) calls buildViewerModel
+// in-file, and tests/cli/replay-render.test.js + tests/replay/alignment-viewer-model.test.js
+// import it from here.
+export { buildViewerModel };
 
 /**
  * Writes replay/<sanitizedPid>.replay.js for every participant with an

package/src/cli/renderers/replay-viewer.client.js

@@ -48,6 +48,17 @@
   var TOL_CONTAIN = 2;
   var TOL_STAGE = 2;
 
+  // Keycast: how long a chip keeps fading after its keyup, in trial-relative
+  // ms. Purely a function of playhead (like the click-ripple fade in
+  // drawOverlay below), not real time, so seeking lands on the same visual
+  // state playing to it would.
+  var KEYCAST_FADE_MS = 500;
+
+  // Buffer-cap explanation fallback: recorder.js's REPLAY_DEFAULTS, used
+  // only when a stopped trial's own ch:capture_stopped event (the real
+  // configured value for THIS recording) can't be found.
+  var CAP_DEFAULTS = { events: 50000, chars: 8000000 };
+
   var DISCRETE_KINDS = {
     mousedown: true, mouseup: true, click: true, touchstart: true, touchend: true
   };
@@ -66,6 +77,17 @@
     return m + ':' + (rem < 10 ? '0' : '') + rem;
   }
 
+  // Human label for a keycast chip. e.key already names special keys well
+  // (Enter, Shift, Backspace, ArrowLeft…); the one gap is the space bar,
+  // which arrives as a literal ' ' and would render as an invisible chip.
+  function formatKeyLabel(key) {
+    return key === ' ' ? 'Space' : key;
+  }
+
+  function fmtCount(n) {
+    return n.toLocaleString('en-US');
+  }
+
   // ── DOM reconstruction (tier 'dom') ──
   // The recorded DOM is UNTRUSTED (an adversarial participant or extension
   // may have injected markup). sandbox="" already blocks scripts; the CSP
@@ -144,6 +166,12 @@
     var playhead = 0;          // trial-relative ms
     var playing = false;
     var speed = 1;
+    // Continuous whole-session playback, default ON: at a trial's end while
+    // playing, load the next trial and keep going, so an analyst watches a
+    // full session as one video instead of stopping at every boundary. The
+    // 'pause at trial boundaries' toggle flips this off, restoring the
+    // original per-trial-stop behavior.
+    var autoAdvance = true;
     var appliedIdx = 0;        // events applied so far (in trial event order)
     var iframeGen = 0;         // increments per rebuild; stale onloads bail
     var domReady = false;
@@ -186,18 +214,64 @@
       var o = el('option', null, s + '×'); o.value = String(s); speedSel.appendChild(o);
     });
     var clock = el('span', 'replay-clock', '0:00.0 / 0:00.0');
+    var sessionPos = el('span', 'replay-note replay-session-pos', '');
+    var pauseLabel = el('label', 'replay-pause-toggle');
+    var pauseCheckbox = document.createElement('input');
+    pauseCheckbox.type = 'checkbox';
+    pauseCheckbox.className = 'replay-pause-checkbox';
+    pauseCheckbox.checked = false;   // default: continuous playback ON
+    pauseCheckbox.addEventListener('change', function () {
+      autoAdvance = !pauseCheckbox.checked;
+    });
+    pauseLabel.appendChild(pauseCheckbox);
+    pauseLabel.appendChild(document.createTextNode(' Pause at trial boundaries'));
     header.appendChild(badge);
     header.appendChild(trialSel);
     header.appendChild(playBtn);
     header.appendChild(speedSel);
     header.appendChild(clock);
+    header.appendChild(sessionPos);
+    if (trials.length > 1) header.appendChild(pauseLabel);
     if (!model.scoring) {
       header.appendChild(el('span', 'replay-note',
-        'Integrity scoring not available (standalone recording)'));
+        'No integrity score attached (this recording was captured standalone)'));
     }
     if (model.captureStopped) {
-      header.appendChild(el('span', 'replay-note replay-warn',
-        'Capture stopped early (buffer cap)'));
+      // The real configured caps for THIS recording live on the trial's own
+      // ch:capture_stopped marker (recorder.js writes it with the limit that
+      // was actually crossed) — read those instead of assuming the library
+      // defaults, since maxEventsPerTrial/maxCharsPerTrial are configurable.
+      var capEventsLimit = null, capCharsLimit = null, capTrialsHit = 0;
+      trials.forEach(function (t) {
+        var hit = false;
+        (t.events || []).forEach(function (e) {
+          if (e.kind !== 'ch:capture_stopped') return;
+          hit = true;
+          if (e.limit != null && capEventsLimit == null) capEventsLimit = e.limit;
+          if (e.limit_chars != null && capCharsLimit == null) capCharsLimit = e.limit_chars;
+        });
+        if (hit) capTrialsHit++;
+      });
+      if (capEventsLimit == null) capEventsLimit = CAP_DEFAULTS.events;
+      if (capCharsLimit == null) capCharsLimit = CAP_DEFAULTS.chars;
+      var capTrialsCount = capTrialsHit || 1;
+      var capDetails = document.createElement('details');
+      capDetails.className = 'replay-note replay-warn replay-cap';
+      capDetails.setAttribute('data-ch-cap-note', '');
+      var capSummary = document.createElement('summary');
+      capSummary.textContent = 'Capture stopped early in ' + capTrialsCount +
+        ' trial' + (capTrialsCount === 1 ? '' : 's') + ' (buffer cap, details)';
+      var capBody = el('p', null,
+        'The recorder caps each trial at ' + fmtCount(capEventsLimit) + ' events or about ' +
+        fmtCount(capCharsLimit) + ' characters, whichever comes first (the character count ' +
+        'starts from that trial’s initial DOM snapshot). Once a trial crosses either cap, ' +
+        'that trial stops recording and a marker is written; the next trial starts capturing ' +
+        'fresh. The caps limit the damage one runaway trial can do. They do not bound the whole ' +
+        'session: a recording with many trials can still add up to a large file. Both caps are ' +
+        'configurable when the recorder is attached (maxEventsPerTrial, maxCharsPerTrial).');
+      capDetails.appendChild(capSummary);
+      capDetails.appendChild(capBody);
+      header.appendChild(capDetails);
     }
     // Alignment status chips — the "never fail silently" surface.
     var alignChip = el('span', 'replay-note', '');
@@ -206,17 +280,17 @@
     header.appendChild(alignChip);
     if (model.legacy) {
       var legacyChip = el('span', 'replay-note replay-warn',
-        'Legacy recording — reduced alignment guarantees (re-projected coordinates, unverified)');
+        'Legacy recording: alignment guarantees are reduced (coordinates re-projected, unverified)');
       legacyChip.setAttribute('data-ch-legacy', '');
       header.appendChild(legacyChip);
     }
     var iframeChip = el('span', 'replay-note replay-warn',
-      'Contains iframe content that was NOT captured — interactions inside it are invisible');
+      'This recording contains iframe content that was not captured. Interactions inside it are not visible here.');
     iframeChip.setAttribute('data-ch-iframe-warn', '');
     iframeChip.style.display = 'none';
     header.appendChild(iframeChip);
     var shadowChip = el('span', 'replay-note replay-warn',
-      'Contains shadow-DOM content that was NOT captured — those areas replay hollow');
+      'This recording contains shadow DOM content that was not captured. Those areas replay empty.');
     shadowChip.setAttribute('data-ch-shadow-warn', '');
     shadowChip.style.display = 'none';
     header.appendChild(shadowChip);
@@ -238,7 +312,7 @@
       return sh.css && /@keyframes/i.test(sh.css);
     });
     if (hasKeyframes) {
-      animChip.textContent = 'Page uses CSS animations — they replay on viewer time; animated positions are approximate';
+      animChip.textContent = 'This page uses CSS animations. They replay on the viewer’s own clock, so animated positions are approximate.';
       animChip.style.display = '';
     }
     header.appendChild(animChip);
@@ -247,7 +321,7 @@
     var omittedSheets = (model.stylesheets || []).filter(function (sh) { return !sh.css; }).length;
     if (omittedSheets > 0) {
       var cssNote = el('span', 'replay-note',
-        omittedSheets + ' external stylesheet(s) not loaded — layout may differ. ');
+        omittedSheets + ' external stylesheet(s) were not loaded. Layout may differ. ');
       var cssBtn = el('button', 'replay-css-btn', 'Load external CSS');
       cssBtn.title = 'Fetches the recorded stylesheet URLs from their origins (network requests leave this machine).';
       cssBtn.addEventListener('click', function () {
@@ -282,13 +356,21 @@
     } else {
       stage.classList.add('replay-neutral');
       stage.appendChild(el('div', 'replay-neutral-label',
-        'Trace-only recording — DOM not captured at this tier'));
+        'Trace-only recording: DOM was not captured at this tier'));
     }
 
     var overlay = document.createElement('canvas');
     overlay.className = 'replay-overlay';
     overlay.setAttribute('aria-hidden', 'true');
     stage.appendChild(overlay);
+    // Keycast: chips for keys currently down or recently released, mirroring
+    // the click-ripple/cursor-trail convention above (a pure function of
+    // playhead, drawn alongside them — see drawKeycast). keys:'off'
+    // recordings carry no keydown/keyup events, so this stays empty; that
+    // absence IS the honest signal, no separate note needed.
+    var keycast = el('div', 'replay-keycast');
+    keycast.setAttribute('aria-hidden', 'true');
+    stage.appendChild(keycast);
     mount.appendChild(stage);
     var ctx = overlay.getContext('2d');
 
@@ -443,6 +525,7 @@
         applyCamScroll();
         applyDomUpTo(thenSeekTo);
         drawOverlay();
+        drawKeycast();
         updateStatusChips();
         // Late-layout revalidation: web fonts settling after the first
         // layout can shift geometry and stale an initially-passing check.
@@ -707,6 +790,7 @@
         applyDomUpTo(playhead);
       }
       drawOverlay();
+      drawKeycast();
       drawLane();
       drawTicker();
       updateStatusChips();
@@ -813,6 +897,66 @@
       }
     }
 
+    // ── Keycast (bottom-of-stage chips) ──
+    // Pairs keydown with its keyup to get each key's [down, up] window, then
+    // returns the ones "live" at T: down and not yet released, or released
+    // within KEYCAST_FADE_MS. Non-redacted pairs match by e.code (handles
+    // overlapping holds, e.g. Shift+A); redacted pairs carry no code (the
+    // identity itself is withheld), so they match FIFO against each other —
+    // an approximation that assumes redacted keystrokes don't overlap, true
+    // for the single-field-typing case this exists to cover.
+    function computeKeycastChips(T) {
+      var events = trial().events;
+      var openByCode = new Map();
+      var redactedQueue = [];
+      var tokens = [];
+      for (var i = 0; i < events.length; i++) {
+        var e = events[i];
+        if (e.t > T) break;
+        if (e.kind !== 'keydown' && e.kind !== 'keyup') continue;
+        if (e.redacted) {
+          if (e.kind === 'keydown') {
+            var rtok = { redacted: true, downT: e.t, upT: null };
+            redactedQueue.push(rtok);
+            tokens.push(rtok);
+          } else {
+            var rt = redactedQueue.shift();
+            if (rt) rt.upT = e.t;
+          }
+          continue;
+        }
+        if (e.kind === 'keydown') {
+          // Auto-repeat sends keydown without an intervening keyup; keep the
+          // original token open rather than starting a new one.
+          if (!openByCode.has(e.code)) {
+            var tok = { key: e.key, downT: e.t, upT: null };
+            openByCode.set(e.code, tok);
+            tokens.push(tok);
+          }
+        } else {
+          var open = openByCode.get(e.code);
+          if (open) { open.upT = e.t; openByCode.delete(e.code); }
+        }
+      }
+      return tokens.filter(function (tok) {
+        return tok.upT == null || T <= tok.upT + KEYCAST_FADE_MS;
+      });
+    }
+
+    function drawKeycast() {
+      var chips = computeKeycastChips(playhead);
+      keycast.textContent = '';
+      chips.forEach(function (tok) {
+        var chip = el('span', 'replay-key-chip' + (tok.redacted ? ' replay-key-chip--redacted' : ''),
+          tok.redacted ? '•' : formatKeyLabel(tok.key));
+        if (tok.upT != null && playhead > tok.upT) {
+          var frac = Math.min(1, (playhead - tok.upT) / KEYCAST_FADE_MS);
+          chip.style.opacity = String(1 - frac);
+        }
+        keycast.appendChild(chip);
+      });
+    }
+
     // ── Marker lane (per trial; redrawn per seek so check marks appear) ──
     function drawLane() {
       var lctx = lane.getContext('2d');
@@ -886,7 +1030,7 @@
       }
       var fails = counters.patchFailures + counters.scrollFailures;
       if (fails > 0) {
-        failChip.textContent = '⚠ ' + fails + ' recorded change(s) could not be re-applied — replay may diverge';
+        failChip.textContent = '⚠ ' + fails + ' recorded change(s) could not be reapplied. Replay may diverge from the original session.';
         failChip.style.display = '';
       } else {
         failChip.style.display = 'none';
@@ -919,6 +1063,11 @@
       }
       lastFrame = ts;
       if (playhead >= trial().durMs) {
+        if (autoAdvance && trialIdx < trials.length - 1) {
+          loadTrial(trialIdx + 1);   // continue playing into the next trial
+          requestAnimationFrame(tick);
+          return;
+        }
         playing = false;
         playBtn.textContent = '▶';
         playBtn.setAttribute('aria-label', 'Play');
@@ -950,11 +1099,18 @@
       else if (ev.key === 'Home') { seek(0); ev.preventDefault(); }
       else if (ev.key === 'End') { seek(trial().durMs); ev.preventDefault(); }
     });
-    function selectTrial(i) {
+    function updateSessionPos() {
+      sessionPos.textContent = 'Trial ' + (trialIdx + 1) + ' of ' + trials.length;
+    }
+
+    // Loads trial i's DOM/camera/scrub state WITHOUT touching playing/playBtn
+    // — the continuous-playback boundary in tick() below calls this directly
+    // so play keeps running across the cut; selectTrial() (manual trial-pick
+    // and boot) wraps it with the playing=false reset a user-driven jump
+    // should have.
+    function loadTrial(i) {
       trialIdx = i;
-      playing = false;
-      playBtn.textContent = '▶';
-      playBtn.setAttribute('aria-label', 'Play');
+      trialSel.value = String(i);
       scrub.max = String(trial().durMs);
       trialHadIframe = false;
       trialHadShadow = false;
@@ -965,8 +1121,8 @@
       var recDpr = (trial().camera && trial().camera.dpr) ||
         (model.viewport && model.viewport.dpr) || null;
       if (recDpr && window.devicePixelRatio && recDpr !== window.devicePixelRatio) {
-        dprChip.textContent = 'Recorded at DPR ' + recDpr + ', viewing at DPR ' +
-          window.devicePixelRatio + ' — resolution-dependent styling may differ';
+        dprChip.textContent = 'Recorded at DPR ' + recDpr + ', now viewing at DPR ' +
+          window.devicePixelRatio + '. Resolution-dependent styling may differ.';
         dprChip.style.display = '';
       } else {
         dprChip.style.display = 'none';
@@ -979,6 +1135,13 @@
         flushCamSize();   // trace tier: transform initializes from the seed
       }
       seek(0);
+      updateSessionPos();
+    }
+    function selectTrial(i) {
+      playing = false;
+      playBtn.textContent = '▶';
+      playBtn.setAttribute('aria-label', 'Play');
+      loadTrial(i);
     }
     trialSel.addEventListener('change', function () {
       selectTrial(Number(trialSel.value) || 0);