cyborg-hunter 0.9.1 → 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/dom-instantiate.js

@@ -616,7 +616,7 @@ function mountTree(domNode, body, doc) {
 //
 // TOLERANT, COUNTED, SURFACED (design §4). A patch naming an id the map does
 // not hold is skipped and counted into `patchFailures`, never thrown on. This
-// is a DELIBERATE divergence from `tests/replay/support/dom-player.js`, which
+// is a DELIBERATE divergence from `packages/sessionrecording-conformance/src/fuzz/dom-player.js`, which
 // throws on the same input: the test player's job is to catch mapper bugs, the
 // viewer's job is to show an analyst as much of an unrepeatable session as
 // survives. The consequence is recorded and routed — a tolerant viewer cannot
@@ -715,6 +715,15 @@ function applyAttr(patch, mount) {
     el.removeAttribute(name);
     return;
   }
+  // An iframe placeholder never receives the IFRAME_SKIP names after mount
+  // either, or a later patch could re-arm what instantiation disarmed. The
+  // marker is viewer-owned on both verbs, so a recording can neither forge nor
+  // strip it, and checking it here is checking what instantiation decided.
+  // Silent and uncounted, like the viewer-owned refusals. Defence in depth:
+  // the viewer's `frame-src 'none'` CSP already blocks the load. SET verb
+  // only — the placeholder carries no label a removal could strip.
+  if (el.getAttribute(PLACEHOLDER_ATTR) === 'iframe'
+      && IFRAME_SKIP[name.toLowerCase()] === true) return;
   // ONE §12 gate on the set path, and it is the gate instantiation uses, so a
   // keyframe and a patch can never disagree about what an element may carry.
   setFilteredAttr(el, name, patch.value, mount);

package/src/replay/index.js

@@ -181,7 +181,9 @@ export function attach(userConfig) {
 export { replayFilename, buildReplayMeta, serialize };
 
 // Browser global — same pattern as the guard extensions (explicit window
-// assignment; no esbuild globalName).
+// assignment; no esbuild globalName). replayFilename rides along so a
+// researcher saving the recording to their own server names it exactly as
+// the CLI expects (sanitized participant id), without an ES import.
 if (typeof window !== 'undefined') {
-  window.CyborgHunterReplay = { attach: attach };
+  window.CyborgHunterReplay = { attach: attach, replayFilename: replayFilename };
 }

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.1";
+export const VERSION = "0.10.0";
 
 // Default detection thresholds shared across presets.
 // Researchers can override any value at init() time.

package/src/shared/schema-v2-validator.js

@@ -1,6 +1,11 @@
+// GENERATED from packages/sessionrecording-conformance/src/validator.js — do not edit; run npm run sync:conformance
+//
+// The conformance package is the source of truth. CH ships this copy so the
+// published tarball can validate without resolving a workspace package.
+
 // SessionRecording v2 validator — dual profiles per spec §11.
-// Zero dependencies. Lifted from tests/replay/schema-v2/ into shipped code (A3 fix
-// round): ingest strict-validates converted recordings in-process (spec §11 A2 —
+// Zero dependencies. Lifted from tests/replay/schema-v2/ into shipped code:
+// ingest strict-validates converted recordings in-process (spec §11 A2 —
 // warn, never refuse), so the validator is a runtime dependency of the CLI.
 
 // Gzip magic bytes (RFC 1952): 0x1f 0x8b.
@@ -50,8 +55,8 @@ export function validateTolerant(input) {
   }
   if (errors.length) return { ok: false, recording: null, errors, warnings };
   for (const k of ADVISORY_TOP) if (!(k in obj)) warnings.push(`missing advisory field: ${k}`);
-  // WARN ON MALFORMED KNOWN FIELDS — WARN, NEVER COERCE (T7 settles this; it
-  // was parked from two reviews). Before this, a present-but-malformed known
+  // WARN ON MALFORMED KNOWN FIELDS — WARN, NEVER COERCE (settled here after
+  // being parked from two reviews). Before this, a present-but-malformed known
   // field (`stylesheets: null`, `truncated: "yes"`) passed through in total
   // silence: defaults fill ABSENT keys only, and the analyst opening the file
   // got no signal at all. Coercing is the wrong repair — overwriting
@@ -253,8 +258,8 @@ export function validateStrict(input) {
     errors.push('end_reason must be "finished" | "aborted" | "unload" | null');
   }
   if (typeof r.truncated !== 'boolean') errors.push('truncated must be a boolean');
-  // `host` appeared ONCE in this file before T7 — in TOP_DEFAULTS — so
-  // `host: {name: 42}` was strict-valid (T3 Task-7).
+  // `host` used to appear ONCE in this file — in TOP_DEFAULTS — so
+  // `host: {name: 42}` was strict-valid.
   if (r.host !== null && !(isPlainObject(r.host)
       && typeof r.host.name === 'string' && typeof r.host.version === 'string')) {
     errors.push('host must be {name, version} strings or null');
@@ -383,7 +388,7 @@ export const REDACTABLE_TYPES = new Set([
   'clipboard.copy', 'clipboard.cut', 'clipboard.paste', 'clipboard.drop',
 ]);
 
-// ── §5.3 clipboard: REQUIRED-BUT-NULLABLE, settled here (T7) ───────────────
+// ── §5.3 clipboard: REQUIRED-BUT-NULLABLE, settled here ────────────────────
 // The parked question was whether §5.3's four fields are required-but-nullable
 // or typed-only-if-present. Settled as REQUIRED, for one reason that is not
 // about strictness for its own sake: §5.3 defines its TWO PRODUCER MODES by
@@ -484,8 +489,8 @@ function checkSegmentsStrict(r, errors) {
     if (s.initial_dom != null && !isKeyframe) {
       errors.push(`${at}.initial_dom must be a DomNode object or null`);
     }
-    // The keyframe tree itself, recursively (spec §4). Until T7 the validator
-    // stopped at "is an object": a keyframe whose children were strings, or
+    // The keyframe tree itself, recursively (spec §4). The validator used to
+    // stop at "is an object": a keyframe whose children were strings, or
     // whose ids were absent, was strict-valid and only failed inside a player.
     if (isKeyframe) checkDomNode(s.initial_dom, `${at}.initial_dom`, errors, 1);
     if (isKeyframe) sawKeyframe = true;