Desktop: add a macOS-style display scale chooser so smaller screens fit more

[jaylfc]

What

A display scale chooser in Settings, like macOS Displays > Scaled, so smaller screens can fit more on screen. Discrete steps rather than a free slider, previewed the way macOS does it ("Larger Text ... More Space").

Requested by Jay.

Why it fits cleanly

theme-store.ts already establishes the exact pattern this needs: localStorage persistence plus document.documentElement.style.setProperty for CSS custom properties, applied at the root. A scale setting is the same shape, so it should mirror that store rather than invent a mechanism.

There is currently no UI scale handling anywhere in desktop/src (no zoom, no root font-size scaling, no density setting), so this is greenfield rather than a refactor.

Proposed approach

Root-level CSS zoom on :root, driven by a persisted uiScale value, with discrete steps (for example 0.8 / 0.9 / 1.0 / 1.1 / 1.25) surfaced in Settings next to Themes.

zoom is preferred over transform: scale() because transform breaks fixed positioning and pointer hit-testing, which a windowing UI depends on heavily.

The real risks, all found by reading the code

These are the reason this is not a one-line change.

1. 27 viewport reads across 18 files would desync. window.innerWidth / window.innerHeight are the layout viewport and are NOT affected by CSS zoom, while layout and CSS media queries ARE. Window.tsx:50-51 derives its bounds from exactly these. Every one of those reads needs to go through a single useEffectiveViewport() helper that divides by the active scale, or window clamping, maximize and snap maths will be wrong at any scale other than 1.0.

2. JS breakpoints and CSS breakpoints would diverge. use-is-mobile.ts and use-device-mode.ts decide mobile vs desktop from window.innerWidth in JS, while CSS media queries evaluate against the zoomed viewport. Under zoom those two disagree, so the OS could style itself as mobile while behaving as desktop, or scaling down could trip the mobile breakpoint and switch the whole shell unexpectedly. This needs one deliberate decision, recorded: does scaling affect the device-mode breakpoint or not? My view is it should NOT (scale is an appearance preference, device mode is a form-factor fact), which means device-mode reads must stay on the true viewport while layout reads use the effective one.

3. Agent desktop control reads bounds. use-desktop-control.ts is how an agent reads screen geometry and drives windows. If it reports unscaled bounds while windows are laid out scaled, agent-driven window placement lands in the wrong place. Whatever coordinate space is chosen has to be the one the control API reports, and the agent manual needs updating to say which.

Acceptance

• Discrete scale steps in Settings, persisted, applied at root, surviving reload
• Single source of truth for the effective viewport; the 27 raw reads go through it
• Device-mode detection explicitly decided and tested at the smallest and largest scale
• use-desktop-control.ts reports coordinates in the documented space, agent manual updated
• Keyboard accessible with proper labels, and the current value announced (per the project accessibility rule)
• Verified by booting the real desktop and screenshotting at the smallest and largest scale, not by unit tests alone

Not in scope

Per-display scaling, fractional/free slider, and remembering scale per device.

[jaylfc]

Progress + a finding that changes the approach

Branch feat/display-scale-chooser, commit eec85b96. Not ready to ship, and the reason is worth recording in full because it invalidates the obvious implementation.

Done and verified

• display-store.ts — discrete steps, localStorage, per device, never per account (Jay). Clamps unparseable / zero / negative / out-of-range values rather than rendering a collapsed desktop.
• DisplayScaleCard.tsx — native radios in a fieldset (so arrow-key nav, roving focus and the checked announcement are the platform's, not ours), 3-across on phones and 5-across from sm up.
• use-effective-viewport.ts — reads the space windows are laid out in; Window.tsx now uses it instead of raw window.innerWidth.
• Full desktop suite green: 391 files, 3353 tests.
• The per-device constraint is red-proofed: adding a PUT /api/desktop/settings to the store makes the test fail; removing it makes it pass. It is a real assertion, not decoration.

Measured, in Chromium, not inferred

Isolated page, 1440x900 viewport:

root zoom	window.innerWidth	documentElement.clientWidth
1.0	1440	1440
0.8	1440 (unchanged)	1800
1.25	1440 (unchanged)	1152

Two useful consequences: innerWidth does not move with root zoom, so use-device-mode is naturally stable and scaling cannot flip the shell into its phone layout (hazard 2 in the original description is closed, and there is now a test locking it). And clientWidth tracks the zoomed space exactly.

THE BLOCKER: CSS zoom does not compose with this shell

The isolated result did not reproduce in the real app, and chasing that is the finding.

The shell is sized in viewport units throughout — index.html sets html, body { width: 100vw; height: 100vh }, App.tsx uses h-screen w-screen, tokens.css has a 100dvh !important mobile rule. 75 viewport-unit usages across 35 files.

Viewport units resolve against the initial containing block, and the ICB does not scale with the root's own zoom. So at 80% the shell keeps a 1440-unit width but paints into 1152 real px, leaving ~288px blank. That is the opposite of "fit more on screen".

Three fixes were tried against the running app and all three failed, measured each time:

1. html, body { width: calc(100vw / S) } — shell painted 1368x831 into a 1440x900 viewport.
2. Percentage chain (html, body, .h-screen, .w-screen → 100%) — painted 1094x0.
3. Move the zoom off :root onto #root with width: calc(100% / S) — root painted 1800x1125 into 1440x900; coordinate spaces compound because clientWidth on a zoomed element reports in that element's own zoomed units.

The root cause is structural, not a tuning problem: the root element's containing block is the ICB, so a zoomed root can never be made to fill the viewport. Any workable version has to zoom a child while the shell's full-screen sizing derives from that child rather than from vw/vh.

Revised plan

The settings half is done. The remaining work is a layout change, not a settings change: give the shell a single scale-aware source for "full screen" (one container sized in px from innerWidth/innerHeight divided by the scale, with the zoom applied to it), and point the shell's full-screen sizing at that container instead of at vw/vh. The ~70 incidental max-h-[80vh]-style usages on menus and modals degrade gracefully and do not need touching.

That is a bigger and more invasive change than this issue originally implied, and it touches the shell every app renders inside, so it wants its own review rather than being folded in quietly.

Not yet verified

No screenshot of the working feature, because there is not yet a working feature to screenshot. The local backend was not running (dev server proxies /api to :6969, all 502), so the app rendered its "taOS is restarting" state. Full-app visual verification is still outstanding and is a requirement before this ships.