cyborg-hunter 0.7.4 → 0.8.0

package/src/replay/capture-dom.js

@@ -1,413 +1,231 @@
 // src/replay/capture-dom.js
-// Tier-2 ("dom") capture: initial-DOM serialization, MutationObserver →
-// patch log, initial stylesheet capture, guard-friction pre-scramble hook.
+// Tier-2 ("dom") capture, wired to the v2 node-tree pipeline: keyframe
+// snapshots (snapshot.js), MutationObserver batches → `dom.*` patches
+// (mutations.js), the `initial_state` seed (initial-state.js), initial
+// stylesheet capture, and the guard-friction pre-scramble hook.
 //
-// The serializer is a hand-rolled tree walker (clean-room; no dependency on
-// outerHTML) so it can (a) strip/redact during the walk and (b) run against
-// duck-typed fixture trees in node tests.
+// This module owns no serialization logic of its own any more. It is the
+// WIRING: what the observed root is, when a keyframe is taken, which span the
+// ids come from, and how a batch reaches the recorder. Everything it used to
+// do by hand is now a shared, separately tested module — which is the point:
+// the keyframe and the patches that address it must agree about exclusion,
+// redaction and node identity, and the only way to guarantee that is for both
+// to run the same code.
 //
-// Node addressing: a path is the list of childNodes indices from the capture
-// root down to the node ([1,1] = root.childNodes[1].childNodes[1]). The
-// viewer resolves paths against its reconstructed tree; paths are relative
-// to the SNAPSHOT state at each point in the patch sequence, which holds as
-// long as patches are applied in order from the initial DOM.
-
-var ELEMENT_NODE = 1;
-var TEXT_NODE = 3;
-
-// Elements never serialized: executable or replay-irrelevant. IFRAME is NOT
-// here — frames serialize as inert size-preserving placeholders (see
-// serializeNode) so the surrounding layout doesn't collapse in the viewer.
-var SKIP_TAGS = { SCRIPT: true, NOSCRIPT: true };
+// What retired here at the v2 switchover (spec §14's CH migration list):
+//   - the HTML-STRING walker (`serializeDom`) and its iframe span placeholder,
+//     void-tag table and escaping. A keyframe is a DomNode tree (spec §4);
+//     iframes are recorded as the element itself with no children (§13).
+//   - the NONCE MARKER registry (`data-chn-*`). Integer node ids scoped to a
+//     keyframe span replaced it, so nothing has to be stamped into serialized
+//     markup and harvested back out by the viewer.
+//   - CHILD-INDEX PATHS (`nodePath`) and the `mutation` patch shape. Patches
+//     address nodes by id (§5.1).
+//   - INTRA-BATCH DEDUP and the characterData→childList fold. Both existed
+//     because a v1 childList patch re-serialized the target's whole resulting
+//     children; a `dom.add` carries only what was inserted. mutations.js's
+//     header records the reasoning, and its batch pre-scan is why the observer
+//     callback below hands over the COMPLETE records array untouched.
+//   - the DUPLICATED redaction predicates. redaction.js is the one definition
+//     (spec §8 makes redaction a property of the file, which is a claim only a
+//     single predicate can make checkable).
+
+import { serializeTree } from './snapshot.js';
+import { mapMutations, MUTATION_OBSERVER_INIT } from './mutations.js';
+import { buildInitialState } from './initial-state.js';
+import { createSpan } from './span.js';
 
 /**
- * Serialization-stable node references. Child-index paths are not stable
- * across HTML reparsing (the parser drops comments, merges text nodes, and
- * inserts elements like <tbody>), so every serialized ELEMENT is stamped
- * with a marker attribute instead. The attribute name embeds a per-recording
- * nonce so page CSS written before the recording existed cannot target it
- * ([data-chn-*]{display:none} attacks) and pre-existing page attributes
- * cannot collide. Ids live in a WeakMap keyed by the LIVE node — the live
- * DOM is never mutated (stamping real attributes would echo through the
- * MutationObserver and interfere with the host page). The viewer harvests
- * markers into an out-of-band map and strips them before any measured layout.
+ * Initial stylesheet capture (spec §2 `StylesheetSnapshot`).
+ *
+ * Ids are the array position plus one, assigned here because the format wants
+ * them: `stylesheet_events` addresses sheets by id, and even with that stream
+ * empty (CH captures no CSSOM mutations — spec §13's known limit) a consumer
+ * reads the two arrays as one addressable set.
+ *
+ * `kind` follows the sheet's origin rather than its readability: a <link>
+ * stays a link sheet even when its rules are readable same-origin, and its
+ * `css` is filled in when they are. A cross-origin sheet throws on `cssRules`,
+ * so only the (absolute) href survives — the viewer can link it, nothing can
+ * inline it.
  */
-export function createMarkerRegistry(nonce) {
-  var ids = new WeakMap();
-  var next = 1;
-  return {
-    attr: 'data-chn-' + nonce,
-    refFor: function (node) {
-      var n = ids.get(node);
-      if (n == null) { n = next++; ids.set(node, n); }
-      return n;
-    }
-  };
-}
-
-// Void elements per the HTML spec — serialized without a closing tag.
-var VOID_TAGS = {
-  AREA: true, BASE: true, BR: true, COL: true, EMBED: true, HR: true,
-  IMG: true, INPUT: true, LINK: true, META: true, SOURCE: true,
-  TRACK: true, WBR: true
-};
-
-// Valid attribute-name token; also refuses event-handler attributes
-// (on*) as defense-in-depth — the viewer sandbox+CSP already block inline
-// handlers, but the serialized artifact should not carry them at all.
-var ATTR_NAME_RE = /^[a-zA-Z_:][-a-zA-Z0-9_:.]*$/;
-function isSerializableAttr(name) {
-  return ATTR_NAME_RE.test(name) && !/^on/i.test(name);
-}
-
-function escapeHtml(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-function isBait(node, opts) {
-  if (opts && opts.keepBait) return false;
-  if (!node || node.nodeType !== ELEMENT_NODE) return false;
-  if (node.id === 'ch-decoy') return true;
-  var attrs = node.attributes || [];
-  for (var i = 0; i < attrs.length; i++) {
-    if (attrs[i].name === 'data-ch-role') return true;
-    if (attrs[i].name === 'data-ch-decoy') return true;
-  }
-  return false;
-}
-
-function isPassword(node) {
-  return node.tagName === 'INPUT' &&
-    (node.type === 'password' || hasAttr(node, 'type', 'password'));
-}
-
-// True when the node should be redacted in the DOM capture: a password field
-// (always) or anything matching the configured redactSelector. Without this the
-// DOM path (initial snapshot, value attributes, characterData/childList patches)
-// leaked the content of fields the researcher explicitly marked for redaction,
-// silently defeating redactSelector for everything except the RAF-coalesced
-// input-value events.
-function isRedacted(node, opts) {
-  if (!node) return false;
-  if (isPassword(node)) return true;
-  var sel = opts && opts.redactSelector;
-  if (!sel || typeof node.matches !== 'function') return false;
-  try { return node.matches(sel); } catch (e) { return false; }
-}
-
-// True when the node is inside (or is) a redacted element. Walks ancestors so
-// that mutation targets which are TEXT NODES (characterData records, added text
-// nodes) — which have no matches() of their own — are correctly redacted when
-// their containing element is. Without the walk, characterData on a redacted
-// contenteditable would leak the typed text through mutation patches.
-function isInRedactedSubtree(node, opts) {
-  var cur = node;
-  while (cur) {
-    if (cur.nodeType === ELEMENT_NODE && isRedacted(cur, opts)) return true;
-    cur = cur.parentNode;
-  }
-  return false;
-}
-
-function hasAttr(node, name, value) {
-  var attrs = node.attributes || [];
-  for (var i = 0; i < attrs.length; i++) {
-    if (attrs[i].name === name) return value == null || attrs[i].value === value;
-  }
-  return false;
-}
-
-/**
- * Serializes a DOM subtree to an HTML string.
- * - strips scripts/iframes and (by default) honeypot/decoy nodes
- * - prefers the `src` PROPERTY for images (always absolute) over the
- *   attribute (may be relative and unresolvable inside the viewer's srcdoc)
- * - redacts password input values (marker attribute, no content)
- */
-export function serializeDom(root, opts) {
-  opts = opts || {};
+export function captureStylesheets(doc) {
   var out = [];
-  serializeNode(root, opts, out);
-  return out.join('');
-}
-
-// Iframe → inert placeholder. Child documents are never captured (their
-// events don't bubble to this document and the srcdoc CSP blocks frames
-// anyway), but dropping the element entirely would collapse the surrounding
-// layout and silently shift every element below it. The placeholder keeps
-// the recorded footprint; the viewer shows a per-trial "iframe content not
-// captured" warning when one is present.
-// Current footprint of an iframe, for the placeholder and for footprint
-// re-sync patches when the iframe's attributes later mutate.
-function iframeFootprint(node) {
-  var w = null, h = null;
-  try {
-    if (typeof node.getBoundingClientRect === 'function') {
-      var r = node.getBoundingClientRect();
-      // A 0×0 rect is a VALID footprint (hidden iframe) — the placeholder
-      // must reproduce it, not invent a default-size box that shifts layout.
-      if (r) { w = Math.round(r.width || 0); h = Math.round(r.height || 0); }
-    }
-  } catch (e) { /* fall through to attributes */ }
-  if (w == null) {
-    w = parseInt(hasAttr(node, 'width') ? getAttrValue(node, 'width') : '', 10);
-    h = parseInt(hasAttr(node, 'height') ? getAttrValue(node, 'height') : '', 10);
-    if (!(w > 0)) w = 300;   // spec default iframe size
-    if (!(h > 0)) h = 150;
-  }
-  return { w: w, h: h };
-}
-
-// Layout-affecting computed properties copied onto the placeholder so an
-// absolutely-positioned / block / floated / margined iframe doesn't collapse
-// into a plain in-flow inline box and shift everything around it.
-var IFRAME_LAYOUT_PROPS = ['position', 'top', 'right', 'bottom', 'left',
-  'margin', 'float', 'vertical-align', 'z-index'];
-
-function iframeFootprintStyle(node) {
-  var f = iframeFootprint(node);
-  var css = '';
-  var display = 'inline-block';
-  try {
-    var view = node.ownerDocument && node.ownerDocument.defaultView;
-    if (view && typeof view.getComputedStyle === 'function') {
-      var cs = view.getComputedStyle(node);
-      // display: keep the computed value except 'inline' — a span needs
-      // inline-block (or stronger) to honor explicit width/height.
-      if (cs.display && cs.display !== 'inline') display = cs.display;
-      for (var i = 0; i < IFRAME_LAYOUT_PROPS.length; i++) {
-        var prop = IFRAME_LAYOUT_PROPS[i];
-        var v = cs.getPropertyValue(prop);
-        if (v && v !== 'auto' && v !== 'none' && v !== 'normal' &&
-            v !== 'baseline' && v !== '0px') {
-          css += prop + ':' + v + ';';
-        }
-      }
-    }
-  } catch (e) { /* fall back to the plain inline-block footprint */ }
-  return 'display:' + display + ';' + css +
-    'width:' + f.w + 'px;height:' + f.h + 'px';
-}
-
-function serializeIframePlaceholder(node, opts, out) {
-  // <span>, not <div>: iframes are phrasing content, so the placeholder must
-  // be too — a div inside <p> would trigger parser reparenting (implicit </p>)
-  // and shift the reconstructed layout the placeholder exists to preserve.
-  out.push('<span data-ch-iframe=""');
-  if (opts.markers) {
-    out.push(' ' + opts.markers.attr + '="' + opts.markers.refFor(node) + '"');
-  }
-  out.push(' style="' + iframeFootprintStyle(node) + '"></span>');
-}
-
-function getAttrValue(node, name) {
-  var attrs = node.attributes || [];
-  for (var i = 0; i < attrs.length; i++) {
-    if (attrs[i].name === name) return attrs[i].value;
-  }
-  return '';
-}
-
-function serializeNode(node, opts, out) {
-  if (!node) return;
-  if (node.nodeType === TEXT_NODE) {
-    out.push(escapeHtml(node.textContent || ''));
-    return;
-  }
-  if (node.nodeType !== ELEMENT_NODE) return;   // comments, PIs: irrelevant
-  var tag = node.tagName;
-  if (SKIP_TAGS[tag]) return;
-  if (isBait(node, opts)) return;
-  if (tag === 'IFRAME') { serializeIframePlaceholder(node, opts, out); return; }
-
-  var lower = tag.toLowerCase();
-  out.push('<' + lower);
-  if (opts.markers) {
-    out.push(' ' + opts.markers.attr + '="' + opts.markers.refFor(node) + '"');
-  }
-  // Shadow roots are not serializable from the outside: the host's box
-  // survives but its rendered content does not. Mark it so the viewer can
-  // refuse to "verify" interactions against a hollow reconstruction.
-  if (node.shadowRoot) out.push(' data-ch-shadow=""');
-
-  var redactValue = isRedacted(node, opts);
-  var srcOverride = (tag === 'IMG' && node.src) ? node.src : null;
-  var wroteSrc = false;
-
-  var attrs = node.attributes || [];
-  for (var i = 0; i < attrs.length; i++) {
-    var name = attrs[i].name;
-    var value = attrs[i].value;
-    if (!isSerializableAttr(name)) continue;
-    if (name === 'value' && redactValue) continue;
-    if (name === 'src' && srcOverride) { value = srcOverride; wroteSrc = true; }
-    out.push(' ' + name + '="' + escapeHtml(value) + '"');
-  }
-  if (srcOverride && !wroteSrc) out.push(' src="' + escapeHtml(srcOverride) + '"');
-  if (redactValue) out.push(' data-ch-redacted="true"');
-  out.push('>');
-
-  if (!VOID_TAGS[tag]) {
-    // A redacted element's text children (e.g. contenteditable content) are
-    // withheld too — otherwise typed text under a redactSelector match would
-    // leak straight into the snapshot despite the marker on the element.
-    if (!redactValue) {
-      var kids = node.childNodes || [];
-      for (var k = 0; k < kids.length; k++) serializeNode(kids[k], opts, out);
+  var sheets = (doc && doc.styleSheets) || [];
+  for (var i = 0; i < sheets.length; i++) {
+    var sheet = sheets[i];
+    var href = sheet.href || null;
+    var media = sheet.media && sheet.media.mediaText ? sheet.media.mediaText : null;
+    var css = null;
+    try {
+      var rules = sheet.cssRules;
+      var text = [];
+      for (var r = 0; r < rules.length; r++) text.push(rules[r].cssText);
+      css = text.join('\n');
+    } catch (e) {
+      css = null;                      // cross-origin: unreadable from here
     }
-    out.push('</' + lower + '>');
+    out.push(href
+      ? { id: i + 1, kind: 'link', href: href, css: css, media: media }
+      : { id: i + 1, kind: 'inline', css: css == null ? '' : css, media: media });
   }
+  return out;
 }
 
 /**
- * Child-index path from root to node; [] for the root itself; null if the
- * node is not under the root (e.g. extension-injected DOM outside the
- * experiment container).
+ * Inline the text of href-only link sheets by fetching them (2026-09-03).
+ *
+ * `captureStylesheets` cannot read a cross-origin sheet's rules — the browser
+ * refuses `cssRules` under the same-origin policy — so such a sheet ships
+ * href-only and the viewer plays unstyled until an analyst opts into fetching
+ * it there. A fresh CORS `fetch()` of the same URL is a different operation
+ * the server may permit (CDNs such as jsdelivr do), so the text can be inlined
+ * HERE, where the page is, and the recording becomes self-contained; the
+ * viewer's no-network frame then needs nothing (spec §12 stays intact).
+ *
+ * Mutates the entries IN PLACE: the recorder holds these same objects
+ * (`setStylesheets`), so a fill that lands before finalize is what ships.
+ * Off the critical path — the caller does not await the returned promise; a
+ * finalize that beats the fetch ships href-only, which is today's behaviour.
+ * Any failure (no fetch, CORS refusal, non-2xx, network) leaves `css: null`.
+ * Only http(s) hrefs are tried: blob:/data: sheets cannot be re-fetched.
+ * No cookies are sent (`credentials: 'omit'`) — a stylesheet needs none, and
+ * a participant's session must never ride on a recorder's request.
  */
-export function nodePath(node, root) {
-  var path = [];
-  var cur = node;
-  while (cur && cur !== root) {
-    var parent = cur.parentNode;
-    if (!parent) return null;
-    var idx = indexOfChild(parent, cur);
-    if (idx === -1) return null;
-    path.unshift(idx);
-    cur = parent;
+export function fillCrossOriginSheets(sheets, fetchImpl) {
+  if (typeof fetchImpl !== 'function' || !Array.isArray(sheets)) return Promise.resolve();
+  var pending = [];
+  for (var i = 0; i < sheets.length; i++) {
+    var sheet = sheets[i];
+    if (!sheet || sheet.kind !== 'link' || sheet.css != null) continue;
+    if (typeof sheet.href !== 'string' || !/^https?:/i.test(sheet.href)) continue;
+    pending.push(fillOne(sheet, fetchImpl));
   }
-  return cur === root ? path : null;
-}
-
-function indexOfChild(parent, child) {
-  var kids = parent.childNodes || [];
-  for (var i = 0; i < kids.length; i++) if (kids[i] === child) return i;
-  return -1;
+  return Promise.all(pending).then(function () { /* settled */ });
 }
 
-/**
- * Translates one MutationRecord into a JSON patch entry, or null when the
- * mutation should not be recorded (bait subtree, node outside root).
- */
-export function mutationToPatch(record, root, opts) {
-  var target = record.target;
-  // Walk up: mutations inside bait subtrees are never recorded.
-  var cur = target;
-  while (cur) {
-    if (isBait(cur, opts)) return null;
-    cur = cur.parentNode;
-  }
-  // With a marker registry, characterData mutations are recorded as the
-  // PARENT's resulting-children snapshot: text nodes are not parser-stable
-  // references (adjacent text nodes merge on reparse; empty ones vanish), so
-  // a text-node address can resolve to the wrong node in the reconstruction.
-  // The parent element IS stable via its marker, and a children snapshot is
-  // idempotent like every other childList patch.
-  if (record.type === 'characterData' && opts.markers) {
-    var parent = target.parentNode;
-    if (!parent || nodePath(parent, root) === null) return null;
-    record = { type: 'childList', target: parent };
-    target = parent;
-  }
-
-  var path = nodePath(target, root);
-  if (path === null) return null;
-
-  // Marker reference: the parser-stable address the viewer resolves first;
-  // the child-index path stays as a diagnostic fallback. `tag` is the tag
-  // EXPECTED IN THE RECONSTRUCTION (that's what resolution validates) — for
-  // iframes that is the placeholder span, not the source tag.
-  var ref = opts.markers && target.nodeType === ELEMENT_NODE
-    ? { n: opts.markers.refFor(target),
-        tag: target.tagName === 'IFRAME' ? 'span' : target.tagName.toLowerCase() }
-    : null;
-
-  if (record.type === 'childList') {
-    // State-snapshot patch: removed nodes are already detached (they have
-    // no address), so a faithful add/remove log is impossible. Serializing
-    // the target's RESULTING children makes application an idempotent
-    // innerHTML assignment — and backward seeks just rebuild from the
-    // initial DOM and re-apply patches in order.
-    //
-    // A childList mutation on (or inside) a redacted element emits empty
-    // children: serializeChildren walks the target's children directly, so it
-    // would otherwise leak text/inputs that serializeNode hides when it reaches
-    // the redacted element itself.
-    return Object.assign({
-      op: 'childList',
-      path: path,
-      html: isInRedactedSubtree(target, opts) ? '' : serializeChildren(target, opts)
-    }, ref || {});
-  }
-  if (record.type === 'attributes') {
-    // The reconstruction holds a placeholder SPAN where the iframe was, and
-    // width/height ATTRIBUTES don't size a span — so any attribute change on
-    // an iframe is translated into a fresh footprint style patch instead of
-    // forwarding an attribute the placeholder can't honor.
-    if (target.tagName === 'IFRAME') {
-      return Object.assign(
-        { op: 'attributes', path: path, name: 'style', value: iframeFootprintStyle(target) },
-        ref || {});
-    }
-    var name = record.attributeName;
-    if (!isSerializableAttr(name)) return null;
-    var value = typeof target.getAttribute === 'function'
-      ? target.getAttribute(name) : null;
-    // Never leak the value attribute of a redacted field (password or
-    // redactSelector match, including via a redacted ancestor).
-    if (name === 'value' && isInRedactedSubtree(target, opts)) value = null;
-    return Object.assign({ op: 'attributes', path: path, name: name, value: value }, ref || {});
-  }
-  if (record.type === 'characterData') {
-    // characterData targets are TEXT NODES, so redaction must consult the
-    // containing element(s): typing into a redacted contenteditable must not
-    // carry the typed text through the patch.
-    var text = isInRedactedSubtree(target, opts) ? '' : (target.textContent || '');
-    return { op: 'characterData', path: path, value: text };
-  }
-  return null;
+function fillOne(sheet, fetchImpl) {
+  return Promise.resolve()
+    .then(function () { return fetchImpl(sheet.href, { mode: 'cors', credentials: 'omit' }); })
+    .then(function (res) {
+      if (!res || !res.ok) return null;
+      return res.text();
+    })
+    .then(function (text) {
+      if (typeof text === 'string' && sheet.css == null) sheet.css = text;
+    })
+    .catch(function () { /* stays href-only */ });
 }
 
-// Serializes only the CHILDREN of a node (innerHTML semantics) — used by
-// the childList state-snapshot patch.
-function serializeChildren(node, opts) {
-  var out = [];
-  var kids = node.childNodes || [];
-  for (var i = 0; i < kids.length; i++) serializeNode(kids[i], opts, out);
-  return out.join('');
+// How many characters a keyframe payload costs, as the wire would carry it.
+// Exact rather than estimated: the trial's size budget is a bound on the
+// payload, and the payload is a JSON tree, so its JSON length is the thing
+// being bounded. Measured ONCE per keyframe and used twice — to decide whether
+// the snapshot itself is over budget, and to seed the recorder's per-trial
+// character count, which cannot see anything stored on the trial.
+function payloadChars(value) {
+  if (value == null) return 0;
+  try { return JSON.stringify(value).length; } catch (e) { return 0; }
 }
 
 /**
- * Initial stylesheet capture: css text where readable, href fallback for
- * cross-origin sheets (viewer inlines css; hrefs render as absolute links).
+ * Keyframe or continuation? (spec §3's cadence guidance.)
+ *
+ * Pure, so the boundaries a scripted DOM cannot hit on purpose are testable
+ * directly. `cadence` is the bookkeeping the attachment keeps per span:
+ *
+ *   `hasKeyframe`       has a keyframe of THIS span reached the file? False at
+ *                       the start of a recording and after a keyframe was
+ *                       dropped or threw — in both cases there is nothing for
+ *                       a continuation to continue from, and §3 requires the
+ *                       first DOM-bearing segment to be a keyframe.
+ *   `segments`          segments opened in this span, the keyframe included.
+ *   `patchChars`        the plan's `bytesSinceKeyframe`. See below.
+ *   `lastSnapshotChars` what the span's keyframe cost the file: the exact JSON
+ *                       length of its tree plus its `initial_state` seed (the
+ *                       same number `noteSnapshotChars` gets). 0 when no
+ *                       keyframe has been measured.
+ *
+ * WHAT `patchChars` COUNTS, exactly: the sum over every observer batch flushed
+ * since the keyframe of `JSON.stringify(patches).length`, where `patches` is
+ * the array of `dom.*` events that batch mapped to.
+ *
+ *   - CHARS, not bytes. The plan and design call it `bytesSinceKeyframe`; it is
+ *     measured in the same unit as `maxCharsPerTrial` (UTF-16 code units, which
+ *     UTF-8 byte size can exceed for non-ASCII), so it carries that config's
+ *     name for that config's reason. Both sides of the comparison use it, so
+ *     the ratio the trigger actually tests is unit-free.
+ *   - `dom.*` ONLY, on FILE-SIZE grounds — not because trace events carry no
+ *     state. Some of them plainly do: `input.value`, `scroll.*` and `media.*`
+ *     are exactly the state `initial_state` re-states (spec §3 `form`,
+ *     `scroll`, `element_scroll`, `media`), and their keyframe-side cost is
+ *     priced into `lastSnapshotChars` through the seed. What makes them
+ *     uncountable here is that a keyframe does not REMOVE them from the file —
+ *     playback needs every one of them — so §3's "at parity the keyframe is
+ *     free" argument, which is the whole basis of this comparison, does not
+ *     apply. Counting them would keyframe on volume the keyframe cannot
+ *     reclaim. The consequence is real and belongs on the record: on a
+ *     form-heavy or scroll-heavy but DOM-STATIC segment this trigger can never
+ *     fire, and `keyframeEvery` becomes the only bound on seek distance and on
+ *     a corrupt event's blast radius — §3's failure mode from the other side.
+ *   - AT EMISSION, before the recorder's per-trial caps can refuse a record, and
+ *     off the in-memory event (absolute `t`) rather than the wire event
+ *     (session-relative, usually shorter). Both make the count an over-estimate:
+ *     MEASURED at 1.08x, 5.3 chars per patch over 12 `dom.attr` patches (864
+ *     in-memory against 800 on the wire), all of it the timestamp. It biases
+ *     toward keyframing sooner — the direction that shortens seek distance and
+ *     shrinks the blast radius of a corrupt event.
+ *
+ * @param {{hasKeyframe: boolean, segments: number, patchChars: number,
+ *          lastSnapshotChars: number}} cadence
+ * @param {number|null} keyframeEvery  segment fallback (recorder config)
  */
-export function captureStylesheets(doc) {
-  var out = [];
-  var sheets = (doc && doc.styleSheets) || [];
-  for (var i = 0; i < sheets.length; i++) {
-    var sheet = sheets[i];
-    try {
-      var rules = sheet.cssRules;
-      var css = [];
-      for (var r = 0; r < rules.length; r++) css.push(rules[r].cssText);
-      out.push({ css: css.join('\n') });
-    } catch (e) {
-      // Cross-origin sheet: record the (absolute) href so the viewer can
-      // at least link it; content is unreadable from this origin.
-      out.push({ href: sheet.href || null });
-    }
-  }
-  return out;
+export function shouldKeyframe(cadence, keyframeEvery) {
+  if (!cadence.hasKeyframe) return true;
+  // The fallback: at most `keyframeEvery` segments per span, so segment N of a
+  // span (counting the keyframe as 1) is where the next keyframe lands.
+  //
+  // The `typeof` is deliberately strict, and diverges from the sibling caps —
+  // `maxViewportChanges` would coerce a string `"10"` and work. Here a wrong
+  // TYPE must not silently become a different CADENCE: `"10"` from a JSON
+  // config or a URL parameter would compare as a string and disable the
+  // fallback, changing the shape of the researcher's file with no other
+  // symptom. It is refused rather than coerced, and `attachDomCapture` warns
+  // once about it at attach, which is where a misconfiguration is still
+  // fixable.
+  if (typeof keyframeEvery === 'number' && keyframeEvery >= 1 &&
+      cadence.segments >= keyframeEvery) return true;
+  // The size trigger: spec §3's self-tuning rule — take a keyframe once the
+  // accumulated mutation volume rivals a fresh snapshot's size, because at that
+  // point the keyframe is free in file size. `>=` so parity keyframes.
+  // Guarded on a measured keyframe: 0 would make the comparison vacuously true.
+  return cadence.lastSnapshotChars > 0 &&
+         cadence.patchChars >= cadence.lastSnapshotChars;
 }
 
 /**
  * Attaches tier-2 capture to a recorder:
- *  - snapshots initial DOM + stylesheets at session start and at each
- *    startTrial (recorder calls snapshotTrial via the returned hooks)
- *  - MutationObserver → 'mutation' events
+ *  - a KEYFRAME at the start of a segment the cadence asks for one at: the
+ *    DomNode tree plus its `initial_state` seed, both taken on the shared
+ *    capture span. Every other segment is a CONTINUATION of it (see
+ *    `shouldKeyframe`)
+ *  - MutationObserver batches → `dom.*` patch events
+ *  - initial stylesheet capture at attach
  *  - guard-friction cooperation: onViolation('start') fires synchronously
  *    BEFORE obfuscateContent() (pinned by contract test), so the clean-DOM
  *    snapshot taken inside the callback is genuinely pre-scramble.
+ *
+ * @param {object} rec  the recorder
+ * @param {object} env  {doc, win, now, MutationObserver} for testing, plus the
+ *   two capture-wide objects the assembly (index.js) threads to BOTH capture
+ *   modules:
+ *     `span`     the capture span (span.js) — node ids and the file's own
+ *                record of what it contains. The SAME object capture-trace
+ *                gets, because an event's `target` and a patch's `node` are
+ *                the same numbering or neither means anything.
+ *     `scrolled` a function returning capture-trace's set of elements that
+ *                have scrolled, which the keyframe seed enumerates (spec §3
+ *                `element_scroll`). Only the scroll listener knows this.
  */
 export function attachDomCapture(rec, env) {
   env = env || {};
@@ -416,112 +234,307 @@ export function attachDomCapture(rec, env) {
   var now = env.now || function () { return performance.now(); };
   var MutationObserverImpl = env.MutationObserver ||
     (typeof MutationObserver !== 'undefined' ? MutationObserver : null);
-  // Per-recording marker nonce (see createMarkerRegistry). Registered on the
-  // recorder so capture-trace can reference the same registry for interaction
-  // anchors and the serializer can emit the attribute name on the wire.
-  var markers = createMarkerRegistry(
-    (Math.random().toString(16).slice(2, 10) || 'fallback0'));
-  if (typeof rec.setMarkers === 'function') {
-    rec.setMarkers(markers);
-    rec.setMarkerAttr(markers.attr);
-  }
-  var opts = { keepBait: rec.config.keepBait, redactSelector: rec.config.redactSelector,
-               markers: markers };
+  // A lone attachment (a test wiring this module by itself) gets its own span
+  // rather than an ambient shared one: a module-level default is what lets a
+  // stray serialization write into a live recording's model (span.js).
+  var span = env.span || createSpan();
+  var scrolled = typeof env.scrolled === 'function'
+    ? env.scrolled : function () { return null; };
+  // One options bag for every consumer — the snapshot walk, the mutation
+  // mapper, the seed and the guard snapshot. Exclusion and redaction cannot be
+  // answered one way in the keyframe and another way in a patch if there is
+  // only one answer to hand around.
+  var opts = {
+    keepBait: rec.config.keepBait,
+    redactSelector: rec.config.redactSelector,
+    taint: env.taint,
+  };
+
+  // THE OBSERVED ROOT, resolved ONCE.
+  //
+  // v1 re-resolved it at every snapshot and every batch, which let the keyframe
+  // and the patches addressing it describe two different elements if the page
+  // replaced the container — and the observer, attached to whichever element
+  // existed first, would have been watching neither. The recording's root is by
+  // definition the element the observer watches, so it is resolved here and
+  // held. (Task 4's residual: the seed's "did anything get walked" guard
+  // catches a never-walked span, not a walk of a DIFFERENT root. One root
+  // identity is what makes that unreachable rather than merely unlikely.)
+  // Did the held root actually come from the configured selector? Resolving
+  // once turns a transient miss into a permanent one, so the answer has to
+  // reach the file rather than being assumed (see rootSelector below).
+  var rootFromSelector = false;
+  var root = resolveRoot();
 
   function resolveRoot() {
     var r = rec.config.root;
-    if (typeof r === 'string') {
-      try { return doc.querySelector(r) || doc.body; } catch (e) { return doc.body; }
+    if (typeof r === 'string' && r) {
+      var found = null;
+      try { found = doc.querySelector(r); } catch (e) { found = null; }
+      if (found) { rootFromSelector = true; return found; }
+      // A selector that matches nothing (or does not parse) is a study
+      // misconfiguration, and the fallback is silent everywhere else: the
+      // recording looks complete and simply describes a different subtree.
+      rec.captureFailure('observed_root', new Error(
+        'root selector "' + r + '" matched nothing at startSession(); ' +
+        'observing document.body instead'));
+      return doc.body;
     }
     return r || doc.body;
   }
 
+  // Spec §2 types `observed_root` as a SELECTOR, and it must name what was
+  // OBSERVED, not what was asked for. Returning the configured selector after
+  // the fallback would put a body-rooted tree in a file labelled `#stage`, and
+  // a conforming player honouring the field would mount it there.
+  //
+  // So: the configured selector only when the held root came from it; else the
+  // root's own id; else null, which is §2's spelling for "the document body"
+  // and exactly what the fallback observed. `null` alone would read as "the
+  // researcher configured nothing", which is why the capture failure above is
+  // the other half of this — together they are diagnosable.
+  function rootSelector() {
+    if (rootFromSelector) return rec.config.root;
+    if (root && root.id) return '#' + root.id;
+    return null;
+  }
+
+  rec.setObservedRoot(rootSelector());
+
   try {
-    rec.setStylesheets(captureStylesheets(doc));
+    var sheets = captureStylesheets(doc);
+    rec.setStylesheets(sheets);
+    // Cross-origin sheets are href-only here; try to inline their text so the
+    // recording is self-contained (see fillCrossOriginSheets). Not awaited.
+    var view = doc && doc.defaultView;
+    if (view && typeof view.fetch === 'function') {
+      fillCrossOriginSheets(sheets, view.fetch.bind(view));
+    }
   } catch (e) { rec.captureFailure('stylesheets', e); }
 
-  // Snapshot the initial DOM at the start of every trial (explicit or
-  // implicit) — this is the frame the viewer reconstructs and patches.
+  // ── Keyframe cadence (spec §3) ──
   //
-  // The initial snapshot is the single largest capture source and is stored on
-  // the trial (not pushed as an event), so the recorder's per-event size cap
-  // can't see it. Enforce the cap HERE at assignment: a snapshot longer than
-  // maxCharsPerTrial is dropped (with a captureFailure) rather than retained,
-  // so a giant DOM can't bypass the resource/payload limit. A dropped snapshot
-  // makes that trial's replay show "no DOM captured" rather than blowing up.
+  // A segment either opens a new keyframe span — a full snapshot, ids restarting
+  // at 1 — or CONTINUES the current one, carrying `initial_dom: null` and
+  // nothing else. `shouldKeyframe` above owns the decision and documents the
+  // trigger; this is the bookkeeping it reads, one object per attachment, which
+  // is one per recording.
+  var cadence = {
+    hasKeyframe: false, segments: 0, patchChars: 0, lastSnapshotChars: 0,
+  };
+
+  // Said once, at attach, rather than per segment: the fallback is refused for
+  // a non-number (see `shouldKeyframe`), and silently recording a differently
+  // shaped file is exactly what the strictness exists to prevent.
+  var kfEvery = rec.config.keyframeEvery;
+  if (kfEvery != null && typeof kfEvery !== 'number') {
+    console.warn('[cyborg-hunter-replay] keyframeEvery must be a number; got ' +
+      typeof kfEvery + ' (' + JSON.stringify(kfEvery) + '). The segment fallback ' +
+      'is DISABLED for this recording — keyframes will be taken on accumulated ' +
+      'patch size alone.');
+  }
+
   rec.onTrialStart(function (trial) {
+    // An IMPLICIT segment is opened RE-ENTRANTLY from inside `pushRecord`
+    // (recorder.js's storeEvent), and the capture path doing that push has
+    // ALREADY resolved its node ids against the current span — mapMutations for
+    // a whole batch, targetFacts for one event — into records that are about to
+    // be stored. A keyframe here calls `span.reset()`, so those ids name a span
+    // the file no longer describes, and because a fresh pre-order walk reuses
+    // the same small integers they do not dangle harmlessly: the player
+    // resolves them against the new tree. Reproduced as a `dom.remove` that
+    // deletes a node the participant never lost, and a `mouse.click` whose
+    // `target` names a different element than its own `anchor.tag`. Strict
+    // validation passes it — `node` fields are only number-checked.
+    //
+    // So an implicit segment always CONTINUES. The single exception is a span
+    // with no keyframe at all, where §3 still forces one below — and in that
+    // state the span holds nothing, so no id in flight can be stale: a mapped
+    // batch produces no events, and a trace event's target already resolves to
+    // null. (One consequence of that exception is recorded at recorder.js's
+    // implicit-trial branch: the event that opens such a segment loses its
+    // `target` id.)
+    //
+    // This is the only re-entrant path into `span.reset()`: its three call
+    // sites are all in this hook, and `fireTrialStart` reaches it from
+    // `startTrial` (host-driven, never re-entrant) and from `storeEvent`
+    // (implicit only). Closing the implicit branch closes it for every capture
+    // module at once, which a check inside any one module could not do.
+    if (trial.implicit && cadence.hasKeyframe) {
+      cadence.segments++;
+      return;
+    }
+    if (!shouldKeyframe(cadence, rec.config.keyframeEvery)) {
+      // A CONTINUATION. Nothing to do, and that is the point: the trial's
+      // `initialDom`/`initialState` are already null (recorder.js), the span is
+      // NOT reset, so every id the keyframe assigned stays valid and every node
+      // the player holds stays held. A seed here would be wrong rather than
+      // merely redundant — `initial_state` states what was true BEFORE a
+      // keyframe (spec §3), and a continuation has no keyframe to precede.
+      // The state it would re-state is already in the file as the patches and
+      // events of the segments since, which the player has replayed by the time
+      // it arrives here.
+      cadence.segments++;
+      return;
+    }
+    // A KEYFRAME. The order is a contract, not a preference: reset, then walk,
+    // then seed. `span.reset()` restarts ids at 1 and empties the delivered
+    // picture in one call (span.js — never `span.registry.resetSpan()` alone,
+    // which silently loses nodes), the walk is the span's FIRST allocation so
+    // the tree numbers 1..N, and the seed reads the ids that walk assigned.
+    // Taken in any other order the seed names nodes the file does not contain.
     try {
-      var html = serializeDom(resolveRoot(), opts);
+      span.reset();
+      var tree = serializeTree(root, span, opts);
+      var seed = buildInitialState(root, span, {
+        win: win,
+        scrolled: scrolled(),
+        keepBait: opts.keepBait,
+        redactSelector: opts.redactSelector,
+        taint: opts.taint,
+      });
+      var chars = payloadChars(tree) + payloadChars(seed);
       var cap = rec.config.maxCharsPerTrial;
-      if (cap != null && html.length > cap) {
+      if (cap != null && chars > cap) {
+        // The keyframe is the single largest capture source and is stored on
+        // the trial rather than pushed as an event, so the recorder's cap
+        // cannot refuse it — it is refused HERE, or a giant DOM bypasses the
+        // payload limit entirely. The trial then replays as "no DOM captured".
         rec.captureFailure('dom_snapshot', new Error(
-          'initial DOM snapshot length ' + html.length + ' exceeds maxCharsPerTrial ' +
+          'initial DOM keyframe of ' + chars + ' chars exceeds maxCharsPerTrial ' +
           cap + '; dropped to bound payload size'));
-        trial.initialDom = '';
+        trial.initialDom = null;
+        trial.initialState = null;
+        // The walk told the span the player holds this tree. It does not: the
+        // keyframe is not in the file. Resetting again empties that picture, so
+        // the patches that follow address nothing and are dropped rather than
+        // naming ids no player ever received.
+        span.reset();
+        keyframeFailed();
       } else {
-        trial.initialDom = html;
+        trial.initialDom = tree;
+        trial.initialState = seed;
+        rec.noteSnapshotChars(trial, chars);
+        cadence.hasKeyframe = true;
+        cadence.segments = 1;
+        cadence.patchChars = 0;
+        cadence.lastSnapshotChars = chars;
       }
     } catch (e) {
       rec.captureFailure('dom_snapshot', e);
-      trial.initialDom = '';
+      trial.initialDom = null;
+      trial.initialState = null;
+      span.reset();
+      keyframeFailed();
     }
   });
 
+  // A keyframe that was dropped or threw leaves the file with no tree for this
+  // span, so the next segment must take one rather than continue from nothing:
+  // a continuation carrying dom.* patches before any keyframe is a recording no
+  // player can reconstruct, and strict validation rejects it (spec §3).
+  //
+  // ONE of these four assignments has behaviour, and the reader is owed that
+  // plainly. `hasKeyframe = false` is what forces the retry; the other three are
+  // DEAD BY CONSTRUCTION and kept deliberately. Proof, not opinion: rule 1 of
+  // `shouldKeyframe` short-circuits before reading `segments`, `patchChars` or
+  // `lastSnapshotChars`, and the next keyframe that lands rewrites all four —
+  // verified by inversion, since reducing this function to its single live line
+  // passes the whole suite. They stay because they make the cadence state a true
+  // description of the file (this span has no keyframe, so it has no segments,
+  // no accumulated patches and no measured snapshot) and because they make the
+  // retry singly-caused: without them the retry would still happen, from the
+  // stale trigger values that asked for the failed keyframe, which is a
+  // coincidence rather than a rule.
+  //
+  // Fault-injection consequence, so nobody reads the four as jointly guarded:
+  // deleting this call altogether is NOT observable (the stale counters retry
+  // anyway); deleting the `hasKeyframe` line alone IS, and is pinned.
+  function keyframeFailed() {
+    cadence.hasKeyframe = false;
+    cadence.segments = 0;
+    cadence.patchChars = 0;
+    cadence.lastSnapshotChars = 0;
+  }
+
+  // ── Mutations (spec §5.1) ──
   if (MutationObserverImpl) {
-    var observer = new MutationObserverImpl(function (records) {
+    var handleBatch = function (records) {
       try {
-        var root = resolveRoot();
-        // Intra-batch dedup: ONE childList patch per TARGET NODE, emitted at
-        // the target's FIRST record position. A single task appending N
-        // children to one container delivers N childList records, and each
-        // patch serializes the target's FULL resulting children — O(N²)
-        // work on the participant's machine without dedup. Serialization
-        // happens at callback time (final state), so every record for a
-        // target would carry identical html — only ORDER matters, and
-        // first-occurrence order guarantees a node created in-batch has its
-        // ancestor's creating patch emitted BEFORE any patch targeting the
-        // new node (observer records are chronological). Keyed by node
-        // IDENTITY, not path (path-keyed dedup was refuted: same-batch
-        // index aliasing). attributes/characterData records never skipped.
-        // Dedup key = the EFFECTIVE childList target: in marker mode,
-        // characterData records become parent-level childList snapshots
-        // inside mutationToPatch, so N text rewrites on one node are the
-        // same O(N²) storm as N appends and must dedup on the PARENT.
-        var seenChildListTargets = new Set();
-        var effectiveChildListTarget = function (record) {
-          if (record.type === 'childList') return record.target;
-          if (record.type === 'characterData' && opts.markers &&
-              record.target && record.target.parentNode) {
-            return record.target.parentNode;
-          }
-          return null;
-        };
-        for (var i = 0; i < records.length; i++) {
-          var key = effectiveChildListTarget(records[i]);
-          if (key) {
-            if (seenChildListTargets.has(key)) continue;
-            seenChildListTargets.add(key);
-          }
-          var patch = mutationToPatch(records[i], root, opts);
-          if (patch) rec.pushEvent('mutation', patch, now());
+        // The COMPLETE batch, in the observer's own order. mapMutations
+        // pre-scans it (which removals and insertions are still to come, what
+        // each attribute held before the batch) and that pre-scan is what makes
+        // the mapping batch-coherent — filtering or reordering records here
+        // would silently break it.
+        var events = mapMutations(records, {
+          root: root,
+          span: span,
+          // One callback = one `t` (spec §7): the batch is one task's worth of
+          // DOM change, and the observer reports it with no per-record times.
+          t: now(),
+          keepBait: opts.keepBait,
+          redactSelector: opts.redactSelector,
+          taint: opts.taint,
+        });
+        for (var i = 0; i < events.length; i++) {
+          rec.pushRecord(events[i], events[i].t);
         }
+        // What the span has cost in deltas so far (see `shouldKeyframe`).
+        // Measured once per batch rather than once per patch: one stringify of
+        // the array is the cheaper call and the closer estimate of what the
+        // events cost as a group on the wire.
+        if (events.length) cadence.patchChars += payloadChars(events);
       } catch (e) { rec.captureFailure('mutations', e); }
-    });
+    };
+    var observer = new MutationObserverImpl(handleBatch);
     try {
-      observer.observe(resolveRoot(), {
-        childList: true, attributes: true, characterData: true, subtree: true
-      });
+      observer.observe(root, MUTATION_OBSERVER_INIT);
       // Registered through the listener registry with the observer marker so
       // recorder.destroy() disconnects it (same convention as core monitor).
       rec.addListener(
         { addEventListener: function () {}, removeEventListener: function () {} },
         '_mutation_observer', observer, { _isObserver: true });
+      // The observer callback is a MICROTASK, so DOM changes made in the same
+      // task as stopSession() are still queued when the recording closes and
+      // disconnecting drops them silently. Draining the queue through the SAME
+      // handler is what makes the last thing a participant saw a patch rather
+      // than a gap (T3 final review, F-5).
+      rec.addPreCloseFlush(function () {
+        var pending = observer.takeRecords();
+        if (pending && pending.length) handleBatch(pending);
+      });
     } catch (e) { rec.captureFailure('mutations', e); }
   }
 
-  // Guard-friction cooperation: snapshot the clean DOM synchronously when a
-  // violation starts (before friction scrambles content), so the analyst can
-  // see exactly what the participant saw at the moment of violation.
+  // ── Guard-friction cooperation ──
+  // Snapshot the clean DOM synchronously when a violation starts (before
+  // friction scrambles content), so the analyst can see exactly what the
+  // participant saw at the moment of violation.
+  //
+  // The snapshot is taken on a THROWAWAY SPAN. It is not part of the recording
+  // the player replays — it is a CH diagnostic in the vendor namespace — so
+  // numbering it into the live span would tell the live recording that the
+  // player holds nodes it was never sent, and suppress the next patch for each
+  // of them (span.js, D1). Its ids are internal to itself and start at 1; a
+  // reader compares it to the recording by structure, not by id.
+  //
+  // The violation itself is a session-level vendor entry, not an event: spec
+  // §5.8 admits no vendor event types in the stream, and there is no standard
+  // event for "the participant left fullscreen".
+  function guardSnapshot() {
+    var tree = serializeTree(root, createSpan(), opts);
+    var cap = rec.config.maxCharsPerTrial;
+    // Bounded by the same budget a keyframe is: this is a whole second copy of
+    // the DOM, and unlike a keyframe it rides a session-level array that no
+    // per-trial cap can see.
+    if (cap != null && payloadChars(tree) > cap) {
+      rec.captureFailure('guard_violation', new Error(
+        'pre-scramble DOM snapshot exceeds maxCharsPerTrial ' + cap + '; withheld'));
+      return null;
+    }
+    return tree;
+  }
+
   if (win.GuardFriction && typeof win.GuardFriction.onViolation === 'function') {
     try {
       // Late-subscription hardening: if a violation is ALREADY in progress
@@ -532,14 +545,13 @@ export function attachDomCapture(rec, env) {
       // misses an ongoing violation.
       // Local invariant guard: assembly (index.js) only attaches captures
       // after startSession(), but make that self-evident here — synthesize
-      // only when the recorder is actually recording, so no wiring change
-      // can ever route this through a pre-session pushEvent.
+      // only when the recorder is actually recording.
       var recState = rec.getState().state;
       if ((recState === 'session' || recState === 'trial') &&
           typeof win.GuardFriction.getCurrentState === 'function') {
         var gs = win.GuardFriction.getCurrentState();
         if (gs && gs.in_violation) {
-          rec.pushEvent('ch:guard_violation', {
+          rec.pushGuardViolation({
             reason: gs.current_reason || 'unknown',
             phase: 'start',
             synthesized_at_subscribe: true,
@@ -548,20 +560,20 @@ export function attachDomCapture(rec, env) {
             // whatever the DOM looks like right now, and its name must not
             // overclaim (an analyst could otherwise read scrambled content
             // as what the participant "really saw" pre-violation).
-            dom_at_subscribe: serializeDom(resolveRoot(), opts)
+            dom_at_subscribe: guardSnapshot()
           }, now());
         }
       }
       win.GuardFriction.onViolation(function (violation) {
         try {
           if (violation && violation.phase === 'start') {
-            rec.pushEvent('ch:guard_violation', {
+            rec.pushGuardViolation({
               reason: violation.reason,
               phase: 'start',
-              pre_scramble_dom: serializeDom(resolveRoot(), opts)
+              pre_scramble_dom: guardSnapshot()
             }, now());
           } else if (violation && violation.phase) {
-            rec.pushEvent('ch:guard_violation', {
+            rec.pushGuardViolation({
               reason: violation.reason, phase: violation.phase,
               duration_ms: violation.duration != null ? violation.duration : null
             }, now());