@abide/abide 0.123.3 → 0.124.0

package/src/server/openDesktopWindow.ts

@@ -0,0 +1,308 @@
+// 38.70 — THE WINDOW `abide bundle`'S EXECUTABLE OPENS, over AppKit through `bun:ffi`: a WKWebView, the
+// page's menu bar and an event drain. What it shows is the `DesktopSession`'s to decide.
+//
+// AppKit's events are drained on a timer rather than by `[NSApp run]`, which would never hand the
+// thread back to bun. A menu held open or a window being resized runs AppKit's own loop inside one
+// drain, and the app answers nothing until it ends.
+
+import { FFIType } from 'bun:ffi'
+
+import {
+    callBlock,
+    created,
+    definedClass,
+    type Id,
+    nsBoolean,
+    nsString,
+    objcClass,
+    selector,
+    send,
+    sendTyped,
+    stringOf,
+} from './appKit.ts'
+import type { DesktopSession } from './DesktopSession.ts'
+import { reportUnexpected } from './hooks.ts'
+import type { Launcher } from './launcherOptions.ts'
+import { installMenu, menuBar, type NativeItem } from './nativeMenu.ts'
+
+const DRAIN_MILLISECONDS = 8
+
+/**
+ * Opens the app's window on a blank page and answers how to point it at an address.
+ *
+ * `base` is the launcher's own page, which the Connect… and Disconnect menu items lead back to.
+ * Quitting stops the session's app before the process ends (38.76).
+ */
+export function openDesktopWindow(
+    appName: string,
+    options: Launcher,
+    base: string,
+    session: DesktopSession,
+): (address: string) => void {
+    const application = send(objcClass('NSApplication'), 'sharedApplication')
+    // Regular: a Dock icon and a menu bar, which a process outside a `.app` does not get by default.
+    sendTyped(
+        application,
+        'setActivationPolicy:',
+        [FFIType.i64],
+        FFIType.void,
+        0,
+    )
+    let quitting = false
+    const quit = (): void => {
+        if (quitting) return
+        quitting = true
+        session.disconnect().finally(() => process.exit(0))
+    }
+    send(
+        application,
+        'setDelegate:',
+        send(
+            definedClass('AbideApplicationDelegate', {
+                'applicationShouldTerminate:': {
+                    types: 'Q@:@',
+                    args: [FFIType.ptr],
+                    returns: FFIType.u64,
+                    // NSTerminateCancel: 38.76 — the app is stopped first, and the process ends after.
+                    run: () => {
+                        quit()
+                        return 0
+                    },
+                },
+                'applicationShouldTerminateAfterLastWindowClosed:': {
+                    types: 'c@:@',
+                    args: [FFIType.ptr],
+                    returns: FFIType.bool,
+                    run: () => true,
+                },
+            }),
+            'new',
+        ),
+    )
+    for (const signal of ['SIGTERM', 'SIGINT'] as const)
+        process.on(signal, quit)
+    // A desktop app outlives a fault in it: it is reported, and the window stays.
+    process.on('unhandledRejection', reportUnexpected)
+    process.on('uncaughtException', reportUnexpected)
+
+    const window = created('NSWindow')
+    // Titled, closable, miniaturizable, resizable.
+    sendTyped(window, 'setStyleMask:', [FFIType.u64], FFIType.void, 15)
+    sendTyped(
+        window,
+        'setReleasedWhenClosed:',
+        [FFIType.bool],
+        FFIType.void,
+        false,
+    )
+    sendTyped(
+        window,
+        'setContentSize:',
+        [FFIType.f64, FFIType.f64],
+        FFIType.void,
+        options.width,
+        options.height,
+    )
+    sendTyped(
+        window,
+        'setContentMinSize:',
+        [FFIType.f64, FFIType.f64],
+        FFIType.void,
+        options.minWidth,
+        options.minHeight,
+    )
+    send(window, 'center')
+    // Where the window was and how large, as the last launch left it.
+    sendTyped(
+        window,
+        'setFrameAutosaveName:',
+        [FFIType.ptr],
+        FFIType.bool,
+        nsString(`${appName} window`),
+    )
+    send(window, 'setTitle:', nsString(appName))
+
+    const view = created('WKWebView')
+    send(
+        send(send(view, 'configuration'), 'preferences'),
+        'setValue:forKey:',
+        nsBoolean(true),
+        nsString('developerExtrasEnabled'),
+    )
+    if (
+        sendTyped(
+            view,
+            'respondsToSelector:',
+            [FFIType.ptr],
+            FFIType.bool,
+            selector('setInspectable:'),
+        )
+    )
+        sendTyped(view, 'setInspectable:', [FFIType.bool], FFIType.void, true)
+    send(view, 'setUIDelegate:', send(uiDelegateClass(), 'new'))
+    send(window, 'setContentView:', view)
+    send(
+        view,
+        'loadHTMLString:baseURL:',
+        nsString(
+            '<!doctype html><style>:root{color-scheme:light dark;background:#f5f5f7}@media (prefers-color-scheme:dark){:root{background:#1c1c1e}}</style>',
+        ),
+        null,
+    )
+    // 38.88 — THE MENU BAR IS THE PAGE'S: the defaults until the page the window loads tells it
+    // what its route exports, and again after every navigation it makes.
+    const showMenu = (told: NativeItem[]): void =>
+        installMenu(menuBar(appName, options.connect, told), (item) => {
+            if (item.role === 'connect')
+                return navigate(`${base}?focus=connect`)
+            // 38.74.
+            if (item.role === 'disconnect')
+                return void session.forget().then(() => navigate(base))
+            if (item.role === 'reload') return void send(view, 'reload')
+            // 38.90, 38.91 — the page that numbered the item does what it means.
+            if (item.id !== undefined)
+                send(
+                    view,
+                    'evaluateJavaScript:completionHandler:',
+                    nsString(
+                        `dispatchEvent(new CustomEvent('abide:menu', { detail: ${item.id} }))`,
+                    ),
+                    null,
+                )
+        })
+    send(
+        send(send(view, 'configuration'), 'userContentController'),
+        'addScriptMessageHandler:name:',
+        send(
+            definedClass('AbideMenuBridge', {
+                'userContentController:didReceiveScriptMessage:': {
+                    types: 'v@:@@',
+                    args: [FFIType.ptr, FFIType.ptr],
+                    returns: FFIType.void,
+                    run: (_controller: Id, message: Id) => {
+                        try {
+                            showMenu(
+                                JSON.parse(
+                                    stringOf(send(message, 'body')),
+                                ) as NativeItem[],
+                            )
+                        } catch (thrown) {
+                            reportUnexpected(thrown)
+                        }
+                    },
+                },
+            }),
+            'new',
+        ),
+        nsString('abideMenu'),
+    )
+    const navigate = (address: string): void => {
+        // 38.92.
+        showMenu([])
+        send(
+            view,
+            'loadRequest:',
+            send(
+                objcClass('NSURLRequest'),
+                'requestWithURL:',
+                send(objcClass('NSURL'), 'URLWithString:', nsString(address)),
+            ),
+        )
+    }
+    showMenu([])
+
+    send(window, 'makeKeyAndOrderFront:', null)
+    sendTyped(
+        application,
+        'activateIgnoringOtherApps:',
+        [FFIType.bool],
+        FFIType.void,
+        true,
+    )
+    send(application, 'finishLaunching')
+
+    const distantPast = send(objcClass('NSDate'), 'distantPast')
+    const defaultMode = nsString('kCFRunLoopDefaultMode')
+    let shownTitle = appName
+    let drains = 0
+    setInterval(() => {
+        for (;;) {
+            const event = sendTyped(
+                application,
+                'nextEventMatchingMask:untilDate:inMode:dequeue:',
+                [FFIType.u64, FFIType.ptr, FFIType.ptr, FFIType.bool],
+                FFIType.ptr,
+                0xffffffffffffffffn,
+                distantPast,
+                defaultMode,
+                true,
+            ) as Id
+            if (event === null) break
+            send(application, 'sendEvent:', event)
+        }
+        // The window is titled by the page it shows.
+        drains += 1
+        if (drains % 32 !== 0) return
+        const title = stringOf(send(view, 'title')) || appName
+        if (title === shownTitle) return
+        shownTitle = title
+        send(window, 'setTitle:', nsString(title))
+    }, DRAIN_MILLISECONDS)
+    return navigate
+}
+
+// What a page asks of its window: a link out opens in the browser, and `alert` and `confirm` are
+// sheets the page waits on.
+let uiDelegate: Id = null
+function uiDelegateClass(): Id {
+    uiDelegate ??= definedClass('AbideUIDelegate', {
+        'webView:createWebViewWithConfiguration:forNavigationAction:windowFeatures:':
+            {
+                types: '@@:@@@@',
+                args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+                returns: FFIType.ptr,
+                run: (_view: Id, _configuration: Id, action: Id) => {
+                    const url = send(send(action, 'request'), 'URL')
+                    if (url !== null)
+                        send(
+                            send(objcClass('NSWorkspace'), 'sharedWorkspace'),
+                            'openURL:',
+                            url,
+                        )
+                    return null
+                },
+            },
+        'webView:runJavaScriptAlertPanelWithMessage:initiatedByFrame:completionHandler:':
+            {
+                types: 'v@:@@@@?',
+                args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+                returns: FFIType.void,
+                run: (_view: Id, message: Id, _frame: Id, done: Id) => {
+                    alert(message, false)
+                    callBlock(done, [])
+                },
+            },
+        'webView:runJavaScriptConfirmPanelWithMessage:initiatedByFrame:completionHandler:':
+            {
+                types: 'v@:@@@@?',
+                args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+                returns: FFIType.void,
+                run: (_view: Id, message: Id, _frame: Id, done: Id) => {
+                    callBlock(done, [FFIType.bool], alert(message, true))
+                },
+            },
+    })
+    return uiDelegate
+}
+
+// An `NSAlert` with the page's message; answers whether it was accepted.
+function alert(message: Id, cancellable: boolean): boolean {
+    const panel = created('NSAlert')
+    send(panel, 'setMessageText:', message)
+    send(panel, 'addButtonWithTitle:', nsString('OK'))
+    if (cancellable) send(panel, 'addButtonWithTitle:', nsString('Cancel'))
+    // NSAlertFirstButtonReturn.
+    return (
+        Number(sendTyped(panel, 'runModal', [], FFIType.i64) as bigint) === 1000
+    )
+}

package/src/server/preload.ts

@@ -5,6 +5,10 @@
 // one place that runs first. The build is `createApp`'s own under `bun test` (42.16), so a test that
 // boots the app afterwards reuses it rather than building twice.
 
+import { beforeEach } from 'bun:test'
+
+import { invalidate } from '#shared/reactive/index.ts'
+
 import { processBuild, servedBuild, spawnedBuild } from './appBuild.ts'
 import { addDerived } from './config.ts'
 import { appRoot } from './createApp.ts'
@@ -20,6 +24,20 @@ const root = appRoot(undefined)
 if (root !== undefined && !(await isWorkspaceRoot(root)))
     await servedBuild(root, await processBuild(root, true), spawnedBuild)
 
+// 38.133 — EACH TEST FILE STARTS COLD: a handler's answer another file settled is otherwise served
+// at once to the next file in the process, so a file's tests pass or fail by the order `bun test`
+// happened to run the files in. Bun has no per-file hook a preload can register, so a test's own
+// `beforeEach` notices the file change through `Bun.main`. Outside the test runner — a bench or a
+// script importing `mount`'s module — there is no runner to register with, and nothing to reset.
+let fileUnderTest: string | undefined
+try {
+    beforeEach(() => {
+        if (Bun.main === fileUnderTest) return
+        if (fileUnderTest !== undefined) invalidate()
+        fileUnderTest = Bun.main
+    })
+} catch {}
+
 async function isWorkspaceRoot(directory: string): Promise<boolean> {
     const manifest = Bun.file(`${directory}/package.json`)
     if (!(await manifest.exists())) return false

package/src/server/principal.ts

@@ -18,10 +18,10 @@ import { PRINCIPAL_HEADER } from '#shared/PRINCIPAL_HEADER.ts'
 import { refuse } from '#shared/refuse.ts'
 import { declare } from '#shared/rpc.ts'
 
-import { mountedOwn } from './answerRpc.ts'
 import { callerOf, callerOrMint, mintCaller } from './callerOf.ts'
 import { config, positiveSetting } from './config.ts'
 import { HOOKS, inOrder } from './hooks.ts'
+import { mountedOwn } from './mountHandlers.ts'
 import { type RequestScope, type Sealed, within } from './requestScope.ts'
 import { signInChanged } from './signInChanged.ts'
 

package/src/server/remote.ts

@@ -12,8 +12,8 @@ import { rankRoutes } from '#shared/routePattern.ts'
 import type { Method } from '#shared/rpc.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 
-import type { Mount } from './answerRpc.ts'
 import { DEFAULT_PORT } from './DEFAULT_PORT.ts'
+import type { Mount } from './mountHandlers.ts'
 import { withoutTrailingSlash } from './withoutTrailingSlash.ts'
 
 /**

package/src/server/render.ts

@@ -4,14 +4,14 @@
 /// <reference path="./componentModules.d.ts" />
 
 import { regionMarkup } from '#shared/anchorMarkup.ts'
-import { EARLY_CALLS } from '#shared/EARLY_CALLS.ts'
 import { headKeyOf } from '#shared/headKeyOf.ts'
 import { isThenable } from '#shared/reactive/isThenable.ts'
+import { runInScope } from '#shared/reactive/scoping.ts'
 import type { ShareScope } from '#shared/reactive/share.ts'
 import { setUpLevels } from '#shared/setUpLevels.ts'
 
-import { buildDeferred, markPainted } from './deferredBuilds.ts'
-import { currentRequestScope, type PageCall } from './requestScope.ts'
+import { buildDeferred } from './deferredBuilds.ts'
+import { currentRequestScope } from './requestScope.ts'
 
 /**
  * A compiled component, opaque to an app.
@@ -265,23 +265,42 @@ function dropAtHeadTop(
  * is bound the same way, with the failure where a page has its params.
  */
 export function boundPage(
-    page: {
-        load: () => Promise<{ default: Component }>
-        layouts: (() => Promise<{ default: Component }>)[]
-    },
+    page: PageModules,
     props: Record<string, () => unknown>,
 ): () => Promise<unknown> {
     return async () => {
-        const [loadedPage, loadedLayouts] = await Promise.all([
-            page.load(),
-            Promise.all(page.layouts.map((layout) => layout())),
-        ])
+        const [loadedPage, loadedLayouts] = await runInScope(
+            undefined,
+            loadedModules,
+            page,
+        )
         const layouts: Component[] = []
         for (const module of loadedLayouts) layouts.push(module.default)
         return composePage(layouts, loadedPage.default, props)
     }
 }
 
+type PageModules = {
+    load: () => Promise<{ default: Component }>
+    layouts: (() => Promise<{ default: Component }>)[]
+}
+
+/**
+ * A page's module and its layouts', imported OUTSIDE EVERY REQUEST — 11.67. A module is evaluated in
+ * the async context its `import()` was called from, so the first request to reach a page evaluated
+ * it, and every module it imports, inside that request's scope: a module's `reactive` saw a scope at
+ * construction, was built as that request's own rather than as a forwarder (`scoped.ts`), and every
+ * later request read what the first one left.
+ */
+function loadedModules(
+    page: PageModules,
+): Promise<[{ default: Component }, { default: Component }[]]> {
+    return Promise.all([
+        page.load(),
+        Promise.all(page.layouts.map((layout) => layout())),
+    ])
+}
+
 /**
  * The document's bytes: `component` rendered into abide's own document (35.6).
  *
@@ -326,10 +345,7 @@ export async function renderDocument(
     // 41.20 — THE PAGE'S CALLS LEAVE AHEAD OF ITS MARKUP. Setup has run, so every call the page
     // makes is known, and a script in the head starts each one as the request the browser's own
     // `Rpc` would make — while the rest of the document and the bundle are still on their way.
-    const calls = currentRequestScope()?.page?.calls
-    if (calls !== undefined) markPainted(calls)
-    const early =
-        calls !== undefined && calls.length > 0 ? earlyCallScript(calls) : ''
+    const early = currentRequestScope()?.page?.earlyCallScript() ?? ''
     // 39.4 — THE SHELL IS THE OUTERMOST CONTRIBUTOR, so its head is merged with the page's in the
     // one pass that merges the levels'.
     //
@@ -342,50 +358,6 @@ export async function renderDocument(
     )
 }
 
-/**
- * The head markup that starts each of the page's calls before the bundle arrives.
- *
- * 41.20 — THE SCRIPT ITSELF: each call started with `fetch`, and its answer left under the call's
- * key in `EARLY_CALLS` for `wire` to take (41.21). An answer's body is left UNREAD (16.32), so a
- * streaming handler's copy takes its chunks as they land rather than after the last one.
- * Inline because nothing else runs before the bundle has arrived, which is the wait it exists to
- * overlap.
- *
- * 41.25 — A ROW ENDING IN `1` IS A CALL THE MARKUP WAS BUILT FROM SETTLED, a refusal included, and
- * its entry is marked `painted` for hydration to wait on — its body read to its bytes, so the wait
- * covers it too. Marked as each pass of the markup is built (`markPainted`), not here. 41.26 — A CALL THAT STREAMS IS NEVER MARKED: the
- * browser reads its chunks as they land (16.32), so no wait for its answer makes it settled where
- * the page hydrates, and its region is 41.24's to put right.
- *
- * 29.9, 29.10 — THE CALLS ARE DATA AND THE RUNNER IS A CONSTANT. What a page called differs per
- * response, so it rides in a JSON block a browser never executes, and the one script that does run
- * is the same bytes in every response — which is what lets `csp` permit it by its hash rather than
- * by the nonce an app's own inline script spends. The JSON has `<` escaped, so no string in it can
- * close the element.
- */
-function earlyCallScript(calls: PageCall[]): string {
-    const rows: (
-        [string, string, RequestInit] | [string, string, RequestInit, 1]
-    )[] = []
-    for (const { request, painted } of calls)
-        rows.push(
-            painted === true
-                ? [request.key, request.url, request.init, 1]
-                : [request.key, request.url, request.init],
-        )
-    return `<script type="application/json">${JSON.stringify(rows).replace(/</g, '\\u003c')}</script><script>${EARLY_CALL_RUNNER}</script>`
-}
-
-// THE RUNNER RECORDS, IT NEVER CLASSIFIES: the `Response`, and a painted call's body read to its end
-// — the one decision is `painted`, which the server made. `answerOf` reads the record as it reads an
-// answer it fetched, so no second reading of a content type lives in a string no typecheck reaches.
-// The shape is `EarlyCall`'s. 16.80 — a page the worker answers has it answer the page's calls too,
-// which the browser alone can tell: the server cannot see whether a worker will replay this page.
-export const EARLY_CALL_RUNNER = `(function(s,c,w){for(var i=0;i<c.length;i++)(function(k,u,n,h){if(w)n.cache='force-cache';var e=s[k]={painted:h,response:void 0,bytes:void 0};e.promise=fetch(u,n).then(function(r){return h?r.arrayBuffer().then(function(b){e.bytes=b;e.response=r}):e.response=r}).catch(function(){})})(c[i][0],c[i][1],c[i][2],c[i][3])})(self.${EARLY_CALLS}||(self.${EARLY_CALLS}={}),JSON.parse(document.currentScript.previousElementSibling.textContent),(self.navigator.serviceWorker||{}).controller)`
-
-/** The early-call runner's hash, as `script-src` names it. 29.9. */
-export const EARLY_CALL_HASH = `'sha256-${new Bun.CryptoHasher('sha256').update(EARLY_CALL_RUNNER).digest('base64')}'`
-
 /** Where the body's content ends, which is where a page's markup goes. */
 function bodyAnchor(document: string): number {
     const found = document.lastIndexOf('</body>')

package/src/server/requestScope.ts

@@ -16,10 +16,11 @@ import type { Framed } from '#shared/framing.ts'
 import type { Params } from '#shared/matchRoute.ts'
 import type { Principal } from '#shared/principal.ts'
 import { type Scope, SCOPING } from '#shared/reactive/scoping.ts'
-import type { RpcRequest } from '#shared/rpcRequest.ts'
 
+import type { Followers } from './Followers.ts'
 import type { McpSurface } from './generatedSurfaces.ts'
 import { IDLE_TIMEOUT_SECONDS } from './IDLE_TIMEOUT_SECONDS.ts'
+import type { PageRender } from './PageRender.ts'
 
 /** The three framings a stream is answered in. 17.6. */
 export type Framing = Framed | 'bytes'
@@ -81,7 +82,7 @@ export type RequestScope = Scope & {
     /** What a write through `response` is collected onto, for whoever answers to apply. 22.9. */
     response: { status: number; headers: Headers }
     /**
-     * The page this scope is rendering, which its calls report into.
+     * The page this scope is rendering, which its calls report into (`PageRender.ts`).
      *
      * 41.13, 41.20 — `undefined` in every scope but a page's.
      */
@@ -103,19 +104,6 @@ export type RequestScope = Scope & {
     }
 }
 
-/**
- * A page's render, as its calls see it: the seed sink and the requests the browser will make.
- *
- * The seed buffer's sink for this caller (41.13), and the requests the browser will make for the
- * calls, for the early-call script (41.20). ON THE SCOPE because that is the only thing a call made
- * deep in a page's setup can find it through when requests interleave — `RPC_SERVER.reached` is
- * one slot for every request in flight.
- */
-export type PageRender = {
-    seed: (rpc: object, args: unknown, reached: unknown) => boolean
-    calls: PageCall[]
-}
-
 /** An app as the scopes it opens hold it: what answers a request in it, and its MCP surface. */
 export type AnsweringApp = {
     answer: (request: Request) => Promise<Response>
@@ -125,17 +113,8 @@ export type AnsweringApp = {
      * still being written, a seed entry and its timer. 42.11 — `App.stop` ends every one.
      */
     held: Set<() => void>
-}
-
-/**
- * One call a page's render made: the request the browser will make for it, what it reached, and
- * whether the markup was built from it settled — `undefined` until the pass that built from it
- * ends (41.25, `markPainted`).
- */
-export type PageCall = {
-    request: RpcRequest
-    reached: unknown
-    painted: boolean | undefined
+    /** Every subscription to this app's handlers, over its mux or as an event stream. 18.3. */
+    followers: Followers
 }
 
 // `undefined` IS A STORE, not the absence of one: a value built outside every request runs its body
@@ -327,16 +306,6 @@ export const LISTENING: {
         LISTENING.server?.timeout(received, seconds),
 }
 
-/**
- * Sets what the calls a render makes report into, on the request's own scope.
- *
- * 41.13 — set before the render runs: a page's render passes one, and an error page's none. The
- * render is awaited where the request is answered, so it runs in that scope throughout (42.6).
- */
-export function beginRender(page: PageRender | undefined): void {
-    ;(STORAGE.getStore() as RequestScope).page = page
-}
-
 /** The scope a request or `App.run` opened, or `undefined` outside every one. */
 export function currentRequestScope(): RequestScope | undefined {
     return STORAGE.getStore()