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

@@ -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.

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,

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,
     });

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,
       });
     });
   }