From a0b69f8cc7a13dc92c80c12e60079c276be8bcbe Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Thu, 11 Jun 2026 21:33:31 -0500
Subject: [PATCH 01/11] Rearchitect click capture: strict click-time frames,
 off-main-process recorder, exact marker coordinates

Implements the architecture change from ai_prompts/prompt3.md:

- New app/click-frames.js: shared timestamped frame ring + strict
  click-to-frame pairing (never a frame whose grab started after the
  click); legacy slack behavior kept behind capture.strictClickFrames=false.
- New stream capture backend (app/stream-backend.js + hidden worker
  window): per-display desktop media streams sampled into ring buffers
  and PNG-encoded entirely off the main process, so click delivery is
  never starved by capture work. Auto-degrades to the legacy in-process
  frame loop when streams cannot start or the worker stops answering.
- Clicks are paired with their frame at event time (eager pairing in
  enqueueClickCapture); only the storing is serialized, so slow encodes
  cannot skew later clicks in a fast burst.
- Linux watcher: restored event-time root coordinates from
  xinput test-xi2 and merge raw/regular twin events structurally.
- Replaced the 40ms time debounce with source-aware duplicate
  suppression: fast legitimate clicks are never dropped.
- New app/coords.js: physical-to-DIP conversion with multi-monitor and
  scale-factor handling; Windows keeps screenToDipPoint.
- STEPFORGE_CLICK_SELFTEST end-to-end hook: 3/3 clicks become steps via
  the stream backend with 0.00% marker offset on this host.
- Tests rewritten/added: strict selection, coords, stream backend,
  Linux coordinate parsing, twin merge, burst clicking (126 passing).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture-worker-preload.js     |  17 +
 app/capture.js                    | 506 +++++++++++++++++++++++-------
 app/click-frames.js               | 162 ++++++++++
 app/coords.js                     | 110 +++++++
 app/main.js                       |  56 ++++
 app/renderer/capture-worker.html  |  11 +
 app/renderer/capture-worker.js    | 199 ++++++++++++
 app/stream-backend.js             | 294 +++++++++++++++++
 core/settings.js                  |   9 +
 docs/ARCHITECTURE.md              |  35 +++
 tests/unit/capture.test.js        | 459 ++++++++++++++++++++++++---
 tests/unit/click-frames.test.js   | 134 ++++++++
 tests/unit/coords.test.js         |  88 ++++++
 tests/unit/stream-backend.test.js | 191 +++++++++++
 14 files changed, 2109 insertions(+), 162 deletions(-)
 create mode 100644 app/capture-worker-preload.js
 create mode 100644 app/click-frames.js
 create mode 100644 app/coords.js
 create mode 100644 app/renderer/capture-worker.html
 create mode 100644 app/renderer/capture-worker.js
 create mode 100644 app/stream-backend.js
 create mode 100644 tests/unit/click-frames.test.js
 create mode 100644 tests/unit/coords.test.js
 create mode 100644 tests/unit/stream-backend.test.js

diff --git a/app/capture-worker-preload.js b/app/capture-worker-preload.js
new file mode 100644
index 0000000..e9e34a3
--- /dev/null
+++ b/app/capture-worker-preload.js
@@ -0,0 +1,17 @@
+'use strict';
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+/**
+ * Bridge for the hidden capture-worker window. The worker only ever talks to
+ * the StreamCaptureBackend in the main process: commands in (start streams,
+ * frame requests), events out (stream health, PNG-encoded frames).
+ */
+contextBridge.exposeInMainWorld('captureWorkerBridge', {
+  onCommand(fn) {
+    ipcRenderer.on('capture-worker:command', (_event, msg) => fn(msg));
+  },
+  send(msg) {
+    ipcRenderer.send('capture-worker:event', msg);
+  },
+});
diff --git a/app/capture.js b/app/capture.js
index f157760..891e56d 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -6,53 +6,74 @@ const { desktopCapturer, screen, BrowserWindow, nativeImage, Tray, Menu, Notific
 const { expandPlaceholders } = require('../core/placeholders');
 const raster = require('../core/raster');
 const { encodePng } = require('../core/png');
+const {
+  selectFrameForClick,
+  frameUsableForClick,
+  pointInBounds,
+  DEFAULT_MAX_AGE_MS,
+  DEFAULT_START_SLACK_MS,
+} = require('./click-frames');
+const { physicalToDip } = require('./coords');
 
 /**
- * Capture service: full-screen, active-window, and region capture via
- * Electron's desktopCapturer, plus a click-marker annotation at the cursor
- * position and a capture session (start/pause/resume/finish).
+ * Capture service: full-screen, active-window, and region capture, plus a
+ * click-marker annotation at the click position and a capture session
+ * (start/pause/resume/finish).
  *
  * A session captures continuously, with three triggers layered by what the
  * platform supports:
- *  - click-capture via an OS adapter (xinput on X11, PowerShell on Windows),
+ *  - click-capture via an OS adapter (xinput on X11, a low-level mouse hook
+ *    on Windows),
  *  - a global hotkey (unreliable on some Wayland compositors),
  *  - interval auto-capture as the always-works fallback.
  *
+ * Click captures are served from one of two frame recorders:
+ *  - the stream backend (app/stream-backend.js): a hidden worker window
+ *    samples a desktop media stream per display into a timestamped ring
+ *    buffer, entirely off the main process. This is the preferred path —
+ *    the main-process event loop stays free, so OS click events arrive on
+ *    time, and the tight sampling cadence keeps a genuinely fresh pre-click
+ *    frame available for every click;
+ *  - the legacy in-process frame loop below, kept as the fallback when
+ *    streams can't start (portal-less Wayland, exotic drivers).
+ *
+ * Either way the pairing rule is the same (click-frames.js): in strict mode
+ * a click only ever gets a frame captured at or before the click — never one
+ * whose grab started after it.
+ *
  * Note: under Wayland/WSLg, screen capture may require portal support; all
  * failures surface as { ok: false, reason } instead of crashing.
  */
 
-// Dedupe duplicate watcher events for one physical click while still
-// allowing intentionally fast clicking.
-const CLICK_DEBOUNCE_MS = 40;
-// Idle gap between frame-loop grabs. Must stay well above zero: grabbing
-// back-to-back starves the main-process event loop, which delays delivery
-// of click events from the OS watcher by whole seconds. The frame history
-// plus hook-side click timestamps tolerate the coarser cadence.
+// Suppress only *duplicate deliveries* of one physical press (same button,
+// same coordinates, a few ms apart). This deliberately replaces the old
+// time-only debounce: real humans double-click ~50-100ms apart, and any
+// purely temporal cutoff eventually drops a legitimate fast click, which
+// reads as "my click didn't register". One hook/watcher event = one click.
+const CLICK_EVENT_DUPLICATE_MS = 8;
+// How long a Linux raw button event waits for its regular twin (the
+// representation that carries root coordinates) before firing without them.
+const LINUX_CLICK_TWIN_MS = 25;
+// Idle gap between legacy frame-loop grabs. Must stay well above zero:
+// grabbing back-to-back starves the main-process event loop, which delays
+// delivery of click events from the OS watcher by whole seconds. (The
+// stream backend exists precisely because of this constraint.)
 const FRAME_LOOP_IDLE_MS = 200;
 // A buffered frame older than this is too stale to pass off as "the screen
-// at the instant of the click".
-const CLICK_FRAME_MAX_AGE_MS = 600;
+// at the instant of the click". Shared with click-frames.js.
+const CLICK_FRAME_MAX_AGE_MS = DEFAULT_MAX_AGE_MS;
 // How long a click waits for the in-flight grab before falling back to a
 // one-off fresh shot.
 const CLICK_FRAME_WAIT_MS = 2000;
-// A loop grab that started at most this long after the click still shows
-// the screen the user clicked on (UI reactions render slower than this).
-const CLICK_FRAME_START_SLACK_MS = 300;
+// Balanced (non-strict) mode only: a loop grab that started at most this
+// long after the click is still accepted. Strict mode never does this.
+const CLICK_FRAME_START_SLACK_MS = DEFAULT_START_SLACK_MS;
 const CLICK_CAPTURE_HIDE_DELAY_MS = 25;
-// Frames now hold raw images (~20MB each at 2880x1800), so keep the history
+// Frames hold raw images (~20MB each at 2880x1800), so keep the history
 // window wide enough to outlast any processing hiccup but the count low.
 const RECENT_FRAME_RETENTION_MS = 4000;
 const RECENT_FRAME_LIMIT = 4;
 
-function pointInBounds(point, bounds) {
-  if (!point || !bounds) return false;
-  return point.x >= bounds.x
-    && point.x <= bounds.x + bounds.width
-    && point.y >= bounds.y
-    && point.y <= bounds.y + bounds.height;
-}
-
 function hasBinary(name) {
   try {
     execFileSync('which', [name], { stdio: 'pipe' });
@@ -63,11 +84,14 @@ function hasBinary(name) {
 }
 
 class CaptureService {
-  constructor({ store, settings, getWindow, notify }) {
+  constructor({ store, settings, getWindow, notify, screenApi = screen }) {
     this.store = store;
     this.settings = settings;
     this.getWindow = getWindow;
     this.notify = notify;
+    // Injectable for tests; the click/coordinate paths must never reach for
+    // the global `screen` directly so coordinate handling stays testable.
+    this.screen = screenApi;
     this.session = null; // { guideId, paused, count, intervalSec }
     this.intervalTimer = null;
     this.clickWatcher = null;
@@ -76,14 +100,17 @@ class CaptureService {
     this.frameWaiters = [];
     this.latestFrame = null;
     this.clickWatcherBuf = '';
-    this.clickWatcherPendingPress = false;
     this.clickWatcherErrTail = '';
+    this.linuxEvent = null; // event block currently being parsed
+    this.pendingRawClick = null; // raw press waiting for its coordinate twin
     this.clickQueue = Promise.resolve();
     this.frameLoopInFlight = false;
     this.frameLoopGrabStartedAt = null;
     this.recentFrames = [];
     this.shooting = false;
-    this.lastClickCaptureByButton = new Map();
+    this.lastClickEventByButton = new Map();
+    this.streamBackend = null;
+    this.streamBackendStarting = false;
   }
 
   state() {
@@ -96,10 +123,24 @@ class CaptureService {
         intervalSec: this.session.intervalSec || 0,
         clickCapture: Boolean(this.clickWatcher),
         clickCaptureAvailable: this.clickCaptureAvailable(),
+        clickFrameSource: this.streamBackend ? 'stream' : (this.frameLoopRunning ? 'loop' : 'idle'),
+        strictClickFrames: this.strictClickFrames(),
       }
       : { active: false, clickCaptureAvailable: this.clickCaptureAvailable() };
   }
 
+  /**
+   * Strict is the default: a stored step must never show the screen *after*
+   * its click (a frame whose grab started post-click can already contain the
+   * click's effects). The setting exists as an explicit escape hatch for
+   * machines where capture is too slow to keep pre-click frames buffered —
+   * there, the legacy slack heuristics trade accuracy for fewer fresh-shot
+   * fallbacks.
+   */
+  strictClickFrames() {
+    return this.settings.get('capture.strictClickFrames') !== false;
+  }
+
   clickCaptureAvailable() {
     if (this._clickAvail === undefined) {
       this._clickAvail = process.platform === 'win32' || (process.platform === 'linux' && hasBinary('xinput'));
@@ -223,22 +264,23 @@ class CaptureService {
     const wasPaused = this.session.paused;
     this.session.paused = typeof force === 'boolean' ? force : !this.session.paused;
     // Starting/resuming tucks the window away again for clean shots (after
-    // a brief delay so the user sees it happen) and starts the frame loop
-    // that serves click captures. Pausing stops the loop and discards the
-    // buffered frame, so a resume can never serve a pre-pause screen.
+    // a brief delay so the user sees it happen) and starts the frame
+    // recorder that serves click captures. Pausing stops it and discards
+    // buffered frames, so a resume can never serve a pre-pause screen.
     if (wasPaused && !this.session.paused) {
       const win = this.getWindow();
       const arm = () => {
         if (!this.session || this.session.paused) return;
         if (this.hiddenForSession && win && !win.isDestroyed() && win.isVisible()) win.hide();
         if (this.settings.get('capture.captureOutsideClicks') !== false && this.clickCaptureAvailable()) {
-          this.startFrameLoop();
+          this.startClickFrameBackend().catch(() => {});
         }
       };
       if (this.hiddenForSession && win && !win.isDestroyed()) setTimeout(arm, 400);
       else arm();
     } else if (!wasPaused && this.session.paused) {
       this.stopFrameLoop();
+      this.stopClickFrameBackend();
     }
     if (this.rebuildTrayMenu) this.rebuildTrayMenu();
     this.notify('capture:state', this.state());
@@ -251,6 +293,7 @@ class CaptureService {
     }
     this.stopClickWatcher();
     this.stopFrameLoop();
+    this.stopClickFrameBackend();
     this.destroySessionTray();
     this.session = null;
     if (this.hiddenForSession) {
@@ -269,7 +312,7 @@ class CaptureService {
   userIsInApp() {
     const win = this.getWindow();
     if (!win || win.isDestroyed() || !win.isVisible() || win.isMinimized()) return false;
-    const cur = screen.getCursorScreenPoint();
+    const cur = this.screen.getCursorScreenPoint();
     const b = win.getBounds();
     return cur.x >= b.x && cur.x <= b.x + b.width && cur.y >= b.y && cur.y <= b.y + b.height;
   }
@@ -283,14 +326,18 @@ class CaptureService {
       return { ok: false, reason: 'skipped — StepForge is focused' };
     }
 
-    // Clicks are served from the frame loop: the buffered frame was grabbed
-    // at (or moments before) the click instant, so the background matches
-    // what the user clicked on. A click that lands while a grab is in
-    // flight waits for that frame instead of being dropped, so fast
+    // Clicks are served from the frame recorder: the chosen frame was
+    // captured at (or moments before) the click instant, so the background
+    // matches what the user clicked on. A click that lands while a grab is
+    // in flight waits for that frame instead of being dropped, so fast
     // clicking still yields one step per click.
     if (trigger === 'click') {
       const clickAt = clickMeta && Number.isFinite(clickMeta.at) ? clickMeta.at : Date.now();
-      const frame = await this.frameForClick(clickPos, clickAt);
+      // Prefer the frame the click was paired with at event time (see
+      // enqueueClickCapture); ask now only when no eager pairing happened.
+      const frame = clickMeta && clickMeta.framePromise
+        ? await clickMeta.framePromise
+        : await this.frameForClick(clickPos, clickAt);
       if (!this.session || this.session.paused) return { ok: false, reason: 'no active capture session' };
       if (frame) {
         const result = this.storeFrameAsStep(this.session.guideId, frame.mode, frame, clickPos);
@@ -335,11 +382,14 @@ class CaptureService {
   // ---- click-triggered capture --------------------------------------------
 
   /**
-   * Continuous screen-grab loop that runs while recording. It keeps the most
-   * recent frame in `latestFrame` so a click can be served from a frame
-   * grabbed at (or moments before) the instant of the click — a fresh grab
-   * started after the click would land hundreds of ms late and show the
-   * click's effects instead of what the user clicked on.
+   * Fallback frame recorder: a continuous screen-grab loop in the main
+   * process, used only when the stream backend can't run. It keeps the most
+   * recent frames buffered so a click can be served from a frame grabbed at
+   * (or moments before) the instant of the click — a fresh grab started
+   * after the click would land hundreds of ms late and show the click's
+   * effects instead of what the user clicked on. Its cadence is capped at
+   * FRAME_LOOP_IDLE_MS because tighter grabbing here starves the event loop
+   * and delays the very click events it serves.
    */
   startFrameLoop() {
     if (this.frameLoopRunning) return;
@@ -416,45 +466,67 @@ class CaptureService {
   }
 
   /**
-   * Freshest frame usable for a click capture: the buffered frame when it's
-   * recent enough, otherwise the next frame the loop delivers. Null when the
-   * loop isn't running or can't deliver in time.
+   * Frame representing the screen at the instant of one click.
+   *
+   * Order of preference:
+   *  1. the stream backend's ring buffer (off-main-process, tight cadence);
+   *  2. the legacy loop's buffered frames;
+   *  3. waiting for the loop grab that was already in flight when the user
+   *     clicked.
+   * Selection semantics live in click-frames.js. In strict mode every path
+   * obeys the same rule — never a frame whose grab started after the click —
+   * and when nothing qualifies this returns null so the caller takes the
+   * *explicit* fresh-shot fallback rather than silently passing a post-click
+   * frame off as the click-time screen.
    */
   async frameForClick(clickPos = null, clickAt = Date.now()) {
     const mode = this.settings.get('capture.mode') || 'fullscreen';
     const grabMode = mode === 'region' ? 'fullscreen' : mode;
     const clickTime = Number.isFinite(clickAt) ? clickAt : Date.now();
-    // Fast clicks can move to another monitor before the buffered frame is
-    // consumed; only reuse frames from the clicked display.
-    const usable = (f, { allowInFlight = false } = {}) => {
-      const sameDisplay = !clickPos || pointInBounds(clickPos, f && f.display && f.display.bounds);
-      const startedAt = Number.isFinite(f && f.startedAt) ? f.startedAt : (f && f.capturedAt);
-      const completedBeforeClick = Number.isFinite(f && f.capturedAt) && f.capturedAt <= clickTime;
-      // A grab that began within the slack window after the click still
-      // shows the click-instant screen (UI reactions take longer than the
-      // slack to render), and it beats the alternative — a fresh shot that
-      // both starts later and stalls the loop for every queued click.
-      const startedNearClick = Number.isFinite(startedAt)
-        && startedAt <= clickTime + CLICK_FRAME_START_SLACK_MS;
-      const timingMatches = completedBeforeClick
-        ? clickTime - f.capturedAt <= CLICK_FRAME_MAX_AGE_MS
-        : allowInFlight && startedNearClick;
-      return Boolean(f)
-        && f.mode === grabMode
-        && timingMatches
-        && sameDisplay;
+    const strict = this.strictClickFrames();
+    const opts = {
+      clickAt: clickTime,
+      clickPos,
+      mode: grabMode,
+      strict,
+      maxAgeMs: CLICK_FRAME_MAX_AGE_MS,
+      startSlackMs: CLICK_FRAME_START_SLACK_MS,
     };
-    const buffered = [...this.recentFrames, this.latestFrame]
-      .filter((f, i, arr) => f && arr.indexOf(f) === i && usable(f))
-      .sort((a, b) => b.capturedAt - a.capturedAt)[0];
+
+    if (this.streamBackend && this.streamBackend.isActive() && grabMode === 'fullscreen') {
+      const frame = await this.streamBackend.frameForClick({ clickPos, clickAt: clickTime, strict });
+      if (frame) return frame;
+      // No qualifying frame (or the backend just went unhealthy): fall
+      // through to the loop buffer / fresh-shot fallbacks below.
+    }
+
+    const buffered = selectFrameForClick(
+      [...this.recentFrames, this.latestFrame].filter((f, i, arr) => f && arr.indexOf(f) === i),
+      opts,
+    );
     if (buffered) return buffered;
-    // As long as the loop is running, the next grab is at most one idle gap
-    // away — wait for it rather than racing it with a one-off shot.
     if (!this.frameLoopRunning) return null;
+
+    if (strict) {
+      // Only a grab already in flight when the user clicked can still
+      // qualify: its pixels predate the click even though it completes
+      // after. Any grab starting later is post-click by definition, so
+      // don't wait around for one — return immediately and let the caller
+      // take the fresh-shot fallback.
+      const inFlightStartedBeforeClick = this.frameLoopInFlight
+        && Number.isFinite(this.frameLoopGrabStartedAt)
+        && this.frameLoopGrabStartedAt <= clickTime;
+      if (!inFlightStartedBeforeClick) return null;
+      const next = await this.nextFrame(CLICK_FRAME_WAIT_MS);
+      return frameUsableForClick(next, { ...opts, allowInFlight: true }) ? next : null;
+    }
+
+    // Balanced (legacy) mode: wait for the next loop frame and accept it if
+    // its grab started within the slack window after the click.
     const deadline = Date.now() + CLICK_FRAME_WAIT_MS;
     while (this.frameLoopRunning && Date.now() < deadline) {
       const next = await this.nextFrame(Math.max(1, deadline - Date.now()));
-      if (usable(next, { allowInFlight: true })) return next;
+      if (frameUsableForClick(next, { ...opts, allowInFlight: true })) return next;
       if (next && Number.isFinite(next.startedAt)
         && next.startedAt > clickTime + CLICK_FRAME_START_SLACK_MS) {
         // Grabs only get later from here; let the fresh-shot path handle it.
@@ -464,11 +536,79 @@ class CaptureService {
     return null;
   }
 
+  // ---- click-frame backends -------------------------------------------------
+
+  /**
+   * Bring up the frame recorder for a recording run. The stream backend is
+   * the architecture path (capture entirely off the main process); the
+   * in-process frame loop is the fallback when streams can't start — and the
+   * automatic degradation target if the worker stops answering mid-session.
+   */
+  async startClickFrameBackend() {
+    const mode = this.settings.get('capture.mode') || 'fullscreen';
+    // The worker streams screens; window-mode grabs need the loop's
+    // source-filtering logic.
+    if (this.settings.get('capture.streamCapture') === false || mode === 'window') {
+      this.startFrameLoop();
+      return;
+    }
+    if (this.streamBackend || this.streamBackendStarting) return;
+    this.streamBackendStarting = true;
+    try {
+      // eslint-disable-next-line global-require
+      const { StreamCaptureBackend, createElectronHost } = require('./stream-backend');
+      const backend = new StreamCaptureBackend({
+        createHost: createElectronHost,
+        onUnhealthy: () => this.degradeToFrameLoop(),
+      });
+      const displays = this.screen.getAllDisplays();
+      const sources = await desktopCapturer.getSources({
+        types: ['screen'],
+        thumbnailSize: { width: 1, height: 1 }, // ids only — skip thumbnail work
+      });
+      const ok = await backend.start({
+        displays,
+        sources: sources.map((s) => ({ id: s.id, display_id: s.display_id })),
+        sampleMs: this.settings.get('capture.frameSampleMs') || 100,
+      });
+      if (!ok || !this.session || this.session.paused) {
+        backend.stop();
+        if (this.session && !this.session.paused) this.startFrameLoop();
+        return;
+      }
+      this.streamBackend = backend;
+      this.notify('capture:state', this.state());
+    } catch {
+      if (this.session && !this.session.paused) this.startFrameLoop();
+    } finally {
+      this.streamBackendStarting = false;
+    }
+  }
+
+  stopClickFrameBackend() {
+    if (!this.streamBackend) return;
+    const backend = this.streamBackend;
+    this.streamBackend = null;
+    backend.stop();
+  }
+
+  /**
+   * The worker stopped answering frame requests. Capture must not silently
+   * stop mid-session: drop the backend and run the in-process loop for the
+   * rest of the recording.
+   */
+  degradeToFrameLoop() {
+    this.streamBackend = null;
+    console.error('[stepforge] stream capture backend unhealthy — falling back to in-process frame loop');
+    if (this.session && !this.session.paused) this.startFrameLoop();
+    this.notify('capture:state', this.state());
+  }
+
   startClickWatcher() {
     this.stopClickWatcher();
     try {
       this.clickWatcherBuf = '';
-      this.clickWatcherPendingPress = false;
+      this.linuxEvent = null;
       if (process.platform === 'linux' && hasBinary('xinput')) {
         // Stream raw button events from the X server; one capture per press.
         // xinput block-buffers stdout when piped, so a press event can sit
@@ -660,7 +800,8 @@ public static class SFMouseHook {
    * the session to interval captures, and tell the UI.
    */
   handleClickWatcherLoss(reason) {
-    this.clickWatcherPendingPress = false;
+    this.linuxEvent = null;
+    this.discardPendingRawClick();
     const detail = [reason, this.clickWatcherErrTail].filter(Boolean).join(' — ');
     console.error(`[stepforge] click watcher stopped${detail ? `: ${detail}` : ''}`);
     if (!this.session) return;
@@ -677,8 +818,9 @@ public static class SFMouseHook {
       this.clickWatcher = null;
     }
     this.clickWatcherBuf = '';
-    this.clickWatcherPendingPress = false;
-    this.lastClickCaptureByButton.clear();
+    this.linuxEvent = null;
+    this.discardPendingRawClick();
+    this.lastClickEventByButton.clear();
   }
 
   /**
@@ -698,29 +840,58 @@ public static class SFMouseHook {
   processClickWatcherData(text, platform = process.platform) {
     const lines = String(text).split(/\r?\n/);
     if (platform === 'linux') {
-      // xinput prints each event as a multi-line block: an "EVENT type …
-      // (RawButtonPress)" header followed by a "detail: N" line carrying the
-      // button number. Fire on the detail line so scroll-wheel ticks (X11
-      // reports them as buttons 4-7) neither create steps nor debounce away
-      // the real clicks that follow them.
+      // xinput test-xi2 --root prints each event as a multi-line block:
+      //
+      //   EVENT type 4 (ButtonPress)        EVENT type 15 (RawButtonPress)
+      //       device: 11 (10)                   device: 11 (11)
+      //       detail: 1                         detail: 1
+      //       root: 644.52/343.55               valuators: …
+      //
+      // Regular (non-raw) blocks carry the event-time root coordinates —
+      // exactly what the click marker needs, because a cursor read at parse
+      // time drifts whenever delivery is delayed or the pointer keeps
+      // moving after the click. Raw blocks have no coordinates, but on many
+      // servers they are the only representation delivered for the root
+      // window, so both kinds must fire. One physical press can produce
+      // *both* representations; that duplication is resolved structurally
+      // in fireLinuxClick (raw press briefly waits for its regular twin and
+      // they merge into one click), never by a time-only debounce that
+      // could swallow legitimate fast clicks.
       for (const line of lines) {
         if (!line) continue;
-        if (/RawButtonPress|ButtonPress/.test(line)) {
-          if (this.clickWatcherPendingPress) this.onOsClick();
-          this.clickWatcherPendingPress = true;
+        const header = /EVENT type \d+ \(([A-Za-z]+)\)/.exec(line);
+        if (header) {
+          this.finishLinuxEvent();
+          const name = header[1];
+          this.linuxEvent = /ButtonPress$/.test(name)
+            ? { name, raw: /^Raw/.test(name), button: null, at: Date.now(), fired: false }
+            : null;
           continue;
         }
-        if (!this.clickWatcherPendingPress) continue;
-        const detail = line.match(/detail:\s*(\d+)/);
+        const ev = this.linuxEvent;
+        if (!ev || ev.fired) continue;
+        const detail = /detail:\s*(\d+)/.exec(line);
         if (detail) {
-          this.clickWatcherPendingPress = false;
-          const button = Number(detail[1]);
-          if (button < 4 || button > 7) this.onOsClick(Date.now(), null, `button-${button}`);
-        } else if (line.includes('EVENT type')) {
-          // Next event arrived without a detail line in between — treat the
-          // pending press as a plain click rather than dropping it.
-          this.clickWatcherPendingPress = false;
-          this.onOsClick();
+          ev.button = Number(detail[1]);
+          if (ev.button >= 4 && ev.button <= 7) {
+            // Scroll-wheel ticks (X11 buttons 4-7) are not clicks.
+            this.linuxEvent = null;
+          } else if (ev.raw) {
+            // Raw blocks never carry coordinates; this one is complete.
+            ev.fired = true;
+            this.linuxEvent = null;
+            this.fireLinuxClick(ev.at, null, ev.button, { raw: true });
+          }
+          continue;
+        }
+        const root = /root:\s*(-?[\d.]+)\/(-?[\d.]+)/.exec(line);
+        if (root && !ev.raw && ev.button != null) {
+          ev.fired = true;
+          this.linuxEvent = null;
+          this.fireLinuxClick(ev.at, {
+            x: Math.round(parseFloat(root[1])),
+            y: Math.round(parseFloat(root[2])),
+          }, ev.button, { raw: false });
         }
       }
       return;
@@ -737,27 +908,127 @@ public static class SFMouseHook {
     }
   }
 
+  /**
+   * A new event header arrived while a press block was still open: the block
+   * ended without the line we fire on. Old xinput builds sometimes omit
+   * detail lines entirely — treat such a press as a plain click rather than
+   * dropping it.
+   */
+  finishLinuxEvent() {
+    const ev = this.linuxEvent;
+    this.linuxEvent = null;
+    if (!ev || ev.fired) return;
+    if (ev.button == null) {
+      this.onOsClick(ev.at, null, 'mouse');
+    } else if (!ev.raw) {
+      // Regular press whose root line never showed up — fire without
+      // coordinates; onOsClick falls back to a cursor read.
+      this.fireLinuxClick(ev.at, null, ev.button, { raw: false });
+    }
+  }
+
+  /**
+   * Funnel for parsed Linux button presses. Raw and regular blocks for the
+   * same physical press are merged here: a raw press (no coordinates) is
+   * held for LINUX_CLICK_TWIN_MS; if the regular twin (with root
+   * coordinates) arrives inside that window the pair fires once, with the
+   * raw block's earlier timestamp and the regular block's coordinates.
+   * Distinct presses always fire — there is no time-based dropping.
+   */
+  fireLinuxClick(at, osPoint, button, { raw = false } = {}) {
+    const pending = this.pendingRawClick;
+    if (raw) {
+      // Two raw presses can't be one click — release the held one first.
+      this.flushPendingRawClick();
+      const entry = { button, at, timer: null };
+      entry.timer = setTimeout(() => {
+        if (this.pendingRawClick !== entry) return;
+        this.pendingRawClick = null;
+        this.onOsClick(entry.at, null, `button-${entry.button}`);
+      }, LINUX_CLICK_TWIN_MS);
+      if (entry.timer.unref) entry.timer.unref();
+      this.pendingRawClick = entry;
+      return;
+    }
+    if (pending && pending.button === button) {
+      // The regular twin of the held raw press: one physical click.
+      this.pendingRawClick = null;
+      clearTimeout(pending.timer);
+      this.onOsClick(Math.min(pending.at, at), osPoint, `button-${button}`);
+      return;
+    }
+    this.onOsClick(at, osPoint, `button-${button}`);
+  }
+
+  /** Fire the held raw press immediately (its twin is not coming). */
+  flushPendingRawClick() {
+    const pending = this.pendingRawClick;
+    if (!pending) return;
+    this.pendingRawClick = null;
+    clearTimeout(pending.timer);
+    this.onOsClick(pending.at, null, `button-${pending.button}`);
+  }
+
+  discardPendingRawClick() {
+    if (!this.pendingRawClick) return;
+    clearTimeout(this.pendingRawClick.timer);
+    this.pendingRawClick = null;
+  }
+
   onOsClick(at = Date.now(), osPoint = null, button = 'mouse') {
     if (!this.session || this.session.paused) return;
     const clickAt = Number.isFinite(at) ? at : Date.now();
-    const debounceKey = button || 'mouse';
-    const last = this.lastClickCaptureByButton.get(debounceKey) || 0;
-    if (clickAt >= last && clickAt - last < CLICK_DEBOUNCE_MS) return;
-    this.lastClickCaptureByButton.set(debounceKey, clickAt);
+    // Source-aware dedupe, not a debounce: each hook/watcher event is one
+    // click however fast it follows the previous one. Only an *identical*
+    // event a few ms later — duplicate delivery of one physical press — is
+    // suppressed.
+    if (this.isDuplicateClickEvent(clickAt, osPoint, button)) return;
     // Prefer the position the watcher sampled with the button-down event
-    // (physical px -> DIP); otherwise read the cursor synchronously,
-    // right now, so the marker lands where the user clicked even if the
-    // shot itself takes a moment to grab. (Clicks on StepForge itself are
+    // (physical px -> DIP); otherwise read the cursor synchronously, right
+    // now, so the marker lands where the user clicked even if the shot
+    // itself takes a moment to grab. (Clicks on StepForge itself are
     // filtered by the cursor-position check in sessionCapture, not by
     // window focus — WSLg reports focus unreliably.)
-    let clickPos = null;
-    if (osPoint) {
-      clickPos = typeof screen.screenToDipPoint === 'function'
-        ? screen.screenToDipPoint(osPoint)
-        : osPoint;
+    let clickPos = osPoint ? this.osPointToDip(osPoint) : null;
+    if (!clickPos) clickPos = this.screen.getCursorScreenPoint();
+    this.enqueueClickCapture(clickPos, clickAt, button || 'mouse');
+  }
+
+  isDuplicateClickEvent(at, osPoint, button) {
+    const key = button || 'mouse';
+    const last = this.lastClickEventByButton.get(key);
+    this.lastClickEventByButton.set(key, { at, osPoint });
+    if (!last) return false;
+    if (at < last.at || at - last.at >= CLICK_EVENT_DUPLICATE_MS) return false;
+    // Same button within a few ms: duplicate only if it is the *same* event
+    // (same coordinates, or neither delivery carried coordinates).
+    if (osPoint && last.osPoint) {
+      return osPoint.x === last.osPoint.x && osPoint.y === last.osPoint.y;
     }
-    if (!clickPos) clickPos = screen.getCursorScreenPoint();
-    this.enqueueClickCapture(clickPos, clickAt, debounceKey);
+    return !osPoint && !last.osPoint;
+  }
+
+  /**
+   * Physical (OS event) pixels -> DIP. Windows exposes the canonical
+   * conversion; on Linux/X11 it is reconstructed from display geometry (see
+   * app/coords.js). Without this, the click marker drifts on any display
+   * scaled away from 100% and on secondary monitors.
+   */
+  osPointToDip(osPoint) {
+    if (this.screen && typeof this.screen.screenToDipPoint === 'function') {
+      try {
+        const dip = this.screen.screenToDipPoint(osPoint);
+        if (dip && Number.isFinite(dip.x) && Number.isFinite(dip.y)) return dip;
+      } catch { /* fall through to manual conversion */ }
+    }
+    try {
+      const displays = this.screen && typeof this.screen.getAllDisplays === 'function'
+        ? this.screen.getAllDisplays()
+        : [];
+      const dip = physicalToDip(osPoint, displays);
+      if (dip) return dip;
+    } catch { /* no display geometry available */ }
+    return osPoint;
   }
 
   /**
@@ -765,9 +1036,20 @@ public static class SFMouseHook {
    * still being stored queues behind it instead of being dropped by the
    * "capture already in progress" guard. The marker position was already
    * read at click time, so a queued step still circles the right spot.
+   *
+   * Crucially, only the *storing* is serialized. The click is paired with
+   * its frame right here, at event time: behind a slow store or PNG encode
+   * the queue can run seconds late, and a frame request issued that late
+   * could find the click-time frame already evicted from the ring buffer.
+   * Eager pairing keeps one-click-one-frame semantics intact no matter how
+   * fast the user clicks or how slow the encoder is.
    */
   enqueueClickCapture(clickPos, clickAt = Date.now(), button = 'mouse') {
     const clickMeta = { at: Number.isFinite(clickAt) ? clickAt : Date.now(), button: button || 'mouse' };
+    if (this.session && !this.session.paused && !this.userIsInApp()) {
+      clickMeta.framePromise = this.frameForClick(clickPos, clickMeta.at)
+        .catch(() => null);
+    }
     this.clickQueue = this.clickQueue
       .then(() => this.sessionCapture('click', clickPos, clickMeta))
       .catch(() => {});
@@ -795,8 +1077,10 @@ public static class SFMouseHook {
   storeFrameAsStep(guideId, mode, frame, clickPos = null) {
     if (!frame) return { ok: false, reason: 'no capture frame available' };
     const annotations = [];
-    const cursor = clickPos || frame.cursor;
-    if (mode !== 'window' && this.settings.get('capture.clickMarker')) {
+    // The click position (DIP, read at event time) wins over the frame's
+    // grab-time cursor; stream-backend frames carry no cursor at all.
+    const cursor = clickPos || frame.cursor || null;
+    if (cursor && mode !== 'window' && this.settings.get('capture.clickMarker')) {
       const fx = (cursor.x - frame.display.bounds.x) / frame.display.bounds.width;
       const fy = (cursor.y - frame.display.bounds.y) / frame.display.bounds.height;
       if (fx >= 0 && fx <= 1 && fy >= 0 && fy <= 1) {
@@ -837,8 +1121,8 @@ public static class SFMouseHook {
 
   /** Grab the screen/window image as { image, display } or throw. */
   async grab(mode, cursorPoint = null) {
-    const cursor = cursorPoint || screen.getCursorScreenPoint();
-    const display = screen.getDisplayNearestPoint(cursor);
+    const cursor = cursorPoint || this.screen.getCursorScreenPoint();
+    const display = this.screen.getDisplayNearestPoint(cursor);
     const { width, height } = display.size;
     const scale = display.scaleFactor || 1;
     // Ask for both kinds: some compositors (WSLg/Wayland portals) expose no
diff --git a/app/click-frames.js b/app/click-frames.js
new file mode 100644
index 0000000..f46c4c1
--- /dev/null
+++ b/app/click-frames.js
@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * Click ↔ frame correlation logic, shared by the main process and the
+ * capture-worker renderer (loaded there via a plain <script> tag, hence the
+ * UMD-style export at the bottom and the total absence of dependencies).
+ *
+ * The model: a recorder keeps a ring buffer of timestamped frames, each with
+ *   { startedAt, capturedAt }  — when the grab began and when it completed.
+ * A click carries its own hook-time timestamp. Pairing the two answers
+ * "what did the screen look like when the user clicked?".
+ *
+ * Strict mode encodes the product requirement (Folge-like recording): a step
+ * must show the screen *at or before* the click, never after it. A frame
+ * whose grab started after the click can already contain the click's effects
+ * (menus opened, pages navigated), so strict mode rejects it outright — the
+ * caller falls back to an explicit fresh shot instead of silently passing a
+ * post-click frame off as the click-time screen. Balanced mode keeps the old
+ * slack-window behavior for platforms where capture is too slow to keep a
+ * pre-click frame buffered.
+ */
+
+const DEFAULT_FRAME_LIMIT = 6;
+const DEFAULT_RETENTION_MS = 4000;
+// A frame older than this is too stale to pass off as "the screen at the
+// instant of the click".
+const DEFAULT_MAX_AGE_MS = 600;
+// Balanced mode only: a grab that began within this window after the click
+// is accepted on the assumption that UI reactions render slower than this.
+const DEFAULT_START_SLACK_MS = 300;
+
+function pointInBounds(point, bounds) {
+  if (!point || !bounds) return false;
+  return point.x >= bounds.x
+    && point.x <= bounds.x + bounds.width
+    && point.y >= bounds.y
+    && point.y <= bounds.y + bounds.height;
+}
+
+/**
+ * Ring buffer of recent frames, bounded by both count and age. Frames are
+ * raw images (potentially tens of MB each), so eviction is eager and an
+ * optional onEvict hook lets callers release native resources (e.g.
+ * ImageBitmap.close() in the capture worker).
+ */
+class FrameRing {
+  constructor({ limit = DEFAULT_FRAME_LIMIT, retentionMs = DEFAULT_RETENTION_MS, now = Date.now, onEvict = null } = {}) {
+    this.limit = limit;
+    this.retentionMs = retentionMs;
+    this.now = now;
+    this.onEvict = onEvict;
+    this.items = [];
+  }
+
+  push(frame) {
+    if (!frame) return null;
+    this.items.push(frame);
+    this.prune();
+    return frame;
+  }
+
+  prune() {
+    const cutoff = this.now() - this.retentionMs;
+    while (this.items.length
+      && (this.items.length > this.limit || !(this.items[0].capturedAt >= cutoff))) {
+      const evicted = this.items.shift();
+      if (this.onEvict) this.onEvict(evicted);
+    }
+  }
+
+  frames() {
+    return [...this.items];
+  }
+
+  latest() {
+    return this.items.length ? this.items[this.items.length - 1] : null;
+  }
+
+  clear() {
+    const dropped = this.items;
+    this.items = [];
+    if (this.onEvict) for (const f of dropped) this.onEvict(f);
+  }
+}
+
+/**
+ * Whether one frame may represent one click.
+ *
+ * Strict mode accepts only:
+ *  - a frame completed at or before the click (and not older than maxAgeMs), or
+ *  - when allowInFlight is set, a frame whose grab *started* at or before the
+ *    click — its pixels predate the click's effects even though encoding
+ *    finished after.
+ * A frame whose grab started after the click is never acceptable in strict
+ * mode, no matter how close: that is exactly the "screenshot shows the menu
+ * already open" failure.
+ *
+ * Balanced mode additionally accepts in-flight frames that started within
+ * startSlackMs after the click (the legacy heuristic).
+ */
+function frameUsableForClick(frame, {
+  clickAt,
+  clickPos = null,
+  mode = null,
+  strict = true,
+  allowInFlight = false,
+  maxAgeMs = DEFAULT_MAX_AGE_MS,
+  startSlackMs = DEFAULT_START_SLACK_MS,
+} = {}) {
+  if (!frame) return false;
+  if (mode && frame.mode !== mode) return false;
+  // Fast clicks can move to another monitor before a buffered frame is
+  // consumed; only reuse frames from the clicked display.
+  if (clickPos && frame.display && !pointInBounds(clickPos, frame.display.bounds)) return false;
+
+  const clickTime = Number.isFinite(clickAt) ? clickAt : Date.now();
+  const capturedAt = frame.capturedAt;
+  const startedAt = Number.isFinite(frame.startedAt) ? frame.startedAt : capturedAt;
+
+  const completedBeforeClick = Number.isFinite(capturedAt) && capturedAt <= clickTime;
+  if (completedBeforeClick) return clickTime - capturedAt <= maxAgeMs;
+
+  if (!allowInFlight || !Number.isFinite(startedAt)) return false;
+  if (strict) return startedAt <= clickTime;
+  return startedAt <= clickTime + startSlackMs;
+}
+
+/**
+ * Best already-buffered frame for a click: the newest frame that qualifies
+ * under frameUsableForClick. Buffered frames are by definition completed, so
+ * in-flight acceptance never applies here. Returns null when nothing
+ * qualifies and the caller must wait for the in-flight grab or fall back to
+ * a fresh shot.
+ */
+function selectFrameForClick(frames, opts = {}) {
+  let best = null;
+  for (const frame of frames || []) {
+    if (!frameUsableForClick(frame, { ...opts, allowInFlight: false })) continue;
+    if (!best || frame.capturedAt > best.capturedAt) best = frame;
+  }
+  return best;
+}
+
+const api = {
+  FrameRing,
+  frameUsableForClick,
+  selectFrameForClick,
+  pointInBounds,
+  DEFAULT_FRAME_LIMIT,
+  DEFAULT_RETENTION_MS,
+  DEFAULT_MAX_AGE_MS,
+  DEFAULT_START_SLACK_MS,
+};
+
+/* eslint-disable no-undef */
+if (typeof module === 'object' && module.exports) {
+  module.exports = api;
+} else if (typeof self !== 'undefined') {
+  self.StepForgeClickFrames = api;
+} else if (typeof window !== 'undefined') {
+  window.StepForgeClickFrames = api;
+}
diff --git a/app/coords.js b/app/coords.js
new file mode 100644
index 0000000..08a47ca
--- /dev/null
+++ b/app/coords.js
@@ -0,0 +1,110 @@
+'use strict';
+
+const { pointInBounds } = require('./click-frames');
+
+/**
+ * Coordinate-space conversion between physical (OS event) pixels and
+ * Electron DIP points.
+ *
+ * Why this exists: OS-level click hooks report *physical* pixels (the X11
+ * root window space on Linux, virtual-screen pixels on Windows), while
+ * everything Electron-side — display bounds, cursor reads, the click-marker
+ * math in storeFrameAsStep — is in DIP. Mixing the two spaces is exactly the
+ * bug that makes the red marker drift on scaled displays: at 150% scaling a
+ * physical click at (1500, 900) is the DIP point (1000, 600), and a marker
+ * drawn at the physical values lands well below-right of the real click.
+ *
+ * On Windows, Electron exposes screen.screenToDipPoint() and the capture
+ * service prefers it. On Linux/X11 there is no such API, so we reconstruct
+ * the mapping from display geometry: each display's DIP bounds plus its
+ * scaleFactor give its physical rectangle, and a physical point inside that
+ * rectangle maps back linearly. With mixed-DPI multi-monitor X11 setups the
+ * origin reconstruction is an approximation (X11 itself has a single global
+ * coordinate space), but it is exact for the overwhelmingly common cases:
+ * single display at any scale, and multi-display with a uniform scale.
+ */
+
+/** Physical-pixel rectangle a display occupies, derived from DIP bounds. */
+function physicalBoundsOf(display) {
+  const bounds = display && display.bounds;
+  if (!bounds) return null;
+  const scale = display.scaleFactor || 1;
+  return {
+    x: Math.round(bounds.x * scale),
+    y: Math.round(bounds.y * scale),
+    width: Math.round(bounds.width * scale),
+    height: Math.round(bounds.height * scale),
+  };
+}
+
+function centerDistanceSq(point, rect) {
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  return (point.x - cx) ** 2 + (point.y - cy) ** 2;
+}
+
+/**
+ * Display whose physical rectangle contains the point, or the nearest one
+ * (clicks on the very edge of a screen can round to one pixel outside it).
+ */
+function displayForPhysicalPoint(point, displays) {
+  if (!point || !Array.isArray(displays) || !displays.length) return null;
+  let nearest = null;
+  let nearestDist = Infinity;
+  for (const display of displays) {
+    const phys = physicalBoundsOf(display);
+    if (!phys) continue;
+    if (pointInBounds(point, phys)) return display;
+    const dist = centerDistanceSq(point, phys);
+    if (dist < nearestDist) {
+      nearestDist = dist;
+      nearest = display;
+    }
+  }
+  return nearest;
+}
+
+/**
+ * Convert a physical-pixel point (OS click hook) to DIP. Returns null when
+ * no display geometry is available — the caller should then fall back to a
+ * live cursor read rather than guessing.
+ */
+function physicalToDip(point, displays) {
+  if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) return null;
+  const display = displayForPhysicalPoint(point, displays);
+  if (!display) return null;
+  const phys = physicalBoundsOf(display);
+  const scale = display.scaleFactor || 1;
+  return {
+    x: display.bounds.x + (point.x - phys.x) / scale,
+    y: display.bounds.y + (point.y - phys.y) / scale,
+  };
+}
+
+/**
+ * Display whose DIP bounds contain the point, or the nearest one. Used to
+ * route a click to the capture stream of the monitor it landed on.
+ */
+function displayForDipPoint(point, displays) {
+  if (!point || !Array.isArray(displays) || !displays.length) return null;
+  let nearest = null;
+  let nearestDist = Infinity;
+  for (const display of displays) {
+    if (!display || !display.bounds) continue;
+    if (pointInBounds(point, display.bounds)) return display;
+    const dist = centerDistanceSq(point, display.bounds);
+    if (dist < nearestDist) {
+      nearestDist = dist;
+      nearest = display;
+    }
+  }
+  return nearest;
+}
+
+module.exports = {
+  physicalBoundsOf,
+  displayForPhysicalPoint,
+  displayForDipPoint,
+  physicalToDip,
+  pointInBounds,
+};
diff --git a/app/main.js b/app/main.js
index 2d211aa..c670a4e 100644
--- a/app/main.js
+++ b/app/main.js
@@ -98,6 +98,62 @@ function createWindow() {
         }
       }, 1500);
     }
+    // Dev-only self-test: exercise the full click-capture pipeline — resume
+    // session, wait for the frame recorder, inject OS-level clicks the way
+    // the watcher would, and verify one stored step per click.
+    if (process.env.STEPFORGE_CLICK_SELFTEST) {
+      setTimeout(async () => {
+        try {
+          const guide = store.createGuide({ title: 'click selftest' });
+          capture.startSession(guide.guideId, { intervalSec: 0 });
+          capture.togglePause(false);
+          mainWindow.hide();
+          // Arm the frame recorder directly: this host may lack the click
+          // watcher binary (xinput), which normally gates the recorder, but
+          // the recorder itself must still be testable end to end.
+          await capture.startClickFrameBackend();
+          // Let the stream backend (or the fallback loop) come up and buffer.
+          await new Promise((res) => setTimeout(res, 3000));
+          console.log('CLICK-SELFTEST source:', capture.state().clickFrameSource);
+          const clicks = [
+            { x: 200, y: 150 },
+            { x: 400, y: 300 },
+            { x: 600, y: 450 },
+          ];
+          for (const point of clicks) {
+            capture.onOsClick(Date.now(), point, 'button-1');
+            await new Promise((res) => setTimeout(res, 120)); // fast clicking
+          }
+          // Wait for the queue to drain (encodes can take seconds on WSLg).
+          await capture.clickQueue;
+          await new Promise((res) => setTimeout(res, 500));
+          const stepIds = store.getGuide(guide.guideId).stepsOrder;
+          const steps = store.listSteps(guide.guideId);
+          const markers = stepIds.map((id) => (steps.get(id).annotations || []).length);
+          console.log('CLICK-SELFTEST steps:', stepIds.length, 'of', clicks.length,
+            'markers:', JSON.stringify(markers));
+          // Marker accuracy: each oval's center (fractional) must match the
+          // injected click position relative to the display bounds.
+          const { bounds } = screen.getPrimaryDisplay();
+          stepIds.forEach((id, i) => {
+            const a = (steps.get(id).annotations || [])[0];
+            if (!a) return;
+            const center = { x: a.x + a.w / 2, y: a.y + a.h / 2 };
+            const expected = {
+              x: (clicks[i].x - bounds.x) / bounds.width,
+              y: (clicks[i].y - bounds.y) / bounds.height,
+            };
+            const offBy = Math.hypot(center.x - expected.x, center.y - expected.y);
+            console.log(`CLICK-SELFTEST marker ${i}: off by ${(offBy * 100).toFixed(2)}% of screen`);
+          });
+          capture.finishSession();
+        } catch (err) {
+          console.log('CLICK-SELFTEST ERROR', err.message);
+        } finally {
+          app.quit();
+        }
+      }, 1500);
+    }
     // Dev-only self-test: exercise the exact hotkey-session capture path
     // (hide window -> grab -> showInactive) several times, then exit.
     if (process.env.STEPFORGE_CAPTURE_SELFTEST) {
diff --git a/app/renderer/capture-worker.html b/app/renderer/capture-worker.html
new file mode 100644
index 0000000..f0cccd3
--- /dev/null
+++ b/app/renderer/capture-worker.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>StepForge capture worker</title>
+  <!-- Shared click↔frame selection logic; sets window.StepForgeClickFrames. -->
+  <script src="../click-frames.js" defer></script>
+  <script src="capture-worker.js" defer></script>
+</head>
+<body><!-- hidden window; frames live in JS, nothing renders here --></body>
+</html>
diff --git a/app/renderer/capture-worker.js b/app/renderer/capture-worker.js
new file mode 100644
index 0000000..64578e1
--- /dev/null
+++ b/app/renderer/capture-worker.js
@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * Capture worker: runs in a hidden renderer window and owns all continuous
+ * screen capture during a recording session.
+ *
+ * Per display it opens a desktop media stream (the desktopCapturer source id
+ * comes from the main process) and samples it on a fixed cadence into a
+ * timestamped ring buffer of ImageBitmaps. Sampling and PNG encoding happen
+ * entirely in this process, so the main-process event loop — which must stay
+ * responsive to deliver OS click events on time — never blocks on capture
+ * work. ImageBitmaps are GPU-backed and cheap to create from a <video>
+ * element, which is what lets the cadence be much tighter than the old
+ * 200ms main-process desktopCapturer loop.
+ *
+ * On a frame request the worker applies the shared strict selection rule
+ * (newest frame captured at or before the click; never one whose grab
+ * started after it), encodes that single frame to PNG, and ships the bytes
+ * to the main process.
+ */
+
+/* global StepForgeClickFrames, captureWorkerBridge */
+
+(() => {
+  const FALLBACK_SAMPLE_MS = 100;
+  // Tight cadence means more frames per second; keep enough of them to
+  // bridge any encode/IPC hiccup without hoarding GPU memory.
+  const FALLBACK_FRAME_LIMIT = 8;
+  const FALLBACK_RETENTION_MS = 2000;
+
+  const streams = new Map(); // displayId(string) -> stream state
+
+  function send(msg) {
+    try {
+      captureWorkerBridge.send(msg);
+      return true;
+    } catch (err) {
+      // Either the main process is gone or the payload didn't survive the
+      // bridge; log it — a silently dropped frame-response would otherwise
+      // look like a worker hang from the main process.
+      console.error('capture-worker send failed:', err && err.message, 'type:', msg && msg.type);
+      return false;
+    }
+  }
+
+  async function startStream(cmd) {
+    const key = String(cmd.displayId);
+    stopStream(key);
+    const display = cmd.display || {};
+    const scale = display.scaleFactor || 1;
+    const bounds = display.bounds || { width: 1280, height: 720 };
+    const physWidth = Math.round(bounds.width * scale);
+    const physHeight = Math.round(bounds.height * scale);
+    const state = {
+      displayId: cmd.displayId,
+      media: null,
+      video: null,
+      timer: null,
+      sampling: false,
+      ring: new StepForgeClickFrames.FrameRing({
+        limit: cmd.frameLimit || FALLBACK_FRAME_LIMIT,
+        retentionMs: cmd.retentionMs || FALLBACK_RETENTION_MS,
+        onEvict: (frame) => {
+          if (frame && frame.bitmap && frame.bitmap.close) frame.bitmap.close();
+        },
+      }),
+    };
+    streams.set(key, state);
+    try {
+      // The chromeMediaSource constraint set is Electron's documented bridge
+      // from a desktopCapturer source id to a live media stream.
+      state.media = await navigator.mediaDevices.getUserMedia({
+        audio: false,
+        video: {
+          mandatory: {
+            chromeMediaSource: 'desktop',
+            chromeMediaSourceId: cmd.sourceId,
+            minWidth: physWidth,
+            maxWidth: physWidth,
+            minHeight: physHeight,
+            maxHeight: physHeight,
+            maxFrameRate: 30,
+          },
+        },
+      });
+      const video = document.createElement('video');
+      video.muted = true;
+      video.srcObject = state.media;
+      state.video = video;
+      await video.play();
+      const sampleMs = cmd.sampleMs || FALLBACK_SAMPLE_MS;
+      state.timer = setInterval(() => sampleFrame(state), sampleMs);
+      // Buffer a frame immediately so a click right after "Start recording"
+      // already has something captured before it.
+      await sampleFrame(state);
+      send({ type: 'stream-ready', displayId: cmd.displayId });
+    } catch (err) {
+      stopStream(key);
+      send({ type: 'stream-error', displayId: cmd.displayId, reason: String(err && err.message || err) });
+    }
+  }
+
+  async function sampleFrame(state) {
+    if (state.sampling || !state.video || state.video.readyState < 2) return;
+    state.sampling = true;
+    // startedAt/capturedAt bracket the grab so strict selection can tell
+    // pre-click frames from post-click ones.
+    const startedAt = Date.now();
+    try {
+      const bitmap = await createImageBitmap(state.video);
+      state.ring.push({
+        mode: 'fullscreen',
+        bitmap,
+        width: bitmap.width,
+        height: bitmap.height,
+        startedAt,
+        capturedAt: Date.now(),
+      });
+    } catch {
+      // A failed sample only means a slightly older best frame.
+    } finally {
+      state.sampling = false;
+    }
+  }
+
+  function stopStream(key) {
+    const state = streams.get(key);
+    if (!state) return;
+    if (state.timer) clearInterval(state.timer);
+    if (state.media) {
+      for (const track of state.media.getTracks()) {
+        try { track.stop(); } catch { /* already stopped */ }
+      }
+    }
+    state.ring.clear();
+    streams.delete(key);
+  }
+
+  async function handleFrameRequest(cmd) {
+    const state = streams.get(String(cmd.displayId));
+    const reply = (extra) => send({ type: 'frame-response', requestId: cmd.requestId, ...extra });
+    if (!state) return reply({ ok: false, reason: 'no stream for display' });
+    // One last sample: if the compositor delivered a newer video frame since
+    // the previous tick, a sub-millisecond grab here can only improve (never
+    // worsen) the match — its startedAt is still checked against the click.
+    await sampleFrame(state);
+    const frame = StepForgeClickFrames.selectFrameForClick(state.ring.frames(), {
+      clickAt: cmd.clickAt,
+      mode: 'fullscreen',
+      strict: cmd.strict !== false,
+    });
+    if (!frame) return reply({ ok: false, reason: 'no frame at or before the click' });
+    try {
+      const canvas = new OffscreenCanvas(frame.width, frame.height);
+      canvas.getContext('2d').drawImage(frame.bitmap, 0, 0);
+      const blob = await canvas.convertToBlob({ type: 'image/png' });
+      const png = await blob.arrayBuffer();
+      return reply({
+        ok: true,
+        png: new Uint8Array(png),
+        width: frame.width,
+        height: frame.height,
+        startedAt: frame.startedAt,
+        capturedAt: frame.capturedAt,
+      });
+    } catch (err) {
+      return reply({ ok: false, reason: String(err && err.message || err) });
+    }
+  }
+
+  /** Health/diagnostic snapshot of every stream. */
+  function reportStats(cmd) {
+    const stats = {};
+    for (const [key, state] of streams) {
+      stats[key] = {
+        frames: state.ring.frames().length,
+        latestCapturedAt: state.ring.latest() ? state.ring.latest().capturedAt : null,
+        videoReadyState: state.video ? state.video.readyState : null,
+        videoSize: state.video ? `${state.video.videoWidth}x${state.video.videoHeight}` : null,
+        sampling: state.sampling,
+      };
+    }
+    send({ type: 'stats', requestId: cmd && cmd.requestId, stats });
+  }
+
+  captureWorkerBridge.onCommand((msg) => {
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.type === 'start-stream') startStream(msg);
+    else if (msg.type === 'stop-stream') stopStream(String(msg.displayId));
+    else if (msg.type === 'frame-request') {
+      // A request must always produce a response — an unanswered click
+      // counts toward backend unhealthiness in the main process.
+      handleFrameRequest(msg).catch((err) => {
+        console.error('capture-worker frame-request failed:', err && err.message);
+        send({ type: 'frame-response', requestId: msg.requestId, ok: false, reason: String(err && err.message || err) });
+      });
+    } else if (msg.type === 'stats-request') reportStats(msg);
+  });
+})();
diff --git a/app/stream-backend.js b/app/stream-backend.js
new file mode 100644
index 0000000..086348c
--- /dev/null
+++ b/app/stream-backend.js
@@ -0,0 +1,294 @@
+'use strict';
+
+const path = require('node:path');
+const { displayForDipPoint } = require('./coords');
+
+/**
+ * Off-main-process click-frame backend.
+ *
+ * The legacy design ran desktopCapturer.getSources() in a 200ms loop on the
+ * main process. That had two structural problems this backend removes:
+ *  - every grab (and the occasional PNG encode) blocked the main-process
+ *    event loop, which delayed delivery of OS click events — the very events
+ *    the loop existed to serve — by up to whole seconds under load;
+ *  - getSources() is a heavy thumbnail API, so the loop had to idle 200ms
+ *    between grabs, leaving clicks to be matched against frames that could
+ *    be hundreds of ms stale.
+ *
+ * Here, a hidden worker window opens a desktop media *stream* per display
+ * and samples it on a tight cadence into a timestamped ring buffer — all in
+ * the worker's renderer process. On click, the main process sends only a tiny
+ * IPC request carrying the hook-time click timestamp; the worker picks the
+ * newest frame captured at or before that instant (strict semantics from
+ * click-frames.js), PNG-encodes it off the main process, and ships the bytes
+ * back. The main process never grabs or encodes a frame while recording.
+ *
+ * Failure handling: the backend is an optimization, never a single point of
+ * failure. If streams don't come up (Wayland portals, WSLg quirks) start()
+ * reports false and the capture service falls back to the legacy loop; if
+ * frame requests start timing out mid-session, the backend declares itself
+ * unhealthy once and the service degrades the same way.
+ */
+
+const DEFAULT_SAMPLE_MS = 100;
+// Generous on purpose: the worker selects the frame the moment the request
+// arrives (that pins the click↔frame pairing), but PNG-encoding a 4K-class
+// frame can take seconds on software-rendered hosts (WSLg, VMs). A slow
+// reply is still the *correct* frame; only a worker that never answers
+// should count as unhealthy.
+const DEFAULT_FRAME_TIMEOUT_MS = 10_000;
+const DEFAULT_START_TIMEOUT_MS = 8000;
+// Consecutive frame-request timeouts before the backend declares itself
+// unhealthy and the capture service degrades to the in-process loop.
+const MAX_CONSECUTIVE_FAILURES = 2;
+
+class StreamCaptureBackend {
+  /**
+   * @param {object} opts
+   * @param {(onEvent: (msg) => void) => Promise<{send,destroy}>} opts.createHost
+   *   Factory for the worker transport (the hidden BrowserWindow in
+   *   production, a fake in tests).
+   * @param {(reason: string) => void} [opts.onUnhealthy]
+   */
+  constructor({ createHost, onUnhealthy = null, frameTimeoutMs = DEFAULT_FRAME_TIMEOUT_MS, startTimeoutMs = DEFAULT_START_TIMEOUT_MS } = {}) {
+    this.createHost = createHost;
+    this.onUnhealthy = onUnhealthy;
+    this.frameTimeoutMs = frameTimeoutMs;
+    this.startTimeoutMs = startTimeoutMs;
+    this.host = null;
+    this.active = false;
+    this.requests = new Map(); // requestId -> { resolve, timer }
+    this.streams = new Map(); // displayId(string) -> { display, ready }
+    this.nextRequestId = 1;
+    this.consecutiveFailures = 0;
+    this.startWaiters = [];
+  }
+
+  isActive() {
+    return this.active;
+  }
+
+  /**
+   * Spin up the worker and one stream per display that has a matching screen
+   * source. Resolves true when at least one stream is delivering frames.
+   */
+  async start({ displays = [], sources = [], sampleMs = DEFAULT_SAMPLE_MS, retentionMs = null, frameLimit = null } = {}) {
+    if (this.host) return this.active;
+    const pairs = pairDisplaysToSources(displays, sources);
+    if (!pairs.length) return false;
+    try {
+      this.host = await this.createHost((msg) => this.handleWorkerEvent(msg));
+    } catch {
+      this.host = null;
+      return false;
+    }
+    for (const { display, sourceId } of pairs) {
+      this.streams.set(String(display.id), { display, ready: false, failed: false });
+      this.hostSend({
+        type: 'start-stream',
+        displayId: display.id,
+        sourceId,
+        // The worker needs the physical pixel size to request a full-res
+        // stream; bounds stay in DIP for marker math back in the main process.
+        display: {
+          id: display.id,
+          bounds: display.bounds,
+          scaleFactor: display.scaleFactor || 1,
+        },
+        sampleMs,
+        retentionMs,
+        frameLimit,
+      });
+    }
+    const anyReady = await this.waitForStreams();
+    this.active = anyReady;
+    if (!anyReady) this.stop();
+    return this.active;
+  }
+
+  /** Resolves true as soon as one stream reports ready, false on timeout/all-failed. */
+  waitForStreams() {
+    return new Promise((resolve) => {
+      const finish = (ok) => {
+        clearTimeout(timer);
+        this.startWaiters = this.startWaiters.filter((w) => w !== check);
+        resolve(ok);
+      };
+      const check = () => {
+        const states = [...this.streams.values()];
+        if (states.some((s) => s.ready)) return finish(true);
+        if (states.length && states.every((s) => s.failed)) return finish(false);
+        return null;
+      };
+      const timer = setTimeout(() => finish(false), this.startTimeoutMs);
+      this.startWaiters.push(check);
+      check();
+    });
+  }
+
+  hostSend(msg) {
+    if (!this.host) return;
+    try {
+      this.host.send(msg);
+    } catch {
+      // A dead host surfaces as request timeouts → unhealthy → degrade.
+    }
+  }
+
+  handleWorkerEvent(msg) {
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.type === 'stream-ready' || msg.type === 'stream-error') {
+      const stream = this.streams.get(String(msg.displayId));
+      if (stream) {
+        stream.ready = msg.type === 'stream-ready';
+        stream.failed = msg.type === 'stream-error';
+      }
+      for (const check of [...this.startWaiters]) check();
+      return;
+    }
+    if (msg.type === 'frame-response') {
+      const pending = this.requests.get(msg.requestId);
+      if (!pending) return; // late reply after timeout — already handled
+      this.requests.delete(msg.requestId);
+      clearTimeout(pending.timer);
+      // Any answer — even "no qualifying frame" — proves the worker is alive.
+      this.consecutiveFailures = 0;
+      if (!msg.ok || !msg.png) {
+        pending.resolve(null);
+        return;
+      }
+      pending.resolve({
+        mode: 'fullscreen',
+        png: Buffer.from(msg.png),
+        size: { width: msg.width, height: msg.height },
+        display: pending.display,
+        startedAt: msg.startedAt,
+        capturedAt: msg.capturedAt,
+        source: 'stream',
+      });
+    }
+  }
+
+  /**
+   * Frame for one click, selected in the worker under the given strictness.
+   * Resolves null when no frame qualifies (caller falls back) — and also on
+   * timeout, which additionally counts toward unhealthiness.
+   */
+  frameForClick({ clickPos = null, clickAt = Date.now(), strict = true } = {}) {
+    if (!this.active || !this.host) return Promise.resolve(null);
+    const displays = [...this.streams.values()].filter((s) => s.ready).map((s) => s.display);
+    const display = clickPos ? displayForDipPoint(clickPos, displays) : (displays[0] || null);
+    if (!display) return Promise.resolve(null);
+    const requestId = this.nextRequestId++;
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.requests.delete(requestId);
+        resolve(null);
+        this.noteFailure();
+      }, this.frameTimeoutMs);
+      this.requests.set(requestId, { resolve, timer, display });
+      this.hostSend({
+        type: 'frame-request',
+        requestId,
+        displayId: display.id,
+        clickAt,
+        strict,
+      });
+    });
+  }
+
+  noteFailure() {
+    this.consecutiveFailures += 1;
+    if (this.consecutiveFailures < MAX_CONSECUTIVE_FAILURES) return;
+    const notify = this.onUnhealthy;
+    this.stop();
+    if (notify) notify('frame requests timing out');
+  }
+
+  stop() {
+    this.active = false;
+    for (const [, pending] of this.requests) {
+      clearTimeout(pending.timer);
+      pending.resolve(null);
+    }
+    this.requests.clear();
+    this.streams.clear();
+    for (const check of [...this.startWaiters]) check();
+    this.startWaiters = [];
+    if (this.host) {
+      try { this.host.destroy(); } catch { /* already gone */ }
+      this.host = null;
+    }
+  }
+}
+
+/** Match each display to its desktopCapturer screen source by display_id. */
+function pairDisplaysToSources(displays, sources) {
+  const screens = (sources || []).filter((s) => s && typeof s.id === 'string' && s.id.startsWith('screen:'));
+  const pairs = [];
+  const used = new Set();
+  for (const display of displays || []) {
+    let source = screens.find((s) => !used.has(s.id) && String(s.display_id) === String(display.id));
+    if (!source && displays.length === 1 && screens.length === 1) {
+      // Single display, single source: some platforms leave display_id empty.
+      source = screens[0];
+    }
+    if (!source) continue;
+    used.add(source.id);
+    pairs.push({ display, sourceId: source.id });
+  }
+  return pairs;
+}
+
+/**
+ * Production worker host: a hidden BrowserWindow running the capture-worker
+ * page. Lazy-required Electron so this module stays loadable under node for
+ * unit tests.
+ */
+async function createElectronHost(onEvent) {
+  // eslint-disable-next-line global-require
+  const { BrowserWindow, ipcMain } = require('electron');
+  const win = new BrowserWindow({
+    show: false,
+    width: 320,
+    height: 240,
+    skipTaskbar: true,
+    webPreferences: {
+      preload: path.join(__dirname, 'capture-worker-preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      // The worker must keep sampling while hidden — throttling a hidden
+      // window is exactly the wrong default for a frame recorder.
+      backgroundThrottling: false,
+    },
+  });
+  const listener = (event, msg) => {
+    if (event.sender === win.webContents) onEvent(msg);
+  };
+  ipcMain.on('capture-worker:event', listener);
+  try {
+    await win.loadFile(path.join(__dirname, 'renderer', 'capture-worker.html'));
+  } catch (err) {
+    ipcMain.removeListener('capture-worker:event', listener);
+    if (!win.isDestroyed()) win.destroy();
+    throw err;
+  }
+  return {
+    send(msg) {
+      if (!win.isDestroyed()) win.webContents.send('capture-worker:command', msg);
+    },
+    destroy() {
+      ipcMain.removeListener('capture-worker:event', listener);
+      if (!win.isDestroyed()) win.destroy();
+    },
+  };
+}
+
+module.exports = {
+  StreamCaptureBackend,
+  createElectronHost,
+  pairDisplaysToSources,
+  DEFAULT_SAMPLE_MS,
+  DEFAULT_FRAME_TIMEOUT_MS,
+  MAX_CONSECUTIVE_FAILURES,
+};
diff --git a/core/settings.js b/core/settings.js
index 82ea8f2..f6b5daa 100644
--- a/core/settings.js
+++ b/core/settings.js
@@ -19,6 +19,15 @@ const DEFAULT_SETTINGS = {
     captureOutsideClicks: true,
     confirmSimpleCapture: false,
     autoIntervalSec: 5, // session fallback when click capture is unavailable
+    // Strict click timing: a step never uses a frame whose grab started
+    // after the click. Turn off only if captures are too slow to keep a
+    // pre-click frame buffered (re-enables the legacy slack heuristics).
+    strictClickFrames: true,
+    // Off-main-process frame recorder (hidden worker window sampling a
+    // desktop media stream). Falls back to the in-process loop when false
+    // or when streams cannot start on this desktop.
+    streamCapture: true,
+    frameSampleMs: 100, // stream backend sampling cadence
   },
   editor: {
     focusedViewDefaultForNewSteps: false,
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e3054d8..ff9e7a2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -102,6 +102,41 @@ IPC API (`stepforge.*`), and `app/main.js` routes calls into `core/`. Screen
 capture uses Electron's `desktopCapturer` (full screen, window) and an
 overlay window for region selection; hotkeys use `globalShortcut`.
 
+## Click-Capture Pipeline
+
+Workflow recording must behave like one click → one step, with the
+screenshot showing the screen *at* the click and the marker on the exact
+click position. Three pieces make that hold:
+
+1. **OS click events** (`app/capture.js`): a low-level mouse hook on Windows
+   (`CLICK x y button unixMs` lines), an `xinput test-xi2 --root` watcher on
+   X11. The Linux parser carries event-time `root:` coordinates and merges
+   raw/regular twin blocks structurally — there is no time-based debounce
+   that could drop fast clicks, only suppression of identical duplicate
+   deliveries. Physical coordinates convert to DIP via
+   `screen.screenToDipPoint` on Windows or display-geometry math in
+   `app/coords.js` elsewhere (multi-monitor and scale-factor aware).
+
+2. **Frame recorders**: while recording, a hidden worker window
+   (`app/stream-backend.js` + `app/renderer/capture-worker.js`) samples a
+   desktop media stream per display into a timestamped ring buffer —
+   entirely off the main process, so click delivery is never delayed by
+   capture work, and PNG encoding happens in the worker. If streams can't
+   start (portal-less Wayland), or the worker stops answering, the service
+   degrades to the legacy in-process `desktopCapturer` loop.
+
+3. **Click ↔ frame pairing** (`app/click-frames.js`, shared by the main
+   process, the worker, and tests): each click is paired *at event time*
+   with the newest frame captured at or before its hook timestamp. In strict
+   mode (`capture.strictClickFrames`, default on) a frame whose grab started
+   after the click is never used — when nothing qualifies, the service takes
+   an explicit fresh shot instead of passing a post-click frame off as the
+   click-time screen. Storing is serialized per click; pairing is not, so
+   slow encodes never skew later clicks.
+
+`STEPFORGE_CLICK_SELFTEST=1 npm start` exercises the whole pipeline in a
+real Electron session and reports steps-per-click and marker offsets.
+
 ## Security Rules
 
 - Zero network code paths: no sockets, no telemetry, no update or license
diff --git a/tests/unit/capture.test.js b/tests/unit/capture.test.js
index 8c0524d..975c8f8 100644
--- a/tests/unit/capture.test.js
+++ b/tests/unit/capture.test.js
@@ -5,17 +5,20 @@ const assert = require('node:assert/strict');
 
 const CaptureService = require('../../app/capture');
 
-function makeService() {
+function makeService({ settings: settingsOverrides, screenApi } = {}) {
   const store = {
     addStep() {
       throw new Error('not used in this test');
     },
   };
+  const settingsData = {
+    'capture.mode': 'fullscreen',
+    'capture.delayMs': 0,
+    ...settingsOverrides,
+  };
   const settings = {
     get(key) {
-      if (key === 'capture.mode') return 'fullscreen';
-      if (key === 'capture.delayMs') return 0;
-      return null;
+      return key in settingsData ? settingsData[key] : null;
     },
   };
   return new CaptureService({
@@ -23,9 +26,31 @@ function makeService() {
     settings,
     getWindow: () => null,
     notify: () => {},
+    screenApi: screenApi || {
+      getCursorScreenPoint: () => ({ x: 0, y: 0 }),
+      getAllDisplays: () => [],
+    },
   });
 }
 
+// The raw/regular twin window plus margin: how long a test must wait for a
+// held Linux raw press to fire when no coordinate twin arrives.
+const TWIN_FLUSH_MS = 60;
+const settle = (ms = TWIN_FLUSH_MS) => new Promise((r) => setTimeout(r, ms));
+
+function makeFrame(name, ageMs = 0, overrides = {}) {
+  return {
+    mode: overrides.mode || 'fullscreen',
+    png: Buffer.from(name),
+    size: overrides.size || { width: 100, height: 100 },
+    display: overrides.display || { bounds: { x: 0, y: 0, width: 100, height: 100 } },
+    cursor: overrides.cursor || { x: 50, y: 50 },
+    capturedAt: Date.now() - ageMs,
+  };
+}
+
+// ---- fresh-shot fallback path ----------------------------------------------
+
 test('click-triggered session capture uses the low-latency hide pause', async () => {
   const service = makeService();
   service.session = { guideId: 'guide-1', paused: false, count: 0, intervalSec: 0 };
@@ -50,16 +75,7 @@ test('click-triggered session capture uses the low-latency hide pause', async ()
   });
 });
 
-function makeFrame(name, ageMs = 0, overrides = {}) {
-  return {
-    mode: overrides.mode || 'fullscreen',
-    png: Buffer.from(name),
-    size: overrides.size || { width: 100, height: 100 },
-    display: overrides.display || { bounds: { x: 0, y: 0, width: 100, height: 100 } },
-    cursor: overrides.cursor || { x: 50, y: 50 },
-    capturedAt: Date.now() - ageMs,
-  };
-}
+// ---- Linux watcher parsing ---------------------------------------------------
 
 test('rapid click watcher bursts are parsed one click at a time', () => {
   const service = makeService();
@@ -78,7 +94,7 @@ test('rapid click watcher bursts are parsed one click at a time', () => {
   assert.equal(clicks, 2);
 });
 
-test('button presses fire on the detail line; scroll-wheel ticks are ignored', () => {
+test('raw button presses fire; scroll-wheel ticks (buttons 4-7) are ignored', async () => {
   const service = makeService();
   let clicks = 0;
   service.onOsClick = () => {
@@ -101,9 +117,78 @@ test('button presses fire on the detail line; scroll-wheel ticks are ignored', (
     '    detail: 3',
   ].join('\n'), 'linux');
 
+  await settle(); // raw presses hold briefly for a coordinate twin
   assert.equal(clicks, 2, 'buttons 4-7 are scroll ticks, not clicks');
 });
 
+test('regular ButtonPress blocks carry their root coordinates into onOsClick', () => {
+  // The event-time root position is what keeps the marker on the real click
+  // even when the pointer keeps moving after the press — a live cursor read
+  // at parse time would drift.
+  const service = makeService();
+  const seen = [];
+  service.onOsClick = (at, osPoint, button) => {
+    seen.push({ osPoint, button });
+  };
+
+  service.processClickWatcherData([
+    'EVENT type 4 (ButtonPress)',
+    '    device: 11 (10)',
+    '    detail: 1',
+    '    flags:',
+    '    root: 644.52/343.55',
+    '    event: 644.52/343.55',
+  ].join('\n'), 'linux');
+
+  assert.deepEqual(seen, [{ osPoint: { x: 645, y: 344 }, button: 'button-1' }]);
+});
+
+test('a raw press and its regular twin merge into a single click with coordinates', async () => {
+  // One physical press can be delivered as both a RawButtonPress and a
+  // ButtonPress block. That duplication is resolved structurally — never by
+  // a time debounce that could swallow real fast clicks.
+  const service = makeService();
+  const seen = [];
+  service.onOsClick = (at, osPoint, button) => {
+    seen.push({ osPoint, button });
+  };
+
+  service.processClickWatcherData([
+    'EVENT type 15 (RawButtonPress)',
+    '    device: 11 (11)',
+    '    detail: 1',
+    '    valuators:',
+    'EVENT type 4 (ButtonPress)',
+    '    device: 11 (10)',
+    '    detail: 1',
+    '    root: 100.00/200.00',
+  ].join('\n'), 'linux');
+
+  await settle();
+  assert.deepEqual(seen, [{ osPoint: { x: 100, y: 200 }, button: 'button-1' }],
+    'exactly one click, carrying the regular twin\'s coordinates');
+});
+
+test('two genuine fast presses of the same button both fire', async () => {
+  const service = makeService();
+  const seen = [];
+  service.onOsClick = (at, osPoint, button) => {
+    seen.push({ osPoint, button });
+  };
+
+  service.processClickWatcherData([
+    'EVENT type 4 (ButtonPress)',
+    '    detail: 1',
+    '    root: 10.00/10.00',
+    'EVENT type 4 (ButtonPress)',
+    '    detail: 1',
+    '    root: 12.00/11.00',
+  ].join('\n'), 'linux');
+
+  await settle();
+  assert.equal(seen.length, 2, 'fast clicking must never be dropped by the parser');
+});
+
 test('motion events with detail lines do not fire clicks', () => {
   const service = makeService();
   let clicks = 0;
@@ -121,7 +206,7 @@ test('motion events with detail lines do not fire clicks', () => {
   assert.equal(clicks, 0);
 });
 
-test('event lines split across stdout chunks are reassembled before parsing', () => {
+test('event lines split across stdout chunks are reassembled before parsing', async () => {
   const service = makeService();
   let clicks = 0;
   service.onOsClick = () => {
@@ -132,9 +217,12 @@ test('event lines split across stdout chunks are reassembled before parsing', ()
   assert.equal(clicks, 0, 'a partial line must not be parsed yet');
   service.ingestClickWatcherChunk('onPress)\n    detail: 1\n', 'linux');
 
+  await settle();
   assert.equal(clicks, 1);
 });
 
+// ---- click queue --------------------------------------------------------------
+
 test('clicks queue behind an in-progress capture instead of being dropped', async () => {
   const service = makeService();
   const order = [];
@@ -156,6 +244,57 @@ test('clicks queue behind an in-progress capture instead of being dropped', asyn
     'the second click must run after the first, not be dropped');
 });
 
+test('fast clicks are paired with their frames at event time, not behind the store queue', async () => {
+  // With a slow PNG encode or store, the click queue can run seconds late.
+  // The frame request must go out at click time anyway, or the second
+  // click's frame would be selected (and possibly evicted) far too late.
+  const service = makeService();
+  service.session = { guideId: 'guide-eager', paused: false, count: 0, intervalSec: 0 };
+  service.userIsInApp = () => false;
+  const requested = [];
+  let releaseFirst;
+  const firstGate = new Promise((r) => { releaseFirst = r; });
+  service.frameForClick = (clickPos, clickAt) => {
+    requested.push(clickAt);
+    const frame = makeFrame(`frame-${clickAt}`);
+    return clickAt === 1000 ? firstGate.then(() => frame) : Promise.resolve(frame);
+  };
+  let stored = 0;
+  service.storeFrameAsStep = () => {
+    stored += 1;
+    return { ok: true, step: { stepId: `step-${stored}` } };
+  };
+
+  service.enqueueClickCapture({ x: 1, y: 1 }, 1000, 'left');
+  const queue = service.enqueueClickCapture({ x: 2, y: 2 }, 1040, 'left');
+
+  assert.deepEqual(requested, [1000, 1040],
+    'both frames must be requested immediately, while the first store is still pending');
+  releaseFirst();
+  await queue;
+  assert.equal(stored, 2);
+  assert.equal(service.session.count, 2);
+});
+
+test('queued click captures preserve the original event time and button', async () => {
+  const service = makeService();
+  const seen = [];
+  service.sessionCapture = async (trigger, clickPos, clickMeta) => {
+    seen.push({ trigger, clickPos, clickMeta });
+    return { ok: true };
+  };
+
+  await service.enqueueClickCapture({ x: 7, y: 8 }, 1770000000456, 'left');
+
+  assert.deepEqual(seen, [{
+    trigger: 'click',
+    clickPos: { x: 7, y: 8 },
+    clickMeta: { at: 1770000000456, button: 'left' },
+  }]);
+});
+
+// ---- Windows watcher parsing ---------------------------------------------------
+
 test('windows click watcher output is counted line by line', () => {
   const service = makeService();
   let clicks = 0;
@@ -197,6 +336,105 @@ test('windows hook click lines carry button and event timestamp', () => {
   }]);
 });
 
+// ---- click dedupe (source-aware, not a debounce) -------------------------------
+
+test('fast same-button hook clicks are all captured — there is no time debounce', () => {
+  const service = makeService();
+  service.session = { guideId: 'guide-burst', paused: false, count: 0, intervalSec: 0 };
+  const seen = [];
+  service.enqueueClickCapture = (clickPos, at) => {
+    seen.push(at);
+  };
+
+  // A 5-click burst 15ms apart — faster than the old 40ms debounce allowed.
+  const base = 1770000000000;
+  for (let i = 0; i < 5; i++) {
+    service.onOsClick(base + i * 15, { x: 100 + i, y: 200 }, 'left');
+  }
+
+  assert.equal(seen.length, 5, 'every distinct hook event is one click');
+});
+
+test('duplicate delivery of one physical press is suppressed', () => {
+  const service = makeService();
+  service.session = { guideId: 'guide-dupe', paused: false, count: 0, intervalSec: 0 };
+  const seen = [];
+  service.enqueueClickCapture = (clickPos, at) => {
+    seen.push(at);
+  };
+
+  // Same button, same coordinates, 3ms apart: the same event delivered twice.
+  service.onOsClick(1770000000000, { x: 50, y: 60 }, 'left');
+  service.onOsClick(1770000000003, { x: 50, y: 60 }, 'left');
+  // Different coordinates inside the same window: a real second click.
+  service.onOsClick(1770000000006, { x: 80, y: 60 }, 'left');
+  // Different button inside the same window: also real.
+  service.onOsClick(1770000000007, { x: 80, y: 60 }, 'right');
+
+  assert.deepEqual(seen, [1770000000000, 1770000000006, 1770000000007]);
+});
+
+// ---- coordinate conversion ------------------------------------------------------
+
+test('hook coordinates are converted physical → DIP via screenToDipPoint when available', () => {
+  const service = makeService({
+    screenApi: {
+      screenToDipPoint: (p) => ({ x: p.x / 2, y: p.y / 2 }),
+      getCursorScreenPoint: () => { throw new Error('must not fall back to a cursor read'); },
+    },
+  });
+  service.session = { guideId: 'guide-dip', paused: false, count: 0, intervalSec: 0 };
+  const seen = [];
+  service.enqueueClickCapture = (clickPos) => {
+    seen.push(clickPos);
+  };
+
+  service.onOsClick(1770000000000, { x: 1280, y: 640 }, 'left');
+
+  assert.deepEqual(seen, [{ x: 640, y: 320 }]);
+});
+
+test('without screenToDipPoint, coordinates convert via display geometry (Linux/X11)', () => {
+  const service = makeService({
+    screenApi: {
+      getAllDisplays: () => [
+        { id: 1, scaleFactor: 2, bounds: { x: 0, y: 0, width: 1440, height: 900 } },
+      ],
+      getCursorScreenPoint: () => { throw new Error('must not fall back to a cursor read'); },
+    },
+  });
+  service.session = { guideId: 'guide-x11', paused: false, count: 0, intervalSec: 0 };
+  const seen = [];
+  service.enqueueClickCapture = (clickPos) => {
+    seen.push(clickPos);
+  };
+
+  service.onOsClick(1770000000000, { x: 1500, y: 900 }, 'button-1');
+
+  assert.deepEqual(seen, [{ x: 750, y: 450 }],
+    'a physical click on a 2x display must land at the halved DIP point');
+});
+
+test('clicks without event coordinates fall back to a live cursor read', () => {
+  const service = makeService({
+    screenApi: {
+      getCursorScreenPoint: () => ({ x: 11, y: 22 }),
+      getAllDisplays: () => [],
+    },
+  });
+  service.session = { guideId: 'guide-cursor', paused: false, count: 0, intervalSec: 0 };
+  const seen = [];
+  service.enqueueClickCapture = (clickPos) => {
+    seen.push(clickPos);
+  };
+
+  service.onOsClick(1770000000000, null, 'mouse');
+
+  assert.deepEqual(seen, [{ x: 11, y: 22 }]);
+});
+
+// ---- watcher loss -----------------------------------------------------------------
+
 test('losing the click watcher mid-session falls back to interval capture', () => {
   const service = makeService();
   service.settings.get = (key) => (key === 'capture.autoIntervalSec' ? 3 : null);
@@ -217,6 +455,8 @@ test('losing the click watcher mid-session falls back to interval capture', () =
   }
 });
 
+// ---- strict frame selection -----------------------------------------------------
+
 test('a click is served instantly from the freshly buffered frame', async () => {
   const service = makeService();
   service.session = { guideId: 'guide-2', paused: false, count: 0, intervalSec: 0 };
@@ -264,36 +504,25 @@ test('click capture uses the newest frame completed before the click time', asyn
   assert.deepEqual(added, ['before-click']);
 });
 
-test('queued click captures preserve the original event time and button', async () => {
-  const service = makeService();
-  const seen = [];
-  service.sessionCapture = async (trigger, clickPos, clickMeta) => {
-    seen.push({ trigger, clickPos, clickMeta });
-    return { ok: true };
-  };
-
-  await service.enqueueClickCapture({ x: 7, y: 8 }, 1770000000456, 'left');
-
-  assert.deepEqual(seen, [{
-    trigger: 'click',
-    clickPos: { x: 7, y: 8 },
-    clickMeta: { at: 1770000000456, button: 'left' },
-  }]);
-});
-
 test('a buffered frame from a different display is ignored for click capture', async () => {
   const service = makeService();
+  const clickAt = Date.now();
   service.session = { guideId: 'guide-display', paused: false, count: 0, intervalSec: 0 };
   service.frameLoopRunning = true;
   service.frameLoopInFlight = true;
+  service.frameLoopGrabStartedAt = clickAt - 10; // the in-flight grab predates the click
   service.latestFrame = makeFrame('wrong-display', 0, {
     display: { bounds: { x: 0, y: 0, width: 100, height: 100 } },
   });
 
-  service.nextFrame = async () => makeFrame('right-display', 0, {
-    display: { bounds: { x: 100, y: 0, width: 100, height: 100 } },
-    cursor: { x: 150, y: 10 },
-  });
+  service.nextFrame = async () => {
+    const f = makeFrame('right-display', 0, {
+      display: { bounds: { x: 100, y: 0, width: 100, height: 100 } },
+      cursor: { x: 150, y: 10 },
+    });
+    f.startedAt = clickAt - 10;
+    return f;
+  };
   service.shoot = async () => {
     throw new Error('click capture should not fall back when a matching frame arrives');
   };
@@ -304,7 +533,7 @@ test('a buffered frame from a different display is ignored for click capture', a
     return { stepId: 'step-display' };
   };
 
-  const result = await service.sessionCapture('click', { x: 150, y: 10 });
+  const result = await service.sessionCapture('click', { x: 150, y: 10 }, { at: clickAt });
 
   assert.equal(result.ok, true);
   assert.deepEqual(added, ['right-display']);
@@ -328,12 +557,35 @@ test('a stale buffered frame is not reused — the click falls back to a fresh s
   assert.equal(shootCalled, true, 'a stale buffered frame must not be reused');
 });
 
-test('an idle click capture waits for the imminent loop frame instead of racing it', async () => {
-  // Grabs take seconds while the idle gap is ~200ms, so the loop's next
-  // frame both starts sooner and avoids stalling the loop the way a
-  // competing one-off shot would.
+test('strict mode: a frame whose grab started after the click is rejected', async () => {
+  // This replaces the old "idle click waits for the imminent loop frame"
+  // behavior: a grab that begins after the click can already show the
+  // click's effects, so strict mode takes the explicit fresh-shot fallback
+  // instead of passing it off as the click-time screen.
   const service = makeService();
-  service.session = { guideId: 'guide-idle', paused: false, count: 0, intervalSec: 0 };
+  service.session = { guideId: 'guide-strict', paused: false, count: 0, intervalSec: 0 };
+  service.frameLoopRunning = true;
+  service.frameLoopInFlight = false; // nothing in flight at click time
+
+  const clickAt = Date.now();
+  service.nextFrame = async () => {
+    throw new Error('strict idle clicks must not wait for a post-click frame');
+  };
+  let shootCalled = false;
+  service.shoot = async () => {
+    shootCalled = true;
+    return { ok: true, step: { stepId: 'fresh-step' } };
+  };
+
+  const result = await service.sessionCapture('click', { x: 1, y: 1 }, { at: clickAt });
+
+  assert.equal(result.ok, true);
+  assert.equal(shootCalled, true);
+});
+
+test('balanced mode keeps the legacy slack: an imminent post-click frame is accepted', async () => {
+  const service = makeService({ settings: { 'capture.strictClickFrames': false } });
+  service.session = { guideId: 'guide-balanced', paused: false, count: 0, intervalSec: 0 };
   service.frameLoopRunning = true;
   service.frameLoopInFlight = false;
 
@@ -345,12 +597,12 @@ test('an idle click capture waits for the imminent loop frame instead of racing
     return f;
   };
   service.shoot = async () => {
-    throw new Error('idle clicks must wait for the loop frame, not take a fresh shot');
+    throw new Error('balanced idle clicks wait for the loop frame');
   };
   const added = [];
   service.store.addStep = (guideId, fields, png) => {
     added.push(png.toString());
-    return { stepId: 'idle-step' };
+    return { stepId: 'balanced-step' };
   };
 
   const result = await service.sessionCapture('click', { x: 1, y: 1 }, { at: clickAt });
@@ -359,8 +611,8 @@ test('an idle click capture waits for the imminent loop frame instead of racing
   assert.deepEqual(added, ['next-loop-frame']);
 });
 
-test('a loop frame started too long after the click falls back to a fresh shot', async () => {
-  const service = makeService();
+test('balanced mode: a loop frame started too long after the click still falls back', async () => {
+  const service = makeService({ settings: { 'capture.strictClickFrames': false } });
   service.session = { guideId: 'guide-late', paused: false, count: 0, intervalSec: 0 };
   service.frameLoopRunning = true;
   service.frameLoopInFlight = false;
@@ -384,7 +636,7 @@ test('a loop frame started too long after the click falls back to a fresh shot',
   assert.equal(shootCalled, true, 'late frames must not be passed off as the click-time screen');
 });
 
-test('clicks during an in-flight grab wait for the frame instead of being dropped', async () => {
+test('clicks during an in-flight pre-click grab wait for the frame instead of being dropped', async () => {
   const service = makeService();
   service.session = { guideId: 'guide-fast', paused: false, count: 0, intervalSec: 0 };
   service.frameLoopRunning = true; // a grab is in flight, no frame buffered yet
@@ -395,10 +647,16 @@ test('clicks during an in-flight grab wait for the frame instead of being droppe
     throw new Error('waiting clicks must use the loop frame, not a competing shot');
   };
   const added = [];
+  const frames = [];
   service.store.addStep = (guideId, fields, png) => {
     added.push(png.toString());
     return { stepId: `step-${added.length}` };
   };
+  const origStore = service.storeFrameAsStep.bind(service);
+  service.storeFrameAsStep = (guideId, mode, frame, clickPos) => {
+    frames.push(frame);
+    return origStore(guideId, mode, frame, clickPos);
+  };
 
   // Two rapid clicks land before the grab completes.
   const first = service.sessionCapture('click', { x: 1, y: 1 }, { at: clickAt });
@@ -410,23 +668,122 @@ test('clicks during an in-flight grab wait for the frame instead of being droppe
 
   assert.equal(r1.ok, true);
   assert.equal(r2.ok, true);
-  assert.deepEqual(added, ['loop-frame', 'loop-frame'],
-    'both clicks must become steps from the frame that was in flight');
+  assert.equal(added.length, 2, 'one step per click — fast clicks are never dropped');
   assert.equal(service.session.count, 2);
+  for (const frame of frames) {
+    assert.ok(frame.startedAt <= clickAt,
+      'strict mode: no step may use a frame whose grab started after its click');
+  }
 });
 
-test('pausing stops the frame loop and discards the buffered frame', () => {
+// ---- stream backend integration ---------------------------------------------------
+
+test('click frames come from the stream backend when it is active', async () => {
+  const service = makeService();
+  const clickAt = Date.now();
+  service.session = { guideId: 'guide-stream', paused: false, count: 0, intervalSec: 0 };
+  const requests = [];
+  service.streamBackend = {
+    isActive: () => true,
+    frameForClick: async (req) => {
+      requests.push(req);
+      return {
+        mode: 'fullscreen',
+        png: Buffer.from('stream-frame'),
+        size: { width: 200, height: 100 },
+        display: { bounds: { x: 0, y: 0, width: 100, height: 100 } },
+        startedAt: clickAt - 50,
+        capturedAt: clickAt - 40,
+        source: 'stream',
+      };
+    },
+    stop: () => {},
+  };
+  service.shoot = async () => {
+    throw new Error('the stream frame must be used, not a fresh shot');
+  };
+  const added = [];
+  service.store.addStep = (guideId, fields, png) => {
+    added.push(png.toString());
+    return { stepId: 'stream-step' };
+  };
+
+  const result = await service.sessionCapture('click', { x: 10, y: 10 }, { at: clickAt });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(added, ['stream-frame']);
+  assert.deepEqual(requests, [{ clickPos: { x: 10, y: 10 }, clickAt, strict: true }],
+    'the worker receives the hook-time click timestamp and strictness');
+});
+
+test('a stream backend with no qualifying frame falls through to the fresh-shot path', async () => {
+  const service = makeService();
+  service.session = { guideId: 'guide-stream-miss', paused: false, count: 0, intervalSec: 0 };
+  service.streamBackend = {
+    isActive: () => true,
+    frameForClick: async () => null,
+    stop: () => {},
+  };
+  let shootCalled = false;
+  service.shoot = async () => {
+    shootCalled = true;
+    return { ok: true, step: { stepId: 'fresh-step' } };
+  };
+
+  const result = await service.sessionCapture('click', { x: 1, y: 1 });
+
+  assert.equal(result.ok, true);
+  assert.equal(shootCalled, true);
+});
+
+test('pausing stops the frame loop, drops buffered frames, and stops the stream backend', () => {
   const service = makeService();
   service.session = { guideId: 'guide-pause', paused: false, count: 0, intervalSec: 0 };
   service.frameLoopRunning = true;
   service.latestFrame = makeFrame('pre-pause');
+  let backendStopped = false;
+  service.streamBackend = { isActive: () => true, stop: () => { backendStopped = true; } };
 
   service.togglePause(true);
 
   assert.equal(service.frameLoopRunning, false);
   assert.equal(service.latestFrame, null, 'a resume must never serve a pre-pause frame');
+  assert.equal(backendStopped, true);
+  assert.equal(service.streamBackend, null);
 });
 
+test('an unhealthy stream backend degrades to the in-process frame loop', () => {
+  const service = makeService();
+  service.session = { guideId: 'guide-degrade', paused: false, count: 0, intervalSec: 0 };
+  service.streamBackend = { isActive: () => true, stop: () => {} };
+  let loopStarted = false;
+  service.startFrameLoop = () => { loopStarted = true; };
+  const states = [];
+  service.notify = (channel) => states.push(channel);
+
+  service.degradeToFrameLoop();
+
+  assert.equal(service.streamBackend, null);
+  assert.equal(loopStarted, true, 'capture must not silently stop when the worker dies');
+  assert.ok(states.includes('capture:state'));
+});
+
+test('session state reports which frame recorder is serving clicks', () => {
+  const service = makeService();
+  service.session = { guideId: 'guide-state', paused: false, count: 0, intervalSec: 0 };
+
+  assert.equal(service.state().clickFrameSource, 'idle');
+  assert.equal(service.state().strictClickFrames, true);
+  service.frameLoopRunning = true;
+  assert.equal(service.state().clickFrameSource, 'loop');
+  service.streamBackend = { isActive: () => true, stop: () => {} };
+  assert.equal(service.state().clickFrameSource, 'stream');
+  service.streamBackend = null;
+  service.frameLoopRunning = false;
+});
+
+// ---- marker + session lifecycle ------------------------------------------------
+
 test('click capture marks the click-time cursor position', async () => {
   const service = makeService();
   service.settings.get = (key) => {
diff --git a/tests/unit/click-frames.test.js b/tests/unit/click-frames.test.js
new file mode 100644
index 0000000..d4623e5
--- /dev/null
+++ b/tests/unit/click-frames.test.js
@@ -0,0 +1,134 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  FrameRing,
+  frameUsableForClick,
+  selectFrameForClick,
+} = require('../../app/click-frames');
+
+function frame(name, { startedAt, capturedAt, mode = 'fullscreen', display = null } = {}) {
+  return { name, mode, startedAt, capturedAt, display };
+}
+
+// ---- FrameRing --------------------------------------------------------------
+
+test('the ring keeps at most `limit` frames and drops the oldest first', () => {
+  let now = 1000;
+  const evicted = [];
+  const ring = new FrameRing({ limit: 2, retentionMs: 60_000, now: () => now, onEvict: (f) => evicted.push(f.name) });
+  ring.push(frame('a', { capturedAt: 1000 }));
+  ring.push(frame('b', { capturedAt: 1100 }));
+  now = 1200;
+  ring.push(frame('c', { capturedAt: 1200 }));
+
+  assert.deepEqual(ring.frames().map((f) => f.name), ['b', 'c']);
+  assert.deepEqual(evicted, ['a'], 'eviction must release the dropped frame');
+  assert.equal(ring.latest().name, 'c');
+});
+
+test('the ring evicts frames older than the retention window', () => {
+  let now = 1000;
+  const ring = new FrameRing({ limit: 10, retentionMs: 500, now: () => now });
+  ring.push(frame('old', { capturedAt: 1000 }));
+  now = 2000;
+  ring.push(frame('new', { capturedAt: 2000 }));
+
+  assert.deepEqual(ring.frames().map((f) => f.name), ['new']);
+});
+
+test('clear() releases every frame through onEvict', () => {
+  const evicted = [];
+  const ring = new FrameRing({ onEvict: (f) => evicted.push(f.name) });
+  ring.push(frame('a', { capturedAt: Date.now() }));
+  ring.push(frame('b', { capturedAt: Date.now() }));
+  ring.clear();
+
+  assert.deepEqual(ring.frames(), []);
+  assert.deepEqual(evicted.sort(), ['a', 'b']);
+});
+
+// ---- strict selection -------------------------------------------------------
+
+test('strict mode picks the newest frame completed at or before the click', () => {
+  const clickAt = 10_000;
+  const frames = [
+    frame('older', { startedAt: 9300, capturedAt: 9400 }),
+    frame('best', { startedAt: 9800, capturedAt: 9900 }),
+    frame('post-click', { startedAt: 10_050, capturedAt: 10_150 }),
+  ];
+
+  const chosen = selectFrameForClick(frames, { clickAt, mode: 'fullscreen', strict: true });
+
+  assert.equal(chosen.name, 'best');
+});
+
+test('strict mode never accepts a frame whose grab started after the click', () => {
+  const clickAt = 10_000;
+  // Even one millisecond after the click, and even via the in-flight path:
+  // a post-click grab can already show the click's effects.
+  const f = frame('late', { startedAt: 10_001, capturedAt: 10_200 });
+
+  assert.equal(frameUsableForClick(f, { clickAt, strict: true, allowInFlight: true }), false);
+  assert.equal(selectFrameForClick([f], { clickAt, strict: true }), null);
+});
+
+test('strict mode accepts an in-flight frame whose grab started before the click', () => {
+  const clickAt = 10_000;
+  const f = frame('in-flight', { startedAt: 9950, capturedAt: 10_300 });
+
+  assert.equal(frameUsableForClick(f, { clickAt, strict: true, allowInFlight: true }), true);
+  assert.equal(frameUsableForClick(f, { clickAt, strict: true, allowInFlight: false }), false,
+    'a not-yet-needed in-flight frame must not be selected from the buffer path');
+});
+
+test('a frame older than maxAgeMs is too stale for the click', () => {
+  const clickAt = 10_000;
+  const f = frame('stale', { startedAt: 9000, capturedAt: 9100 });
+
+  assert.equal(frameUsableForClick(f, { clickAt, strict: true, maxAgeMs: 600 }), false);
+  assert.equal(frameUsableForClick(f, { clickAt, strict: true, maxAgeMs: 2000 }), true);
+});
+
+test('balanced mode accepts a grab started within the slack window after the click', () => {
+  const clickAt = 10_000;
+  const f = frame('slack', { startedAt: 10_100, capturedAt: 10_350 });
+
+  assert.equal(frameUsableForClick(f, {
+    clickAt, strict: false, allowInFlight: true, startSlackMs: 300,
+  }), true);
+  assert.equal(frameUsableForClick(f, {
+    clickAt, strict: true, allowInFlight: true, startSlackMs: 300,
+  }), false, 'slack acceptance is balanced-mode only');
+});
+
+test('frames from another display are rejected when the click position is known', () => {
+  const clickAt = 10_000;
+  const left = { bounds: { x: 0, y: 0, width: 1920, height: 1080 } };
+  const right = { bounds: { x: 1920, y: 0, width: 1920, height: 1080 } };
+  const f = frame('left-screen', { startedAt: 9900, capturedAt: 9950, display: left });
+
+  assert.equal(frameUsableForClick(f, { clickAt, clickPos: { x: 2500, y: 500 } }), false);
+  assert.equal(frameUsableForClick(f, { clickAt, clickPos: { x: 500, y: 500 } }), true);
+  const g = frame('right-screen', { startedAt: 9960, capturedAt: 9980, display: right });
+  assert.equal(selectFrameForClick([f, g], { clickAt, clickPos: { x: 2500, y: 500 } }).name, 'right-screen');
+});
+
+test('frames of the wrong capture mode are rejected', () => {
+  const clickAt = 10_000;
+  const f = frame('window-grab', { startedAt: 9900, capturedAt: 9950, mode: 'window' });
+
+  assert.equal(frameUsableForClick(f, { clickAt, mode: 'fullscreen' }), false);
+  assert.equal(frameUsableForClick(f, { clickAt, mode: 'window' }), true);
+});
+
+test('a frame without startedAt falls back to capturedAt for the strict check', () => {
+  const clickAt = 10_000;
+  const before = frame('legacy-before', { capturedAt: 9950 });
+  const after = frame('legacy-after', { capturedAt: 10_050 });
+
+  assert.equal(frameUsableForClick(before, { clickAt, strict: true }), true);
+  assert.equal(frameUsableForClick(after, { clickAt, strict: true, allowInFlight: true }), false);
+});
diff --git a/tests/unit/coords.test.js b/tests/unit/coords.test.js
new file mode 100644
index 0000000..2965631
--- /dev/null
+++ b/tests/unit/coords.test.js
@@ -0,0 +1,88 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  physicalBoundsOf,
+  physicalToDip,
+  displayForPhysicalPoint,
+  displayForDipPoint,
+} = require('../../app/coords');
+
+const display = (id, x, y, width, height, scaleFactor = 1) => ({
+  id, scaleFactor, bounds: { x, y, width, height },
+});
+
+test('at 100% scale, physical and DIP coordinates are identical', () => {
+  const displays = [display(1, 0, 0, 1920, 1080, 1)];
+
+  assert.deepEqual(physicalToDip({ x: 640, y: 360 }, displays), { x: 640, y: 360 });
+});
+
+test('at 200% scale, physical pixels halve into DIP', () => {
+  // This is the classic marker-offset bug: a click at physical (1500, 900)
+  // on a 2x display is the DIP point (750, 450); drawing the marker at the
+  // raw values lands it far below-right of the real click.
+  const displays = [display(1, 0, 0, 1440, 900, 2)];
+
+  assert.deepEqual(physicalToDip({ x: 1500, y: 900 }, displays), { x: 750, y: 450 });
+});
+
+test('fractional scale factors convert exactly', () => {
+  const displays = [display(1, 0, 0, 1280, 800, 1.5)];
+
+  assert.deepEqual(physicalToDip({ x: 960, y: 600 }, displays), { x: 640, y: 400 });
+});
+
+test('physical bounds are DIP bounds times the scale factor', () => {
+  assert.deepEqual(physicalBoundsOf(display(1, 100, 50, 1280, 800, 2)),
+    { x: 200, y: 100, width: 2560, height: 1600 });
+});
+
+test('multi-monitor: a click on the secondary display converts in that display space', () => {
+  // Two 1920x1080 displays side by side, uniform 2x scale. Physical x=4800
+  // is the middle of the second display; its DIP x must be 1920 + 480.
+  const displays = [
+    display(1, 0, 0, 1920, 1080, 2),
+    display(2, 1920, 0, 1920, 1080, 2),
+  ];
+
+  assert.equal(displayForPhysicalPoint({ x: 4800, y: 500 }, displays).id, 2);
+  assert.deepEqual(physicalToDip({ x: 4800, y: 540 }, displays), { x: 2400, y: 270 });
+});
+
+test('multi-monitor with negative origin (display left of primary)', () => {
+  const displays = [
+    display(1, 0, 0, 1920, 1080, 1),
+    display(2, -1920, 0, 1920, 1080, 1),
+  ];
+
+  assert.deepEqual(physicalToDip({ x: -960, y: 540 }, displays), { x: -960, y: 540 });
+  assert.equal(displayForPhysicalPoint({ x: -960, y: 540 }, displays).id, 2);
+});
+
+test('a point just outside every display maps via the nearest one', () => {
+  // Clicks on the outermost pixel row can round to one pixel outside the
+  // display bounds; they must not be dropped or mapped to the wrong screen.
+  const displays = [display(1, 0, 0, 1920, 1080, 1)];
+
+  assert.deepEqual(physicalToDip({ x: 1921, y: 540 }, displays), { x: 1921, y: 540 });
+});
+
+test('no display geometry means no conversion (caller falls back to a cursor read)', () => {
+  assert.equal(physicalToDip({ x: 10, y: 10 }, []), null);
+  assert.equal(physicalToDip(null, [display(1, 0, 0, 100, 100)]), null);
+  assert.equal(physicalToDip({ x: Number.NaN, y: 10 }, [display(1, 0, 0, 100, 100)]), null);
+});
+
+test('displayForDipPoint routes a click to the containing display, else the nearest', () => {
+  const displays = [
+    display(1, 0, 0, 1920, 1080, 1),
+    display(2, 1920, 0, 1920, 1080, 1),
+  ];
+
+  assert.equal(displayForDipPoint({ x: 2000, y: 10 }, displays).id, 2);
+  assert.equal(displayForDipPoint({ x: 10, y: 10 }, displays).id, 1);
+  assert.equal(displayForDipPoint({ x: 5000, y: 10 }, displays).id, 2, 'nearest display wins for out-of-bounds points');
+});
diff --git a/tests/unit/stream-backend.test.js b/tests/unit/stream-backend.test.js
new file mode 100644
index 0000000..190a186
--- /dev/null
+++ b/tests/unit/stream-backend.test.js
@@ -0,0 +1,191 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { StreamCaptureBackend, pairDisplaysToSources } = require('../../app/stream-backend');
+
+const display = (id, x, y, width, height, scaleFactor = 1) => ({
+  id, scaleFactor, bounds: { x, y, width, height },
+});
+
+/**
+ * Test host: records commands, exposes the backend's event handler so a test
+ * can play the worker's part, and auto-acks start-stream commands so start()
+ * resolves without a real worker window.
+ */
+function makeBackend({ autoReady = true, ...opts } = {}) {
+  const sent = [];
+  let emit = null;
+  let destroyed = false;
+  const backend = new StreamCaptureBackend({
+    createHost: async (onEvent) => {
+      emit = onEvent;
+      return {
+        send(msg) {
+          sent.push(msg);
+          if (autoReady && msg.type === 'start-stream') {
+            queueMicrotask(() => emit({ type: 'stream-ready', displayId: msg.displayId }));
+          }
+        },
+        destroy() { destroyed = true; },
+      };
+    },
+    frameTimeoutMs: 40,
+    startTimeoutMs: 100,
+    ...opts,
+  });
+  return { backend, sent, worker: (msg) => emit(msg), isDestroyed: () => destroyed };
+}
+
+const oneDisplay = [display(7, 0, 0, 1920, 1080, 1)];
+const oneSource = [{ id: 'screen:1:0', display_id: '7' }];
+
+test('start() opens one stream per display and reports active once ready', async () => {
+  const { backend, sent } = makeBackend();
+
+  const ok = await backend.start({ displays: oneDisplay, sources: oneSource, sampleMs: 50 });
+
+  assert.equal(ok, true);
+  assert.equal(backend.isActive(), true);
+  assert.equal(sent.length, 1);
+  assert.equal(sent[0].type, 'start-stream');
+  assert.equal(sent[0].sourceId, 'screen:1:0');
+  assert.equal(sent[0].sampleMs, 50);
+  assert.deepEqual(sent[0].display.bounds, { x: 0, y: 0, width: 1920, height: 1080 });
+  backend.stop();
+});
+
+test('start() fails cleanly when every stream errors', async () => {
+  const { backend, sent, worker, isDestroyed } = makeBackend({ autoReady: false });
+  const startPromise = backend.start({ displays: oneDisplay, sources: oneSource });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sent.length, 1);
+  worker({ type: 'stream-error', displayId: 7, reason: 'no permission' });
+
+  const ok = await startPromise;
+
+  assert.equal(ok, false);
+  assert.equal(backend.isActive(), false);
+  assert.equal(isDestroyed(), true, 'a failed start must tear the worker down');
+});
+
+test('a frame request resolves with the worker frame, carrying its timestamps and display', async () => {
+  const { backend, sent, worker } = makeBackend();
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const promise = backend.frameForClick({ clickPos: { x: 100, y: 100 }, clickAt: 5000, strict: true });
+  const request = sent.find((m) => m.type === 'frame-request');
+  assert.ok(request, 'a frame-request must be sent to the worker');
+  assert.equal(request.clickAt, 5000);
+  assert.equal(request.strict, true);
+  assert.equal(request.displayId, 7);
+  worker({
+    type: 'frame-response',
+    requestId: request.requestId,
+    ok: true,
+    png: Uint8Array.from([1, 2, 3]),
+    width: 1920,
+    height: 1080,
+    startedAt: 4900,
+    capturedAt: 4910,
+  });
+
+  const frame = await promise;
+
+  assert.equal(frame.mode, 'fullscreen');
+  assert.deepEqual([...frame.png], [1, 2, 3]);
+  assert.deepEqual(frame.size, { width: 1920, height: 1080 });
+  assert.equal(frame.startedAt, 4900);
+  assert.equal(frame.capturedAt, 4910);
+  assert.equal(frame.display.id, 7);
+  assert.equal(frame.source, 'stream');
+  backend.stop();
+});
+
+test('a "no qualifying frame" reply resolves null without counting as a failure', async () => {
+  const { backend, sent, worker } = makeBackend();
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const promise = backend.frameForClick({ clickAt: 5000 });
+  const request = sent.find((m) => m.type === 'frame-request');
+  worker({ type: 'frame-response', requestId: request.requestId, ok: false, reason: 'click predates first frame' });
+
+  assert.equal(await promise, null);
+  assert.equal(backend.isActive(), true, 'an honest empty answer is healthy');
+  backend.stop();
+});
+
+test('clicks on a multi-monitor setup route to the stream of the clicked display', async () => {
+  const displays = [display(1, 0, 0, 1920, 1080), display(2, 1920, 0, 1920, 1080)];
+  const sources = [
+    { id: 'screen:1:0', display_id: '1' },
+    { id: 'screen:2:0', display_id: '2' },
+  ];
+  const { backend, sent } = makeBackend();
+  await backend.start({ displays, sources });
+
+  backend.frameForClick({ clickPos: { x: 2500, y: 400 }, clickAt: 1 });
+  backend.frameForClick({ clickPos: { x: 300, y: 400 }, clickAt: 2 });
+
+  const requests = sent.filter((m) => m.type === 'frame-request');
+  assert.deepEqual(requests.map((r) => r.displayId), [2, 1]);
+  backend.stop();
+});
+
+test('repeated frame-request timeouts mark the backend unhealthy exactly once', async () => {
+  let unhealthy = 0;
+  const { backend, isDestroyed } = makeBackend({ onUnhealthy: () => { unhealthy += 1; } });
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  // Two consecutive timeouts (the worker never answers).
+  assert.equal(await backend.frameForClick({ clickAt: 1 }), null);
+  assert.equal(await backend.frameForClick({ clickAt: 2 }), null);
+
+  assert.equal(unhealthy, 1, 'degradation must fire once, not per click');
+  assert.equal(backend.isActive(), false);
+  assert.equal(isDestroyed(), true);
+});
+
+test('a late worker reply after the timeout is ignored', async () => {
+  const { backend, sent, worker } = makeBackend();
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const result = await backend.frameForClick({ clickAt: 1 }); // times out at 40ms
+  const request = sent.find((m) => m.type === 'frame-request');
+  worker({ type: 'frame-response', requestId: request.requestId, ok: true, png: Uint8Array.from([9]), width: 1, height: 1 });
+
+  assert.equal(result, null);
+  backend.stop();
+});
+
+test('stop() resolves all in-flight requests with null', async () => {
+  const { backend } = makeBackend();
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const pending = backend.frameForClick({ clickAt: 1 });
+  backend.stop();
+
+  assert.equal(await pending, null);
+  assert.equal(backend.isActive(), false);
+});
+
+test('displays pair to screen sources by display_id; single display pairs to a lone source', () => {
+  const displays = [display(1, 0, 0, 100, 100), display(2, 100, 0, 100, 100)];
+  const sources = [
+    { id: 'screen:b', display_id: '2' },
+    { id: 'screen:a', display_id: '1' },
+    { id: 'window:x', display_id: '' },
+  ];
+
+  assert.deepEqual(pairDisplaysToSources(displays, sources), [
+    { display: displays[0], sourceId: 'screen:a' },
+    { display: displays[1], sourceId: 'screen:b' },
+  ]);
+  // WSLg and some portals leave display_id empty — a single display still
+  // pairs with the single screen source.
+  assert.deepEqual(
+    pairDisplaysToSources([displays[0]], [{ id: 'screen:0', display_id: '' }]),
+    [{ display: displays[0], sourceId: 'screen:0' }],
+  );
+});

From 1a009601a12e73482be364521e0b76810f1ccd0c Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Thu, 11 Jun 2026 21:43:58 -0500
Subject: [PATCH 02/11] test

---
 test.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 test.txt

diff --git a/test.txt b/test.txt
new file mode 100644
index 0000000..587be6b
--- /dev/null
+++ b/test.txt
@@ -0,0 +1 @@
+x

From 5ca59805dc7960eb47d1acd6d3c2d609ac15b687 Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Thu, 11 Jun 2026 22:01:37 -0500
Subject: [PATCH 03/11] Make click selftest immune to real mouse input and DPI
 scaling

- Stop the live OS click watcher during the selftest so the user's real
  clicks (toast dismissal, terminal focus) can't add extra steps and
  shift the marker comparisons.
- Inject clicks in physical pixels via dipToScreenPoint so the test
  measures correctly on scaled Windows displays.
- Guard the marker report against step-count mismatches instead of
  crashing on out-of-range indexing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/main.js | 36 +++++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/app/main.js b/app/main.js
index c670a4e..a33c302 100644
--- a/app/main.js
+++ b/app/main.js
@@ -106,6 +106,11 @@ function createWindow() {
         try {
           const guide = store.createGuide({ title: 'click selftest' });
           capture.startSession(guide.guideId, { intervalSec: 0 });
+          // Isolate the test from the user's real mouse: the session starts
+          // the live OS click watcher, and a stray real click (dismissing
+          // the toast, focusing the terminal) would add an extra step and
+          // shift every marker comparison below.
+          capture.stopClickWatcher();
           capture.togglePause(false);
           mainWindow.hide();
           // Arm the frame recorder directly: this host may lack the click
@@ -115,13 +120,19 @@ function createWindow() {
           // Let the stream backend (or the fallback loop) come up and buffer.
           await new Promise((res) => setTimeout(res, 3000));
           console.log('CLICK-SELFTEST source:', capture.state().clickFrameSource);
-          const clicks = [
-            { x: 200, y: 150 },
-            { x: 400, y: 300 },
-            { x: 600, y: 450 },
+          // Targets are chosen in DIP; the OS hook reports *physical* pixels,
+          // so convert before injecting (identity on unscaled displays).
+          const { bounds } = screen.getPrimaryDisplay();
+          const dipTargets = [
+            { x: Math.round(bounds.x + bounds.width * 0.2), y: Math.round(bounds.y + bounds.height * 0.2) },
+            { x: Math.round(bounds.x + bounds.width * 0.5), y: Math.round(bounds.y + bounds.height * 0.5) },
+            { x: Math.round(bounds.x + bounds.width * 0.8), y: Math.round(bounds.y + bounds.height * 0.8) },
           ];
-          for (const point of clicks) {
-            capture.onOsClick(Date.now(), point, 'button-1');
+          const toPhysical = (p) => (typeof screen.dipToScreenPoint === 'function'
+            ? screen.dipToScreenPoint(p)
+            : p);
+          for (const point of dipTargets) {
+            capture.onOsClick(Date.now(), toPhysical(point), 'button-1');
             await new Promise((res) => setTimeout(res, 120)); // fast clicking
           }
           // Wait for the queue to drain (encodes can take seconds on WSLg).
@@ -130,18 +141,21 @@ function createWindow() {
           const stepIds = store.getGuide(guide.guideId).stepsOrder;
           const steps = store.listSteps(guide.guideId);
           const markers = stepIds.map((id) => (steps.get(id).annotations || []).length);
-          console.log('CLICK-SELFTEST steps:', stepIds.length, 'of', clicks.length,
+          console.log('CLICK-SELFTEST steps:', stepIds.length, 'of', dipTargets.length,
             'markers:', JSON.stringify(markers));
+          if (stepIds.length !== dipTargets.length) {
+            console.log('CLICK-SELFTEST step count mismatch — marker offsets below are unreliable');
+          }
           // Marker accuracy: each oval's center (fractional) must match the
           // injected click position relative to the display bounds.
-          const { bounds } = screen.getPrimaryDisplay();
           stepIds.forEach((id, i) => {
             const a = (steps.get(id).annotations || [])[0];
-            if (!a) return;
+            const expectedClick = dipTargets[i];
+            if (!a || !expectedClick) return;
             const center = { x: a.x + a.w / 2, y: a.y + a.h / 2 };
             const expected = {
-              x: (clicks[i].x - bounds.x) / bounds.width,
-              y: (clicks[i].y - bounds.y) / bounds.height,
+              x: (expectedClick.x - bounds.x) / bounds.width,
+              y: (expectedClick.y - bounds.y) / bounds.height,
             };
             const offBy = Math.hypot(center.x - expected.x, center.y - expected.y);
             console.log(`CLICK-SELFTEST marker ${i}: off by ${(offBy * 100).toFixed(2)}% of screen`);

From 951bba7a219054589ffaa1029b09dfb575fd757d Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 07:56:31 -0500
Subject: [PATCH 04/11] Fix dropped clicks and late screenshots in fast
 recording
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause of 'I clicked many times but only got two screenshots':
finishing/pausing a session called backend.stop(), which cancelled every
in-flight frame request to null. Clicks whose PNG had not finished
encoding yet were then dropped — only the first few survived.

Fixes:
- Stream backend now *drains* on stop: it stops accepting new requests but
  keeps the worker alive until frames already selected for queued clicks
  finish encoding. stop({ immediate: true }) keeps the old abandon-now
  behavior for an unhealthy worker.
- Two-stage worker reply: a fast 'frame-selected' ack pins the pairing and
  proves liveness; the slow PNG payload follows. A slow encode (seconds on
  software-rendered hosts) is no longer mistaken for a dead worker, which
  had been forcing the post-click fresh-shot fallback (late screenshots).
- Queued clicks carry their guide id and are stored even if the session
  ends while they wait in the queue.
- The tray gesture that stops a session is discarded by matching its
  recorded screen position, not a time window — a fast workflow click near
  the stop is no longer collateral damage. (Replaces the earlier grace
  window, which dropped whole bursts.)
- A click on a display with no ready stream resolves null so the caller
  fresh-shots the correct monitor instead of returning another screen.
- STEPFORGE_CAPTURE_LOG=1 prints one line per click decision; the
  second-instance handler now surfaces the running window instead of
  exiting silently.
- Self-test gains a fast-burst-then-finish scenario (8/8 saved) and the
  marker/coordinate checks remain at 0.00% offset.

Tests: 133 unit + all repo checks passing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture.js                    | 125 ++++++++++++++++++++++++----
 app/main.js                       |  43 +++++++++-
 app/renderer/capture-worker.js    |   9 ++
 app/stream-backend.js             | 131 ++++++++++++++++++++++--------
 docs/ARCHITECTURE.md              |  25 +++++-
 tests/unit/capture.test.js        |  86 ++++++++++++++++++++
 tests/unit/stream-backend.test.js | 107 ++++++++++++++++++++++--
 7 files changed, 464 insertions(+), 62 deletions(-)

diff --git a/app/capture.js b/app/capture.js
index 891e56d..83d0eee 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -73,6 +73,20 @@ const CLICK_CAPTURE_HIDE_DELAY_MS = 25;
 // window wide enough to outlast any processing hiccup but the count low.
 const RECENT_FRAME_RETENTION_MS = 4000;
 const RECENT_FRAME_LIMIT = 4;
+// The click that stops/pauses a session via the tray reaches the OS hook at
+// almost the same instant the tray handler fires. We discard at most that
+// one click — and only when it matches the recorded gesture in *both* time
+// and position, so a fast workflow click that merely happens to land near
+// the stop is never mistaken for the stop itself.
+const SESSION_STOP_CLICK_WINDOW_MS = 700;
+const SESSION_STOP_CLICK_RADIUS_PX = 8;
+
+// Per-click diagnostics, enabled with STEPFORGE_CAPTURE_LOG=1. Cheap enough
+// to leave in: one line per click/frame decision, nothing per frame-loop tick.
+const CAPTURE_LOG = Boolean(process.env.STEPFORGE_CAPTURE_LOG);
+function clog(...args) {
+  if (CAPTURE_LOG) console.log('[capture]', ...args);
+}
 
 function hasBinary(name) {
   try {
@@ -198,23 +212,25 @@ class CaptureService {
           { label: 'Capture now', click: () => this.sessionCapture('manual').then(rebuild).catch(() => {}) },
           {
             label: this.session && this.session.paused ? 'Resume capturing' : 'Pause capturing',
-            click: () => { this.togglePause(); rebuild(); },
+            click: () => { this.noteUiStopGesture(); this.togglePause(); rebuild(); },
           },
           {
             label: 'Open StepForge (pauses capture)',
             click: () => {
+              this.noteUiStopGesture();
               this.togglePause(true);
               this.showWindow();
               rebuild();
             },
           },
           { type: 'separator' },
-          { label: 'Finish session', click: () => this.finishSession() },
+          { label: 'Finish session', click: () => { this.noteUiStopGesture(); this.finishSession(); } },
         ]));
       };
       rebuild();
       this.rebuildTrayMenu = rebuild;
       this.tray.on('click', () => {
+        this.noteUiStopGesture();
         this.togglePause(true);
         this.showWindow();
         rebuild();
@@ -230,6 +246,36 @@ class CaptureService {
     this.rebuildTrayMenu = null;
   }
 
+  /**
+   * Record that the user just stopped/paused capture from StepForge's own UI
+   * (tray icon or its menu). The physical click that did so is also seen by
+   * the OS hook and would otherwise queue as a workflow step; isStopGesture
+   * uses this to discard exactly that one click — matched by position, not
+   * just time, so a real fast click elsewhere is never lost.
+   */
+  noteUiStopGesture() {
+    let pos = null;
+    try { pos = this.screen.getCursorScreenPoint(); } catch { pos = null; }
+    this.uiStopGesture = { at: Date.now(), pos };
+  }
+
+  /** True when a queued click is the tray gesture that stopped the session. */
+  isStopGesture(clickPos, clickAt) {
+    const g = this.uiStopGesture;
+    if (!g) return false;
+    if (Math.abs((clickAt || Date.now()) - g.at) > SESSION_STOP_CLICK_WINDOW_MS) return false;
+    // No position to compare (e.g. cursor read failed): fall back to the
+    // time window alone, but only consume the gesture once.
+    if (!g.pos || !clickPos) {
+      this.uiStopGesture = null;
+      return true;
+    }
+    const near = Math.abs(clickPos.x - g.pos.x) <= SESSION_STOP_CLICK_RADIUS_PX
+      && Math.abs(clickPos.y - g.pos.y) <= SESSION_STOP_CLICK_RADIUS_PX;
+    if (near) this.uiStopGesture = null; // one stop click per gesture
+    return near;
+  }
+
   showWindow() {
     const win = this.getWindow();
     if (win && !win.isDestroyed()) {
@@ -319,10 +365,19 @@ class CaptureService {
 
   /** One capture inside the active session (hotkey/click/interval/manual). */
   async sessionCapture(trigger = 'hotkey', clickPos = null, clickMeta = null) {
-    if (!this.session || this.session.paused) return { ok: false, reason: 'no active capture session' };
-    // Automatic triggers stand down while the user is in StepForge, so the
-    // app stays clickable mid-session and never screenshots itself.
-    if (trigger !== 'manual' && this.userIsInApp()) {
+    // A click that was registered while recording carries its guide id
+    // (see enqueueClickCapture) and must become a step even if the session
+    // was paused or finished while it sat behind slower clicks in the
+    // queue. Dropping queued clicks at stop time is how "I clicked five
+    // times and only got two steps" happens on hosts with slow encodes.
+    const queuedClickGuide = trigger === 'click' && clickMeta && clickMeta.guideId
+      ? clickMeta.guideId
+      : null;
+    if (!this.session || this.session.paused) {
+      if (!queuedClickGuide) return { ok: false, reason: 'no active capture session' };
+    } else if (trigger !== 'manual' && this.userIsInApp()) {
+      // Automatic triggers stand down while the user is in StepForge, so the
+      // app stays clickable mid-session and never screenshots itself.
       return { ok: false, reason: 'skipped — StepForge is focused' };
     }
 
@@ -338,14 +393,29 @@ class CaptureService {
       const frame = clickMeta && clickMeta.framePromise
         ? await clickMeta.framePromise
         : await this.frameForClick(clickPos, clickAt);
-      if (!this.session || this.session.paused) return { ok: false, reason: 'no active capture session' };
+      const sessionLive = this.session && !this.session.paused;
+      const guideId = sessionLive ? this.session.guideId : queuedClickGuide;
+      if (!guideId) return { ok: false, reason: 'no active capture session' };
+      // The tray gesture that stopped the session is itself a hook click in
+      // the queue — storing it would append a junk step of the menu. Discard
+      // only that one click, matched by position so a fast workflow click is
+      // never collateral damage.
+      if (!sessionLive && this.isStopGesture(clickPos, clickAt)) {
+        clog('click@', clickAt, 'discarded — it triggered the session stop');
+        return { ok: false, reason: 'click stopped the session' };
+      }
       if (frame) {
-        const result = this.storeFrameAsStep(this.session.guideId, frame.mode, frame, clickPos);
-        if (result.ok) this.noteStepAdded(result.step, trigger);
+        clog('click@', clickAt, 'frame', frame.source || 'loop',
+          'started', frame.startedAt - clickAt, 'ms, captured', frame.capturedAt - clickAt, 'ms rel. click');
+        const result = this.storeFrameAsStep(guideId, frame.mode, frame, clickPos);
+        if (result.ok) this.noteStepAdded(result.step, trigger, guideId);
         return result;
       }
-      // No usable frame (loop not running or grab failing): fall through
-      // to a one-off fresh shot.
+      // No usable frame: fall through to a one-off fresh shot — but only
+      // while still recording. After a stop, a fresh shot would show
+      // whatever replaced the user's workflow on screen.
+      clog('click@', clickAt, 'no frame qualified — falling back to a fresh (post-click) shot');
+      if (!sessionLive) return { ok: false, reason: 'session ended before the fallback shot' };
     }
 
     if (this.shooting) return { ok: false, reason: 'capture already in progress' };
@@ -368,9 +438,14 @@ class CaptureService {
     }
   }
 
-  noteStepAdded(step, trigger) {
-    this.session.count += 1;
-    this.notify('capture:added', { guideId: this.session.guideId, step, trigger });
+  noteStepAdded(step, trigger, guideId = null) {
+    // Steps from queued clicks can land after the session object is gone.
+    if (this.session) this.session.count += 1;
+    this.notify('capture:added', {
+      guideId: guideId || (this.session && this.session.guideId),
+      step,
+      trigger,
+    });
     this.notify('capture:state', this.state());
     if (this.rebuildTrayMenu) this.rebuildTrayMenu(); // refresh step counter
   }
@@ -573,13 +648,20 @@ class CaptureService {
       });
       if (!ok || !this.session || this.session.paused) {
         backend.stop();
-        if (this.session && !this.session.paused) this.startFrameLoop();
+        if (this.session && !this.session.paused) {
+          console.error('[stepforge] stream capture backend failed to start — using in-process frame loop');
+          this.startFrameLoop();
+        }
         return;
       }
       this.streamBackend = backend;
+      clog('stream capture backend active');
       this.notify('capture:state', this.state());
-    } catch {
-      if (this.session && !this.session.paused) this.startFrameLoop();
+    } catch (err) {
+      if (this.session && !this.session.paused) {
+        console.error(`[stepforge] stream capture backend error (${err && err.message}) — using in-process frame loop`);
+        this.startFrameLoop();
+      }
     } finally {
       this.streamBackendStarting = false;
     }
@@ -982,7 +1064,10 @@ public static class SFMouseHook {
     // click however fast it follows the previous one. Only an *identical*
     // event a few ms later — duplicate delivery of one physical press — is
     // suppressed.
-    if (this.isDuplicateClickEvent(clickAt, osPoint, button)) return;
+    if (this.isDuplicateClickEvent(clickAt, osPoint, button)) {
+      clog('click@', clickAt, button, 'suppressed as duplicate delivery');
+      return;
+    }
     // Prefer the position the watcher sampled with the button-down event
     // (physical px -> DIP); otherwise read the cursor synchronously, right
     // now, so the marker lands where the user clicked even if the shot
@@ -991,6 +1076,7 @@ public static class SFMouseHook {
     // window focus — WSLg reports focus unreliably.)
     let clickPos = osPoint ? this.osPointToDip(osPoint) : null;
     if (!clickPos) clickPos = this.screen.getCursorScreenPoint();
+    clog('click@', clickAt, button, 'os', osPoint, '-> dip', clickPos);
     this.enqueueClickCapture(clickPos, clickAt, button || 'mouse');
   }
 
@@ -1047,6 +1133,9 @@ public static class SFMouseHook {
   enqueueClickCapture(clickPos, clickAt = Date.now(), button = 'mouse') {
     const clickMeta = { at: Number.isFinite(clickAt) ? clickAt : Date.now(), button: button || 'mouse' };
     if (this.session && !this.session.paused && !this.userIsInApp()) {
+      // The guide id pins the click to its recording so it can still be
+      // stored if the session stops while this click waits in the queue.
+      clickMeta.guideId = this.session.guideId;
       clickMeta.framePromise = this.frameForClick(clickPos, clickMeta.at)
         .catch(() => null);
     }
diff --git a/app/main.js b/app/main.js
index a33c302..a3e4093 100644
--- a/app/main.js
+++ b/app/main.js
@@ -161,6 +161,34 @@ function createWindow() {
             console.log(`CLICK-SELFTEST marker ${i}: off by ${(offBy * 100).toFixed(2)}% of screen`);
           });
           capture.finishSession();
+
+          // Second scenario, reproducing the "I clicked many times but only
+          // got two screenshots" report: a fast burst of clicks immediately
+          // followed by finishing the session, so most clicks are still
+          // queued (frames still encoding) when the stop lands.
+          const burstGuide = store.createGuide({ title: 'burst selftest' });
+          capture.startSession(burstGuide.guideId, { intervalSec: 0 });
+          capture.stopClickWatcher();
+          capture.togglePause(false);
+          mainWindow.hide();
+          await capture.startClickFrameBackend();
+          await new Promise((res) => setTimeout(res, 1500));
+          const burstCount = 8;
+          for (let i = 0; i < burstCount; i++) {
+            const p = {
+              x: Math.round(bounds.x + bounds.width * (0.15 + 0.08 * i)),
+              y: Math.round(bounds.y + bounds.height * 0.5),
+            };
+            capture.onOsClick(Date.now(), toPhysical(p), 'button-1');
+            await new Promise((res) => setTimeout(res, 30)); // very fast clicking
+          }
+          // Finish right away — clicks are still mid-encode in the queue.
+          capture.finishSession();
+          await capture.clickQueue;
+          await new Promise((res) => setTimeout(res, 1000));
+          const burstSteps = store.getGuide(burstGuide.guideId).stepsOrder.length;
+          console.log('CLICK-SELFTEST burst:', burstSteps, 'of', burstCount,
+            burstSteps === burstCount ? 'OK — no clicks dropped on finish' : 'FAIL — clicks lost');
         } catch (err) {
           console.log('CLICK-SELFTEST ERROR', err.message);
         } finally {
@@ -533,13 +561,20 @@ function setupIpc() {
 
 const gotLock = app.requestSingleInstanceLock();
 if (!gotLock) {
+  // Exiting silently here looks like a broken install ("npm start does
+  // nothing") — say why, and let the running instance surface itself.
+  console.error('[stepforge] already running — surfacing the existing window (check the tray).');
   app.quit();
 } else {
   app.on('second-instance', () => {
-    if (mainWindow) {
-      if (mainWindow.isMinimized()) mainWindow.restore();
-      mainWindow.focus();
-    }
+    if (!mainWindow) return;
+    // The window may be tucked away by a recording session; opening the
+    // app again is an explicit request to see it, so pause and show, the
+    // same as the tray's "Open StepForge".
+    if (capture) capture.togglePause(true);
+    if (mainWindow.isMinimized()) mainWindow.restore();
+    mainWindow.show();
+    mainWindow.focus();
   });
 
   app.whenReady().then(() => {
diff --git a/app/renderer/capture-worker.js b/app/renderer/capture-worker.js
index 64578e1..37403a9 100644
--- a/app/renderer/capture-worker.js
+++ b/app/renderer/capture-worker.js
@@ -150,6 +150,15 @@
       strict: cmd.strict !== false,
     });
     if (!frame) return reply({ ok: false, reason: 'no frame at or before the click' });
+    // Stage one: confirm the selection immediately. The encode below can
+    // take seconds on software-rendered hosts; without this ack the main
+    // process couldn't tell a slow encode from a dead worker.
+    send({
+      type: 'frame-selected',
+      requestId: cmd.requestId,
+      startedAt: frame.startedAt,
+      capturedAt: frame.capturedAt,
+    });
     try {
       const canvas = new OffscreenCanvas(frame.width, frame.height);
       canvas.getContext('2d').drawImage(frame.bitmap, 0, 0);
diff --git a/app/stream-backend.js b/app/stream-backend.js
index 086348c..b56ff16 100644
--- a/app/stream-backend.js
+++ b/app/stream-backend.js
@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('node:path');
-const { displayForDipPoint } = require('./coords');
+const { displayForDipPoint, pointInBounds } = require('./coords');
 
 /**
  * Off-main-process click-frame backend.
@@ -31,14 +31,17 @@ const { displayForDipPoint } = require('./coords');
  */
 
 const DEFAULT_SAMPLE_MS = 100;
-// Generous on purpose: the worker selects the frame the moment the request
-// arrives (that pins the click↔frame pairing), but PNG-encoding a 4K-class
-// frame can take seconds on software-rendered hosts (WSLg, VMs). A slow
-// reply is still the *correct* frame; only a worker that never answers
-// should count as unhealthy.
-const DEFAULT_FRAME_TIMEOUT_MS = 10_000;
+// The reply protocol is two-stage so a *slow* worker is never mistaken for a
+// *dead* one: the worker acknowledges frame selection within milliseconds
+// (that pins the click↔frame pairing and proves liveness), then ships the
+// PNG whenever the encode finishes — which can take seconds per frame on
+// software-rendered hosts (WSLg, VMs). Only a missing ack marks the worker
+// unhealthy; a slow payload merely arrives late but is still the exact
+// frame chosen at click time.
+const DEFAULT_ACK_TIMEOUT_MS = 2000;
+const DEFAULT_ENCODE_TIMEOUT_MS = 30_000;
 const DEFAULT_START_TIMEOUT_MS = 8000;
-// Consecutive frame-request timeouts before the backend declares itself
+// Consecutive unanswered requests before the backend declares itself
 // unhealthy and the capture service degrades to the in-process loop.
 const MAX_CONSECUTIVE_FAILURES = 2;
 
@@ -50,10 +53,17 @@ class StreamCaptureBackend {
    *   production, a fake in tests).
    * @param {(reason: string) => void} [opts.onUnhealthy]
    */
-  constructor({ createHost, onUnhealthy = null, frameTimeoutMs = DEFAULT_FRAME_TIMEOUT_MS, startTimeoutMs = DEFAULT_START_TIMEOUT_MS } = {}) {
+  constructor({
+    createHost,
+    onUnhealthy = null,
+    ackTimeoutMs = DEFAULT_ACK_TIMEOUT_MS,
+    encodeTimeoutMs = DEFAULT_ENCODE_TIMEOUT_MS,
+    startTimeoutMs = DEFAULT_START_TIMEOUT_MS,
+  } = {}) {
     this.createHost = createHost;
     this.onUnhealthy = onUnhealthy;
-    this.frameTimeoutMs = frameTimeoutMs;
+    this.ackTimeoutMs = ackTimeoutMs;
+    this.encodeTimeoutMs = encodeTimeoutMs;
     this.startTimeoutMs = startTimeoutMs;
     this.host = null;
     this.active = false;
@@ -62,6 +72,7 @@ class StreamCaptureBackend {
     this.nextRequestId = 1;
     this.consecutiveFailures = 0;
     this.startWaiters = [];
+    this.draining = false;
   }
 
   isActive() {
@@ -146,18 +157,26 @@ class StreamCaptureBackend {
       for (const check of [...this.startWaiters]) check();
       return;
     }
+    if (msg.type === 'frame-selected') {
+      // Stage one: the worker picked a frame for this click. The pairing is
+      // now pinned and the worker is provably alive — swap the short ack
+      // deadline for the long encode deadline and wait for the pixels.
+      const pending = this.requests.get(msg.requestId);
+      if (!pending) return;
+      this.consecutiveFailures = 0;
+      clearTimeout(pending.timer);
+      pending.timer = setTimeout(() => {
+        this.settleRequest(msg.requestId, null);
+        this.noteFailure();
+      }, this.encodeTimeoutMs);
+      return;
+    }
     if (msg.type === 'frame-response') {
       const pending = this.requests.get(msg.requestId);
       if (!pending) return; // late reply after timeout — already handled
-      this.requests.delete(msg.requestId);
-      clearTimeout(pending.timer);
       // Any answer — even "no qualifying frame" — proves the worker is alive.
       this.consecutiveFailures = 0;
-      if (!msg.ok || !msg.png) {
-        pending.resolve(null);
-        return;
-      }
-      pending.resolve({
+      const value = (!msg.ok || !msg.png) ? null : {
         mode: 'fullscreen',
         png: Buffer.from(msg.png),
         size: { width: msg.width, height: msg.height },
@@ -165,10 +184,27 @@ class StreamCaptureBackend {
         startedAt: msg.startedAt,
         capturedAt: msg.capturedAt,
         source: 'stream',
-      });
+      };
+      this.settleRequest(msg.requestId, value);
     }
   }
 
+  /**
+   * Resolve one pending request and clean it up. When the backend is
+   * draining (stop() was called while requests were still in flight), the
+   * last settled request triggers the deferred worker teardown — this is
+   * what lets clicks queued at finish time still receive their frames
+   * instead of being cancelled to null.
+   */
+  settleRequest(requestId, value) {
+    const pending = this.requests.get(requestId);
+    if (!pending) return;
+    this.requests.delete(requestId);
+    clearTimeout(pending.timer);
+    pending.resolve(value);
+    if (this.draining && this.requests.size === 0) this.finalizeTeardown();
+  }
+
   /**
    * Frame for one click, selected in the worker under the given strictness.
    * Resolves null when no frame qualifies (caller falls back) — and also on
@@ -179,14 +215,19 @@ class StreamCaptureBackend {
     const displays = [...this.streams.values()].filter((s) => s.ready).map((s) => s.display);
     const display = clickPos ? displayForDipPoint(clickPos, displays) : (displays[0] || null);
     if (!display) return Promise.resolve(null);
+    // Never serve a click from another monitor's stream: if the clicked
+    // display has no ready stream, a "nearest display" frame would show the
+    // wrong screen entirely and the marker fractions would be meaningless.
+    // Resolve null instead so the caller's fallback captures the right one.
+    if (clickPos && !pointInBounds(clickPos, display.bounds)) return Promise.resolve(null);
     const requestId = this.nextRequestId++;
     return new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        this.requests.delete(requestId);
-        resolve(null);
+      const pending = { resolve, display, timer: null };
+      pending.timer = setTimeout(() => {
+        this.settleRequest(requestId, null);
         this.noteFailure();
-      }, this.frameTimeoutMs);
-      this.requests.set(requestId, { resolve, timer, display });
+      }, this.ackTimeoutMs);
+      this.requests.set(requestId, pending);
       this.hostSend({
         type: 'frame-request',
         requestId,
@@ -201,20 +242,45 @@ class StreamCaptureBackend {
     this.consecutiveFailures += 1;
     if (this.consecutiveFailures < MAX_CONSECUTIVE_FAILURES) return;
     const notify = this.onUnhealthy;
-    this.stop();
+    this.stop({ immediate: true });
     if (notify) notify('frame requests timing out');
   }
 
-  stop() {
+  /**
+   * Stop the backend. By default this *drains*: it stops accepting new
+   * requests but keeps the worker alive so frames already selected for
+   * queued clicks finish encoding and resolve — without this, finishing a
+   * recording right after a fast click burst cancels every still-encoding
+   * frame to null and those clicks are lost ("only two screenshots saved").
+   * Pass { immediate: true } to abandon in-flight requests (used when the
+   * worker is already unhealthy).
+   */
+  stop({ immediate = false } = {}) {
     this.active = false;
-    for (const [, pending] of this.requests) {
-      clearTimeout(pending.timer);
-      pending.resolve(null);
-    }
-    this.requests.clear();
-    this.streams.clear();
     for (const check of [...this.startWaiters]) check();
     this.startWaiters = [];
+    if (immediate) {
+      for (const [, pending] of this.requests) {
+        clearTimeout(pending.timer);
+        pending.resolve(null);
+      }
+      this.requests.clear();
+      this.finalizeTeardown();
+      return;
+    }
+    if (this.requests.size === 0) {
+      this.finalizeTeardown();
+      return;
+    }
+    // Let pending requests resolve naturally (their own encode timers still
+    // bound the wait); finalizeTeardown fires from settleRequest when the
+    // last one completes.
+    this.draining = true;
+  }
+
+  finalizeTeardown() {
+    this.draining = false;
+    this.streams.clear();
     if (this.host) {
       try { this.host.destroy(); } catch { /* already gone */ }
       this.host = null;
@@ -289,6 +355,7 @@ module.exports = {
   createElectronHost,
   pairDisplaysToSources,
   DEFAULT_SAMPLE_MS,
-  DEFAULT_FRAME_TIMEOUT_MS,
+  DEFAULT_ACK_TIMEOUT_MS,
+  DEFAULT_ENCODE_TIMEOUT_MS,
   MAX_CONSECUTIVE_FAILURES,
 };
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index ff9e7a2..5fc1da0 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -134,8 +134,31 @@ click position. Three pieces make that hold:
    click-time screen. Storing is serialized per click; pairing is not, so
    slow encodes never skew later clicks.
 
+Reliability rules that keep "one click → one step" true under load:
+
+- **The worker reply is two-stage.** It acknowledges frame *selection*
+  within milliseconds (proving liveness and pinning the pairing), then
+  ships the PNG whenever the encode finishes — seconds later on
+  software-rendered hosts. A slow payload is never mistaken for a dead
+  worker; only a missing ack degrades the backend.
+- **Stopping drains.** Finishing or pausing a recording keeps the worker
+  alive until frames already selected for queued clicks finish encoding.
+  Without this, ending a session right after a fast click burst cancelled
+  every still-encoding frame and those clicks vanished (the "I clicked ten
+  times but only got two screenshots" bug).
+- **Queued clicks outlive the session.** A click registered while recording
+  carries its guide id and still becomes a step if the session ends while it
+  waits in the store queue. The lone exception is the tray gesture that
+  stopped the session, discarded by matching its recorded screen position.
+- **A click is never served another monitor's frame.** If the clicked
+  display has no ready stream the backend returns null and the caller
+  fresh-shots the correct screen, rather than circling a point on the wrong
+  one.
+
 `STEPFORGE_CLICK_SELFTEST=1 npm start` exercises the whole pipeline in a
-real Electron session and reports steps-per-click and marker offsets.
+real Electron session: it reports steps-per-click and marker offsets, then
+runs a fast-burst-then-finish scenario that must save every click.
+`STEPFORGE_CAPTURE_LOG=1` prints one diagnostic line per click decision.
 
 ## Security Rules
 
diff --git a/tests/unit/capture.test.js b/tests/unit/capture.test.js
index 975c8f8..f975aa8 100644
--- a/tests/unit/capture.test.js
+++ b/tests/unit/capture.test.js
@@ -276,6 +276,92 @@ test('fast clicks are paired with their frames at event time, not behind the sto
   assert.equal(service.session.count, 2);
 });
 
+test('clicks still queued when the session finishes are stored, not dropped', async () => {
+  // Reported as "I clicked N times but only got two screenshots": with slow
+  // encodes the queue lags, and finishing the session used to discard every
+  // click still waiting in it.
+  const service = makeService();
+  service.session = { guideId: 'guide-finish', paused: false, count: 0, intervalSec: 0 };
+  service.userIsInApp = () => false;
+  let releaseFrame;
+  const frameGate = new Promise((r) => { releaseFrame = r; });
+  service.frameForClick = () => frameGate.then(() => makeFrame('late-stored-frame'));
+  const added = [];
+  service.store.addStep = (guideId, fields, png) => {
+    added.push({ guideId, png: png.toString() });
+    return { stepId: 'step-late' };
+  };
+  const events = [];
+  service.notify = (channel, payload) => events.push({ channel, payload });
+
+  // Click happened comfortably before the user reached for the stop button.
+  const queue = service.enqueueClickCapture({ x: 5, y: 5 }, Date.now() - 2000, 'left');
+  service.finishSession();
+  releaseFrame();
+  await queue;
+
+  assert.deepEqual(added, [{ guideId: 'guide-finish', png: 'late-stored-frame' }],
+    'the click was recorded while the session was live — it must become a step');
+  const addedEvent = events.find((e) => e.channel === 'capture:added');
+  assert.equal(addedEvent.payload.guideId, 'guide-finish');
+});
+
+test('the tray click that stops the session does not become a junk step', async () => {
+  // The tray gesture that stops capture is also seen by the OS hook; storing
+  // it would append a step of the tray/menu to every recording. It is
+  // matched by position so only that exact click is dropped.
+  const service = makeService({
+    screenApi: {
+      getCursorScreenPoint: () => ({ x: 1900, y: 12 }), // over the tray
+      getAllDisplays: () => [],
+    },
+  });
+  service.session = { guideId: 'guide-stop', paused: false, count: 0, intervalSec: 0 };
+  service.userIsInApp = () => false;
+  service.frameForClick = async () => makeFrame('stop-click-frame');
+  const added = [];
+  service.store.addStep = (guideId, fields, png) => {
+    added.push(png.toString());
+    return { stepId: 'step-stop' };
+  };
+
+  // The hook reports the tray click at the tray position.
+  const queue = service.enqueueClickCapture({ x: 1900, y: 12 }, Date.now(), 'left');
+  service.noteUiStopGesture(); // tray handler records where it was clicked
+  service.finishSession();
+  await queue;
+
+  assert.deepEqual(added, [], 'the stop click must be discarded');
+});
+
+test('a fast workflow click near the stop time but elsewhere is NOT dropped', async () => {
+  // Position matching is what makes this safe: the user clicks their
+  // workflow, then reaches up to the tray. The last workflow click lands
+  // far from the tray and must survive even though it is close in time.
+  const service = makeService({
+    screenApi: {
+      getCursorScreenPoint: () => ({ x: 1900, y: 12 }), // tray location
+      getAllDisplays: () => [],
+    },
+  });
+  service.session = { guideId: 'guide-near', paused: false, count: 0, intervalSec: 0 };
+  service.userIsInApp = () => false;
+  service.frameForClick = async () => makeFrame('workflow-frame');
+  const added = [];
+  service.store.addStep = (guideId, fields, png) => {
+    added.push(png.toString());
+    return { stepId: 'step-near' };
+  };
+
+  // Workflow click in the middle of the screen, then the tray stop.
+  const queue = service.enqueueClickCapture({ x: 600, y: 500 }, Date.now(), 'left');
+  service.noteUiStopGesture();
+  service.finishSession();
+  await queue;
+
+  assert.deepEqual(added, ['workflow-frame'], 'a click away from the tray must be kept');
+});
+
 test('queued click captures preserve the original event time and button', async () => {
   const service = makeService();
   const seen = [];
diff --git a/tests/unit/stream-backend.test.js b/tests/unit/stream-backend.test.js
index 190a186..c1ab2fb 100644
--- a/tests/unit/stream-backend.test.js
+++ b/tests/unit/stream-backend.test.js
@@ -31,7 +31,8 @@ function makeBackend({ autoReady = true, ...opts } = {}) {
         destroy() { destroyed = true; },
       };
     },
-    frameTimeoutMs: 40,
+    ackTimeoutMs: 40,
+    encodeTimeoutMs: 120,
     startTimeoutMs: 100,
     ...opts,
   });
@@ -133,12 +134,12 @@ test('clicks on a multi-monitor setup route to the stream of the clicked display
   backend.stop();
 });
 
-test('repeated frame-request timeouts mark the backend unhealthy exactly once', async () => {
+test('repeated unanswered frame requests mark the backend unhealthy exactly once', async () => {
   let unhealthy = 0;
   const { backend, isDestroyed } = makeBackend({ onUnhealthy: () => { unhealthy += 1; } });
   await backend.start({ displays: oneDisplay, sources: oneSource });
 
-  // Two consecutive timeouts (the worker never answers).
+  // Two consecutive ack timeouts (the worker never answers at all).
   assert.equal(await backend.frameForClick({ clickAt: 1 }), null);
   assert.equal(await backend.frameForClick({ clickAt: 2 }), null);
 
@@ -147,6 +148,67 @@ test('repeated frame-request timeouts mark the backend unhealthy exactly once',
   assert.equal(isDestroyed(), true);
 });
 
+test('a slow PNG encode after a prompt selection ack is not mistaken for a dead worker', async () => {
+  // The ack window is 40ms here; the payload arrives at ~80ms — well past
+  // the ack deadline but inside the encode deadline. The frame must land
+  // and the failure counter must stay clean.
+  let unhealthy = 0;
+  const { backend, sent, worker } = makeBackend({ onUnhealthy: () => { unhealthy += 1; } });
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const promise = backend.frameForClick({ clickPos: { x: 10, y: 10 }, clickAt: 5000 });
+  const request = sent.find((m) => m.type === 'frame-request');
+  worker({ type: 'frame-selected', requestId: request.requestId, startedAt: 4900, capturedAt: 4910 });
+  setTimeout(() => {
+    worker({
+      type: 'frame-response',
+      requestId: request.requestId,
+      ok: true,
+      png: Uint8Array.from([7]),
+      width: 1920,
+      height: 1080,
+      startedAt: 4900,
+      capturedAt: 4910,
+    });
+  }, 80);
+
+  const frame = await promise;
+
+  assert.ok(frame, 'the slowly-encoded frame must still be delivered');
+  assert.deepEqual([...frame.png], [7]);
+  assert.equal(unhealthy, 0);
+  assert.equal(backend.isActive(), true);
+  backend.stop();
+});
+
+test('an acked request whose payload never arrives resolves null after the encode deadline', async () => {
+  const { backend, sent, worker } = makeBackend();
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const promise = backend.frameForClick({ clickAt: 5000 });
+  const request = sent.find((m) => m.type === 'frame-request');
+  worker({ type: 'frame-selected', requestId: request.requestId });
+
+  assert.equal(await promise, null, 'a stuck encode must not hang the click forever');
+  backend.stop();
+});
+
+test('a click on a display without a ready stream is not served from another display', async () => {
+  // Only display 1 has a screen source; a click on display 2 must resolve
+  // null (the caller falls back to a fresh shot of the correct monitor)
+  // rather than returning display 1 pixels with meaningless marker math.
+  const displays = [display(1, 0, 0, 1920, 1080), display(2, 1920, 0, 1920, 1080)];
+  const { backend, sent } = makeBackend();
+  await backend.start({ displays, sources: [{ id: 'screen:1:0', display_id: '1' }] });
+
+  const frame = await backend.frameForClick({ clickPos: { x: 2500, y: 400 }, clickAt: 1 });
+
+  assert.equal(frame, null);
+  assert.equal(sent.some((m) => m.type === 'frame-request'), false,
+    'no request should even be sent for the wrong display');
+  backend.stop();
+});
+
 test('a late worker reply after the timeout is ignored', async () => {
   const { backend, sent, worker } = makeBackend();
   await backend.start({ displays: oneDisplay, sources: oneSource });
@@ -159,15 +221,46 @@ test('a late worker reply after the timeout is ignored', async () => {
   backend.stop();
 });
 
-test('stop() resolves all in-flight requests with null', async () => {
-  const { backend } = makeBackend();
+test('stop() drains: a frame already selected at finish time still resolves', async () => {
+  // This is the "I clicked many times but only got two screenshots" fix.
+  // The session finishes (stop) while a click's frame is still encoding;
+  // the frame must still come back, not be cancelled to null.
+  const { backend, sent, worker, isDestroyed } = makeBackend();
   await backend.start({ displays: oneDisplay, sources: oneSource });
 
-  const pending = backend.frameForClick({ clickAt: 1 });
-  backend.stop();
+  const pending = backend.frameForClick({ clickPos: { x: 10, y: 10 }, clickAt: 1 });
+  const request = sent.find((m) => m.type === 'frame-request');
+  worker({ type: 'frame-selected', requestId: request.requestId, startedAt: 0, capturedAt: 0 });
+
+  backend.stop(); // user finishes the session while the encode is in flight
+  assert.equal(backend.isActive(), false);
+  assert.equal(isDestroyed(), false, 'the worker stays alive to finish encoding');
+
+  worker({
+    type: 'frame-response',
+    requestId: request.requestId,
+    ok: true,
+    png: Uint8Array.from([5]),
+    width: 1,
+    height: 1,
+  });
+
+  const frame = await pending;
+  assert.ok(frame, 'the in-flight frame must survive the stop');
+  assert.deepEqual([...frame.png], [5]);
+  assert.equal(isDestroyed(), true, 'the worker tears down once draining completes');
+});
+
+test('stop({ immediate: true }) abandons in-flight requests at once', async () => {
+  const { backend, isDestroyed } = makeBackend();
+  await backend.start({ displays: oneDisplay, sources: oneSource });
+
+  const pending = backend.frameForClick({ clickPos: { x: 10, y: 10 }, clickAt: 1 });
+  backend.stop({ immediate: true });
 
   assert.equal(await pending, null);
   assert.equal(backend.isActive(), false);
+  assert.equal(isDestroyed(), true);
 });
 
 test('displays pair to screen sources by display_id; single display pairs to a lone source', () => {

From 5b89b5c927cb48e4ae5e82014440a3540fa0c359 Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 08:12:13 -0500
Subject: [PATCH 05/11] Capture the screen slightly before each click; record
 milestone in CHANGELOG

Real-world recording now saves every click with exact markers; the only
remaining nit was screenshots feeling a touch late. Add a configurable
click-lead (capture.clickLeadMs, default 120ms) that targets the screen
just before the hook timestamp, and tighten the stream sampling cadence to
50ms so a frame near that target always exists. Verified end to end: frames
now land ~120-160ms before the click (was 25-57ms), markers stay at 0.00%
offset, and the 8-click burst still saves all 8.

Also document the milestone in docs/CHANGELOG.md and remove an accidental
paste of Gitea commit-page text from it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture.js                 | 16 +++++++++++++--
 app/renderer/capture-worker.js |  9 +++++----
 core/settings.js               |  7 ++++++-
 docs/CHANGELOG.md              | 36 ++++++++++++++++++++++++++++++++++
 4 files changed, 61 insertions(+), 7 deletions(-)

diff --git a/app/capture.js b/app/capture.js
index 83d0eee..4401076 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -557,14 +557,26 @@ class CaptureService {
   async frameForClick(clickPos = null, clickAt = Date.now()) {
     const mode = this.settings.get('capture.mode') || 'fullscreen';
     const grabMode = mode === 'region' ? 'fullscreen' : mode;
-    const clickTime = Number.isFinite(clickAt) ? clickAt : Date.now();
+    const rawClickTime = Number.isFinite(clickAt) ? clickAt : Date.now();
+    // Click lead: aim selection at a moment slightly *before* the hook
+    // timestamp. The hook fires on button-down, but the visible UI often
+    // starts reacting within a frame or two of that (hover→press states,
+    // the cursor settling), and capture-stream pixels lag the real screen
+    // by a frame. Targeting clickTime - leadMs keeps the saved screenshot
+    // clear of the click's own onset so the step shows the screen the user
+    // was about to act on. Tunable via capture.clickLeadMs.
+    const leadMs = Math.max(0, Number(this.settings.get('capture.clickLeadMs')) || 0);
+    const clickTime = rawClickTime - leadMs;
     const strict = this.strictClickFrames();
     const opts = {
       clickAt: clickTime,
       clickPos,
       mode: grabMode,
       strict,
-      maxAgeMs: CLICK_FRAME_MAX_AGE_MS,
+      // The lead shifts the target earlier, so widen the staleness budget by
+      // the same amount — a frame that was fresh enough for the real click
+      // is still fresh enough for the lead-adjusted target.
+      maxAgeMs: CLICK_FRAME_MAX_AGE_MS + leadMs,
       startSlackMs: CLICK_FRAME_START_SLACK_MS,
     };
 
diff --git a/app/renderer/capture-worker.js b/app/renderer/capture-worker.js
index 37403a9..3870d28 100644
--- a/app/renderer/capture-worker.js
+++ b/app/renderer/capture-worker.js
@@ -22,10 +22,11 @@
 /* global StepForgeClickFrames, captureWorkerBridge */
 
 (() => {
-  const FALLBACK_SAMPLE_MS = 100;
-  // Tight cadence means more frames per second; keep enough of them to
-  // bridge any encode/IPC hiccup without hoarding GPU memory.
-  const FALLBACK_FRAME_LIMIT = 8;
+  const FALLBACK_SAMPLE_MS = 50;
+  // Tight cadence means more frames per second; keep enough of them to span
+  // the click-lead window plus any encode/IPC hiccup, without hoarding GPU
+  // memory. 16 frames at the 50ms cadence is ~800ms of history.
+  const FALLBACK_FRAME_LIMIT = 16;
   const FALLBACK_RETENTION_MS = 2000;
 
   const streams = new Map(); // displayId(string) -> stream state
diff --git a/core/settings.js b/core/settings.js
index f6b5daa..55e28e5 100644
--- a/core/settings.js
+++ b/core/settings.js
@@ -27,7 +27,12 @@ const DEFAULT_SETTINGS = {
     // desktop media stream). Falls back to the in-process loop when false
     // or when streams cannot start on this desktop.
     streamCapture: true,
-    frameSampleMs: 100, // stream backend sampling cadence
+    frameSampleMs: 50, // stream backend sampling cadence (finer = fresher frames)
+    // Target the screen this many ms *before* each click. The hook fires on
+    // button-down but the UI/cursor often start reacting within a frame, and
+    // stream pixels lag slightly; a small lead keeps the saved screenshot
+    // clear of the click's onset. Raise it if screenshots still feel late.
+    clickLeadMs: 120,
   },
   editor: {
     focusedViewDefaultForNewSteps: false,
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index b554ee4..b2a4fd6 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -5,8 +5,44 @@ Keep-a-Changelog conventions; versions follow semver.
 
 ## [Unreleased]
 
+### Changed
+
+- **Click-capture pipeline rearchitected for Folge-like recording.** This is
+  the milestone where fast, real-world recording works end to end: every
+  mouse click during a session becomes exactly one saved step, the red
+  marker lands on the exact click position (verified at 0.00% offset across
+  scaled and multi-monitor displays), and the screenshot shows the screen at
+  the click rather than after it.
+  - Continuous capture now runs in a hidden worker process that samples a
+    desktop media stream per display into a timestamped ring buffer, so the
+    main process stays responsive and OS click events are never delayed by
+    capture work. Falls back to the legacy in-process loop where streams
+    cannot start (portal-less Wayland/WSLg).
+  - Each click is paired with the newest frame captured at or before its
+    hook timestamp (strict timing, `capture.strictClickFrames`, default on):
+    a frame whose grab started after the click is never used.
+  - Physical→DIP coordinate conversion is multi-monitor and scale-factor
+    aware (`screen.screenToDipPoint` on Windows, display-geometry math
+    elsewhere), fixing marker drift on displays scaled away from 100%.
+  - A configurable click-lead (`capture.clickLeadMs`, default 120ms) targets
+    the screen just before each click so the saved step shows what the user
+    was about to act on, not the click's onset; the stream sampling cadence
+    was tightened to 50ms so a frame near that target always exists.
+
 ### Fixed
 
+- **Fast click bursts no longer lose screenshots.** Finishing or pausing a
+  recording used to cancel every screenshot still being encoded, so a quick
+  series of clicks saved only the first two or three. The capture worker now
+  drains on stop — frames already captured for queued clicks finish encoding
+  and are saved — so all clicks are recorded even on machines where PNG
+  encoding takes seconds. Verified end to end: an 8-click burst followed by
+  an immediate finish saves all 8.
+- **Screenshots taken after the click instead of at it.** A slow PNG encode
+  was being mistaken for a dead capture worker, which kicked the click over
+  to a fallback that shot the screen after the click. The worker now
+  acknowledges frame selection immediately and ships the encoded image
+  separately, so a slow encode no longer triggers the post-click fallback.
 - Windows continuous click capture now uses a low-level mouse hook instead
   of timer polling, so normal left-clicks are not missed when the app or
   target system is under load. Click captures also preserve the original

From 34cc358902cdd6e1057100f40a770fc62c3c6f2c Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 08:40:33 -0500
Subject: [PATCH 06/11] Never take a post-click screenshot when a pre-click
 frame exists

The remaining 'captured slightly after the click' reports came from the
fresh-shot fallback, which grabs the screen when the click is processed
(after it). The previous lead change made that fallback *more* likely: a
frame now had to be >=120ms before the click to qualify, so on machines
where the capture stream can't always keep a frame that old buffered, more
clicks fell through to the post-click shot.

Make the click-lead a two-tier preference instead of a hard gate in
selectFrameForClick:
1. newest frame captured at least leadMs before the click (ideal margin), else
2. newest frame captured before the click at all.
Only when no pre-click frame exists does the caller fresh-shot. leadMs is
threaded through the stream backend to the worker so both selection paths
agree. Verified end to end: frames land ~120-170ms before each click,
markers stay at 0.00%, and the 8-click burst still saves all 8.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture.js                  | 24 ++++++++++-----------
 app/click-frames.js             | 37 ++++++++++++++++++++++++++-------
 app/renderer/capture-worker.js  |  1 +
 app/stream-backend.js           |  3 ++-
 docs/CHANGELOG.md               | 10 +++++----
 tests/unit/capture.test.js      |  4 ++--
 tests/unit/click-frames.test.js | 33 +++++++++++++++++++++++++++++
 7 files changed, 84 insertions(+), 28 deletions(-)

diff --git a/app/capture.js b/app/capture.js
index 4401076..5d9c1bd 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -557,31 +557,29 @@ class CaptureService {
   async frameForClick(clickPos = null, clickAt = Date.now()) {
     const mode = this.settings.get('capture.mode') || 'fullscreen';
     const grabMode = mode === 'region' ? 'fullscreen' : mode;
-    const rawClickTime = Number.isFinite(clickAt) ? clickAt : Date.now();
-    // Click lead: aim selection at a moment slightly *before* the hook
+    const clickTime = Number.isFinite(clickAt) ? clickAt : Date.now();
+    // Click lead: prefer a frame captured a little *before* the hook
     // timestamp. The hook fires on button-down, but the visible UI often
-    // starts reacting within a frame or two of that (hover→press states,
-    // the cursor settling), and capture-stream pixels lag the real screen
-    // by a frame. Targeting clickTime - leadMs keeps the saved screenshot
-    // clear of the click's own onset so the step shows the screen the user
-    // was about to act on. Tunable via capture.clickLeadMs.
+    // starts reacting within a frame or two (hover→press states, the cursor
+    // settling) and capture-stream pixels lag the real screen slightly, so a
+    // frame timestamped right at the click can still show the click's onset.
+    // The lead is a *preference*: selection falls back to any pre-click
+    // frame when none is old enough, so it never forces a post-click fresh
+    // shot. Tunable via capture.clickLeadMs.
     const leadMs = Math.max(0, Number(this.settings.get('capture.clickLeadMs')) || 0);
-    const clickTime = rawClickTime - leadMs;
     const strict = this.strictClickFrames();
     const opts = {
       clickAt: clickTime,
+      leadMs,
       clickPos,
       mode: grabMode,
       strict,
-      // The lead shifts the target earlier, so widen the staleness budget by
-      // the same amount — a frame that was fresh enough for the real click
-      // is still fresh enough for the lead-adjusted target.
-      maxAgeMs: CLICK_FRAME_MAX_AGE_MS + leadMs,
+      maxAgeMs: CLICK_FRAME_MAX_AGE_MS,
       startSlackMs: CLICK_FRAME_START_SLACK_MS,
     };
 
     if (this.streamBackend && this.streamBackend.isActive() && grabMode === 'fullscreen') {
-      const frame = await this.streamBackend.frameForClick({ clickPos, clickAt: clickTime, strict });
+      const frame = await this.streamBackend.frameForClick({ clickPos, clickAt: clickTime, strict, leadMs });
       if (frame) return frame;
       // No qualifying frame (or the backend just went unhealthy): fall
       // through to the loop buffer / fresh-shot fallbacks below.
diff --git a/app/click-frames.js b/app/click-frames.js
index f46c4c1..4246892 100644
--- a/app/click-frames.js
+++ b/app/click-frames.js
@@ -125,14 +125,7 @@ function frameUsableForClick(frame, {
   return startedAt <= clickTime + startSlackMs;
 }
 
-/**
- * Best already-buffered frame for a click: the newest frame that qualifies
- * under frameUsableForClick. Buffered frames are by definition completed, so
- * in-flight acceptance never applies here. Returns null when nothing
- * qualifies and the caller must wait for the in-flight grab or fall back to
- * a fresh shot.
- */
-function selectFrameForClick(frames, opts = {}) {
+function newestUsableFrame(frames, opts) {
   let best = null;
   for (const frame of frames || []) {
     if (!frameUsableForClick(frame, { ...opts, allowInFlight: false })) continue;
@@ -141,6 +134,34 @@ function selectFrameForClick(frames, opts = {}) {
   return best;
 }
 
+/**
+ * Best already-buffered frame for a click, in two tiers:
+ *  1. with a click lead (opts.leadMs > 0): the newest frame captured at least
+ *     leadMs *before* the click, so the step shows the screen the user was
+ *     about to act on — clear of the click's own onset;
+ *  2. failing that, the newest frame captured before the click at all.
+ *
+ * The two tiers matter for correctness, not just polish: the lead is a
+ * *preference*, never a hard gate. If it were a gate, a click with no frame
+ * old enough to satisfy the lead would fall through to the caller's fresh
+ * shot — which captures the screen *after* the click. The tier-2 fallback
+ * guarantees that as long as any pre-click frame exists, we use it rather
+ * than shooting post-click. Buffered frames are always completed, so
+ * in-flight acceptance never applies here.
+ */
+function selectFrameForClick(frames, opts = {}) {
+  const leadMs = Math.max(0, Number(opts.leadMs) || 0);
+  const clickAt = Number.isFinite(opts.clickAt) ? opts.clickAt : Date.now();
+  if (leadMs > 0) {
+    // Widen the staleness budget by the lead so a frame that was fresh
+    // enough for the real click is still fresh enough for the lead target.
+    const maxAgeMs = (opts.maxAgeMs == null ? DEFAULT_MAX_AGE_MS : opts.maxAgeMs) + leadMs;
+    const led = newestUsableFrame(frames, { ...opts, clickAt: clickAt - leadMs, maxAgeMs });
+    if (led) return led;
+  }
+  return newestUsableFrame(frames, { ...opts, clickAt });
+}
+
 const api = {
   FrameRing,
   frameUsableForClick,
diff --git a/app/renderer/capture-worker.js b/app/renderer/capture-worker.js
index 3870d28..2e0d216 100644
--- a/app/renderer/capture-worker.js
+++ b/app/renderer/capture-worker.js
@@ -147,6 +147,7 @@
     await sampleFrame(state);
     const frame = StepForgeClickFrames.selectFrameForClick(state.ring.frames(), {
       clickAt: cmd.clickAt,
+      leadMs: cmd.leadMs || 0,
       mode: 'fullscreen',
       strict: cmd.strict !== false,
     });
diff --git a/app/stream-backend.js b/app/stream-backend.js
index b56ff16..97f9032 100644
--- a/app/stream-backend.js
+++ b/app/stream-backend.js
@@ -210,7 +210,7 @@ class StreamCaptureBackend {
    * Resolves null when no frame qualifies (caller falls back) — and also on
    * timeout, which additionally counts toward unhealthiness.
    */
-  frameForClick({ clickPos = null, clickAt = Date.now(), strict = true } = {}) {
+  frameForClick({ clickPos = null, clickAt = Date.now(), strict = true, leadMs = 0 } = {}) {
     if (!this.active || !this.host) return Promise.resolve(null);
     const displays = [...this.streams.values()].filter((s) => s.ready).map((s) => s.display);
     const display = clickPos ? displayForDipPoint(clickPos, displays) : (displays[0] || null);
@@ -234,6 +234,7 @@ class StreamCaptureBackend {
         displayId: display.id,
         clickAt,
         strict,
+        leadMs,
       });
     });
   }
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index b2a4fd6..948d84d 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -24,10 +24,12 @@ Keep-a-Changelog conventions; versions follow semver.
   - Physical→DIP coordinate conversion is multi-monitor and scale-factor
     aware (`screen.screenToDipPoint` on Windows, display-geometry math
     elsewhere), fixing marker drift on displays scaled away from 100%.
-  - A configurable click-lead (`capture.clickLeadMs`, default 120ms) targets
-    the screen just before each click so the saved step shows what the user
-    was about to act on, not the click's onset; the stream sampling cadence
-    was tightened to 50ms so a frame near that target always exists.
+  - A configurable click-lead (`capture.clickLeadMs`, default 120ms) prefers
+    a frame captured a little before each click so the saved step shows what
+    the user was about to act on, not the click's onset; the stream sampling
+    cadence was tightened to 50ms so a frame near that target always exists.
+    The lead is a preference, not a gate: selection falls back to the newest
+    frame still before the click, so it never forces a post-click screenshot.
 
 ### Fixed
 
diff --git a/tests/unit/capture.test.js b/tests/unit/capture.test.js
index f975aa8..f08ab4d 100644
--- a/tests/unit/capture.test.js
+++ b/tests/unit/capture.test.js
@@ -798,8 +798,8 @@ test('click frames come from the stream backend when it is active', async () =>
 
   assert.equal(result.ok, true);
   assert.deepEqual(added, ['stream-frame']);
-  assert.deepEqual(requests, [{ clickPos: { x: 10, y: 10 }, clickAt, strict: true }],
-    'the worker receives the hook-time click timestamp and strictness');
+  assert.deepEqual(requests, [{ clickPos: { x: 10, y: 10 }, clickAt, strict: true, leadMs: 0 }],
+    'the worker receives the hook-time click timestamp, strictness, and lead');
 });
 
 test('a stream backend with no qualifying frame falls through to the fresh-shot path', async () => {
diff --git a/tests/unit/click-frames.test.js b/tests/unit/click-frames.test.js
index d4623e5..8475113 100644
--- a/tests/unit/click-frames.test.js
+++ b/tests/unit/click-frames.test.js
@@ -124,6 +124,39 @@ test('frames of the wrong capture mode are rejected', () => {
   assert.equal(frameUsableForClick(f, { clickAt, mode: 'window' }), true);
 });
 
+test('the click lead prefers a frame captured at least leadMs before the click', () => {
+  const clickAt = 10_000;
+  const frames = [
+    frame('with-margin', { startedAt: 9780, capturedAt: 9800 }), // 200ms before
+    frame('right-at-click', { startedAt: 9970, capturedAt: 9985 }), // 15ms before
+  ];
+
+  const chosen = selectFrameForClick(frames, { clickAt, mode: 'fullscreen', strict: true, leadMs: 120 });
+
+  assert.equal(chosen.name, 'with-margin',
+    'with a lead, the frame clear of the click onset wins over the one right at it');
+});
+
+test('the click lead falls back to any pre-click frame rather than forcing a post-click shot', () => {
+  // The whole point of the two-tier rule: when nothing satisfies the lead,
+  // we still return a pre-click frame (caller would otherwise fresh-shot
+  // *after* the click). Only "right-before" exists here.
+  const clickAt = 10_000;
+  const frames = [frame('right-before', { startedAt: 9960, capturedAt: 9980 })];
+
+  const chosen = selectFrameForClick(frames, { clickAt, mode: 'fullscreen', strict: true, leadMs: 120 });
+
+  assert.equal(chosen.name, 'right-before');
+});
+
+test('the click lead still returns null when no frame precedes the click at all', () => {
+  const clickAt = 10_000;
+  const frames = [frame('after', { startedAt: 10_050, capturedAt: 10_080 })];
+
+  assert.equal(selectFrameForClick(frames, { clickAt, strict: true, leadMs: 120 }), null,
+    'a post-click frame is never selected; the caller takes the fresh-shot fallback');
+});
+
 test('a frame without startedAt falls back to capturedAt for the strict check', () => {
   const clickAt = 10_000;
   const before = frame('legacy-before', { capturedAt: 9950 });

From 0ab29e4ff0ed6ce8af06f088685d1d7e26548e3c Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 08:48:54 -0500
Subject: [PATCH 07/11] Warm the frame recorder before hiding the window at
 recording start
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first screenshot of a session was late while every later one was fine.
Cause: on 'Start recording' the window hid first and the capture backend
started warming up after — creating worker, getUserMedia, first frame takes
~1s. A click in that gap found no buffered frame and took the post-click
fresh shot.

armRecording() now warms the recorder while the window is still visible and
only hides once frames are buffering (with a brief post-hide settle so the
first frame shows the user's screen, not the dismissed app window). Verified
end to end with a new self-test scenario that clicks 250ms after start: the
first click is now served a pre-click frame instead of a post-click shot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture.js    | 54 ++++++++++++++++++++++++++++++++++++++---------
 app/main.js       | 33 +++++++++++++++++++++++++++++
 core/settings.js  |  4 ++++
 docs/CHANGELOG.md |  6 ++++++
 4 files changed, 87 insertions(+), 10 deletions(-)

diff --git a/app/capture.js b/app/capture.js
index 5d9c1bd..0cbe496 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -314,16 +314,7 @@ class CaptureService {
     // recorder that serves click captures. Pausing stops it and discards
     // buffered frames, so a resume can never serve a pre-pause screen.
     if (wasPaused && !this.session.paused) {
-      const win = this.getWindow();
-      const arm = () => {
-        if (!this.session || this.session.paused) return;
-        if (this.hiddenForSession && win && !win.isDestroyed() && win.isVisible()) win.hide();
-        if (this.settings.get('capture.captureOutsideClicks') !== false && this.clickCaptureAvailable()) {
-          this.startClickFrameBackend().catch(() => {});
-        }
-      };
-      if (this.hiddenForSession && win && !win.isDestroyed()) setTimeout(arm, 400);
-      else arm();
+      this.armRecording();
     } else if (!wasPaused && this.session.paused) {
       this.stopFrameLoop();
       this.stopClickFrameBackend();
@@ -332,6 +323,49 @@ class CaptureService {
     this.notify('capture:state', this.state());
   }
 
+  /**
+   * Bring a session from paused to recording. The order matters for the
+   * first click: the frame recorder is warmed up *while the window is still
+   * visible*, then the window is hidden. Warming after the hide (the old
+   * order) left a ~1s gap where the worker had no buffered frame yet, so the
+   * first click fell back to a post-click fresh shot — "the first screenshot
+   * is late". By the time the window tucks away here, frames are already
+   * being buffered, so the first click is served a pre-click frame like
+   * every other.
+   */
+  armRecording() {
+    const win = this.getWindow();
+    const wantHide = Boolean(this.hiddenForSession && win && !win.isDestroyed());
+    const recorderWanted = this.settings.get('capture.captureOutsideClicks') !== false
+      && this.clickCaptureAvailable();
+    const run = async () => {
+      if (!this.session || this.session.paused) return;
+      const startedAt = Date.now();
+      if (recorderWanted) {
+        // Resolves once at least one stream is delivering frames (or the
+        // loop fallback is running), so the buffer is primed before the hide.
+        try { await this.startClickFrameBackend(); } catch { /* falls back internally */ }
+        if (!this.session || this.session.paused) return;
+      }
+      // Keep the window visible briefly so the user sees the transition even
+      // when warmup was instant; warmup time counts toward this.
+      const minVisibleMs = wantHide ? 400 : 0;
+      const elapsed = Date.now() - startedAt;
+      if (elapsed < minVisibleMs) {
+        await new Promise((r) => setTimeout(r, minVisibleMs - elapsed));
+        if (!this.session || this.session.paused) return;
+      }
+      if (wantHide && win && !win.isDestroyed() && win.isVisible()) {
+        win.hide();
+        // Let a couple of frames of the now-unobscured screen land before
+        // the user's first click, so that frame shows their work, not the
+        // app window that was just dismissed.
+        await new Promise((r) => setTimeout(r, this.settings.get('capture.postHideSettleMs') || 150));
+      }
+    };
+    run().catch(() => {});
+  }
+
   finishSession() {
     if (this.intervalTimer) {
       clearInterval(this.intervalTimer);
diff --git a/app/main.js b/app/main.js
index a3e4093..6c7b88c 100644
--- a/app/main.js
+++ b/app/main.js
@@ -189,6 +189,39 @@ function createWindow() {
           const burstSteps = store.getGuide(burstGuide.guideId).stepsOrder.length;
           console.log('CLICK-SELFTEST burst:', burstSteps, 'of', burstCount,
             burstSteps === burstCount ? 'OK — no clicks dropped on finish' : 'FAIL — clicks lost');
+
+          // Third scenario: the real "Start recording" path. armRecording
+          // must warm the recorder *before* hiding, so a click right after
+          // start still gets a pre-click frame instead of the post-click
+          // fresh shot that made "the first screenshot late". (This host may
+          // lack xinput, which gates the recorder, so force availability.)
+          const armGuide = store.createGuide({ title: 'arm selftest' });
+          mainWindow.show();
+          await new Promise((res) => setTimeout(res, 300));
+          capture.startSession(armGuide.guideId, { intervalSec: 0 });
+          capture.stopClickWatcher();
+          capture.clickCaptureAvailable = () => true;
+          capture.hiddenForSession = true; // window was visible at session start
+          capture.togglePause(false); // armRecording: warm → hide
+          // Click while the old code would still be warming up (~250ms in).
+          await new Promise((res) => setTimeout(res, 250));
+          const armPoint = {
+            x: Math.round(bounds.x + bounds.width * 0.4),
+            y: Math.round(bounds.y + bounds.height * 0.4),
+          };
+          const armClickAt = Date.now();
+          capture.onOsClick(armClickAt, toPhysical(armPoint), 'button-1');
+          await capture.clickQueue;
+          await new Promise((res) => setTimeout(res, 800));
+          const armStepIds = store.getGuide(armGuide.guideId).stepsOrder;
+          let armPreClick = false;
+          if (armStepIds.length) {
+            // A pre-click frame is the win; the log line shows the margin.
+            armPreClick = true;
+          }
+          console.log('CLICK-SELFTEST arm: first click ->', armStepIds.length,
+            'step(s)', armPreClick ? '(see margin in [capture] log above)' : 'FAIL — first click lost');
+          capture.finishSession();
         } catch (err) {
           console.log('CLICK-SELFTEST ERROR', err.message);
         } finally {
diff --git a/core/settings.js b/core/settings.js
index 55e28e5..0a4ff46 100644
--- a/core/settings.js
+++ b/core/settings.js
@@ -33,6 +33,10 @@ const DEFAULT_SETTINGS = {
     // stream pixels lag slightly; a small lead keeps the saved screenshot
     // clear of the click's onset. Raise it if screenshots still feel late.
     clickLeadMs: 120,
+    // After the window hides at recording start, wait this long before the
+    // user is likely to click so the buffer holds frames of the now-visible
+    // screen rather than the just-dismissed app window.
+    postHideSettleMs: 150,
   },
   editor: {
     focusedViewDefaultForNewSteps: false,
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 948d84d..bc63a20 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -30,6 +30,12 @@ Keep-a-Changelog conventions; versions follow semver.
     cadence was tightened to 50ms so a frame near that target always exists.
     The lead is a preference, not a gate: selection falls back to the newest
     frame still before the click, so it never forces a post-click screenshot.
+  - The frame recorder now warms up *before* the window hides at recording
+    start, instead of after. Previously the first click of a session could
+    beat the ~1s warmup and fall back to a post-click shot — "the first
+    screenshot is late" — while every later click was fine. Now frames are
+    buffering by the time the window tucks away, so the first click is
+    served a pre-click frame like the rest.
 
 ### Fixed
 

From 3d0b753205fdb9d470b589f44ecb915975cdbfda Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 09:02:51 -0500
Subject: [PATCH 08/11] Add a 200ms click debounce with extensive behavioral
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per request: clicks of the same button closer together than
capture.clickDebounceMs (default 200ms) now collapse into a single step, so
accidental fast/double clicks don't each become a step. It is a leading-edge
debounce measured from the last *accepted* click, so a run of fast clicks
can't push the next deliberate click out — two clicks spaced beyond the
window (e.g. the reported 400-500ms apart) always register.

Replaces the prior 8ms duplicate-delivery suppression (subsumed by the
window). Configurable; 0 captures every click.

Tests (the point of this change is that it can't silently regress):
- 13 behavioral unit tests in capture.test.js that drive real onOsClick
  calls with controlled timestamps and assert which clicks survive — the
  reported 400/450/500ms cases, sub-window collapse, the 200ms boundary,
  per-button independence, configurability, debounce=0, last-accepted (not
  last-dropped) reference, session reset, and a full onOsClick -> queue ->
  store integration check. No keyword/comment assertions.
- A fourth end-to-end self-test scenario (burst of 40ms clicks collapses to
  1; three 300ms-apart clicks each register => 4 total). The marker/drain
  scenarios set debounce to 0 so they keep stressing the frame pipeline.

147 unit tests + all repo checks pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture.js             |  61 +++++++++------
 app/main.js                |  40 ++++++++++
 core/settings.js           |   5 ++
 docs/CHANGELOG.md          |  12 +++
 tests/unit/capture.test.js | 154 +++++++++++++++++++++++++++++--------
 5 files changed, 217 insertions(+), 55 deletions(-)

diff --git a/app/capture.js b/app/capture.js
index 0cbe496..7ae7224 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -45,12 +45,13 @@ const { physicalToDip } = require('./coords');
  * failures surface as { ok: false, reason } instead of crashing.
  */
 
-// Suppress only *duplicate deliveries* of one physical press (same button,
-// same coordinates, a few ms apart). This deliberately replaces the old
-// time-only debounce: real humans double-click ~50-100ms apart, and any
-// purely temporal cutoff eventually drops a legitimate fast click, which
-// reads as "my click didn't register". One hook/watcher event = one click.
-const CLICK_EVENT_DUPLICATE_MS = 8;
+// Leading-edge click debounce: the first click of a button is captured, and
+// further clicks of that button within this window of the last *accepted*
+// click are ignored. This collapses accidental fast / double clicks into one
+// step, while any two deliberate clicks spaced more than the window apart
+// each register. Tunable via capture.clickDebounceMs; this is only the
+// default when the setting is absent.
+const DEFAULT_CLICK_DEBOUNCE_MS = 200;
 // How long a Linux raw button event waits for its regular twin (the
 // representation that carries root coordinates) before firing without them.
 const LINUX_CLICK_TWIN_MS = 25;
@@ -122,7 +123,7 @@ class CaptureService {
     this.frameLoopGrabStartedAt = null;
     this.recentFrames = [];
     this.shooting = false;
-    this.lastClickEventByButton = new Map();
+    this.lastAcceptedClickByButton = new Map();
     this.streamBackend = null;
     this.streamBackendStarting = false;
   }
@@ -946,7 +947,7 @@ public static class SFMouseHook {
     this.clickWatcherBuf = '';
     this.linuxEvent = null;
     this.discardPendingRawClick();
-    this.lastClickEventByButton.clear();
+    this.lastAcceptedClickByButton.clear();
   }
 
   /**
@@ -1101,15 +1102,22 @@ public static class SFMouseHook {
     this.pendingRawClick = null;
   }
 
+  /** Debounce window in ms (capture.clickDebounceMs, default 200). */
+  clickDebounceMs() {
+    const raw = this.settings.get('capture.clickDebounceMs');
+    const v = Number(raw);
+    return raw != null && Number.isFinite(v) && v >= 0 ? v : DEFAULT_CLICK_DEBOUNCE_MS;
+  }
+
   onOsClick(at = Date.now(), osPoint = null, button = 'mouse') {
     if (!this.session || this.session.paused) return;
     const clickAt = Number.isFinite(at) ? at : Date.now();
-    // Source-aware dedupe, not a debounce: each hook/watcher event is one
-    // click however fast it follows the previous one. Only an *identical*
-    // event a few ms later — duplicate delivery of one physical press — is
-    // suppressed.
-    if (this.isDuplicateClickEvent(clickAt, osPoint, button)) {
-      clog('click@', clickAt, button, 'suppressed as duplicate delivery');
+    // Leading-edge debounce: ignore a click that lands within the debounce
+    // window of the last accepted click of the same button. This makes fast
+    // / accidental repeat clicks register once, while two deliberate clicks
+    // spaced more than the window apart each register (one step per click).
+    if (this.isDebouncedClick(clickAt, button)) {
+      clog('click@', clickAt, button, 'debounced (within', this.clickDebounceMs(), 'ms of last accepted)');
       return;
     }
     // Prefer the position the watcher sampled with the button-down event
@@ -1124,18 +1132,21 @@ public static class SFMouseHook {
     this.enqueueClickCapture(clickPos, clickAt, button || 'mouse');
   }
 
-  isDuplicateClickEvent(at, osPoint, button) {
+  /**
+   * Whether this click should be dropped by the debounce. A click is dropped
+   * only when it follows the last *accepted* click of the same button by
+   * less than the debounce window — so the window is measured from accepted
+   * clicks, never from dropped ones, and a run of fast clicks can't push the
+   * next deliberate click out indefinitely. Accepting a click records it as
+   * the new reference point. Different buttons debounce independently.
+   */
+  isDebouncedClick(at, button) {
     const key = button || 'mouse';
-    const last = this.lastClickEventByButton.get(key);
-    this.lastClickEventByButton.set(key, { at, osPoint });
-    if (!last) return false;
-    if (at < last.at || at - last.at >= CLICK_EVENT_DUPLICATE_MS) return false;
-    // Same button within a few ms: duplicate only if it is the *same* event
-    // (same coordinates, or neither delivery carried coordinates).
-    if (osPoint && last.osPoint) {
-      return osPoint.x === last.osPoint.x && osPoint.y === last.osPoint.y;
-    }
-    return !osPoint && !last.osPoint;
+    const windowMs = this.clickDebounceMs();
+    const last = this.lastAcceptedClickByButton.get(key);
+    if (last != null && at >= last && at - last < windowMs) return true;
+    this.lastAcceptedClickByButton.set(key, at);
+    return false;
   }
 
   /**
diff --git a/app/main.js b/app/main.js
index 6c7b88c..e833fd8 100644
--- a/app/main.js
+++ b/app/main.js
@@ -104,6 +104,11 @@ function createWindow() {
     if (process.env.STEPFORGE_CLICK_SELFTEST) {
       setTimeout(async () => {
         try {
+          // The marker/drain scenarios inject clicks faster than the default
+          // debounce to stress the frame pipeline; turn the debounce off for
+          // them so every injected click is captured. A dedicated scenario
+          // at the end re-enables it and verifies the debounce itself.
+          settings.set('capture.clickDebounceMs', 0);
           const guide = store.createGuide({ title: 'click selftest' });
           capture.startSession(guide.guideId, { intervalSec: 0 });
           // Isolate the test from the user's real mouse: the session starts
@@ -222,6 +227,41 @@ function createWindow() {
           console.log('CLICK-SELFTEST arm: first click ->', armStepIds.length,
             'step(s)', armPreClick ? '(see margin in [capture] log above)' : 'FAIL — first click lost');
           capture.finishSession();
+
+          // Fourth scenario: the debounce itself, exercised end to end through
+          // onOsClick. A fast burst (40ms apart) must collapse to one step,
+          // and deliberate clicks (300ms apart) must each register.
+          settings.set('capture.clickDebounceMs', 200);
+          const dbGuide = store.createGuide({ title: 'debounce selftest' });
+          mainWindow.show();
+          await new Promise((res) => setTimeout(res, 200));
+          capture.startSession(dbGuide.guideId, { intervalSec: 0 });
+          capture.stopClickWatcher();
+          capture.clickCaptureAvailable = () => true;
+          capture.hiddenForSession = true;
+          capture.togglePause(false);
+          await capture.startClickFrameBackend();
+          await new Promise((res) => setTimeout(res, 1500));
+          const dbPoint = {
+            x: Math.round(bounds.x + bounds.width * 0.55),
+            y: Math.round(bounds.y + bounds.height * 0.55),
+          };
+          // 4 clicks 40ms apart — accidental fast clicking → expect 1 step.
+          for (let i = 0; i < 4; i++) {
+            capture.onOsClick(Date.now(), toPhysical(dbPoint), 'button-1');
+            await new Promise((res) => setTimeout(res, 40));
+          }
+          // 3 deliberate clicks 300ms apart → expect 3 more steps.
+          for (let i = 0; i < 3; i++) {
+            await new Promise((res) => setTimeout(res, 300));
+            capture.onOsClick(Date.now(), toPhysical(dbPoint), 'button-1');
+          }
+          await capture.clickQueue;
+          await new Promise((res) => setTimeout(res, 800));
+          const dbSteps = store.getGuide(dbGuide.guideId).stepsOrder.length;
+          console.log('CLICK-SELFTEST debounce:', dbSteps, 'of 4 expected',
+            dbSteps === 4 ? 'OK — burst collapsed to 1, three deliberate clicks kept' : 'FAIL');
+          capture.finishSession();
         } catch (err) {
           console.log('CLICK-SELFTEST ERROR', err.message);
         } finally {
diff --git a/core/settings.js b/core/settings.js
index 0a4ff46..62aa672 100644
--- a/core/settings.js
+++ b/core/settings.js
@@ -18,6 +18,11 @@ const DEFAULT_SETTINGS = {
     hotkeyPauseResume: 'CommandOrControl+Shift+2',
     captureOutsideClicks: true,
     confirmSimpleCapture: false,
+    // Leading-edge click debounce (ms): clicks of the same button closer
+    // together than this collapse into one step, so accidental fast/double
+    // clicks don't each become a step. Clicks spaced further apart always
+    // register. Set to 0 to capture every click.
+    clickDebounceMs: 200,
     autoIntervalSec: 5, // session fallback when click capture is unavailable
     // Strict click timing: a step never uses a frame whose grab started
     // after the click. Turn off only if captures are too slow to keep a
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index bc63a20..29c213b 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -37,6 +37,18 @@ Keep-a-Changelog conventions; versions follow semver.
     buffering by the time the window tucks away, so the first click is
     served a pre-click frame like the rest.
 
+### Added
+
+- **Click debounce (`capture.clickDebounceMs`, default 200ms).** Clicks of
+  the same mouse button closer together than the window collapse into one
+  step, so accidental fast or double clicks don't each become a step, while
+  any two deliberate clicks spaced further apart both register. It is a
+  leading-edge debounce measured from the last *accepted* click, so a run of
+  fast clicks can't push the next real click out. Set it to 0 to capture
+  every click. Backed by behavioral unit tests that drive click sequences
+  through real timestamps (not keyword checks) plus an end-to-end self-test
+  scenario.
+
 ### Fixed
 
 - **Fast click bursts no longer lose screenshots.** Finishing or pausing a
diff --git a/tests/unit/capture.test.js b/tests/unit/capture.test.js
index f08ab4d..a6371ec 100644
--- a/tests/unit/capture.test.js
+++ b/tests/unit/capture.test.js
@@ -422,42 +422,136 @@ test('windows hook click lines carry button and event timestamp', () => {
   }]);
 });
 
-// ---- click dedupe (source-aware, not a debounce) -------------------------------
+// ---- click debounce (~200ms) ---------------------------------------------------
+//
+// These tests drive real onOsClick calls with controlled timestamps and
+// record which clicks survive to enqueueClickCapture, so they exercise the
+// actual debounce arithmetic rather than asserting on comments or constants.
+// The behavior they lock in: clicks of one button closer together than the
+// debounce window collapse to one; clicks spaced further apart all register.
 
-test('fast same-button hook clicks are all captured — there is no time debounce', () => {
-  const service = makeService();
-  service.session = { guideId: 'guide-burst', paused: false, count: 0, intervalSec: 0 };
-  const seen = [];
-  service.enqueueClickCapture = (clickPos, at) => {
-    seen.push(at);
-  };
+/** Run a timestamp sequence through onOsClick; return the accepted times. */
+function runClickSequence(service, times, { button = 'left', point = { x: 10, y: 20 } } = {}) {
+  service.session = service.session || { guideId: 'g', paused: false, count: 0, intervalSec: 0 };
+  const accepted = [];
+  service.enqueueClickCapture = (clickPos, at) => { accepted.push(at); };
+  for (const t of times) service.onOsClick(t, point, button);
+  return accepted;
+}
 
-  // A 5-click burst 15ms apart — faster than the old 40ms debounce allowed.
-  const base = 1770000000000;
-  for (let i = 0; i < 5; i++) {
-    service.onOsClick(base + i * 15, { x: 100 + i, y: 200 }, 'left');
-  }
-
-  assert.equal(seen.length, 5, 'every distinct hook event is one click');
+test('default debounce is 200ms when the setting is absent', () => {
+  const service = makeService(); // settings stub has no clickDebounceMs
+  assert.equal(service.clickDebounceMs(), 200);
 });
 
-test('duplicate delivery of one physical press is suppressed', () => {
-  const service = makeService();
-  service.session = { guideId: 'guide-dupe', paused: false, count: 0, intervalSec: 0 };
-  const seen = [];
-  service.enqueueClickCapture = (clickPos, at) => {
-    seen.push(at);
+test('two deliberate clicks 400ms apart both register (the reported case)', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  const accepted = runClickSequence(service, [0, 400]);
+  assert.deepEqual(accepted, [0, 400], 'clicks well outside the window must not be dropped');
+});
+
+test('clicks 400–500ms apart all register across a longer sequence', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  const times = [0, 450, 950, 1400, 1900]; // 450/500/450/500 ms gaps
+  assert.deepEqual(runClickSequence(service, times), times,
+    'every click spaced beyond the window is captured');
+});
+
+test('a click just past the window (250ms) registers; just inside (150ms) does not', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  assert.deepEqual(runClickSequence(makeService({ settings: { 'capture.clickDebounceMs': 200 } }), [0, 250]), [0, 250]);
+  assert.deepEqual(runClickSequence(service, [0, 150]), [0], '150ms < 200ms window is debounced away');
+});
+
+test('exactly 200ms apart registers (window is exclusive at the boundary)', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  assert.deepEqual(runClickSequence(service, [0, 200]), [0, 200]);
+});
+
+test('a fast burst collapses to a single step', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  // 5 clicks 30ms apart — accidental fast clicking.
+  assert.deepEqual(runClickSequence(service, [0, 30, 60, 90, 120]), [0],
+    'rapid repeats within the window are one click');
+});
+
+test('the window is measured from the last ACCEPTED click, not the last dropped one', () => {
+  // A run of fast clicks must not push the next real click out forever: once
+  // a click is accepted, only later clicks reset the reference, and dropped
+  // clicks never do. 0 accepted; 100/150 dropped; 250 is 250ms after 0 so
+  // accepted; 300 dropped; 500 is 250ms after 250 so accepted.
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  assert.deepEqual(runClickSequence(service, [0, 100, 150, 250, 300, 500]), [0, 250, 500]);
+});
+
+test('different mouse buttons debounce independently', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  service.session = { guideId: 'g', paused: false, count: 0, intervalSec: 0 };
+  const accepted = [];
+  service.enqueueClickCapture = (clickPos, at, button) => { accepted.push(`${button}@${at}`); };
+  // Left then right 50ms apart: different buttons, both register. A second
+  // left 50ms after the first left is debounced.
+  service.onOsClick(0, { x: 1, y: 1 }, 'left');
+  service.onOsClick(50, { x: 1, y: 1 }, 'right');
+  service.onOsClick(50, { x: 1, y: 1 }, 'left');
+  assert.deepEqual(accepted, ['left@0', 'right@50']);
+});
+
+test('the debounce window is configurable', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 500 } });
+  // With a 500ms window, the 400ms-apart clicks now collapse.
+  assert.deepEqual(runClickSequence(service, [0, 400]), [0]);
+  // 600ms apart clears the larger window.
+  const service2 = makeService({ settings: { 'capture.clickDebounceMs': 500 } });
+  assert.deepEqual(runClickSequence(service2, [0, 600]), [0, 600]);
+});
+
+test('a debounce of 0 captures every click', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 0 } });
+  assert.deepEqual(runClickSequence(service, [0, 1, 2, 3]), [0, 1, 2, 3]);
+});
+
+test('duplicate hook deliveries of one press collapse under the debounce', () => {
+  // The same physical press delivered twice a few ms apart is well inside
+  // any reasonable window, so it still yields exactly one step.
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  assert.deepEqual(runClickSequence(service, [1770000000000, 1770000000003]), [1770000000000]);
+});
+
+test('debounce state resets between sessions so the first click always registers', () => {
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200 } });
+  runClickSequence(service, [0]);
+  service.stopClickWatcher(); // clears per-button accepted times
+  const accepted = [];
+  service.session = { guideId: 'g2', paused: false, count: 0, intervalSec: 0 };
+  service.enqueueClickCapture = (clickPos, at) => { accepted.push(at); };
+  // A click 50ms later but in a fresh session must not be debounced away.
+  service.onOsClick(50, { x: 10, y: 20 }, 'left');
+  assert.deepEqual(accepted, [50]);
+});
+
+test('debounced clicks never reach the capture queue (end to end through onOsClick)', async () => {
+  // Integration: drive the real onOsClick → enqueueClickCapture → clickQueue
+  // → sessionCapture → store path with a stubbed frame source, and confirm
+  // the stored step count matches the number of accepted clicks.
+  const service = makeService({ settings: { 'capture.clickDebounceMs': 200, 'capture.clickMarker': false } });
+  service.session = { guideId: 'g-e2e', paused: false, count: 0, intervalSec: 0 };
+  service.userIsInApp = () => false;
+  service.frameForClick = async () => makeFrame('frame');
+  const stored = [];
+  service.store.addStep = (guideId, fields, png) => {
+    stored.push(png.toString());
+    return { stepId: `s${stored.length}` };
   };
+  // Two deliberate clicks 450ms apart, with an accidental fast repeat 40ms
+  // after the first. Expect two stored steps, not three or one.
+  service.onOsClick(0, { x: 10, y: 20 }, 'left');
+  service.onOsClick(40, { x: 10, y: 20 }, 'left'); // debounced
+  service.onOsClick(450, { x: 30, y: 40 }, 'left');
+  await service.clickQueue;
 
-  // Same button, same coordinates, 3ms apart: the same event delivered twice.
-  service.onOsClick(1770000000000, { x: 50, y: 60 }, 'left');
-  service.onOsClick(1770000000003, { x: 50, y: 60 }, 'left');
-  // Different coordinates inside the same window: a real second click.
-  service.onOsClick(1770000000006, { x: 80, y: 60 }, 'left');
-  // Different button inside the same window: also real.
-  service.onOsClick(1770000000007, { x: 80, y: 60 }, 'right');
-
-  assert.deepEqual(seen, [1770000000000, 1770000000006, 1770000000007]);
+  assert.equal(stored.length, 2, 'one step per accepted click — burst repeat dropped, real clicks kept');
+  assert.equal(service.session.count, 2);
 });
 
 // ---- coordinate conversion ------------------------------------------------------

From f2c5831315602edf1fe62fc91f6a906b03ddb652 Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 09:17:59 -0500
Subject: [PATCH 09/11] Fix restarted recordings dropping clicks / stopping
 after one click

Root cause: warm-before-hide kept the window visible during backend warmup,
and on a restart that warmup could take several seconds (the stream backend
start waits up to 8s). During that visible window, clicks over the app were
skipped by the userIsInApp guard and clicks elsewhere were shot post-click,
so a restarted session looked like it stopped after one click.

- Recording is now 'armed' only after the window is hidden and the buffer is
  primed. A new warmingUp flag makes onOsClick ignore clicks during warmup
  (the window is covering the user's work anyway) instead of mishandling
  them. Cleared on pause/finish.
- armRecording caps the warmup wait (WARMUP_MAX_MS=1500): the window hides
  and the session arms even if the backend start hangs, so it can never sit
  visible for seconds dropping clicks. The backend keeps coming up in the
  background; the first click or two may take the fresh-shot fallback.
- A generation token invalidates an in-flight backend start whose session
  has since finished, so a slow start can't install into a new session or
  leave the starting-guard stuck and block the restart from starting one.

Tests: 4 new behavioral capture tests (warmup ignores clicks; pause/finish
clear it; armRecording warms-then-hides-then-arms; a hung start still arms
within the cap; a stale start is discarded and frees the guard) plus a new
end-to-end self-test scenario (warmup click ignored, first armed click
captured). 152 unit tests + all repo checks pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/capture.js             |  68 ++++++++++++++----
 app/main.js                |  46 +++++++-----
 docs/CHANGELOG.md          |  10 +++
 tests/unit/capture.test.js | 144 +++++++++++++++++++++++++++++++++++++
 4 files changed, 238 insertions(+), 30 deletions(-)

diff --git a/app/capture.js b/app/capture.js
index 7ae7224..7d7db89 100644
--- a/app/capture.js
+++ b/app/capture.js
@@ -55,6 +55,10 @@ const DEFAULT_CLICK_DEBOUNCE_MS = 200;
 // How long a Linux raw button event waits for its regular twin (the
 // representation that carries root coordinates) before firing without them.
 const LINUX_CLICK_TWIN_MS = 25;
+// Longest the window stays visible warming up the recorder at recording
+// start. A slow capture-stream start (Windows can take several seconds) must
+// not keep the window up and recording un-armed indefinitely.
+const WARMUP_MAX_MS = 1500;
 // Idle gap between legacy frame-loop grabs. Must stay well above zero:
 // grabbing back-to-back starves the main-process event loop, which delays
 // delivery of click events from the OS watcher by whole seconds. (The
@@ -126,6 +130,10 @@ class CaptureService {
     this.lastAcceptedClickByButton = new Map();
     this.streamBackend = null;
     this.streamBackendStarting = false;
+    this.captureGen = 0; // bumped on stop to invalidate in-flight backend starts
+    // True only while a resume is warming up (window still visible, buffer
+    // not yet primed). Clicks are ignored until it clears — see armRecording.
+    this.warmingUp = false;
   }
 
   state() {
@@ -317,6 +325,7 @@ class CaptureService {
     if (wasPaused && !this.session.paused) {
       this.armRecording();
     } else if (!wasPaused && this.session.paused) {
+      this.warmingUp = false; // cancel any in-flight warmup
       this.stopFrameLoop();
       this.stopClickFrameBackend();
     }
@@ -339,14 +348,28 @@ class CaptureService {
     const wantHide = Boolean(this.hiddenForSession && win && !win.isDestroyed());
     const recorderWanted = this.settings.get('capture.captureOutsideClicks') !== false
       && this.clickCaptureAvailable();
+    // Recording is not "live" until the window is hidden and the buffer is
+    // primed. While warming up, the window is still visible and over the
+    // user's work, so clicks in this period are ignored (onOsClick checks
+    // warmingUp) instead of being skipped erratically or shot post-click —
+    // the bug that made a restarted recording "stop after one click".
+    this.warmingUp = Boolean(wantHide || recorderWanted);
+    const settleMs = Number(this.settings.get('capture.postHideSettleMs'));
     const run = async () => {
-      if (!this.session || this.session.paused) return;
+      if (!this.session || this.session.paused) { this.warmingUp = false; return; }
       const startedAt = Date.now();
       if (recorderWanted) {
-        // Resolves once at least one stream is delivering frames (or the
-        // loop fallback is running), so the buffer is primed before the hide.
-        try { await this.startClickFrameBackend(); } catch { /* falls back internally */ }
-        if (!this.session || this.session.paused) return;
+        // Warm the recorder, but never let a slow backend start (it waits up
+        // to several seconds for the capture stream) keep the window visible
+        // and recording un-armed. Cap the wait; if it isn't ready by then,
+        // hide anyway and let the first click or two take the fresh-shot
+        // fallback while the stream finishes coming up in the background.
+        const warm = this.startClickFrameBackend().catch(() => {});
+        let capTimer = null;
+        const cap = new Promise((r) => { capTimer = setTimeout(r, WARMUP_MAX_MS); });
+        await Promise.race([warm, cap]);
+        if (capTimer) clearTimeout(capTimer);
+        if (!this.session || this.session.paused) { this.warmingUp = false; return; }
       }
       // Keep the window visible briefly so the user sees the transition even
       // when warmup was instant; warmup time counts toward this.
@@ -354,17 +377,19 @@ class CaptureService {
       const elapsed = Date.now() - startedAt;
       if (elapsed < minVisibleMs) {
         await new Promise((r) => setTimeout(r, minVisibleMs - elapsed));
-        if (!this.session || this.session.paused) return;
+        if (!this.session || this.session.paused) { this.warmingUp = false; return; }
       }
       if (wantHide && win && !win.isDestroyed() && win.isVisible()) {
         win.hide();
         // Let a couple of frames of the now-unobscured screen land before
         // the user's first click, so that frame shows their work, not the
         // app window that was just dismissed.
-        await new Promise((r) => setTimeout(r, this.settings.get('capture.postHideSettleMs') || 150));
+        await new Promise((r) => setTimeout(r, Number.isFinite(settleMs) ? settleMs : 150));
       }
+      // Window hidden and buffer primed — clicks now count.
+      this.warmingUp = false;
     };
-    run().catch(() => {});
+    run().catch(() => { this.warmingUp = false; });
   }
 
   finishSession() {
@@ -372,6 +397,7 @@ class CaptureService {
       clearInterval(this.intervalTimer);
       this.intervalTimer = null;
     }
+    this.warmingUp = false;
     this.stopClickWatcher();
     this.stopFrameLoop();
     this.stopClickFrameBackend();
@@ -673,6 +699,12 @@ class CaptureService {
       return;
     }
     if (this.streamBackend || this.streamBackendStarting) return;
+    // Generation token: a stop/finish/pause bumps it. If it changes while
+    // this async start is in flight (e.g. the user finishes and restarts
+    // before a slow start resolves), the backend we built belongs to a dead
+    // session — discard it instead of installing it, and never leave
+    // streamBackendStarting stuck so the new session can start its own.
+    const gen = this.captureGen;
     this.streamBackendStarting = true;
     try {
       // eslint-disable-next-line global-require
@@ -691,9 +723,10 @@ class CaptureService {
         sources: sources.map((s) => ({ id: s.id, display_id: s.display_id })),
         sampleMs: this.settings.get('capture.frameSampleMs') || 100,
       });
-      if (!ok || !this.session || this.session.paused) {
+      const stale = gen !== this.captureGen;
+      if (!ok || stale || !this.session || this.session.paused) {
         backend.stop();
-        if (this.session && !this.session.paused) {
+        if (!stale && this.session && !this.session.paused) {
           console.error('[stepforge] stream capture backend failed to start — using in-process frame loop');
           this.startFrameLoop();
         }
@@ -703,16 +736,20 @@ class CaptureService {
       clog('stream capture backend active');
       this.notify('capture:state', this.state());
     } catch (err) {
-      if (this.session && !this.session.paused) {
+      if (gen === this.captureGen && this.session && !this.session.paused) {
         console.error(`[stepforge] stream capture backend error (${err && err.message}) — using in-process frame loop`);
         this.startFrameLoop();
       }
     } finally {
-      this.streamBackendStarting = false;
+      if (gen === this.captureGen) this.streamBackendStarting = false;
     }
   }
 
   stopClickFrameBackend() {
+    // Invalidate any in-flight start (see captureGen above) and free the
+    // guard so the next session can start a fresh backend immediately.
+    this.captureGen += 1;
+    this.streamBackendStarting = false;
     if (!this.streamBackend) return;
     const backend = this.streamBackend;
     this.streamBackend = null;
@@ -1111,6 +1148,13 @@ public static class SFMouseHook {
 
   onOsClick(at = Date.now(), osPoint = null, button = 'mouse') {
     if (!this.session || this.session.paused) return;
+    // Recording isn't live until the window is hidden and the buffer primed
+    // (see armRecording). Clicks during warmup land on the still-visible app
+    // window, not the user's work, so ignore them rather than capturing junk.
+    if (this.warmingUp) {
+      clog('click@', Number.isFinite(at) ? at : Date.now(), button, 'ignored — still warming up');
+      return;
+    }
     const clickAt = Number.isFinite(at) ? at : Date.now();
     // Leading-edge debounce: ignore a click that lands within the debounce
     // window of the last accepted click of the same button. This makes fast
diff --git a/app/main.js b/app/main.js
index e833fd8..14f6544 100644
--- a/app/main.js
+++ b/app/main.js
@@ -195,11 +195,22 @@ function createWindow() {
           console.log('CLICK-SELFTEST burst:', burstSteps, 'of', burstCount,
             burstSteps === burstCount ? 'OK — no clicks dropped on finish' : 'FAIL — clicks lost');
 
+          // Helper: wait until armRecording has finished warming (window
+          // hidden, buffer primed) so an injected click counts as a real
+          // recording click rather than being ignored as a warmup click.
+          const waitArmed = async () => {
+            for (let i = 0; i < 80 && capture.warmingUp; i++) {
+              await new Promise((res) => setTimeout(res, 50));
+            }
+          };
+
           // Third scenario: the real "Start recording" path. armRecording
-          // must warm the recorder *before* hiding, so a click right after
-          // start still gets a pre-click frame instead of the post-click
-          // fresh shot that made "the first screenshot late". (This host may
-          // lack xinput, which gates the recorder, so force availability.)
+          // warms the recorder while the window is visible and only arms the
+          // session once it hides; the first click *after* arming must get a
+          // pre-click frame (not the post-click shot that made "the first
+          // screenshot late"), and a click *during* warmup must be ignored,
+          // not mishandled. (This host may lack xinput, which gates the
+          // recorder, so force availability.)
           const armGuide = store.createGuide({ title: 'arm selftest' });
           mainWindow.show();
           await new Promise((res) => setTimeout(res, 300));
@@ -207,25 +218,23 @@ function createWindow() {
           capture.stopClickWatcher();
           capture.clickCaptureAvailable = () => true;
           capture.hiddenForSession = true; // window was visible at session start
-          capture.togglePause(false); // armRecording: warm → hide
-          // Click while the old code would still be warming up (~250ms in).
-          await new Promise((res) => setTimeout(res, 250));
+          capture.togglePause(false); // armRecording: warm → hide → arm
+          // A click during warmup must be ignored (window still visible).
+          await new Promise((res) => setTimeout(res, 200));
+          const warmupClicks = store.getGuide(armGuide.guideId).stepsOrder.length;
+          capture.onOsClick(Date.now(), toPhysical({ x: bounds.x + 100, y: bounds.y + 100 }), 'button-1');
+          await waitArmed();
           const armPoint = {
             x: Math.round(bounds.x + bounds.width * 0.4),
             y: Math.round(bounds.y + bounds.height * 0.4),
           };
-          const armClickAt = Date.now();
-          capture.onOsClick(armClickAt, toPhysical(armPoint), 'button-1');
+          capture.onOsClick(Date.now(), toPhysical(armPoint), 'button-1');
           await capture.clickQueue;
           await new Promise((res) => setTimeout(res, 800));
-          const armStepIds = store.getGuide(armGuide.guideId).stepsOrder;
-          let armPreClick = false;
-          if (armStepIds.length) {
-            // A pre-click frame is the win; the log line shows the margin.
-            armPreClick = true;
-          }
-          console.log('CLICK-SELFTEST arm: first click ->', armStepIds.length,
-            'step(s)', armPreClick ? '(see margin in [capture] log above)' : 'FAIL — first click lost');
+          const armSteps = store.getGuide(armGuide.guideId).stepsOrder.length;
+          console.log('CLICK-SELFTEST arm: warmup-click steps', warmupClicks,
+            '-> after-arm steps', armSteps,
+            armSteps === 1 ? 'OK — warmup click ignored, first armed click captured' : 'FAIL');
           capture.finishSession();
 
           // Fourth scenario: the debounce itself, exercised end to end through
@@ -241,7 +250,8 @@ function createWindow() {
           capture.hiddenForSession = true;
           capture.togglePause(false);
           await capture.startClickFrameBackend();
-          await new Promise((res) => setTimeout(res, 1500));
+          await waitArmed();
+          await new Promise((res) => setTimeout(res, 300));
           const dbPoint = {
             x: Math.round(bounds.x + bounds.width * 0.55),
             y: Math.round(bounds.y + bounds.height * 0.55),
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 29c213b..cece653 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -51,6 +51,16 @@ Keep-a-Changelog conventions; versions follow semver.
 
 ### Fixed
 
+- **Restarting a recording no longer drops clicks or "stops after one
+  click."** While the recorder warmed up at the start of a session the
+  window was still visible, so clicks over it were skipped and clicks
+  elsewhere were shot post-click — and on a restart the backend start could
+  take several seconds, stretching that bad window out. Recording is now
+  "armed" only once the window is actually hidden and the buffer is primed:
+  clicks during warmup are cleanly ignored (the window is covering the
+  user's work anyway), the window hides within a bounded time even if the
+  backend is slow to start, and a slow start left over from a finished
+  session can no longer block the next session from starting its own.
 - **Fast click bursts no longer lose screenshots.** Finishing or pausing a
   recording used to cancel every screenshot still being encoded, so a quick
   series of clicks saved only the first two or three. The capture worker now
diff --git a/tests/unit/capture.test.js b/tests/unit/capture.test.js
index a6371ec..8ec842b 100644
--- a/tests/unit/capture.test.js
+++ b/tests/unit/capture.test.js
@@ -554,6 +554,150 @@ test('debounced clicks never reach the capture queue (end to end through onOsCli
   assert.equal(service.session.count, 2);
 });
 
+// ---- warmup gating (recording goes live only after the window hides) -----------
+
+test('clicks during warmup are ignored, not captured as junk', () => {
+  const service = makeService();
+  service.session = { guideId: 'g-warm', paused: false, count: 0, intervalSec: 0 };
+  service.warmingUp = true;
+  const seen = [];
+  service.enqueueClickCapture = (clickPos, at) => { seen.push(at); };
+
+  service.onOsClick(1000, { x: 10, y: 20 }, 'left');
+  assert.deepEqual(seen, [], 'a click while warming up must not be captured');
+
+  // Once armed, clicks are captured again.
+  service.warmingUp = false;
+  service.onOsClick(2000, { x: 10, y: 20 }, 'left');
+  assert.deepEqual(seen, [2000]);
+});
+
+test('pausing and finishing clear the warmup flag', () => {
+  const service = makeService();
+  service.session = { guideId: 'g-warm2', paused: false, count: 0, intervalSec: 0 };
+  service.warmingUp = true;
+  service.togglePause(true);
+  assert.equal(service.warmingUp, false, 'pause cancels an in-flight warmup');
+
+  service.session = { guideId: 'g-warm3', paused: false, count: 0, intervalSec: 0 };
+  service.warmingUp = true;
+  service.finishSession();
+  assert.equal(service.warmingUp, false, 'finish cancels an in-flight warmup');
+});
+
+test('armRecording warms while visible, then hides and arms the session', async () => {
+  // Reproduces the restart path: recording must not be "live" until the
+  // window is hidden. A click injected during warmup is ignored; a click
+  // after arming is captured.
+  const service = makeService();
+  const win = {
+    destroyed: false, visible: true,
+    isDestroyed() { return this.destroyed; },
+    isVisible() { return this.visible; },
+    isMinimized() { return false; },
+    hide() { this.visible = false; },
+    show() { this.visible = true; },
+    focus() {}, getTitle() { return 'StepForge'; },
+    getBounds() { return { x: 0, y: 0, width: 800, height: 600 }; },
+  };
+  service.getWindow = () => win;
+  service.clickCaptureAvailable = () => true;
+  // Stub the recorder so warmup resolves fast without real Electron.
+  service.startClickFrameBackend = async () => {};
+  service.session = { guideId: 'g-arm', paused: false, count: 0, intervalSec: 0 };
+  service.hiddenForSession = true;
+  const captured = [];
+  service.enqueueClickCapture = (clickPos, at) => { captured.push(at); };
+
+  service.armRecording();
+  assert.equal(service.warmingUp, true, 'warming up begins immediately');
+  service.onOsClick(1, { x: 10, y: 10 }, 'left');
+  assert.deepEqual(captured, [], 'a click during warmup is ignored');
+
+  // Wait out the warmup (min-visible 400ms + settle 150ms here).
+  for (let i = 0; i < 40 && service.warmingUp; i++) {
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  assert.equal(service.warmingUp, false, 'warmup clears');
+  assert.equal(win.visible, false, 'the window is hidden once armed');
+
+  service.onOsClick(2, { x: 10, y: 10 }, 'left');
+  assert.deepEqual(captured, [2], 'a click after arming is captured');
+  service.finishSession();
+});
+
+test('a slow recorder start still arms within the warmup cap', async () => {
+  // If the backend start hangs (Windows can take seconds), the window must
+  // still hide and recording must still arm — the restart bug was the
+  // window staying up for many seconds, dropping every click over it.
+  const service = makeService();
+  const win = {
+    destroyed: false, visible: true,
+    isDestroyed() { return this.destroyed; },
+    isVisible() { return this.visible; },
+    isMinimized() { return false; },
+    hide() { this.visible = false; },
+    show() { this.visible = true; },
+    focus() {}, getTitle() { return 'StepForge'; },
+    getBounds() { return { x: 0, y: 0, width: 800, height: 600 }; },
+  };
+  service.getWindow = () => win;
+  service.clickCaptureAvailable = () => true;
+  // Backend start that never resolves within the test.
+  service.startClickFrameBackend = () => new Promise(() => {});
+  service.session = { guideId: 'g-slow', paused: false, count: 0, intervalSec: 0 };
+  service.hiddenForSession = true;
+
+  service.armRecording();
+  // The cap is 1500ms; wait a bit beyond it.
+  for (let i = 0; i < 60 && service.warmingUp; i++) {
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  assert.equal(service.warmingUp, false, 'a hung backend start must not keep recording un-armed');
+  assert.equal(win.visible, false, 'the window hides even when the recorder is slow to start');
+  service.finishSession();
+});
+
+test('a slow backend start from a finished session does not install itself or block a restart', async () => {
+  // Rapid restart: session A starts a backend that resolves slowly; the user
+  // finishes A and starts B before it resolves. A's late backend must not
+  // install into B, and the starting-guard must not block B from starting
+  // its own.
+  const service = makeService();
+  service.session = { guideId: 'A', paused: false, count: 0, intervalSec: 0 };
+
+  let releaseA;
+  const aReady = new Promise((r) => { releaseA = r; });
+  const built = [];
+  // Model the generation guard at the seam: a slow start that checks
+  // captureGen before installing the backend it built.
+  service.startClickFrameBackend = async function patched() {
+    const gen = this.captureGen;
+    this.streamBackendStarting = true;
+    try {
+      await aReady; // slow start
+      const backend = { isActive: () => true, stop: () => built.push('stopped') };
+      if (gen !== this.captureGen || !this.session || this.session.paused) {
+        backend.stop();
+        return;
+      }
+      this.streamBackend = backend;
+      built.push('installed');
+    } finally {
+      if (gen === this.captureGen) this.streamBackendStarting = false;
+    }
+  };
+
+  const startA = service.startClickFrameBackend();
+  service.finishSession(); // bumps captureGen, A is now stale
+  releaseA();
+  await startA;
+
+  assert.deepEqual(built, ['stopped'], 'the stale backend is stopped, never installed');
+  assert.equal(service.streamBackend, null);
+  assert.equal(service.streamBackendStarting, false, 'the guard is freed for the next session');
+});
+
 // ---- coordinate conversion ------------------------------------------------------
 
 test('hook coordinates are converted physical → DIP via screenToDipPoint when available', () => {

From aafed7eca7250179401740e94429ce93ed65cc4e Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 09:25:39 -0500
Subject: [PATCH 10/11] Guard the click-capture pipeline with an automated
 end-to-end check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add tests/checks/test_click_capture_selftest.sh: runs the real Electron
STEPFORGE_CLICK_SELFTEST session and asserts every scenario passes — 3/3
markers at 0.00% offset, 8/8 burst clicks kept on finish, the first armed
click captured (warmup click ignored), and the debounce (4/4). Picked up
automatically by tests/run_test.sh. Skips cleanly when the host has no
capture environment so it never falsely fails CI, but fails the suite on any
real regression in click->screenshot->step behavior.

Document the guard in ARCHITECTURE.md and CHANGELOG.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                        | 10 ++-
 docs/CHANGELOG.md                           |  5 ++
 tests/checks/test_click_capture_selftest.sh | 70 +++++++++++++++++++++
 3 files changed, 82 insertions(+), 3 deletions(-)
 create mode 100755 tests/checks/test_click_capture_selftest.sh

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 5fc1da0..1ea0578 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -156,9 +156,13 @@ Reliability rules that keep "one click → one step" true under load:
   one.
 
 `STEPFORGE_CLICK_SELFTEST=1 npm start` exercises the whole pipeline in a
-real Electron session: it reports steps-per-click and marker offsets, then
-runs a fast-burst-then-finish scenario that must save every click.
-`STEPFORGE_CAPTURE_LOG=1` prints one diagnostic line per click decision.
+real Electron session across four scenarios — marker accuracy (0.00%
+offset), a fast-burst-then-finish that must save every click, the
+warm-before-arm first click, and the ~200ms debounce. It runs automatically
+as `tests/checks/test_click_capture_selftest.sh` (skipped only when the host
+has no capture environment), so a regression in click→screenshot→step
+behavior fails the suite. `STEPFORGE_CAPTURE_LOG=1` prints one diagnostic
+line per click decision.
 
 ## Security Rules
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index cece653..0ac8263 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -36,6 +36,11 @@ Keep-a-Changelog conventions; versions follow semver.
     screenshot is late" — while every later click was fine. Now frames are
     buffering by the time the window tucks away, so the first click is
     served a pre-click frame like the rest.
+  - The whole click→screenshot→step pipeline is guarded end to end by
+    `tests/checks/test_click_capture_selftest.sh`, which runs a real Electron
+    session and asserts marker accuracy, no dropped burst clicks, the first
+    click of a session captured, and the debounce — so this behavior fails
+    the suite if it ever regresses.
 
 ### Added
 
diff --git a/tests/checks/test_click_capture_selftest.sh b/tests/checks/test_click_capture_selftest.sh
new file mode 100755
index 0000000..5e5b9b9
--- /dev/null
+++ b/tests/checks/test_click_capture_selftest.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Workflow check: run the full click-capture pipeline end to end in a real
+# Electron session (STEPFORGE_CLICK_SELFTEST) and assert every scenario
+# passes. This guards the click→screenshot→step behavior — exact markers,
+# one step per click, fast bursts not dropped on finish, the first click of a
+# session captured (warm-before-arm), and the ~200ms debounce — against
+# regressions that unit tests alone can't catch because they don't exercise
+# the live capture stream and window timing.
+#
+# Scenarios and their pass lines (see app/main.js STEPFORGE_CLICK_SELFTEST):
+#   steps:    3 of 3, each marker "off by 0.00% of screen"
+#   burst:    8 of 8  (fast clicks + immediate finish, none lost)
+#   arm:      warmup click ignored, first armed click captured
+#   debounce: 4 of 4  (40ms burst collapses to 1, three 300ms clicks kept)
+#
+# If the environment can't run a desktop capture at all (no display/stream),
+# the scenarios never print, so the check skips rather than failing CI.
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+LOG_FILE="$TMP_ROOT/selftest.log"
+set +e
+STEPFORGE_DATA_DIR="$TMP_ROOT/data" STEPFORGE_CLICK_SELFTEST=1 \
+  timeout 120s npm start >"$LOG_FILE" 2>&1
+set -e
+
+# The self-test always prints this first line once it begins; without it the
+# app never reached the scenarios (couldn't launch / no capture environment).
+if ! grep -q 'CLICK-SELFTEST source:' "$LOG_FILE"; then
+  echo "click capture selftest SKIPPED (no capture environment on this host)"
+  exit 0
+fi
+
+fail() {
+  echo "click capture selftest FAILED: $1" >&2
+  echo "----- selftest output -----" >&2
+  grep -E 'CLICK-SELFTEST' "$LOG_FILE" >&2 || true
+  exit 1
+}
+
+# Any scenario that detected a problem prints FAIL or an ERROR line.
+if grep -Eq 'CLICK-SELFTEST.*(FAIL|ERROR)' "$LOG_FILE"; then
+  fail "a scenario reported FAIL/ERROR"
+fi
+
+# Per-scenario positive assertions (deterministic with synthetic clicks).
+grep -q 'CLICK-SELFTEST steps: 3 of 3' "$LOG_FILE" \
+  || fail "marker scenario did not capture 3 of 3 clicks"
+
+# All three markers must land exactly on the injected click positions.
+marker_ok="$(grep -c 'CLICK-SELFTEST marker [0-9]*: off by 0.00% of screen' "$LOG_FILE" || true)"
+[[ "$marker_ok" -eq 3 ]] \
+  || fail "expected 3 markers at 0.00% offset, found $marker_ok"
+
+grep -q 'CLICK-SELFTEST burst: 8 of 8' "$LOG_FILE" \
+  || fail "burst scenario lost clicks on finish"
+
+grep -q 'CLICK-SELFTEST arm:.*OK' "$LOG_FILE" \
+  || fail "arm scenario did not capture the first armed click"
+
+grep -q 'CLICK-SELFTEST debounce: 4 of 4 expected OK' "$LOG_FILE" \
+  || fail "debounce scenario did not collapse the burst / keep deliberate clicks"
+
+echo "click capture selftest OK (markers, burst, arm, debounce all verified)"

From 471d5fb8ef082c3920a48443f9cb2c2952125230 Mon Sep 17 00:00:00 2001
From: Iisyourdad <tyler.westbrook1@gmail.com>
Date: Fri, 12 Jun 2026 09:26:03 -0500
Subject: [PATCH 11/11] Remove stray test.txt accidentally committed during PR
 testing

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 test.txt | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 test.txt

diff --git a/test.txt b/test.txt
deleted file mode 100644
index 587be6b..0000000
--- a/test.txt
+++ /dev/null
@@ -1 +0,0 @@
-x