Pool windows are spawned at this off-screen position so they
don’t appear on the user’s desktop while pre-painting. On
promote they’re moved to the cursor and shown.
Pixels above the cursor where the title bar sits — matches
open_window_at_position so the cursor lands near the top-center
of the title bar after promotion.
HWND cache for pool windows. Populated at on_after_created
(register_pool_window) and consulted at promote_pool_window as
the source of truth — BrowserHost::window_handle() returns null
once the page loads even though the underlying Win32 window is
alive (verified by IsWindow — see
SPEC_POOL_WINDOW_HWND_NULL_2026_05_06.md §4.1 diagnostic run).
Phase B.5c follow-up — clean up an orphan pool window left behind
when promote_pool_window’s HWND validation fails. Without this,
the popped label sits in state.browsers but is no longer in
unpromoted_pool_labels (promote removed it) and never became a
real user window (no WindowOpened was reported). Host’s
compute_and_report_host_counts then counts it as a window, while
the launcher mirror correctly does not — persistent off-by-one
drift. (Caught by B.4b drift detection during B.5c smoke test on
v0.33.461.)
Initialize the pool after primary-window first paint. Spawns
POOL_TARGET_SIZE windows. Called once per app run from
on_after_created for the “main” label.
Called from the pool_window_ready IPC handler — fired by the
frontend’s awaitPoolPromote AFTER its pool:promote listener
is installed. NOW it’s safe to enqueue this window for
promotion.
Called when a pool window is destroyed before it ever became
renderer-ready (renderer crash mid-init, user closed at OS level,
etc.). Without this clearing path the respawn semaphore would
stay locked forever and the pool would never refill.
Promote a pool window for tear-off. Pops a label, sends a
move-and-show task to the CEF UI thread, and emits
pool:promote to the renderer with the workspace ID. Returns
the promoted window’s label so the caller can chain SC_MOVE
against it. Returns None if the pool is empty (caller should
fall back to the cold path).
Called from on_after_created when a pool window’s browser is
registered. Logs + applies WS_EX_TOOLWINDOW so the off-screen
pool window doesn’t show up in the taskbar / Alt+Tab. The
promote path (promote_pool_window) clears it again so the
torn-off window IS taskbar-visible.
Toggle WS_EX_TOOLWINDOW on a window’s extended style so it
appears (or doesn’t) in the taskbar / Alt+Tab. We use this so
pre-warmed pool windows stay invisible to the user, then
re-enter the taskbar when promoted to a real torn-off window.
Spawn a single pool window. Called at startup (N times) and
after each promote (1 refill). Idempotent against the
in-flight semaphore — concurrent calls collapse to one spawn
in flight at a time.