cyborg-hunter 0.5.0 → 0.7.0

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

@@ -0,0 +1,135 @@
+// jsPsych extension adapter for the cyborg-hunter session replay recorder.
+// Bundled SELF-CONTAINED (imports the replay core), following the guard-
+// extension precedent: one dist file provides both window.CyborgHunterReplay
+// (standalone use) and window.jsPsychCyborgHunterReplay (jsPsych use).
+//
+// Wiring (order matters at finalize; declaration order is free):
+//
+//   const jsPsych = initJsPsych({
+//     extensions: [
+//       { type: jsPsychCyborgHunter,       params: { participantId, preset } },
+//       { type: jsPsychGuardFriction },
+//       { type: jsPsychGuardHoneypot },
+//       { type: jsPsychCyborgHunterReplay, params: {
+//           participantId, tier: 'dom',
+//           autoSave: { mode: 'datapipe', experimentId: 'ABC123' } } }
+//     ],
+//     on_finish: async function () {
+//       jsPsych.extensions['guard-friction'].finalize();
+//       jsPsych.extensions['guard-honeypot'].finalize();
+//       jsPsych.extensions['cyborg-hunter'].finalize();
+//       await jsPsych.extensions['cyborg-hunter-replay'].finalize();
+//       jsPsych.data.get().localSave('csv', 'data.csv');
+//     }
+//   });
+//
+// Replay finalizes LAST: it pulls CH's session report through a monitor
+// reference stashed at initialize() — never through window.CyborgHunter,
+// whose singleton slot is nulled by CH's destroy(). getSessionReport()
+// remains callable after destroy() (sessionData survives teardown), so the
+// pull works even though CH finalized first.
+
+import * as CHReplay from '../replay/index.js';
+import { buildReplayMeta } from '../replay/persistence.js';
+
+class CyborgHunterReplayExtension {
+  static info = {
+    name: 'cyborg-hunter-replay',
+    version: '0.7.0',
+    data: {}   // per-trial return is {}; session meta goes via addProperties
+  };
+
+  constructor(jsPsych) {
+    this.jsPsych = jsPsych;
+    this.api = null;
+    this._chMonitor = null;
+    this._lastRecording = null;
+    this._monitoring = false;
+  }
+
+  initialize(params) {
+    this.params = params || {};
+    this.api = CHReplay.attach(this.params);
+    this.api.startSession();
+    this._stashChMonitor();
+  }
+
+  // The cyborg-hunter extension initializes before this one when declared
+  // earlier in the extensions array; if not, retry the stash at finalize.
+  _stashChMonitor() {
+    try {
+      var ch = this.jsPsych && this.jsPsych.extensions &&
+        this.jsPsych.extensions['cyborg-hunter'];
+      if (ch && ch.monitor) this._chMonitor = ch.monitor;
+    } catch (e) { /* standalone replay is fine */ }
+  }
+
+  // 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) {}
+
+  on_load(params) {
+    if (!this.api) return;
+    this._monitoring = true;
+    var trialIndex = 0;
+    var plugin = 'unknown';
+    try { trialIndex = this.jsPsych.getProgress().current_trial_global; } catch (e) {}
+    try {
+      plugin = (this.jsPsych.getCurrentTrial() || {}).type?.info?.name || 'unknown';
+    } catch (e) {}
+    this.api.startTrial({
+      trialId: (params && params.trialId) || 'trial-' + trialIndex,
+      plugin: plugin
+    });
+  }
+
+  on_finish(_params) {
+    if (this.api && this._monitoring) {
+      this._monitoring = false;
+      this.api.endTrial();
+    }
+    return {};
+  }
+
+  // Called manually from the experiment's on_finish, AFTER the other three
+  // extensions (see header). Serializes, autosaves, attaches the meta
+  // pointer. Never throws — the experiment's save path must always run.
+  async finalize() {
+    if (!this.api) return;
+    try {
+      try { this.api.stopSession('finished'); } catch (e) { /* already stopped */ }
+      if (!this._chMonitor) this._stashChMonitor();
+      var chReport = null;
+      try {
+        chReport = this._chMonitor ? this._chMonitor.getSessionReport() : null;
+      } catch (e) {
+        console.warn('[cyborg-hunter-replay] could not pull CH session report:', e);
+      }
+      var result = await this.api.autoSaveNow({ chSessionReport: chReport });
+      this._lastRecording = result.recording;
+      this.jsPsych.data.addProperties({ integrityReplayMeta: result.meta });
+    } catch (e) {
+      console.warn('[cyborg-hunter-replay] finalize failed:', e);
+      try {
+        this.jsPsych.data.addProperties({
+          replayFinalizeError: String(e && e.message ? e.message : e)
+        });
+      } catch (_) { /* nothing left to do */ }
+    }
+    try { this.api.destroy(); } catch (e) { /* teardown best-effort */ }
+    // Null the handle so a second finalize() (e.g. duplicated on_finish
+    // wiring) is a clean no-op instead of re-serializing and re-saving.
+    this.api = null;
+  }
+
+  // Debug/test access to the finalized recording (also handy in the console
+  // during piloting: jsPsych.extensions['cyborg-hunter-replay'].getLastRecording()).
+  getLastRecording() {
+    return this._lastRecording;
+  }
+}
+
+export { CyborgHunterReplayExtension };
+if (typeof window !== 'undefined') {
+  window.jsPsychCyborgHunterReplay = CyborgHunterReplayExtension;
+}

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.3.0',
+    version: '0.7.0',
     data: { integrity: { type: 'object' } }
   };
 
@@ -71,7 +71,10 @@ class CyborgHunterExtension {
     this.monitor.startTrial({
       trialId: (params && params.trialId) || `trial-${trialIndex}`,
       phase: params?.phase || null,
-      decoyAnswer: params?.decoyAnswer || null,
+      // Nullish coalescing (not ||) so an explicit `decoyAnswer: false` — the
+      // per-trial "skip the decoy" opt-out — reaches the core as false. With
+      // `|| null` it became null, and the core auto-generated a decoy instead.
+      decoyAnswer: params?.decoyAnswer ?? null,
       experimentContainer: params?.experimentContainer || null
     });
   }
@@ -154,6 +157,10 @@ class CyborgHunterExtension {
           sidebarEvents, keyboardShortcuts, windowPositions,
           layoutShifts, zoomChanges, idleGaps, extensionInjections,
           tabAwaySums, charsPerSec, aiExtensionsFound,
+          // Persist the effective runtime settings (preset + thresholds the CLI
+          // consumes) so the report can interpret this participant with the
+          // thresholds the library actually used, not analyst-side defaults.
+          config,
           ...extras
         },
         integrityScore: { hardScore, softScore, anyHardTriggered, trialsCompleted, softScoreThreshold },

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

@@ -56,6 +56,22 @@
 //
 // ============================================================
 
+// Prefix-aware fullscreen-element lookup. Safari <16.4 and some iOS WebViews
+// expose ONLY document.webkitFullscreenElement (and fire 'webkitfullscreenchange');
+// older Firefox used the moz-prefixed API. requestFullscreen() below already
+// falls through these prefixes, so the authoritative check()/start()/settling
+// gates MUST too — otherwise a participant who successfully enters fullscreen on
+// a prefix-only browser reads a null unprefixed element and is trapped behind a
+// permanent false 'not_fullscreen' violation. Pure + exported for unit testing.
+export function fullscreenElementOf(doc) {
+    doc = doc || (typeof document !== 'undefined' ? document : null);
+    if (!doc) return null;
+    return doc.fullscreenElement
+        || doc.webkitFullscreenElement
+        || doc.mozFullScreenElement
+        || null;
+}
+
 (function (global) {
     'use strict';
 
@@ -143,10 +159,7 @@
     }
 
     function getDiagnostics() {
-        const fsEl = document.fullscreenElement
-            || document.webkitFullscreenElement
-            || document.mozFullScreenElement
-            || null;
+        const fsEl = fullscreenElementOf(document);
         const baselineDeltaCssPx = computeBaselineDeltaCssPx();
 
         return {
@@ -487,7 +500,7 @@
     function check() {
         const diagnostics = getDiagnostics();
 
-        if (!document.fullscreenElement) {
+        if (!fullscreenElementOf(document)) {
             return { ok: false, reason: 'not_fullscreen', diagnostics: diagnostics };
         }
         if (document.visibilityState !== 'visible') {
@@ -689,7 +702,7 @@
                 // re-capture baseline against the now-settled DPR. Fixes
                 // a Chrome-on-Retina case where DPR is briefly stale on
                 // the frame where fullscreenchange fires.
-                if (document.fullscreenElement && performance.now() < state.rebaselineUntil) {
+                if (fullscreenElementOf(document) && performance.now() < state.rebaselineUntil) {
                     state.rebaselineUntil = 0;
                     captureBaseline(function () { update('event.resize.rebaseline'); });
                     return;
@@ -699,6 +712,11 @@
         };
 
         _addEventListener.call(document, 'fullscreenchange', state.eventHandlers.fullscreenchange);
+        // Prefixed variants for browsers that only fire the vendor event
+        // (Safari <16.4, some iOS WebViews, older Firefox). Same handler, so
+        // baseline capture / re-check happens regardless of which one fires.
+        _addEventListener.call(document, 'webkitfullscreenchange', state.eventHandlers.fullscreenchange);
+        _addEventListener.call(document, 'mozfullscreenchange', state.eventHandlers.fullscreenchange);
         _addEventListener.call(document, 'visibilitychange', state.eventHandlers.visibilitychange);
         _addEventListener.call(window, 'blur', state.eventHandlers.blur);
         _addEventListener.call(window, 'focus', state.eventHandlers.focus);
@@ -712,6 +730,8 @@
 
         if (state.eventHandlers) {
             _removeEventListener.call(document, 'fullscreenchange', state.eventHandlers.fullscreenchange);
+            _removeEventListener.call(document, 'webkitfullscreenchange', state.eventHandlers.fullscreenchange);
+            _removeEventListener.call(document, 'mozfullscreenchange', state.eventHandlers.fullscreenchange);
             _removeEventListener.call(document, 'visibilitychange', state.eventHandlers.visibilitychange);
             _removeEventListener.call(window, 'blur', state.eventHandlers.blur);
             _removeEventListener.call(window, 'focus', state.eventHandlers.focus);
@@ -724,7 +744,7 @@
     }
 
     function onFullscreenChange() {
-        if (document.fullscreenElement) {
+        if (fullscreenElementOf(document)) {
             captureBaseline();
             // Open a brief window during which the next resize re-captures
             // baseline. Chrome reports a stale devicePixelRatio on the
@@ -802,7 +822,7 @@
             state.tamperHandle = _setInterval(tamperCheck, TAMPER_CHECK_MS);
             logDebug('tamper_poll.started', { interval_ms: TAMPER_CHECK_MS });
         }
-        if (document.fullscreenElement) {
+        if (fullscreenElementOf(document)) {
             captureBaseline(function () { update('start'); });
         } else {
             update('start');
@@ -1054,10 +1074,10 @@
 class GuardFrictionExtension {
   static info = {
     name: 'guard-friction',
-    // Hand-bumped on each release. The actual library version is whatever
-    // plugin-guard-friction.js exports at runtime; this number is for the
-    // jsPsych developer console only.
-    version: '0.4.0',
+    // 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',
     data: {}
   };
 

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

@@ -160,6 +160,8 @@
         // ----- Hidden form fields (catch full-DOM scrapes) -----
         const honeypot = _createElement.call(document, 'div');
         honeypot.id = 'fg-honeypot';
+        // Marks bait DOM for replay/DOM serializers to exclude ([data-ch-role]).
+        honeypot.setAttribute('data-ch-role', 'honeypot');
         Object.assign(honeypot.style, {
             position: 'absolute',
             width: '0',
@@ -199,6 +201,8 @@
         // doesn't change.
         const baitButton = _createElement.call(document, 'button');
         baitButton.id = 'fg-ai-bait-button';
+        // Marks bait DOM for replay/DOM serializers to exclude ([data-ch-role]).
+        baitButton.setAttribute('data-ch-role', 'honeypot');
         baitButton.type = 'button';
         baitButton.tabIndex = -1;
         baitButton.setAttribute('aria-label', BAIT_BUTTON_LABEL);
@@ -221,6 +225,8 @@
         const baitInput = _createElement.call(document, 'input');
         baitInput.type = 'text';
         baitInput.id = 'fg-ai-bait-input';
+        // Marks bait DOM for replay/DOM serializers to exclude ([data-ch-role]).
+        baitInput.setAttribute('data-ch-role', 'honeypot');
         baitInput.name = 'fg-ai-bait-input';
         baitInput.tabIndex = -1;
         baitInput.setAttribute('aria-label', BAIT_INPUT_LABEL);
@@ -285,12 +291,30 @@
         }
     }
 
+    function resetBaitFields() {
+        const aiUseEl = document.getElementById('fg-ai-use');
+        const aiReportEl = document.getElementById('fg-ai-report');
+        if (aiUseEl) aiUseEl.checked = false;
+        if (aiReportEl) aiReportEl.value = '';
+    }
+
     function init(opts) {
         opts = opts || {};
         if (opts.jsPsych) state.jsPsych = opts.jsPsych;
         if (typeof opts.debug === 'boolean') state.debugEnabled = opts.debug;
 
+        // Reset per-run forensic state. init() runs once per experiment, before
+        // any trial, so a second init() means a fresh run (jsPsych preview,
+        // restart, or two experiments sharing a tab) — it must NOT inherit the
+        // prior run's violation evidence or AI disclosures. injectHoneypotDOM()
+        // is idempotent (guards on state.injected), so on a re-init the old bait
+        // fields survive with their stale values; clear them explicitly.
+        state.violations = [];
+        state.currentViolation = null;
+        state.trialViolationStartIdx = 0;
+
         injectHoneypotDOM();
+        resetBaitFields();
 
         const friction = opts.friction || global.GuardFriction;
         if (friction && typeof friction.onViolation === 'function') {
@@ -418,7 +442,7 @@
 class GuardHoneypotExtension {
   static info = {
     name: 'guard-honeypot',
-    version: '0.4.0',
+    version: '0.6.0',
     // Per-trial fields written by on_finish. Reflect violations for this
     // trial only; jsPsych spreads them onto each trial row (CSV columns).
     // Session totals are written as global properties by finalize().