SubMiner/backlog/tasks/task-238.1 - Extract-main-window-and-overlay-window-composition-from-src-main.ts.md

id, title, status, assignee, created_date, labels, milestone, dependencies, references, parent_task_id, priority

id	title	status	assignee	created_date	labels	milestone	dependencies	references	parent_task_id	priority
TASK-238.1	Extract main-window and overlay-window composition from src/main.ts	Done		2026-03-26 20:49	tech-debt runtime windows maintainability	m-0		src/main.ts src/main/runtime/composers src/main/runtime/overlay-runtime-bootstrap.ts docs/architecture/README.md	TASK-238	high

Description

src/main.ts still directly owns several BrowserWindow construction and window-lifecycle paths, including overlay-adjacent windows and setup flows. That keeps the composition root far larger than intended and makes window behavior hard to test in isolation. Extract the remaining window/bootstrap composition into named runtime modules so src/main.ts mostly wires dependencies and app lifecycle events together.

Acceptance Criteria

• #1 At least the main overlay window path plus two other window/setup flows are extracted from direct BrowserWindow construction inside src/main.ts.
• #2 The extracted modules expose narrow factory/handler APIs that can be tested without booting the whole app.
• #3 src/main.ts becomes materially smaller and easier to scan, with window creation concentrated behind well-named runtime surfaces.
• #4 Relevant runtime/window tests pass, and new tests are added for any newly isolated window composition helpers.

Implementation Plan

1. Map the remaining direct BrowserWindow creation sites in src/main.ts and group them by shared lifecycle concerns.
2. Extract coherent modules for construction, preload/path resolution, and open/focus/reuse behavior rather than moving raw option objects wholesale.
3. Update the composition root to consume the new modules and keep side effects/app state ownership explicit.
4. Verify with focused runtime/window tests plus bun run typecheck.

Completion Notes

• Window composition now flows through src/main/runtime/setup-window-factory.ts and src/main/runtime/overlay-window-factory.ts, with src/main/runtime/overlay-window-runtime-handlers.ts composing the main/modal overlay entrypoints.
• src/main.ts keeps dependency wiring and state ownership, while the named runtime helpers own the reusable window-creation surfaces.
• Verification:
  • bun test src/main/runtime/overlay-window-factory.test.ts src/main/runtime/overlay-window-runtime-handlers.test.ts
  • bun run typecheck failed on unrelated existing errors in src/core/services/immersion-tracker/lifetime.ts, src/core/services/immersion-tracker/maintenance.ts, and src/core/services/stats-server.ts