cyborg-hunter 0.3.0

package/src/cli/renderers/trajectories.js

@@ -0,0 +1,607 @@
+// 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).
+//
+// 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
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+// 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
+
+export async function renderTrajectories(participants, triage, config) {
+  const { createCanvas } = await import('canvas');
+  const triageMap = new Map(triage.map(t => [t.participantId, t]));
+
+  for (const p of participants) {
+    const trials = p.trials;
+    if (trials.length === 0) continue;
+
+    // Compute grid layout
+    const cols = Math.min(5, trials.length);
+    const rows = Math.ceil(trials.length / cols);
+
+    const canvasW = cols * (PANEL_W + PANEL_PAD) + PANEL_PAD;
+    const canvasH = HEADER_HEIGHT + rows * (PANEL_H + TITLE_HEIGHT + PANEL_PAD) + PANEL_PAD;
+    const canvas = createCanvas(canvasW, canvasH);
+    const ctx = canvas.getContext('2d');
+
+    // Background
+    ctx.fillStyle = '#ffffff';
+    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.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.
+    ctx.font = '11px sans-serif';
+    ctx.fillStyle = '#666';
+    ctx.fillText(
+      'Blue●=start  Red■=end  Green▼=mousedown  Magenta▲=mouseup  Yellow◆=tab-away (left)  Cyan◆=tab-away (returned)  Grey○=pause',
+      PANEL_PAD, 48
+    );
+    ctx.fillText(
+      'Teal outer rect=screen  Purple dashed rect=browser window  Red panel frame=hard signal triggered on this trial',
+      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.
+    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.
+      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);
+    }
+
+    const buf = canvas.toBuffer('image/png');
+    const filename = `trajectories_${sanitize(p.participantId)}.png`;
+    writeFileSync(join(config.outputDir, 'images', filename), buf);
+  }
+
+  console.log(`  trajectories — ${participants.length} images`);
+}
+
+function renderTrialPanel(ctx, trial, x0, y0, config, metadata) {
+  const mouse = trial.mouseEvents || [];
+  const tabAways = trial.tabAwayEvents || [];
+  const trialId = trial.trialId || trial.ruleId || '?';
+  const rt = (trial.duration_ms || trial.responseTime_ms || 0) / 1000;
+  const moves = mouse.filter(e => e.type === 'move');
+  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.
+  const anyHardHit = trial.trialSignals?.hard &&
+    Object.values(trial.trialSignals.hard).some(s => (s.trialHits || 0) > 0);
+  ctx.strokeStyle = anyHardHit ? '#ff0000' : '#ccc';
+  ctx.lineWidth = anyHardHit ? 3 : 1;
+  ctx.strokeRect(x0, y0 + TITLE_HEIGHT, PANEL_W, PANEL_H);
+
+  // Panel background
+  ctx.fillStyle = '#fafafa';
+  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.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.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.
+  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;
+    minX = 0;
+    minY = 0;
+    maxX = Math.max(screenW, winX + winW);
+    maxY = Math.max(screenH, winY + winH);
+    offsetX = winX;
+    offsetY = winY;
+  } else if (screenFrame.mode === 'window-only') {
+    // Frame the canvas around the window itself. Mouse coords are
+    // viewport-relative (0..innerWidth), so adding offsetX=winX places the
+    // trajectory inside the window outline at roughly the right spot. The
+    // chrome offset isn't accounted for, but for a no-screen visualization
+    // this is honest enough — the window outline shows scale and position.
+    const { winX, winY, winW, winH } = screenFrame;
+    minX = winX;
+    minY = winY;
+    maxX = winX + winW;
+    maxY = winY + winH;
+    offsetX = winX;
+    offsetY = winY;
+  } else {
+    // Auto-fit fallback
+    const allX = moves.map(m => m.x);
+    const allY = moves.map(m => m.y);
+    minX = Math.min(...allX) - 20;
+    maxX = Math.max(...allX) + 20;
+    minY = Math.min(...allY) - 20;
+    maxY = Math.max(...allY) + 20;
+    offsetX = 0;
+    offsetY = 0;
+  }
+  const rangeX = maxX - minX || 1;
+  const rangeY = maxY - minY || 1;
+
+  // Zoom-robust mouse plotting. Mouse coords (clientX/Y) are in viewport CSS
+  // pixels; the window outline is in screen CSS pixels. At non-100% browser
+  // zoom these scales differ — clicks would plot outside the outline.
+  // Scaling mouse coords by outer/inner ratio aligns them with the outline.
+  // Critically, X and Y scales are computed separately because chrome
+  // geometry isn't symmetric (top tabs+address bar vs ~zero left/right).
+  // 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);
+
+  // Screen + browser-window rectangles. The frame chooser above decides which
+  // rectangles are safe to draw. `drawOuter` is false for legacy data with a
+  // window/screen paradox (zoom-out, multi-monitor) — we'd rather show nothing
+  // than a screen rect smaller than the window it supposedly contains. It's
+  // 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);
+    ctx.save();
+    ctx.lineWidth = 1;
+    if (drawOuter) {
+      ctx.strokeStyle = '#26a69a';
+      ctx.strokeRect(
+        rectMapX(0), rectMapY(0),
+        rectMapX(screenW) - rectMapX(0),
+        rectMapY(screenH) - rectMapY(0)
+      );
+    }
+    ctx.strokeStyle = '#7e57c2';
+    ctx.setLineDash([4, 3]);
+    ctx.strokeRect(
+      rectMapX(winX), rectMapY(winY),
+      rectMapX(winX + winW) - rectMapX(winX),
+      rectMapY(winY + winH) - rectMapY(winY)
+    );
+    ctx.setLineDash([]);
+    ctx.restore();
+  }
+
+  // Zoom indicator — appended to the title. Honest signal that the viewport
+  // is scaled, so the viewer doesn't try to compare px counts across panels
+  // with different effective scales. Detected from visualViewport.scale or
+  // from outerWidth/innerWidth deviation.
+  const zoomTag = computeZoomTag(metadata);
+  if (zoomTag) {
+    ctx.fillStyle = '#a06000';
+    ctx.font = 'italic 10px sans-serif';
+    ctx.fillText(zoomTag, x0 + PANEL_W - 60, y0 + TITLE_HEIGHT - 8);
+  }
+
+  // Time normalization for color gradient
+  const ts = moves.map(m => m.t);
+  const tMin = Math.min(...ts);
+  const tMax = Math.max(...ts);
+  const tRange = tMax - tMin || 1;
+
+  // Draw path segments with time-based color (blue→red)
+  ctx.lineWidth = 1;
+  ctx.globalAlpha = 0.6;
+  for (let j = 1; j < moves.length; j++) {
+    const tNorm = (moves[j].t - tMin) / tRange;
+    ctx.strokeStyle = timeColor(tNorm);
+    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();
+
+    // Pause markers (>3s gap without matching tab-away).
+    // Both moves[j].t and ta.startRel_ms are trial-relative ms (normalized in ingest).
+    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 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');
+
+        // Dashed connector
+        ctx.setLineDash([4, 3]);
+        ctx.strokeStyle = '#ff8c00';
+        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.beginPath();
+        ctx.arc(mapX(moves[j - 1].x), mapY(moves[j - 1].y), 3, 0, Math.PI * 2);
+        ctx.fill();
+      }
+    }
+  }
+  ctx.globalAlpha = 1;
+
+  // Start marker (blue circle)
+  ctx.fillStyle = '#0000ff';
+  ctx.strokeStyle = '#000';
+  ctx.lineWidth = 0.5;
+  ctx.beginPath();
+  ctx.arc(mapX(moves[0].x), mapY(moves[0].y), 5, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.stroke();
+
+  // End marker (red square)
+  const ex = mapX(moves[moves.length - 1].x);
+  const ey = mapY(moves[moves.length - 1].y);
+  ctx.fillStyle = '#ff0000';
+  ctx.fillRect(ex - 4, ey - 4, 8, 8);
+  ctx.strokeRect(ex - 4, ey - 4, 8, 8);
+
+  // Mousedown markers (green triangles)
+  ctx.fillStyle = '#00cc00';
+  for (const d of downs) {
+    drawTriangle(ctx, mapX(d.x), mapY(d.y), 5, 'down');
+  }
+
+  // Mouseup markers (magenta triangles)
+  ctx.fillStyle = '#ff00ff';
+  for (const u of ups) {
+    drawTriangle(ctx, mapX(u.x), mapY(u.y), 5, 'up');
+  }
+}
+
+// Interpolates blue→red based on normalized time (0→1)
+function timeColor(t) {
+  const r = Math.round(t * 255);
+  const b = Math.round((1 - t) * 255);
+  return `rgb(${r}, 50, ${b})`;
+}
+
+function drawDiamond(ctx, x, y, size, fill, stroke) {
+  ctx.fillStyle = fill;
+  ctx.strokeStyle = stroke;
+  ctx.lineWidth = 1.5;
+  ctx.beginPath();
+  ctx.moveTo(x, y - size);
+  ctx.lineTo(x + size, y);
+  ctx.lineTo(x, y + size);
+  ctx.lineTo(x - size, y);
+  ctx.closePath();
+  ctx.fill();
+  ctx.stroke();
+}
+
+function drawTriangle(ctx, x, y, size, direction) {
+  ctx.beginPath();
+  if (direction === 'down') {
+    ctx.moveTo(x - size, y - size);
+    ctx.lineTo(x + size, y - size);
+    ctx.lineTo(x, y + size);
+  } else {
+    ctx.moveTo(x - size, y + size);
+    ctx.lineTo(x + size, y + size);
+    ctx.lineTo(x, y - size);
+  }
+  ctx.closePath();
+  ctx.fill();
+}
+
+function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 40);
+}
+
+// Picks the windowPositions sample closest in time to the trial's start
+// anchor and translates it into the field shape chooseScreenFrame() expects.
+//
+// Returns null when:
+//   - windowPositions is empty (e.g. signal disabled, or pre-tracking data)
+//   - the trial has no trialStart_perfNow (no time anchor → can't pick)
+//
+// Translation: monitor stores compact field names (x/y/w/h/iw/ih/sw/sh) for
+// terse JSON; the renderer's chooseScreenFrame reads expanded names. Doing
+// the rename here keeps both sides clean.
+//
+// The screenWidth/screenHeight fields are conditionally included — the
+// April 2026 monitor change added sw/sh capture, but older recordings
+// won't have it. Omitting (rather than zero-filling) lets chooseScreenFrame
+// fall through its legacy/auto-fit branches honestly.
+export function pickWindowGeometryForTrial(trial, windowPositions) {
+  if (!Array.isArray(windowPositions) || windowPositions.length === 0) return null;
+  const anchor = trial?.trialStart_perfNow;
+  if (typeof anchor !== 'number') return null;
+
+  // Selection strategy (in priority order):
+  //   1. Among samples within the trial's time range, prefer ones whose
+  //      viewport (after zoom-scaling) contains the trial's max mouse extent.
+  //      This handles trials that span a window resize — the trial's mouse
+  //      events may live in different viewport states, so we pick the one
+  //      that best contains them visually. Closest-in-time among fitting
+  //      candidates.
+  //   2. If no in-range sample fits, pick the in-range sample with the
+  //      largest viewport (best chance of mouse showing inside outline).
+  //   3. If nothing in range at all, fall back to the global closest-in-time.
+  //
+  // Without this, a trial that spanned a resize would get an arbitrary
+  // snapshot and mouse plotted outside the outline — visually misleading.
+
+  const duration = trial.duration_ms || 0;
+  const trialEnd = anchor + duration;
+  const moves = (trial.mouseEvents || []).filter(e => e.type === 'move');
+  const maxX = moves.length ? Math.max(...moves.map(m => m.x)) : 0;
+  const maxY = moves.length ? Math.max(...moves.map(m => m.y)) : 0;
+
+  function fits(s) {
+    if (!s.w || !s.iw || !s.h || !s.ih) return false;
+    return (maxX * s.w / s.iw) <= s.w && (maxY * s.h / s.ih) <= s.h;
+  }
+  function viewportArea(s) { return (s.iw || 0) * (s.ih || 0); }
+  function timeDelta(s) { return Math.abs(s.t - anchor); }
+
+  // Allow a 1-second slop on each end of the trial to account for resize
+  // event debouncing (samples may land slightly outside the trial window).
+  const inRange = duration > 0
+    ? windowPositions.filter(s => s.t >= anchor - 1000 && s.t <= trialEnd + 1000)
+    : windowPositions;
+
+  let best;
+  const fitting = inRange.filter(fits);
+  if (fitting.length > 0) {
+    best = fitting.reduce((a, b) => timeDelta(a) <= timeDelta(b) ? a : b);
+  } else if (inRange.length > 0) {
+    best = inRange.reduce((a, b) => viewportArea(a) >= viewportArea(b) ? a : b);
+  } else {
+    best = windowPositions.reduce((a, b) => timeDelta(a) <= timeDelta(b) ? a : b);
+  }
+
+  const out = {
+    windowX: best.x,
+    windowY: best.y,
+    windowWidth: best.w,
+    windowHeight: best.h,
+    // Both outer and inner dimensions on BOTH axes are needed by
+    // computeZoomScale — chrome asymmetry means the X and Y zoom factors
+    // genuinely differ. Earlier versions of this function dropped the
+    // height fields, which silently zeroed out the Y scale and plotted
+    // mouse Y way outside the outline at non-100% zoom.
+    outerWidth: best.w,
+    outerHeight: best.h,
+    innerWidth: best.iw,
+    innerHeight: best.ih,
+  };
+  if (typeof best.sw === 'number' && typeof best.sh === 'number') {
+    out.screenWidth = best.sw;
+    out.screenHeight = best.sh;
+  }
+  // Zoom diagnostics added April 2026. Optional — older recordings won't
+  // have these fields. devicePixelRatio captures HIDPI/retina scaling;
+  // visualViewportScale captures pinch zoom (touch devices, distinct
+  // from CSS-level browser zoom which we infer from outerWidth/innerWidth).
+  if (typeof best.dpr === 'number') out.devicePixelRatio = best.dpr;
+  if (typeof best.vvScale === 'number') out.visualViewportScale = best.vvScale;
+  return out;
+}
+
+// CSS-level browser zoom (Cmd-Plus / Cmd-Minus on desktop) has no direct JS
+// API. We infer it from the ratio of outer (window frame, fixed in screen
+// pixels) to inner (viewport, in CSS pixels that scale with zoom):
+//   zoom_factor ≈ outerWidth / innerWidth
+//   - ≈ 1 at 100% zoom
+//   - < 1 zoomed out (viewport reports MORE CSS pixels than outer frame)
+//   - > 1 zoomed in  (viewport reports FEWER CSS pixels than outer frame)
+//
+// Critically, X and Y zoom factors can differ because chrome geometry isn't
+// symmetric: most browsers have ~0px left/right chrome but ~80px top chrome
+// (tabs + address bar). On macOS retina especially, this asymmetry creates
+// significantly different x and y ratios, so a single uniform scale plots
+// mouse outside the outline on one axis. Returning {x, y} fixes this.
+//
+// Both fields default to 1 (identity, no scaling) when either dimension is
+// missing or non-positive — keeps callers honest without per-call null checks.
+export function computeZoomScale(metadata) {
+  if (!metadata) return { x: 1, y: 1 };
+  const ow = metadata.outerWidth, iw = metadata.innerWidth;
+  const oh = metadata.outerHeight, ih = metadata.innerHeight;
+  return {
+    x: (typeof ow === 'number' && typeof iw === 'number' && ow > 0 && iw > 0) ? ow / iw : 1,
+    y: (typeof oh === 'number' && typeof ih === 'number' && oh > 0 && ih > 0) ? oh / ih : 1,
+  };
+}
+
+// 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 }
+//   { mode: 'auto-fit' }
+//
+// The 'screen-api' branch trusts metadata.screens (Window Management API). It
+// uses the screen the window currently sits on (currentScreenLabel-matched)
+// rather than the primary monitor, eliminating the multi-monitor paradox.
+//
+// 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.
+export function chooseScreenFrame(metadata) {
+  if (!metadata) return { mode: 'auto-fit' };
+
+  // Branch 1: Window Management API data present (post-P7 collection).
+  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
+    // the window origin; otherwise fall back to the primary.
+    const current = pickCurrentScreen(metadata);
+    const winX = metadata.windowX ?? 0;
+    const winY = metadata.windowY ?? 0;
+    const winW = metadata.windowWidth || current.width;
+    const winH = metadata.windowHeight || current.height;
+    return {
+      mode: 'screen-api',
+      screenW: current.width,
+      screenH: current.height,
+      winX, winY, winW, winH,
+      drawOuter: true
+    };
+  }
+
+  // Branch 2: legacy data — primaryScreenWidth (post-P7 alias) or screenWidth.
+  const screenW = metadata.primaryScreenWidth ?? metadata.screenWidth;
+  const screenH = metadata.primaryScreenHeight ?? metadata.screenHeight;
+  if (screenW > 0 && screenH > 0) {
+    const winX = metadata.windowX ?? 0;
+    const winY = metadata.windowY ?? 0;
+    const winW = metadata.windowWidth || screenW;
+    const winH = metadata.windowHeight || screenH;
+    // Paradox check: window must fit inside screen for the outer rect to be
+    // honest. A 1px tolerance accommodates rounding. If the window exceeds
+    // the screen on any side, drop the outer rect — the participant likely
+    // zoomed out, used a secondary monitor, or has DPR scaling weirdness.
+    const tol = 1;
+    const fits =
+      winX >= -tol && winY >= -tol &&
+      (winX + winW) <= (screenW + tol) &&
+      (winY + winH) <= (screenH + tol);
+    return {
+      mode: 'legacy',
+      screenW, screenH, winX, winY, winW, winH,
+      drawOuter: fits
+    };
+  }
+
+  // Branch 3: window-only — we have window geometry but no screen size.
+  // Recordings made before the April 2026 monitor change (which added
+  // window.screen.width/height capture) hit this path. Draw just the
+  // browser-window rectangle; the screen rectangle is omitted because we
+  // genuinely don't know the screen dimensions.
+  if (metadata.windowWidth > 0 && metadata.windowHeight > 0) {
+    return {
+      mode: 'window-only',
+      winX: metadata.windowX ?? 0,
+      winY: metadata.windowY ?? 0,
+      winW: metadata.windowWidth,
+      winH: metadata.windowHeight,
+      drawOuter: false,
+    };
+  }
+
+  return { mode: 'auto-fit' };
+}
+
+function pickCurrentScreen(metadata) {
+  const screens = metadata.screens;
+  if (metadata.currentScreenLabel) {
+    const match = screens.find(s => s.label === metadata.currentScreenLabel);
+    if (match) return match;
+  }
+  // Prefer the screen whose availLeft/availTop bound the window origin.
+  if (typeof metadata.windowX === 'number' && typeof metadata.windowY === 'number') {
+    const containing = screens.find(s =>
+      metadata.windowX >= (s.availLeft ?? 0) &&
+      metadata.windowX < (s.availLeft ?? 0) + s.width &&
+      metadata.windowY >= (s.availTop ?? 0) &&
+      metadata.windowY < (s.availTop ?? 0) + s.height
+    );
+    if (containing) return containing;
+  }
+  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.
+export function computeZoomTag(metadata) {
+  if (!metadata) return null;
+  const tol = 0.05;
+  const vvScale = metadata.visualViewportScale;
+  if (typeof vvScale === 'number' && Math.abs(vvScale - 1) > tol) {
+    return `zoom × ${vvScale.toFixed(2)}`;
+  }
+  const ow = metadata.outerWidth;
+  const iw = metadata.windowWidth ?? 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)}`;
+    }
+  }
+  return null;
+}

package/src/cli/renderers/triage-md.js

@@ -0,0 +1,29 @@
+// src/cli/renderers/triage-md.js
+// Writes triage.md — a ranked markdown table of participants by suspiciousness.
+// This is the "start here" document for manual review.
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export async function renderTriage(triage, config) {
+  const lines = [
+    '# Participant Triage — Ranked by Suspiciousness',
+    '',
+    `_${triage.length} participants analyzed_`,
+    '',
+    '| Rank | Participant | Score | Hard | Reason |',
+    '|------|-------------|-------|------|--------|',
+  ];
+
+  triage.forEach((t, i) => {
+    const hard = t.hardTriggered ? '**YES**' : 'no';
+    // Escape pipe characters in reason text to avoid breaking the table
+    const reason = t.reason.replace(/\|/g, '\\|');
+    lines.push(`| ${i + 1} | ${t.participantId} | ${t.score} | ${hard} | ${reason} |`);
+  });
+
+  lines.push('');
+  const outPath = join(config.outputDir, 'triage.md');
+  writeFileSync(outPath, lines.join('\n'));
+  console.log(`  triage.md — ranked list`);
+}