Module windows 

Secondary windows (docs/windows.md): the app-facing open_window API, the per-window registry, and the fallback that presents window content as a fullscreen cover where the toolkit cannot open windows (Cap::MultiWindow = Unsupported).

Windows live in the ONE thread-local tree as additional boundary roots (the same “wrap an externally-owned handle” record as the primary root and the list cell anchors), so bindings, find_by_id, and dayscript work across windows unchanged. Close is asynchronous everywhere: the platform (or the cover’s hide transition) confirms, and teardown runs THEN — one path for native and programmatic closes.

Structs

WindowHandle

A live secondary window (docs/windows.md). Cheap to clone; inert after close.

Constants

PREFERENCES_KEY

The singleton key every preferences window opens under.

Functions

finish_window_open

Backend-facing: complete a Pending window open (docs/windows.md). id is the node the backend’s open_window received; raw is the new window’s CONTENT container; size its content size in points. false ⇒ the window was closed before completion — the backend should drop the native window it just created.

focused_window

The most recently focused open secondary window, if any. None ⇒ the primary window is key (or no secondary window exists).

new_window_action_id

The dispatch id of the New Window action (0 = unregistered) — MenuRole::NewWindow lowering and the backends’ tab-bar “+” wiring.

open_new_window

Open a window through the registered new-window builder (the newWindowForTab: / File ▸ New Window path). None = no builder registered.

open_preferences

Open-or-focus the preferences surface (docs/windows.md): a WindowKind::Preferences singleton window on desktop, the cover fallback elsewhere — one call for menu items and toolbar gears alike. false = no preferences piece is registered (logged).

open_window

Open a secondary window (docs/windows.md). key names the LOGICAL window: when a window with this key is already open it is focused and returned instead of duplicated (the preferences pattern); None always opens a new one. Where the toolkit cannot open windows (Cap::MultiWindow = Unsupported — probe it to adapt chrome) the content presents as a fullscreen cover in the primary window instead, closable the same way.

open_window_count

Test/diagnostic surface: the number of open secondary windows.

preferences_action_id

The dispatch id of the auto Preferences menu action (0 = unregistered). Backends use it to wire their default-menu Settings item; the injection pass uses it for app_menu.

register_new_window

Register the builder behind File ▸ New Window and the macOS tab-bar “+” (docs/windows.md): each call opens another WindowKind::Normal window. A menu_role(MenuRole::NewWindow) item lowers to this action; without a registration it lowers disabled.

register_preferences

Declare the app’s preferences piece (docs/windows.md) — once, in root(), ideally before app_menu. Enables the desktop Preferences window (singleton, primary+,), the auto Settings…/Preferences menu item, and open_preferences everywhere (cover fallback where the toolkit cannot open windows). The window titles itself with options.title; use register_preferences_with to localize it or change the size.

register_preferences_with

register_preferences with explicit window options (localized title, size).

reset_windows

Reset the registry + registrations (tests — pairs with uninstall_tree).

window_by_key

The open window registered under key, if any (the dayscript screenshot step’s window: target resolves here).

window_kind_of

The WindowKind of the open window at root, for backends and tests.

window_node_id

The window root’s spec-boundary id (backends key their per-window maps by it).

window_root_by_key

The tree root of the window registered under key — day-script’s snapshot target.