feat(sweep): the drag-select box drawn natively at Explorer's latency (#338)

[Maxaubert]

Closes #338.

On Windows 11 the drag-select box (the sweep) is drawn by DirectComposition on Prism's own window, from the real cursor, every compositor frame, as File Explorer draws its box. Today's DOM box is the automatic fallback everywhere else. Spec and plan: docs/superpowers/specs/2026-10-09-native-sweep-overlay-design.md and docs/superpowers/plans/2026-10-09-native-sweep-overlay.md. Measurements: research/prism/2026-10-09-native-sweep-spike.md.

What changed

• native/sweep/: Prism's own N-API addon (C++, /MT, /W4 /WX). It runs one native thread, one D3D11 + DComp device and one topmost DComp target per window. The thread samples the cursor late in the frame, 1000 us before the next compositor tick. A commit that lands under 100 us before the tick counts as a miss; more than 14 misses in 1440 up-frames widens the lead by 250 us, up to 2000 us, after which it samples at the tick. Anchor delays: K auto 2, wheel 0, resize 2. The thread never calls into JS. selfTest() covers the box math.

• tools/build-sweep.mjs (npm run build:sweep, part of package, CI and release):

  • runs node-gyp against the Node that Electron embeds;
  • fails if dumpbin /dependents lists anything other than KERNEL32, USER32, d3d11, dxgi, dcomp or node.exe;
  • runs the self-test in plain Node.

• src/main/sweepOverlay.ts decides, per window, whether the box is drawn natively, and forwards the page's messages validated and in physical pixels. The fallback has no setting and switches on when:

  • the addon is missing or fails to load;
  • the compositor clock is missing (Windows 10);
  • the session is Remote Desktop;
  • the run is --e2e or uses --sweep-overlay=off;
  • a target or an HRESULT fails;
  • the thread stops moving (500 ms watchdog).

  Main also ends the box itself on blur, minimize, hide, close, a dead page and a new document. The addon loads 400 ms after the first window's first load, so nothing is added to the startup path.

• useSweep: a MOUSE sweep sends begin / update (with its cause) / end. The anchor goes through each list's new fromList option (the inverse of toList), the clip is the scroller's exact visible rect, and the colours are the band's own computed colours. Nothing is sent per pointer move. A pen sweep keeps the DOM box. The band stays mounted and placed, and is display: none only while main has said native: true.

• The spike's driver is removed (sweepSpike.ts, measure.mjs, spike-checks.mjs). tools/sweep-latency/addon-check.mjs is the offscreen check for the product addon.

• Version 0.100.0. In docs/features.md (where docs: split CLAUDE.md into docs/features.md and docs/ui-direction.md #339 moved it from CLAUDE.md), the native box rule replaces "the rest of the trail is Chromium's, and was left"; CLAUDE.md's native-module line and docs/build-and-conventions.md name the addon and node-gyp.

Numbers (spike gate, injected sweeps, 1x)

	Lag median (frames)	p95
Native, late 1000 us	0.26 to 0.31 at every speed (300 to 4000 CSS px/s)	0.35 to 0.44
File Explorer, same motion	0.72 to 0.86
DOM box (today)	1.06
Native sampled at the tick	1.15

• Steady SD: native 0.05 to 0.11; Explorer 0.35 to 2.0.
• Frames shown a frame late: 0.14 to 0.47 %. The adaptive run stayed at 1000 us with 0 widenings.
• Box gone after release: median 0 frames, max 1.
• Origin: 0 px, normal and maximised.
• Owner by eye, under Wind: 1500 us was "not quite there"; 1000 us "seems like it works".
• Offscreen check, product addon: 50 of 50 quits with a box up exited 0. 0 failed joins in 5,000 start-stops, 0 idle wakeups. A second window attaches and detaches.

Gate (this PR)

• npm run typecheck, npm run lint (0 errors), npm test: 2700 passed.

• npm run build:sweep: imports KERNEL32, d3d11, dcomp, USER32, node.exe; self-test passed.

• e2e, one process at a time: bigTree, treeNav, selection, marquee, marqueeQuiet, marqueeEdge, sweepLag, sweepOverlay (new) and treeVerbs all passed, and startup stayed under 800 ms (median 663). sweepOverlay was proved against a build with end taken out of hide(): it failed, then passed.

• npm run package built Prism-Setup-x64-0.100.0.exe with resources\sweep\prism_sweep.node. The unpacked build on a scratch profile logged sweep-overlay native: true, window: 0 and exited 0. Not installed.

• CI is green (check, bundled-indexer, gate). check built and self-tested the addon on windows-latest (build 26100, Node 22 host). binding.gyp defaults enable_thin_lto, which Node 24's common.gypi needs and a Node 22 host does not define.

Unsigned: the .node is a PE file and ships unsigned like the rest of the app. It must join the SignPath signing set when Prism is enrolled.

Hands-on list (installed build)

• Fast sweeps, unzoomed and zoomed in Wind (both the transform and the render engine).
• Auto-scroll down and up.
• A wheel turn under a held button: the anchored edge stays on its row.
• Escape mid-sweep; Alt+Tab and Win+D mid-sweep; a release outside the window.
• A second monitor at another scale, with the window dragged across.
• Acrylic on and off, mica, maximised and fullscreen, and a live material switch. These were not measured in the spike.
• A light theme, a dark theme and a picked accent.
• The tree and the Explorer; two Prism windows; quit with a box up.
• The marks following the box on a fast sweep, zoomed in.
• A toast or tooltip over the list mid-sweep (it is now under the box); square corners.

Owner's calls

• Windows 10 keeps today's DOM box (there is no compositor clock).
• The marks now trail the box by Chromium's frames. This is the inverse of today. The marks that stand at the release are still the box's.
• Spec gate wording: criterion 1 now compares against Explorer's median, as asked. Criterion 2 was changed on the measuring agent's own initiative: "at least 1 frame below the DOM box" became "below the DOM box's median", because the DOM box measures 1.06 frames and the old bar could not be met. Please confirm.
• CPU while a box is up: 0.95 to 1.15 % of a core in the spike, which included per-frame logging that this PR removes. This is borderline against "under 1 %".

Found, not changed

The Explorer's list is a controlled scroll. During auto-scroll it writes the previous step back a beat later, so the list steps back one step between ticks. This is not new. The DOM box and the native anchor both follow it. It is recorded in the research file.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t