cyborg-hunter 0.3.0 → 0.4.0

package/src/jspsych/extension.js

@@ -1,91 +1,71 @@
-// src/jspsych/extension.js
-// jsPsych extension adapter for Cyborg Hunter.
-// Translates jsPsych's trial lifecycle into CyborgHunter API calls.
-//
-// Two main usage patterns:
-//   1. Monitor everything (default) — every trial gets startTrial/endTrial
-//   2. Explicit opt-in (autoMonitor: false) — monitor only specified trials
-//      (trials must pass { trialId: '...' } in their extension parameters)
-//
-// IMPORTANT: This file does NOT import from the core library. It references
-// window.CyborgHunter at runtime. The researcher must load cyborg-hunter.min.js
-// before this script. This avoids bundling the core into the extension.
+// jsPsych extension adapter for cyborg-hunter.
+// Loaded as a script tag AFTER cyborg-hunter.min.js — references
+// window.CyborgHunter at runtime rather than importing the core, so the
+// extension stays a thin (~2KB) adapter even though the core is ~28KB.
 
 class CyborgHunterExtension {
-  // jsPsych reads this static info object to register the extension.
-  // The `data` field declares what on_finish() will return — here, an
-  // `integrity` object containing the trial's signal report.
   static info = {
     name: 'cyborg-hunter',
-    version: '0.1.0',
+    // Must match the cyborg-hunter library version (src/shared/constants.js
+    // 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',
     data: { integrity: { type: 'object' } }
   };
 
   constructor(jsPsych) {
     this.jsPsych = jsPsych;
-    this.monitor = null;       // CyborgHunter monitor instance (set in initialize)
-    this.params = {};           // extension-level params from jsPsych config
-    this._monitoring = false;   // whether the current trial is being monitored
-    this._trialStart_perfNow = null; // performance.now() captured at on_load
+    this.monitor = null;
+    this.params = {};
+    this._monitoring = false;
+    this._trialStart_perfNow = null;
   }
 
-  // Called once when jsPsych initializes extensions (before any trials run).
-  // `params` comes from the experiment's extensions config, e.g.:
-  //   extensions: [{ type: jsPsychCyborgHunter, params: { preset: 'standard' } }]
-  //
-  // We pull out extension-specific keys (autoMonitor, excludeTrialTypes) and
-  // pass everything else through to CyborgHunter.init() as monitor config.
+  // jsPsych calls this once during initJsPsych setup.
+  // Splits extension-specific keys out and forwards the rest to the monitor.
   initialize(params) {
     this.params = params;
     const { autoMonitor, excludeTrialTypes, ...monitorConfig } = params;
 
-    // Look up the global CyborgHunter object (or its backward-compat alias).
-    // The researcher must include cyborg-hunter.min.js before this extension.
     const CyborgHunter = window.CyborgHunter || window.IntegrityMonitor;
     if (!CyborgHunter) {
       throw new Error('CyborgHunter not found. Load cyborg-hunter.min.js before the jsPsych extension.');
     }
 
-    // init() creates the monitor; startSession() begins session-scoped listeners.
     this.monitor = CyborgHunter.init(monitorConfig);
     this.monitor.startSession();
   }
 
   // jsPsych 7 unconditionally calls on_start for every trial that lists this
-  // extension — even though the work happens in on_load (after DOM render).
-  // Without this no-op, the very next trial after the first throws
+  // extension, even though the actual setup happens in on_load (after DOM
+  // render). Without this no-op, the very next trial throws
   // "this.extensions['cyborg-hunter'].on_start is not a function".
   on_start(_params) {}
 
-  // Called at the start of each trial, after the trial's DOM is rendered.
-  // `params` here are per-trial extension parameters, e.g.:
-  //   extensions: [{ type: jsPsychCyborgHunter, params: { trialId: 'rule-3' } }]
+  // Called per trial after DOM render. Per-trial extension params arrive here.
   on_load(params) {
     this._monitoring = false;
 
-    // In explicit opt-in mode (autoMonitor: false), only monitor trials
-    // that provide a trialId in their per-trial extension params.
-    if (this.params.autoMonitor === false) {
-      if (!params || !params.trialId) return;
+    // Explicit opt-in mode: only monitor trials that pass a trialId.
+    if (this.params.autoMonitor === false && !(params && params.trialId)) {
+      return;
     }
 
-    // Auto-monitor with exclusions: skip trial types the researcher listed.
-    // This is useful for excluding instruction screens, fixation crosses, etc.
-    // Trial type name comes from the plugin's static info.name property.
+    // Auto-monitor with exclusions: skip trial types named in the config
+    // (instructions, fixation, etc.). Trial type name comes from the plugin's
+    // static info.name property.
     if (this.params.excludeTrialTypes) {
-      const currentTrial = this.jsPsych.getCurrentTrial();
-      const typeName = currentTrial.type?.info?.name || '';
+      const typeName = this.jsPsych.getCurrentTrial().type?.info?.name || '';
       if (this.params.excludeTrialTypes.includes(typeName)) return;
     }
 
-    // Start monitoring this trial. We pass through per-trial params so the
-    // core library knows the trial ID, phase, decoy text, and where to scope
-    // typing/mouse signals.
     this._monitoring = true;
-    // P3: Record performance.now() at trial start so ingest can compute
-    // trial-relative tab-away timestamps by direct subtraction (no offset
-    // estimator needed). Captured on the same monotonic clock that
-    // tabAwayEvents[*].start uses, so the difference is exact.
+    // Capture performance.now() at trial start so ingest can compute
+    // trial-relative tab-away timestamps by direct subtraction. tabAwayEvents
+    // store their `start` on the same monotonic clock, so the difference is
+    // exact. Without this anchor, the CLI falls back to a heuristic estimator
+    // on session-anchored data, which is less precise.
     this._trialStart_perfNow = performance.now();
     const trialIndex = this.jsPsych.getProgress().current_trial_global;
     this.monitor.startTrial({
@@ -96,23 +76,22 @@ class CyborgHunterExtension {
     });
   }
 
-  // Called when a trial finishes (after participant response, before data save).
-  // Returns the integrity report object, which jsPsych merges into trial data
-  // under the key declared in static info.data (i.e., data.integrity).
-  on_finish(params) {
+  // Called when a trial finishes. Returns the integrity report, which jsPsych
+  // merges into the trial's data under the key declared in static info.data
+  // (i.e., data.integrity).
+  on_finish(_params) {
     if (!this._monitoring) return {};
     this._monitoring = false;
     const report = this.monitor.endTrial();
-    // P3: Attach the on_load performance.now() so downstream ingest can
-    // convert session-absolute event timestamps (e.g., tabAwayEvents[*].start)
-    // to trial-relative ms without heuristic offset estimation.
+    // Forward the on_load anchor (see on_load above) so ingest can do exact
+    // time arithmetic without re-deriving it.
     report.trialStart_perfNow = this._trialStart_perfNow;
     this._trialStart_perfNow = null;
     return { integrity: report };
   }
 
-  // Called explicitly by the researcher from their initJsPsych({ on_finish })
-  // callback, BEFORE saving data. Example:
+  // Called explicitly by the researcher from initJsPsych({ on_finish }), BEFORE
+  // saving data. Example:
   //
   //   const jsPsych = initJsPsych({
   //     extensions: [{ type: jsPsychCyborgHunter, params: { ... } }],
@@ -125,42 +104,41 @@ class CyborgHunterExtension {
   // Why this isn't automatic: jsPsych 7 has no on_finish_experiment extension
   // hook (only initialize / on_start / on_load / on_finish exist). An earlier
   // version of this wrapper defined on_finish_experiment and silently dropped
-  // session data because jsPsych never called it.
+  // session data because jsPsych never called it. We surface the boundary
+  // explicitly so it can't silently regress.
   //
-  // Persists the full session report using Option A split attachment:
-  //   - Scalars (counts, booleans, version) go to jsPsych.data.addProperties()
-  //     so they land as columns on EVERY trial row — small, filterable in R/pandas.
-  //   - Arrays and nested objects (sidebarEvents, integrityScore, etc.) go to
-  //     jsPsych.data.addDataToLastTrial() so they're attached ONCE to the final
-  //     trial row — avoids duplicating kilobytes of JSON across every row.
+  // Persistence shape (split attachment):
+  //   - Scalars (counts, booleans, version) → addProperties, so they appear
+  //     as columns on EVERY trial row. Cheap, queryable from R/pandas.
+  //   - Arrays + nested objects (sidebarEvents, integrityScore, etc.) →
+  //     addDataToLastTrial, so they're attached ONCE on the final row.
+  //     Avoids duplicating kilobytes of identical JSON across every row.
   //
-  // After persisting, tears down all listeners and clears session state.
+  // After persisting, tears down listeners and clears session state.
   finalize() {
     if (!this.monitor) return;
 
     try {
-      // Single call — Task 5A made getSessionReport() the source of truth, so
-      // this object has both the accumulators AND the scoring summary.
+      // getSessionReport() is the source of truth: contains both the
+      // accumulators and the scoring summary in one shape.
       const report = this.monitor.getSessionReport();
 
       const {
-        // Arrays — go to last trial only (no CSV bloat).
+        // Arrays — attached once on the last trial only (no CSV bloat).
         sidebarEvents = [], keyboardShortcuts = [], windowPositions = [],
         layoutShifts = [], zoomChanges = [], idleGaps = [], extensionInjections = [],
         tabAwaySums = [], charsPerSec = [], aiExtensionsFound = [],
-        // Scoring summary — full object to last trial; key scalars also duplicated
-        // to every trial via addProperties below.
+        // Scoring summary — full object on last trial; key scalars below
+        // also duplicated to every row via addProperties.
         hardScore, softScore, anyHardTriggered, trialsCompleted, softScoreThreshold,
         // Scalars.
         pasteCount = 0, copyCount = 0, dropCount = 0,
         libraryVersion, config,
-        // Anything else the monitor adds in the future — goes with the arrays
-        // so it's captured on the last trial without polluting every row.
+        // Future-proof: anything new from the monitor flows into integritySession
+        // automatically without polluting the per-row scalar columns.
         ...extras
       } = report;
 
-      // Scalars: one column per field, duplicated across every trial row.
-      // Cheap, useful for per-trial filtering and quick exclusion queries.
       this.jsPsych.data.addProperties({
         integrityPasteCount: pasteCount,
         integrityCopyCount: copyCount,
@@ -170,7 +148,6 @@ class CyborgHunterExtension {
         cyborgHunterVersion: libraryVersion,
       });
 
-      // Arrays + nested objects: attached once, on the final trial row.
       this.jsPsych.data.addDataToLastTrial({
         integritySession: {
           pasteCount, copyCount, dropCount,
@@ -182,17 +159,26 @@ class CyborgHunterExtension {
         integrityScore: { hardScore, softScore, anyHardTriggered, trialsCompleted, softScoreThreshold },
       });
     } catch (e) {
-      // Never let a reporting error crash the experiment's end-of-session path.
+      // Don't crash the experiment's end-of-session path — the user's save
+      // call (localSave / dispatcher / etc.) MUST still run. But don't fail
+      // silently either — drop a marker into the data so analysts can see
+      // during ingest that finalize() failed for this participant, plus log
+      // to console for local debugging.
       console.warn('[cyborg-hunter] Failed to save session report:', e);
+      try {
+        this.jsPsych.data.addProperties({
+          cyborgHunterFinalizeError: String(e && e.message ? e.message : e)
+        });
+      } catch (_) { /* if even addProperties fails, the warn above is all we have */ }
     }
 
     this.monitor.destroy();
   }
 }
 
-// Export for both module and IIFE contexts.
-// When loaded as a script tag, window.jsPsychCyborgHunter is the class
-// that researchers pass to jsPsych's extensions array.
+// Module export AND IIFE-friendly window assignment. The build target is IIFE,
+// so `window.jsPsychCyborgHunter` is what researchers reference in their
+// extensions array. The named export exists for completeness.
 export { CyborgHunterExtension };
 if (typeof window !== 'undefined') {
   window.jsPsychCyborgHunter = CyborgHunterExtension;