cyborg-hunter 0.7.5 → 0.8.0

package/src/cli/report.js

@@ -150,6 +150,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.8.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.8.0',
     data: { integrity: { type: 'object' } }
   };