cyborg-hunter 0.7.5 → 0.9.0

package/src/cli/renderers/score-weights.js

@@ -0,0 +1,16 @@
+// src/cli/renderers/score-weights.js
+// Writes score-weights.json — the weights this report's triage score was built
+// with (config.scoreWeights merged onto the defaults). Always written, so two
+// reports can be checked for comparability without their config files.
+// Warnings stay on the console (config.js); this file holds weights only.
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { resolveScoreWeights } from '../analyzers/score-weights.js';
+
+export function renderScoreWeights(config) {
+  const { weights, isDefault } = resolveScoreWeights(config?.scoreWeights);
+  writeFileSync(join(config.outputDir, 'score-weights.json'),
+    JSON.stringify({ isDefault, weights }, null, 2) + '\n');
+  console.log(`  score-weights.json — ${isDefault ? 'default' : 'custom'} weights`);
+}

package/src/cli/renderers/summary-csv.js

@@ -9,6 +9,8 @@ import { join } from 'path';
 const COLUMNS = [
   ['participantId', (s, t) => s.participantId],
   ['trialCount', (s, t) => s.trialCount],
+  // The exact score rankTriage sorted on (not the one-decimal display form),
+  // so the analysis file never disagrees with the ranking.
   ['triageScore', (s, t) => t.score],
   ['hardTriggered', (s, t) => t.hardTriggered ? 'YES' : 'no'],
   ['triageReason', (s, t) => t.reason],

package/src/cli/renderers/trajectories-core.js

@@ -26,6 +26,7 @@
 //   - Title with trial ID, RT, mouse count, tab-away count + total duration
 
 import { ruleChronologicalCompare } from '../extract-core.js';
+import { formatScore } from '../analyzers/score-weights.js';
 
 // Panel dimensions (pixels).
 const PANEL_W = 400;
@@ -121,7 +122,7 @@ export function drawTrajectoryGrid(p, triageEntry, config, createCanvas) {
   ctx.fillRect(0, 0, canvasW, canvasH);
 
   // Header
-  const headerText = `${p.participantId} — Score: ${triageEntry?.score ?? '?'} — ${triageEntry?.reason ?? ''}`;
+  const headerText = `${p.participantId} — Score: ${formatScore(triageEntry?.score ?? '?')} — ${triageEntry?.reason ?? ''}`;
   ctx.fillStyle = COLORS.headerText;
   ctx.font = 'bold 16px sans-serif';
   ctx.fillText(headerText, PANEL_PAD, 30);

package/src/cli/renderers/triage-md.js

@@ -4,8 +4,15 @@
 
 import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { resolveScoreWeights, formulaText, formatScore } from '../analyzers/score-weights.js';
 
 export async function renderTriage(triage, config) {
+  // Default weights keep the 0.8.0 sentence verbatim; custom ones state the
+  // formula that was actually applied (config.scoreWeights).
+  const { weights, isDefault } = resolveScoreWeights(config?.scoreWeights);
+  const formula = isDefault
+    ? 'heuristic (5×paste + 5×copy + 3×sidebar + 1×tab-away) — it orders rows'
+    : `heuristic (${formulaText(weights)}, set by scoreWeights) — it orders rows`;
   const lines = [
     '# Participant Triage — Ranked by Suspiciousness',
     '',
@@ -14,7 +21,7 @@ export async function renderTriage(triage, config) {
     '**Tier** is the library\'s two-tier screening verdict: `HARD` = a hard signal',
     '(paste/drop/copy) crossed its count threshold; `soft` = library soft score ≥',
     'its threshold; `clean` = neither. **Score** is the CLI\'s separate ranking',
-    'heuristic (5×paste + 5×copy + 3×sidebar + 1×tab-away) — it orders rows',
+    formula,
     '*within* a tier and is not the library soft score.',
     '',
     '| Rank | Participant | Tier | Score | Reason |',
@@ -25,7 +32,7 @@ export async function renderTriage(triage, config) {
     const tier = t.hardTriggered ? '**HARD**' : t.softFlagged ? 'soft' : 'clean';
     // Escape pipe characters in reason text to avoid breaking the table
     const reason = t.reason.replace(/\|/g, '\\|');
-    lines.push(`| ${i + 1} | ${t.participantId} | ${tier} | ${t.score} | ${reason} |`);
+    lines.push(`| ${i + 1} | ${t.participantId} | ${tier} | ${formatScore(t.score)} | ${reason} |`);
   });
 
   lines.push('');

package/src/cli/report.js

@@ -12,6 +12,7 @@ import { ingest } from './ingest.js';
 import { computeSummary } from './analyzers/summary.js';
 import { detectEdgeExits } from './analyzers/edge-exit.js';
 import { rankTriage } from './analyzers/triage.js';
+import { resolveScoreWeights, formulaText } from './analyzers/score-weights.js';
 import { applyPhaseScope, describePhaseScope, findUnmatchedPhaseScopePhases } from './analyzers/phase-scope.js';
 import { VERSION } from '../shared/constants.js';
 import { checkForUpdate, formatUpdateNotice, formatCollectedVersionNotice } from './update-check.js';
@@ -86,14 +87,18 @@ export async function run(args) {
   // "flagged": the tier counts below come from the LIBRARY's two-tier
   // screening (hard count thresholds / soft score vs its threshold), while
   // triage.md is ORDERED by the CLI's separate composite triage score
-  // (5×paste + 5×copy + 3×sidebar + 1×tab-away) within each tier. Label both
-  // explicitly so the console summary can't be read as "top N of triage.md".
+  // (by default 5×paste + 5×copy + 3×sidebar + 1×tab-away; config.scoreWeights
+  // can change it) within each tier. Label both explicitly so the console
+  // summary can't be read as "top N of triage.md".
+  const scoreWeights = resolveScoreWeights(config.scoreWeights);
   console.log(`\nAnalyzing...`);
   console.log(`  Hard-flagged (hard signal crossed its count threshold): ${flaggedHard}`);
   console.log(`  Soft-flagged (library soft score >= its threshold):     ${flaggedSoft}`);
   console.log(`  Clean:                                                  ${clean}`);
   console.log(`  Triage.md orders tier-first (hard > soft > clean), then by the CLI`);
-  console.log(`  triage score (5xpaste + 5xcopy + 3xsidebar + 1xtab-away) within a tier.`);
+  console.log(scoreWeights.isDefault
+    ? `  triage score (5xpaste + 5xcopy + 3xsidebar + 1xtab-away) within a tier.`
+    : `  triage score (${formulaText(scoreWeights.weights, 'x')}, from scoreWeights) within a tier.`);
 
   // 4. Render outputs
   console.log(`\nRendering...`);
@@ -107,6 +112,8 @@ export async function run(args) {
   const { renderExtensions } = await import('./renderers/extensions.js');
 
   await renderSummaryCSV(summaries, triage, config);
+  const { renderScoreWeights } = await import('./renderers/score-weights.js');
+  renderScoreWeights(config);
   await renderTriage(triage, config);
   await renderEventLog(participants, config);
   await renderExtensions(participants, config);
@@ -150,6 +157,12 @@ export async function run(args) {
   if (replayAssets.count > 0) {
     console.log(`  replay/ — ${replayAssets.count} session replays (${(replayAssets.totalBytes / 1024 / 1024).toFixed(1)} MB)`);
   }
+  // A skipped artifact is already visible in the report (the participant's
+  // replay section says why), but an analyst watching the CLI must not have
+  // to open the HTML to learn a recording did not make it.
+  for (const s of replayAssets.skipped) {
+    console.log(`  replay/ — skipped ${s.participantId}: ${s.reason}`);
+  }
 
   // HTML index page — references images/ folder (not base64-embedded)
   const { renderHtmlIndex } = await import('./renderers/html-index.js');

package/src/core/monitor.js

@@ -64,7 +64,7 @@ export function init(userConfig) {
     }, userConfig.domProtection || {}),
     collectForPostHoc: Object.assign({
       fullKeystrokeTimestamps: false,
-      rawMouseTrack: false,
+      rawMouseTrack: true,   // see the privacy note at endTrial (flipped on 2026-09-02)
       responseText: false,
       windowPositionLog: true,
       elementTrace: false,
@@ -378,18 +378,17 @@ 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.
+      // Raw per-sample mouse coordinates persist under `mouseTrack` (the
+      // name extract-core's field map expects: mouseTrack → mouseEvents, so a
+      // saved report round-trips through extractIntegrityData() without new
+      // glue) unless collectForPostHoc.rawMouseTrack is set false, in which
+      // case only the derived mouseMetrics above ship and the {x,y,t,type}
+      // samples never leave the browser. ON by default since 2026-09-02: a
+      // researcher who adds CH to an experiment has already adjudicated
+      // collecting behavioural traces, and an off-by-default gate made the
+      // report's trajectory panels read "no mouse data" for everyone who
+      // never found the toggle (found by CK on the bench harness). The
+      // toggle stays for protocols that need less.
       if (config.collectForPostHoc.rawMouseTrack) {
         report.mouseTrack = report.mouseEvents;
       }

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.5',
+    version: '0.9.0',
     data: {}   // per-trial return is {}; session meta goes via addProperties
   };
 
@@ -47,9 +47,37 @@ class CyborgHunterReplayExtension {
     this._monitoring = false;
   }
 
+  // Keyframe cadence on a jsPsych host: every TRIAL segment, always.
+  //
+  // The standalone recorder keyframes adaptively (spec §3's size trigger plus a
+  // segment fallback) because a persistent DOM makes a continuation cheap: the
+  // player carries the previous segment's tree forward and applies deltas. A
+  // jsPsych trial wipes the display and builds a new one, so there is nothing
+  // to carry forward — a continuation would make the player reconstruct each
+  // trial by replaying the wipe as a removal of everything followed by an
+  // insertion of everything, and would leave a seek into any trial dependent on
+  // the trials before it. §3 says as much: wiping hosts SHOULD keyframe every
+  // segment, which is also jsPsych-v1's own behaviour.
+  //
+  // Forced over researcher config rather than merged under it: the reason is a
+  // property of the host, not a tuning preference, so a value passed here is a
+  // misunderstanding rather than a choice. It is not discarded silently.
+  //
+  // "Every TRIAL segment" is exact, not loose. A jsPsych recording can also
+  // contain UNBRACKETED segments — the inter-trial interval, where the display
+  // wipe fires mutations between one trial's `on_finish` and the next trial's
+  // `on_load` — and those are recorded as CONTINUATIONS whatever this setting
+  // says (capture-dom's implicit-segment rule). That is correct: an ITI segment
+  // genuinely continues the outgoing trial's DOM as it is torn down, and its
+  // patches were numbered against that span before the segment existed.
   initialize(params) {
     this.params = params || {};
-    this.api = CHReplay.attach(this.params);
+    if (this.params.keyframeEvery != null && this.params.keyframeEvery !== 1) {
+      console.warn('[cyborg-hunter-replay] ignoring keyframeEvery: ' +
+        this.params.keyframeEvery + ' — jsPsych wipes the display between ' +
+        'trials, so every trial segment is recorded as a keyframe.');
+    }
+    this.api = CHReplay.attach(Object.assign({}, this.params, { keyframeEvery: 1 }));
     this.api.startSession();
     this._stashChMonitor();
   }
@@ -64,6 +92,36 @@ class CyborgHunterReplayExtension {
     } catch (e) { /* standalone replay is fine */ }
   }
 
+  // Spec §2's `host`: the runtime the recorder was embedded in, as opposed to
+  // `recorder`, which is this library. The recorder core is host-agnostic by
+  // construction and never sniffs for globals, so the adapter — the one piece
+  // that exists because jsPsych does — is where the answer comes from.
+  //
+  // §2 types host as `{name, version} | null` with version a required STRING,
+  // so a runtime that reports no version gets no host record rather than a
+  // half-record a conforming consumer would trip over.
+  //
+  // `version()` is the only shape checked for, because it is the only shape
+  // jsPsych has: 7.3.1 defines `version() { return version; }` on the JsPsych
+  // class and 8.x keeps the same core-API accessor. An earlier draft also
+  // accepted a plain string field; nothing produces one, so it was speculative
+  // dead code and went.
+  //
+  // Never throws: finalize()'s outer catch turns any throw into
+  // replayFinalizeError with NO autosave, and the least important field in
+  // the file must not be able to cost the recording.
+  _detectHost() {
+    try {
+      var jp = this.jsPsych;
+      if (!jp || typeof jp.version !== 'function') return null;
+      var v = jp.version();
+      if (typeof v !== 'string' || !v) return null;
+      return { name: 'jspsych', version: v };
+    } catch (e) {
+      return null;
+    }
+  }
+
   // jsPsych 7 calls on_start unconditionally for every trial that lists the
   // extension — must exist even as a no-op (see extension-cyborg-hunter.js).
   on_start(_params) {}
@@ -105,7 +163,10 @@ class CyborgHunterReplayExtension {
       } catch (e) {
         console.warn('[cyborg-hunter-replay] could not pull CH session report:', e);
       }
-      var result = await this.api.autoSaveNow({ chSessionReport: chReport });
+      var result = await this.api.autoSaveNow({
+        chSessionReport: chReport,
+        host: this._detectHost()
+      });
       this._lastRecording = result.recording;
       this.jsPsych.data.addProperties({ integrityReplayMeta: result.meta });
     } catch (e) {

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.5',
+    version: '0.9.0',
     data: { integrity: { type: 'object' } }
   };