cyborg-hunter 0.5.0 → 0.7.2

package/src/cli/ingest.js

@@ -4,7 +4,7 @@
 //   1. JSON Shape 1 — { participantId: 'P1', trials: [{ integrity: {...} }] }
 //      jsPsych extension data with one file per participant.
 //   2. JSON Shape 2 — { metadata: {...}, responses: [{ mouseTrack, tabAwayEvents, ... }] }
-//      The original rule-gallery format. Signal data lives flat on each response
+//      The original legacy format. Signal data lives flat on each response
 //      (no `integrity` wrapper). Pre-dates the standalone library.
 //   3. CSV — jsPsych default save format. Each row is a trial; nested objects
 //      (integrity, integritySession, integrityScore) are JSON-stringified into
@@ -12,19 +12,71 @@
 
 import { readFileSync, readdirSync } from 'fs';
 import { join, extname } from 'path';
+import { gunzipSync } from 'zlib';
 import Papa from 'papaparse';
-import { TRIAL_REPORT_FIELDS } from '../shared/schema.js';
+import { sanitizeId } from '../shared/constants.js';
+import { getByPath } from '../shared/paths.js';
+import { extractIntegrityData, ruleChronologicalCompare } from './extract-core.js';
+
+// Replay artifacts saved by the replay extension:
+//   <sanitizedPid>-replay-<sessionStartEpochMs>.json[.gz]
+// They sit in dataDir (or replayDir) next to the participant files and must
+// never enter the participant-file pass.
+const REPLAY_FILE_RE = /-replay-\d+\.json(\.gz)?$/i;
+
+// Content sniff: replay artifacts (ours or #3661's) are identified by
+// structure, not just filename — schema_version plus either our recorder
+// stamp or a #3661-shaped trials array.
+function looksLikeReplayArtifact(text) {
+  try {
+    const j = JSON.parse(text);
+    return j && typeof j === 'object' && 'schema_version' in j &&
+      (String(j.metadata?.recorder || '').startsWith('cyborg-hunter-replay') ||
+        (Array.isArray(j.trials) && j.trials.length > 0 &&
+          j.trials.every(t => t && 'events' in t && 'initial_dom' in t)));
+  } catch (e) {
+    return true;   // unparseable + replay-named → let the replay pass report it
+  }
+}
 
 export async function ingest(config) {
-  const files = findFiles(config.dataDir, config.filePattern);
+  const allFiles = findFiles(config.dataDir, config.filePattern);
   const participants = [];
   const warnings = [];
 
+  // Replay artifacts are excluded from the participant pass by filename —
+  // but only after a content check, so a participant export that happens to
+  // match the naming pattern is never silently dropped.
+  const files = [];
+  for (const file of allFiles) {
+    if (REPLAY_FILE_RE.test(file)) {
+      let text = null;
+      try { text = readFileSync(file, 'utf8'); } catch (e) { text = null; }
+      let parseable = true;
+      if (text !== null) {
+        try { JSON.parse(text); } catch (e) { parseable = false; }
+      }
+      if (text === null || !parseable) {
+        // Never let a replay-named file vanish silently: if its pid maps to
+        // a discovered participant the attach pass warns again with more
+        // context, but an orphan (no matching participant) would otherwise
+        // disappear without a trace.
+        warnings.push({ file,
+          warnings: ['Replay-named file could not be parsed (truncated upload or a misnamed participant export?) — skipped from the participant pass; if a matching participant exists, the replay pass reports it too.'] });
+        continue;
+      }
+      if (looksLikeReplayArtifact(text)) continue;
+      warnings.push({ file,
+        warnings: ['File matches the replay-artifact naming pattern (<pid>-replay-<epoch>.json) but contains participant data — parsed as a participant file. Consider renaming it to avoid ambiguity.'] });
+    }
+    files.push(file);
+  }
+
   for (const file of files) {
     try {
       const text = readFileSync(file, 'utf8');
       // Branch by extension. CSV is jsPsych's default save format; JSON is what
-      // rule-gallery and other server-side-saving experiments use.
+      // server-side-saving experiments use.
       const raw = extname(file).toLowerCase() === '.csv'
         ? parseCsvToRaw(text, config)
         : JSON.parse(text);
@@ -46,214 +98,216 @@ export async function ingest(config) {
     }
   }
 
-  return { participants, warnings };
-}
-
-// Extracts integrity trial data from a single participant's raw JSON.
-// Returns { participantId, trials, warnings, metadata }.
-export function extractIntegrityData(raw, config) {
-  const warnings = [];
-  const pidField = config.participantIdField || 'participantId';
-  const intField = config.integrityField || 'integrity';
-
-  // Determine participant ID — check top level, then metadata sub-object
-  const participantId = raw[pidField] || raw.metadata?.[pidField] || 'unknown';
-
-  let trials = [];
-
-  // Shape 1: { trials: [{ integrity: {...} }, ...] } — jsPsych extension data.
-  // Each trial has an `integrity` sub-object added by CyborgHunter.endTrial().
-  if (Array.isArray(raw.trials)) {
-    trials = raw.trials
-      .filter(t => t[intField])
-      .map(t => t[intField]);
-    // jsPsych extension data carries trialStart_perfNow per trial (set by the
-    // wrapper's on_load), so normalization takes the exact-subtraction fast
-    // path. Without it, renderers see only session-absolute `start` values
-    // and plot tab-away markers far off the per-trial axis.
-    normalizeTabAwayTimestamps(trials, raw);
-  }
-  // Shape 2: { responses: [{ mouseTrack, tabAwayEvents, ... }] } (rule-gallery legacy format)
-  // Signal data lives directly on the response — no integrity wrapper.
-  // We apply field name mapping (mouseTrack → mouseEvents).
-  else if (Array.isArray(raw.responses)) {
-    trials = raw.responses.map((r, i) => mapLegacyFields({
-      ...r,
-      _sourceIndex: i
-    }));
-    // Normalize tab-away timestamps from session-relative performance.now()
-    // to trial-relative milliseconds so renderers can plot them on the
-    // same x-axis as mouseEvents[].t (which is already trial-relative).
-    normalizeTabAwayTimestamps(trials, raw);
-  }
-  // Shape 3: Top-level array of trials
-  else if (Array.isArray(raw)) {
-    trials = raw.filter(t => t[intField]).map(t => t[intField]);
-  }
-
-  if (trials.length === 0) {
-    warnings.push(`No integrity data found (looked for "${intField}" field)`);
-  }
-
-  // Validate each trial has the minimum required fields from the schema.
-  // Missing fields get a warning but don't prevent analysis.
-  for (const trial of trials) {
-    const missing = [];
-    for (const [field, spec] of Object.entries(TRIAL_REPORT_FIELDS)) {
-      if (spec.required && trial[field] === undefined) {
-        missing.push(field);
-      }
-    }
-    if (missing.length > 0) {
-      warnings.push(`Trial ${trial.trialId || '?'}: missing fields: ${missing.join(', ')}`);
+  // Duplicate-upload guard. Two files resolving to the same participantId are
+  // conflated downstream (triage/HTML/image outputs key by id), so the second
+  // upload's evidence can silently overwrite or vanish. We do NOT auto-dedup —
+  // the analyst must decide which upload is canonical — but we surface it.
+  // (attachReplayArtifacts below adds its own duplicate-id note describing the
+  // replay-association consequence specifically.)
+  const idCounts = new Map();
+  for (const p of participants) idCounts.set(p.participantId, (idCounts.get(p.participantId) || 0) + 1);
+  for (const [id, n] of idCounts) {
+    if (n > 1) {
+      warnings.push({ file: '(multiple)', warnings: [
+        `duplicate participantId "${id}" appears in ${n} files — downstream ` +
+        `outputs key by id, so entries may be conflated. Keep one upload per participant.`
+      ] });
     }
   }
 
-  const { session, score } = findSessionData(raw);
-  if (session === null && trials.length > 0) {
-    warnings.push('No session-level integrity data — some signals unavailable (did the experiment call getSessionReport()?)');
-  }
+  attachReplayArtifacts(participants, config, warnings);
 
-  return { participantId, trials, warnings, metadata: raw.metadata || {}, session, score };
+  return { participants, warnings };
 }
 
-// Locates session-level integrity data in one of three locations, in priority order:
-//   1. raw.metadata.integritySession / integrityScore — the card-games convention.
-//   2. Last trial's integritySession / integrityScore — jsPsych addDataToLastTrial (Option A).
-//   3. Any trial's integritySession — fallback (Option B).
-// Returns { session, score }, both null if not found.
-function findSessionData(raw) {
-  // 1. card-games metadata convention
-  if (raw.metadata?.integritySession) {
-    return { session: raw.metadata.integritySession, score: raw.metadata.integrityScore || null };
-  }
-  // 2. jsPsych addDataToLastTrial convention (Option A)
-  if (Array.isArray(raw.trials) && raw.trials.length > 0) {
-    const last = raw.trials[raw.trials.length - 1];
-    if (last?.integritySession) {
-      return { session: last.integritySession, score: last.integrityScore || null };
+// Finds and attaches each participant's replay artifact (if any) as
+// `participant.replay`:
+//   { recording, file, meta }            — parsed and attached
+//   { error: 'parse_failed', reason }    — artifact exists but unreadable
+//   null                                 — no artifact (silent unless meta
+//                                          says one went to 'download')
+function attachReplayArtifacts(participants, config, warnings) {
+  const dir = config.replayDir || config.dataDir;
+  let entries = [];
+  try {
+    entries = readdirSync(dir);
+  } catch (e) {
+    if (config.replayDir) {
+      warnings.push({ file: dir, warnings: [`replayDir not readable: ${e.message}`] });
     }
   }
-  // 3. Any-trial fallback
-  if (Array.isArray(raw.trials)) {
-    const t = raw.trials.find(x => x?.integritySession);
-    if (t) return { session: t.integritySession, score: t.integrityScore || null };
-  }
-  return { session: null, score: null };
-}
-
-// Maps rule-gallery legacy field names to CyborgHunter schema names.
-// The CLI can then use a single set of field names downstream.
-const LEGACY_FIELD_MAP = {
-  mouseTrack: 'mouseEvents',
-};
 
-// Normalizes tabAwayEvents[*].start from session-relative performance.now()
-// (ms since browser navigation) to trial-relative ms (ms since this trial
-// began), stored as a new `startRel_ms` field. Renderers plot per-trial
-// against trial-relative time; without normalization, tab-away markers
-// land tens of thousands of ms off the right edge — invisible.
-//
-// Two paths:
-//   FAST PATH — every trial has a per-trial performance.now() anchor (either
-//     trialStart_perfNow set by the jsPsych wrapper, or startTime set by the
-//     standalone monitor). Subtract directly; result is exact.
-//   ESTIMATOR PATH — rule-gallery / pre-monitor data has neither anchor.
-//     We infer the session-start performance.now() value from the
-//     relationship between trial-end wall-clocks (`timestamp`),
-//     `responseTime_ms`, and the first tab-away's session-relative `start`,
-//     then subtract the inferred offset to get a trial-relative value.
-//     Less precise than the fast path; used only when nothing better exists.
-function normalizeTabAwayTimestamps(trials, raw) {
-  // Fast path — every trial has a usable anchor.
-  const everyTrialHasAnchor = trials.length > 0 && trials.every(t =>
-    typeof (t.trialStart_perfNow ?? t.startTime) === 'number'
-  );
-  if (everyTrialHasAnchor) {
-    for (const trial of trials) {
-      const tabs = trial.tabAwayEvents;
-      if (!Array.isArray(tabs) || tabs.length === 0) continue;
-      const trialStart = trial.trialStart_perfNow ?? trial.startTime;
-      trial.tabAwayEvents = tabs.map(ta => ({
-        ...ta,
-        startRel_ms: typeof ta.start === 'number' ? ta.start - trialStart : null
-      }));
-    }
-    return;
+  // Sanitized-name census: filename sanitization is many-to-one, so a
+  // no-embedded-id artifact may only attach when exactly one participant
+  // maps to its sanitized name (otherwise ownership is ambiguous).
+  // The census is keyed on LOWERCASED sanitized ids because the filename
+  // match below is case-insensitive (macOS filesystems are) — both
+  // mechanisms must share the same equivalence classes or an ownerless
+  // artifact could attach to two case-variant participants at once.
+  // Null-prototype maps: a participant id that collides with an
+  // Object.prototype key ("__proto__", "constructor") must count like any
+  // other id — on a literal {}, assigning a primitive to __proto__ is a
+  // silent no-op, which skipped the duplicate warning AND the
+  // ambiguous-association guard below.
+  const sanitize = sanitizeId;
+  const saneCounts = Object.create(null);
+  const idCounts = Object.create(null);
+  for (const p of participants) {
+    const s = sanitize(p.participantId).toLowerCase();
+    saneCounts[s] = (saneCounts[s] || 0) + 1;
+    idCounts[p.participantId] = (idCounts[p.participantId] || 0) + 1;
   }
 
-  // Estimator path. Need a session-start wall-clock anchor; if there isn't
-  // one, we have no way to relate trial-end timestamps to a 0 reference.
-  const sessStartIso = raw.metadata?.startTime;
-  if (!sessStartIso) return;
-  const sessStartMs = Date.parse(sessStartIso);
-  if (!Number.isFinite(sessStartMs)) return;
-
-  // For each trial, compute trial-start in ms-since-session-start (wall-clock).
-  // trial-end is response.timestamp; trial-start = trial-end − duration.
-  const trialStartRels = trials.map(t => {
-    if (!t.timestamp || t.responseTime_ms == null) return null;
-    const endMs = Date.parse(t.timestamp);
-    if (!Number.isFinite(endMs)) return null;
-    return (endMs - sessStartMs) - t.responseTime_ms;
-  });
-
-  // For each trial that has ≥1 tab-away, estimate the session offset:
-  //   sessionOffset = (performance.now value at session start, in ms)
-  // The first tab-away of the trial must fall inside the trial's response
-  // window, so:
-  //   firstTabStart ∈ [sessionOffset + trialStartRel,
-  //                    sessionOffset + trialStartRel + trialDuration]
-  // Solving for sessionOffset gives an interval; we use the midpoint as
-  // each trial's candidate, then take the median across trials as the
-  // robust estimate. This is approximate but converges quickly with even
-  // a few tab-away-bearing trials.
-  const candidates = [];
-  for (let i = 0; i < trials.length; i++) {
-    const tabs = trials[i].tabAwayEvents;
-    if (!Array.isArray(tabs) || tabs.length === 0) continue;
-    const trialStartRel = trialStartRels[i];
-    const trialDurationMs = trials[i].responseTime_ms;
-    if (trialStartRel == null || trialDurationMs == null) continue;
-    const firstTabStart = tabs[0].start;
-    if (typeof firstTabStart !== 'number') continue;
-    candidates.push(firstTabStart - trialStartRel - trialDurationMs / 2);
+  // Duplicate participant ids (repeat runs, duplicate exports) are outside
+  // the pipeline's data model — every renderer keys outputs by pid, so the
+  // whole report already treats them as one person. Replay attachment
+  // follows the same semantics (both records get the same latest artifact);
+  // say so once per duplicated id instead of silently doing it.
+  for (const [id, n] of Object.entries(idCounts)) {
+    if (n > 1) {
+      warnings.push({ file: dir,
+        warnings: [`Duplicate participant id "${id}" across ${n} files — the report (including replay attachment) treats these as one person; per-session replay association is not attempted.`] });
+    }
   }
 
-  if (candidates.length === 0) return;
+  for (const p of participants) {
+    // Same sanitization the browser-side filename builder applies. The
+    // match is ANCHORED (^<sane>-replay-<digits>.json$): a bare prefix
+    // would let participant "a" swallow "a-replay-replay-<epoch>.json",
+    // which belongs to participant "a-replay".
+    const sane = sanitize(p.participantId);
+    const escaped = sane.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const exactRe = new RegExp(`^${escaped}-replay-\\d+\\.json(\\.gz)?$`, 'i');
+    const mine = entries.filter(f => exactRe.test(f));
+    // The meta pointer rides on every trial row via addProperties.
+    const meta = (p.trials && p.trials[0] && p.trials[0].integrityReplayMeta) || null;
+    // Replay finalize failures ride the same way — surface them where the
+    // analyst looks (they mean the artifact was probably never saved).
+    const finErr = p.trials && p.trials[0] && p.trials[0].replayFinalizeError;
+    if (finErr) {
+      warnings.push({ file: dir,
+        warnings: [`Replay finalize failed for ${p.participantId}: ${finErr} — the artifact was likely never saved.`] });
+    }
 
-  candidates.sort((a, b) => a - b);
-  const sessionOffset = candidates[Math.floor(candidates.length / 2)];
+    if (mine.length === 0) {
+      p.replay = null;
+      if (meta && meta.saved_to === 'download') {
+        warnings.push({
+          file: dir,
+          warnings: [`Replay artifact for ${p.participantId} was downloaded to the participant's machine (autoSave mode "download") and is not recoverable from here — check the autosave configuration for future runs.`]
+        });
+      }
+      continue;
+    }
 
-  // Apply normalization. Original `start` is preserved alongside `startRel_ms`
-  // so consumers can still see the absolute time if they want it.
-  for (let i = 0; i < trials.length; i++) {
-    const tabs = trials[i].tabAwayEvents;
-    if (!Array.isArray(tabs) || tabs.length === 0) continue;
-    const trialStartRel = trialStartRels[i];
-    if (trialStartRel == null) continue;
-    trials[i].tabAwayEvents = tabs.map(ta => ({
-      ...ta,
-      startRel_ms: typeof ta.start === 'number'
-        ? ta.start - sessionOffset - trialStartRel
-        : null
-    }));
-  }
-}
+    const parsed = [];
+    for (const f of mine) {
+      try {
+        const buf = readFileSync(join(dir, f));
+        const json = f.toLowerCase().endsWith('.gz')
+          ? gunzipSync(buf).toString('utf8')
+          : buf.toString('utf8');
+        // Same structural sniff as the participant pass: a misnamed
+        // participant export was rescued as participant data there and
+        // must not double as its own "replay" here.
+        if (!looksLikeReplayArtifact(json)) continue;
+        parsed.push({ file: f, recording: JSON.parse(json) });
+      } catch (e) {
+        parsed.push({ file: f, reason: e.message });
+      }
+    }
+    if (parsed.length === 0) {
+      p.replay = null;
+      continue;
+    }
 
-function mapLegacyFields(trial) {
-  const mapped = { ...trial };
-  for (const [oldName, newName] of Object.entries(LEGACY_FIELD_MAP)) {
-    if (mapped[oldName] !== undefined && mapped[newName] === undefined) {
-      mapped[newName] = mapped[oldName];
-      delete mapped[oldName];
+    // Every unreadable artifact warns individually — a corrupt NEWEST
+    // session must never be silently masked by an older readable one.
+    for (const bad of parsed.filter(x => !x.recording)) {
+      warnings.push({ file: join(dir, bad.file),
+        warnings: [`Replay artifact ${bad.file} unreadable: ${bad.reason} — if this is the newest session, its replay is lost.`] });
+    }
+    const readable = parsed.filter(x => x.recording);
+    if (readable.length === 0) {
+      p.replay = { error: 'parse_failed', reason: parsed[0].reason, file: parsed[0].file };
+      continue;
+    }
+    if (mine.length > 1) {
+      warnings.push({ file: dir,
+        warnings: [`Multiple replay artifacts for ${p.participantId} (page reload?) — using the latest by start_time.`] });
     }
+    // Filename sanitization is many-to-one ('a/b' and 'a_b' both map to
+    // 'a_b'), so ownership is verified against the UNsanitized
+    // participant_id embedded in the recording. Artifacts without one
+    // (e.g. plain #3661 recordings) attach with a soft warning.
+    const owned = [];
+    for (const cand of readable) {
+      const embedded = cand.recording.metadata?.participant_id;
+      if (embedded == null) {
+        // Ownerless artifacts skip id verification entirely, so the filename
+        // must match EXACT-case (our recorder writes sanitize(pid) verbatim).
+        // Case-tolerant matching stays for discovery, where the embedded-id
+        // check catches cross-case impostors.
+        if (!cand.file.startsWith(sane + '-replay-')) {
+          warnings.push({ file: join(dir, cand.file),
+            warnings: [`Replay artifact has no embedded participant_id and its filename case does not match "${sane}" exactly — not attached.`] });
+        } else if (saneCounts[sane.toLowerCase()] > 1) {
+          warnings.push({ file: join(dir, cand.file),
+            warnings: [`Replay artifact has no embedded participant_id and its filename is ambiguous (${saneCounts[sane.toLowerCase()]} participants sanitize to "${sane}") — not attached to anyone.`] });
+        } else {
+          warnings.push({ file: join(dir, cand.file),
+            warnings: [`Replay artifact has no embedded participant_id — cannot verify ownership; attaching to ${p.participantId} by unique filename match.`] });
+          owned.push(cand);
+        }
+      } else if (String(embedded) === String(p.participantId)) {
+        owned.push(cand);
+      } else {
+        warnings.push({ file: join(dir, cand.file),
+          warnings: [`Replay artifact participant_id mismatch: file matches ${p.participantId} by name but was recorded for ${embedded} (sanitization collision?) — not attached.`] });
+      }
+    }
+    if (owned.length === 0) {
+      p.replay = null;
+      continue;
+    }
+    // Duplicate records for this id + multiple owned artifacts: the
+    // per-session mapping is genuinely ambiguous. Attach nothing rather
+    // than knowingly mis-associate a session's replay.
+    if (idCounts[p.participantId] > 1 && owned.length > 1) {
+      warnings.push({ file: dir,
+        warnings: [`Cannot associate ${owned.length} replay artifacts with ${idCounts[p.participantId]} duplicate records of "${p.participantId}" — none attached. Separate the sessions into distinct data dirs (or ids) to view their replays.`] });
+      p.replay = null;
+      continue;
+    }
+    // Latest-session pick tolerates non-ISO start_time in third-party
+    // artifacts: ISO string → numeric epoch → the filename's own epoch.
+    const sessionEpoch = (cand) => {
+      const v = cand.recording.metadata?.start_time;
+      const n = typeof v === 'number' ? v : Date.parse(v);
+      if (Number.isFinite(n)) return n;
+      const m = cand.file.match(/-replay-(\d+)\.json/i);
+      return m ? Number(m[1]) : 0;
+    };
+    owned.sort((a, b) => sessionEpoch(a) - sessionEpoch(b));
+    const chosen = owned[owned.length - 1];
+    if (chosen.recording.schema_version !== 1) {
+      warnings.push({ file: join(dir, chosen.file),
+        warnings: [`Replay schema_version ${chosen.recording.schema_version} (this CLI targets 1) — attaching anyway; the viewer may degrade.`] });
+    }
+    p.replay = { recording: chosen.recording, file: chosen.file, meta };
   }
-  // Flag distinguishes "no tracking hardware" from "tracked, zero events"
-  mapped.mouseDataAvailable = Array.isArray(mapped.mouseEvents) && mapped.mouseEvents.length > 0;
-  return mapped;
 }
 
+// Load-bearing re-exports:
+//   - getByPath: html-index.js (and external adopters) import it from ingest.js.
+//   - extractIntegrityData, ruleChronologicalCompare: moved to extract-core.js
+//     (0.7.2 extraction — pure/no Node APIs so a browser demo can bundle it);
+//     this file re-exports both for existing callers — trajectories.js imports
+//     ruleChronologicalCompare from here, and tests/cli/*.test.js import
+//     extractIntegrityData from here.
+export { getByPath };
+export { extractIntegrityData, ruleChronologicalCompare };
+
 // Finds files matching a glob pattern in the given directory.
 // Supports:
 //   - `*.json`         (default, broadened to also match `*.csv`)
@@ -335,7 +389,10 @@ function parseCsvToRaw(text, config) {
 
   // Hoist participant ID from the first row to the top level so Shape-1 ingest
   // finds it via raw[pidField]. Falls back to 'unknown' if the column isn't there.
-  const participantId = rows[0]?.[pidField] ?? 'unknown';
+  // getByPath supports dotted paths into JSON-parsed cells (e.g. a "metadata"
+  // column that held a stringified object); Shape-1's flat-key-first lookup
+  // then finds the hoisted value under the same (possibly dotted) key name.
+  const participantId = getByPath(rows[0], pidField) ?? 'unknown';
 
   return {
     [pidField]: participantId,

package/src/cli/init.js

@@ -16,7 +16,7 @@ export async function runInit() {
 
   // Minimal config — just the fields every project needs to set.
   // filePattern defaults to JSON-or-CSV because jsPsych's `.csv()` save is
-  // the most common format we see in the wild (rule-gallery uses JSON; most
+  // the most common format we see in the wild (Shape-2 producers use JSON; most
   // jsPsych setups use CSV).
   const config = {
     dataDir: './data',

package/src/cli/preview-entry.js

@@ -0,0 +1,36 @@
+// src/cli/preview-entry.js
+// Browser-preview surface (0.7.2): the pure subset of the CLI pipeline the
+// in-browser results screen (demo/results.js) needs to run the same
+// ingest → analyze → render steps the real CLI runs, without any Node APIs.
+// Bundled by tools/build-preview-core.mjs into demo/preview-core.js (esbuild,
+// platform: browser) — every re-export below must resolve to a module with
+// no fs/path/zlib/papaparse imports, or the bundle step fails with an
+// unresolved-import error (the empirical gate the 0.7.2 scope relies on).
+//
+// extractIntegrityData is NOT re-exported from src/cli/ingest.js here even
+// though that's its public home — ingest.js imports Node's `fs`/`zlib` at
+// module scope for the file-discovery/CSV/replay-artifact machinery that
+// surrounds it, so bundling ingest.js itself pulls those in. extract-core.js
+// is the pure extraction the ingest.js module re-exports from (0.7.2), and
+// is what this entry point bundles instead.
+
+export { renderIndexHtml } from './renderers/html-index-core.js';
+export { computeSummary } from './analyzers/summary.js';
+export { detectEdgeExits } from './analyzers/edge-exit.js';
+export { rankTriage } from './analyzers/triage.js';
+export { extractIntegrityData } from './extract-core.js';
+// buildViewerModel: pure wire->viewer conversion (src/replay/viewer-model.js,
+// see that file's docblock) — the demo's results build needs it to construct
+// the visitor's replay viewer-model in-browser (demo/results.js, C2) without
+// re-implementing the time-conversion logic. No Node APIs, so it bundles
+// cleanly here.
+export { buildViewerModel } from '../replay/viewer-model.js';
+
+// The three pure plot cores (0.7.2-style extraction — see each file's own
+// docblock): drawSessionTimeline, drawTrajectoryGrid, drawTypingProfile.
+// Each takes an injected createCanvas factory instead of importing the
+// `canvas` package directly, so they bundle cleanly here too. Consumed by
+// demo/plot-adapter.js to render the visitor's own plots in-browser.
+export { drawSessionTimeline } from './renderers/session-timeline-core.js';
+export { drawTrajectoryGrid } from './renderers/trajectories-core.js';
+export { drawTypingProfile } from './renderers/typing-profile-core.js';

package/src/cli/renderers/event-log.js

@@ -12,41 +12,40 @@ export async function renderEventLog(participants, config) {
   const rows = [];
 
   for (const p of participants) {
+    // Collect this participant's events with their session-absolute timestamp,
+    // then sort chronologically before serializing. All event timestamps are on
+    // the same performance.now() clock (copy/paste/drop/synthetic use `e.t`,
+    // tab-aways use `e.start`), so a single numeric sort interleaves them
+    // correctly. Without this the rows came out in loop/category order
+    // (all pastes, then all copies, …), contradicting the "chronological" docs.
+    const pEvents = [];
     for (const trial of p.trials) {
       const trialId = trial.trialId || trial.ruleId || '?';
 
-      // Paste events
       for (const e of (trial.pasteEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'paste', e.t, '', e.text));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'paste', e.t, '', e.text) });
       }
-
-      // Copy events
       for (const e of (trial.copyEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'copy', e.t, '', ''));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'copy', e.t, '', '') });
       }
-
-      // Drop events
       for (const e of (trial.dropEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'drop', e.t, '', e.text));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'drop', e.t, '', e.text) });
       }
-
-      // Synthetic insertions (text appeared without keystrokes)
       for (const e of (trial.syntheticInsertions || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'synthetic', e.t, '', e.text));
+        pEvents.push({ ts: e.t, row: formatRow(p.participantId, trialId, 'synthetic', e.t, '', e.text) });
       }
-
-      // Tab-away events. timestamp uses the session-absolute `start` (same
-      // performance.now() clock the copy/paste `t` field uses), so all rows
-      // in this CSV share one chronological scale. The `text` column carries
-      // the tab-away type (windowBlur / visibilityChange / etc.) so analysts
-      // can filter by trigger.
+      // Tab-away timestamp uses the session-absolute `start` (the `text` column
+      // carries the trigger type — windowBlur / visibilityChange / etc. — so
+      // analysts can filter by trigger).
       for (const e of (trial.tabAwayEvents || [])) {
-        rows.push(formatRow(p.participantId, trialId, 'tabAway', e.start, e.duration_ms, e.type || ''));
+        pEvents.push({ ts: e.start, row: formatRow(p.participantId, trialId, 'tabAway', e.start, e.duration_ms, e.type || '') });
       }
     }
+    // Stable chronological sort; events with no usable timestamp sort last.
+    pEvents.sort((a, b) => (a.ts ?? Infinity) - (b.ts ?? Infinity));
+    for (const e of pEvents) rows.push(e.row);
   }
 
-  // Sort chronologically within each participant
   const csv = [header, ...rows].join('\n') + '\n';
   const outPath = join(config.outputDir, 'event-log.csv');
   writeFileSync(outPath, csv);

package/src/cli/renderers/extensions.js

@@ -5,6 +5,7 @@
 
 import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { countSidebarOpenings } from '../analyzers/summary.js';
 
 export async function renderExtensions(participants, config) {
   const header = 'participantId,detectionType,name,details';
@@ -20,9 +21,17 @@ export async function renderExtensions(participants, config) {
       rows.push(`${pid},extension,${escapeCSV(name)},`);
     }
 
-    // Sidebar detection
-    const hasSidebar = p.trials.some(t => (t.sidebarGapPx || 0) > 0);
-    if (hasSidebar) {
+    // Sidebar detection. Prefer the current library's session-level
+    // sidebarEvents (the monitor records sidebars session-scoped, not per-trial);
+    // fall back to the legacy per-trial sidebarGapPx only when no session events
+    // exist (pre-session / Shape-2 legacy data). countSidebarOpenings() counts
+    // distinct openings (collapsing the paired open/close records and the
+    // innerWidth_delta + layout_compression double-detection), matching the
+    // summary/triage count.
+    const sidebarOpens = countSidebarOpenings(p.session?.sidebarEvents);
+    if (sidebarOpens > 0) {
+      rows.push(`${pid},sidebar,browser_sidebar,${sidebarOpens} open event${sidebarOpens === 1 ? '' : 's'}`);
+    } else if (p.trials.some(t => (t.sidebarGapPx || 0) > 0)) {
       const maxGap = Math.max(...p.trials.map(t => t.sidebarGapPx || 0));
       rows.push(`${pid},sidebar,browser_sidebar,${maxGap}px gap`);
     }