cyborg-hunter 0.9.2 → 0.10.0

package/src/cli/extract-core.js

@@ -15,6 +15,7 @@
 
 import { TRIAL_REPORT_FIELDS } from '../shared/schema.js';
 import { getByPath } from '../shared/paths.js';
+import { collectSegments, reassembleSegments, rebaseTrialReport } from './segment-reassembly.js';
 
 // Extracts integrity trial data from a single participant's raw JSON.
 // Returns { participantId, trials, warnings, metadata }.
@@ -53,6 +54,27 @@ export function extractIntegrityData(raw, config) {
     trials = raw.trials
       .filter(t => t && t[intField])
       .map(t => ({ ...t, ...t[intField] }));
+    // One-line setup (0.10.0) across several pages: each page has its own
+    // performance.now() origin, recorded as integritySegment.pageOrigin.
+    // Re-base trials from later pages onto the first page's origin so the
+    // session timeline and the per-trial anchors below stay on one clock.
+    // Only the page-clock fields move (anchors + absolute-time event arrays,
+    // listed in segment-reassembly.js); trial-relative mouseTrack/elementTrace
+    // times must NOT move, or trajectories misplace every later-page trial.
+    // Single-page data, and data without segments, is untouched. A row whose
+    // trial was not segmented itself (it carries only the closing
+    // integritySegmentFinal) takes that segment's page.
+    const rowOrigin = t => t?.integritySegment?.pageOrigin ?? t?.integritySegmentFinal?.pageOrigin;
+    if (raw.trials.some(t => typeof rowOrigin(t) === 'number')) {
+      const origin0 = collectSegments(raw)[0]?.pageOrigin;
+      if (typeof origin0 === 'number') {
+        trials = trials.map(trial => {
+          const origin = rowOrigin(trial);
+          return (typeof origin === 'number' && origin !== origin0)
+            ? rebaseTrialReport(trial, origin - origin0) : trial;
+        });
+      }
+    }
     // jsPsych extension data carries trialStart_perfNow per trial (set by the
     // wrapper's on_load), so normalization takes the exact-subtraction fast
     // path. Without it, renderers see only session-absolute `start` values
@@ -156,7 +178,7 @@ export function extractIntegrityData(raw, config) {
     }
   }
 
-  const { session, score } = findSessionData(raw, config);
+  const { session, score } = findSessionData(raw, config, warnings);
   if (session === null && trials.length > 0) {
     warnings.push('No session-level integrity data — some signals unavailable (did the experiment call getSessionReport()?)');
   }
@@ -173,6 +195,16 @@ export function extractIntegrityData(raw, config) {
   if (finalizeError) {
     warnings.push(`finalize() failed for this participant (cyborgHunterFinalizeError): ${finalizeError} — session data may be incomplete`);
   }
+  // The one-line setup (0.10.0) has no finalize(); when it hits an internal
+  // error it drops a `cyborgHunterError` marker instead. Same three locations.
+  const oneLinerError = raw.cyborgHunterError
+    ?? raw.metadata?.cyborgHunterError
+    ?? (Array.isArray(raw.trials)
+        ? raw.trials.find(t => t?.cyborgHunterError)?.cyborgHunterError
+        : undefined);
+  if (oneLinerError) {
+    warnings.push(`one-line setup reported an error for this participant (cyborgHunterError): ${oneLinerError} — data after that point may be incomplete`);
+  }
 
   return {
     participantId,
@@ -227,10 +259,17 @@ function looksLikeSessionData(obj) {
 //   4. raw.cyborgHunter — native top-level location used by raw-DOM
 //      adopters before they adopt the
 //      metadata.integritySession mirror. Added 2026-05-26.
-// Returns { session, score }, both null if not found.
-function findSessionData(raw, config) {
+//   5. Rolling snapshot (0.10.0 one-line setup) — per-row integritySegment
+//      deltas, reassembled by src/cli/segment-reassembly.js.
+// Returns { session, score }, both null if not found. `warnings` receives a
+// note when a dumped session and rolling segments are both present. Not
+// exported (ingest.js re-exports only extractIntegrityData and
+// ruleChronologicalCompare); its one caller always passes `warnings`, and the
+// `= []` default only keeps a warnings-less call from throwing.
+function findSessionData(raw, config, warnings = []) {
   let session = null;
   let score = null;
+  let usedSegments = false;
 
   // 0. Analyst-specified location, e.g. "payload.cyborgHunter" for pipelines
   //    that nest the getSessionReport() output somewhere non-standard. Falls
@@ -273,6 +312,26 @@ function findSessionData(raw, config) {
     session = raw.cyborgHunter;
     score = null;
   }
+  // 5. Rolling snapshot (0.10.0 one-line setup): per-row integritySegment deltas,
+  //    concatenated in segmentIndex order into the same shape finalize() dumps.
+  else {
+    const segs = collectSegments(raw);
+    if (segs.length > 0) {
+      const rolled = reassembleSegments(segs);
+      session = rolled.session;
+      score = rolled.score;
+      usedSegments = true;
+    }
+  }
+
+  // A file carrying both is a study that mixed manual finalize() with the
+  // one-line setup. The dumped session is complete by construction, so it
+  // wins; say so rather than silently ignoring the segments. This also fires
+  // when branch 0 (the analyst's sessionIntegrityPath) found the session,
+  // since that leaves usedSegments false too.
+  if (session && !usedSegments && collectSegments(raw).length > 0) {
+    warnings.push('both a dumped integritySession and rolling segments (integritySegment) were found — the dumped integritySession was used; this file mixes manual mode and the one-line setup');
+  }
 
   // When no separate integrityScore blob was saved, synthesize the authoritative
   // score from the session object itself. getSessionReport() embeds the scoring
@@ -320,7 +379,14 @@ function scoreFromSession(session) {
 // (or metadata). Each entry is { reason, start, end, duration, in_progress };
 // the renderer keys off `t` (perfNow ms), so map start → t. Apps that hand-write
 // a top-level `raw.guardFriction` object still take precedence over this.
+// One-line setup across several pages (0.10.0 vanilla host): each page's
+// entries carry that page's `pageOrigin`, and `t` is re-based onto the first
+// segment's origin like the rest of the session; entries without one keep
+// their `start`.
 function findGuardViolations(raw) {
+  const origin0 = collectSegments(raw)[0]?.pageOrigin;
+  const offset = (v) => (typeof v.pageOrigin === 'number' && typeof origin0 === 'number')
+    ? v.pageOrigin - origin0 : 0;
   const parseArr = (v) => {
     if (Array.isArray(v)) return v;
     if (typeof v === 'string') { try { return JSON.parse(v); } catch { return null; } }
@@ -353,7 +419,7 @@ function findGuardViolations(raw) {
     if (Array.isArray(arr)) {
       const violations = arr
         .filter(v => v && typeof v.start === 'number')
-        .map(v => ({ t: v.start, reason: v.reason || 'unknown', phase: 'unknown', duration_ms: v.duration }));
+        .map(v => ({ t: v.start + offset(v), reason: v.reason || 'unknown', phase: 'unknown', duration_ms: v.duration }));
       // Fall through to the next source on an empty/violation-less candidate
       // instead of locking onto it — otherwise an empty placeholder (e.g. a
       // metadata mirror set to []) would shadow real violations on the trial rows.

package/src/cli/segment-reassembly.js

@@ -0,0 +1,204 @@
+// src/cli/segment-reassembly.js
+// CLI side of the rolling snapshot (0.10.0 one-line setup). The browser cuts
+// the monitor's session arrays into per-segment deltas
+// (src/oneliner/segment-diff.js) and saves one `integritySegment` per data
+// row; this module puts them back together into the same session object
+// finalize() dumps as `integritySession`, plus the score.
+//
+// Pure: no imports, no Node APIs — extract-core.js (bundled by the browser
+// demo) depends on it.
+
+// Field names that hold a performance.now()-style time. Everything else
+// (duration_ms, ISO `timestamp` strings, counts) is left alone when re-basing.
+// rebaseTimes() applies this at any depth, which is right for the SESSION
+// arrays (every entry's t/start is a raw page performance.now()), but not for
+// a whole trial report — use rebaseTrialReport() for those.
+// Bare-number arrays are never shifted: editTimestamps holds absolute
+// performance.now() values too, but the CLI only uses their differences
+// (typing speed), so they are intentionally left on their own page's clock.
+const TIME_KEYS = new Set(['t', 'start', 'startTime', 'trialStart_perfNow']);
+
+// Mirrors ALIAS_KEYS in src/oneliner/segment-diff.js (a test pins the two
+// equal): the alias key is not shipped in segments, so it is restored here
+// pointing at its canonical key.
+export const ALIAS_KEYS = { layoutShifts: 'viewportWidthShifts' };
+
+// Trial-report fields that carry the page's performance.now() clock and so
+// move with the page origin. Time base of each, from src/core:
+//   startTime            performance.now() at startTrial   (monitor.js startTrial)
+//   trialStart_perfNow   performance.now() at on_load      (jspsych extension on_load)
+//   pasteEvents[].t      performance.now()                 (signals/clipboard.js)
+//   copyEvents[].t       performance.now()                 (signals/clipboard.js)
+//   dropEvents[].t       performance.now()                 (signals/clipboard.js)
+//   tabAwayEvents[].start performance.now() at leave      (signals/focus.js)
+//   idleGaps[].t         performance.now()                 (signals/focus.js)
+//   syntheticInsertions[].t performance.now()              (signals/typing.js)
+//   foreignInputEvents[].t  performance.now()              (signals/typing.js)
+// NOT shifted (left as they are):
+//   mouseTrack/mouseEvents[].t  ms since trial start       (signals/mouse.js)
+//   elementTrace[].t            ms since trial start       (signals/browser.js)
+//   mouseTrackingCappedAtMs, duration_ms  durations
+//   editTimestamps              absolute, bare numbers — see TIME_KEYS note
+//   anything else on the row (integrity, integritySegment, jsPsych columns)
+const TRIAL_ANCHOR_KEYS = ['startTime', 'trialStart_perfNow'];
+const TRIAL_PAGE_TIME_ARRAYS = ['pasteEvents', 'copyEvents', 'dropEvents', 'tabAwayEvents',
+  'idleGaps', 'syntheticInsertions', 'foreignInputEvents'];
+
+// Returns a shallow copy of a merged trial report with only the page-clock
+// fields above shifted by offsetMs. Offset 0 returns the input itself.
+export function rebaseTrialReport(trial, offsetMs) {
+  if (!offsetMs || !trial || typeof trial !== 'object') return trial;
+  const out = { ...trial };
+  for (const k of TRIAL_ANCHOR_KEYS) {
+    if (typeof out[k] === 'number') out[k] += offsetMs;
+  }
+  for (const k of TRIAL_PAGE_TIME_ARRAYS) {
+    if (Array.isArray(out[k])) out[k] = rebaseTimes(out[k], offsetMs);
+  }
+  return out;
+}
+
+// Returns a deep copy of `value` with every numeric property named t, start,
+// startTime or trialStart_perfNow shifted by offsetMs, at any depth.
+// Offset 0 returns the input itself (no copy), so a single-page session costs
+// nothing.
+export function rebaseTimes(value, offsetMs) {
+  if (!offsetMs) return value;
+  return shift(value, offsetMs);
+}
+
+function shift(value, offsetMs) {
+  if (Array.isArray(value)) return value.map(v => shift(v, offsetMs));
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = (TIME_KEYS.has(k) && typeof v === 'number') ? v + offsetMs : shift(v, offsetMs);
+  }
+  return out;
+}
+
+function isSegment(x) {
+  return !!x && typeof x === 'object' && !Array.isArray(x) && typeof x.segmentIndex === 'number';
+}
+
+// Gathers every segment saved in a participant file, sorted by segmentIndex.
+// Sources: raw.trials[*].integritySegment, raw.trials[*].integritySegmentFinal
+// (any row) and raw.integritySegments (array). Non-objects are skipped — a CSV
+// cell that failed to JSON.parse stays a string. When the same index appears
+// twice, the first occurrence wins.
+export function collectSegments(raw) {
+  const found = [];
+  if (raw && Array.isArray(raw.trials)) {
+    for (const row of raw.trials) {
+      if (!row || typeof row !== 'object') continue;
+      if (isSegment(row.integritySegment)) found.push(row.integritySegment);
+      if (isSegment(row.integritySegmentFinal)) found.push(row.integritySegmentFinal);
+    }
+  }
+  if (raw && Array.isArray(raw.integritySegments)) {
+    for (const s of raw.integritySegments) if (isSegment(s)) found.push(s);
+  }
+  // Array.prototype.sort is stable, so on equal indices the earlier-found
+  // segment stays first and the duplicate check below keeps it.
+  found.sort((a, b) => a.segmentIndex - b.segmentIndex);
+  const out = [];
+  for (const s of found) {
+    if (out.length > 0 && out[out.length - 1].segmentIndex === s.segmentIndex) continue;
+    out.push(s);
+  }
+  return out;
+}
+
+// Concatenates segment deltas in segmentIndex order into the finalize() dump
+// shape: { pasteCount, copyCount, dropCount, <every array key>, layoutShifts,
+// config } — score fields and libraryVersion are NOT in the session (finalize()
+// stores them separately). Returns { session, score, pageOrigins } or null for
+// no segments. Segments from a later page (different pageOrigin) have their
+// times re-based to the first page's origin. Counters and score add up the
+// pages (pageTotals below); single-page data keeps the last segment's score
+// object as it is.
+export function reassembleSegments(segments) {
+  if (!Array.isArray(segments) || segments.length === 0) return null;
+  const sorted = segments.slice().sort((a, b) => a.segmentIndex - b.segmentIndex);
+
+  const pageOrigins = [];
+  for (const s of sorted) {
+    if (!pageOrigins.includes(s.pageOrigin)) pageOrigins.push(s.pageOrigin);
+  }
+
+  const session = {};
+  for (const s of sorted) {
+    const offset = (typeof s.pageOrigin === 'number' && typeof pageOrigins[0] === 'number')
+      ? s.pageOrigin - pageOrigins[0] : 0;
+    for (const [key, entries] of Object.entries(s.deltas || {})) {
+      if (!Array.isArray(entries)) continue;
+      session[key] = (session[key] || []).concat(rebaseTimes(entries, offset));
+    }
+  }
+  for (const [alias, canonical] of Object.entries(ALIAS_KEYS)) {
+    if (!session[canonical]) session[canonical] = [];
+    session[alias] = session[canonical];   // same array, as in the monitor
+  }
+
+  // Counters and score are cumulative per monitor, and every page load runs a
+  // new monitor: the session total is the sum over pages of each page's last
+  // segment. `?? 0` matches finalize()'s destructuring defaults.
+  const lasts = pageLasts(sorted);
+  for (const k of ['pasteCount', 'copyCount', 'dropCount']) {
+    session[k] = lasts.reduce((sum, s) => sum + ((s.counters || {})[k] ?? 0), 0);
+  }
+  const withConfig = sorted.find(s => s.config);
+  session.config = withConfig ? withConfig.config : undefined;
+
+  return { session, score: sessionScore(lasts), pageOrigins };
+}
+
+// The last segment of each page, in page order. A page is identified by its
+// pageOrigin, not by a run of consecutive segments: a page shown again from
+// the back/forward cache keeps its origin and its monitor, so its last
+// segment already holds everything that monitor counted, earlier visit
+// included (summing per run would count the first visit twice).
+function pageLasts(sorted) {
+  const byOrigin = new Map();
+  for (const s of sorted) byOrigin.set(s.pageOrigin, s);   // sorted: the last one wins
+  return [...byOrigin.values()].sort((a, b) => a.segmentIndex - b.segmentIndex);
+}
+
+// One page: that segment's score object, untouched. Several pages: the same
+// shape as the monitor's (src/core/scoring.js:130-139, monitor.js:413-420),
+// added up. Each hard signal's count is the sum of the pages' counts, its
+// threshold the last page's, triggered = count >= threshold; softScore and
+// trialsCompleted are sums; softScoreThreshold is the last page's.
+function sessionScore(lasts) {
+  const scored = lasts.filter(s => s.score && typeof s.score === 'object');
+  if (scored.length === 0) return lasts[lasts.length - 1].score ?? null;
+  const last = scored[scored.length - 1].score;
+  if (lasts.length === 1) return last;
+
+  const hardScore = {};
+  let softScore = 0;
+  let trialsCompleted = 0;
+  for (const { score } of scored) {
+    for (const [k, h] of Object.entries(score.hardScore || {})) {
+      if (!h || typeof h !== 'object') continue;
+      if (!hardScore[k]) hardScore[k] = { count: 0, threshold: undefined, triggered: false };
+      hardScore[k].count += h.count ?? 0;
+      if (h.threshold !== undefined) hardScore[k].threshold = h.threshold;
+    }
+    softScore += score.softScore ?? 0;
+    trialsCompleted += score.trialsCompleted ?? 0;
+  }
+  for (const k of Object.keys(hardScore)) {
+    const lastThreshold = last.hardScore?.[k]?.threshold;
+    if (lastThreshold !== undefined) hardScore[k].threshold = lastThreshold;
+    hardScore[k].triggered = typeof hardScore[k].threshold === 'number' && hardScore[k].count >= hardScore[k].threshold;
+  }
+  return {
+    ...last,
+    hardScore,
+    softScore,
+    softScoreThreshold: last.softScoreThreshold,
+    anyHardTriggered: Object.values(hardScore).some(h => h.triggered),
+    trialsCompleted
+  };
+}

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.9.2',
+    version: '0.10.0',
     data: {}   // per-trial return is {}; session meta goes via addProperties
   };
 

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

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

@@ -954,6 +954,9 @@ export function exitFullscreenFnOf(doc) {
             active: state.active,
             in_violation: !!state.currentViolation,
             current_reason: state.currentViolation ? state.currentViolation.reason : null,
+            // true while violations are only logged (no curtain); the entry
+            // trial switches it off — enforcement starts at that mark.
+            observe_only: state.observeOnly,
         };
     }
 
@@ -981,7 +984,11 @@ export function exitFullscreenFnOf(doc) {
                 logDebug('entry_trial.on_finish', { diagnostics: getDiagnostics() });
                 requestFullscreen();
                 _setTimeout(() => {
-                    const token = start({ jsPsych: state.jsPsych });
+                    // observeOnly: false explicitly — start() keeps the prior
+                    // value when the option is absent, so a session started
+                    // observe-only (the one-liner's friction before its mark)
+                    // would otherwise never enforce from this mark on.
+                    const token = start({ jsPsych: state.jsPsych, observeOnly: false });
                     // Non-enumerable stash so the experiment's on_finish can
                     // pass the token to stop() without exposing it on a
                     // discoverable property name. configurable:true so the
@@ -1118,11 +1125,18 @@ export function exitFullscreenFnOf(doc) {
     };
 
     Object.freeze(api);
-    Object.defineProperty(global, 'GuardFriction', {
-        value: api,
-        writable: false,
-        configurable: false,
-    });
+    // A second copy of this core on the page (ch.js bundles it, so ch.js plus
+    // this file's own <script> tag, in either order) keeps the first
+    // definition instead of throwing "Cannot redefine property".
+    if (!global.GuardFriction) {
+        Object.defineProperty(global, 'GuardFriction', {
+            value: api,
+            writable: false,
+            configurable: false,
+        });
+    } else {
+        console.error('[cyborg-hunter] Not redefining GuardFriction: GuardFriction is already defined, so two scripts on this page include the friction guard. Fix: keep one of them (ch.js already contains the friction guard). https://github.com/cyborg-hunter/cyborg-hunter/blob/main/docs/advanced-integration.md#double-load');
+    }
 })(window);
 // ----- jsPsych extension adapter -----
 // Wraps the GuardFriction core (above) in the jsPsych extension
@@ -1144,7 +1158,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.9.2',
+    version: '0.10.0',
     data: {}
   };
 

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

@@ -421,11 +421,18 @@
     };
 
     Object.freeze(api);
-    Object.defineProperty(global, 'GuardHoneypot', {
-        value: api,
-        writable: false,
-        configurable: false,
-    });
+    // A second copy of this core on the page (ch.js bundles it, so ch.js plus
+    // this file's own <script> tag, in either order) keeps the first
+    // definition instead of throwing "Cannot redefine property".
+    if (!global.GuardHoneypot) {
+        Object.defineProperty(global, 'GuardHoneypot', {
+            value: api,
+            writable: false,
+            configurable: false,
+        });
+    } else {
+        console.error('[cyborg-hunter] Not redefining GuardHoneypot: GuardHoneypot is already defined, so two scripts on this page include the honeypot. Fix: keep one of them (ch.js already contains the honeypot). https://github.com/cyborg-hunter/cyborg-hunter/blob/main/docs/advanced-integration.md#double-load');
+    }
 })(window);
 // ----- jsPsych extension adapter -----
 // Wraps the GuardHoneypot core (above) in the jsPsych extension
@@ -442,7 +449,7 @@
 class GuardHoneypotExtension {
   static info = {
     name: 'guard-honeypot',
-    version: '0.9.2',
+    version: '0.10.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().

package/src/oneliner/adapters/jspsych-extension.js

@@ -0,0 +1,196 @@
+// src/oneliner/adapters/jspsych-extension.js
+// The jsPsych extension ch.js injects into every trial (adapters/jspsych.js
+// adds it to initJsPsych's list and to each trial object). Unlike the manual
+// extension (src/jspsych/extension-cyborg-hunter.js) it creates no monitor:
+// boot already has one, kept inside a trial by the segmenter. So:
+//   on_load    rotate: close the span before this trial (a "gap"), open the
+//              host trial;
+//   on_finish  cut: close the host trial, turn everything since the last cut
+//              into a segment, open the next gap span. The returned object is
+//              merged into this trial's own row by jsPsych (jspsych.js 7.3.1
+//              :2772, :2814-2823), before the trial's own on_finish, so
+//              whatever save the researcher already does carries the segment
+//              and the running totals up to this row.
+//
+// The class keeps info.name 'cyborg-hunter' (jsPsych keys its extension
+// instances by name) and exposes `.monitor`, which the replay extension reads
+// through jsPsych.extensions['cyborg-hunter'].monitor.
+//
+// A trial listing the manual class by name (a researcher-named entry with
+// params.trialId) reaches this instance too, with its params, so its trialId
+// names the segment.
+//
+// A late on_load is dropped. A synchronous plugin (call-function) finishes
+// inside its own trial() call, and jsPsych runs that trial's load callback
+// only afterwards (jspsych.js 7.3.1 :3046-3056, :3101-3103), in one of two
+// orders:
+//   - nextTrial runs synchronously from finishTrial: the next trial's
+//     on_start and on_load come first, then the stale on_load, which would
+//     close the next trial's span as a gap and reopen it unnamed;
+//   - post_trial_gap / default_iti > 0 defer nextTrial: the stale on_load
+//     comes right after its own on_finish and would open a span for a trial
+//     that already ended.
+// A third order: when the next trial's trial() returns a Promise (jsPsych 7
+// audio plugins, custom plugins), jsPsych leaves its load callback to the
+// plugin (:3099-3103), so the stale on_load arrives after the next trial's
+// on_start but before that trial's own on_load.
+// An index check (current_trial_global) catches only the first order: in the
+// second the index has not moved yet. So on_start arms the load and records
+// the params object jsPsych passed; on_load counts only while armed and only
+// with that same object; on_finish disarms. jsPsych hands one trial's
+// on_start and on_load the same object (extension.params of the same trial,
+// :3027-3030, :3046-3054), and the adapter gives every trial its own copy of
+// the injected entry, so the stale call is rejected in all three orders.
+// (jsPsych calls the extension's on_start on every trial that lists it, so
+// every real on_load is armed.)
+//
+// After the session has ended (the final hook ran, ctx.jspsych.finalized),
+// both hooks leave the segmenter alone: rows of a second jsPsych instance
+// that runs afterwards get no cyborgHunterError ('finished') marker; the
+// adapter warned about the second instance when it was created. They also
+// stand down when the deferred session start failed (ctx.bootError, boot.js
+// failDeferred), which marked every row already.
+//
+// ctx (set by installJsPsychAdapter): { monitor, segmenter, jspsych, debug? }.
+// None of the hooks throws into jsPsych: a failure becomes cyborgHunterError
+// on the row. With no ctx (ch.js failed or stood down, boot.js; the class is
+// still registered so researcher trials typed jsPsychCyborgHunter run) every
+// hook does nothing.
+//
+// Leftovers of manual wiring on a half-migrated page, where
+// jsPsychCyborgHunter is this class: participantId / preset in the
+// initJsPsych entry's params (initialize) and the on_finish finalize() call
+// each warn once from the catalogue and are otherwise ignored; finalize()
+// existing at all keeps the researcher's save code after it running.
+
+import { MESSAGES } from '../errors.js';
+
+export class OneLinerExtension {
+  static info = {
+    name: 'cyborg-hunter',
+    // Hand-bumped with the package version (tests/cli/version-invariant.test.js
+    // pins it to package.json by reading this literal).
+    version: '0.10.0',
+    data: {
+      integrity: { type: 'object' },
+      integritySegment: { type: 'object' }
+    }
+  };
+
+  static ctx = null;
+
+  constructor(jsPsych) {
+    this.jsPsych = jsPsych;
+    this._trialStart_perfNow = null;
+    this._loadError = null;
+    this._loadArmed = false;
+    this._armedParams = undefined;
+    this._paramsWarned = false;
+    this._finalizeWarned = false;
+  }
+
+  get monitor() {
+    return OneLinerExtension.ctx ? OneLinerExtension.ctx.monitor : null;
+  }
+
+  // The monitor already exists (boot); nothing to set up. jsPsych passes the
+  // initJsPsych entry's params (a researcher's entry wins the dedupe over
+  // ours, adapters/jspsych.js).
+  initialize(params) {
+    if (this._paramsWarned || !params) return;
+    if (params.participantId !== undefined || params.preset !== undefined) {
+      this._paramsWarned = true;
+      console.warn(MESSAGES.extensionParamsIgnored());
+    }
+  }
+
+  // The manual extension's end-of-session call. ch.js ends the session from
+  // initJsPsych's on_finish (adapters/jspsych.js), before the researcher's.
+  finalize() {
+    if (this._finalizeWarned) return;
+    this._finalizeWarned = true;
+    console.warn(MESSAGES.finalizeNotNeeded());
+  }
+
+  // jsPsych 7 calls on_start on every trial that lists the extension, before
+  // the plugin's trial(): arm this trial's on_load, for these params only.
+  on_start(params) {
+    this._loadArmed = true;
+    this._armedParams = params;
+  }
+
+  on_load(params) {
+    var ctx = OneLinerExtension.ctx;
+    // A late on_load (see the header) is dropped before anything is reset:
+    // the trial now open keeps its anchor and any rotate error.
+    if (!this._loadArmed || params !== this._armedParams) return;
+    this._loadArmed = false;
+    this._armedParams = undefined;
+    this._loadError = null;
+    if (!ctx || ctx.bootError || (ctx.jspsych && ctx.jspsych.finalized)) return;
+    try {
+      // Same anchor as the manual extension: ingest subtracts it from the
+      // tab-away `start` times (same performance.now() clock).
+      this._trialStart_perfNow = performance.now();
+      var r = ctx.segmenter.rotate({
+        trialId: (params && params.trialId) || 'trial-' + this.jsPsych.getProgress().current_trial_global,
+        phase: (params && params.phase) || null,
+        // ?? not ||: an explicit decoyAnswer:false (skip the decoy) must reach
+        // the core as false.
+        decoyAnswer: params && params.decoyAnswer !== undefined && params.decoyAnswer !== null ? params.decoyAnswer : null,
+        experimentContainer: (params && params.experimentContainer) || null
+      });
+      if (r && r.error) this._loadError = r.error;
+    } catch (e) {
+      this._loadError = String((e && e.message) || e);
+    }
+    // jsPsych's prepareDom wiped <body>, badge included, before the first
+    // trial; this puts it back while that trial is on screen.
+    try { if (ctx.debug && ctx.debug.refresh) ctx.debug.refresh(); } catch (_) { /* a debug aid */ }
+  }
+
+  on_finish(_params) {
+    var ctx = OneLinerExtension.ctx;
+    this._loadArmed = false;
+    this._armedParams = undefined;
+    if (!ctx || ctx.bootError || (ctx.jspsych && ctx.jspsych.finalized)) return {};
+    // Timed only under data-debug: no clock reads otherwise.
+    var t0 = ctx.debug ? performance.now() : 0;
+    var out;
+    try {
+      var idx = this.jsPsych.getProgress().current_trial_global;
+      var r = ctx.segmenter.cut({ source: 'host', nextTrialId: 'gap-' + idx });
+      if (r && r.segment) {
+        var report = r.trialReport || {};
+        report.trialStart_perfNow = this._trialStart_perfNow;
+        out = {
+          integrity: report,
+          integritySegment: r.segment,
+          integrityPasteCount: r.segment.counters.pasteCount,
+          integrityCopyCount: r.segment.counters.copyCount,
+          integrityDropCount: r.segment.counters.dropCount,
+          integritySoftScore: r.segment.score.softScore,
+          integrityAnyHardTriggered: r.segment.score.anyHardTriggered
+        };
+        // A segment that comes with an error is complete; only the next span
+        // failed to open. Save it, and mark the row.
+        var err = r.error || this._loadError;
+        if (err) out.cyborgHunterError = err;
+        if (ctx.jspsych) ctx.jspsych.segmentsWritten = (ctx.jspsych.segmentsWritten || 0) + 1;
+      } else {
+        out = { cyborgHunterError: (r && r.error) || this._loadError || 'no segment' };
+      }
+    } catch (e) {
+      out = { cyborgHunterError: String((e && e.message) || e) };
+    }
+    this._trialStart_perfNow = null;
+    this._loadError = null;
+    try {
+      // The timing covers ch.js's cut plus output assembly, not jsPsych's own
+      // merge of this output into the data row.
+      if (ctx.debug && ctx.debug.stats) ctx.debug.stats().segmentWriteMs.push(performance.now() - t0);
+      if (ctx.debug && ctx.debug.refresh) ctx.debug.refresh();   // after the timing push
+    } catch (_) { /* debug counters are optional */ }
+    return out;
+  }
+}