cyborg-hunter 0.5.0 → 0.7.2

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.5.0";
+export const VERSION = "0.7.2";
 
 // Default detection thresholds shared across presets.
 // Researchers can override any value at init() time.
@@ -11,6 +11,7 @@ export const DEFAULT_THRESHOLDS = {
   dropMinChars: 0,             // record ALL drops
   sidebarGapPx: 100,           // outerWidth - innerWidth above this = sidebar
   layoutCompressionPx: 20,     // innerWidth - clientWidth above scrollbar width
+  viewportShiftDebounceMs: 250, // quiet period before a viewport-width shift is logged (one gesture = one event)
   syntheticGapMs: 100,         // keydown-to-input gap above this = synthetic insertion
   idleGapMs: 10000,            // no input for this long = idle gap
   idleCheckIntervalMs: 5000,   // how often to check for idle gaps
@@ -37,7 +38,7 @@ export const PRESETS = {
   permissive: {
     // Collect everything, screen out nobody. For calibration/pilot studies.
     signals: {
-      paste: true, copy: true, tabAway: true, typingSpeed: true,
+      paste: true, copy: true, drop: true, tabAway: true, typingSpeed: true,
       devTools: true, aiExtensions: true, sidebarGap: true,
       keyboardShortcuts: true, mouseTracking: true, idleGaps: true,
       windowPosition: true, clipboardManager: true,
@@ -66,7 +67,7 @@ export const PRESETS = {
   standard: {
     // Balanced detection. Default for most studies.
     signals: {
-      paste: true, copy: true, tabAway: true, typingSpeed: true,
+      paste: true, copy: true, drop: true, tabAway: true, typingSpeed: true,
       devTools: true, aiExtensions: true, sidebarGap: true,
       keyboardShortcuts: true, mouseTracking: true, idleGaps: true,
       windowPosition: true, clipboardManager: true,
@@ -93,7 +94,7 @@ export const PRESETS = {
   strict: {
     // Low thresholds, all signals. For high-stakes studies.
     signals: {
-      paste: true, copy: true, tabAway: true, typingSpeed: true,
+      paste: true, copy: true, drop: true, tabAway: true, typingSpeed: true,
       devTools: true, aiExtensions: true, sidebarGap: true,
       keyboardShortcuts: true, mouseTracking: true, idleGaps: true,
       windowPosition: true, clipboardManager: true,
@@ -158,5 +159,10 @@ export const BENIGN_TAGS = [
   "dashlane", "roboform", "honey", "ublock", "adblock"
 ];
 
-// Storage key prefix for localStorage/sessionStorage persistence
-export const STORAGE_PREFIX = "integrity_monitor_";
+
+// Filesystem/CSS-safe participant-id sanitizer. Single source of truth for
+// every artifact filename (browser persistence, CLI ingest, report assets)
+// — divergent copies caused a live fallback-path mismatch (autoreview 0.7.0).
+export function sanitizeId(id) {
+  return String(id).replace(/[^a-zA-Z0-9_.-]/g, '_');
+}

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;
+}

package/src/shared/schema.js

@@ -33,13 +33,16 @@ export const TRIAL_REPORT_FIELDS = {
 // All fields have sensible defaults — minimal config is just dataDir + filePattern.
 export const DEFAULT_CLI_CONFIG = {
   dataDir: "./data",
+  replayDir: null,             // replay artifacts dir; defaults to dataDir
   filePattern: "*.json",
   participantIdField: "participantId",
   trialIdField: "trialId",
   trialOrderField: "trialIndex",
   integrityField: "integrity",
+  sessionIntegrityPath: null,
   trialsPerParticipant: null,
   platformIdField: null,
+  showPlatformId: false,
   conditionField: null,
   groupField: null,
   typingSpeedThreshold_cps: 10,
@@ -48,9 +51,11 @@ export const DEFAULT_CLI_CONFIG = {
   suspiciouslyFastRT_ms: 2000,
   scoring: null,  // uses library defaults
   signals: null,  // all enabled
+  phaseScope: null,  // {include: [...], exclude: [...]} — scope scores to phases
   trajectoryGrid: "auto",
   trajectoryTrialLabel: "trialId",
   trajectoryResponseField: null,
+  trajectoryDisplayOrder: "rule",
   outputDir: "./cyborg-hunter-report",
   outputFormat: "html"
 };

package/src/shared/validation.js

@@ -8,6 +8,7 @@ import { DEFAULT_THRESHOLDS } from './constants.js';
 // All recognized config keys across both browser library and CLI.
 // Unknown keys trigger a warning with the closest match suggestion.
 const ALL_KNOWN_KEYS = [
+  'replayDir',
   ...Object.keys(DEFAULT_CLI_CONFIG),
   ...Object.keys(DEFAULT_THRESHOLDS),
   'preset', 'participantId', 'signals', 'thresholds', 'scoring',
@@ -36,6 +37,60 @@ export function validateConfig(config, knownKeys = ALL_KNOWN_KEYS) {
   return warnings;
 }
 
+/**
+ * Validates the SHAPE of a merged scoring config, after preset+user overrides.
+ * Returns warning strings for rules whose required numeric field is missing.
+ *
+ * Why this exists: scoring overrides replace each rule object wholesale
+ * (Object.assign at the rule level), and validateConfig() only inspects
+ * top-level keys. So a nested typo like `{hard:{paste:{countThreshhold:2}}}`
+ * drops the real `countThreshold`, and `count >= undefined` is always false —
+ * silently disabling a hard screenout rule with no warning. This catches that
+ * class of misconfiguration: every hard rule needs a numeric countThreshold,
+ * every soft rule a numeric weight. Valid overrides produce no warnings.
+ */
+export function validateScoringShape(scoring) {
+  const warnings = [];
+  if (!scoring || typeof scoring !== 'object') return warnings;
+  // Number.isFinite (not typeof === 'number') so NaN and ±Infinity are also
+  // flagged: typeof NaN === 'number', yet `count >= NaN` is always false (hard
+  // rule silently off) and a NaN/Infinity weight breaks the soft score.
+  // safeStr() is used in the message so a non-stringifiable value (e.g. a
+  // Symbol, which template interpolation would throw on) still warns rather than
+  // crashing the very validation meant to surface the misconfiguration.
+  const hard = scoring.hard || {};
+  Object.keys(hard).forEach(key => {
+    const rule = hard[key];
+    if (!rule || !Number.isFinite(rule.countThreshold)) {
+      warnings.push(
+        `scoring.hard.${key} has no finite numeric countThreshold (got ` +
+        `${rule ? safeStr(rule.countThreshold) : 'no rule'}) — this hard ` +
+        `screenout rule can never trigger. A likely cause is a typo in the ` +
+        `override key (e.g. "countThreshhold").`
+      );
+    }
+  });
+  const soft = scoring.soft || {};
+  Object.keys(soft).forEach(key => {
+    const rule = soft[key];
+    if (!rule || !Number.isFinite(rule.weight)) {
+      warnings.push(
+        `scoring.soft.${key} has no finite numeric weight (got ` +
+        `${rule ? safeStr(rule.weight) : 'no rule'}) — this soft signal ` +
+        `contributes nothing (or breaks the soft score). A likely cause is a ` +
+        `typo in the override key (e.g. "wieght").`
+      );
+    }
+  });
+  return warnings;
+}
+
+// Coerce a value to a string for a warning message without ever throwing.
+// String(Symbol()) throws; falling back to the typeof keeps the warning alive.
+function safeStr(v) {
+  try { return String(v); } catch (e) { return typeof v; }
+}
+
 /**
  * Finds the closest matching key using Levenshtein distance.
  * Returns null if no key is within edit distance 3 (too different to suggest).

package/src/cli/renderers/tab-timeline.js

@@ -1,149 +0,0 @@
-// src/cli/renderers/tab-timeline.js
-// Renders tab-away timeline images using node-canvas.
-// Produces one PNG per participant showing when tab-aways occurred
-// relative to the experiment timeline.
-//
-// Layout: horizontal bar chart where X-axis = experiment time,
-// each row = a trial, bars = tab-away events colored by duration.
-// Bins match the analyzer split: flicker (<3s), medium (3-10s), long (≥10s).
-// The 3s boundary is the scoring engine's soft-score cutoff.
-
-import { writeFileSync } from 'fs';
-import { join } from 'path';
-
-const ROW_HEIGHT = 25;
-const LABEL_WIDTH = 120;
-const CHART_WIDTH = 600;
-const TOP_PAD = 50;
-const BOTTOM_PAD = 30;
-const LEFT_PAD = 10;
-
-export async function renderTabTimelines(participants, config) {
-  const { createCanvas } = await import('canvas');
-
-  for (const p of participants) {
-    const trials = p.trials;
-    if (trials.length === 0) continue;
-
-    // Check if there are any tab-away events to render
-    const totalTabAways = trials.reduce((s, t) => s + (t.tabAwayEvents || []).length, 0);
-    if (totalTabAways === 0) continue;
-
-    const canvasH = TOP_PAD + trials.length * ROW_HEIGHT + BOTTOM_PAD;
-    const canvasW = LEFT_PAD + LABEL_WIDTH + CHART_WIDTH + 20;
-    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(`Tab-Away Timeline — ${p.participantId}`, LEFT_PAD, 20);
-    ctx.font = '10px sans-serif';
-    ctx.fillStyle = '#666';
-    ctx.fillText(`${totalTabAways} tab-away events across ${trials.length} trials`, LEFT_PAD, 35);
-
-    // Legend (right-aligned under title)
-    const legend = [
-      { label: 'trial duration', color: '#f0f0f0', border: '#ccc' },
-      { label: '<3s flicker', color: '#bdbdbd', border: '#333' },
-      { label: '3–10s', color: '#ff9800', border: '#333' },
-      { label: '≥10s', color: '#f44336', border: '#333' },
-    ];
-    let lx = canvasW - 10;
-    ctx.font = '9px sans-serif';
-    // Draw legend right-to-left
-    for (let k = legend.length - 1; k >= 0; k--) {
-      const item = legend[k];
-      const textW = ctx.measureText(item.label).width;
-      lx -= textW;
-      ctx.fillStyle = '#333';
-      ctx.fillText(item.label, lx, 22);
-      lx -= 4;
-      ctx.fillStyle = item.color;
-      ctx.fillRect(lx - 10, 15, 10, 8);
-      ctx.strokeStyle = item.border;
-      ctx.lineWidth = 0.5;
-      ctx.strokeRect(lx - 10, 15, 10, 8);
-      lx -= 14;
-    }
-
-    // Find the maximum trial duration for X-axis scaling
-    const maxDuration = Math.max(...trials.map(t =>
-      (t.duration_ms || t.responseTime_ms || 30000)));
-    const xScale = CHART_WIDTH / maxDuration;
-
-    for (let i = 0; i < trials.length; i++) {
-      const trial = trials[i];
-      const y = TOP_PAD + i * ROW_HEIGHT;
-      const trialId = trial.trialId || trial.ruleId || `T${i + 1}`;
-      const tabAways = trial.tabAwayEvents || [];
-
-      // Row label
-      ctx.fillStyle = '#333';
-      ctx.font = '10px sans-serif';
-      ctx.fillText(trialId.substring(0, 16), LEFT_PAD, y + ROW_HEIGHT / 2 + 3);
-
-      // Trial duration background (light grey bar)
-      const trialDur = trial.duration_ms || trial.responseTime_ms || 30000;
-      const barX = LEFT_PAD + LABEL_WIDTH;
-      ctx.fillStyle = '#f0f0f0';
-      ctx.fillRect(barX, y + 3, trialDur * xScale, ROW_HEIGHT - 6);
-
-      // Tab-away bars
-      for (const ta of tabAways) {
-        // Use trial-relative timestamp (normalized in ingest). Fall back to
-        // raw `start` only if normalization was unavailable; this will look
-        // wrong (off-canvas) but at least won't crash.
-        const start = (ta.startRel_ms != null) ? ta.startRel_ms : (ta.start || 0);
-        const dur = ta.duration_ms || 0;
-        // Skip tab-aways that fall outside the trial window — they likely
-        // occurred between trials (inter-trial pause) and aren't meaningful here.
-        if (start < -1000 || start > trialDur + 1000) continue;
-        const clamped = Math.max(0, start);
-        const barStart = barX + clamped * xScale;
-        const barWidth = Math.max(2, dur * xScale);
-
-        // Color by duration: flicker (<3s) = grey, medium (3-10s) = orange, long (≥10s) = red.
-        // Matches summary analyzer bins and the scoring engine's 3s cutoff.
-        const durSec = dur / 1000;
-        ctx.fillStyle = durSec < 3 ? '#bdbdbd' : durSec < 10 ? '#ff9800' : '#f44336';
-        ctx.fillRect(barStart, y + 5, barWidth, ROW_HEIGHT - 10);
-        ctx.strokeStyle = '#333';
-        ctx.lineWidth = 0.5;
-        ctx.strokeRect(barStart, y + 5, barWidth, ROW_HEIGHT - 10);
-      }
-
-      // Row separator
-      ctx.strokeStyle = '#e0e0e0';
-      ctx.lineWidth = 0.5;
-      ctx.beginPath();
-      ctx.moveTo(LEFT_PAD, y + ROW_HEIGHT);
-      ctx.lineTo(canvasW - 10, y + ROW_HEIGHT);
-      ctx.stroke();
-    }
-
-    // X-axis labels
-    ctx.fillStyle = '#666';
-    ctx.font = '9px sans-serif';
-    const tickCount = 5;
-    for (let t = 0; t <= tickCount; t++) {
-      const time = (maxDuration / tickCount) * t;
-      const x = LEFT_PAD + LABEL_WIDTH + time * xScale;
-      ctx.fillText(`${(time / 1000).toFixed(0)}s`, x, canvasH - 10);
-    }
-
-    const buf = canvas.toBuffer('image/png');
-    const filename = `tab_timeline_${sanitize(p.participantId)}.png`;
-    writeFileSync(join(config.outputDir, 'images', filename), buf);
-  }
-
-  console.log(`  tab timelines — rendered`);
-}
-
-function sanitize(name) {
-  return name.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 40);
-}