cyborg-hunter 0.9.2 → 0.10.0

package/src/oneliner/segment-diff.js

@@ -0,0 +1,68 @@
+// src/oneliner/segment-diff.js
+// Turns the monitor's cumulative session report into per-segment deltas.
+// The session arrays are append-only (every write in src/core is a .push), so
+// "what happened since the last cut" is report[key].slice(lastSeen[key]).
+// Keys are discovered at every cut, not fixed at build time, so a signal added
+// to the core later flows through without touching this file.
+//
+// createSegmentDiffer(monitor) → { cut(meta) → segment, seen() → {[key]: number} }
+//   monitor: anything with getSessionReport() and getSessionScore()
+//   meta: { segmentIndex, source: 'manual'|'host'|'page'|'final', trialId,
+//           pageOrigin, trialReport?, gapReports? }
+//   segment: { segmentIndex, source, trialId, pageOrigin,
+//              deltas: { [arrayKey]: any[] },   // every array key except aliases
+//              counters: { pasteCount, copyCount, dropCount },
+//              score: getSessionScore() verbatim,
+//              gap?: [...],                     // non-empty gap reports only
+//              config?, libraryVersion? }       // segmentIndex === 0 only
+//
+// The CLI side (src/cli/segment-reassembly.js) concatenates the deltas back
+// into the session shape finalize() dumps.
+
+// Keys that are the same array as another key inside the monitor (monitor.js
+// keeps layoutShifts as a deprecated alias of viewportWidthShifts). Skipped on
+// the way out so the entries are not shipped twice; restored on the way in
+// (src/cli/segment-reassembly.js keeps a copy; a test pins the two equal).
+export const ALIAS_KEYS = { layoutShifts: 'viewportWidthShifts' };
+
+export function createSegmentDiffer(monitor) {
+  var lastSeen = {};
+  function arrayKeys(report) {
+    return Object.keys(report).filter(function (k) {
+      return Array.isArray(report[k]) && !(k in ALIAS_KEYS);
+    });
+  }
+  // A gap report covers the time between two host trials. Most are empty;
+  // only those with paste/copy/drop/synthetic-insertion evidence are kept,
+  // and only those four arrays plus the duration (no mouse trace).
+  function nonEmptyGap(r) {
+    var keys = ['pasteEvents', 'copyEvents', 'dropEvents', 'syntheticInsertions'];
+    var any = keys.some(function (k) { return Array.isArray(r[k]) && r[k].length > 0; });
+    if (!any) return null;
+    var out = { duration_ms: r.duration_ms };
+    keys.forEach(function (k) { out[k] = r[k] || []; });
+    return out;
+  }
+  return {
+    seen: function () { return Object.assign({}, lastSeen); },
+    cut: function (meta) {
+      var report = monitor.getSessionReport();   // one deep copy per cut (monitor.js getSessionReport); O(session size)
+      var deltas = {};
+      arrayKeys(report).forEach(function (k) {
+        var from = lastSeen[k] || 0;
+        deltas[k] = report[k].slice(from);
+        lastSeen[k] = report[k].length;
+      });
+      var seg = {
+        segmentIndex: meta.segmentIndex, source: meta.source, trialId: meta.trialId, pageOrigin: meta.pageOrigin,
+        deltas: deltas,
+        counters: { pasteCount: report.pasteCount, copyCount: report.copyCount, dropCount: report.dropCount },
+        score: monitor.getSessionScore()
+      };
+      var gaps = (meta.gapReports || []).map(nonEmptyGap).filter(Boolean);
+      if (gaps.length) seg.gap = gaps;
+      if (meta.segmentIndex === 0) { seg.config = report.config; seg.libraryVersion = report.libraryVersion; }
+      return seg;
+    }
+  };
+}

package/src/oneliner/segmenter.js

@@ -0,0 +1,186 @@
+// src/oneliner/segmenter.js
+// Keeps the monitor permanently inside a trial. The core attaches its paste,
+// typing, mouse, idle-gap and element-trace listeners only between startTrial
+// and endTrial (monitor.js startTrial), so a paste outside a trial is never
+// recorded. The one-line setup therefore opens a span at boot and, at every
+// boundary, closes the current trial and opens the next one in the same call.
+//
+// createSegmenter({ monitor, differ, clock, sourceDefault }) → {
+//   start({ trialId })          open the boot span; no-op if already open
+//                               → null | { error }
+//   rotate(opts)                close the span (a "gap"), open the host's trial;
+//                               no segment; the gap report is buffered for the
+//                               next cut() and also returned
+//                               → gapReport | null (nothing was open) | { error }
+//   cut({ source, nextTrialId?, nextOpts? })   close + segment + open next
+//                               → { segment, trialReport }          success
+//                               → { segment, trialReport, error }   cut OK, reopen failed
+//                               → { error }                         nothing was cut
+//   finish({ source })          close + segment, nothing reopened
+//                               → { segment, trialReport } | null (closed) | { error }
+//   abandon()                   close without a segment (manual-mode hand-over)
+//                               → null | { error }
+//   state()                     { open, segmentIndex, currentTrialId }
+//   setSegmentIndex(n)          multi-page restore
+// }
+//   differ: createSegmentDiffer(monitor) (src/oneliner/segment-diff.js)
+//   clock:  () => number, the page origin (performance.timeOrigin); injectable
+//
+// Contract for the host adapters: a result with `segment` must be saved even
+// when it also carries `error` (the data is complete; only the next span failed
+// to open, and the error becomes the cyborgHunterError marker). A result with
+// `error` alone means nothing was cut.
+//
+// None of these throws into the host: a monitor or differ failure is logged
+// and returned as { error: message }. After finish() or abandon() the segmenter
+// is latched: start/rotate/cut return { error: 'finished' | 'abandoned' }
+// without touching the monitor, and finish() returns null.
+//
+// Keeping `open` true to the monitor. The monitor has no state getter, but
+// transition() is the FIRST statement of both startTrial and endTrial
+// (monitor.js), and its rejection message names the current state. So:
+//   - any endTrial throw leaves the monitor outside a trial (rejected, or
+//     already transitioned) → open = false;
+//   - a startTrial throw that is not a lifecycle rejection means the
+//     transition happened → the trial IS open (listeners maybe partly
+//     attached) → open = true, so cut()/finish() still segment it rather than
+//     drop it, and endTrial's removeTrialListeners cleans up whatever attached;
+//   - a startTrial rejected "from 'trial'" means a trial we thought closed is
+//     still open → close it, keep its report as a gap, and retry once.
+
+// Mirrors the message thrown by monitor.js transition(); null when `e` is not
+// a lifecycle rejection.
+var LIFECYCLE_FROM = /invalid lifecycle call: cannot transition from '(\w+)'/;
+function lifecycleFrom(e) {
+  var m = LIFECYCLE_FROM.exec(String((e && e.message) || e));
+  return m ? m[1] : null;
+}
+
+export function createSegmenter(opts) {
+  var monitor = opts.monitor;
+  var differ = opts.differ;
+  var clock = opts.clock || function () { return performance.timeOrigin; };
+  var sourceDefault = opts.sourceDefault || 'host';
+
+  var open = false;
+  var latched = null;    // 'finished' | 'abandoned': the segmenter no longer drives the monitor
+  var segmentIndex = 0;
+  var currentTrialId = null;
+  var gapReports = [];   // gap trial reports since the last cut
+
+  function fail(what, e) {
+    var message = String((e && e.message) || e);
+    console.error('[cyborg-hunter] ' + what + ' failed: ' + message);
+    return { error: message };
+  }
+
+  // A span the host did not name is called after the segment it will become.
+  function spanId() { return 'span-' + segmentIndex; }
+
+  function closeTrial() {
+    try { return monitor.endTrial(); }
+    finally { open = false; }
+  }
+
+  // The explicit trialId always wins: it is assigned last, so a trialId inside
+  // `extra` (nextOpts, rotate's opts) can never rename the span.
+  function openTrial(trialId, extra) {
+    var args = Object.assign({}, extra || {}, { trialId: trialId });
+    try {
+      monitor.startTrial(args);
+    } catch (e) {
+      var from = lifecycleFrom(e);
+      if (from === 'trial') {
+        gapReports.push(closeTrial());
+        monitor.startTrial(args);
+      } else {
+        if (from === null) { currentTrialId = trialId; open = true; }
+        throw e;
+      }
+    }
+    currentTrialId = trialId;
+    open = true;
+  }
+
+  // Close the open trial and turn everything since the last cut into a segment.
+  function closeAndSegment(source) {
+    var report = closeTrial();
+    var segment = differ.cut({
+      segmentIndex: segmentIndex, source: source, trialId: currentTrialId,
+      pageOrigin: clock(), trialReport: report, gapReports: gapReports
+    });
+    gapReports = [];
+    segmentIndex += 1;
+    return { segment: segment, trialReport: report };
+  }
+
+  return {
+    start: function (o) {
+      if (latched) return { error: latched };
+      if (open) return null;
+      try {
+        openTrial((o && o.trialId) || spanId());
+        return null;
+      } catch (e) { return fail('start', e); }
+    },
+
+    rotate: function (o) {
+      if (latched) return { error: latched };
+      o = o || {};
+      var gap = null;
+      try {
+        if (open) {
+          gap = closeTrial();
+          gapReports.push(gap);
+        }
+      } catch (e) { return fail('trial rotation', e); }
+      var extra = Object.assign({}, o);
+      delete extra.trialId;
+      try {
+        openTrial(o.trialId || spanId(), extra);
+      } catch (e) { return fail('trial rotation', e); }   // the gap, if any, stays buffered
+      return gap;
+    },
+
+    cut: function (o) {
+      if (latched) return { error: latched };
+      o = o || {};
+      var out;
+      try {
+        out = closeAndSegment(o.source || sourceDefault);
+      } catch (e) { return fail('segment write', e); }
+      try {
+        openTrial(o.nextTrialId || spanId(), o.nextOpts);
+      } catch (e) { out.error = fail('trial reopen', e).error; }
+      return out;
+    },
+
+    finish: function (o) {
+      if (latched) return null;
+      latched = 'finished';
+      if (!open) return null;
+      try {
+        return closeAndSegment((o && o.source) || 'final');
+      } catch (e) { return fail('segment write', e); }
+    },
+
+    // Hands the monitor to the host (manual mode). Gap reports still buffered
+    // are intentionally discarded: no cut() follows, and the abandoned spans
+    // carry no host trial to attach them to.
+    abandon: function () {
+      if (latched) return null;
+      latched = 'abandoned';
+      if (!open) return null;
+      try {
+        closeTrial();
+        return null;
+      } catch (e) { return fail('abandon', e); }
+    },
+
+    state: function () {
+      return { open: open, segmentIndex: segmentIndex, currentTrialId: currentTrialId };
+    },
+
+    setSegmentIndex: function (n) { segmentIndex = n; }
+  };
+}

package/src/replay/recorder.js

@@ -360,7 +360,11 @@ export function createRecorder(userConfig) {
         ? { w: de.clientWidth || 0, h: de.clientHeight || 0 } : null;
       session.userAgent = typeof navigator !== 'undefined' && navigator.userAgent
         ? String(navigator.userAgent) : '';
-      if (config.autoSave.mode === 'none') {
+      // _ownerSavesRecording (internal): the embedding library takes the
+      // recording itself and tells its user how to save it (the one-line
+      // setup's CyborgHunter.replay(), src/oneliner/replay-loader.js), so
+      // this warning, which names getRecording(), would only mislead there.
+      if (config.autoSave.mode === 'none' && !config._ownerSavesRecording) {
         console.warn('[cyborg-hunter-replay] autoSave.mode is "none" — the recording will be lost unless you call getRecording() yourself.');
       }
     },

package/src/shared/constants.js

@@ -2,7 +2,7 @@
 // Default thresholds and preset configurations for Cyborg Hunter.
 // Single source of truth — used by both the browser library and CLI report tool.
 
-export const VERSION = "0.9.2";
+export const VERSION = "0.10.0";
 
 // Default detection thresholds shared across presets.
 // Researchers can override any value at init() time.