@abide/abide 0.102.0 → 0.103.0

package/src/server/createApp.ts

@@ -14,7 +14,7 @@ import { servedTable } from './abideModules.ts'
 import { type AppSources, answerRequest } from './answerRequest.ts'
 import { Mux, type MuxConnection } from './answerSocket.ts'
 import { appDirectories } from './appDirectories.ts'
-import { holdsAbide } from './appTree.ts'
+import { holdsApp } from './appTree.ts'
 import { buildDirectory } from './buildDirectory.ts'
 import { APP_PACKAGE, type AppPackage, config, packageUnder } from './config.ts'
 import { McpSurface } from './generatedSurfaces.ts'
@@ -65,21 +65,33 @@ export async function createApp(): Promise<App> {
         throw new Error(
             `abide: createApp found no app. Looked for a .abide under ${resolve('src')}, or under ${process.cwd()} where it has no src.`,
         )
-    // 42.16 — under `bun test` the app is built for its sources as they stand rather than read off
-    // whatever `abide build` last left, which a test run would otherwise need first and could find
-    // stale.
-    const out =
-        process.env.NODE_ENV === 'test'
-            ? await testBuild(root)
-            : buildDirectory(root)
-    const { loadBuild, serveBuild } = await import('./serveBuild.ts')
-    if (!(await serveBuild(root, out)))
+    const out = await servedBuild(root)
+    if (out === undefined)
         throw new Error(
             `abide: createApp found nothing under ${root} to build.`,
         )
+    const { loadBuild } = await import('./serveBuild.ts')
     return bootApp(originUnder(root), () => loadBuild({ root, out }))
 }
 
+/**
+ * The build of the app under `root`, served to this process's imports — or `undefined` where
+ * nothing under it builds. `fresh` builds it for its sources as they stand.
+ *
+ * 42.16 — under `bun test` the app is built for its sources as they stand rather than read off
+ * whatever `abide build` last left, which a test run would otherwise need first and could find
+ * stale. One answer for `createApp` and the test preload (38.109), so a test that boots the app
+ * reuses the build its imports were served from.
+ */
+export async function servedBuild(
+    root: string,
+    fresh = process.env.NODE_ENV === 'test',
+): Promise<string | undefined> {
+    const out = fresh ? await testBuild(root) : buildDirectory(root)
+    const { serveBuild } = await import('./serveBuild.ts')
+    return (await serveBuild(root, out)) ? out : undefined
+}
+
 /**
  * The app's root — `--root`, else `src` where the working directory holds one, else the working
  * directory — or `undefined` where it is no app's.
@@ -99,7 +111,7 @@ export function appRoot(given: string | undefined): string | undefined {
     let packaged = false
     for (const directory of appDirectories(root))
         packaged ||= existsSync(`${directory}/package.json`)
-    return packaged && holdsAbide(root) ? root : undefined
+    return packaged && holdsApp(root) ? root : undefined
 }
 
 /**

package/src/server/devWorker.ts

@@ -378,7 +378,11 @@ async function open(
             bundleInMemory(
                 root,
                 // 16.28, 16.29 — the browser's view of the server, as `abide build` gives it.
-                [fenceServer(root), abideModules(root, compilation), ...own],
+                [
+                    fenceServer(root, compilation.mounted),
+                    abideModules(root, compilation),
+                    ...own,
+                ],
                 paged,
                 publicAddresses,
                 compilation,

package/src/server/fenceServer.ts

@@ -1,7 +1,8 @@
 // 16.29 — WHAT THE BROWSER'S BUNDLE SEES OF THE SERVER: nothing under a `server` directory, at any
 // depth, so a secret or a database client cannot ride into the browser by being imported from the
-// wrong file. A handler crosses as the wrapper its file's browser module carries in place of the
-// server block (34.23), which the compiler wrote; this is the fence around everything else.
+// wrong file. A handler crosses as the wrapper the compiler wrote in its place — a handler file as
+// that file, a private handler in its server block's place (16.28); this is the fence around
+// everything else.
 //
 // A PLUGIN ON THE BUNDLE, NOT A REWRITE OF THE PAGES. A rewrite reaches the specifiers the compiler
 // emitted; the bundle reaches every edge — a helper the page imports, importing a server module,
@@ -9,11 +10,16 @@
 //
 // REGISTERED AHEAD OF `abideModules`, AND IN ITS NAMESPACES: a load is answered by the first plugin
 // that answers it, and a component or a file's text is loaded there rather than as a `file`.
+//
+// BY POSITION, NOT BY PATH (23.19): a directory a file mounts places its files where the app says,
+// so a `server` directory inside it is fenced as the app's own would be, wherever the package lies.
 
+import { resolve } from 'node:path' // bun exposes no path helpers of its own
 import { SERVER_DIRECTORY } from '#shared/RESERVED_DIRECTORIES.ts'
 import { placeOf } from '#shared/routePattern.ts'
 import {
     COMPONENT_NAMESPACE,
+    type Compilation,
     STYLE_NAMESPACE,
     TEXT_NAMESPACE,
 } from './abideModules.ts'
@@ -25,24 +31,41 @@ const FENCED = ['file', COMPONENT_NAMESPACE, TEXT_NAMESPACE, STYLE_NAMESPACE]
 /**
  * The bundler plugin refusing everything under a `server` directory to the browser's bundle.
  *
- * `root` is its real path (`appRoot`), which is how the bundler names a file. Listed before
- * `abideModules`.
+ * `root` is its real path (`appRoot`), which is how the bundler names a file; `mounted` is the
+ * compilation's. Listed before `abideModules`.
  */
-export function fenceServer(root: string): Bun.BunPlugin {
-    // Anything with a `server` directory in its path below the root, and `placeOf` decides — a load
-    // it passes on falls through to the next plugin's, or the bundler's own.
-    const filter = new RegExp(
-        `^${RegExp.escape(root)}/(?:.*/)?${SERVER_DIRECTORY}/`,
-    )
+export function fenceServer(
+    root: string,
+    mounted: Compilation['mounted'],
+): Bun.BunPlugin {
+    // Mounted directories first: one under the root's `node_modules` is the app's at its position.
+    const directories: [string, string][] = []
+    for (const [directory, at] of Object.entries(mounted))
+        directories.push([`${resolve(root, directory)}/`, at])
+    const positionOf = (path: string): string | undefined => {
+        for (const [directory, at] of directories)
+            if (path.startsWith(directory))
+                return `${at}${path.slice(directory.length)}`
+        return path.startsWith(`${root}/`)
+            ? path.slice(root.length + 1)
+            : undefined
+    }
+    // Anything with a `server` directory in its path, and `placeOf` decides by its position — a
+    // load it passes on falls through to the next plugin's, or the bundler's own.
+    const filter = new RegExp(`/${SERVER_DIRECTORY}/`)
     return {
         name: 'abide-fence',
         setup(build) {
             for (const namespace of FENCED)
                 build.onLoad({ filter, namespace }, (args) => {
-                    const below = args.path.slice(root.length + 1)
-                    if (placeOf(below) !== 'server') return undefined
+                    const position = positionOf(args.path)
+                    if (
+                        position === undefined ||
+                        placeOf(position) !== 'server'
+                    )
+                        return undefined
                     throw new Error(
-                        `abide: ${below.replace(/::\w+$/, '')} is under a server directory, and the browser's bundle imports it. RULEBOOK 16.29.`,
+                        `abide: ${position.replace(/::\w+$/, '')} is under a server directory, and the browser's bundle imports it. RULEBOOK 16.29.`,
                     )
                 })
         },

package/src/server/hooks.ts

@@ -1,5 +1,5 @@
-// SECTION 37 — THE LIFECYCLE HOOKS, called from a page's or a layout's `<script server>` rather
-// than exported from it (37.1). Each call files its function here, at the ROUTE of the file that
+// SECTION 37 — THE LIFECYCLE HOOKS, called from a `.abide`'s `<script server>` or a handler file
+// rather than exported from it (37.1). Each call files its function here, at the ROUTE of the file that
 // called it, and hands back what unfiles it; `createApp` reads what is filed once every module
 // holding a server block has run.
 //
@@ -22,6 +22,7 @@ import {
 } from '#shared/routePattern.ts'
 import type { Schema } from '#shared/Schema.ts'
 import { config } from './config.ts'
+import type { LauncherOptions } from './launcherOptions.ts'
 import { currentRequestScope } from './requestScope.ts'
 
 export type AppRung = Middleware<{ request: Request }, Response>
@@ -51,17 +52,20 @@ export const HOOKS = {
         options: ConfigOptions | undefined
     }>[],
     principal: [] as Filed<(claims: unknown) => unknown | Promise<unknown>>[],
+    launcher: [] as Filed<() => LauncherOptions>[],
 }
 
 const ROOT = '/'
 
-// The route a hook called now is filed at — the server block being evaluated, or the root.
+// The route a hook called now is filed at — the server block or handler file being evaluated, or
+// the root.
 let filing: string | undefined
 
 /**
  * Sets the route the hooks called next are filed at, or the root again for `undefined`.
  *
- * 37.1 — what a compiled server module calls around its `<script server>`; nothing an app writes.
+ * 37.1 — what a compiled server module calls around its `<script server>`, and the plugin around a
+ * handler file; nothing an app writes.
  */
 export function fileRoute(route: string | undefined): void {
     filing = route
@@ -208,6 +212,15 @@ export function onPrincipal(
     return filed(HOOKS.principal, resolve)
 }
 
+/**
+ * Files what the desktop app's window and launcher are; returns what unfiles it.
+ *
+ * 38.80 — called in `src/launcher.abide` alone (38.107), and read as the app launches.
+ */
+export function onLauncher(options: () => LauncherOptions): () => void {
+    return filed(HOOKS.launcher, options)
+}
+
 /**
  * Logs an unexpected error and hands it to every `onError` hook.
  *

package/src/server/index.ts

@@ -58,6 +58,7 @@ export {
     onConfig,
     onError,
     onHealth,
+    onLauncher,
     onPrincipal,
     onStart,
     onStop,

package/src/server/installSourceMaps.ts

@@ -7,6 +7,7 @@
 // rebuild, and a test boots several apps in one process.
 
 import { resolve } from 'node:path' // bun exposes no path helpers of its own
+import { HANDLER_FACE } from './MODULE_QUERIES.ts'
 import { decodeMappings, placeAt, type Segment } from './sourceMappings.ts'
 
 /** Per `.abide` below the root, as its server module is served there: the file, and its `mappings`. */
@@ -63,7 +64,11 @@ function placeFrames(error: Error, frames: CallSite[]): string {
 
 // A call site's column counts from 0 where the stack bun writes counts from 1.
 function placed(frame: CallSite): string {
-    const file = frame.getFileName() ?? '<anonymous>'
+    // A handler file's frames name the file the author wrote, not the face it is served as.
+    const file = (frame.getFileName() ?? '<anonymous>').replace(
+        HANDLER_FACE,
+        '',
+    )
     const line = frame.getLineNumber() ?? 0
     const column = frame.getColumnNumber() ?? 0
     const registered = registeredFor(file)

package/src/server/launcherOptions.ts

@@ -1,12 +1,11 @@
-// 38.80 — THE `launcher` A `src/launcher.abide`'S `<script module>` EXPORTS: the window the desktop
-// app opens and the forms its launcher offers. 34.32 — read off the module as the app launches,
-// never by evaluating it during the bundle.
+// 38.80 — WHAT THE `onLauncher` A `src/launcher.abide` CALLS ANSWERS: the window the desktop app opens
+// and the forms its launcher offers, read as the app launches.
 
 import { isRecord } from '#shared/isRecord.ts'
 
 /**
- * What the `launcher` export may set. 38.81 — turning off both forms is not one of them, so the
- * checker refuses it where the export is typed.
+ * What `onLauncher` may answer. 38.81 — turning off both forms is not one of them, so the checker
+ * refuses it where the answer is typed.
  */
 export type LauncherOptions = {
     width?: number
@@ -29,10 +28,10 @@ const SIZES = ['width', 'height', 'minWidth', 'minHeight'] as const
 const FORMS = ['start', 'connect'] as const
 
 /**
- * The launcher `exported` sets, or the refusal naming what is wrong with it — the export read at
- * run time, where an untyped one can still name a key it does not take.
+ * The launcher what `onLauncher` answered sets, or the refusal naming what is wrong with it — read
+ * at run time, where an untyped answer can still name a key it does not take.
  */
-export function launcherOf(exported: unknown): Launcher | string {
+export function launcherOf(answered: unknown): Launcher | string {
     const launcher: Launcher = {
         width: 1100,
         height: 760,
@@ -41,9 +40,9 @@ export function launcherOf(exported: unknown): Launcher | string {
         start: true,
         connect: true,
     }
-    if (exported === undefined) return launcher
-    if (!isRecord(exported)) return '`launcher` is an object'
-    for (const [key, value] of Object.entries(exported)) {
+    if (answered === undefined) return launcher
+    if (!isRecord(answered)) return '`onLauncher` answers an object'
+    for (const [key, value] of Object.entries(answered)) {
         if (
             (SIZES as readonly string[]).includes(key) &&
             typeof value === 'number' &&
@@ -56,10 +55,10 @@ export function launcherOf(exported: unknown): Launcher | string {
         )
             launcher[key as (typeof FORMS)[number]] = value
         else
-            return `\`launcher.${key}\` is not a launcher option, or ${JSON.stringify(value)} is not a value it takes`
+            return `\`${key}\` is not a launcher option, or ${JSON.stringify(value)} is not a value it takes`
     }
     // 38.81.
     if (!launcher.start && !launcher.connect)
-        return '`launcher` turns off both start and connect, which leaves the launcher nothing to do'
+        return '`onLauncher` turns off both start and connect, which leaves the launcher nothing to do'
     return launcher
 }

package/src/server/launcherPage.ts

@@ -21,9 +21,9 @@ const SYSTEM_ACCENT = '#0a84ff'
 export type Launch = {
     /** The app's name, as its package gives it. */
     name: string
-    /** Where the start form posts, or `undefined` where the `launcher` export turns starting off. */
+    /** Where the start form posts, or `undefined` where what `onLauncher` answers turns starting off. */
     start: string | undefined
-    /** Where the connect form posts, or `undefined` where the `launcher` export turns connecting off. */
+    /** Where the connect form posts, or `undefined` where what `onLauncher` answers turns connecting off. */
     connect: string | undefined
     fields: ConfigField[]
     /** The URL the last connect was given. */

package/src/server/nativeMenu.ts

@@ -1,5 +1,5 @@
-// THE DESKTOP APP'S MENU BAR (38.88): the default, with what the page the window shows exports,
-// built as an `NSMenu`.
+// THE DESKTOP APP'S MENU BAR (38.88): the default, with the menus the standing layouts and page file
+// with `onMenu`, built as an `NSMenu`.
 
 import { FFIType } from 'bun:ffi'
 import type { MenuRole } from '#shared/menuItem.ts'
@@ -77,7 +77,7 @@ const NAMED_KEYS: Record<string, string> = {
  * The menu bar the window shows: the application, File, Edit, View and Window menus, and `added`.
  *
  * 38.88 — AN ADDED MENU NAMED AS A DEFAULT ONE GROWS IT, and any other stands before Window, where
- * the platform puts an app's own. 38.83 — no Connect… where the `launcher` export turns connecting off.
+ * the platform puts an app's own. 38.83 — no Connect… where what `onLauncher` answers turns connecting off.
  */
 export function menuBar(
     appName: string,

package/src/server/preload.ts

@@ -0,0 +1,13 @@
+// 38.109 — `@abide/abide/test`, PRELOADED BY `bun test`: the app's compilation served before any test
+// file is loaded, so a test imports a `.abide` as any module — beside the code it tests, at the top
+// of the file, with no `createApp` run first. Bun loads every import of a file before it evaluates
+// any, so registering the compilation from inside a test is always too late; a preload is the
+// 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 { appRoot, servedBuild } from './createApp.ts'
+
+const root = appRoot(undefined)
+// A run from a directory that holds no app — a workspace's root — preloads nothing.
+// Fresh whatever `NODE_ENV` says: `bun test` sets it only where nothing else has.
+if (root !== undefined) await servedBuild(root, true)

package/src/server/runDesktop.ts

@@ -26,7 +26,7 @@ import { APP_PACKAGE, configuredMount, dataDirectory } from './config.ts'
 import { configFields } from './configFields.ts'
 import { type App, type AppOrigin, bootApp } from './createApp.ts'
 import { executableName } from './executableName.ts'
-import { reportUnexpected } from './hooks.ts'
+import { HOOKS, inOrder, reportUnexpected } from './hooks.ts'
 import { installServer } from './installServer.ts'
 import { launcherOf } from './launcherOptions.ts'
 import { type Launch, launcherPage } from './launcherPage.ts'
@@ -53,15 +53,10 @@ type Failure = {
 
 /** What `abide bundle` read of the launcher's files, carried in the executable. */
 export type Desktop = {
-    /** 38.80 — `src/launcher.abide`, where the app has one: its `launcher`, and its page. */
+    /** 38.82 — `src/launcher.abide`'s page, where the app has one that paints. */
     launch:
-        | (() => Promise<{
-              default: (props: Launch) => Component
-              launcher?: unknown
-          }>)
+        | (() => Promise<{ default: (props: Launch) => Component }>)
         | undefined
-    /** 38.82 — whether that file has markup of its own, which then stands in for the built-in page. */
-    custom: boolean
     /** The document the launch page renders into, its stylesheet already in its head (38.84). */
     document: string
     /** 38.101 — the app's icon as a data URL, and the accent taken from it. */
@@ -87,23 +82,23 @@ export async function runDesktop(
 async function launch(
     origin: AppOrigin,
     load: () => ReturnType<typeof builtSources>,
-    { launch: launchModule, custom, document, icon, accent }: Desktop,
+    { launch: launchModule, document, icon, accent }: Desktop,
 ): Promise<void> {
     installServer()
     APP_PACKAGE.current = origin.package
-    // 37.1 — imported for what it files, so the start form reads `onConfig`.
+    // 37.1 — imported for what it files, so the start form reads `onConfig` and the launcher's
+    // `onLauncher` is filed.
     await origin.hooks?.()
-    // 34.32 — the `launcher` export, read off its module as the app launches. 38.85 — one that fails
-    // to load leaves the built-in page, with its defaults.
-    const launcherModule = await launchModule?.().catch((thrown: unknown) => {
+    // 38.85 — a launcher page that fails to load leaves the built-in page, with its defaults.
+    const launchPage = await launchModule?.().catch((thrown: unknown) => {
         reportUnexpected(thrown)
         return undefined
     })
-    const options = launcherOf(launcherModule?.launcher)
-    // 38.81 — a `launcher` the checker would have refused, written where nothing checked it.
+    // 38.80 — what its `onLauncher` answers.
+    const options = launcherOf(inOrder(HOOKS.launcher).at(-1)?.())
+    // 38.81 — an `onLauncher` answer the checker would have refused, written where nothing checked it.
     if (typeof options === 'string')
         throw new Error(`abide: ${options}. RULEBOOK 38.81.`)
-    const launchPage = custom ? launcherModule : undefined
     const appName = executableName(origin.package.name)
     const directory = dataDirectory(origin.package.name ?? 'app')
     const stateFile = `${directory}/desktop.json`

package/src/server/serveDev.ts

@@ -22,6 +22,7 @@ import { watch } from 'node:fs' // bun exposes no file watcher of its own
 import { dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
 import {
     type AppChecker,
+    compilationOf,
     compileApp,
     openChecker,
 } from '#compiler/compileApp.ts'
@@ -144,7 +145,7 @@ export async function serveDev(
                 console.warn(formatDiagnosis(warning, process.cwd()))
             watchDependencies(compiled.files)
             return {
-                compilation: { files: compiled.files, tables: compiled.tables },
+                compilation: compilationOf(compiled),
                 published: compiled.published,
                 failure: '',
             }
@@ -154,7 +155,12 @@ export async function serveDev(
                 thrown instanceof Error ? thrown.message : String(thrown)
             console.error(`abide dev: ${failure}`)
             return {
-                compilation: { files: {}, tables: {} },
+                compilation: {
+                    files: {},
+                    handlers: {},
+                    tables: {},
+                    mounted: {},
+                },
                 published: new Map(),
                 failure,
             }

package/src/server/surfaceOf.ts

@@ -31,6 +31,8 @@ export function surfaceOf(
     mount: Mount | Mounted,
     surface: Surface,
 ): Listed | undefined {
+    // 16.71 — a private handler is its file's alone.
+    if (mount.private) return undefined
     const live = 'handler' in mount ? mount : undefined
     // 16.37 — what its `clients` says, and the build's default where it says nothing.
     const carried =

package/src/server/withAbideSources.ts

@@ -96,7 +96,7 @@ export async function withAbideSources(
 }
 
 /**
- * 16.28, 34.20 — the `.abide`'s text with every `<script server>` body blanked: the map is served
+ * 16.28, 34.19 — the `.abide`'s text with every `<script server>` body blanked: the map is served
  * to a browser, which reads none of one. Each line is kept, so every line the map places is still
  * the line it names.
  */

package/src/shared/ADDRESSES.ts

@@ -24,6 +24,9 @@ export const ABIDE_ADDRESS = '/__abide'
  */
 export const CLIENT_ADDRESS = `${ABIDE_ADDRESS}/client`
 
+/** Where a private handler is answered, below its file's path and then its name (16.70). */
+export const PRIVATE_HANDLERS_ADDRESS = `${ABIDE_ADDRESS}/handlers`
+
 // 20.5, 20.9, 36.7 — the generated surfaces, which the CLI reaches as well as the server answers.
 
 /** The generated OpenAPI document. */

package/src/shared/LAUNCHER_FILES.ts

@@ -0,0 +1,9 @@
+// THE DESKTOP LAUNCHER'S FILES. Its page, which calls `onLauncher`, sits at the app's root beside the
+// root layout, a name the framework finds rather than a page (23.21); the icon is a public file,
+// so it is wherever the address it answers at says (36.11).
+
+/** The `.abide` the desktop launcher renders, at the root alone. 38.80, 38.82. */
+export const LAUNCHER_PAGE = 'launcher.abide'
+
+/** The addresses of the desktop app's icon, the `.icns` first. 38.79. */
+export const ICON_ADDRESSES = { icns: '/icon.icns', png: '/icon.png' } as const

package/src/shared/RESERVED_DIRECTORIES.ts

@@ -1,6 +1,7 @@
-// THE TWO DIRECTORY NAMES THAT ARE NEVER AN ADDRESS (23.15): `server` fences a graph (16.29) and
-// `public` is answered as authored (36.11). Every other directory under the root is a segment of the
-// address of the `page.abide`, `layout.abide` and `error.abide` in it (23.14).
+// THE FENCES: the four directory names that are never an address (23.15). `server` fences a graph
+// (16.29), `public` is answered as authored (36.11), and `lib` and `tests` hold what is neither an
+// address nor either of those. Every other directory under the root is a segment of the routes of
+// the files directly in it (23.14), and holds nothing else (23.22).
 
 /** A module under one only the server loads. */
 export const SERVER_DIRECTORY = 'server'
@@ -8,8 +9,16 @@ export const SERVER_DIRECTORY = 'server'
 /** A file under one is answered as authored, at the path above it. */
 export const PUBLIC_DIRECTORY = 'public'
 
-/** Both, as the walk of the app tests a directory against them. */
+/** The app's own code that is no address: components, modules, both sides. */
+export const LIB_DIRECTORY = 'lib'
+
+/** The app's tests. */
+export const TESTS_DIRECTORY = 'tests'
+
+/** All four, as the walk of the app tests a directory against them. */
 export const RESERVED_DIRECTORIES: ReadonlySet<string> = new Set([
     SERVER_DIRECTORY,
     PUBLIC_DIRECTORY,
+    LIB_DIRECTORY,
+    TESTS_DIRECTORY,
 ])

package/src/shared/index.ts

@@ -36,13 +36,14 @@ export { listOf } from './listOf.ts'
 export { type Logger, type LogRecord, log } from './log.ts'
 export type { Middleware } from './Middleware.ts'
 export type { Params } from './matchRoute.ts'
-// 38.88 — a desktop app's menu items, exported by the route's layouts and page.
+// 38.88 — a desktop app's menu items, and the hook a route's layouts and page file them with.
 export {
     type MenuEntry,
     type MenuItem,
     type MenuRole,
     menuItem,
 } from './menuItem.ts'
+export { onMenu } from './onMenu.ts'
 // `navigate` ALONE, of everything routing needs. This barrel is what an app resolves through the
 // bare `@abide/abide` specifier, and the matcher, the pattern grammar and `routeOf` are reached by path
 // from the two places that have them — the build and the client router. Putting them here would

package/src/{ui → shared}/menuBridge.ts

@@ -1,7 +1,7 @@
 /**
  * The channel a desktop app's window opens to the page for its menu, or `undefined` in a browser.
  *
- * ITS OWN MODULE, so the router asks without importing the reporter: `reportMenu` is a chunk only a
+ * ITS OWN MODULE, so `onMenu` asks without importing the reporter: `reportMenu` is a chunk only a
  * page inside a desktop app loads. 38.88.
  */
 export function menuBridge():

package/src/shared/menuItem.ts

@@ -1,5 +1,5 @@
-// 38.88 — THE DESKTOP APP'S MENU BAR IS THE ROUTE'S: a layout or a page exports `menu` from its
-// `<script module>`, and the window shows what the route it stands on exports. An item made by
+// 38.88 — THE DESKTOP APP'S MENU BAR IS THE ROUTE'S: a layout or a page calls `onMenu` in its
+// `<script>`, and the window shows the menus filed while it stands. An item made by
 // `menuItem` is one a page answers; the rest are an address or a role, which need no page.
 
 /** What a menu item does natively, where an address or a page's own answer could not. 38.89. */

package/src/shared/onMenu.ts

@@ -0,0 +1,58 @@
+// 38.88, 38.92 — THE MENUS A LAYOUT OR A PAGE ADDS TO A DESKTOP APP'S MENU BAR, filed while it
+// stands. Called in its `<script>`, so the menus are a function of its state: what `read` reads moving
+// tells the window again, and the component going takes them with it. Outside a desktop app's window
+// there is no menu bar, and nothing is filed.
+
+import { menuBridge } from './menuBridge.ts'
+import type { MenuItem } from './menuItem.ts'
+import { watch } from './reactive/index.ts'
+
+/** One `onMenu`'s menus, as it last answered, and whether its component has gone. */
+type Filed = { menus: MenuItem[]; gone: boolean }
+
+// IN THE ORDER FILED, which is outermost first: a layout's setup runs before the page inside it.
+let filed: Filed[] = []
+let telling = false
+
+/** Files the menus `read` answers for as long as the calling component stands; returns what unfiles them. */
+export function onMenu(read: () => readonly MenuItem[]): () => void {
+    if (menuBridge() === undefined) return () => {}
+    const entry: Filed = { menus: [], gone: false }
+    filed.push(entry)
+    const stop = watch(() => {
+        entry.gone = false
+        entry.menus = [...read()]
+        tell()
+        // A rerun files again at once; a component that went stays gone.
+        return () => {
+            entry.gone = true
+            tell()
+        }
+    })
+    // 12.8 — a `read` that threw stopped the watch with no cleanup to run, so the unfiling is
+    // done here too.
+    return () => {
+        stop()
+        entry.gone = true
+        tell()
+    }
+}
+
+// ONCE PER TURN, after every rerun and every component a navigation took has settled.
+function tell(): void {
+    if (telling) return
+    telling = true
+    queueMicrotask(async () => {
+        telling = false
+        const standing: Filed[] = []
+        const menus: MenuItem[] = []
+        for (const entry of filed) {
+            if (entry.gone) continue
+            standing.push(entry)
+            menus.push(...entry.menus)
+        }
+        filed = standing
+        const { reportMenu } = await import('./reportMenu.ts')
+        reportMenu(menus)
+    })
+}

package/src/{ui → shared}/reportMenu.ts

@@ -1,9 +1,9 @@
-// 38.88 — A ROUTE'S MENU, TOLD TO THE WINDOW IT IS SHOWN IN. Loaded only inside a desktop app, where
-// the window has opened `abideMenu` to the page; anywhere else the router never imports it.
+// 38.88 — A ROUTE'S MENUS, TOLD TO THE WINDOW IT IS SHOWN IN. Loaded only inside a desktop app, where
+// the window has opened `abideMenu` to the page; anywhere else `onMenu` never imports it.
 
-import { MenuEntry, type MenuItem } from '#shared/menuItem.ts'
-import { navigate } from '#shared/navigate.ts'
 import { menuBridge } from './menuBridge.ts'
+import { MenuEntry, type MenuItem } from './menuItem.ts'
+import { navigate } from './navigate.ts'
 
 /** A menu item as the window builds it: an item the page answers carries the `id` it is told by. */
 type Told =
@@ -20,15 +20,13 @@ type Told =
 let numbered: Exclude<MenuItem, 'separator'>[] = []
 let listening = false
 
-/** Tells the window the menus `chain` exports, layouts outermost first and the page last. */
-export function reportMenu(chain: { menu?: unknown }[]): void {
+/** Tells the window `menus`, the layouts' outermost first and the page's last. */
+export function reportMenu(menus: readonly MenuItem[]): void {
     const bridge = menuBridge()
     if (bridge === undefined) return
     numbered = []
     const told: Told[] = []
-    for (const level of chain)
-        if (Array.isArray(level.menu))
-            for (const menu of level.menu as MenuItem[]) told.push(tell(menu))
+    for (const menu of menus) told.push(tell(menu))
     if (!listening) {
         listening = true
         // 38.90, 38.91 — the window names the item picked; the page does what it means.