cyborg-hunter 0.7.4 → 0.8.0

package/src/replay/node-registry.js

@@ -0,0 +1,116 @@
+// src/replay/node-registry.js
+// Node-ID registry for the v2 recording format. Pure — no imports, no DOM
+// APIs — so it runs identically in the browser, in node tests against
+// fake-DOM fixtures, and (later) inside the shared engine.
+//
+// Spec §4: every node in a recording carries an integer id; ids are scoped to
+// a KEYFRAME SPAN (a keyframe segment plus its continuation segments) and are
+// assigned in first-seen pre-order, restarting at 1 at each keyframe. The
+// snapshot walk numbers the tree; mid-span `dom.add` subtrees continue the
+// same counter (canonical-core pins ids 6,7 after a 5-node keyframe).
+//
+// Identity, not content: a WeakMap keyed by the LIVE node object. Nothing is
+// stamped into the DOM (the v1 nonce-marker attribute mechanism, which had to
+// dodge its own MutationObserver echo, is retired by this module), and a
+// dropped span's entries become garbage-collectable the moment resetSpan()
+// releases the map.
+
+/**
+ * Create a node-ID registry for one keyframe span.
+ *
+ * @returns {{
+ *   idFor: (node: object) => number,
+ *   assignTree: (root: object) => number,
+ *   peekId: (node: object) => number | null,
+ *   resetSpan: () => void,
+ *   count: number
+ * }}
+ */
+export function createRegistry() {
+  let ids = new WeakMap();
+  let nextId = 1;
+
+  // Assign-if-absent for a SINGLE node (no descendant walk). In normal
+  // operation every node of the observed tree is numbered by assignTree
+  // first — snapshot walk at the keyframe, dom.add walks mid-span — so this
+  // is the fallback path for a node that WILL be serialized but has not been
+  // walked yet.
+  //
+  // NOT the way to resolve an event target or anchor: use peekId there. A
+  // target outside the observed root must resolve to null (design §2), and
+  // minting an id for it would put a number in the file that names nothing in
+  // the player's tree. dom.remove (Task 3) and anchors (Task 5) are peekId
+  // callers for the same reason.
+  //
+  // ids.set BEFORE the counter advances, so a call that throws (a non-object
+  // node) burns no id and leaves the span's numbering intact.
+  function idFor(node) {
+    const existing = ids.get(node);
+    if (existing !== undefined) return existing;
+    ids.set(node, nextId);
+    return nextId++;
+  }
+
+  // Pre-order walk: root, then each child's whole subtree, left to right.
+  // Numbers EVERY node the DomNode serialization can emit — elements, text,
+  // comments — because spec §4 gives all three an id.
+  //
+  // Boundary: the registry numbers whatever tree it is handed. Exclusion
+  // (data-record-exclude placeholders) and redaction filtering are the
+  // SERIALIZER's concern (Task 2); an excluded element still occupies its
+  // position and still needs an id, and the serializer decides what of the
+  // subtree reaches the file. Keeping the walk unconditional means ids stay
+  // stable regardless of what the serializer later chooses to emit.
+  //
+  // Precondition for the fixture's tidy 1..N numbering: the keyframe snapshot
+  // walk must be the FIRST allocation after each resetSpan(). Spec §4 only
+  // demands unique first-seen ids, and this registry stays correct either way
+  // (an idFor between reset and snapshot just shifts the tree to 2..N+1), but
+  // the canonical-core keyframe reads 1..5 only because nothing allocates
+  // ahead of its walk. Callers: reset, then snapshot, then everything else.
+  function assignTree(root) {
+    const rootId = idFor(root);
+    const children = root.childNodes;
+    if (children) {
+      for (let i = 0; i < children.length; i++) assignTree(children[i]);
+    }
+    return rootId;
+  }
+
+  // Read-only lookup: never allocates. Used wherever minting an id would be
+  // wrong rather than merely early — `dom.remove` targets, event anchors —
+  // because a fresh id there names a node the player was never sent.
+  //
+  // What it does NOT tell you: a non-null id does not mean the player has the
+  // node. assignTree numbers unconditionally, so descendants of a
+  // data-record-exclude placeholder, script/noscript elements the serializer
+  // skips, and anything numbered by an idFor fallback outside the observed
+  // root all peek non-null while appearing nowhere in the file. Strict
+  // validation only number-checks `node` fields, so a dangling reference
+  // survives validation and shows up as broken replay. Resolving a hit up to
+  // the nearest EMITTED ancestor (the placeholder, per spec §4) is the
+  // caller's job — this function answers "was it numbered", not "was it sent".
+  function peekId(node) {
+    const id = ids.get(node);
+    return id === undefined ? null : id;
+  }
+
+  // Keyframe boundary: drop the whole span's assignments and restart at 1.
+  // A fresh WeakMap rather than per-entry deletion — the old map is simply
+  // released along with the span it described.
+  function resetSpan() {
+    ids = new WeakMap();
+    nextId = 1;
+  }
+
+  return {
+    idFor,
+    assignTree,
+    peekId,
+    resetSpan,
+    // Ids are handed out only by the counter, one per node, so the number
+    // assigned in this span is always nextId − 1 — no second tally to keep in
+    // sync. A getter (not a snapshot property) so callers read it live.
+    get count() { return nextId - 1; },
+  };
+}

package/src/replay/persistence.js

@@ -10,14 +10,21 @@ var DATAPIPE_URL = 'https://pipe.jspsych.org/api/data/';
 
 import { sanitizeId } from '../shared/constants.js';
 
+// The CH vendor namespace of a v2 recording (spec §9), where `metadata.tier`
+// and the `ch_extensions` diagnostics moved.
+function chExt(recording) {
+  var ext = recording && recording.extensions;
+  return (ext && ext['cyborg-hunter']) || {};
+}
+
 /**
- * <pid>-replay-<sessionStartEpochMs>.json — the epoch suffix makes reloads
+ * <pid>-replay-<recordingStartEpochMs>.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);
+  var pid = sanitizeId(recording.participant_id);
+  var epoch = Date.parse(recording.recording_started_at);
   return pid + '-replay-' + epoch + '.json';
 }
 
@@ -25,16 +32,22 @@ export function replayFilename(recording) {
  * 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.
+ *
+ * The OUTPUT shape is a stable contract with the CLI ingest and the HTML index
+ * (they read these six keys); only where the values are read FROM moved to v2.
  */
 export function buildReplayMeta(recording, savedTo) {
+  var ext = chExt(recording);
   return {
     schema_version: recording.schema_version,
-    tier: recording.metadata.tier,
+    tier: ext.tier != null ? ext.tier : null,
     saved_to: savedTo,
     bytes_uncompressed: JSON.stringify(recording).length,
-    capture_failures: (recording.ch_extensions.capture_failures || [])
+    capture_failures: (ext.capture_failures || [])
       .map(function (f) { return f.channel; }),
-    capture_stopped: !!recording.ch_extensions.capture_stopped
+    // Spec §5.7's standard flag, which mirrors the vendor one; reading the
+    // standard field keeps the pointer honest for any v2 producer.
+    capture_stopped: !!recording.truncated
   };
 }