cyborg-hunter 0.7.0 → 0.7.3

package/src/cli/renderers/typing-profile-core.js

@@ -0,0 +1,211 @@
+// src/cli/renderers/typing-profile-core.js
+//
+// Pure drawing core for per-participant typing-speed bar-chart images — no
+// Node APIs, so a browser demo can bundle it directly (0.7.2-style
+// extraction from cli/renderers/typing-profile.js, which is now a thin fs
+// wrapper around this module: it acquires node-canvas, calls
+// drawTypingProfile per participant, and writes the returned canvas to a
+// PNG). Mirrors the session-timeline-core.js / trajectories-core.js split.
+//
+// drawTypingProfile(p, config, createCanvas) draws one participant's typing
+// speed bar chart — one bar per trial's chars/sec, with a horizontal
+// threshold line and bars above threshold colored red — and returns the
+// drawn canvas (or null if there's nothing to draw: no trials, or no trial
+// has either a typed speed or a paste event). createCanvas is injected so
+// this module never imports the `canvas` package directly — a browser
+// caller can pass a document-canvas-backed factory instead.
+
+const BAR_WIDTH = 30;
+const BAR_GAP = 8;
+const CHART_HEIGHT = 200;
+const TOP_PAD = 50;
+const BOTTOM_PAD = 50;
+const LEFT_PAD = 60;
+
+// ── Per-participant renderer ─────────────────────────────────────────────
+// Returns the drawn canvas, or null if there's no data to draw (caller
+// decides what "no data" means — the fs wrapper skips the PNG write).
+export function drawTypingProfile(p, config, createCanvas) {
+  const trials = p.trials;
+  if (trials.length === 0) return null;
+
+  // Per-participant threshold line: prefer the typing-speed cutoff the library
+  // actually screened this participant with (saved in session.config.thresholds)
+  // so the red "fast typing" line matches summary.csv's count; fall back to the
+  // CLI/default. A strict participant (8 cps) otherwise shows a 10 cps line.
+  const threshold =
+    p.session?.config?.thresholds?.typingSpeedCps ?? config.typingSpeedThreshold_cps ?? 10;
+
+  // Per-trial state. We distinguish three cases:
+  //   "typed"       — charsPerSec is a real number, draw a normal bar
+  //   "paste-only"  — charsPerSec is null but there's a paste event; draw a
+  //                   grey hatched marker so the absence is legible. Single
+  //                   paste fires one input event → editTimestamps.length < 2
+  //                   → computeTypingSpeed returns null. Without this, a
+  //                   pasted response looks identical to a very slow one.
+  //   "no-data"     — neither, leave blank
+  const kinds = trials.map(t => {
+    if (typeof t.charsPerSec === 'number') return 'typed';
+    if ((t.pasteEvents || []).length > 0) return 'paste-only';
+    return 'no-data';
+  });
+  const speeds = trials.map(t => (typeof t.charsPerSec === 'number' ? t.charsPerSec : 0));
+  if (kinds.every(k => k === 'no-data')) return null;
+
+  const canvasW = LEFT_PAD + trials.length * (BAR_WIDTH + BAR_GAP) + 20;
+  const canvasH = TOP_PAD + CHART_HEIGHT + BOTTOM_PAD;
+  const canvas = createCanvas(canvasW, canvasH);
+  const ctx = canvas.getContext('2d');
+
+  // Background
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, canvasW, canvasH);
+
+  // Title
+  ctx.fillStyle = '#333';
+  ctx.font = 'bold 14px sans-serif';
+  ctx.fillText(`Typing Speed Profile — ${p.participantId}`, LEFT_PAD, 20);
+  ctx.font = '10px sans-serif';
+  ctx.fillStyle = '#666';
+  ctx.fillText(`Threshold: ${threshold} chars/sec`, LEFT_PAD, 35);
+
+  // Legend — three states documented in the `kinds` comment above.
+  const legendY = 35;
+  const legendX0 = LEFT_PAD + 180;
+  ctx.fillStyle = '#2196F3';
+  ctx.fillRect(legendX0, legendY - 8, 12, 10);
+  ctx.fillStyle = '#666';
+  ctx.fillText('typed', legendX0 + 16, legendY);
+  ctx.fillStyle = '#f44336';
+  ctx.fillRect(legendX0 + 60, legendY - 8, 12, 10);
+  ctx.fillStyle = '#666';
+  ctx.fillText('> threshold', legendX0 + 76, legendY);
+  // Hatched swatch for paste-only
+  drawHatchedRect(ctx, legendX0 + 150, legendY - 8, 12, 10);
+  ctx.fillStyle = '#666';
+  ctx.fillText('paste (P)', legendX0 + 166, legendY);
+
+  // Y-axis scaling
+  const maxSpeed = Math.max(...speeds, threshold * 1.5);
+  const yScale = CHART_HEIGHT / maxSpeed;
+
+  // Y-axis labels
+  ctx.fillStyle = '#666';
+  ctx.font = '9px sans-serif';
+  const yTicks = 5;
+  for (let t = 0; t <= yTicks; t++) {
+    const val = (maxSpeed / yTicks) * t;
+    const y = TOP_PAD + CHART_HEIGHT - val * yScale;
+    ctx.fillText(`${val.toFixed(1)}`, 5, y + 3);
+    // Grid line
+    ctx.strokeStyle = '#eee';
+    ctx.lineWidth = 0.5;
+    ctx.beginPath();
+    ctx.moveTo(LEFT_PAD, y);
+    ctx.lineTo(canvasW - 10, y);
+    ctx.stroke();
+  }
+
+  // Threshold line
+  const threshY = TOP_PAD + CHART_HEIGHT - threshold * yScale;
+  ctx.strokeStyle = '#ff0000';
+  ctx.lineWidth = 1.5;
+  ctx.setLineDash([5, 3]);
+  ctx.beginPath();
+  ctx.moveTo(LEFT_PAD, threshY);
+  ctx.lineTo(canvasW - 10, threshY);
+  ctx.stroke();
+  ctx.setLineDash([]);
+
+  // Bars
+  const PASTE_BAR_H = CHART_HEIGHT * 0.2; // Paste-only marker height: fixed 20% of chart.
+  for (let i = 0; i < trials.length; i++) {
+    const kind = kinds[i];
+    const speed = speeds[i];
+    const x = LEFT_PAD + i * (BAR_WIDTH + BAR_GAP);
+
+    if (kind === 'paste-only') {
+      // Fixed-height hatched grey bar + "P" marker. The height is arbitrary
+      // — the point is visible presence, not magnitude (we have no CPS to
+      // show). Sits at the bottom like a normal bar.
+      const y = TOP_PAD + CHART_HEIGHT - PASTE_BAR_H;
+      drawHatchedRect(ctx, x, y, BAR_WIDTH, PASTE_BAR_H);
+      ctx.strokeStyle = '#888';
+      ctx.lineWidth = 0.5;
+      ctx.strokeRect(x, y, BAR_WIDTH, PASTE_BAR_H);
+      // "P" marker above the bar
+      ctx.fillStyle = '#555';
+      ctx.font = 'bold 11px sans-serif';
+      ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
+    } else if (kind === 'typed') {
+      const barH = speed * yScale;
+      const y = TOP_PAD + CHART_HEIGHT - barH;
+      ctx.fillStyle = speed > threshold ? '#f44336' : '#2196F3';
+      ctx.fillRect(x, y, BAR_WIDTH, barH);
+      ctx.strokeStyle = '#333';
+      ctx.lineWidth = 0.5;
+      ctx.strokeRect(x, y, BAR_WIDTH, barH);
+      if (speed > 0) {
+        ctx.fillStyle = '#fff';
+        ctx.font = 'bold 9px sans-serif';
+        ctx.fillText(speed.toFixed(1), x + 3, y + 12);
+      }
+      // Mixed: typed AND pasted in the same trial. The bar shows the typing
+      // rate (legitimate signal); the "P" glyph above it flags that *some*
+      // of the response came in via paste. Distinct from pure paste-only
+      // (which is a hatched bar, no colored fill).
+      if ((trials[i].pasteEvents || []).length > 0) {
+        ctx.fillStyle = '#555';
+        ctx.font = 'bold 11px sans-serif';
+        ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
+      }
+    }
+    // 'no-data' → render nothing (blank column)
+
+    // Trial label (always drawn, even for blank columns)
+    const trialId = trials[i].trialId || trials[i].ruleId || `T${i + 1}`;
+    ctx.fillStyle = '#333';
+    ctx.font = '8px sans-serif';
+    ctx.save();
+    ctx.translate(x + BAR_WIDTH / 2, TOP_PAD + CHART_HEIGHT + 10);
+    ctx.rotate(Math.PI / 4);
+    ctx.fillText(trialId.substring(0, 12), 0, 0);
+    ctx.restore();
+  }
+
+  // Baseline
+  ctx.strokeStyle = '#333';
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  ctx.moveTo(LEFT_PAD, TOP_PAD + CHART_HEIGHT);
+  ctx.lineTo(canvasW - 10, TOP_PAD + CHART_HEIGHT);
+  ctx.stroke();
+
+  return canvas;
+}
+
+// Cross-hatched fill for paste-only markers. Uses a light grey background
+// with diagonal strokes so the bar reads as "distinct category, not zero".
+function drawHatchedRect(ctx, x, y, w, h) {
+  ctx.save();
+  ctx.fillStyle = '#e8e8e8';
+  ctx.fillRect(x, y, w, h);
+  ctx.beginPath();
+  ctx.rect(x, y, w, h);
+  ctx.clip();
+  ctx.strokeStyle = '#888';
+  ctx.lineWidth = 0.8;
+  const step = 5;
+  for (let d = -h; d < w + h; d += step) {
+    ctx.beginPath();
+    ctx.moveTo(x + d, y);
+    ctx.lineTo(x + d + h, y + h);
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+
+// Used by the fs wrapper to build the per-participant PNG filename.
+export function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 40);
+}

package/src/cli/renderers/typing-profile.js

@@ -1,177 +1,26 @@
 // src/cli/renderers/typing-profile.js
-// Renders per-participant typing speed bar chart using node-canvas.
-// Each bar = one trial's chars/sec. A horizontal threshold line shows
-// the configured CPS threshold. Bars above threshold are colored red.
-
+// Thin fs wrapper around the pure drawing core (typing-profile-core.js).
+// The core takes an injected createCanvas and returns the drawn canvas (or
+// null when there's nothing to draw); this wrapper owns node-canvas
+// acquisition and PNG serialization so the core can also run in a browser
+// context (demo plot adapter) with document canvases.
 import { writeFileSync } from 'fs';
 import { join } from 'path';
-
-const BAR_WIDTH = 30;
-const BAR_GAP = 8;
-const CHART_HEIGHT = 200;
-const TOP_PAD = 50;
-const BOTTOM_PAD = 50;
-const LEFT_PAD = 60;
-
+import { drawTypingProfile, sanitize } from './typing-profile-core.js';
+// Load-bearing re-export: drawTypingProfile serves this wrapper's own loop
+// below and the future browser demo plot adapter — mirrors
+// session-timeline.js / trajectories.js. (renderTypingProfiles remains the
+// only symbol external consumers import from this file — see
+// tests/cli/renderers.test.js and src/cli/report.js.)
+export { drawTypingProfile };
+
+// ── Public API ───────────────────────────────────────────────────────────
 export async function renderTypingProfiles(participants, config) {
   const { createCanvas } = await import('canvas');
 
   for (const p of participants) {
-    const trials = p.trials;
-    if (trials.length === 0) continue;
-
-    // Per-participant threshold line: prefer the typing-speed cutoff the library
-    // actually screened this participant with (saved in session.config.thresholds)
-    // so the red "fast typing" line matches summary.csv's count; fall back to the
-    // CLI/default. A strict participant (8 cps) otherwise shows a 10 cps line.
-    const threshold =
-      p.session?.config?.thresholds?.typingSpeedCps ?? config.typingSpeedThreshold_cps ?? 10;
-
-    // Per-trial state. We distinguish three cases:
-    //   "typed"       — charsPerSec is a real number, draw a normal bar
-    //   "paste-only"  — charsPerSec is null but there's a paste event; draw a
-    //                   grey hatched marker so the absence is legible. Single
-    //                   paste fires one input event → editTimestamps.length < 2
-    //                   → computeTypingSpeed returns null. Without this, a
-    //                   pasted response looks identical to a very slow one.
-    //   "no-data"     — neither, leave blank
-    const kinds = trials.map(t => {
-      if (typeof t.charsPerSec === 'number') return 'typed';
-      if ((t.pasteEvents || []).length > 0) return 'paste-only';
-      return 'no-data';
-    });
-    const speeds = trials.map(t => (typeof t.charsPerSec === 'number' ? t.charsPerSec : 0));
-    if (kinds.every(k => k === 'no-data')) continue;
-
-    const canvasW = LEFT_PAD + trials.length * (BAR_WIDTH + BAR_GAP) + 20;
-    const canvasH = TOP_PAD + CHART_HEIGHT + BOTTOM_PAD;
-    const canvas = createCanvas(canvasW, canvasH);
-    const ctx = canvas.getContext('2d');
-
-    // Background
-    ctx.fillStyle = '#ffffff';
-    ctx.fillRect(0, 0, canvasW, canvasH);
-
-    // Title
-    ctx.fillStyle = '#333';
-    ctx.font = 'bold 14px sans-serif';
-    ctx.fillText(`Typing Speed Profile — ${p.participantId}`, LEFT_PAD, 20);
-    ctx.font = '10px sans-serif';
-    ctx.fillStyle = '#666';
-    ctx.fillText(`Threshold: ${threshold} chars/sec`, LEFT_PAD, 35);
-
-    // Legend — three states documented in the `kinds` comment above.
-    const legendY = 35;
-    const legendX0 = LEFT_PAD + 180;
-    ctx.fillStyle = '#2196F3';
-    ctx.fillRect(legendX0, legendY - 8, 12, 10);
-    ctx.fillStyle = '#666';
-    ctx.fillText('typed', legendX0 + 16, legendY);
-    ctx.fillStyle = '#f44336';
-    ctx.fillRect(legendX0 + 60, legendY - 8, 12, 10);
-    ctx.fillStyle = '#666';
-    ctx.fillText('> threshold', legendX0 + 76, legendY);
-    // Hatched swatch for paste-only
-    drawHatchedRect(ctx, legendX0 + 150, legendY - 8, 12, 10);
-    ctx.fillStyle = '#666';
-    ctx.fillText('paste (P)', legendX0 + 166, legendY);
-
-    // Y-axis scaling
-    const maxSpeed = Math.max(...speeds, threshold * 1.5);
-    const yScale = CHART_HEIGHT / maxSpeed;
-
-    // Y-axis labels
-    ctx.fillStyle = '#666';
-    ctx.font = '9px sans-serif';
-    const yTicks = 5;
-    for (let t = 0; t <= yTicks; t++) {
-      const val = (maxSpeed / yTicks) * t;
-      const y = TOP_PAD + CHART_HEIGHT - val * yScale;
-      ctx.fillText(`${val.toFixed(1)}`, 5, y + 3);
-      // Grid line
-      ctx.strokeStyle = '#eee';
-      ctx.lineWidth = 0.5;
-      ctx.beginPath();
-      ctx.moveTo(LEFT_PAD, y);
-      ctx.lineTo(canvasW - 10, y);
-      ctx.stroke();
-    }
-
-    // Threshold line
-    const threshY = TOP_PAD + CHART_HEIGHT - threshold * yScale;
-    ctx.strokeStyle = '#ff0000';
-    ctx.lineWidth = 1.5;
-    ctx.setLineDash([5, 3]);
-    ctx.beginPath();
-    ctx.moveTo(LEFT_PAD, threshY);
-    ctx.lineTo(canvasW - 10, threshY);
-    ctx.stroke();
-    ctx.setLineDash([]);
-
-    // Bars
-    const PASTE_BAR_H = CHART_HEIGHT * 0.2; // Paste-only marker height: fixed 20% of chart.
-    for (let i = 0; i < trials.length; i++) {
-      const kind = kinds[i];
-      const speed = speeds[i];
-      const x = LEFT_PAD + i * (BAR_WIDTH + BAR_GAP);
-
-      if (kind === 'paste-only') {
-        // Fixed-height hatched grey bar + "P" marker. The height is arbitrary
-        // — the point is visible presence, not magnitude (we have no CPS to
-        // show). Sits at the bottom like a normal bar.
-        const y = TOP_PAD + CHART_HEIGHT - PASTE_BAR_H;
-        drawHatchedRect(ctx, x, y, BAR_WIDTH, PASTE_BAR_H);
-        ctx.strokeStyle = '#888';
-        ctx.lineWidth = 0.5;
-        ctx.strokeRect(x, y, BAR_WIDTH, PASTE_BAR_H);
-        // "P" marker above the bar
-        ctx.fillStyle = '#555';
-        ctx.font = 'bold 11px sans-serif';
-        ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
-      } else if (kind === 'typed') {
-        const barH = speed * yScale;
-        const y = TOP_PAD + CHART_HEIGHT - barH;
-        ctx.fillStyle = speed > threshold ? '#f44336' : '#2196F3';
-        ctx.fillRect(x, y, BAR_WIDTH, barH);
-        ctx.strokeStyle = '#333';
-        ctx.lineWidth = 0.5;
-        ctx.strokeRect(x, y, BAR_WIDTH, barH);
-        if (speed > 0) {
-          ctx.fillStyle = '#fff';
-          ctx.font = 'bold 9px sans-serif';
-          ctx.fillText(speed.toFixed(1), x + 3, y + 12);
-        }
-        // Mixed: typed AND pasted in the same trial. The bar shows the typing
-        // rate (legitimate signal); the "P" glyph above it flags that *some*
-        // of the response came in via paste. Distinct from pure paste-only
-        // (which is a hatched bar, no colored fill).
-        if ((trials[i].pasteEvents || []).length > 0) {
-          ctx.fillStyle = '#555';
-          ctx.font = 'bold 11px sans-serif';
-          ctx.fillText('P', x + BAR_WIDTH / 2 - 3, y - 3);
-        }
-      }
-      // 'no-data' → render nothing (blank column)
-
-      // Trial label (always drawn, even for blank columns)
-      const trialId = trials[i].trialId || trials[i].ruleId || `T${i + 1}`;
-      ctx.fillStyle = '#333';
-      ctx.font = '8px sans-serif';
-      ctx.save();
-      ctx.translate(x + BAR_WIDTH / 2, TOP_PAD + CHART_HEIGHT + 10);
-      ctx.rotate(Math.PI / 4);
-      ctx.fillText(trialId.substring(0, 12), 0, 0);
-      ctx.restore();
-    }
-
-    // Baseline
-    ctx.strokeStyle = '#333';
-    ctx.lineWidth = 1;
-    ctx.beginPath();
-    ctx.moveTo(LEFT_PAD, TOP_PAD + CHART_HEIGHT);
-    ctx.lineTo(canvasW - 10, TOP_PAD + CHART_HEIGHT);
-    ctx.stroke();
-
+    const canvas = drawTypingProfile(p, config, createCanvas);
+    if (!canvas) continue;
     const buf = canvas.toBuffer('image/png');
     const filename = `typing_profile_${sanitize(p.participantId)}.png`;
     writeFileSync(join(config.outputDir, 'images', filename), buf);
@@ -179,28 +28,3 @@ export async function renderTypingProfiles(participants, config) {
 
   console.log(`  typing profiles — rendered`);
 }
-
-function sanitize(name) {
-  return name.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 40);
-}
-
-// Cross-hatched fill for paste-only markers. Uses a light grey background
-// with diagonal strokes so the bar reads as "distinct category, not zero".
-function drawHatchedRect(ctx, x, y, w, h) {
-  ctx.save();
-  ctx.fillStyle = '#e8e8e8';
-  ctx.fillRect(x, y, w, h);
-  ctx.beginPath();
-  ctx.rect(x, y, w, h);
-  ctx.clip();
-  ctx.strokeStyle = '#888';
-  ctx.lineWidth = 0.8;
-  const step = 5;
-  for (let d = -h; d < w + h; d += step) {
-    ctx.beginPath();
-    ctx.moveTo(x + d, y);
-    ctx.lineTo(x + d + h, y + h);
-    ctx.stroke();
-  }
-  ctx.restore();
-}

package/src/cli/report.js

@@ -14,10 +14,15 @@ import { detectEdgeExits } from './analyzers/edge-exit.js';
 import { rankTriage } from './analyzers/triage.js';
 import { applyPhaseScope, describePhaseScope, findUnmatchedPhaseScopePhases } from './analyzers/phase-scope.js';
 import { VERSION } from '../shared/constants.js';
+import { checkForUpdate, formatUpdateNotice, formatCollectedVersionNotice } from './update-check.js';
 
 export async function run(args) {
   console.log(`cyborg-hunter report v${VERSION}\n`);
 
+  // Kick the update check off first so the registry request overlaps the
+  // whole pipeline; awaited (bounded by its own short timeout) at the end.
+  const updateCheck = checkForUpdate({ currentVersion: VERSION }).catch(() => null);
+
   // 1. Load and merge config (defaults ← file ← CLI flags)
   const config = loadConfig(args);
 
@@ -45,6 +50,13 @@ export async function run(args) {
     process.exit(1);
   }
 
+  // Offline staleness note: payloads stamp the library version that collected
+  // them, so an experiment still serving an old bundle is visible without any
+  // network. (The registry check above covers the CLI side.)
+  const collectedNotice = formatCollectedVersionNotice(
+    participants.map(p => p.libraryVersion), VERSION);
+  if (collectedNotice) console.log(collectedNotice);
+
   // 3. Analyze — compute summaries, detect edge exits, rank by triage priority.
   // config.phaseScope (0.6.1) filters which trials feed the analyzers so
   // scores can honor pre-registered phase scoping; renderers below still get
@@ -145,4 +157,9 @@ export async function run(args) {
 
   console.log(`\nReport written to ${config.outputDir}/`);
   console.log(`  Open ${config.outputDir}/index.html to review`);
+
+  const update = await updateCheck;
+  if (update && update.updateAvailable) {
+    console.log(`\n${formatUpdateNotice(VERSION, update.latest)}`);
+  }
 }

package/src/cli/update-check.js

@@ -0,0 +1,110 @@
+// src/cli/update-check.js
+// Post-report update nudge, plus the offline collected-with version notice.
+//
+// The registry check is deliberately zero-dependency and fail-silent: one
+// request to npm's registry for the `latest` dist-tag, throttled to once per
+// day via a small cache file. A report run must never break, slow down, or
+// complain because npm is unreachable. It runs only in the CLI on the
+// researcher's machine — the browser library never makes network requests.
+//
+// Opt-outs (checked before any network or cache access):
+//   NO_UPDATE_NOTIFIER — the convention established by update-notifier
+//   CI                 — CI runs have no human to nudge
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/cyborg-hunter/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+
+function defaultCacheFile() {
+  return join(homedir(), '.cache', 'cyborg-hunter', 'update-check.json');
+}
+
+// Numeric dot-segment comparison ("0.10.0" vs "0.7.2"): returns 1 / 0 / -1 as
+// a is newer / equal / older than b. Non-numeric segments count as 0, so a
+// malformed registry answer degrades to "no update" rather than a false nudge.
+export function compareVersions(a, b) {
+  const as = String(a).split('.').map(s => parseInt(s, 10) || 0);
+  const bs = String(b).split('.').map(s => parseInt(s, 10) || 0);
+  const len = Math.max(as.length, bs.length);
+  for (let i = 0; i < len; i++) {
+    const d = (as[i] || 0) - (bs[i] || 0);
+    if (d > 0) return 1;
+    if (d < 0) return -1;
+  }
+  return 0;
+}
+
+// Resolves to { latest, updateAvailable } or null (opted out, offline, old
+// Node without fetch, or any registry hiccup — all silent by design).
+// Everything impure is injectable so tests never touch the network or $HOME.
+export async function checkForUpdate({
+  currentVersion,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  cacheFile = defaultCacheFile(),
+  timeoutMs = FETCH_TIMEOUT_MS,
+  now = Date.now(),
+} = {}) {
+  if (env.NO_UPDATE_NOTIFIER || env.CI || typeof fetchImpl !== 'function') return null;
+
+  let cached = null;
+  try {
+    cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
+  } catch { /* no cache yet, or unreadable — fetch below */ }
+
+  let latest;
+  if (cached && typeof cached.latest === 'string' &&
+      typeof cached.checkedAt === 'number' && now - cached.checkedAt < CHECK_INTERVAL_MS) {
+    latest = cached.latest;
+  } else {
+    const controller = new AbortController();
+    // Deliberately NOT unref'd: on a hung fetch this timer can be the only
+    // live handle, and an unref'd one lets the event loop drain before it
+    // fires (Node 20 cancels pending awaits that way). It is cleared the
+    // moment fetch settles, so it never holds a normal run open.
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(REGISTRY_LATEST_URL, { signal: controller.signal });
+      if (!res.ok) return null;
+      const body = await res.json();
+      if (typeof body.version !== 'string') return null;
+      latest = body.version;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+    try {
+      mkdirSync(dirname(cacheFile), { recursive: true });
+      writeFileSync(cacheFile, JSON.stringify({ checkedAt: now, latest }));
+    } catch { /* unwritable cache dir just means one fetch per run */ }
+  }
+
+  return { latest, updateAvailable: compareVersions(latest, currentVersion) > 0 };
+}
+
+export function formatUpdateNotice(current, latest) {
+  return `Update available: cyborg-hunter ${current} -> ${latest}\n` +
+         `  npx picks up new versions automatically; a global install updates with\n` +
+         `  npm install -g cyborg-hunter@latest`;
+}
+
+// Offline staleness notice: session payloads stamp the library version that
+// collected them (monitor.js sets report.libraryVersion), so a mismatch with
+// the CLI's own version is detectable with no network at all. This catches
+// the case the registry check can't: an experiment still collecting data
+// with an old bundle. Returns the notice string, or null when every session
+// matches the CLI version (or carries no version, e.g. CSV-derived data).
+export function formatCollectedVersionNotice(collectedVersions, cliVersion) {
+  const distinct = [...new Set(
+    collectedVersions.filter(v => typeof v === 'string' && v.length > 0)
+  )].filter(v => v !== cliVersion).sort(compareVersions);
+  if (distinct.length === 0) return null;
+  return `  Note: sessions in this dataset were collected with cyborg-hunter ` +
+         `${distinct.join(', ')}; this CLI is ${cliVersion}.\n` +
+         `  Signal definitions and scoring defaults can differ between versions.`;
+}

package/src/core/monitor.js

@@ -378,6 +378,23 @@ export function init(userConfig) {
         report.mouseMetrics = mouseMetrics;
       }
 
+      // Privacy gate: the raw per-sample mouse coordinates are a much
+      // higher-resolution behavioral trace than the derived mouseMetrics
+      // above. Persist them ONLY when explicitly enabled
+      // (collectForPostHoc.rawMouseTrack) — under the `mouseTrack` name,
+      // which is what extract-core's field map already expects (mouseTrack →
+      // mouseEvents), so a saved report round-trips through
+      // extractIntegrityData() without new glue. Otherwise drop the raw
+      // report.mouseEvents entirely — the mouseMetrics signal above still
+      // works, but the {x,y,t,type} samples never leave the browser. Before
+      // this gate, deepCopy(trialData) put the full raw track in every
+      // report regardless of the documented off-by-default rawMouseTrack
+      // toggle.
+      if (config.collectForPostHoc.rawMouseTrack) {
+        report.mouseTrack = report.mouseEvents;
+      }
+      delete report.mouseEvents;
+
       // Accumulate into session
       sessionData.trialsCompleted++;
 

package/src/jspsych/extension-cyborg-hunter-replay.js

@@ -35,7 +35,7 @@ import { buildReplayMeta } from '../replay/persistence.js';
 class CyborgHunterReplayExtension {
   static info = {
     name: 'cyborg-hunter-replay',
-    version: '0.7.0',
+    version: '0.7.3',
     data: {}   // per-trial return is {}; session meta goes via addProperties
   };
 

package/src/jspsych/extension-cyborg-hunter.js

@@ -10,7 +10,7 @@ class CyborgHunterExtension {
     // and package.json). Hand-bumped on each release; if you forget, the
     // jsPsych developer console shows a stale number — the actual version
     // attached to data is read from window.CyborgHunter.VERSION at runtime.
-    version: '0.7.0',
+    version: '0.7.3',
     data: { integrity: { type: 'object' } }
   };
 

package/src/jspsych/extension-guard-friction.js

@@ -905,8 +905,11 @@ export function fullscreenElementOf(doc) {
     }
 
     // ----- Entry trial ---------------------------------------------
-    function createEntryTrial(opts = {}) {
-        const message = opts.message || `
+    // Hoisted out of createEntryTrial (verbatim string move) so the frozen
+    // public API can expose it as `defaultEntryMessage` below — demo/demo.js
+    // renders this SAME string verbatim on its guard-entry step, so it can
+    // never drift out of sync with what a real participant actually sees.
+    const DEFAULT_ENTRY_MESSAGE = `
             <h2>Fullscreen mode required</h2>
             <p>To keep the experiment fair for everyone, we ask that this study be completed in fullscreen mode,
                with no browser sidebars (Gemini, Copilot, Edge sidebar, etc.) open, and with this tab focused.</p>
@@ -914,6 +917,9 @@ export function fullscreenElementOf(doc) {
             <p>We care about collecting high-quality data, and these rules help ensure a fair experience for all participants.</p>
             <p>Please close any sidebars now, then click the button below to continue in fullscreen.</p>
         `;
+
+    function createEntryTrial(opts = {}) {
+        const message = opts.message || DEFAULT_ENTRY_MESSAGE;
         return {
             type: jsPsychHtmlButtonResponse,
             stimulus: message,
@@ -1048,6 +1054,9 @@ export function fullscreenElementOf(doc) {
         createEntryTrial: function (opts) { return createEntryTrial(opts); },
         onViolation: function (handler) { return onViolation(handler); },
         getCurrentState: function () { return getCurrentState(); },
+        // Added on the object literal BEFORE Object.freeze() below — a
+        // post-freeze assignment would silently no-op.
+        defaultEntryMessage: DEFAULT_ENTRY_MESSAGE,
     };
 
     Object.freeze(api);