npm - cyborg-hunter - Versions diffs - 0.7.5 → 0.9.0 - Mend

cyborg-hunter 0.7.5 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/CHANGELOG.md +74 -0
package/CITATION.cff +2 -2
package/README.md +22 -7
package/dist/cyborg-hunter-replay.js +3 -3
package/dist/cyborg-hunter.esm.js +5 -2
package/dist/cyborg-hunter.min.js +3 -3
package/dist/extension-cyborg-hunter.js +1 -1
package/package.json +10 -2
package/src/cli/analyzers/score-weights.js +145 -0
package/src/cli/analyzers/triage.js +55 -39
package/src/cli/config.js +15 -0
package/src/cli/ingest.js +311 -57
package/src/cli/renderers/html-index-core.js +88 -22
package/src/cli/renderers/html-index.js +7 -5
package/src/cli/renderers/replay-assets.js +61 -7
package/src/cli/renderers/replay-client-source.js +102 -0
package/src/cli/renderers/replay-viewer.client.js +1750 -595
package/src/cli/renderers/score-weights.js +16 -0
package/src/cli/renderers/summary-csv.js +2 -0
package/src/cli/renderers/trajectories-core.js +2 -1
package/src/cli/renderers/triage-md.js +9 -2
package/src/cli/report.js +16 -3
package/src/core/monitor.js +12 -13
package/src/jspsych/extension-cyborg-hunter-replay.js +64 -3
package/src/jspsych/extension-cyborg-hunter.js +1 -1
package/src/replay/capture-dom.js +470 -458
package/src/replay/capture-trace.js +688 -271
package/src/replay/delivery.js +82 -0
package/src/replay/dom-instantiate.js +779 -0
package/src/replay/index.js +88 -5
package/src/replay/initial-state.js +295 -0
package/src/replay/mutations.js +668 -0
package/src/replay/node-registry.js +116 -0
package/src/replay/persistence.js +19 -6
package/src/replay/recorder.js +342 -73
package/src/replay/redaction.js +165 -0
package/src/replay/serializer.js +148 -43
package/src/replay/snapshot.js +409 -0
package/src/replay/span.js +55 -0
package/src/replay/viewer-model.js +293 -102
package/src/shared/constants.js +1 -1
package/src/shared/inline-safe.js +80 -0
package/src/shared/schema-v2-validator.js +595 -0
package/src/shared/schema.js +1 -0
package/src/shared/validation.js +1 -1
package/tools/convert/jspsych-v1-to-v2.mjs +432 -0

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

@@ -21,7 +21,10 @@
 import { VERSION, sanitizeId } from '../../shared/constants.js';
 import { decomposeScore } from '../analyzers/triage.js';
+import { resolveScoreWeights, customWeightsText, formatScore } from '../analyzers/score-weights.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 +36,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 +62,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
@@ -450,7 +460,7 @@ export async function renderIndexHtml(summaries, triage, participants, config, v
 <body data-filter="all">
   <header class="topbar">
     <h1>Cyborg Hunter Report</h1>
-    <span class="meta">${triage.length} participants &middot; v${VERSION}</span>
+    <span class="meta">${triage.length} participants &middot; v${VERSION}${scoreWeightsNote(config)}</span>
     <button class="legend-btn" type="button" aria-haspopup="dialog" aria-controls="legend-modal">Legend &#9432;</button>
   </header>
   <div class="layout">
@@ -740,11 +750,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 +766,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 +789,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 +810,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 +820,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?');
@@ -825,7 +847,8 @@ function tierOf(t) {
 //              drop, long tab-aways, AI extensions detected).
 //   warn     — soft-score-contributing signals that compound with others.
 //   muted    — diagnostic signals that are noise alone but corroborate.
-// Tone classes track scoring weights; if computeTriageScore changes, audit this.
+// Tone classes track the DEFAULT score weights (score-weights.js); custom
+// config.scoreWeights do not retone the tiles. If the defaults change, audit this.
 // `aiExtensionsCount` and `edgeExitCount` are derived (not on summary directly);
 // renderSignalGrid handles that mapping.
 const SIGNALS = [
@@ -939,7 +962,7 @@ function renderCohortRow(t) {
     <div class="cohort-row-top">
       <span class="tier-dot" data-tier="${tier}"></span>
       <span class="mono pid" title="${esc(pid)}">${esc(pid)}</span>
-      <span class="mono score">${score}</span>
+      <span class="mono score">${formatScore(score)}</span>
     </div>
     <div class="cohort-row-bot">
       <span class="reason-excerpt">${esc(reason)}</span>
@@ -1013,7 +1036,7 @@ function renderDetail(t, participant, config, visualsRendered, visualsUnavailabl
   return `<section class="participant" id="p-${sanitized}"${defaultVisible ? '' : ' hidden'}>
     ${renderDetailHeader(t, tier, participant, config)}
     ${renderSignalGrid(s, t)}
-    ${renderScoreBreakdown(t)}
+    ${renderScoreBreakdown(t, config)}
     ${renderReasonQuote(t)}
     ${renderSessionBlock(s, participant)}
     ${renderPasteEvidence(participant)}
@@ -1041,9 +1064,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 +1089,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;
@@ -1184,7 +1240,7 @@ function renderDetailHeader(t, tier, participant, config) {
     <div class="detail-header-top">
       <span class="mono pid-full">${esc(t.participantId)}</span>
       <span class="tier-pill" data-tier="${tier}">${tierLabel}</span>
-      <span class="mono score-big">${t.score}</span>
+      <span class="mono score-big">${formatScore(t.score)}</span>
     </div>
     <div class="detail-header-sub">
       ${s.trialCount ?? 0} trials · ${cps} cps · ${offTask} off-task
@@ -1193,9 +1249,12 @@ function renderDetailHeader(t, tier, participant, config) {
 }
 // Horizontal score breakdown — only non-zero contributions, ending in Total:N.
-// Sourced from decomposeScore so the displayed terms always sum to t.score.
-function renderScoreBreakdown(t) {
-  const terms = decomposeScore(t.summary || {}, t.edgeExitCount, t.hardTriggered)
+// Draws the terms rankTriage actually summed (t.terms). Rows built elsewhere
+// without terms (hand-built callers) are decomposed here with the CONFIGURED
+// weights, so the bars never disagree with a custom-weights header.
+function renderScoreBreakdown(t, config) {
+  const terms = (t.terms ?? decomposeScore(t.summary || {}, t.edgeExitCount, t.hardTriggered,
+    resolveScoreWeights(config?.scoreWeights).weights))
     .filter(([, n]) => n > 0);
   const total = t.score;
@@ -1205,17 +1264,24 @@ function renderScoreBreakdown(t) {
   const termHtml = terms.map(([label, n]) =>
     `<span class="score-term">
        <span class="label">${label}</span>
-       <span class="mono contrib">+${n}</span>
+       <span class="mono contrib">+${formatScore(n)}</span>
        <span class="bar" style="width:${barFor(n)}px"></span>
      </span>`
   ).join('');
   return `<div class="score-breakdown">
     ${termHtml}
-    <span class="score-total mono">Total: ${total}</span>
+    <span class="score-total mono">Total: ${formatScore(total)}</span>
   </div>`;
 }
+// Top-bar note, present only when config.scoreWeights changes the score from
+// the defaults: " · custom score weights: copy 5 max 3, synthetic 1".
+function scoreWeightsNote(config) {
+  const { weights, isDefault } = resolveScoreWeights(config?.scoreWeights);
+  return isDefault ? '' : ` &middot; custom score weights: ${esc(customWeightsText(weights))}`;
+}
 // Format milliseconds as "Xs" / "Xm Ys".
 function formatDuration(ms) {
   if (!ms || ms < 1000) return '0s';

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

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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'));
+}