cyborg-hunter 0.7.4 → 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.4',
+    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.4',
+    version: '0.8.0',
     data: { integrity: { type: 'object' } }
   };
 

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

@@ -72,6 +72,23 @@ export function fullscreenElementOf(doc) {
         || null;
 }
 
+// Mirrors requestFullscreen()'s prefix fallback on the exit side: Safari
+// <16.4 exposes only webkitExitFullscreen, older Firefox
+// mozCancelFullScreen. Pure + exported for unit testing, like
+// fullscreenElementOf above. Returns the METHOD, unbound — every caller
+// must invoke it as fn.call(document) (see exitFullscreen below): a
+// detached call (fn()) throws "Illegal invocation" in real Chrome, because
+// document.exitFullscreen is a native method that requires document as its
+// receiver.
+export function exitFullscreenFnOf(doc) {
+    doc = doc || (typeof document !== 'undefined' ? document : null);
+    if (!doc) return null;
+    return doc.exitFullscreen
+        || doc.webkitExitFullscreen
+        || doc.mozCancelFullScreen
+        || null;
+}
+
 (function (global) {
     'use strict';
 
@@ -789,6 +806,42 @@ export function fullscreenElementOf(doc) {
         }
     }
 
+    // Counterpart to requestFullscreen() above, on the exit side. Two guards
+    // before ever touching the native method: a no-op when nothing is
+    // fullscreen (fullscreenElementOf(document) is null — nothing to exit),
+    // and a no-op while the guard is armed (state.active, the same flag
+    // start()/stop() maintain and getCurrentState() reports). The second
+    // guard matters because check() runs on every fullscreenchange: exiting
+    // while armed would immediately log a false 'not_fullscreen' violation
+    // against the participant — a footgun for any study calling this
+    // mid-timeline. Callers must stop() first. Never throws.
+    function exitFullscreen() {
+        if (!fullscreenElementOf(document)) {
+            logDebug('exit_fullscreen.not_fullscreen', { diagnostics: getDiagnostics() });
+            return;
+        }
+        if (state.active) {
+            logDebug('exit_fullscreen.refused_guard_active', { diagnostics: getDiagnostics() });
+            return;
+        }
+        const exit = exitFullscreenFnOf(document);
+        if (exit) {
+            try {
+                logDebug('exit_fullscreen.attempt', { diagnostics: getDiagnostics() });
+                // .call(document) is mandatory, not stylistic — see
+                // exitFullscreenFnOf's comment above.
+                exit.call(document);
+            } catch (e) {
+                logDebug('exit_fullscreen.error', {
+                    message: e && e.message ? e.message : String(e),
+                    diagnostics: getDiagnostics(),
+                });
+            }
+        } else {
+            logDebug('exit_fullscreen.unavailable_api', { diagnostics: getDiagnostics() });
+        }
+    }
+
     function start(opts = {}) {
         state.jsPsych = opts.jsPsych || state.jsPsych;
         if (typeof opts.sidebarTolerance === 'number') {
@@ -1050,6 +1103,11 @@ export function fullscreenElementOf(doc) {
         stop: function (token) { stop(token); },
         setJsPsych: function (j) { state.jsPsych = j; },
         requestFullscreen: function () { requestFullscreen(); },
+        // Counterpart to requestFullscreen() above. Call this AFTER stop() —
+        // it no-ops while the guard is still armed (see exitFullscreen's
+        // guard above), so the ordering (not just the refusal) is what a
+        // caller should rely on.
+        exitFullscreen: function () { exitFullscreen(); },
         injectRefusalNotices: function () { injectRefusalNotices(); },
         createEntryTrial: function (opts) { return createEntryTrial(opts); },
         onViolation: function (handler) { return onViolation(handler); },
@@ -1086,7 +1144,7 @@ class GuardFrictionExtension {
     // Hand-bumped on each release to track the package version
     // (package.json / src/shared/constants.js). Shown in the jsPsych developer
     // console only; the runtime library version is independent.
-    version: '0.6.0',
+    version: '0.7.0',
     data: {}
   };