feat(move): make the borderless window movable — right-drag, Alt+arrow nudge, explicit x/y

[h4x0r]

The problem

Borderless mode builds new BrowserWindow({ frame: false }) and loads an arbitrary remote page straight into it. There is no OS frame, and the drag handle that makes the normal window movable lives in our electron/toolbar.html (-webkit-app-region: drag), which borderless deliberately never loads. Nothing set x/y either. So the window was nailed wherever Electron first put it.

The usual Electron answer — app-region: drag in the page's CSS — is unavailable by construction: the page belongs to someone else, and editing it would alter the thing being filmed. Electron's own frameless-window docs don't cover the third-party-page case.

The fix

Move the decision out of the renderer and into the main process, which sees input before Chromium dispatches it to the page and can cancel it. Three ways to move, all live in both modes and inert in fullscreen/kiosk:

Gesture	Effect
Right-drag	pick the window up anywhere on it
Escape mid-drag	drop it back where the drag started
Alt + arrow	nudge 1 px
Alt + Shift + arrow	nudge 10 px

Plus explicit placement for repeatability across takes: X/Y, --x/--y, or x/y in a scene file. Signed, so a display left of or above the primary is reachable; the pair is all-or-nothing, and an incomplete pair falls back to the OS's placement.

The page never receives the grab, never scrolls on our arrow keys, and is never modified.

Why the right button and not Alt+drag

Alt+drag was the intended design and it does not work. Electron 43 emits no modifiers field on before-mouse-event or input-event — measured on 43.3.0, an Alt+click payload is byte-identical to a plain one:

BEFORE-MOUSE {"type":"mouseDown","clickCount":1,"button":"left","globalX":500,"globalY":400,"x":300,"y":200}   # plain
BEFORE-MOUSE {"type":"mouseDown","clickCount":1,"button":"left","globalX":500,"globalY":400,"x":300,"y":200}   # Alt held

modifiers is on the MouseInputEvent structure because that type is also the input to webContents.sendInputEvent; being accepted going in is not being populated coming out. button is reported reliably (left/right/none), so the button is the discriminator and the left button stays entirely the page's. The keyboard channel is unaffected — before-input-event carries real alt/shift, which is why the nudges work to the pixel.

Drag mechanics

The window keeps the grabbed point under the cursor, so the cursor cannot leave the window mid-drag and the ending mouse-up is always delivered — even though the page never received the mouse-down and so never took pointer capture. Position is driven by polling screen.getCursorScreenPoint() at ~60 Hz rather than by mouse-move payloads, and the drag is torn down on mouse-up, window blur, close, or Escape.

Verification

TDD, RED then GREEN as separate commits. Decisions live in src/move.js under the existing 100% coverage gate; electron/main.js stays a Humble Object that only wires them. 122 tests, 100% lines/branches/functions/statements, eslint and prettier clean.

Unit tests are mine, so they are not independent. Verified separately on both platforms by synthesizing real input and reading the resulting window position back from the OS — neither the stimulus nor the measurement produced by this code.

macOS (Quartz CGEvent into the HID tap; measured by CGWindowListCopyWindowInfo), run against both borderless and framed builds:

start x=320 y=180 w=1440 h=900
ok   plain left drag leaves it put: got (320, 180), expected (320, 180)
ok   right drag moves by the cursor delta: got (460, 270), expected (460, 270)
ok   window stops following after mouse-up: got (460, 270), expected (460, 270)
ok   alt+right nudges 1px: got (461, 270), expected (461, 270)
ok   alt+shift+down nudges 10px: got (461, 280), expected (461, 280)
VERDICT: PASS

Windows 11 ARM64 (build 26200) in a Parallels VM, against Electron 43.3.0 win32-arm64, cloning this branch — mouse_event/keybd_event measured by DwmGetWindowAttribute(DWMWA_EXTENDED_FRAME_BOUNDS):

ok   plain left drag leaves it put: got 312,180, expected 312,180
ok   right drag moves by the cursor delta: got 452,270, expected 452,270
ok   window stops following after mouse-up: got 452,270, expected 452,270
ok   alt+right nudges 1 DIP: got 453,270, expected 453,270
ok   alt+shift+down nudges 10 DIP: got 453,280, expected 453,280

requested (320,180) -> visible (319,180) size 802x501
requested (100, 50) -> visible ( 99, 50) size 802x501
delta measured (220,130) expected (220,130) -> ok
VERDICT: PASS

The plain-left-drag line is the positive control: it proves the harness can tell "the gesture worked" from "any drag moves it". It is what caught the original Alt+drag implementation, which passed every unit test and moved nothing.

Two Windows measurement traps found on the way, neither a defect in this change: GetWindowRect counts the invisible resize border (~8 px per side) and so disagrees with the visible frame — DWMWA_EXTENDED_FRAME_BOUNDS is the right call; and Windows clamps a window taller than the monitor work area, so an oversized HEIGHT comes back smaller than requested.

Still not verified

• Linux. On Wayland setPosition and getCursorScreenPoint are documented non-functional, so placement and drag will not work there (X11 should be fine); most Linux WMs already offer Super/Alt+drag.
• Non-100% display scaling. Both test machines reported scale 1.0. Coordinates are DIP, so at 125%/150% DIP-to-physical rounding may shift exact placement by a pixel.

Separate pre-existing bug, not fixed here

src/scene.js omits borderless from BOOL_FIELDS, so "borderless": true in a scene file is silently stripped — despite src/config.js documenting "same env-over-scene-over-default precedence as kiosk". Left alone to keep this diff to the ask; worth a one-line follow-up.

🤖 Generated with Claude Code