ReviewOS

also looking at this

craft-native/craft

feat: add Linux and Windows named-window routing

#325
Merged glennmichael123 wants to merge codex/multi-window-linux-windows into main
29 files +2250 -200
docs/architecture/multi-window-ownership.mdmodified+41-21
Changes to docs/architecture/multi-window-ownership.md
@@ -1,7 +1,7 @@
11# Multi-window ownership
22
33This document records Craft's current multi-window ownership contract. It is
4both a map of the implemented macOS behavior and a boundary around the choices
4both a map of the implemented desktop behavior and a boundary around the choices
55that are still open. A process-global Zig object is not automatically a
66single-window bug: the important question is whether it is a shared service or
77whether it stores a window-specific target.
@@ -10,17 +10,35 @@ whether it stores a window-specific target.
1010
1111| Area | macOS | Linux | Windows |
1212| --- | --- | --- | --- |
13| Runtime creation from `createWindow()` | Implemented | Not wired to the SDK handle contract | Not wired to the SDK handle contract |
14| Stable named handles | Implemented | Not implemented | Not implemented |
15| Sender-authenticated local actions | Implemented | Not implemented | Not implemented |
16| Named cross-window actions | Implemented | Not implemented | Not implemented |
17| Per-window lifecycle events | Implemented | Not implemented | Not implemented |
18| Permanent destroy and cleanup | Implemented for named windows | Not implemented | Not implemented |
13| Runtime creation from `createWindow()` | Implemented | Implemented; GUI smoke in CI | Implemented; WebView2 GUI smoke in CI |
14| Stable named handles | Implemented | Implemented | Implemented |
15| Sender-authenticated local actions | Implemented | Implemented through WebKitGTK | Implemented through WebView2 |
16| Named cross-window actions | Implemented | Implemented for core controls | Implemented for core controls |
17| Per-window lifecycle events | Implemented | Implemented | Implemented |
18| Permanent destroy and cleanup | Implemented for named windows | Implemented on close/destroy | Implemented on close/destroy |
1919| Modal and parent relationships | Unspecified | Unspecified | Unspecified |
2020
21Issue #67 therefore remains open. Its macOS core is substantially implemented,
22but closing it would imply cross-platform and modal/parent semantics that Craft
23does not yet provide.
21The runtime-creation, stable-handle, reply-routing, and event-scoping contract
22from issue #67 is covered here. Modal/parent semantics remain separate future
23decisions. The Windows release archive stages an app-local WebView2 loader;
24users still need the Microsoft WebView2 Runtime.
25
26Linux and Windows keep their live native window/webview pairs in
27`desktop_window_registry.zig`. Page messages are authenticated by the sending
28WebKitGTK view or the per-WebView2 event subscription; names select a target
29only after that native source is known.
30Replies go back to the requesting view, and lifecycle events go to the changed
31window plus its named handle's creator. Linux must register its `GtkApplication`
32before constructing the first `GtkApplicationWindow`, because the CLI creates
33that window before entering `g_application_run()`. On Windows, the controller
34passed to the asynchronous WebView2 completion callback is borrowed. Each live
35window retains its own controller reference until native destruction; otherwise
36WebView2 can close before the page bridge registers or navigation begins.
37WebView2 also forbids entering a nested message loop from its message callback.
38Windows therefore queues page-requested child creation onto the UI message
39queue, preserving the authenticated owner and reply ID until that callback
40returns. Concurrent opens are drained serially and abandoned if their creator
41window is destroyed before dispatch.
2442
2543## Per-window state
2644
@@ -57,9 +75,10 @@ back to whichever window was created most recently:
5775- The local scroll monitor is installed once, but reads the event's `NSWindow`,
5876 advances only that window's accumulator and emits only to its webview.
5977
60`close()` preserves these resources and the SDK's native-event subscriptions
61so the same page can reopen with its DOM and JavaScript state intact, including
62when the primary window is reopened by the Dock rather than `createWindow()`.
78On macOS, `close()` preserves these resources and the SDK's native-event
79subscriptions so the same page can reopen with its DOM and JavaScript state
80intact, including when the primary window is reopened by the Dock rather than
81`createWindow()`.
6382`destroy()` removes the named registry entry, Native UI graph, gesture and
6483material slots, recovery state, event ownership and retained AppKit objects
6584before releasing the window and detaching the SDK's DOM listeners.
@@ -118,13 +137,12 @@ The next multi-window milestone needs product decisions in addition to code:
118137 application-level asynchronous source above.
1191383. Decide whether Touch Bar should stay primary-window scoped or follow the
120139 key window with separately owned item definitions and callbacks.
1214. Bring Linux and Windows runtime creation, stable handles, sender routing,
122 lifecycle events and destroy semantics up to the macOS contract. Their
123 platform backends can create native windows today, but the TypeScript bridge
124 deliberately reports runtime creation as unsupported outside macOS.
1255. Add platform-native integration coverage. Source conformance and pure state
126 tests defend macOS invariants without requiring a GUI runner, but they do
127 not substitute for real Windows WebView2 and Linux WebKitGTK lifecycle tests.
1404. Finish advanced Linux/Windows window actions and clarify which are portable
141 versus platform-specific, without conflating close semantics: macOS retains
142 a closed page, while Linux and Windows release it.
1435. Expand platform-native integration beyond the current named-window lifecycle
144 smokes. CI runs Linux WebKitGTK under Xvfb and Windows WebView2 on a native
145 runner, but advanced actions and packaged-app behavior still need coverage.
128146
129147## Review checklist
130148
@@ -134,6 +152,8 @@ For every new bridge or callback that touches a window, verify:
134152- An explicit window ID is resolved through the registry and unknown IDs fail.
135153- An asynchronous reply retains both its target and its requesting webview.
136154- A delayed control callback stores its owner on the control/delegate instance.
137- Ordinary close preserves state; permanent destroy forgets it exactly once.
155- On macOS, ordinary close retains the page and permanent destroy forgets it
156 exactly once. On Linux and Windows, close and destroy both release the native
157 window/webview; a later open of the same name creates a fresh native page.
138158- A process-global event sink is documented as primary, broadcast or
139159 subscriber-owned rather than inheriting accidental last-window behavior.