cyborg-hunter 0.7.5 → 0.8.0

package/src/cli/renderers/html-index-core.js

@@ -22,6 +22,8 @@
 import { VERSION, sanitizeId } from '../../shared/constants.js';
 import { decomposeScore } from '../analyzers/triage.js';
 import { getByPath } from '../../shared/paths.js';
+import { inferTier } from '../../replay/viewer-model.js';
+import { inlineSafeJson, inlineSafeSrc } from '../../shared/inline-safe.js';
 
 /**
  * Renders the report's index.html as a string. `opts.replayClientSrc` is the
@@ -33,7 +35,14 @@ import { getByPath } from '../../shared/paths.js';
  * pre-split renderHtmlIndex always rendered).
  */
 export async function renderIndexHtml(summaries, triage, participants, config, visualsRendered, opts = {}) {
-  const replayClientSrc = opts.replayClientSrc ?? '';
+  // Inlining JS into an HTML <script> means owning the one sequence the HTML
+  // parser reacts to (see src/shared/inline-safe.js for both rules and the
+  // precondition the source rule carries). Without it, one comment discussing
+  // script-end-tag breakouts — two of the v2 replay modules have one —
+  // truncates the whole viewer and the report boots with a SyntaxError. This
+  // was hand-rolled in nine places and missing from exactly this one, which is
+  // why the rule now lives in one module (T5 Task 10 + its fix round 3).
+  const replayClientSrc = inlineSafeSrc(opts.replayClientSrc);
   const visualsUnavailableNote = opts.visualsUnavailableNote
     ?? 'Visual renderers not available (install the canvas package).';
   const imageSources = opts.imageSources ?? null;       // pid → {typingProfile, sessionTimeline, trajectories} data URIs (null entry = omit that img)
@@ -52,11 +61,11 @@ export async function renderIndexHtml(summaries, triage, participants, config, v
 
   // Preloaded replay models (demo mode only) — embedded ahead of the replay
   // client script so window.__chReplay exists before any viewer code runs.
-  // '<' chars are escaped to a six-character JS unicode escape sequence (not
-  // the literal char) so a "</script>" inside the JSON can't prematurely
-  // close this tag.
+  // This is DATA, so it takes the every-`<` rule (inline-safe.js rule 1),
+  // which is both lossless inside a JSON string and complete: no `<` survives
+  // for the HTML tokenizer to react to, in any of its states.
   const preloadedReplayScript = inlineReplayModels
-    ? `<script>/* preloaded replay models (demo mode) */window.__chReplay = ${JSON.stringify(inlineReplayModels).replace(/</g, '\\u003c')};</script>\n  `
+    ? `<script>/* preloaded replay models (demo mode) */window.__chReplay = ${inlineSafeJson(inlineReplayModels)};</script>\n  `
     : '';
 
   // Hash-sync emission for the rail click handler (selectById, below): demo
@@ -740,11 +749,13 @@ export async function renderIndexHtml(summaries, triage, participants, config, v
     .replay-note { font-size: 12px; color: var(--dim); }
     .replay-warn { color: var(--hard); }
     /* Controls share the report's flat, line-bordered button style */
-    .replay-play, .replay-load-btn, .replay-css-btn, .replay-trial-select, .replay-speed {
+    .replay-play, .replay-load-btn, .replay-css-btn, .replay-segment-select, .replay-speed {
       padding: 4px 10px; border: 1px solid var(--line); background: var(--surface);
       color: var(--ink); border-radius: 4px; cursor: pointer; font-size: 13px; }
     .replay-play:hover, .replay-load-btn:hover, .replay-css-btn:hover { background: var(--bg); }
     .replay-play:disabled, .replay-load-btn:disabled { opacity: 0.6; cursor: default; }
+    .replay-fetch-css-label { margin-left: 10px; font-size: 12px; color: #555; }
+    .replay-unstyled { position: absolute; left: 0; right: 0; top: 0; z-index: 3; background: #fff4dd; color: #7a4b00; border-bottom: 1px solid #e8b24a; padding: 6px 10px; font-size: 12px; line-height: 1.4; }
     .replay-css-btn { font-size: 12px; padding: 2px 8px; }
     .replay-clock { font: 12px/1.3 ui-monospace, SFMono-Regular, 'IBM Plex Mono', monospace;
                     font-variant-numeric: tabular-nums; }
@@ -754,6 +765,13 @@ export async function renderIndexHtml(summaries, triage, participants, config, v
                     background: rgba(0,0,0,0.72); color: #fff; padding: 2px 7px;
                     border-radius: 3px; white-space: nowrap; }
     .replay-key-chip--redacted { background: rgba(0,0,0,0.5); font-style: italic; }
+    /* Media is reported as state, never played (design §7): the badges say what
+       the recorded element was doing, in the stage's top-left. */
+    .replay-media { position: absolute; left: 0; top: 0; display: flex; gap: 4px;
+                    padding: 5px 6px; pointer-events: none; flex-wrap: wrap; }
+    .replay-media-badge { font: 11px/1.2 ui-monospace, SFMono-Regular, 'IBM Plex Mono', monospace;
+                    background: rgba(0,137,123,0.85); color: #fff; padding: 2px 7px;
+                    border-radius: 3px; white-space: nowrap; }
   </style>
   ${preloadedReplayScript}<script>
 ${replayClientSrc}
@@ -770,6 +788,9 @@ ${replayClientSrc}
         const src = block.dataset.replaySrc;
         const pid = block.dataset.pid;
         const mount = block.querySelector('.replay-mount');
+        // Read the fetch decision before the mount is cleared.
+        const fetchBox = block.querySelector('.replay-fetch-css');
+        const viewerOpts = { externalCss: !!(fetchBox && fetchBox.checked) };
         btn.disabled = true;
         btn.textContent = 'Loading…';
         mount.setAttribute('aria-busy', 'true');
@@ -788,7 +809,7 @@ ${replayClientSrc}
         if (preloaded) {
           mount.removeAttribute('aria-busy');
           mount.textContent = '';
-          window.initChReplayViewer(mount, preloaded);
+          window.initChReplayViewer(mount, preloaded, viewerOpts);
           return;
         }
         ` : ''}const s = document.createElement('script');
@@ -798,7 +819,7 @@ ${replayClientSrc}
           const model = (window.__chReplay || {})[pid];
           if (!model) { fail('Replay data failed to load (' + src + ').'); return; }
           mount.textContent = '';
-          window.initChReplayViewer(mount, model);
+          window.initChReplayViewer(mount, model, viewerOpts);
         };
         s.onerror = function () {
           fail('Replay asset missing (' + src + ') — was the report generated with the replay artifacts present?');
@@ -1041,9 +1062,20 @@ function renderReplaySection(participant, sanitized, demoModel = null, replaySho
   if (!participant) return '';
   const replay = participant?.replay;
   if ((replay && replay.recording) || demoModel) {
+    // Tier badge. The recording branch reads the v2 site
+    // (extensions['cyborg-hunter'].tier) and falls back to the structural
+    // inference, through the SAME helper the viewer model uses — reading the
+    // tier off a v1 `metadata` block badged every v2 recording "trace",
+    // because v2 has no such block (the tier moved in serializer.js:145).
+    // The demo branch takes `demoModel.tier`: `inlineReplayModels` holds
+    // VIEWER MODELS (see the opts docblock above), and a viewer model has
+    // never had a `metadata` block in any version — that read resolved to
+    // "trace" for every model ever passed. Suspected-dead branch
+    // (demo/tests/tour.spec.js:420 records that the demo stopped passing
+    // inlineReplayModels), fixed rather than deleted.
     const tier = demoModel
-      ? (demoModel.metadata?.tier || 'trace')
-      : (replay.recording.metadata?.tier || 'trace');
+      ? (demoModel.tier || 'trace')
+      : inferTier(replay.recording);
     // assetPath is stamped by replay-assets.js (collision-deduped filename)
     // and must be preferred — recomputing from the sanitized pid here would
     // resurrect the lossy-name collision the assets renderer just resolved.
@@ -1055,18 +1087,40 @@ function renderReplaySection(participant, sanitized, demoModel = null, replaySho
     // preloadedReplayScript in renderIndexHtml), so the block is marked
     // data-replay-preloaded instead of pointing the lazy loader at a file
     // that doesn't exist in the sandboxed iframe.
+    // Sheets the capture could not inline (cross-origin, fetch refused) are
+    // href-only. Offer the fetch decision HERE, beside the one button, ticked
+    // by default: an unstyled replay is misaligned by construction, and the
+    // in-viewer opt-in went unread through a whole session (2026-09-03).
+    // Rendered only when it applies, so recordings with inlined CSS keep the
+    // exact markup the snapshot tests pin.
+    const externalSheets = replay && replay.recording
+      ? (replay.recording.stylesheets || []).filter((sh) => sh && sh.kind === 'link' && sh.css == null).length
+      : 0;
+    const fetchCssLabel = externalSheets > 0
+      ? `
+        <label class="replay-fetch-css-label"><input type="checkbox" class="replay-fetch-css" checked> also fetch ${externalSheets} external stylesheet${externalSheets === 1 ? '' : 's'} from ${externalSheets === 1 ? 'its origin' : 'their origins'} (needed for a styled, aligned replay)</label>`
+      : '';
     return `<div class="image-block replay-block" data-pid="${esc(participant.participantId)}"
          ${demoModel ? 'data-replay-preloaded="true"' : `data-replay-src="${esc(assetPath)}"`}>
       <h4 class="section-heading">Session replay <span class="replay-note">(${esc(tier)} tier)</span></h4>
       <div class="replay-mount">
-        <button class="replay-load-btn" type="button">Load replay</button>
+        <button class="replay-load-btn" type="button">Load replay</button>${fetchCssLabel}
       </div>
     </div>`;
   }
   if (replay && replay.error) {
+    // Two ways an attached artifact fails to reach the viewer, and the
+    // analyst needs to tell them apart: 'parse_failed' (ingest could not read
+    // the file at all) and 'unloadable' (the file parsed but the §11 tolerant
+    // profile rejected it — a CH-v1 artifact is the common case, and there is
+    // no v1 playback path). Calling a readable v1 file "corrupted" would send
+    // the analyst looking for a truncated upload.
+    const lead = replay.error === 'unloadable'
+      ? 'Replay artifact could not be loaded'
+      : 'Replay artifact corrupted';
     return `<div class="image-block replay-block">
       <h4 class="section-heading">Session replay</h4>
-      <p class="replay-note replay-warn">Replay artifact corrupted (${esc(replay.reason || replay.error)}) — file: ${esc(replay.file || 'unknown')}</p>
+      <p class="replay-note replay-warn">${lead} (${esc(replay.reason || replay.error)}) — file: ${esc(replay.file || 'unknown')}</p>
     </div>`;
   }
   const meta = participant?.trials?.[0]?.integrityReplayMeta;

package/src/cli/renderers/html-index.js

@@ -2,15 +2,17 @@
 // Thin Node wrapper around the pure render core (html-index-core.js):
 // reads the replay viewer client from disk, writes index.html to outputDir.
 // Public API unchanged — report.js and adopters keep calling renderHtmlIndex.
-import { writeFileSync, readFileSync } from 'fs';
+import { writeFileSync } from 'fs';
 import { join } from 'path';
 import { renderIndexHtml } from './html-index-core.js';
+import { readReplayClientSrc } from './replay-client-source.js';
 
-// The replay viewer client is developed as a real JS file (linted, syntax-
+// The replay viewer client is developed as real JS files (linted, syntax-
 // highlighted) and embedded verbatim at render time — same file://-safe
-// output as the inline IIFE, without string-blob development pain.
-const REPLAY_CLIENT_SRC = readFileSync(
-  new URL('./replay-viewer.client.js', import.meta.url), 'utf8');
+// output as an inline IIFE, without string-blob development pain. It is a
+// CONCATENATION: the client calls into src/replay/dom-instantiate.js, which
+// ships ahead of it in the same script (see replay-client-source.js).
+const REPLAY_CLIENT_SRC = readReplayClientSrc();
 
 export async function renderHtmlIndex(summaries, triage, participants, config, visualsRendered) {
   const html = await renderIndexHtml(summaries, triage, participants, config,

package/src/cli/renderers/replay-assets.js

@@ -16,6 +16,7 @@ import { join } from 'path';
 
 import { sanitizeId as sanitize } from '../../shared/constants.js';
 import { buildViewerModel } from '../../replay/viewer-model.js';
+import { inlineSafeJson } from '../../shared/inline-safe.js';
 
 // Load-bearing re-export: renderReplayAssets (below) calls buildViewerModel
 // in-file, and tests/cli/replay-render.test.js + tests/replay/alignment-viewer-model.test.js
@@ -24,17 +25,55 @@ export { buildViewerModel };
 
 /**
  * Writes replay/<sanitizedPid>.replay.js for every participant with an
- * attached recording. Returns { count, totalBytes } so report.js can print
- * an honest size line (replay assets dominate report size at dom tier).
+ * attached recording. Returns { count, totalBytes, skipped } so report.js can
+ * print an honest size line (replay assets dominate report size at dom tier)
+ * and an honest line about what did not make it.
+ *
+ * `skipped` is [{participantId, file, reason}] — one entry per artifact that
+ * exists, reads fine, and still never reaches the viewer. Two things produce
+ * one, and they are the same event seen at different layers:
+ *
+ *   - the §11 tolerant profile rejecting a recording here. buildViewerModel
+ *     THROWS on that set (it is v2-only; a CH-v1 artifact is the common case),
+ *     and the alternative to catching is that one unloadable file in a cohort
+ *     aborts the whole report — precisely the data-loss trade §11 exists to
+ *     refuse. v1 degraded and rendered the rest; v2 skips the participant and
+ *     says so.
+ *   - a refusal already stamped by INGEST (A3): a jsPsych v1 recording the
+ *     converter would not migrate, which never gets as far as a model. Task
+ *     10(b) settled that a replay which does not make it is visible on three
+ *     surfaces, and the CLI line report.js prints from this list is one of
+ *     them, so both origins have to be accounted for here or the console is a
+ *     partial account.
+ *
+ * A corrupted file (ingest's `parse_failed`) deliberately stays out: it keeps
+ * its own report lead text and its own ingest warning.
+ *
+ * The say-so is a stamp on `p.replay`, read by renderReplaySection's error
+ * branch — the report's existing state for "attached but not viewable".
+ * Repeated calls now return the same list (both classes are recognised from
+ * the stamp), which retires the non-idempotence noted at T5 Task 10 review
+ * M-5. One caller today (`report.js:149`), which renders the index from the
+ * same array.
  */
 export function renderReplayAssets(participants, outputDir) {
   let count = 0;
   let totalBytes = 0;
+  const skipped = [];
+  for (const p of participants) {
+    if (p.replay && !p.replay.recording && p.replay.error === 'unloadable') {
+      skipped.push({ participantId: p.participantId, file: p.replay.file || null,
+        reason: p.replay.reason || p.replay.error });
+    }
+  }
   const withReplay = participants.filter((p) => p.replay && p.replay.recording);
-  if (withReplay.length === 0) return { count, totalBytes };
+  if (withReplay.length === 0) return { count, totalBytes, skipped };
 
+  // Created on the first successful write, not up front: a cohort whose
+  // every artifact is unloadable would otherwise ship an empty replay/ dir
+  // beside a report that says there is nothing to load.
   const replayDir = join(outputDir, 'replay');
-  mkdirSync(replayDir, { recursive: true });
+  let dirMade = false;
 
   // Sanitization is lossy ('a/b' and 'a_b' both map to a_b) — dedupe with a
   // stable numeric suffix so a later write can never overwrite an earlier
@@ -42,7 +81,21 @@ export function renderReplayAssets(participants, outputDir) {
   // (replay.assetPath) and consumed by html-index, which must not recompute.
   const usedNames = new Set();
   for (const p of withReplay) {
-    const model = buildViewerModel(p.replay.recording);
+    let model;
+    try {
+      model = buildViewerModel(p.replay.recording);
+    } catch (e) {
+      // Skip this participant, keep the cohort. The recording is dropped from
+      // the participant so the index cannot render a Load button for an asset
+      // that was never written; `error: 'unloadable'` distinguishes it from
+      // ingest's 'parse_failed' (a file that could not even be read).
+      // `e.reasons` is the §11 profile's own list; the message wrapper adds
+      // a function name the analyst has no use for.
+      const reason = Array.isArray(e.reasons) ? e.reasons.join('; ') : e.message;
+      skipped.push({ participantId: p.participantId, file: p.replay.file || null, reason });
+      p.replay = { error: 'unloadable', reason, file: p.replay.file || null };
+      continue;
+    }
     // The store is keyed by the RAW participant id (what the report's
     // loader passes); the filename uses the sanitized form.
     // Null-prototype store: participant ids are untrusted, and a pid like
@@ -51,17 +104,18 @@ export function renderReplayAssets(participants, outputDir) {
     const src =
       'window.__chReplay = window.__chReplay || Object.create(null);\n' +
       'window.__chReplay[' + JSON.stringify(String(p.participantId)) + '] = ' +
-      JSON.stringify(model).replace(/</g, '\\u003c') + ';\n';
+      inlineSafeJson(model) + ';\n';
     let base = sanitize(p.participantId);
     let name = base + '.replay.js';
     for (let n = 2; usedNames.has(name.toLowerCase()); n++) {
       name = base + '~' + n + '.replay.js';
     }
     usedNames.add(name.toLowerCase());
+    if (!dirMade) { mkdirSync(replayDir, { recursive: true }); dirMade = true; }
     writeFileSync(join(replayDir, name), src);
     p.replay.assetPath = 'replay/' + name;
     count++;
     totalBytes += Buffer.byteLength(src);
   }
-  return { count, totalBytes };
+  return { count, totalBytes, skipped };
 }

package/src/cli/renderers/replay-client-source.js

@@ -0,0 +1,102 @@
+// src/cli/renderers/replay-client-source.js
+// The report's viewer script, ASSEMBLED — the one place that knows the viewer
+// client is a concatenation rather than a file.
+//
+// T5 Task 2 recorded the decision this module executes: `replay-viewer.client.js`
+// calls `mountTree`/`applyPatch`/`applyPatches` out of `src/replay/dom-instantiate.js`,
+// and the client is a plain IIFE inlined verbatim into an HTML report — it
+// cannot `import`. The two ways to give it those functions are (a) the client
+// carries its own copy, which would put two readings of spec §4 in the repo,
+// which is the failure this migration exists to remove, or (b) the build
+// concatenates the module ahead of the client with its single `export` line
+// stripped. (b) is the decision, and `tests/replay/dom-instantiate.test.js`
+// machine-checks that the module stays concatenable — no imports, exactly one
+// strippable ESM statement, strict-safe.
+//
+// The concatenation is wrapped in ONE `'use strict'` IIFE so the module's ~35
+// top-level `var`s and helper functions (`bind`, `resolve`, `result`, …) never
+// reach the report page's global scope, where they would collide with the
+// report's own scripts. The client's own IIFE nests inside it and closes over
+// them; `window.initChReplayViewer` is still assigned, which is the whole
+// public surface.
+//
+// FIVE consumers were surveyed at Task 2 and are routed as follows:
+//   html-index.js                      → this module (the shipped report)
+//   tools/assemble-demo-site.mjs       → this module (writes the ASSEMBLED file,
+//                                        which demo/results.js fetches by name)
+//   cursor-alignment.battery.mjs       → this module (Task 8's harness)
+//   tools/investigate/probe-support.mjs → NOT a consumer of the assembly: it
+//                                        extracts the literal `srcdocCsp()` out
+//                                        of the client source and needs the raw
+//                                        file, not the bundle.
+//   tools/investigate/cursor-alignment-probe.mjs → superseded (Task 1).
+
+import { readFileSync } from 'fs';
+
+import { inlineSrcHazards } from '../../shared/inline-safe.js';
+
+// The one ESM statement `dom-instantiate.js` is allowed to carry. The same
+// literal appears in that module's own concatenability test; if it drifts, this
+// throws rather than shipping a report whose viewer has a stray `export`.
+const EXPORT_BLOCK = /^export \{[^}]*\};$/m;
+
+const MODULE_URL = new URL('../../replay/dom-instantiate.js', import.meta.url);
+const CLIENT_URL = new URL('./replay-viewer.client.js', import.meta.url);
+
+/**
+ * The assembly itself, over sources rather than paths, so every contract the
+ * assembled script has to satisfy can be exercised with a constructed
+ * violation instead of by editing shipped files.
+ *
+ * @param {string} mod     src/replay/dom-instantiate.js
+ * @param {string} client  src/cli/renderers/replay-viewer.client.js
+ * @returns {string} the two inside one strict IIFE
+ * @throws {Error} on any of the three contract violations below
+ */
+export function assembleReplayClientSrc(mod, client) {
+  if (!EXPORT_BLOCK.test(mod)) {
+    throw new Error(
+      'replay-client-source: dom-instantiate.js no longer ends in a single strippable ' +
+      '`export { … };` line — the concatenation contract (T5 Task 2) is broken. ' +
+      'Fix the module, not this assembler.');
+  }
+  if (/^\s*import\b/m.test(mod)) {
+    throw new Error(
+      'replay-client-source: dom-instantiate.js grew an import; a plain script ' +
+      'concatenation cannot resolve it.');
+  }
+  const out = "(function () {\n'use strict';\n" +
+    mod.replace(EXPORT_BLOCK, '') + '\n' +
+    client + '\n})();\n';
+  // Third contract, and the reason it is HERE (T5 Task 10 fix round 3, review
+  // I-1): every consumer of this function inlines the result into an HTML
+  // `<script>`, and `inlineSafeSrc` — the rule they all apply — neutralises
+  // `</script` and cannot neutralise the script-data-ESCAPED breakout. An
+  // unpaired `<!--` followed by a `<script`, in a comment or a string, makes
+  // the parser swallow the page's own closing tag: the viewer never boots and
+  // NOTHING is logged. That is strictly worse than the truncation Task 10
+  // fixed, which at least raised a SyntaxError. The escape cannot be widened
+  // safely (see inline-safe.js), so the precondition is asserted instead —
+  // loudly, at build time, on the day a comment mentioning HTML lands.
+  const hazards = inlineSrcHazards(out);
+  if (hazards.length) {
+    throw new Error(
+      'replay-client-source: the assembled viewer cannot be safely inlined into a ' +
+      '<script> element — it ' + hazards.join('; and it ') + '. Such a sequence puts ' +
+      'the HTML parser into script-data-escaped state, where the report\'s own ' +
+      '</script> no longer closes the element and the viewer silently never boots. ' +
+      'Reword the source (a comment mentioning HTML is the usual cause); do NOT ' +
+      'widen the escape, which would change the meaning of regex literals.');
+  }
+  return out;
+}
+
+/**
+ * @returns {string} the viewer script as the report inlines it: the §4
+ *   instantiation/patch module and the viewer client inside one strict IIFE.
+ */
+export function readReplayClientSrc() {
+  return assembleReplayClientSrc(
+    readFileSync(MODULE_URL, 'utf8'),
+    readFileSync(CLIENT_URL, 'utf8'));
+}