also looking at this
feat: add Linux and Windows named-window routing
#325
29 files
+2250
-200
| @@ -1,7 +1,7 @@ | ||
| 1 | 1 | # Multi-window ownership |
| 2 | 2 | |
| 3 | 3 | This document records Craft's current multi-window ownership contract. It is |
| 4 | both a map of the implemented macOS behavior and a boundary around the choices | |
| 4 | both a map of the implemented desktop behavior and a boundary around the choices | |
| 5 | 5 | that are still open. A process-global Zig object is not automatically a |
| 6 | 6 | single-window bug: the important question is whether it is a shared service or |
| 7 | 7 | whether it stores a window-specific target. |
| @@ -10,17 +10,35 @@ whether it stores a window-specific target. | ||
| 10 | 10 | |
| 11 | 11 | | Area | macOS | Linux | Windows | |
| 12 | 12 | | --- | --- | --- | --- | |
| 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 | | |
| 19 | 19 | | Modal and parent relationships | Unspecified | Unspecified | Unspecified | |
| 20 | 20 | |
| 21 | Issue #67 therefore remains open. Its macOS core is substantially implemented, | |
| 22 | but closing it would imply cross-platform and modal/parent semantics that Craft | |
| 23 | does not yet provide. | |
| 21 | The runtime-creation, stable-handle, reply-routing, and event-scoping contract | |
| 22 | from issue #67 is covered here. Modal/parent semantics remain separate future | |
| 23 | decisions. The Windows release archive stages an app-local WebView2 loader; | |
| 24 | users still need the Microsoft WebView2 Runtime. | |
| 25 | ||
| 26 | Linux and Windows keep their live native window/webview pairs in | |
| 27 | `desktop_window_registry.zig`. Page messages are authenticated by the sending | |
| 28 | WebKitGTK view or the per-WebView2 event subscription; names select a target | |
| 29 | only after that native source is known. | |
| 30 | Replies go back to the requesting view, and lifecycle events go to the changed | |
| 31 | window plus its named handle's creator. Linux must register its `GtkApplication` | |
| 32 | before constructing the first `GtkApplicationWindow`, because the CLI creates | |
| 33 | that window before entering `g_application_run()`. On Windows, the controller | |
| 34 | passed to the asynchronous WebView2 completion callback is borrowed. Each live | |
| 35 | window retains its own controller reference until native destruction; otherwise | |
| 36 | WebView2 can close before the page bridge registers or navigation begins. | |
| 37 | WebView2 also forbids entering a nested message loop from its message callback. | |
| 38 | Windows therefore queues page-requested child creation onto the UI message | |
| 39 | queue, preserving the authenticated owner and reply ID until that callback | |
| 40 | returns. Concurrent opens are drained serially and abandoned if their creator | |
| 41 | window is destroyed before dispatch. | |
| 24 | 42 | |
| 25 | 43 | ## Per-window state |
| 26 | 44 | |
| @@ -57,9 +75,10 @@ back to whichever window was created most recently: | ||
| 57 | 75 | - The local scroll monitor is installed once, but reads the event's `NSWindow`, |
| 58 | 76 | advances only that window's accumulator and emits only to its webview. |
| 59 | 77 | |
| 60 | `close()` preserves these resources and the SDK's native-event subscriptions | |
| 61 | so the same page can reopen with its DOM and JavaScript state intact, including | |
| 62 | when the primary window is reopened by the Dock rather than `createWindow()`. | |
| 78 | On macOS, `close()` preserves these resources and the SDK's native-event | |
| 79 | subscriptions so the same page can reopen with its DOM and JavaScript state | |
| 80 | intact, including when the primary window is reopened by the Dock rather than | |
| 81 | `createWindow()`. | |
| 63 | 82 | `destroy()` removes the named registry entry, Native UI graph, gesture and |
| 64 | 83 | material slots, recovery state, event ownership and retained AppKit objects |
| 65 | 84 | before 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: | ||
| 118 | 137 | application-level asynchronous source above. |
| 119 | 138 | 3. Decide whether Touch Bar should stay primary-window scoped or follow the |
| 120 | 139 | key window with separately owned item definitions and callbacks. |
| 121 | 4. 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. | |
| 125 | 5. 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. | |
| 140 | 4. 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. | |
| 143 | 5. 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. | |
| 128 | 146 | |
| 129 | 147 | ## Review checklist |
| 130 | 148 | |
| @@ -134,6 +152,8 @@ For every new bridge or callback that touches a window, verify: | ||
| 134 | 152 | - An explicit window ID is resolved through the registry and unknown IDs fail. |
| 135 | 153 | - An asynchronous reply retains both its target and its requesting webview. |
| 136 | 154 | - 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. | |
| 138 | 158 | - A process-global event sink is documented as primary, broadcast or |
| 139 | 159 | subscriber-owned rather than inheriting accidental last-window behavior. |