--- title: Quick Launch Modal (part 3) --- # Quick Launch Modal (part 3) ## What it is This is part 3 of the [Quick Launch Modal](quick-launch-modal.md) page. The [main page](quick-launch-modal.md) covers what Quick Launch is, how to open it, how to compose and send, and its settings; [part 2](quick-launch-modal-part-2.md) covers every other tab and the mobile sheet. This half is the implementation view: how the window, the hotkeys and the tabs are built, and why they are built that way. ## Where to find it There is no separate UI surface here — this half is for someone working in the codebase. Everything it describes is reached at runtime through the same floating window and the same Settings → Quick Launch page the other two pages cover. ## How it behaves What a reader can observe of the choices below: the modal pops up over whatever is on screen but never covers an exclusive-fullscreen game or video player, it hides rather than closes so an unsent draft survives, and its window is frameless and cannot be moved or resized. ## For agents ### How it works (for repo-aware readers) - **Window manager**: [quick-launch-window.ts](../../src/main/services/quick/quick-launch-window.ts) owns the BrowserWindow lifecycle as an explicit state machine (`Cold`, `PreWarming`, `WarmHidden`, `Opening`, `Shown`, `Closing`, `Hidden`) — lazy creation on first open, "kept alive" across opens, primary-display centering recomputed every show, lifecycle listeners (`focus` / `blur` / `closed`) wire up voice-service suppression and click-outside-to-dismiss. It also **self-heals a blank pre-warmed window**: because the window is loaded once and only `show()`'d (never reloaded), a silent renderer mount failure used to leave it permanently blank until an app restart. The renderer reports `QUICK_LAUNCH_RENDERER_READY` on mount, and real BrowserWindows must also emit Electron `ready-to-show` before reveal; a hidden→shown open that is not reveal-ready reloads once, waits for readiness, or discards before any `show()` call if readiness times out (fall-through-to-recreate immediate if the reload itself hard-fails — the healthy path stays await-free). `render-process-gone` / a main-frame `did-fail-load` also discard the window so the next hotkey lazy-recreates it. Full invariants (I11/I22): [quick-launch-entrance-animation-contract.md](../../.claude/memory/contracts/quick-launch-entrance-animation-contract.md). - **Graceful close (v14)**: every dismiss — Escape / Ctrl+W, click-away, and submit — routes through `animateCloseAndHide()`, which **shrinks the window's BOUNDS toward its centre and glides it away** rather than hard-cutting the opaque rectangle (which read as "the dark background stays up / two windows"). An opaque window can't fade — a panel-opacity fade reads as a blank rectangle and `win.setOpacity()` re-introduces the fragile layered window v11 deleted — so bounds are the only lever. Main runs a `setBounds` frame-tween (~130 ms); the renderer content scale is a **`requestAnimationFrame` follower that re-reads the LIVE window size every frame** (`QUICK_LAUNCH_CLOSING` → `quick-launch-exit`, opacity held at 1, over a pixel-frozen wrapper), NOT an independent scale-out keyframe. **v14 CENTRES that wrapper in the live viewport** (`position:fixed`; `left/top:50%`; scaled via `translate(-50%, -50%) scale(...)`), so the collapse lands on the window centre = screen centre by construction. v13 scaled the wrapper about its TOP-LEFT, so a lagging (too-big) frame was clipped only at the bottom-right and its visible centre drifted up-and-left — the **"hides to the left"** bug (reproduced 2026-07-12). (The earlier v12 drift was worse: two unsynchronized clocks — main's `setInterval` bounds-shrink about CENTRE + a renderer wall-clock CSS keyframe about TOP-LEFT — "collapsed in a different direction each time.") A centre-anchored scale/size mismatch is a symmetric dark hairline on all sides (invisible), never a corner pin. Then `hide()`s + restores full bounds. Re-entrant, `setWindowHeight` no-ops while closing, and a re-open mid-shrink aborts cleanly. Full invariants (I17/I18): [quick-launch-entrance-animation-contract.md](../../.claude/memory/contracts/quick-launch-entrance-animation-contract.md). - **Theme-matched window background (open-flash fix)**: the opaque BrowserWindow's native `backgroundColor` is seeded at `#18181b` (bare-dark surface-100), but the panel paints the ACTIVE theme's `bg-surface-100` (glassmorphism `#0e0e16`, ~1.7× darker). On open, a compositor re-raster momentarily drops the renderer's paint — including the wrapper — so for ~1 frame the fixed, lighter bg showed as a full-modal light/white flash before the dark content painted (worst under glassmorphism, the default theme). Fix: the renderer reports the live `--color-surface-100` on every theme apply/change (`QUICK_LAUNCH_SET_WINDOW_BG`) and main keeps the native `backgroundColor` matched via `win.setBackgroundColor` — the window stays fully OPAQUE (never `transparent:true` / `setOpacity`), only its solid color follows the theme. Full invariants (I15): [quick-launch-entrance-animation-contract.md](../../.claude/memory/contracts/quick-launch-entrance-animation-contract.md). - **Hotkey registration**: Electron `globalShortcut.register(accelerator, () => quickLaunchWindow.toggleShow())` — re-registered on every settings change so a new value takes effect without an app restart. - **Per-tab hotkeys**: planned by `planHotkeyRegistrations()` in [src/shared/global-hotkeys.ts](../../src/shared/global-hotkeys.ts) (a `'quick launch tab'` candidate per assigned tab, appended after the fixed four + email recipients; gated on `quickLaunchHotkeyEnabled`). `registerGlobalHotkeys()` in [src/main/index.ts](../../src/main/index.ts) first runs `selectQuickLaunchTabHotkeys(settings.quickLaunchTabHotkeys, isEnabled)` to drop disabled/unknown tabs — its `isEnabled` predicate accepts a repo tab id (`parseRepoTabId(id) !== null`) as well as an enabled registry action, so **repo tabs get a hotkey too** (their project existence is validated at fire time, not in the pure planner). Each fired hotkey does `await toggleShow()` + `emitPush(QUICK_LAUNCH_OPEN_TO_TAB, { actionId })`. The modal listens for that validated push; both its `QUICK_LAUNCH_OPEN_TO_TAB` handler and the `visibleTabIds` fold gate on `isTabVisible(actionId, enabledByActionId, existingProjectIds)` — the same dual gate that covers repo tabs — so a forced target (registry OR repo) selects, renders, cycles, and reverts on dismiss (a repo target whose project was deleted just falls through to the default tab). The push channel must be in `QUICK_LAUNCH_ALLOWLIST` ([detached-push-filter.ts](../../src/main/services/detached-push-filter.ts)) and have a modal listener (both pinned by [quick-launch-push-listener-coverage.test.ts](../../tests/unit/lint/quick-launch-push-listener-coverage.test.ts)). Invariants `hotkeys-register-last` … `repo-tabs-hotkey-capable`: [quick-launch-action-registry-contract.md](../../.claude/memory/contracts/quick-launch-action-registry-contract.md). - **Renderer entry**: [src/renderer/quick-launch.html](../../src/renderer/quick-launch.html) + [src/renderer/src/quick-launch.tsx](../../src/renderer/src/quick-launch.tsx) — third rollup entry alongside `index.html` and `recorder-host.html`. Loaded via `ELECTRON_RENDERER_URL` in dev, from disk in production. On mount it fires `QUICK_LAUNCH_RENDERER_READY` from a top-level effect (so a render throw never signals ready) — the blank-renderer recovery handshake the window manager uses to tell a healthy window from one that came up blank. - **Modal component**: [src/renderer/src/features/quick-launch/QuickLaunchModal.tsx](../../src/renderer/src/features/quick-launch/QuickLaunchModal.tsx) — textarea + chip row + send button + inline error strip. Owns the textarea state; Esc / submit / blur clear it. The tab strip + gear icon + the **"+" add-tab button** (with its `AddTabMenu` dropdown) live here; `Ctrl+Tab` / `Ctrl+Shift+Tab` cycling **and `Ctrl+1`…`Ctrl+9` direct tab-jump** share one **window-level** `keydown` listener (a `useEffect` on `window`, not a panel-scoped `onKeyDown`) so they fire whenever the modal window is focused regardless of where focus sits inside it. The digit branch guards on `!e.altKey` (so AltGr / odd-layout combos can't hijack), maps digit _n_ → the _n_-th `visibleTabIds` entry (no-op past the 9th or out of range), and only `preventDefault()`s a key it acts on. Each of the first nine tabs surfaces its number on hover via the shared `` and exposes it to assistive tech with `aria-keyshortcuts` (no raw `title=`). No collision with the main window's universal `Ctrl+1`…`Ctrl+0` project/inbox switcher: the Quick Launch window is a separate React root ([quick-launch.tsx](../../src/renderer/src/quick-launch.tsx)) that never mounts `useKeyboardShortcuts`, so that dispatcher isn't present here. The "+" lists `getAvailableToAddActions(pinnedActionIds, enabledByActionId)` and pins a choice by optimistically updating local `pinnedActionIds` then persisting via `IPC.SETTINGS_UPDATE` (rollback + inline error on failure) — no new IPC. The strip mounts when `>1` tab is visible **or** there is something to add, so the "+" stays reachable from a single-tab install. Right-clicking a tab opens `TabContextMenu` (opaque, cursor-positioned via `containToViewport`) — it now opens for **every** tab, Session included. At the top is an inline **Global hotkey** capture field (the shared `QuickLaunchTabHotkeyField`, `autoFocus`ed, `pretty`-displayed) that persists via `handleSetTabHotkey` → `SETTINGS_UPDATE` (optimistic + rollback); below it a **Remove from Quick Launch** action calls `handleRemoveTab` — strikes the id from `pinnedActionIds`, persists via `SETTINGS_UPDATE` (rollback + inline error), reselects `firstVisibleTabId` when the removed tab was active — shown for every tab **except Session** (Remove suppressed for Session, contract **`remove-unpins-in-place`**; Session's menu is hotkey-only). Locked by [QuickLaunchModal-remove-tab.test.tsx](../../tests/unit/features/quick-launch/QuickLaunchModal-remove-tab.test.tsx). When the pinned tabs overflow the fixed-width window, the tab row is a horizontally-scrolling region (`overflow-x-auto`, scrollbar hidden via the modal's inline `