@abide/abide 0.103.0 → 0.105.0

package/src/server/abideModules.ts

@@ -21,6 +21,19 @@ import { basename, dirname, resolve } from 'node:path' // bun exposes no path he
 import { SERVER_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import type { ServerTable } from './answerRequest.ts'
 import type { MountRow } from './answerRpc.ts'
+import {
+    type Asked,
+    BOUND_NAMESPACE,
+    CLIENT_NAMESPACE,
+    componentNamespaceOf,
+    type Face,
+    faceOf,
+    type HandlerFace,
+    type Lane,
+    realFileOf,
+    STYLE_NAMESPACE,
+    TEXT_NAMESPACE,
+} from './faceOf.ts'
 import { installSourceMaps, type SourceMaps } from './installSourceMaps.ts'
 import {
     CLIENT_QUERY,
@@ -68,24 +81,8 @@ export type Compilation = {
     mounted: Record<string, string>
 }
 
-// A VIRTUAL FACE'S PATH: its file's, with a suffix that is not a query. Both registries key a module
-// by its path whatever its namespace, and the runtime's drops a query from it — so a file's text, its
-// stylesheet or its bound face under `?…` took the place of the module the file compiles to.
-const BOUND = '::bound'
-const CLIENT = '::client'
-const TEXT = '::text'
-const STYLE = '::style'
-
-/** The namespace a bundle's component module is answered in, at its file's own path. */
-export const COMPONENT_NAMESPACE = 'abide-component'
-/** The namespaces a file's text and a component's stylesheet are loaded in. */
-export const TEXT_NAMESPACE = 'abide-text'
-export const STYLE_NAMESPACE = 'abide-style'
 const RELATIVE_OR_SUBPATH = /^(?:\.\.?\/|#)/
 
-/** One handler file, as `Compilation.handlers` holds it. */
-type HandlerFace = { scope: string; client: string }
-
 /** The plugin serving `compilation`'s files and tables, for one bundle. */
 export function abideModules(
     root: string,
@@ -123,13 +120,39 @@ let registered = false
  */
 export function serveCompilation(root: string, compilation: Compilation): void {
     const real = realOrAsGiven(root)
-    addCompilation(real, compilation, RUNTIME)
+    const handlerFiles = addCompilation(real, compilation, RUNTIME)
     installSourceMaps(serverMapsOf(compilation, real), real)
+    if (handlerFiles.length !== 0) Bun.plugin(handlerFilesPlugin(handlerFiles))
     if (registered) return
     registered = true
     Bun.plugin(modulesPlugin(RUNTIME))
 }
 
+// 16.2 — A HANDLER FILE LOADED AT ITS OWN PATH RE-EXPORTS ITS FACE, so every spelling of its import
+// is the module the server mounted. The runtime asks `onResolve` only for a specifier with an
+// extension, while `onLoad` is asked by the path the file resolved to, however it was spelled. One
+// plugin per compilation because the filter is fixed at registration, and the runtime's `onLoad`
+// cannot fall through, so the filter names the handler files and nothing else. The face it names
+// is resolved by `modulesPlugin`, registered once.
+function handlerFilesPlugin(paths: string[]): Bun.BunPlugin {
+    return {
+        name: 'abide-handler-files',
+        setup(build) {
+            build.onLoad(
+                {
+                    filter: new RegExp(
+                        `^(?:${paths.map(RegExp.escape).join('|')})$`,
+                    ),
+                },
+                (args) => ({
+                    contents: `export { default } from ${JSON.stringify(`${args.path}${HANDLER_SUFFIX}`)}\n`,
+                    loader: 'js',
+                }),
+            )
+        },
+    }
+}
+
 /** What the server's table exports: its routes and error pages, server blocks and handlers. */
 export type BuiltTable = ServerTable & {
     /** 37.1 — every module a `<script server>` runs in, imported before the app boots. */
@@ -162,18 +185,24 @@ export function serverMapsOf(
     return maps
 }
 
+/** Adds `compilation` to `held`, and answers its handler files' absolute paths. */
 function addCompilation(
     root: string,
     compilation: Compilation,
     held: Held,
-): void {
+): string[] {
     // RESOLVED, not joined: a dependency's file is keyed above the root (`../node_modules/…`).
     for (const [relative, compiled] of Object.entries(compilation.files))
         held.files.set(resolve(root, relative), compiled)
-    for (const [relative, face] of Object.entries(compilation.handlers))
-        held.handlers.set(resolve(root, relative), face)
+    const handlerFiles: string[] = []
+    for (const [relative, face] of Object.entries(compilation.handlers)) {
+        const path = resolve(root, relative)
+        held.handlers.set(path, face)
+        handlerFiles.push(path)
+    }
     for (const [name, text] of Object.entries(compilation.tables))
         held.tables.set(`${root}/${VIRTUAL_DIRECTORY}/${name}`, text)
+    return handlerFiles
 }
 
 // `Bun.resolveSync` asks EVERY abide plugin's `onResolve` again — this one's, and the runtime's, which
@@ -203,79 +232,59 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
         name: 'abide-modules',
         setup(build) {
             // THE LANE IS THE BUILD'S TARGET: a browser bundle gets each file's browser module, and
-            // the runtime — which has no config — and a server bundle get its server module. A
-            // browser module the runtime was asked for (`CLIENT_QUERY`) is the one exception, and
-            // what it imports is in its lane.
+            // the runtime — which has no config — and a server bundle get its server module.
             const bundling: boolean = 'config' in build
-            const browser = bundling && build.config.target === 'browser'
-            const inBrowser = (importer: string): boolean =>
-                browser || pathOf(importer).endsWith(CLIENT)
-            // A BUNDLE'S COMPONENT MODULE IS IN A NAMESPACE OF ITS OWN: the bundler refuses a
-            // `file` path a plugin answers with `..` anywhere in it, which a `[...rest]` directory
-            // writes (23.5). The runtime has no such check, and its stack frames name the path.
-            const componentNamespace = bundling ? COMPONENT_NAMESPACE : 'file'
-            // The module `path` compiles to, in the lane its importer is in.
-            const componentFor = (path: string, importer: string) =>
-                inBrowser(importer) && !browser
-                    ? { path: `${path}${CLIENT}`, namespace: 'abide-client' }
-                    : { path, namespace: componentNamespace }
+            const lane: Lane = {
+                bundling,
+                browser: bundling && build.config.target === 'browser',
+            }
             const resolved = (specifier: string, importer: string): string =>
                 resolvedFile(specifier, dirname(pathOf(importer)))
+            // Each hook below only adapts bun's ask to `faceOf`'s: the file the specifier resolved to,
+            // its query taken off, and the answer handed back — a refusal thrown.
+            const answer = (
+                asked: Asked,
+                file: string,
+                importer: string,
+            ): Face | undefined => {
+                const face = faceOf(
+                    asked,
+                    file,
+                    pathOf(importer),
+                    lane,
+                    served.handlers,
+                )
+                if (face instanceof Error) throw face
+                return face
+            }
             // A filter off the query's own constant, so renaming one cannot silently stop a match.
+            const asking = (asked: Asked, query: string, filter: RegExp) =>
+                build.onResolve({ filter }, (args) =>
+                    resolving
+                        ? undefined
+                        : answer(
+                              asked,
+                              resolved(
+                                  args.path.slice(
+                                      0,
+                                      args.path.length - query.length,
+                                  ),
+                                  args.importer,
+                              ),
+                              args.importer,
+                          ),
+                )
             const abideWith = (query: string) =>
                 new RegExp(`\\.abide${RegExp.escape(query)}$`)
-
-            build.onResolve(
-                { filter: new RegExp(`${RegExp.escape(TEXT_QUERY)}$`) },
-                (args) => {
-                    if (resolving) return undefined
-                    const specifier = args.path.slice(0, -TEXT_QUERY.length)
-                    // A path of its own (`TEXT`): a file is often imported as code and as text at once
-                    // — an example's Files tab.
-                    return {
-                        path: `${resolved(specifier, args.importer)}${TEXT}`,
-                        namespace: TEXT_NAMESPACE,
-                    }
-                },
+            asking(
+                'text',
+                TEXT_QUERY,
+                new RegExp(`${RegExp.escape(TEXT_QUERY)}$`),
             )
-            build.onResolve({ filter: abideWith(STYLE_QUERY) }, (args) => {
-                if (resolving) return undefined
-                const specifier = args.path.slice(0, -STYLE_QUERY.length)
-                return {
-                    path: `${resolved(specifier, args.importer)}${STYLE}`,
-                    namespace: STYLE_NAMESPACE,
-                }
-            })
-            build.onResolve({ filter: abideWith(COMPONENT_QUERY) }, (args) => {
-                if (resolving) return undefined
-                const specifier = args.path.slice(0, -COMPONENT_QUERY.length)
-                return componentFor(
-                    resolved(specifier, args.importer),
-                    args.importer,
-                )
-            })
-            build.onResolve({ filter: abideWith(CLIENT_QUERY) }, (args) => {
-                if (resolving) return undefined
-                const path = resolved(
-                    args.path.slice(0, -CLIENT_QUERY.length),
-                    args.importer,
-                )
-                return browser
-                    ? { path, namespace: componentNamespace }
-                    : { path: `${path}${CLIENT}`, namespace: 'abide-client' }
-            })
-            build.onResolve({ filter: /\.abide$/ }, (args) => {
-                if (resolving) return undefined
-                const path = resolved(args.path, args.importer)
-                // A bound face's own import of its component, and every browser import, is the
-                // component module.
-                if (
-                    inBrowser(args.importer) ||
-                    pathOf(args.importer) === `${path}${BOUND}`
-                )
-                    return componentFor(path, args.importer)
-                return { path: `${path}${BOUND}`, namespace: 'abide-bound' }
-            })
+            asking('style', STYLE_QUERY, abideWith(STYLE_QUERY))
+            asking('component', COMPONENT_QUERY, abideWith(COMPONENT_QUERY))
+            asking('client', CLIENT_QUERY, abideWith(CLIENT_QUERY))
+            asking('abide', '', /\.abide$/)
             build.onResolve(
                 { filter: new RegExp(`/${VIRTUAL_DIRECTORY}/[^/]+\\.ts$`) },
                 (args) => {
@@ -290,48 +299,39 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
                 },
             )
 
-            // A HANDLER FILE IS FOUND BY WHERE ITS IMPORT RESOLVES, however the import spells it, and
-            // only from the app's own modules: a package's never names one, and asking bun again for
-            // each of a package's relative imports is a resolve per module of the bundle. IN A BUNDLE
+            // A HANDLER FILE IS FOUND BY WHERE ITS IMPORT RESOLVES, however the import spells it — the
+            // app's own, or a mounted package's own page importing a handler file of its (23.19).
             // THE FILTER IS THE HANDLER FILES' NAMES: a hook matching every relative import costs the
             // bundle abide's own `sideEffects`, and the barrel's rest — the validator, the csp — moved
-            // into the chunk every page loads (38.94). The runtime is told of each compilation after
-            // it registered, so it matches every relative or `#` import and asks.
+            // into the chunk every page loads (38.94); and since only an import ending in one of those
+            // names is resolved again, a package's other imports cost nothing, so a package's are not
+            // passed over by where they lie. ONLY IN A BUNDLE: the runtime finds a handler file by the
+            // path it loads at (`handlerFilesPlugin`), and asks no `onResolve` of an extensionless
+            // specifier at all.
             // Each handler file's name without `.ts` — what an import of one ends in.
-            let stems: string[] | undefined
-            if (bundling) {
-                const names = new Set<string>()
+            const stems = new Set<string>()
+            if (bundling)
                 for (const path of served.handlers.keys())
-                    names.add(basename(path, '.ts'))
-                stems = [...names]
-            }
-            const handlerImport =
-                stems === undefined
-                    ? RELATIVE_OR_SUBPATH
-                    : new RegExp(
-                          `(?:^|/)(?:${stems.map(RegExp.escape).join('|')})(?:\\.ts)?$`,
-                      )
-            if (stems?.length !== 0)
-                build.onResolve({ filter: handlerImport }, (args) => {
-                    if (resolving || !RELATIVE_OR_SUBPATH.test(args.path))
-                        return undefined
-                    const importer = pathOf(args.importer)
-                    if (importer.includes('/node_modules/')) return undefined
-                    let path: string
-                    try {
-                        path = resolved(args.path, args.importer)
-                    } catch {
-                        return undefined
-                    }
-                    const face = served.handlers.get(path)
-                    if (face === undefined) return undefined
-                    // 20.4 — a handler the browser is handed no wrapper for is no import of its.
-                    if (inBrowser(args.importer) && face.client === '')
-                        throw new Error(
-                            `abide: ${pathOf(args.importer)} imports ${args.path}, whose handler withholds itself from the browser (\`clients: { ui: false }\`). Call it from a <script server>, or let the browser have it. RULEBOOK 20.4.`,
-                        )
-                    return { path: `${path}${HANDLER_SUFFIX}` }
-                })
+                    stems.add(basename(path, '.ts'))
+            if (stems.size !== 0)
+                build.onResolve(
+                    {
+                        filter: new RegExp(
+                            `(?:^|/)(?:${[...stems].map(RegExp.escape).join('|')})(?:\\.ts)?$`,
+                        ),
+                    },
+                    (args) => {
+                        if (resolving || !RELATIVE_OR_SUBPATH.test(args.path))
+                            return undefined
+                        let file: string
+                        try {
+                            file = resolved(args.path, args.importer)
+                        } catch {
+                            return undefined
+                        }
+                        return answer('handler', file, args.importer)
+                    },
+                )
 
             // A RELATIVE SPECIFIER A FACE IMPORTS AT RUN TIME is resolved from the file the face
             // stands for: bun's runtime reads one from an importer in a namespace as no path at
@@ -340,19 +340,27 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
             // and where a hook matching every relative import in a package costs the bundle that
             // package's `sideEffects`: a two-page app grew by 12 KB, the validator one page never
             // calls moved into the chunk both pages load.
-            if (!bundling)
+            if (!bundling) {
+                // A face `handlerFilesPlugin` re-exports, named by its absolute path, which no file
+                // is at.
+                build.onResolve({ filter: HANDLER_FACE }, (args) => ({
+                    path: args.path,
+                }))
                 build.onResolve({ filter: /^\.\.?\// }, (args) =>
                     resolving || pathOf(args.importer) === args.importer
                         ? undefined
                         : { path: resolved(args.path, args.importer) },
                 )
+            }
 
             build.onLoad(
-                { filter: /\.abide$/, namespace: componentNamespace },
+                { filter: /\.abide$/, namespace: componentNamespaceOf(lane) },
                 (args) => {
                     const compiled = compiledAt(served, args.path)
                     return {
-                        contents: browser ? compiled.client : compiled.server,
+                        contents: lane.browser
+                            ? compiled.client
+                            : compiled.server,
                         loader: 'ts',
                     }
                 },
@@ -364,9 +372,9 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
             // resolves from its directory as the file's own imports do. A namespace of abide's own
             // had bun resolve a bare one from the working directory: a second abide, run from `/`.
             build.onLoad({ filter: HANDLER_FACE }, async (args) => {
-                const path = args.path.slice(0, -HANDLER_SUFFIX.length)
+                const path = realFileOf(args.path)
                 const face = served.handlers.get(path) as HandlerFace
-                if (browser) return { contents: face.client, loader: 'js' }
+                if (lane.browser) return { contents: face.client, loader: 'js' }
                 const text = await Bun.file(path).text()
                 return {
                     contents: `import { fileRoute as __fileRoute } from '${SERVER_SPECIFIER}';__fileRoute(${JSON.stringify(face.scope)});${text}\n;__fileRoute(undefined)\n`,
@@ -374,22 +382,22 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
                 }
             })
             build.onLoad(
-                { filter: /.*/, namespace: 'abide-client' },
+                { filter: /.*/, namespace: CLIENT_NAMESPACE },
                 (args) => ({
-                    contents: compiledAt(
-                        served,
-                        args.path.slice(0, -CLIENT.length),
-                    ).client,
+                    contents: compiledAt(served, realFileOf(args.path)).client,
                     loader: 'ts',
                 }),
             )
-            build.onLoad({ filter: /.*/, namespace: 'abide-bound' }, (args) => {
-                const path = args.path.slice(0, -BOUND.length)
-                return {
-                    contents: boundModule(path),
-                    loader: 'js',
-                }
-            })
+            build.onLoad(
+                { filter: /.*/, namespace: BOUND_NAMESPACE },
+                (args) => {
+                    const path = realFileOf(args.path)
+                    return {
+                        contents: boundModule(path),
+                        loader: 'js',
+                    }
+                },
+            )
             // A stylesheet is the bundle's; outside one there is no document to apply it to.
             build.onLoad(
                 { filter: /.*/, namespace: STYLE_NAMESPACE },
@@ -397,10 +405,8 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
                     bundling
                         ? {
                               contents:
-                                  compiledAt(
-                                      served,
-                                      args.path.slice(0, -STYLE.length),
-                                  ).sheet ?? '',
+                                  compiledAt(served, realFileOf(args.path))
+                                      .sheet ?? '',
                               loader: 'css',
                           }
                         : { contents: '', loader: 'js' },
@@ -408,7 +414,7 @@ function modulesPlugin(served: Held): Bun.BunPlugin {
             build.onLoad(
                 { filter: /.*/, namespace: TEXT_NAMESPACE },
                 async (args) => ({
-                    contents: `export default ${JSON.stringify(await Bun.file(args.path.slice(0, -TEXT.length)).text())}\n`,
+                    contents: `export default ${JSON.stringify(await Bun.file(realFileOf(args.path)).text())}\n`,
                     loader: 'js',
                 }),
             )

package/src/server/answerRequest.ts

@@ -20,6 +20,7 @@ import { DEBUG_META } from '#shared/DEBUG_META.ts'
 import { decodedOrKept } from '#shared/decodedOrKept.ts'
 import { escapeAttribute } from '#shared/escapeText.ts'
 import { type Failed, isFailed } from '#shared/Failed.ts'
+import { HandlerRoute } from '#shared/HandlerRoute.ts'
 import { health } from '#shared/health.ts'
 import { appName } from '#shared/log.ts'
 import { compose } from '#shared/Middleware.ts'
@@ -50,6 +51,7 @@ import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
 import { callerOrMint } from './callerOf.ts'
 import { compressAnswer } from './compressAnswer.ts'
 import { DOCUMENT_HEADERS } from './DOCUMENT_HEADERS.ts'
+import { noteCallInRender } from './deferredBuilds.ts'
 import { answerMcp, openApi } from './generatedSurfaces.ts'
 import { type AppRung, failureOf, rungsOver } from './hooks.ts'
 import { chunksOf, type Manifest } from './manifestOf.ts'
@@ -208,8 +210,8 @@ export async function answerRequest(
     }
 
     // 36.11 — A PUBLIC FILE IS ITS PATH BELOW THE DIRECTORY, so `/favicon.ico` is answered
-    // before any route is tried. The order is not load-bearing: `abide build` and `abide dev`
-    // run `refuseAddressCollision` (36.13) over the same two trees before anything is served,
+    // before any route is tried. The order is not load-bearing: the compile `abide build` and
+    // `abide dev` share refuses a collision (36.13) over the same two trees before anything is served,
     // so at run time there can never be a collision to resolve. 36.11 — keyed by its name on disk
     // and asked for percent-encoded: `my photo.jpg` is `/my%20photo.jpg`.
     const file = app.published.get(decodedOrKept(asked))
@@ -383,6 +385,10 @@ const SURFACES = new Map<
     [BRIDGE_ADDRESS, (_app, request) => answerBridge(request)],
 ])
 
+// Each handler's route, compiled once rather than per render that calls it — as its `Rpc` keeps its
+// own; compiled again only where it was mounted at another address since.
+const ROUTE_OF = new WeakMap<object, HandlerRoute>()
+
 // What a call made in a page's render reports into: the seed buffer (41.13), and — where the handler
 // is mounted — the request the browser will make for it, for the early-call script (41.20). Once per
 // render, as the browser's `Rpc` makes it once, and the seed buffer is what says which is the once.
@@ -392,18 +398,26 @@ export function reachedInRender(
     reached: unknown,
 ): void {
     const page = currentRequestScope()?.page
-    if (page === undefined || !page.seed(rpc, args, reached)) return
+    if (page === undefined) return
+    noteCallInRender()
+    if (!page.seed(rpc, args, reached)) return
     // 16.10 — the address the browser's own call is made at, stamped under the mount by
     // `mountHandlers` — and `undefined` on a handler nothing mounted.
     const { address, method } = rpc as Rpc<unknown, unknown>
     if (address === undefined) return
+    let route = ROUTE_OF.get(rpc)
+    if (route?.address !== address) {
+        route = new HandlerRoute(address)
+        ROUTE_OF.set(rpc, route)
+    }
     page.calls.push({
         request: rpcRequest(
             method,
-            address,
+            route,
             args as Record<string, unknown> | undefined,
         ),
         reached,
+        painted: undefined,
     })
 }