cyborg-hunter 0.7.0 → 0.7.2

package/src/cli/renderers/typing-profile-core.js

@@ -0,0 +1,211 @@
+// src/cli/renderers/typing-profile-core.js
+//
+// Pure drawing core for per-participant typing-speed bar-chart images — no
+// Node APIs, so a browser demo can bundle it directly (0.7.2-style
+// extraction from cli/renderers/typing-profile.js, which is now a thin fs
+// wrapper around this module: it acquires node-canvas, calls
+// drawTypingProfile per participant, and writes the returned canvas to a
+// PNG). Mirrors the session-timeline-core.js / trajectories-core.js split.
+//
+// drawTypingProfile(p, config, createCanvas) draws one participant's typing
+// speed bar chart — one bar per trial's chars/sec, with a horizontal
+// threshold line and bars above threshold colored red — and returns the
+// drawn canvas (or null if there's nothing to draw: no trials, or no trial
+// has either a typed speed or a paste event). createCanvas is injected so
+// this module never imports the `canvas` package directly — a browser
+// caller can pass a document-canvas-backed factory instead.
+
+const BAR_WIDTH = 30;
+const BAR_GAP = 8;
+const CHART_HEIGHT = 200;
+const TOP_PAD = 50;
+const BOTTOM_PAD = 50;
+const LEFT_PAD = 60;
+
+// ── Per-participant renderer ─────────────────────────────────────────────
+// Returns the drawn canvas, or null if there's no data to draw (caller
+// decides what "no data" means — the fs wrapper skips the PNG write).
+export function drawTypingProfile(p, config, createCanvas) {
+  const trials = p.trials;
+  if (trials.length === 0) return null;
+
+  // Per-participant threshold line: prefer the typing-speed cutoff the library
+  // actually screened this participant with (saved in session.config.thresholds)
+  // so the red "fast typing" line matches summary.csv's count; fall back to the
+  // CLI/default. A strict participant (8 cps) otherwise shows a 10 cps line.
+  const threshold =
+    p.session?.config?.thresholds?.typingSpeedCps ?? config.typingSpeedThreshold_cps ?? 10;
+
+  // Per-trial state. We distinguish three cases:
+  //   "typed"       — charsPerSec is a real number, draw a normal bar
+  //   "paste-only"  — charsPerSec is null but there's a paste event; draw a
+  //                   grey hatched marker so the absence is legible. Single
+  //                   paste fires one input event → editTimestamps.length < 2
+  //                   → computeTypingSpeed returns null. Without this, a
+  //                   pasted response looks identical to a very slow one.
+  //   "no-data"     — neither, leave blank
+  const kinds = trials.map(t => {
+    if (typeof t.charsPerSec === 'number') return 'typed';
+    if ((t.pasteEvents || []).length > 0) return 'paste-only';
+    return 'no-data';
+  });
+  const speeds = trials.map(t => (typeof t.charsPerSec === 'number' ? t.charsPerSec : 0));
+  if (kinds.every(k => k === 'no-data')) return null;
+
+  const canvasW = LEFT_PAD + trials.length * (BAR_WIDTH + BAR_GAP) + 20;
+  const canvasH = TOP_PAD + CHART_HEIGHT + BOTTOM_PAD;
+  const canvas = createCanvas(canvasW, canvasH);
+  const ctx = canvas.getContext('2d');
+
+  // Background
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, canvasW, canvasH);
+
+  // Title
+  ctx.fillStyle = '#333';
+  ctx.font = 'bold 14px sans-serif';
+  ctx.fillText(`Typing Speed Profile — ${p.participantId}`, LEFT_PAD, 20);
+  ctx.font = '10px sans-serif';
+  ctx.fillStyle = '#666';
+  ctx.fillText(`Threshold: ${threshold} chars/sec`, LEFT_PAD, 35);
+
+  // Legend — three states documented in the `kinds` comment above.
+  const legendY = 35;
+  const legendX0 = LEFT_PAD + 180;
+  ctx.fillStyle = '#2196F3';
+  ctx.fillRect(legendX0, legendY - 8, 12, 10);
+  ctx.fillStyle = '#666';
+  ctx.fillText('typed', legendX0 + 16, legendY);
+  ctx.fillStyle = '#f44336';
+  ctx.fillRect(legendX0 + 60, legendY - 8, 12, 10);
+  ctx.fillStyle = '#666';
+  ctx.fillText('> threshold', legendX0 + 76, legendY);
+  // Hatched swatch for paste-only
+  drawHatchedRect(ctx, legendX0 + 150, legendY - 8, 12, 10);
+  ctx.fillStyle = '#666';
+  ctx.fillText('paste (P)', legendX0 + 166, legendY);
+
+  // Y-axis scaling
+  const maxSpeed = Math.max(...speeds, threshold * 1.5);
+  const yScale = CHART_HEIGHT / maxSpeed;
+
+  // Y-axis labels
+  ctx.fillStyle = '#666';
+  ctx.font = '9px sans-serif';
+  const yTicks = 5;
+  for (let t = 0; t <= yTicks; t++) {
+    const val = (maxSpeed / yTicks) * t;
+    const y = TOP_PAD + CHART_HEIGHT - val * yScale;
+    ctx.fillText(`${val.toFixed(1)}`, 5, y + 3);
+    // Grid line
+    ctx.strokeStyle = '#eee';
+    ctx.lineWidth = 0.5;
+    ctx.beginPath();
+    ctx.moveTo(LEFT_PAD, y);
+    ctx.lineTo(canvasW - 10, y);
+    ctx.stroke();
+  }
+
+  // Threshold line
+  const threshY = TOP_PAD + CHART_HEIGHT - threshold * yScale;
+  ctx.strokeStyle = '#ff0000';
+  ctx.lineWidth = 1.5;
+  ctx.setLineDash([5, 3]);
+  ctx.beginPath();
+  ctx.moveTo(LEFT_PAD, threshY);
+  ctx.lineTo(canvasW - 10, threshY);
+  ctx.stroke();
+  ctx.setLineDash([]);
+
+  // Bars
+  const PASTE_BAR_H = CHART_HEIGHT * 0.2; // Paste-only marker height: fixed 20% of chart.
+  for (let i = 0; i < trials.length; i++) {
+    const kind = kinds[i];
+    const speed = speeds[i];
+    const x = LEFT_PAD + i * (BAR_WIDTH + BAR_GAP);
+
+    if (kind === 'paste-only') {
+      // Fixed-height hatched grey bar + "P" marker. The height is arbitrary
+      // — the point is visible presence, not magnitude (we have no CPS to
+      // show). Sits at the bottom like a normal bar.
+      const y = TOP_PAD + CHART_HEIGHT - PASTE_BAR_H;
+      drawHatchedRect(ctx, x, y, BAR_WIDTH, PASTE_BAR_H);
+      ctx.strokeStyle = '#888';
+      ctx.lineWidth = 0.5;
+      ctx.strokeRect(x, y, BAR_WIDTH, PASTE_BAR_H);
+      // "P" marker above the bar
+      ctx.fillStyle = '#555';
+      ctx.font = 'bold 11px sans-serif';
+      ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
+    } else if (kind === 'typed') {
+      const barH = speed * yScale;
+      const y = TOP_PAD + CHART_HEIGHT - barH;
+      ctx.fillStyle = speed > threshold ? '#f44336' : '#2196F3';
+      ctx.fillRect(x, y, BAR_WIDTH, barH);
+      ctx.strokeStyle = '#333';
+      ctx.lineWidth = 0.5;
+      ctx.strokeRect(x, y, BAR_WIDTH, barH);
+      if (speed > 0) {
+        ctx.fillStyle = '#fff';
+        ctx.font = 'bold 9px sans-serif';
+        ctx.fillText(speed.toFixed(1), x + 3, y + 12);
+      }
+      // Mixed: typed AND pasted in the same trial. The bar shows the typing
+      // rate (legitimate signal); the "P" glyph above it flags that *some*
+      // of the response came in via paste. Distinct from pure paste-only
+      // (which is a hatched bar, no colored fill).
+      if ((trials[i].pasteEvents || []).length > 0) {
+        ctx.fillStyle = '#555';
+        ctx.font = 'bold 11px sans-serif';
+        ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
+      }
+    }
+    // 'no-data' → render nothing (blank column)
+
+    // Trial label (always drawn, even for blank columns)
+    const trialId = trials[i].trialId || trials[i].ruleId || `T${i + 1}`;
+    ctx.fillStyle = '#333';
+    ctx.font = '8px sans-serif';
+    ctx.save();
+    ctx.translate(x + BAR_WIDTH / 2, TOP_PAD + CHART_HEIGHT + 10);
+    ctx.rotate(Math.PI / 4);
+    ctx.fillText(trialId.substring(0, 12), 0, 0);
+    ctx.restore();
+  }
+
+  // Baseline
+  ctx.strokeStyle = '#333';
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  ctx.moveTo(LEFT_PAD, TOP_PAD + CHART_HEIGHT);
+  ctx.lineTo(canvasW - 10, TOP_PAD + CHART_HEIGHT);
+  ctx.stroke();
+
+  return canvas;
+}
+
+// Cross-hatched fill for paste-only markers. Uses a light grey background
+// with diagonal strokes so the bar reads as "distinct category, not zero".
+function drawHatchedRect(ctx, x, y, w, h) {
+  ctx.save();
+  ctx.fillStyle = '#e8e8e8';
+  ctx.fillRect(x, y, w, h);
+  ctx.beginPath();
+  ctx.rect(x, y, w, h);
+  ctx.clip();
+  ctx.strokeStyle = '#888';
+  ctx.lineWidth = 0.8;
+  const step = 5;
+  for (let d = -h; d < w + h; d += step) {
+    ctx.beginPath();
+    ctx.moveTo(x + d, y);
+    ctx.lineTo(x + d + h, y + h);
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+
+// Used by the fs wrapper to build the per-participant PNG filename.
+export function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 40);
+}

package/src/cli/renderers/typing-profile.js

@@ -1,177 +1,26 @@
 // src/cli/renderers/typing-profile.js
-// Renders per-participant typing speed bar chart using node-canvas.
-// Each bar = one trial's chars/sec. A horizontal threshold line shows
-// the configured CPS threshold. Bars above threshold are colored red.
-
+// Thin fs wrapper around the pure drawing core (typing-profile-core.js).
+// The core takes an injected createCanvas and returns the drawn canvas (or
+// null when there's nothing to draw); this wrapper owns node-canvas
+// acquisition and PNG serialization so the core can also run in a browser
+// context (demo plot adapter) with document canvases.
 import { writeFileSync } from 'fs';
 import { join } from 'path';
-
-const BAR_WIDTH = 30;
-const BAR_GAP = 8;
-const CHART_HEIGHT = 200;
-const TOP_PAD = 50;
-const BOTTOM_PAD = 50;
-const LEFT_PAD = 60;
-
+import { drawTypingProfile, sanitize } from './typing-profile-core.js';
+// Load-bearing re-export: drawTypingProfile serves this wrapper's own loop
+// below and the future browser demo plot adapter — mirrors
+// session-timeline.js / trajectories.js. (renderTypingProfiles remains the
+// only symbol external consumers import from this file — see
+// tests/cli/renderers.test.js and src/cli/report.js.)
+export { drawTypingProfile };
+
+// ── Public API ───────────────────────────────────────────────────────────
 export async function renderTypingProfiles(participants, config) {
   const { createCanvas } = await import('canvas');
 
   for (const p of participants) {
-    const trials = p.trials;
-    if (trials.length === 0) continue;
-
-    // Per-participant threshold line: prefer the typing-speed cutoff the library
-    // actually screened this participant with (saved in session.config.thresholds)
-    // so the red "fast typing" line matches summary.csv's count; fall back to the
-    // CLI/default. A strict participant (8 cps) otherwise shows a 10 cps line.
-    const threshold =
-      p.session?.config?.thresholds?.typingSpeedCps ?? config.typingSpeedThreshold_cps ?? 10;
-
-    // Per-trial state. We distinguish three cases:
-    //   "typed"       — charsPerSec is a real number, draw a normal bar
-    //   "paste-only"  — charsPerSec is null but there's a paste event; draw a
-    //                   grey hatched marker so the absence is legible. Single
-    //                   paste fires one input event → editTimestamps.length < 2
-    //                   → computeTypingSpeed returns null. Without this, a
-    //                   pasted response looks identical to a very slow one.
-    //   "no-data"     — neither, leave blank
-    const kinds = trials.map(t => {
-      if (typeof t.charsPerSec === 'number') return 'typed';
-      if ((t.pasteEvents || []).length > 0) return 'paste-only';
-      return 'no-data';
-    });
-    const speeds = trials.map(t => (typeof t.charsPerSec === 'number' ? t.charsPerSec : 0));
-    if (kinds.every(k => k === 'no-data')) continue;
-
-    const canvasW = LEFT_PAD + trials.length * (BAR_WIDTH + BAR_GAP) + 20;
-    const canvasH = TOP_PAD + CHART_HEIGHT + BOTTOM_PAD;
-    const canvas = createCanvas(canvasW, canvasH);
-    const ctx = canvas.getContext('2d');
-
-    // Background
-    ctx.fillStyle = '#ffffff';
-    ctx.fillRect(0, 0, canvasW, canvasH);
-
-    // Title
-    ctx.fillStyle = '#333';
-    ctx.font = 'bold 14px sans-serif';
-    ctx.fillText(`Typing Speed Profile — ${p.participantId}`, LEFT_PAD, 20);
-    ctx.font = '10px sans-serif';
-    ctx.fillStyle = '#666';
-    ctx.fillText(`Threshold: ${threshold} chars/sec`, LEFT_PAD, 35);
-
-    // Legend — three states documented in the `kinds` comment above.
-    const legendY = 35;
-    const legendX0 = LEFT_PAD + 180;
-    ctx.fillStyle = '#2196F3';
-    ctx.fillRect(legendX0, legendY - 8, 12, 10);
-    ctx.fillStyle = '#666';
-    ctx.fillText('typed', legendX0 + 16, legendY);
-    ctx.fillStyle = '#f44336';
-    ctx.fillRect(legendX0 + 60, legendY - 8, 12, 10);
-    ctx.fillStyle = '#666';
-    ctx.fillText('> threshold', legendX0 + 76, legendY);
-    // Hatched swatch for paste-only
-    drawHatchedRect(ctx, legendX0 + 150, legendY - 8, 12, 10);
-    ctx.fillStyle = '#666';
-    ctx.fillText('paste (P)', legendX0 + 166, legendY);
-
-    // Y-axis scaling
-    const maxSpeed = Math.max(...speeds, threshold * 1.5);
-    const yScale = CHART_HEIGHT / maxSpeed;
-
-    // Y-axis labels
-    ctx.fillStyle = '#666';
-    ctx.font = '9px sans-serif';
-    const yTicks = 5;
-    for (let t = 0; t <= yTicks; t++) {
-      const val = (maxSpeed / yTicks) * t;
-      const y = TOP_PAD + CHART_HEIGHT - val * yScale;
-      ctx.fillText(`${val.toFixed(1)}`, 5, y + 3);
-      // Grid line
-      ctx.strokeStyle = '#eee';
-      ctx.lineWidth = 0.5;
-      ctx.beginPath();
-      ctx.moveTo(LEFT_PAD, y);
-      ctx.lineTo(canvasW - 10, y);
-      ctx.stroke();
-    }
-
-    // Threshold line
-    const threshY = TOP_PAD + CHART_HEIGHT - threshold * yScale;
-    ctx.strokeStyle = '#ff0000';
-    ctx.lineWidth = 1.5;
-    ctx.setLineDash([5, 3]);
-    ctx.beginPath();
-    ctx.moveTo(LEFT_PAD, threshY);
-    ctx.lineTo(canvasW - 10, threshY);
-    ctx.stroke();
-    ctx.setLineDash([]);
-
-    // Bars
-    const PASTE_BAR_H = CHART_HEIGHT * 0.2; // Paste-only marker height: fixed 20% of chart.
-    for (let i = 0; i < trials.length; i++) {
-      const kind = kinds[i];
-      const speed = speeds[i];
-      const x = LEFT_PAD + i * (BAR_WIDTH + BAR_GAP);
-
-      if (kind === 'paste-only') {
-        // Fixed-height hatched grey bar + "P" marker. The height is arbitrary
-        // — the point is visible presence, not magnitude (we have no CPS to
-        // show). Sits at the bottom like a normal bar.
-        const y = TOP_PAD + CHART_HEIGHT - PASTE_BAR_H;
-        drawHatchedRect(ctx, x, y, BAR_WIDTH, PASTE_BAR_H);
-        ctx.strokeStyle = '#888';
-        ctx.lineWidth = 0.5;
-        ctx.strokeRect(x, y, BAR_WIDTH, PASTE_BAR_H);
-        // "P" marker above the bar
-        ctx.fillStyle = '#555';
-        ctx.font = 'bold 11px sans-serif';
-        ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
-      } else if (kind === 'typed') {
-        const barH = speed * yScale;
-        const y = TOP_PAD + CHART_HEIGHT - barH;
-        ctx.fillStyle = speed > threshold ? '#f44336' : '#2196F3';
-        ctx.fillRect(x, y, BAR_WIDTH, barH);
-        ctx.strokeStyle = '#333';
-        ctx.lineWidth = 0.5;
-        ctx.strokeRect(x, y, BAR_WIDTH, barH);
-        if (speed > 0) {
-          ctx.fillStyle = '#fff';
-          ctx.font = 'bold 9px sans-serif';
-          ctx.fillText(speed.toFixed(1), x + 3, y + 12);
-        }
-        // Mixed: typed AND pasted in the same trial. The bar shows the typing
-        // rate (legitimate signal); the "P" glyph above it flags that *some*
-        // of the response came in via paste. Distinct from pure paste-only
-        // (which is a hatched bar, no colored fill).
-        if ((trials[i].pasteEvents || []).length > 0) {
-          ctx.fillStyle = '#555';
-          ctx.font = 'bold 11px sans-serif';
-          ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
-        }
-      }
-      // 'no-data' → render nothing (blank column)
-
-      // Trial label (always drawn, even for blank columns)
-      const trialId = trials[i].trialId || trials[i].ruleId || `T${i + 1}`;
-      ctx.fillStyle = '#333';
-      ctx.font = '8px sans-serif';
-      ctx.save();
-      ctx.translate(x + BAR_WIDTH / 2, TOP_PAD + CHART_HEIGHT + 10);
-      ctx.rotate(Math.PI / 4);
-      ctx.fillText(trialId.substring(0, 12), 0, 0);
-      ctx.restore();
-    }
-
-    // Baseline
-    ctx.strokeStyle = '#333';
-    ctx.lineWidth = 1;
-    ctx.beginPath();
-    ctx.moveTo(LEFT_PAD, TOP_PAD + CHART_HEIGHT);
-    ctx.lineTo(canvasW - 10, TOP_PAD + CHART_HEIGHT);
-    ctx.stroke();
-
+    const canvas = drawTypingProfile(p, config, createCanvas);
+    if (!canvas) continue;
     const buf = canvas.toBuffer('image/png');
     const filename = `typing_profile_${sanitize(p.participantId)}.png`;
     writeFileSync(join(config.outputDir, 'images', filename), buf);
@@ -179,28 +28,3 @@ export async function renderTypingProfiles(participants, config) {
 
   console.log(`  typing profiles — rendered`);
 }
-
-function sanitize(name) {
-  return name.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 40);
-}
-
-// Cross-hatched fill for paste-only markers. Uses a light grey background
-// with diagonal strokes so the bar reads as "distinct category, not zero".
-function drawHatchedRect(ctx, x, y, w, h) {
-  ctx.save();
-  ctx.fillStyle = '#e8e8e8';
-  ctx.fillRect(x, y, w, h);
-  ctx.beginPath();
-  ctx.rect(x, y, w, h);
-  ctx.clip();
-  ctx.strokeStyle = '#888';
-  ctx.lineWidth = 0.8;
-  const step = 5;
-  for (let d = -h; d < w + h; d += step) {
-    ctx.beginPath();
-    ctx.moveTo(x + d, y);
-    ctx.lineTo(x + d + h, y + h);
-    ctx.stroke();
-  }
-  ctx.restore();
-}

package/src/core/monitor.js

@@ -378,6 +378,23 @@ export function init(userConfig) {
         report.mouseMetrics = mouseMetrics;
       }
 
+      // Privacy gate: the raw per-sample mouse coordinates are a much
+      // higher-resolution behavioral trace than the derived mouseMetrics
+      // above. Persist them ONLY when explicitly enabled
+      // (collectForPostHoc.rawMouseTrack) — under the `mouseTrack` name,
+      // which is what extract-core's field map already expects (mouseTrack →
+      // mouseEvents), so a saved report round-trips through
+      // extractIntegrityData() without new glue. Otherwise drop the raw
+      // report.mouseEvents entirely — the mouseMetrics signal above still
+      // works, but the {x,y,t,type} samples never leave the browser. Before
+      // this gate, deepCopy(trialData) put the full raw track in every
+      // report regardless of the documented off-by-default rawMouseTrack
+      // toggle.
+      if (config.collectForPostHoc.rawMouseTrack) {
+        report.mouseTrack = report.mouseEvents;
+      }
+      delete report.mouseEvents;
+
       // Accumulate into session
       sessionData.trialsCompleted++;
 

package/src/jspsych/extension-cyborg-hunter-replay.js

@@ -35,7 +35,7 @@ import { buildReplayMeta } from '../replay/persistence.js';
 class CyborgHunterReplayExtension {
   static info = {
     name: 'cyborg-hunter-replay',
-    version: '0.7.0',
+    version: '0.7.2',
     data: {}   // per-trial return is {}; session meta goes via addProperties
   };
 

package/src/jspsych/extension-cyborg-hunter.js

@@ -10,7 +10,7 @@ class CyborgHunterExtension {
     // and package.json). Hand-bumped on each release; if you forget, the
     // jsPsych developer console shows a stale number — the actual version
     // attached to data is read from window.CyborgHunter.VERSION at runtime.
-    version: '0.7.0',
+    version: '0.7.2',
     data: { integrity: { type: 'object' } }
   };
 

package/src/jspsych/extension-guard-friction.js

@@ -905,8 +905,11 @@ export function fullscreenElementOf(doc) {
     }
 
     // ----- Entry trial ---------------------------------------------
-    function createEntryTrial(opts = {}) {
-        const message = opts.message || `
+    // Hoisted out of createEntryTrial (verbatim string move) so the frozen
+    // public API can expose it as `defaultEntryMessage` below — demo/demo.js
+    // renders this SAME string verbatim on its guard-entry step, so it can
+    // never drift out of sync with what a real participant actually sees.
+    const DEFAULT_ENTRY_MESSAGE = `
             <h2>Fullscreen mode required</h2>
             <p>To keep the experiment fair for everyone, we ask that this study be completed in fullscreen mode,
                with no browser sidebars (Gemini, Copilot, Edge sidebar, etc.) open, and with this tab focused.</p>
@@ -914,6 +917,9 @@ export function fullscreenElementOf(doc) {
             <p>We care about collecting high-quality data, and these rules help ensure a fair experience for all participants.</p>
             <p>Please close any sidebars now, then click the button below to continue in fullscreen.</p>
         `;
+
+    function createEntryTrial(opts = {}) {
+        const message = opts.message || DEFAULT_ENTRY_MESSAGE;
         return {
             type: jsPsychHtmlButtonResponse,
             stimulus: message,
@@ -1048,6 +1054,9 @@ export function fullscreenElementOf(doc) {
         createEntryTrial: function (opts) { return createEntryTrial(opts); },
         onViolation: function (handler) { return onViolation(handler); },
         getCurrentState: function () { return getCurrentState(); },
+        // Added on the object literal BEFORE Object.freeze() below — a
+        // post-freeze assignment would silently no-op.
+        defaultEntryMessage: DEFAULT_ENTRY_MESSAGE,
     };
 
     Object.freeze(api);

package/src/replay/viewer-model.js

@@ -0,0 +1,125 @@
+// src/replay/viewer-model.js
+// Wire SessionRecording → viewer model. Pure — no Node APIs — so a browser
+// demo can bundle it directly (0.7.2 extraction from
+// cli/renderers/replay-assets.js, which re-exports this for existing
+// callers).
+//
+// This is one of exactly two allowed wire→viewer time-conversion points (the
+// other lives in the CLI ingest path): SessionRecording carries ms since
+// session start; the viewer speaks trial-relative ms.
+
+/**
+ * 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
+  };
+}

package/src/shared/constants.js

@@ -2,7 +2,7 @@
 // Default thresholds and preset configurations for Cyborg Hunter.
 // Single source of truth — used by both the browser library and CLI report tool.
 
-export const VERSION = "0.7.0";
+export const VERSION = "0.7.2";
 
 // Default detection thresholds shared across presets.
 // Researchers can override any value at init() time.

package/src/shared/paths.js

@@ -0,0 +1,20 @@
+// src/shared/paths.js
+// Pure path-walking helper. No Node APIs — shared by CLI and browser preview.
+// Used by: CLI ingest/renderers and the browser preview bundle.
+
+// Resolves a possibly-dotted field path against an object (0.6.1).
+// A flat key wins over a dotted walk, so data that literally contains a
+// "metadata.sessionId" column stays addressable; otherwise the path is
+// walked one segment at a time. Returns undefined when any segment is
+// missing or a non-object is hit mid-path.
+export function getByPath(obj, path) {
+  if (obj == null || typeof path !== 'string' || path.length === 0) return undefined;
+  if (Object.prototype.hasOwnProperty.call(obj, path)) return obj[path];
+  if (!path.includes('.')) return undefined;
+  let cur = obj;
+  for (const seg of path.split('.')) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}