perf: make the desktop UI feel native — unstack blurs, kill idle churn, watch instead of poll

[coreyepstein]

Why

The desktop app felt choppy and laggy. An audit across four surfaces (CSS compositing, Svelte reactivity, the native window layer, and keyboard handling) found the cost was stacked, not singular:

1. Blur applied twice. A native NSGlassEffectView sits behind a transparent WKWebView, and the chat rail then ran a second blur(28px) backdrop-filter on top of it — a full-height per-frame GPU pass whose backdrop the native material had already blurred. apply_liquid_glass_window was also non-idempotent, so every desktop-window re-open stacked another glass view, each sampling independently.
2. A background heartbeat that never idled. The always-visible widget window made any_window_visible permanently true, so the sessions poller's idle gating was dead code. Every 5s, forever: thousands of stats, a blocking pgrep fork on a tokio worker, and a full MissionControlSnapshot broadcast to every live webview — delta-free.
3. Idle re-render churn. tick() allocated a new array even when empty (rewriting $state every 5s for nothing); presence-store.emitSnapshot() deep-copied every company's actor map once per presence message; each message row re-ran JSON.parse and Intl formatting on every render.
4. Layout-animating CSS. .reply-column animated width; the skeleton shimmer animated background-position (paint-only, never composited) across 12 concurrent elements.

What changed

Compositing — dropped the redundant backdrop-filter from the chat rail, files rail and launch buttons (native glass already provides the material; --side-bg alpha raised to compensate), converted progress fills to transform: scaleX() and the shimmer to a transform sheen, added contain: layout paint to the two scrollers.

Reactivity — reference-stable returns from tick() and mergeFetchedTimeline; microtask-coalesced presence emits with a per-company snapshot cache; a precomputed renderRows derived (one parse/format per timeline change, not per render); rAF-throttled scroll; visibility-gated pollers; de-indexed list keys; batched file rendering; lazy/sized images.

Native — HUD windows excluded from the visibility gate; spawn_blocking for the snapshot walk; emit_snapshot_if_changed; idempotent glass via an identifier-tagged subview; FollowsWindowActiveState so background windows stop re-sampling; a 120ms sync-progress coalescer; lto = "thin" + codegen-units = 1.

Session freshness (architecture change) — the local poll is replaced by a notify filesystem watcher (300ms debounce) feeding a shared refresh_and_emit. Watch roots are re-resolved on the safety tick so a session directory created after startup is picked up. The expensive filesystem walk drops to 90s as a backstop; a separate 15s process-only liveness tick keeps session-exit latency unchanged. (The remote/outpost half already used a single MQTT subscription and is untouched.)

Keyboard shortcuts (new) — one capture-phase registry replaces ~15 ad-hoc listeners, resolving the pre-existing three-way ⌘1–5 conflict. ⌘⇧] / ⌘⇧[ next/previous conversation, ⌘N, ⌘F, ⌘⇧F, ⌘1–4 main views, ⌘/ cheat sheet. Mirrored in a native View menu. Matches on both event.code and event.key so non-US layouts work.

Bug fix — the Window opacity slider wrote a CSS variable nothing read. It now drives the real transparency factor through the host's appearance seam.

Diagnostics — pnpm perf measures scroll frame times, load, interaction latency and idle cost locally, with machine/power context and noise-banded baseline comparison. pnpm perf:lint holds the static budgets. Neither gates CI.

Review findings fixed before merge

An adversarial review found five regressions that rode in with the perf work. All fixed, each with a regression test verified to fail without the fix:

• Theme reset on every launch — applyWindowOpacity dispatched a partial appearance payload, so normalizeColorTheme(undefined) resolved to "system" and deleted data-force-theme. A user on forced Light dropped to system/dark on every launch and every slider drag.
• Reactions/reply keyboard-unreachable — visibility: hidden on the resting quick-react bar removed it from the tab order; :focus-within could then never fire on rows with no other focusable descendant. Now box-shadow: none at rest instead, which keeps the rasterization win.
• Team switch didn't scroll to bottom — effects flushed in declaration order and read a stale non-reactive flag. Also fixed a same-team regression where the reset fired on every poll and yanked a scrolled-up reader.
• Duplicate optimistic message — temp rows were only cleared when the newest event id changed, but synthetic ids can never reconcile against the server echo. Now removed by positive reconciliation.
• Watcher blind on fresh installs — watch roots were resolved once. A missing ~/.claude/projects fell back to a non-recursive ancestor watch, and the later directory-create event was filtered out as non-.jsonl, leaving the watcher permanently blind until restart.

Verification

Suite	Result
packages/ui tests	2546 passed
packages/core tests	119 passed
hq-sync-menubar (Rust)	1084 passed
hq-desktop-core sessions	112 passed
svelte-check	0 errors
apps/sync build	✓
pnpm perf:lint	39 passed

The release bundle was built, ad-hoc signed, launched and exercised by the owner, who confirmed the app feels materially smoother.

Honest limitations

• The perf harness cannot measure the native wins. It drives the static shell in headless Chromium with Tauri IPC mocked, so the glass, widget-gating and watcher changes — two of the twelve commits, almost entirely src-tauri/ and crates/ — are not reflected in its numbers. Those are covered by tests and code review, not frame measurement.
• A before/after comparison was attempted and is not trustworthy. Load average was 20–33 across the runs and the power state changed between passes (battery → AC). docs/performance-before-after.md records this plainly rather than presenting the numbers as a result. The two load-independent findings do stand: total JS grew +11,308 B (+0.46%) from the shortcuts registry and cheat sheet, and idle main-thread busy is 0.0 ms on both trees — because the idle churn this branch fixes lives behind the mocked IPC boundary.
• apps/work's build is broken on main (mqtt pulling https into the browser graph). Pre-existing, unrelated, not fixed here.

🤖 Generated with Claude Code