cyborg-hunter 0.3.0 → 0.4.0

package/src/cli/renderers/trajectories.js

@@ -1,27 +1,54 @@
-// src/cli/renderers/trajectories.js
-// Renders mouse trajectory images using node-canvas.
-// Produces one PNG per participant with a grid of panels (one per trial).
+// Mouse trajectory rendering (node-canvas). One PNG per participant, grid of
+// per-trial panels. Mirrors the visual conventions of the Python reference
+// pipeline in card-games/rule-gallery/analysis/trajectories.py.
 //
-// Visual elements (matching the Python reference in trajectories.py):
-//   - Time-colored path: blue→red gradient via line segments
-//   - Start marker: blue circle, End marker: red square
-//   - Mousedown: green triangle, Mouseup: magenta triangle
-//   - Tab-away: yellow diamond (left), cyan diamond (returned), size ∝ duration
-//   - Pause markers: grey circles for >3s gaps without tab-away
-//   - Edge-exit highlights: orange overlay on edge-exit segments
-//   - Screen/window bounding rectangles
-//   - Red border if hard signal triggered on that trial
-//   - Title with trial ID, RT, mouse count, tab-away info
+// Per-panel visual elements:
+//   - Time-colored path (blue → red gradient over the trial's duration)
+//   - Start marker (blue circle), end marker (red square)
+//   - Mousedown (green ▼), mouseup (magenta ▲)
+//   - Tab-away pairs (yellow ◆ at the leave point, cyan ◆ at return, size ∝
+//     duration), connected by a dashed line
+//   - Pause circles (grey ○) for >3s gaps that don't overlap a tab-away
+//   - Browser-window outline (purple, dashed); screen outline (teal, solid)
+//     when geometry data is present and internally consistent
+//   - Red panel border if any hard signal fired on this trial
+//   - Title with trial ID, RT, mouse count, tab-away count + total duration
 
 import { writeFileSync } from 'fs';
 import { join } from 'path';
 
-// Panel dimensions (pixels)
+// Panel dimensions (pixels).
 const PANEL_W = 400;
 const PANEL_H = 300;
 const PANEL_PAD = 40;
 const TITLE_HEIGHT = 40;
-const HEADER_HEIGHT = 80;  // accommodates 2-line legend
+const HEADER_HEIGHT = 80;   // accommodates 2-line legend
+const PANEL_MARGIN = 15;    // inset between panel border and content area
+
+// Color palette. Hoisted from inline string literals to give the rendering
+// style one place to look. Names match the visual element they style.
+const COLORS = {
+  bg: '#ffffff',
+  panelBg: '#fafafa',
+  panelBorder: '#ccc',
+  panelBorderHardHit: '#ff0000',
+  headerText: '#333',
+  legendText: '#666',
+  zoomTag: '#a06000',
+  noData: '#999',
+  screenRect: '#26a69a',
+  windowRect: '#7e57c2',
+  pathStart: '#0000ff',
+  pathEnd: '#ff0000',
+  pathEndStroke: '#000',
+  mousedown: '#00cc00',
+  mouseup: '#ff00ff',
+  tabAwayLeftFill: '#ffff00',
+  tabAwayLeftStroke: '#ff8c00',
+  tabAwayReturnFill: '#00ffff',
+  tabAwayReturnStroke: '#008b8b',
+  pauseCircle: '#ccc',
+};
 
 export async function renderTrajectories(participants, triage, config) {
   const { createCanvas } = await import('canvas');
@@ -41,20 +68,20 @@ export async function renderTrajectories(participants, triage, config) {
     const ctx = canvas.getContext('2d');
 
     // Background
-    ctx.fillStyle = '#ffffff';
+    ctx.fillStyle = COLORS.bg;
     ctx.fillRect(0, 0, canvasW, canvasH);
 
     // Header
     const t = triageMap.get(p.participantId);
     const headerText = `${p.participantId} — Score: ${t?.score ?? '?'} — ${t?.reason ?? ''}`;
-    ctx.fillStyle = '#333';
+    ctx.fillStyle = COLORS.headerText;
     ctx.font = 'bold 16px sans-serif';
     ctx.fillText(headerText, PANEL_PAD, 30);
 
-    // Legend — split across two lines so the long enumeration stays readable
-    // and the panel-frame meaning isn't buried at the end of a wrap.
+    // Two-line legend — splitting keeps the panel-frame meaning visible rather
+    // than buried at the end of a wrap.
     ctx.font = '11px sans-serif';
-    ctx.fillStyle = '#666';
+    ctx.fillStyle = COLORS.legendText;
     ctx.fillText(
       'Blue●=start  Red■=end  Green▼=mousedown  Magenta▲=mouseup  Yellow◆=tab-away (left)  Cyan◆=tab-away (returned)  Grey○=pause',
       PANEL_PAD, 48
@@ -64,30 +91,27 @@ export async function renderTrajectories(participants, triage, config) {
       PANEL_PAD, 64
     );
 
-    // session.windowPositions is the 2-second-poll record from
-    // core/signals/browser.js. Per-trial geometry is the sample whose
-    // timestamp is closest to that trial's trialStart_perfNow anchor.
-    // Older data without sw/sh (pre-April-2026 monitor) yields a
-    // window-only geometry; chooseScreenFrame degrades gracefully.
+    // session.windowPositions is the 2-second-poll-plus-resize-event record
+    // from core/signals/browser.js. Per-trial geometry uses the sample whose
+    // timestamp best fits the trial's mouse extent (see
+    // pickWindowGeometryForTrial). Older recordings without sw/sh fields
+    // yield a window-only geometry; chooseScreenFrame degrades gracefully.
     const windowPositions = p.session?.windowPositions || [];
 
-    // Render each trial panel
     for (let i = 0; i < trials.length; i++) {
       const col = i % cols;
       const row = Math.floor(i / cols);
       const x0 = PANEL_PAD + col * (PANEL_W + PANEL_PAD);
       const y0 = HEADER_HEIGHT + PANEL_PAD + row * (PANEL_H + TITLE_HEIGHT + PANEL_PAD);
 
-      // P7: prefer per-trial geometry (collected at renderRule time) over
-      // session-end metadata, which can be stale if the participant dragged
-      // the window mid-experiment. Fall back to session metadata for old data.
+      // Geometry resolution priority: explicit per-trial > session-end > polled.
+      // Per-trial wins because it was captured AT trial render time and can't
+      // be stale; session-end can drift if the participant resized between
+      // last sample and end-of-experiment. Polled fills in for jsPsych
+      // extension data, which has no explicit per-trial geometry field.
       const sessionMeta = p.metadata || {};
       const sessionGeom = sessionMeta.geometry || {};
       const trialGeom = trials[i].geometry || {};
-      // April 2026: also derive geometry from session.windowPositions if no
-      // explicit per-trial geometry was attached. This is the path jsPsych
-      // extension data takes (no per-trial geometry field, just the polled
-      // session-level samples).
       const polledGeom = pickWindowGeometryForTrial(trials[i], windowPositions) || {};
       const effectiveMeta = { ...sessionMeta, ...sessionGeom, ...polledGeom, ...trialGeom };
       renderTrialPanel(ctx, trials[i], x0, y0, config, effectiveMeta);
@@ -110,48 +134,46 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
   const downs = mouse.filter(e => e.type === 'down');
   const ups = mouse.filter(e => e.type === 'up');
 
-  // Panel border — red if any hard-signal trialHits fired (v3.1.0 data shape).
-  // Mirrors the `.triggered` → `trialHits > 0` migration in summary.js.
+  // Panel border — red if any hard-signal trialHits fired on this trial.
   const anyHardHit = trial.trialSignals?.hard &&
     Object.values(trial.trialSignals.hard).some(s => (s.trialHits || 0) > 0);
-  ctx.strokeStyle = anyHardHit ? '#ff0000' : '#ccc';
+  ctx.strokeStyle = anyHardHit ? COLORS.panelBorderHardHit : COLORS.panelBorder;
   ctx.lineWidth = anyHardHit ? 3 : 1;
   ctx.strokeRect(x0, y0 + TITLE_HEIGHT, PANEL_W, PANEL_H);
 
   // Panel background
-  ctx.fillStyle = '#fafafa';
+  ctx.fillStyle = COLORS.panelBg;
   ctx.fillRect(x0 + 1, y0 + TITLE_HEIGHT + 1, PANEL_W - 2, PANEL_H - 2);
 
   // Title
   const nTabs = tabAways.length;
   const tabDur = tabAways.reduce((s, e) => s + (e.duration_ms || 0), 0) / 1000;
-  ctx.fillStyle = '#333';
+  ctx.fillStyle = COLORS.headerText;
   ctx.font = '11px sans-serif';
   ctx.fillText(`${trialId.substring(0, 20)} — ${rt.toFixed(0)}s, ${moves.length} mv, ${nTabs} tabs (${tabDur.toFixed(0)}s)`,
     x0, y0 + TITLE_HEIGHT - 8);
 
   if (moves.length === 0) {
-    ctx.fillStyle = '#999';
+    ctx.fillStyle = COLORS.noData;
     ctx.font = '12px sans-serif';
     ctx.fillText('No mouse data', x0 + PANEL_W / 2 - 40, y0 + TITLE_HEIGHT + PANEL_H / 2);
     return;
   }
 
-  // P7: choose a geometry frame and decide which rectangles can be drawn honestly.
-  // Three cases, in priority order:
-  //   1. SCREEN-API frame  — metadata.screens (Window Management API) is present.
-  //                          We know the multi-monitor layout, so we can render in
-  //                          true screen space and always draw both rectangles.
-  //   2. LEGACY-COMPAT frame — old data with screenWidth/screenHeight; we draw both
-  //                          rectangles BUT only when the window geometry doesn't
-  //                          paradoxically exceed the screen (zoom / multi-monitor).
-  //                          When it does exceed, we drop the outer rect — drawing
-  //                          a "screen" smaller than the "window" is dishonest.
-  //   3. WINDOW-ONLY frame — window geometry only (no screen size known); fit
-  //                          canvas to the window outline and draw it alone.
-  //   4. AUTO-FIT frame    — no geometry at all; auto-fit to mouse path.
+  // Choose a geometry frame and decide which rectangles can be drawn honestly.
+  // Four cases, in priority order:
+  //   1. SCREEN-API   — metadata.screens (Window Management API) present.
+  //                     Multi-monitor layout known; render in true screen space
+  //                     and draw both rectangles.
+  //   2. LEGACY       — screenWidth/screenHeight present. Draw both rects when
+  //                     the window geometry doesn't paradoxically exceed the
+  //                     screen (zoom-out, multi-monitor). When it does, drop
+  //                     the outer rect — drawing a "screen" smaller than the
+  //                     "window" it supposedly contains is dishonest.
+  //   3. WINDOW-ONLY  — window geometry but no screen size. Fit canvas to the
+  //                     window outline and draw it alone.
+  //   4. AUTO-FIT     — no geometry at all; auto-fit to mouse path.
   const screenFrame = chooseScreenFrame(metadata);
-  const margin = 15;
   let minX, maxX, minY, maxY, offsetX, offsetY;
   if (screenFrame.mode === 'screen-api' || screenFrame.mode === 'legacy') {
     const { screenW, screenH, winX, winY, winW, winH } = screenFrame;
@@ -197,8 +219,8 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
   // Skipped in auto-fit mode (no outline → no alignment needed).
   const zoom = (screenFrame.mode === 'auto-fit') ? { x: 1, y: 1 } : computeZoomScale(metadata);
 
-  const mapX = (px) => x0 + margin + ((px * zoom.x + offsetX - minX) / rangeX) * (PANEL_W - 2 * margin);
-  const mapY = (py) => y0 + TITLE_HEIGHT + margin + ((py * zoom.y + offsetY - minY) / rangeY) * (PANEL_H - 2 * margin);
+  const mapX = (px) => x0 + PANEL_MARGIN + ((px * zoom.x + offsetX - minX) / rangeX) * (PANEL_W - 2 * PANEL_MARGIN);
+  const mapY = (py) => y0 + TITLE_HEIGHT + PANEL_MARGIN + ((py * zoom.y + offsetY - minY) / rangeY) * (PANEL_H - 2 * PANEL_MARGIN);
 
   // Screen + browser-window rectangles. The frame chooser above decides which
   // rectangles are safe to draw. `drawOuter` is false for legacy data with a
@@ -207,19 +229,19 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
   // also false for window-only mode (no screen data at all).
   if (screenFrame.mode === 'screen-api' || screenFrame.mode === 'legacy' || screenFrame.mode === 'window-only') {
     const { screenW, screenH, winX, winY, winW, winH, drawOuter } = screenFrame;
-    const rectMapX = (px) => x0 + margin + ((px - minX) / rangeX) * (PANEL_W - 2 * margin);
-    const rectMapY = (py) => y0 + TITLE_HEIGHT + margin + ((py - minY) / rangeY) * (PANEL_H - 2 * margin);
+    const rectMapX = (px) => x0 + PANEL_MARGIN + ((px - minX) / rangeX) * (PANEL_W - 2 * PANEL_MARGIN);
+    const rectMapY = (py) => y0 + TITLE_HEIGHT + PANEL_MARGIN + ((py - minY) / rangeY) * (PANEL_H - 2 * PANEL_MARGIN);
     ctx.save();
     ctx.lineWidth = 1;
     if (drawOuter) {
-      ctx.strokeStyle = '#26a69a';
+      ctx.strokeStyle = COLORS.screenRect;
       ctx.strokeRect(
         rectMapX(0), rectMapY(0),
         rectMapX(screenW) - rectMapX(0),
         rectMapY(screenH) - rectMapY(0)
       );
     }
-    ctx.strokeStyle = '#7e57c2';
+    ctx.strokeStyle = COLORS.windowRect;
     ctx.setLineDash([4, 3]);
     ctx.strokeRect(
       rectMapX(winX), rectMapY(winY),
@@ -236,7 +258,7 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
   // from outerWidth/innerWidth deviation.
   const zoomTag = computeZoomTag(metadata);
   if (zoomTag) {
-    ctx.fillStyle = '#a06000';
+    ctx.fillStyle = COLORS.zoomTag;
     ctx.font = 'italic 10px sans-serif';
     ctx.fillText(zoomTag, x0 + PANEL_W - 60, y0 + TITLE_HEIGHT - 8);
   }
@@ -258,34 +280,38 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
     ctx.lineTo(mapX(moves[j].x), mapY(moves[j].y));
     ctx.stroke();
 
-    // Pause markers (>3s gap without matching tab-away).
-    // Both moves[j].t and ta.startRel_ms are trial-relative ms (normalized in ingest).
+    // Pause markers (>3s gap with no movement).
+    // Both moves[j].t and ta.startRel_ms are trial-relative ms (normalized in
+    // ingest). Find the tab-away (if any) whose [start, start+duration] window
+    // overlaps the gap. If we find one, draw the leave/return diamond pair;
+    // otherwise drop a grey pause circle.
     const gap = moves[j].t - moves[j - 1].t;
     if (gap > 3000) {
       const taStart = (ta) => (ta.startRel_ms != null ? ta.startRel_ms : ta.start);
-      const isTabAway = tabAways.some(ta =>
-        taStart(ta) < moves[j].t + 1000 && (taStart(ta) + (ta.duration_ms || 0)) > moves[j - 1].t - 1000);
-      if (isTabAway) {
-        // Tab-away diamond markers
-        const dur = tabAways.find(ta => taStart(ta) < moves[j].t + 1000)?.duration_ms || gap;
+      const overlappingTab = tabAways.find(ta =>
+        taStart(ta) < moves[j].t + 1000 &&
+        (taStart(ta) + (ta.duration_ms || 0)) > moves[j - 1].t - 1000
+      );
+      if (overlappingTab) {
+        // Diamond size scales with √duration (square root keeps very long
+        // tab-aways from drawing as huge blobs that obscure the trajectory).
+        const dur = overlappingTab.duration_ms || gap;
         const size = Math.min(20, Math.max(4, 4 + Math.sqrt(dur / 1000) * 3));
 
-        // Left diamond (yellow)
-        drawDiamond(ctx, mapX(moves[j - 1].x), mapY(moves[j - 1].y), size, '#ffff00', '#ff8c00');
-        // Return diamond (cyan)
-        drawDiamond(ctx, mapX(moves[j].x), mapY(moves[j].y), size, '#00ffff', '#008b8b');
+        drawDiamond(ctx, mapX(moves[j - 1].x), mapY(moves[j - 1].y), size,
+          COLORS.tabAwayLeftFill, COLORS.tabAwayLeftStroke);
+        drawDiamond(ctx, mapX(moves[j].x), mapY(moves[j].y), size,
+          COLORS.tabAwayReturnFill, COLORS.tabAwayReturnStroke);
 
-        // Dashed connector
         ctx.setLineDash([4, 3]);
-        ctx.strokeStyle = '#ff8c00';
+        ctx.strokeStyle = COLORS.tabAwayLeftStroke;
         ctx.beginPath();
         ctx.moveTo(mapX(moves[j - 1].x), mapY(moves[j - 1].y));
         ctx.lineTo(mapX(moves[j].x), mapY(moves[j].y));
         ctx.stroke();
         ctx.setLineDash([]);
       } else {
-        // Pause circle (grey)
-        ctx.fillStyle = '#ccc';
+        ctx.fillStyle = COLORS.pauseCircle;
         ctx.beginPath();
         ctx.arc(mapX(moves[j - 1].x), mapY(moves[j - 1].y), 3, 0, Math.PI * 2);
         ctx.fill();
@@ -295,8 +321,8 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
   ctx.globalAlpha = 1;
 
   // Start marker (blue circle)
-  ctx.fillStyle = '#0000ff';
-  ctx.strokeStyle = '#000';
+  ctx.fillStyle = COLORS.pathStart;
+  ctx.strokeStyle = COLORS.pathEndStroke;
   ctx.lineWidth = 0.5;
   ctx.beginPath();
   ctx.arc(mapX(moves[0].x), mapY(moves[0].y), 5, 0, Math.PI * 2);
@@ -306,18 +332,18 @@ function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
   // End marker (red square)
   const ex = mapX(moves[moves.length - 1].x);
   const ey = mapY(moves[moves.length - 1].y);
-  ctx.fillStyle = '#ff0000';
+  ctx.fillStyle = COLORS.pathEnd;
   ctx.fillRect(ex - 4, ey - 4, 8, 8);
   ctx.strokeRect(ex - 4, ey - 4, 8, 8);
 
-  // Mousedown markers (green triangles)
-  ctx.fillStyle = '#00cc00';
+  // Mousedown markers (green ▼)
+  ctx.fillStyle = COLORS.mousedown;
   for (const d of downs) {
     drawTriangle(ctx, mapX(d.x), mapY(d.y), 5, 'down');
   }
 
-  // Mouseup markers (magenta triangles)
-  ctx.fillStyle = '#ff00ff';
+  // Mouseup markers (magenta ▲)
+  ctx.fillStyle = COLORS.mouseup;
   for (const u of ups) {
     drawTriangle(ctx, mapX(u.x), mapY(u.y), 5, 'up');
   }
@@ -480,23 +506,31 @@ export function computeZoomScale(metadata) {
   };
 }
 
-// P7: pick the geometry frame and decide which rectangles are safe to draw.
-// Returns one of:
-//   { mode: 'screen-api', screenW, screenH, winX, winY, winW, winH, drawOuter: true }
-//   { mode: 'legacy',     screenW, screenH, winX, winY, winW, winH, drawOuter }
+// Picks the geometry frame and decides which rectangles are safe to draw.
+// Returns one of FOUR shapes:
+//   { mode: 'screen-api',  screenW, screenH, winX, winY, winW, winH, drawOuter: true }
+//   { mode: 'legacy',      screenW, screenH, winX, winY, winW, winH, drawOuter }
+//   { mode: 'window-only', winX, winY, winW, winH, drawOuter: false }
 //   { mode: 'auto-fit' }
 //
-// The 'screen-api' branch trusts metadata.screens (Window Management API). It
+// The 'screen-api' branch trusts metadata.screens (Window Management API) and
 // uses the screen the window currently sits on (currentScreenLabel-matched)
-// rather than the primary monitor, eliminating the multi-monitor paradox.
+// rather than the primary monitor — eliminates multi-monitor paradoxes.
+//
+// The 'legacy' branch covers data with screenWidth/screenHeight: draw both
+// rects when the geometry is internally consistent, drop the outer rect when
+// the window paradoxically exceeds the (primary-only) screen.
+//
+// The 'window-only' branch is for jsPsych extension data captured before
+// the April 2026 monitor change added window.screen.width/height to its
+// polled samples.
 //
-// The 'legacy' branch is the backward-compat path (Option B): draw both rects
-// when the geometry is internally consistent, drop the outer rect when the
-// window paradoxically exceeds the (primary-only) screen.
+// The 'auto-fit' branch is the catch-all: no usable geometry, fit canvas to
+// the mouse path.
 export function chooseScreenFrame(metadata) {
   if (!metadata) return { mode: 'auto-fit' };
 
-  // Branch 1: Window Management API data present (post-P7 collection).
+  // Branch 1: Window Management API data present.
   if (Array.isArray(metadata.screens) && metadata.screens.length > 0) {
     // Pick the screen the window lives on. If currentScreenLabel matches a
     // labeled entry, use it; otherwise prefer the screen whose bounds contain
@@ -515,7 +549,7 @@ export function chooseScreenFrame(metadata) {
     };
   }
 
-  // Branch 2: legacy data — primaryScreenWidth (post-P7 alias) or screenWidth.
+  // Branch 2: legacy data — primaryScreenWidth or screenWidth.
   const screenW = metadata.primaryScreenWidth ?? metadata.screenWidth;
   const screenH = metadata.primaryScreenHeight ?? metadata.screenHeight;
   if (screenW > 0 && screenH > 0) {
@@ -577,12 +611,20 @@ function pickCurrentScreen(metadata) {
   return screens.find(s => s.isPrimary) || screens[0];
 }
 
-// P7: compute a "zoom × N" tag when the viewport is scaled. Returns a string
-// like "zoom × 0.75" or null. Two heuristics:
-//   1. visualViewport.scale (post-P7 collection) — direct, exact.
-//   2. outerWidth/innerWidth ratio (post-P7 collection) — proxy for zoom level
-//      that doesn't require visualViewport API.
-// Pre-P7 data has neither, so this returns null and no tag is shown.
+// Compute a "zoom × N" tag for the panel title when the participant has
+// adjusted browser zoom away from 100%. Returns a string like "zoom × 0.75"
+// or null when zoom is within tolerance.
+//
+// Two heuristics, in order of directness:
+//   1. visualViewport.scale — direct API value, exact for pinch zoom on touch
+//      devices. Doesn't catch CSS-level browser zoom (Cmd-Plus / Cmd-Minus on
+//      desktop), which has no JS API.
+//   2. outerWidth / innerWidth ratio — proxy for CSS-level zoom. outer stays
+//      fixed in screen pixels; inner scales with zoom. Ratio ≈ 1 at 100%,
+//      < 1 zoomed out, > 1 zoomed in.
+//
+// Threshold of 10% (0.9 < ratio < 1.1) absorbs the typical chrome offset and
+// scrollbar width; only flags clear deviation from 100%.
 export function computeZoomTag(metadata) {
   if (!metadata) return null;
   const tol = 0.05;
@@ -590,15 +632,15 @@ export function computeZoomTag(metadata) {
   if (typeof vvScale === 'number' && Math.abs(vvScale - 1) > tol) {
     return `zoom × ${vvScale.toFixed(2)}`;
   }
+  // Read innerWidth directly. Earlier versions fell back to windowWidth here
+  // — but in the polled-geometry pipeline, windowWidth is an alias for
+  // outerWidth, so the fallback gave outerWidth/outerWidth = 1 and the tag
+  // never fired. Use innerWidth strictly.
   const ow = metadata.outerWidth;
-  const iw = metadata.windowWidth ?? metadata.innerWidth;
+  const iw = metadata.innerWidth;
   if (typeof ow === 'number' && typeof iw === 'number' && iw > 0) {
     const ratio = ow / iw;
-    // Larger outer/inner means user zoomed out (viewport > chrome).
-    // Smaller means zoomed in. Either way, flag deviation.
     if (Math.abs(ratio - 1) > 0.1) {
-      // Browser chrome itself takes ~5-10% of outer in normal cases; only flag
-      // if deviation is more extreme than typical chrome offset.
       const zoomEstimate = 1 / ratio;
       return `zoom × ${zoomEstimate.toFixed(2)}`;
     }

package/src/cli/report.js

@@ -26,7 +26,21 @@ export async function run(args) {
     (warnings.length ? ` (${warnings.length} files had warnings)` : ''));
 
   if (participants.length === 0) {
-    console.error('No valid participant data found. Check dataDir and filePattern.');
+    console.error(
+      `[cyborg-hunter] no valid participant data found in ${config.dataDir} (pattern: ${config.filePattern}).`
+    );
+    console.error(`  Common causes:`);
+    console.error(`    - dataDir points to the wrong directory`);
+    console.error(`    - filePattern doesn't match your file extensions (try "*.csv" or "*.{json,csv}")`);
+    console.error(`    - participantIdField doesn't match the actual field in your data`);
+    console.error(`      (jsPsych output usually uses "subject_ID", not "participantId")`);
+    if (warnings.length > 0) {
+      console.error(`  Per-file warnings (${warnings.length}):`);
+      for (const w of warnings.slice(0, 3)) {
+        console.error(`    - ${w.file}: ${w.warnings[0]}`);
+      }
+      if (warnings.length > 3) console.error(`    ... and ${warnings.length - 3} more`);
+    }
     process.exit(1);
   }
 

package/src/core/monitor.js

@@ -36,7 +36,7 @@ export function init(userConfig) {
   var presetName = userConfig.preset || "standard";
   var preset = PRESETS[presetName];
   if (!preset) {
-    throw new Error("IntegrityMonitor: unknown preset '" + presetName + "'. Use: permissive, standard, strict.");
+    throw new Error("[cyborg-hunter] unknown preset '" + presetName + "'. Use: permissive, standard, strict.");
   }
 
   // Build effective config: DEFAULT_THRESHOLDS → preset → user overrides.
@@ -75,19 +75,18 @@ export function init(userConfig) {
     decoyMap: userConfig.decoyMap || null,
     decoyVisibility: userConfig.decoyVisibility || "offscreen",
     decoyFraming: userConfig.decoyFraming || "answer-key",
-    decoyExcludeButtons: userConfig.decoyExcludeButtons || [".jspsych-btn"],
-    _debug: userConfig._debug || false
+    decoyExcludeButtons: userConfig.decoyExcludeButtons || [".jspsych-btn"]
   };
 
-  // Validate config keys — warn on typos
+  // Validate config keys — warn on typos.
   var KNOWN_KEYS = [
     "participantId", "preset", "signals", "thresholds", "scoring",
     "screenout", "domProtection", "collectForPostHoc", "decoyAnswers",
     "decoyMap", "decoyVisibility", "decoyFraming", "decoyExcludeButtons",
-    "onSignal", "experimentContainer", "knownInputs", "_debug"
+    "onSignal", "experimentContainer", "knownInputs"
   ];
   var warnings = validateConfig(userConfig, KNOWN_KEYS);
-  warnings.forEach(function (w) { console.warn("IntegrityMonitor: " + w); });
+  warnings.forEach(function (w) { console.warn("[cyborg-hunter] " + w); });
 
   // Freeze config
   Object.freeze(config);
@@ -159,8 +158,15 @@ export function init(userConfig) {
 
   function transition(to) {
     if (!sm.transition(to)) {
+      // Common causes: calling startTrial() while another trial is open
+      // (forgot endTrial?), calling endTrial() before startTrial(), or
+      // calling anything after destroy(). Show what was expected vs got
+      // so the user can match the lifecycle.
       throw new Error(
-        "IntegrityMonitor: invalid transition " + sm.current + " → " + to
+        "[cyborg-hunter] invalid lifecycle call: cannot transition from '" +
+        sm.current + "' to '" + to + "'. " +
+        "Expected order: init() → startSession() → (startTrial → endTrial)* → destroy(). " +
+        "Common cause: a startTrial() without a preceding endTrial(), or a call after destroy()."
       );
     }
   }
@@ -240,34 +246,45 @@ export function init(userConfig) {
         syntheticInsertions: []
       };
 
-      // Decoy injection
+      // Decoy injection. Logic in one place instead of four scattered branches:
+      //   - decoyAnswers off + opts.decoyAnswer set      → warn, no injection
+      //   - opts.decoyAnswer === false                   → record explicit skip
+      //   - opts.decoyAnswer is a non-empty string OR
+      //     config.decoyMap has an entry for this trial  → inject NOW
+      //   - anything else                                → defer via setTimeout(0)
+      //                                                    (gives DOM time to settle
+      //                                                    when startTrial runs
+      //                                                    before the trial UI is up)
+      // Invalid (non-string, non-false, non-null) values get a warning before
+      // the deferred inject.
       removeDecoyElement();
-      if (config.decoyAnswers) {
-        var currentTrialId = trialData.trialId;
-        if (opts.decoyAnswer === false) {
-          trialData.decoy = { level: 0, source: "skipped" };
-        } else if (typeof opts.decoyAnswer === "string" && opts.decoyAnswer.length > 0) {
-          injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
-        } else if (config.decoyMap && config.decoyMap[currentTrialId]) {
-          injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
-        } else if (opts.decoyAnswer != null && opts.decoyAnswer !== false) {
+      if (!config.decoyAnswers) {
+        if (opts.decoyAnswer != null) {
           console.warn(
-            "IntegrityMonitor: decoyAnswer must be a non-empty string, got: " +
-            typeof opts.decoyAnswer + ". Falling through to auto-detection."
+            "[cyborg-hunter] decoyAnswer provided but decoyAnswers is not enabled. " +
+            "Add decoyAnswers: true to init() config."
           );
-          setTimeout(function () {
-            injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
-          }, 0);
+        }
+      } else if (opts.decoyAnswer === false) {
+        trialData.decoy = { level: 0, source: "skipped" };
+      } else {
+        var currentTrialId = trialData.trialId;
+        var inject = function () {
+          injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
+        };
+        var hasExplicitString = typeof opts.decoyAnswer === "string" && opts.decoyAnswer.length > 0;
+        var hasMapEntry = config.decoyMap && config.decoyMap[currentTrialId];
+        if (hasExplicitString || hasMapEntry) {
+          inject();
         } else {
-          setTimeout(function () {
-            injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
-          }, 0);
+          if (opts.decoyAnswer != null) {
+            console.warn(
+              "[cyborg-hunter] decoyAnswer must be a non-empty string, got: " +
+              typeof opts.decoyAnswer + ". Falling through to auto-detection."
+            );
+          }
+          setTimeout(inject, 0);
         }
-      } else if (opts.decoyAnswer != null) {
-        console.warn(
-          "IntegrityMonitor: decoyAnswer provided but decoyAnswers is not enabled. " +
-          "Add decoyAnswers: true to init() config."
-        );
       }
 
       // Attach trial-scoped signal listeners

package/src/core/signals/dom-protection.js

@@ -188,7 +188,7 @@ export function injectDecoy(opts, expectedTrialId, config, trialData, getTrialDa
   } else if (config.decoyMap) {
     // decoyMap configured but trialId not found — Level 4 calibration fallback
     console.warn(
-      'IntegrityMonitor: No decoyMap entry for trialId "' + expectedTrialId +
+      '[cyborg-hunter] no decoyMap entry for trialId "' + expectedTrialId +
       '". Falling back to Level 3/4.'
     );
     var fallbackText = buildDecoyText(null, "calibration-metadata", null, _decoyTrialIndex);

package/src/core/state-machine.js

@@ -26,7 +26,7 @@ export function createStateMachine() {
         state = to;
         return true;
       }
-      console.warn("[CyborgHunter] Invalid transition: " + state + " → " + to);
+      console.warn("[cyborg-hunter] invalid transition: " + state + " → " + to);
       return false;
     }
   };