cyborg-hunter 0.5.0 → 0.7.2

package/src/replay/persistence.js

@@ -0,0 +1,141 @@
+// src/replay/persistence.js
+// Artifact naming, autosave, and the integrityReplayMeta pointer.
+//
+// Delivery semantics are honest by design (design §10): the artifact has the
+// same delivery guarantees as the jsPsych data itself. There is no fallback
+// chain — the configured mode either works or reports saved_to:'failed', and
+// the analyst-facing meta pointer always states what actually happened.
+
+var DATAPIPE_URL = 'https://pipe.jspsych.org/api/data/';
+
+import { sanitizeId } from '../shared/constants.js';
+
+/**
+ * <pid>-replay-<sessionStartEpochMs>.json — the epoch suffix makes reloads
+ * produce distinct artifacts instead of overwriting (CLI picks the latest
+ * and warns on multiples).
+ */
+export function replayFilename(recording) {
+  var pid = sanitizeId(recording.metadata.participant_id);
+  var epoch = Date.parse(recording.metadata.start_time);
+  return pid + '-replay-' + epoch + '.json';
+}
+
+/**
+ * The small pointer that rides along in the jsPsych data (one
+ * addProperties call) so the analyst can tell from the CSV alone whether a
+ * replay exists, how big it was, and where it went.
+ */
+export function buildReplayMeta(recording, savedTo) {
+  return {
+    schema_version: recording.schema_version,
+    tier: recording.metadata.tier,
+    saved_to: savedTo,
+    bytes_uncompressed: JSON.stringify(recording).length,
+    capture_failures: (recording.ch_extensions.capture_failures || [])
+      .map(function (f) { return f.channel; }),
+    capture_stopped: !!recording.ch_extensions.capture_stopped
+  };
+}
+
+/**
+ * Saves the recording using the configured mode. Never throws — failures
+ * come back as { saved_to: 'failed', error } so the experiment's finish
+ * path is never interrupted.
+ *
+ * Modes:
+ *   datapipe — window.jsPsychPipe.saveData if loaded, else a direct POST to
+ *              the DataPipe API. Sends PLAIN JSON (DataPipe stores strings;
+ *              base64-gzip would make the OSF file unreadable for analysts).
+ *   download — synthetic-anchor download (participant's machine!). Useful
+ *              for local piloting; the CLI warns if it sees this in meta.
+ *   none     — recording stays in memory; researcher handles it.
+ */
+export async function autoSave(recording, autoSaveConfig) {
+  var cfg = autoSaveConfig || { mode: 'none' };
+  var filename = replayFilename(recording);
+  var w = typeof window !== 'undefined' ? window : {};
+
+  if (cfg.mode === 'none') {
+    return { saved_to: 'none', filename: filename };
+  }
+
+  if (cfg.mode === 'datapipe') {
+    if (!cfg.experimentId) {
+      return { saved_to: 'failed', filename: filename,
+        error: 'autoSave.mode "datapipe" requires autoSave.experimentId' };
+    }
+    try {
+      // Inside the try: JSON.stringify can throw (circular ref, BigInt) and
+      // this function is contractually never-throw — a serialization failure
+      // must come back as saved_to:'failed', not break the experiment's finish.
+      var json = JSON.stringify(recording);
+      if (w.jsPsychPipe && typeof w.jsPsychPipe.saveData === 'function') {
+        await w.jsPsychPipe.saveData(cfg.experimentId, filename, json);
+      } else {
+        var fetchFn = w.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+        if (!fetchFn) throw new Error('no fetch available for DataPipe POST');
+        var res = await fetchFn(DATAPIPE_URL, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Accept: '*/*' },
+          body: JSON.stringify({
+            experimentID: cfg.experimentId,
+            filename: filename,
+            data: json
+          })
+        });
+        if (res && res.ok === false) throw new Error('DataPipe HTTP error');
+      }
+      return { saved_to: 'datapipe:' + cfg.experimentId + '/' + filename, filename: filename };
+    } catch (e) {
+      console.error('[cyborg-hunter-replay] DataPipe autosave failed:', e);
+      return { saved_to: 'failed', filename: filename,
+        error: e && e.message ? e.message : String(e) };
+    }
+  }
+
+  if (cfg.mode === 'download') {
+    try {
+      var doc = typeof document !== 'undefined' ? document : null;
+      var BlobImpl = w.Blob || (typeof Blob !== 'undefined' ? Blob : null);
+      var urlApi = w.URL || (typeof URL !== 'undefined' ? URL : null);
+      if (!doc || !BlobImpl || !urlApi) throw new Error('download mode needs a browser');
+      var blob = new BlobImpl([JSON.stringify(recording)], { type: 'application/json' });
+      var a = doc.createElement('a');
+      a.href = urlApi.createObjectURL(blob);
+      a.download = filename;
+      doc.body.appendChild(a);
+      a.click();
+      doc.body.removeChild(a);
+      urlApi.revokeObjectURL(a.href);
+      return { saved_to: 'download', filename: filename };
+    } catch (e) {
+      console.error('[cyborg-hunter-replay] download autosave failed:', e);
+      return { saved_to: 'failed', filename: filename,
+        error: e && e.message ? e.message : String(e) };
+    }
+  }
+
+  return { saved_to: 'failed', filename: filename,
+    error: 'unknown autoSave.mode "' + cfg.mode + '"' };
+}
+
+/**
+ * Gzip the recording via CompressionStream when the browser has it;
+ * falls back to a plain-JSON Blob (callers check blob.type).
+ */
+export async function compressRecording(recording) {
+  var json = JSON.stringify(recording);
+  var w = typeof window !== 'undefined' ? window : {};
+  var CS = w.CompressionStream ||
+    (typeof CompressionStream !== 'undefined' ? CompressionStream : null);
+  var BlobImpl = w.Blob || (typeof Blob !== 'undefined' ? Blob : null);
+  if (!BlobImpl) return null;
+  if (!CS) {
+    return new BlobImpl([json], { type: 'application/json' });
+  }
+  var stream = new BlobImpl([json]).stream().pipeThrough(new CS('gzip'));
+  var ResponseImpl = w.Response || (typeof Response !== 'undefined' ? Response : null);
+  var buf = await new ResponseImpl(stream).arrayBuffer();
+  return new BlobImpl([buf], { type: 'application/gzip' });
+}

package/src/replay/recorder.js

@@ -0,0 +1,315 @@
+// src/replay/recorder.js
+// Recorder engine: lifecycle state, event buffer, caps, listener registry.
+//
+// Deliberately DOM-free: it never touches document/window except to read
+// viewport geometry (guarded), so it unit-tests in plain node. Capture
+// modules (capture-trace.js, capture-dom.js) own all DOM listeners and
+// register them here via addListener/addInterval so destroy() can tear
+// everything down in one place. Assembly (singleton + capture wiring +
+// window global) lives in index.js.
+//
+// Time base: every event carries an ABSOLUTE performance.now() `t`. This is
+// the same clock CH core uses, so CH-derived data merges with no conversion;
+// serializer.js converts to ms-since-session-start on the wire.
+
+export const REPLAY_DEFAULTS = {
+  participantId: 'unknown',
+  tier: 'trace',               // 'trace' | 'dom'  (canvas reserved for v0.8)
+  keys: 'full',                // 'full' | 'off'
+  mouseHz: 30,                 // mousemove sampling ceiling
+  redactSelector: '[data-ch-redact]',
+  keepBait: false,             // keep honeypot/decoy nodes in DOM snapshots
+  root: null,                  // capture root; resolved at startSession (default document.body)
+  autoSave: { mode: 'none' },  // 'datapipe' | 'download' | 'none'
+  maxEventsPerTrial: 50000,
+  // Size ceiling per trial, measured in CHARACTERS (JS string length / UTF-16
+  // code units) — an approximate, monotonic proxy for payload size, deliberately
+  // not called "bytes" since UTF-8 byte size can exceed it for non-ASCII content.
+  // The event-count cap alone can't bound a recording that stays under 50k events
+  // but stores multi-megabyte values (a giant textarea edited repeatedly, a large
+  // DOM subtree). The budget covers events AND the initial DOM snapshot. ~8M chars
+  // is far above any normal trial yet bounds a runaway before it breaks the tab or
+  // the DataPipe/localStorage upload. Set null to disable.
+  maxCharsPerTrial: 8000000
+};
+
+// States: created → session ⇄ trial → stopped; destroyed is terminal.
+const VALID = {
+  created:   ['session', 'destroyed'],
+  session:   ['trial', 'stopped', 'destroyed'],
+  trial:     ['session', 'stopped', 'destroyed'],
+  stopped:   ['destroyed'],
+  destroyed: []
+};
+
+export function createRecorder(userConfig) {
+  var config = Object.assign({}, REPLAY_DEFAULTS, userConfig || {});
+  config.autoSave = Object.assign({}, REPLAY_DEFAULTS.autoSave, (userConfig || {}).autoSave || {});
+
+  var state = 'created';
+  var listeners = [];
+  var intervals = [];
+  var trialCounter = 0;
+  var trialStartHooks = [];   // capture modules subscribe (e.g. DOM snapshot)
+  // Running byte estimate for the OPEN trial (reset per trial). Kept off the
+  // serialized trial object (a WeakMap) so it never pollutes the wire payload.
+  var trialChars = new WeakMap();
+  // Trials that hit a per-trial cap. Tracking this per-trial (not via the
+  // session-wide captureStopped flag) means one oversized trial stops only
+  // itself; a subsequent trial captures fresh. captureStopped remains as a
+  // session-level "something was truncated somewhere" signal for the meta.
+  var stoppedTrials = new WeakSet();
+  function estimateEventChars(o) {
+    try { return JSON.stringify(o).length; } catch (e) { return 0; }
+  }
+
+  // The in-memory session buffer. Serialized by serializer.js at the end.
+  var session = {
+    participantId: config.participantId,
+    tier: config.tier,
+    keys: config.keys,
+    sessionStart: null,        // performance.now() at startSession
+    sessionStartEpoch: null,   // Date.now() at startSession (wire metadata + filename)
+    viewport: null,
+    stylesheets: [],           // filled by capture-dom at startSession (tier dom)
+    trials: [],
+    guardViolations: [],       // filled via GuardFriction.onViolation subscription
+    captureFailures: [],
+    captureStopped: false,
+    endReason: null,
+    markerAttr: null           // set by capture-dom (serialization markers)
+  };
+  var currentTrial = null;
+  // Opaque marker registry (capture-dom owns it; capture-trace reads it for
+  // interaction anchors). The recorder never inspects it — staying DOM-free.
+  var markers = null;
+
+  function transition(to) {
+    if (VALID[state].indexOf(to) === -1) {
+      throw new Error(
+        '[cyborg-hunter-replay] invalid lifecycle call: ' + state + ' → ' + to +
+        '. Expected order: attach() → startSession() → (startTrial → endTrial)* → stopSession() → destroy().' +
+        (state === 'created' ? ' Did you forget startSession()?' : '')
+      );
+    }
+    state = to;
+  }
+
+  function newTrial(opts, implicit) {
+    trialCounter++;
+    return {
+      trialIndex: trialCounter - 1,
+      trialId: (opts && opts.trialId) || (implicit ? '__session__' : 'trial-' + (trialCounter - 1)),
+      plugin: (opts && opts.plugin) || 'ch:standalone',
+      implicit: !!implicit,
+      // tLoad is THE trial time origin (see design §10). tStart/tDomReady are
+      // #3661-parity fields; null when the host has no pre-render hook.
+      tLoad: implicit ? session.sessionStart : performance.now(),
+      tStart: (opts && opts.tStart) != null ? opts.tStart : null,
+      tDomReady: (opts && opts.tDomReady) != null ? opts.tDomReady : null,
+      tEnd: null,
+      initialDom: '',
+      events: []
+    };
+  }
+
+  function closeTrial() {
+    currentTrial.tEnd = performance.now();
+    session.trials.push(currentTrial);
+    currentTrial = null;
+  }
+
+  // Fire trial-start subscribers (used by capture-dom for the initial DOM
+  // snapshot). A throwing hook is contained like any capture failure.
+  function fireTrialStart(trial) {
+    for (var i = 0; i < trialStartHooks.length; i++) {
+      try { trialStartHooks[i](trial); } catch (e) {
+        session.captureFailures.push({
+          channel: 'trial_start_hook',
+          message: e && e.message ? String(e.message) : String(e),
+          t: performance.now()
+        });
+      }
+    }
+  }
+
+  var recorder = {
+    config: config,
+
+    startSession: function () {
+      transition('session');
+      session.sessionStart = performance.now();
+      session.sessionStartEpoch = Date.now();
+      // Viewport geometry, if a window exists (absent in node tests).
+      var w = typeof window !== 'undefined' ? window : null;
+      // documentElement.clientWidth/Height = the LAYOUT width the page was
+      // actually formatted against (innerWidth minus any classic scrollbar) —
+      // the viewer sizes its reconstruction by this, not innerWidth.
+      var de = typeof document !== 'undefined' && document.documentElement
+        ? document.documentElement : null;
+      session.viewport = w ? {
+        width: w.innerWidth || null,
+        height: w.innerHeight || null,
+        client_width: de ? de.clientWidth || null : null,
+        client_height: de ? de.clientHeight || null : null,
+        dpr: w.devicePixelRatio || 1,
+        visual_viewport: w.visualViewport ? {
+          width: w.visualViewport.width, height: w.visualViewport.height,
+          scale: w.visualViewport.scale
+        } : null
+      } : { width: null, height: null, client_width: null, client_height: null,
+            dpr: null, visual_viewport: null };
+      if (config.autoSave.mode === 'none') {
+        console.warn('[cyborg-hunter-replay] autoSave.mode is "none" — the recording will be lost unless you call getRecording() yourself.');
+      }
+    },
+
+    startTrial: function (opts) {
+      if (state === 'trial') {
+        // Standalone users may forget endTrial(); auto-close so events never
+        // bleed across trials, and leave an auditable marker.
+        this.pushEvent('ch:lifecycle_error', { reason: 'startTrial_without_endTrial' });
+        closeTrial();
+        state = 'session';
+      } else if (currentTrial) {
+        // An implicit trial is open (session-scoped events arrived before
+        // the first explicit startTrial — e.g. a guard violation during the
+        // instructions screen). Close it; overwriting currentTrial would
+        // orphan those events. This is the NORMAL path, not an error.
+        closeTrial();
+      }
+      transition('trial');
+      currentTrial = newTrial(opts, false);
+      fireTrialStart(currentTrial);
+    },
+
+    endTrial: function () {
+      transition('session');
+      if (currentTrial) closeTrial();
+    },
+
+    stopSession: function (reason) {
+      if (state === 'trial') {
+        state = 'session';
+      }
+      // Close whatever trial is open — explicit (state was 'trial') or
+      // implicit (state 'session' with a lazily-opened trial).
+      if (currentTrial) closeTrial();
+      transition('stopped');
+      session.endReason = reason || 'finished';
+    },
+
+    // Central event sink used by all capture modules.
+    // Events land in the current trial; unbracketed events lazily open a
+    // single implicit trial that spans the session (design §5).
+    pushEvent: function (kind, payload, tOverride) {
+      if (state === 'destroyed') {
+        throw new Error('[cyborg-hunter-replay] pushEvent called on a destroyed recorder');
+      }
+      if (state === 'created' || state === 'stopped') return; // not recording
+      if (!currentTrial) {
+        currentTrial = newTrial(null, true);
+        fireTrialStart(currentTrial);
+      }
+      // Per-trial stop (not the session-wide flag): a trial that already hit a
+      // cap drops further events, but a fresh trial is unaffected.
+      if (stoppedTrials.has(currentTrial)) return;
+      if (currentTrial.events.length >= config.maxEventsPerTrial) {
+        stoppedTrials.add(currentTrial);
+        session.captureStopped = true;
+        currentTrial.events.push({
+          t: tOverride != null ? tOverride : performance.now(),
+          kind: 'ch:capture_stopped',
+          limit: config.maxEventsPerTrial
+        });
+        return;
+      }
+      var e = Object.assign(
+        { t: tOverride != null ? tOverride : performance.now(), kind: kind },
+        payload || {});
+      // Size cap: stop capturing once the trial's estimated serialized length
+      // exceeds maxCharsPerTrial, so a few huge values can't blow up the payload
+      // while staying under the event-count cap. The budget is SEEDED with the
+      // initial DOM snapshot (stored on the trial, not pushed as an event) so a
+      // multi-megabyte snapshot counts too rather than bypassing the cap.
+      if (config.maxCharsPerTrial != null) {
+        var soFar = trialChars.get(currentTrial);
+        if (soFar == null) {
+          soFar = currentTrial.initialDom ? currentTrial.initialDom.length : 0;
+        }
+        soFar += estimateEventChars(e);
+        if (soFar > config.maxCharsPerTrial) {
+          stoppedTrials.add(currentTrial);
+          session.captureStopped = true;
+          currentTrial.events.push({
+            t: e.t, kind: 'ch:capture_stopped', limit_chars: config.maxCharsPerTrial
+          });
+          return;
+        }
+        trialChars.set(currentTrial, soFar);
+      }
+      currentTrial.events.push(e);
+    },
+
+    // Capture-channel failure: record and keep going. Recording must never
+    // break an experiment (design §6).
+    captureFailure: function (channel, err) {
+      session.captureFailures.push({
+        channel: channel,
+        message: err && err.message ? String(err.message) : String(err),
+        t: performance.now()
+      });
+    },
+
+    onTrialStart: function (fn) {
+      trialStartHooks.push(fn);
+    },
+
+    setStylesheets: function (sheets) {
+      session.stylesheets = sheets || [];
+    },
+
+    // Marker registry passthrough (opaque — see comment on `markers` above).
+    setMarkers: function (reg) { markers = reg; },
+    getMarkers: function () { return markers; },
+    setMarkerAttr: function (attr) { session.markerAttr = attr || null; },
+
+    // Listener/interval registry — single teardown point.
+    addListener: function (target, event, handler, options) {
+      target.addEventListener(event, handler, options || false);
+      listeners.push({ target: target, event: event, handler: handler, options: options || false });
+    },
+
+    addInterval: function (id) {
+      intervals.push(id);
+    },
+
+    // Read-only view for serializer + tests. Trials array includes the open
+    // trial so mid-session getRecording() sees everything so far.
+    // Deliberately readable AFTER destroy(): the buffer survives teardown
+    // (only capture stops), mirroring CH core's getSessionReport contract —
+    // destroy-then-serialize returns complete data instead of losing it.
+    getState: function () {
+      var trials = session.trials.slice();
+      if (currentTrial) trials.push(currentTrial);
+      return Object.assign({}, session, { trials: trials, state: state });
+    },
+
+    destroy: function () {
+      if (state === 'destroyed') return;
+      transition('destroyed');
+      listeners.forEach(function (l) {
+        if (l.options && l.options._isObserver) {
+          l.handler.disconnect();
+        } else {
+          l.target.removeEventListener(l.event, l.handler, l.options);
+        }
+      });
+      listeners = [];
+      intervals.forEach(function (id) { clearInterval(id); });
+      intervals = [];
+    }
+  };
+
+  return recorder;
+}

package/src/replay/serializer.js

@@ -0,0 +1,119 @@
+// src/replay/serializer.js
+// In-memory recorder state → SessionRecording v1 (jsPsych PR #3661 wire
+// format) with a ch_extensions namespace for CH-only data.
+//
+// This is one of exactly two places in the system that convert time bases
+// (the other is the CLI ingest): in-memory events carry absolute
+// performance.now() values; the wire carries ms-since-session-start.
+
+import { VERSION } from '../shared/constants.js';
+
+// Convert an absolute performance.now() value to wire time (ms since
+// session start), rounded to 1 decimal to keep JSON compact.
+function wireT(t, sessionStart) {
+  if (t == null) return null;
+  return Math.round((t - sessionStart) * 10) / 10;
+}
+
+// Session-scoped CH arrays whose entries carry absolute `t` — converted to
+// session-relative on the way into ch_extensions.
+function convertTimes(entries, sessionStart) {
+  return (entries || []).map(function (e) {
+    var out = Object.assign({}, e);
+    if (typeof out.t === 'number') out.t = wireT(out.t, sessionStart);
+    if (typeof out.start === 'number') out.start = wireT(out.start, sessionStart);
+    return out;
+  });
+}
+
+/**
+ * @param {Object} state - recorder.getState() output
+ * @param {Object} opts - { chSessionReport } — pull-model CH merge; the
+ *   caller (jsPsych adapter or researcher) provides CH's session report,
+ *   the serializer never reaches into CH itself.
+ */
+export function serialize(state, opts) {
+  opts = opts || {};
+  var s0 = state.sessionStart;
+  if (s0 == null) {
+    throw new Error('[cyborg-hunter-replay] cannot serialize before startSession() — call startSession() first, or the timestamps would be meaningless (Unix epoch).');
+  }
+  var ch = opts.chSessionReport || null;
+
+  var lastT = s0;
+  var trials = state.trials.map(function (trial) {
+    var events = trial.events.slice().sort(function (a, b) { return a.t - b.t; });
+    var lastEventT = events.length > 0 ? events[events.length - 1].t : trial.tLoad;
+    if (lastEventT > lastT) lastT = lastEventT;
+    return {
+      trial_index: trial.trialIndex,
+      trial_id: trial.trialId,
+      plugin: trial.plugin,
+      // t_load is the trial time origin (design §10). t_start/t_dom_ready are
+      // #3661-parity fields, null when the host has no pre-render hook.
+      t_start: wireT(trial.tStart, s0),
+      t_dom_ready: wireT(trial.tDomReady, s0),
+      t_load: wireT(trial.tLoad, s0),
+      // A trial still open at serialization time (tab closed, mid-session
+      // getRecording) ends at its last observed event.
+      t_end: wireT(trial.tEnd != null ? trial.tEnd : lastEventT, s0),
+      // Scroll/viewport state at trial start — the viewer's camera seed.
+      // Times inside are absolute-free (plain state), so no conversion.
+      view_state: trial.viewState || null,
+      initial_dom: trial.initialDom || '',
+      events: events.map(function (e) {
+        var out = Object.assign({}, e);
+        out.t = wireT(e.t, s0);
+        return out;
+      }),
+      trial_data: {}
+    };
+  });
+
+  var chExtensions = {
+    replay_version: VERSION,
+    // Serialization-marker attribute name (per-recording nonce); the viewer
+    // harvests these markers out of the reconstructed DOM for stable
+    // mutation/anchor resolution. Null on trace-tier or legacy recordings.
+    marker_attr: state.markerAttr || null,
+    ch_version: ch ? (ch.libraryVersion || null) : null,
+    preset: ch && ch.config ? ch.config.preset : null,
+    scoring: ch ? {
+      hard_score: ch.hardScore || {},
+      soft_score: ch.softScore != null ? ch.softScore : null,
+      soft_score_threshold: ch.softScoreThreshold != null ? ch.softScoreThreshold : null,
+      any_hard_triggered: !!ch.anyHardTriggered,
+      trials_completed: ch.trialsCompleted != null ? ch.trialsCompleted : null
+    } : null,
+    session_signals: ch ? {
+      sidebar_events: convertTimes(ch.sidebarEvents, s0),
+      ai_extensions_found: convertTimes(ch.aiExtensionsFound, s0),
+      devtools_events: convertTimes(ch.devToolsEvents, s0),
+      window_positions: convertTimes(ch.windowPositions, s0),
+      layout_shifts: convertTimes(ch.layoutShifts, s0),
+      zoom_changes: convertTimes(ch.zoomChanges, s0),
+      extension_injections: convertTimes(ch.extensionInjections, s0)
+    } : null,
+    guard_violations: convertTimes(state.guardViolations, s0),
+    capture_failures: convertTimes(state.captureFailures, s0),
+    capture_stopped: !!state.captureStopped
+  };
+
+  return {
+    schema_version: 1,
+    metadata: {
+      start_time: new Date(state.sessionStartEpoch).toISOString(),
+      end_time: new Date(state.sessionStartEpoch + Math.max(0, Math.round(lastT - s0))).toISOString(),
+      end_reason: state.endReason || 'aborted',
+      participant_id: state.participantId,
+      recorder: 'cyborg-hunter-replay@' + VERSION,
+      tier: state.tier,
+      keys: state.keys
+    },
+    viewport: state.viewport,
+    stylesheets: { initial: state.stylesheets || [], events: [] },
+    rng_calls: [],   // shape parity with #3661; CH never re-executes code
+    trials: trials,
+    ch_extensions: chExtensions
+  };
+}