cyborg-hunter 0.9.1 → 0.10.0

package/src/oneliner/errors.js

@@ -0,0 +1,219 @@
+// src/oneliner/errors.js
+// The one-line setup's loud errors. Every message names the problem, its
+// cause, the fix and a doc link, in that order, so a researcher reading the
+// console knows what to change without opening the source:
+//   [cyborg-hunter] <problem>: <cause>. Fix: <fix>. <link>
+// build.js imports MESSAGES for the cyborg-hunter.min.js double-load footer,
+// so the bundle and the catalogue share one string. The guard cores are plain
+// IIFEs that cannot import this file; their double-load messages are written
+// out in the same format (tests/oneliner/errors.test.js checks all of them).
+
+export const DOCS = 'https://github.com/cyborg-hunter/cyborg-hunter/blob/main/docs/';
+
+export function formatError(problem, cause, fix, link) {
+  return '[cyborg-hunter] ' + problem + ': ' + cause + '. Fix: ' + fix + '. ' + link;
+}
+
+// For one-off messages; the catalogue entries below are passed to
+// console.error directly (they are already formatted).
+export function loudError(problem, cause, fix, link) {
+  console.error(formatError(problem, cause, fix, link));
+}
+
+var REPORT_FIX = 'open an issue with this message and your <script> tag';
+
+// The data-debug summary's part for MESSAGES.replaySaveReminder (debug.js).
+export const REPLAY_SAVE_REMINDER = 'data-replay is on: save CyborgHunter.replay() in your save code';
+
+export const MESSAGES = {
+  doubleLoad: function (first, second) {
+    return formatError('Not starting a second monitor', second + ' was loaded after ' + first,
+      'load only one of ch.js and cyborg-hunter.min.js (the one-liner already contains the monitor)',
+      DOCS + 'advanced-integration.md#double-load');
+  },
+  // min.js's own sentinel found by a second copy of min.js: nothing to say
+  // about ch.js, and no load order to claim.
+  coreLoadedTwice: function () {
+    return formatError('cyborg-hunter.min.js is loaded twice',
+      'two <script> tags on this page load the monitor bundle',
+      'keep one <script> tag',
+      DOCS + 'advanced-integration.md#double-load');
+  },
+  notHookable: function () {
+    return formatError('Not monitoring jsPsych trials',
+      'ch.js loaded after initJsPsych() ran, or the page calls jsPsychModule.initJsPsych / new JsPsych directly (a bundler or ES module build), which never goes through window.initJsPsych',
+      'move the ch.js <script> above your experiment code (and below jspsych.js); for a bundled jsPsych, use manual mode (cyborg-hunter.min.js)',
+      DOCS + 'quickstart.md#placement');
+  },
+  loadedAboveJsPsych: function () {
+    return formatError('Not monitoring jsPsych trials',
+      'ch.js was loaded before jspsych.js, so initJsPsych could not be wrapped',
+      'move the ch.js <script> below jspsych.js and above your experiment code',
+      DOCS + 'quickstart.md#placement');
+  },
+  // The URL parameter names are not spelled out here: the caller supplies the
+  // list (participant-id.js), and the docs anchor documents it.
+  randomId: function (id) {
+    return formatError('Participant rows cannot be linked to your platform ID',
+      'no PROLIFIC-style URL parameter, data-participant-id or CyborgHunterConfig.participantId was found; using ' + id,
+      'add data-participant-id="..." to the ch.js tag or pass the ID in the URL',
+      DOCS + 'quickstart.md#participant-id');
+  },
+  manualInitOnOneLiner: function () {
+    return formatError('CyborgHunter.init() called while the one-liner is running',
+      'ch.js already created the monitor at page load',
+      'remove the init()/startTrial()/endTrial() code, or switch to cyborg-hunter.min.js for manual mode',
+      DOCS + 'advanced-integration.md#manual-mode');
+  },
+  // console.warn, not error: the monitor still runs, on the standard preset.
+  unknownPreset: function (value) {
+    return formatError('Unknown preset "' + value + '"',
+      'data-preset / CyborgHunterConfig.preset must be permissive, standard or strict; using standard',
+      'use permissive, standard or strict',
+      DOCS + 'quickstart.md#configuration');
+  },
+  bootFailed: function (msg) {
+    return formatError('Cyborg Hunter did not start', msg, REPORT_FIX, DOCS + 'known-issues.md#one-line-setup');
+  },
+  // The jsPsych host: wrapping initJsPsych, walking the timeline at run(),
+  // and the end-of-session hook. jsPsych keeps running after each of them.
+  hookFailed: function (msg) {
+    return formatError('Cyborg Hunter could not hook initJsPsych', msg, REPORT_FIX, DOCS + 'known-issues.md#one-line-setup');
+  },
+  instrumentFailed: function (msg) {
+    return formatError('Cyborg Hunter could not instrument the timeline', msg, REPORT_FIX, DOCS + 'known-issues.md#one-line-setup');
+  },
+  sessionEndFailed: function (msg) {
+    return formatError('Cyborg Hunter could not write the end-of-session data', msg, REPORT_FIX, DOCS + 'known-issues.md#one-line-setup');
+  },
+  guardFailed: function (guard, msg) {
+    return formatError('The ' + guard + ' guard is not running', msg, REPORT_FIX, DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.warn: the experiment runs; the entry trial still starts friction,
+  // but without the friction extension it has no jsPsych instance and no
+  // refusal notices.
+  frictionEntryWithoutFriction: function () {
+    return formatError('Friction is only partly set up',
+      'the timeline has friction\'s entry trial but data-guards does not enable friction',
+      'add friction to data-guards (for example data-guards="honeypot,friction"), or remove the entry trial',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // Vanilla host: a mark click, a form submit or pagehide. The page carries on;
+  // the segment may be missing from the blob.
+  vanillaEventFailed: function (msg) {
+    return formatError('Cyborg Hunter could not record a page boundary', msg, REPORT_FIX, DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.warn, vanilla host: CyborgHunter.startFriction() or a
+  // data-ch-friction-start click still starts enforcement (as the jsPsych
+  // entry trial does), but nothing injected the refusal notices.
+  frictionStartWithoutFriction: function () {
+    return formatError('Friction is only partly set up',
+      'friction was started (data-ch-friction-start or CyborgHunter.startFriction()) but data-guards does not enable friction',
+      'add friction to data-guards (for example data-guards="honeypot,friction"), or remove the friction start',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.warn, once per page, vanilla host: the whole session is kept in
+  // sessionStorage so the last page's form carries it; browsers cap it at
+  // about 5 MB per origin.
+  storageNearlyFull: function () {
+    return formatError('The saved session is approaching the sessionStorage limit',
+      'the session kept for the next page is over 4 MB, mostly the raw mouse trace',
+      'set CyborgHunterConfig.collectForPostHoc.rawMouseTrack = false',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.error, vanilla host: the session could not be kept for the next
+  // page (storage blocked or full). This page's form and data() still carry
+  // everything recorded so far.
+  storageFailed: function (msg) {
+    return formatError('The session could not be carried to the next page', msg,
+      'allow site storage for the study page, or save CyborgHunter.data() on every page',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // Session replay (data-replay): cyborg-hunter-replay.js is loaded lazily
+  // from next to ch.js (or data-replay-src). console.error; the experiment
+  // runs on without replay.
+  replayUnavailable: function (msg) {
+    return formatError('Session replay is not recording', msg,
+      'put cyborg-hunter-replay.js next to ch.js or point data-replay-src at it, and allow its URL in the page\'s Content-Security-Policy',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.warn, from CyborgHunter.replay(), which then returns null.
+  replayOff: function () {
+    return formatError('CyborgHunter.replay() has no recording',
+      'session replay is off (the ch.js tag has no data-replay)',
+      'add data-replay to the ch.js tag',
+      DOCS + 'advanced-integration.md#replay-with-the-one-liner');
+  },
+  replayNotReady: function () {
+    return formatError('CyborgHunter.replay() has no recording',
+      'the replay recorder has not started yet, or cyborg-hunter-replay.js failed to load (see the error above)',
+      'call CyborgHunter.replay() when the session ends (your on_finish or save code)',
+      DOCS + 'advanced-integration.md#replay-with-the-one-liner');
+  },
+  // console.warn, from CyborgHunter.replay(): the autoSave finalize() ran but
+  // left no recording (its save failed, or it timed out); replay() returns null.
+  replayFinalizeFailed: function () {
+    return formatError('CyborgHunter.replay() has no recording',
+      'the recorder\'s autoSave finalize ended without a recording (its save failed; see the error above)',
+      'check the console for the save error above, or set autoSave.mode to \'none\' and save the recording CyborgHunter.replay() returns yourself',
+      DOCS + 'advanced-integration.md#replay-with-the-one-liner');
+  },
+  // console.warn at boot, vanilla host: CyborgHunterConfig.replay.autoSave
+  // has no effect there (no session-end hook to run the recorder's save from).
+  replayAutoSaveVanilla: function () {
+    return formatError('CyborgHunterConfig.replay.autoSave is ignored',
+      'autoSave is jsPsych-only under the one-liner, and this page has no jsPsych',
+      'save the recording yourself: call CyborgHunter.replay() in your submit or save code and send what it returns (autoSave works only with jsPsych)',
+      DOCS + 'advanced-integration.md#replay-with-the-one-liner');
+  },
+  // console.warn, jsPsych host: the autoSave finalize() did not settle in time;
+  // the researcher's on_finish runs anyway.
+  replayFinalizeTimedOut: function () {
+    return formatError('The replay recorder\'s autoSave did not finish',
+      'finalize() had not settled after 15 s, so the session ends without waiting for it',
+      'check that the autoSave target (for example DataPipe) is reachable, or save the recording yourself with CyborgHunter.replay()',
+      DOCS + 'advanced-integration.md#replay-with-the-one-liner');
+  },
+  // console.warn: ch.js keeps one session per page. The session ends when the
+  // first instance finishes; rows recorded after that carry no integrity data.
+  secondJsPsychInstance: function () {
+    return formatError('A second jsPsych instance was created',
+      'ch.js records one session per page and ends it when the first instance finishes, so trials run after that are not monitored',
+      'create one jsPsych instance with initJsPsych() and run one timeline, or use cyborg-hunter.min.js and the jsPsych extension (manual mode) for several instances',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.info, once at boot, with data-replay and no data-debug (with
+  // data-debug the summary carries REPLAY_SAVE_REMINDER instead; debug.js).
+  // It replaces the recorder's own autoSave warning, which the one-liner
+  // silences (replay-loader.js recorderConfig).
+  replaySaveReminder: function () {
+    return formatError('data-replay is on',
+      'ch.js records the session but does not save the recording',
+      'save CyborgHunter.replay() in your save code',
+      DOCS + 'advanced-integration.md#replay-with-the-one-liner');
+  },
+  // console.warn, once, from the inert window.CyborgHunter that boot leaves
+  // when ch.js failed (api.js buildInertApi): the call did nothing.
+  notRunning: function () {
+    return formatError('Cyborg Hunter is not running on this page',
+      'ch.js did not start (see the error above), so CyborgHunter calls do nothing',
+      'fix the error logged above; until then the experiment runs without monitoring',
+      DOCS + 'known-issues.md#one-line-setup');
+  },
+  // console.warn, once: a half-migrated manual page still calls the manual
+  // extension's finalize() from its on_finish.
+  finalizeNotNeeded: function () {
+    return formatError('finalize() is not needed with ch.js',
+      'ch.js ends the session itself when the jsPsych timeline finishes, so this call does nothing',
+      'remove the finalize() call from your on_finish (keep your own save code)',
+      DOCS + 'advanced-integration.md#switching-to-the-one-liner');
+  },
+  // console.warn, once: the manual docs' initJsPsych entry still carries
+  // participantId / preset params, which the one-liner does not read.
+  extensionParamsIgnored: function () {
+    return formatError('participantId and preset in the cyborg-hunter extension params are ignored by ch.js',
+      'ch.js reads the participant ID and the preset from its own <script> tag',
+      'use data-participant-id / data-preset on the ch.js tag instead',
+      DOCS + 'advanced-integration.md#switching-to-the-one-liner');
+  }
+};

package/src/oneliner/guards.js

@@ -0,0 +1,67 @@
+// src/oneliner/guards.js
+// Starts the guard cores that ch.js bundles (window.GuardHoneypot,
+// window.GuardFriction) without jsPsych: the honeypot injects its bait DOM and
+// subscribes to friction's violations; friction injects its AI refusal
+// notices and runs observe-only (it logs violations, shows no curtain) until
+// a host mark starts enforcement. Called once per page: by boot on the
+// vanilla host, or when a jsPsych page falls back to vanilla.
+//
+// startGuards({ win, doc, guards: { honeypot, friction }, debug })
+//
+// Order matters, as in extension-guard-friction.js initialize(): friction's
+// start() emits its first violation synchronously, so it is deferred to a
+// microtask that runs after the honeypot has subscribed. The honeypot needs
+// document.body for its bait elements; when ch.js runs in <head> both guards
+// wait for DOMContentLoaded, keeping the same order.
+//
+// A missing core (only possible outside the ch.js bundle) is skipped. A core
+// that throws is reported loudly and does not stop the other one.
+//
+// A guard already running is not started again. That happens on a jsPsych
+// page ch.js could not hook whose researcher listed the guard extensions
+// themselves: their initialize() ran before the fallback. A second
+// GuardHoneypot.init would reset its violation log, a second
+// injectRefusalNotices adds another refresh interval. The signs are the DOM
+// each one leaves (the honeypot's #fg-honeypot bait, friction's
+// #ai-research-notice) and friction's token.
+
+import { MESSAGES } from './errors.js';
+
+function attempt(name, fn) {
+  try { fn(); } catch (e) { console.error(MESSAGES.guardFailed(name, String((e && e.message) || e))); }
+}
+
+export function startGuards(opts) {
+  var win = opts.win, doc = opts.doc, guards = opts.guards;
+  var debug = !!opts.debug;
+
+  function present(id) {
+    return typeof doc.getElementById === 'function' && !!doc.getElementById(id);
+  }
+
+  function run() {
+    if (guards.honeypot && win.GuardHoneypot && !present('fg-honeypot')) {
+      attempt('honeypot', function () {
+        win.GuardHoneypot.init({ jsPsych: null, friction: win.GuardFriction, debug: debug });
+      });
+    }
+    if (guards.friction && win.GuardFriction && !win._guardFrictionToken && !present('ai-research-notice')) {
+      // Once per page, as the friction extension's initialize() does (the
+      // notices are not idempotent: each call adds another refresh interval).
+      attempt('friction', function () { win.GuardFriction.injectRefusalNotices(); });
+      Promise.resolve().then(function () {
+        attempt('friction', function () {
+          var token = win.GuardFriction.start({ jsPsych: null, observeOnly: true, debug: debug });
+          // Same non-enumerable slot the friction extension uses, so whoever
+          // finalizes the session can stop() with the right token.
+          Object.defineProperty(win, '_guardFrictionToken', {
+            value: token, writable: false, enumerable: false, configurable: true
+          });
+        });
+      });
+    }
+  }
+
+  if (doc.body) run();
+  else doc.addEventListener('DOMContentLoaded', run, { once: true });
+}

package/src/oneliner/participant-id.js

@@ -0,0 +1,49 @@
+// src/oneliner/participant-id.js
+// Which participant the session belongs to, in order of precedence:
+//   1. a URL parameter, the first name in `params` present in the query
+//      string (recruitment platforms append the worker's ID to the study URL);
+//   2. the ch.js tag's data-participant-id attribute;
+//   3. window.CyborgHunterConfig.participantId;
+//   4. a random id, which boot.js warns about: those rows cannot be linked
+//      back to the platform's records.
+// Values are trimmed; an empty or blank value counts as missing.
+//
+// resolveParticipantId({ search, attr, configId, params, random }) → { id, source }
+//   search:  location.search ('?a=1&b=2')
+//   params:  ordered URL parameter names; the caller supplies the list
+//   random:  () => string, called only when nothing else is found
+//   source:  'url:<param>' | 'attribute' | 'config' | 'random'
+//            (boot.js adds 'session': a random id kept from an earlier page)
+
+// The URL parameter names boot.js reads by default, in order of precedence:
+// Prolific's and MTurk's documented study-URL parameters, then a generic name.
+export const DEFAULT_PARAMS = ['PROLIFIC_PID', 'workerId', 'participant'];
+
+function clean(v) {
+  if (v === null || v === undefined) return null;
+  var s = String(v).trim();
+  return s === '' ? null : s;
+}
+
+export function resolveParticipantId(opts) {
+  var query = new URLSearchParams(opts.search || '');
+  var params = opts.params || [];
+  for (var i = 0; i < params.length; i++) {
+    var fromUrl = clean(query.get(params[i]));
+    if (fromUrl) return { id: fromUrl, source: 'url:' + params[i] };
+  }
+  var attr = clean(opts.attr);
+  if (attr) return { id: attr, source: 'attribute' };
+  var configId = clean(opts.configId);
+  if (configId) return { id: configId, source: 'config' };
+  return { id: opts.random(), source: 'random' };
+}
+
+// 'ch-' + 12 lowercase hex characters (48 random bits) from the given
+// Web Crypto object (window.crypto in the browser).
+export function randomParticipantId(crypto) {
+  var bytes = crypto.getRandomValues(new Uint8Array(6));
+  var hex = '';
+  for (var i = 0; i < bytes.length; i++) hex += (bytes[i] < 16 ? '0' : '') + bytes[i].toString(16);
+  return 'ch-' + hex;
+}

package/src/oneliner/replay-loader.js

@@ -0,0 +1,296 @@
+// src/oneliner/replay-loader.js
+// Session replay under the one-line setup, opt-in with data-replay. ch.js does
+// not bundle the recorder: cyborg-hunter-replay.js (self-contained, the same
+// file manual mode loads) is fetched only when data-replay is set, from the
+// directory ch.js itself was loaded from, or from data-replay-src.
+//
+//   jsPsych  initJsPsych runs synchronously in the experiment code, before
+//            the script can have loaded. ch.js therefore lists a proxy
+//            extension (adapters/jspsych.js) whose async initialize() loads
+//            the script and then hands over to the real replay extension:
+//            jsPsych's run() awaits loadExtensions, which awaits every
+//            initialize() (jspsych.js 7.3.1 :2695, :2946). The proxy keeps
+//            the name 'cyborg-hunter-replay', so the replay extension finds
+//            the monitor through jsPsych.extensions['cyborg-hunter'] as in
+//            manual mode.
+//   vanilla  the standalone recorder (window.CyborgHunterReplay.attach)
+//            starts once the page has loaded (DOMContentLoaded) and follows
+//            the segmenter: adapters/vanilla.js ends its trial and starts the
+//            next span's at every cut, and stops it at pagehide. Recordings
+//            are per page.
+//
+// CyborgHunter.replay() stops the recorder, serializes it and returns the
+// recording for the researcher's own save code (default autoSave mode
+// 'none'; boot reminds the researcher to save it, replaySaveReminder, in
+// place of the recorder's own warning). CyborgHunterConfig.replay = { tier, autoSave } keeps the
+// recorder's own DataPipe save available (adapters/jspsych.js finalizes it at
+// the end of the session).
+//
+// Nothing here throws into the page. A script that fails to load (404,
+// network, Content-Security-Policy) or does not arrive within LOAD_TIMEOUT_MS
+// is a catalogue error, and the experiment runs on without replay: jsPsych's
+// run() is waiting on the proxy's initialize(), so a stalled CDN must not
+// hold the experiment back indefinitely.
+
+import { VERSION } from '../shared/constants.js';
+import { MESSAGES } from './errors.js';
+
+var REPLAY_FILE = 'cyborg-hunter-replay.js';
+var REPLAY_NAME = 'cyborg-hunter-replay';
+var LOAD_TIMEOUT_MS = 15000;
+
+function message(e) { return String((e && e.message) || e); }
+
+// The recorder's defaults under the one-liner; the researcher's
+// CyborgHunterConfig.replay keys (tier, autoSave) override them.
+// _ownerSavesRecording silences the recorder's "autoSave.mode is none"
+// warning (src/replay/recorder.js), which names getRecording(): the
+// one-liner's own reminder (replaySaveReminder below) names
+// CyborgHunter.replay() instead.
+function recorderConfig(ctx, params) {
+  return Object.assign({ participantId: ctx.participantId, autoSave: { mode: 'none' }, _ownerSavesRecording: true }, params);
+}
+
+// Whether the researcher must save CyborgHunter.replay() themselves: replay
+// is on and has a script URL, and the recorder does not save itself
+// (CyborgHunterConfig.replay.autoSave, which only the jsPsych host runs).
+// Read by debug.js for the summary.
+export function replaySaveReminderApplies(ctx) {
+  if (!ctx.config.replay || !ctx.replaySrc) return false;
+  var autoSave = ctx.config.replay.autoSave;
+  var selfSaving = !!(autoSave && autoSave.mode && autoSave.mode !== 'none');
+  return !(selfSaving && ctx.host !== 'vanilla');
+}
+
+// data-replay-src when given, else cyborg-hunter-replay.js next to ch.js.
+// scriptSrc is document.currentScript.src (entry.js); it is null for an
+// inline or bundled ch.js, which has no directory to look in.
+export function replaySrcFor(scriptSrc, override) {
+  if (override) return override;
+  if (!scriptSrc) {
+    throw new Error('ch.js could not tell which URL it was loaded from (inline or bundled), so it cannot find ' +
+      REPLAY_FILE + '; set data-replay-src');
+  }
+  return new URL(REPLAY_FILE, scriptSrc).href;
+}
+
+// One <script> per src and document; every caller gets the same promise.
+var loads = new WeakMap();   // doc → { src: promise }
+
+export function loadScript(doc, src, timeoutMs, nonce) {
+  var perDoc = loads.get(doc);
+  if (!perDoc) { perDoc = Object.create(null); loads.set(doc, perDoc); }
+  if (perDoc[src]) return perDoc[src];
+  var p = new Promise(function (resolve, reject) {
+    var el = doc.createElement('script');
+    var timer = setTimeout(function () {
+      reject(new Error(src + ' timed out after ' + Math.round((timeoutMs || LOAD_TIMEOUT_MS) / 1000) + ' s'));
+    }, timeoutMs || LOAD_TIMEOUT_MS);
+    // Listeners before the append: a script can settle inside appendChild.
+    el.addEventListener('load', function () { clearTimeout(timer); resolve(); });
+    el.addEventListener('error', function () {
+      clearTimeout(timer);
+      reject(new Error('could not load ' + src + ' (missing file, network error or Content-Security-Policy)'));
+    });
+    // A page with a nonce-based Content-Security-Policy only runs scripts that carry its nonce.
+    if (nonce) el.nonce = nonce;
+    el.src = src;
+    (doc.head || doc.documentElement || doc.body).appendChild(el);
+  });
+  perDoc[src] = p;
+  return p;
+}
+
+// makeReplayProxy({ doc, src, ctx, timeoutMs? }) → class ReplayProxyExtension
+export function makeReplayProxy(opts) {
+  var doc = opts.doc, src = opts.src, ctx = opts.ctx, timeoutMs = opts.timeoutMs;
+  var win = ctx.win;
+
+  class ReplayProxyExtension {
+    static info = { name: REPLAY_NAME, version: VERSION, data: {} };
+
+    constructor(jsPsych) {
+      this.jsPsych = jsPsych;
+      this.inner = null;   // the real replay extension, once loaded and initialized
+    }
+
+    // Always resolves: a rejection here would stop jsPsych's run().
+    async initialize(params) {
+      var inner = null;
+      try {
+        // Already on the page (a <script> of the researcher's own): no load.
+        if (typeof win.jsPsychCyborgHunterReplay !== 'function') await loadScript(doc, src, timeoutMs, ctx.scriptNonce);
+        var Inner = win.jsPsychCyborgHunterReplay;
+        if (typeof Inner !== 'function') throw new Error(src + ' loaded but did not define jsPsychCyborgHunterReplay');
+        inner = new Inner(this.jsPsych);
+        inner.initialize(recorderConfig(ctx, params));
+        this.inner = inner;
+      } catch (e) {
+        // A recorder attached before the failure would keep its listeners.
+        if (inner && inner.api) { try { inner.api.destroy(); } catch (_) { /* already failing */ } }
+        console.error(MESSAGES.replayUnavailable(message(e)));
+      }
+    }
+
+    // jsPsych calls these on every trial that lists the extension: no-ops
+    // until the real extension is in place, and never a throw into jsPsych.
+    on_start(params) {
+      if (!this.inner) return;
+      try { this.inner.on_start(params); } catch (_) { /* replay only */ }
+    }
+
+    on_load(params) {
+      if (!this.inner) return;
+      try { this.inner.on_load(params); } catch (_) { /* replay only */ }
+    }
+
+    on_finish(params) {
+      if (!this.inner) return {};
+      try { return this.inner.on_finish(params) || {}; } catch (_) { return {}; }
+    }
+
+    finalize() {
+      return this.inner ? this.inner.finalize() : Promise.resolve();
+    }
+
+    getLastRecording() {
+      return this.inner ? this.inner.getLastRecording() : null;
+    }
+  }
+
+  return ReplayProxyExtension;
+}
+
+// createVanillaReplay({ win, doc, src, ctx, timeoutMs? })
+//   → Promise<{ api, startTrial(trialId), endTrial(), stop() }>
+// The wrappers never throw (the recorder's lifecycle calls do, on a call out
+// of order) and do nothing once stop() ran or replay() took the recording
+// (handle.api is null then).
+export function createVanillaReplay(opts) {
+  var win = opts.win, doc = opts.doc, src = opts.src, ctx = opts.ctx;
+  var ready = win.CyborgHunterReplay ? Promise.resolve() : loadScript(doc, src, opts.timeoutMs, ctx.scriptNonce);
+  return ready.then(function () {
+    var R = win.CyborgHunterReplay;
+    if (!R || typeof R.attach !== 'function') throw new Error(src + ' loaded but did not define CyborgHunterReplay');
+    var api = R.attach(recorderConfig(ctx, ctx.config.replay));
+    var handle = {
+      api: api,
+      stopped: false,
+      startTrial: function (trialId) {
+        if (!handle.api || handle.stopped) return;
+        try { handle.api.startTrial({ trialId: trialId }); } catch (_) { /* replay only */ }
+      },
+      endTrial: function () {
+        if (!handle.api || handle.stopped) return;
+        try { handle.api.endTrial(); } catch (_) { /* replay only */ }
+      },
+      stop: function () {
+        if (!handle.api || handle.stopped) return;
+        handle.stopped = true;
+        try { handle.api.stopSession('finished'); } catch (_) { /* replay only */ }
+      }
+    };
+    try {
+      api.startSession();
+      var state = ctx.segmenter.state();
+      if (state.open) api.startTrial({ trialId: state.currentTrialId });
+    } catch (e) {
+      try { api.destroy(); } catch (_) { /* already failing */ }
+      throw e;
+    }
+    return handle;
+  });
+}
+
+// Stop, serialize, destroy. The recorder refuses stopSession once stopped,
+// which is fine: the recording is complete then.
+function takeRecording(holder, opts) {
+  var api = holder.api;
+  try { api.stopSession('finished'); } catch (_) { /* already stopped */ }
+  try {
+    return api.getRecording(opts);
+  } finally {
+    try { api.destroy(); } catch (_) { /* teardown best-effort */ }
+    holder.api = null;   // the jsPsych extension's later finalize() is a no-op
+  }
+}
+
+// The object holding the recorder handle (.api): the real jsPsych replay
+// extension behind the proxy, or the vanilla handle.
+function currentHolder(ctx) {
+  if (ctx.host === 'vanilla') return ctx.replay || null;
+  var ext = ctx.jsPsych && ctx.jsPsych.extensions && ctx.jsPsych.extensions[REPLAY_NAME];
+  if (!ext) return null;
+  return 'inner' in ext ? ext.inner : ext;
+}
+
+function replay(ctx) {
+  if (!ctx.config.replay) { console.warn(MESSAGES.replayOff()); return null; }
+  if (ctx.replayRecording) return ctx.replayRecording;
+  var holder = currentHolder(ctx);
+  if (holder && holder.api) {
+    var report = null;
+    try { report = ctx.monitor.getSessionReport(); } catch (_) { /* the recording stands on its own */ }
+    var host = null;
+    try { host = typeof holder._detectHost === 'function' ? holder._detectHost() : null; } catch (_) { /* optional */ }
+    ctx.replayRecording = takeRecording(holder, { chSessionReport: report, host: host });
+    return ctx.replayRecording;
+  }
+  // An autosaving finalize() (CyborgHunterConfig.replay.autoSave) took it.
+  var last = holder && typeof holder.getLastRecording === 'function' ? holder.getLastRecording() : null;
+  if (last) return last;
+  // The holder exists but its recorder is gone and saved nothing: an autosaving
+  // finalize() destroyed it and failed. Not "has not started yet".
+  console.warn(holder ? MESSAGES.replayFinalizeFailed() : MESSAGES.replayNotReady());
+  return null;
+}
+
+// installReplay({ win, ctx, doc?, timeoutMs? }) → { startVanilla() }
+// Installs ctx.handlers.replay (CyborgHunter.replay()) whether or not replay
+// is on. With data-replay: ctx.replaySrc, and on the jsPsych host
+// ctx.replayProxy, which adapters/jspsych.js lists in initJsPsych.
+// startVanilla() starts the vanilla recorder (vanilla host, or a jsPsych page
+// ch.js could not hook), once, after DOMContentLoaded; it sets ctx.replay.
+export function installReplay(opts) {
+  var win = opts.win, ctx = opts.ctx;
+  var doc = opts.doc || win.document;
+  ctx.handlers.replay = function () {
+    try { return replay(ctx); } catch (e) {
+      console.error(MESSAGES.replayUnavailable(message(e)));
+      return null;
+    }
+  };
+  var none = { startVanilla: function () {} };
+  if (!ctx.config.replay) return none;
+  try {
+    ctx.replaySrc = replaySrcFor(ctx.scriptSrc, ctx.config.replaySrc);
+  } catch (e) {
+    console.error(MESSAGES.replayUnavailable(message(e)));
+    return none;
+  }
+  var autoSave = ctx.config.replay.autoSave;
+  if (ctx.host === 'vanilla' && autoSave && autoSave.mode && autoSave.mode !== 'none') {
+    console.warn(MESSAGES.replayAutoSaveVanilla());
+  }
+  // With data-debug the summary says it (debug.js), so the page gets one line.
+  if (!ctx.debug && replaySaveReminderApplies(ctx)) console.info(MESSAGES.replaySaveReminder());
+  if (ctx.host === 'jspsych') {
+    ctx.replayProxy = makeReplayProxy({ doc: doc, src: ctx.replaySrc, ctx: ctx, timeoutMs: opts.timeoutMs });
+  }
+
+  var started = false;
+  function start() {
+    createVanillaReplay({ win: win, doc: doc, src: ctx.replaySrc, ctx: ctx, timeoutMs: opts.timeoutMs }).then(
+      function (handle) { ctx.replay = handle; },
+      function (e) { console.error(MESSAGES.replayUnavailable(message(e))); }
+    );
+  }
+  return {
+    startVanilla: function () {
+      if (started) return;
+      started = true;
+      if (doc.readyState === 'loading') doc.addEventListener('DOMContentLoaded', start, { once: true });
+      else start();
+    }
+  };
+}