feat(host): seamless in-place window-mode transitions + foundational cleanup

[Kosinkadink]

Originally branched as a pre-seamless-transition cleanup pass; now also lands the seamless transitions feature itself, the bug fixes shaken out by it, and the supporting refactors / e2e hardening that grew out of the same investigation.

Headline feature: seamless in-place window-mode transitions

The chooser host now flips into the install's host in place instead of close+open swap — same BrowserWindow.id, no flicker, no window-count blip. Symmetric undo via Return to Dashboard flips back without spawning a new chooser window.

Main code paths:

• claim-attach-host IPC handler (src/main/index.ts) accepts the chooser-host renderer's claim and registers a pendingAttachClaims entry keyed by install id.
• onLaunch consumes the claim, calls rebuildComfyViewIfNeeded (handles unique-partition installs by swapping entry.comfyView to a persist:${id} partition view), loadTitleBarUrl (re-navigates the title bar so its URL carries the new install id), destroyPanelView (drops the chooser PanelApp + any in-flight launch overlay), then attachInstall against the same host.
• returnToDashboard (src/main/host/detach.ts) → entry.detachInstall() → _detachInstallImpl runs the symmetric undo: _installCleanup, navigate comfyView to about:blank, reset entry identity, loadTitleBarUrl(_, ''), applyChooserHostTheme, destroyPanelView + ensurePanelView('chooser'), layout.
• New loadTitleBarUrl() and destroyPanelView() helpers shared between attach + detach + close paths.
• Close-handler teardown wraps every step in safeTeardown(source, fn) so a single throw can't skip BrowserWindow.destroy() (errors forwarded to Datadog with their source tag).

Bugs fixed during validation

• layoutViews stale-closure (createHostWindow.ts): operated on the captured comfyView instead of entry.comfyView. After rebuildComfyViewIfNeeded swapped the view (Standalone / Portable installs), the new view was added to contentView with default 0×0 invisible bounds — ComfyUI loaded but never painted. Now reads entry?.comfyView ?? comfyView. The strengthened lifecycle.test.ts "split-view architecture" test now asserts getVisible() + non-zero bounds.
• Spawn-collision overlap: File → New Window opened the new chooser at exactly the same x/y/w/h as the existing one — looked like the previous window had simply re-rendered. New cascadeOffsetForCollisions walks live host origins and bumps (x, y) by 30px per collision (with chain detection).
• Bounds-key drift: saveWindowBounds was bound to the construction-time opts.boundsKey. A chooser host that flipped to install-backed kept saving install-mode resizes under the chooser slot (and vice versa via Return to Dashboard). Now reads liveBoundsKeyFor(entry) so each identity slot only persists what the host did while it was that identity.
• Sibling-aware default sizing: when a live host of the same identity already exists, open at the canonical 1280×900 default offset from the sibling's origin. First-spawn (no sibling) restores saved bounds.
• Chooser hosts always default-size: the dashboard isn't a workspace the user customizes — it's a launcher surface. Skips both getSavedBounds restore and persistBounds save for chooser hosts so cold start, app relaunch, and File → New Window all open at the canonical default.
• Stranded attach claims: when the existing-entry path takes over a launch, consumeAttachClaim(installationId) drops the stale claim instead of leaving it pinned in the map until the chooser host closes.

E2E coverage

e2e/lifecycle.test.ts adds:

• launches ComfyUI from chooser tile — snapshots BrowserWindow.ids before/after the click; same id must survive the launch (in-place flip guard).
• split-view architecture now also asserts comfyVisible === true + comfyBounds.{width,height} > 0 (regression guard for the stale-closure bug).
• return-to-dashboard flips install host in place (same window id) — drives the File menu's Return to Dashboard via a new returnFirstInstallHostToDashboard E2E hook, asserts the host id survives the flip, the comfy frontend unloads, the chooser body re-paints, and a re-launch from the same chooser flips it back to the same id.

All 9 lifecycle tests + 43 fast Windows e2e tests pass.

Foundational refactors (originally index.ts was ~4,500 lines)

Host module split (src/main/host/)

• registry.ts — comfyWindows map, installationIdToWindowKey index, pendingAttachClaims, isChooserHost / isInstallHost predicates, computeBodyMode.
• createHostWindow.ts — shared createHostWindow() + the openChooserHostWindow wrapper, loadTitleBarUrl, cascadeOffsetForCollisions, buildComfyView, rebuildComfyViewIfNeeded, expectedPartitionFor, theme helpers.
• attach.ts — attachInstall(entry, opts) with _installCleanup for symmetric undo.
• detach.ts — consultPanelRendererClose, closeAllHostWindows, confirmAndCloseAllHostWindows, returnToDashboard, _detachInstallImpl.
• panelView.ts — ensurePanelView, destroyPanelView, setActivePanel, refreshComfyTabBody, focusActiveBody, sendToPanelDeferred, panel-routing IPC.

Dedicated unit tests for each module (registry.test.ts, createHostWindow.test.ts, attach/detach/panelView test files).

Popup primitive

• New EmbeddedPopupView lifecycle primitive (src/main/popups/embeddedPopupView.ts).
• popups/{titlePopup,titleTooltip,systemModal}.ts adopt it.

Renderer composable extractions

• TitleBarApp: useTitleBarHoverGate, useTitleBarIdentity, useTitleBarMenus, useTitleBarTooltip, useUpdatePills.
• PanelApp: useChooserHandoff, useFirstUseChain, usePanelOverlays, useDeepLinkRouter, useAppUpdatePrompts, useSendFeedback.
• ChooserView: ChooserInstallTile.vue + shared chooser-tiles.css.
• SnapshotTab: SnapshotInspector.vue + lib/snapshots.ts.

Other extractions

• lib/windowState.ts — bounds cache.
• lib/contextMenu.ts — attachContextMenu.
• lib/processErrorHandlers.ts — forwardDatadogError etc.
• lib/ipc/registerAssetDownloadHandlers.ts, lib/ipc/registerDownloadHandlers.ts.

E2E hardening

The pre-existing suite was disabled (testIgnore) because every test assumed the legacy sidebar / fullscreen UI. Replaced with a new harness:

• e2e/support/cdpPages.ts — WebContentsPage eval-bridge facade. Required because the chooser host's parent BrowserWindow has no DOM (just hosts WebContentsView children); Playwright's connectOverCDP hangs during enumeration in that topology, so we run executeJavaScript against each child's webContents directly.
• e2e/support/{chooserHelpers,devHooks,electronHarness,evalRetry,hoverGate}.ts — facades and retry helpers for the new architecture.
• New tests: chooser.test.ts, devhooks-smoke.test.ts, downloads-shelf.test.ts, dropdowns.test.ts, settings.test.ts, title-bar-hover-gate.test.ts, title-bar-hover-gate-comfy-window.test.ts, update-pills.test.ts.
• lifecycle.test.ts rewritten against the new harness; capped at 3 minutes per test (was 10).
• playwright.config.ts drops the testIgnore block.

Comment / doc cleanup

Per ComfyUI-Launcher/AGENTS.md (no plan-step / phase / track / stage references in code comments). Sweeps across version-resolve.ts, standalone/actions.ts, index.ts, settings.ts, and several renderer composables / tests. Removed completed planning docs (357-code-quality-plan.md, 431-view-flattening-plan.md, view-flattening-plan.md, window-mode-unification-revert.md). Added loadTitleBarUrl JSDoc that documents the explicit handshake contract — every channel onTitleBarReadyHandler must re-push since the navigation drops cached messages.

Verification

pnpm run typecheck          # passes
pnpm run lint               # passes
pnpm run build              # passes
pnpm run test               # 937 vitest tests pass
pnpm run test:e2e:windows -- --project=lifecycle
  # 52/52 pass in 2.5m (43 fast Windows + 9 lifecycle)

Notes

• Branched off origin/main, independent of docs(agents): forbid ending sessions with uncommitted work #550.
• Net delta: ~+11,170 / −8,318 lines across 82 files, but src/main/index.ts itself shrinks from ~4,500 lines to ~480 (the rest is moved into the host / popup / lib modules listed above).