@abide/abide 0.102.0 → 0.104.0

package/src/server/appTree.ts

@@ -1,28 +1,36 @@
-// 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. Every directory below the root
-// is a segment of an address, and a `page.abide`, `layout.abide` or `error.abide` in it answers there;
-// a `server` or `public` directory is never one (23.15) — the first fences a graph and the second
-// holds files answered as authored, at the path of the directories above it. So an app is organized
-// by subject (`media/[id]/page.abide`, `media/server`) and the addresses follow.
+// 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. A file directly in a directory
+// below the root is an address — a page, a layout, an error page or a handler file — and nothing
+// else is there (23.22); a fence is never one (23.15): `server` fences a graph, `public` holds files
+// answered as authored at the path of the directories above it, and `lib` and `tests` hold the rest.
+// So listing a directory lists its routes.
 //
-// ONE WALK for the sources and the public files `abide build` copies and `abide dev` answers, and
-// the refusals (23.16, 23.17, 23.18) — and ONE SKIP RULE, `skipped`, for every walk of the tree,
-// beside `placeOf`, which answers the same question of one path.
+// ONE WALK for the sources, the handler files, the server and lib modules, and the public files
+// `abide build` copies and `abide dev` answers, and the refusals (23.16, 23.17, 23.18, 23.22) — and
+// ONE SKIP RULE, `skipped`, for every walk of the tree, beside `placeOf`, which answers the same
+// question of one path.
 //
 // A WALK RATHER THAN A GLOB: a glob descends `node_modules` and the build output before a filter
 // can drop them.
 
-import { type Dirent, readdirSync } from 'node:fs' // bun has no directory listing of its own
+import { type Dirent, existsSync, readdirSync } from 'node:fs' // bun has no directory listing or sync existence check of its own
 import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
 import {
+    HOLDS_SERVER,
+    LIB_DIRECTORY,
     PUBLIC_DIRECTORY,
     RESERVED_DIRECTORIES,
+    SERVER_DIRECTORY,
 } from '#shared/RESERVED_DIRECTORIES.ts'
-import { fileKind, routeOf, skipped } from '#shared/routePattern.ts'
+import { DIRECTORY_FILES, routeOf, skipped } from '#shared/routePattern.ts'
 
 /** What one walk of the app finds, every path relative to the root. */
-export type AppFiles = {
+type AppFiles = {
     /** Every `.abide`, in path order. */
     abide: string[]
+    /** Every handler file, in path order. */
+    handlers: string[]
+    /** Every module under a `server` or a `lib` directory, in path order — read for 37.13. */
+    modules: string[]
     /** Every file under a `public` directory, to the address it is answered at below the mount. */
     published: Map<string, string>
 }
@@ -35,7 +43,8 @@ const THROW: Refuse = (_path, message) => {
 }
 
 /**
- * The app's `.abide` sources and public files, refusing a tree 23.16, 23.17 or 23.18 forbids.
+ * The app's `.abide` sources, handler files, server and lib modules and public files, refusing a
+ * tree 23.16, 23.17, 23.18 or 23.22 forbids.
  *
  * `refuse` throws by default, which is the build's answer; `abide check` collects instead (38.33),
  * and the checker's route table ignores them, since a refused tree is the build's to report.
@@ -43,9 +52,19 @@ const THROW: Refuse = (_path, message) => {
  * A missing root is an app with nothing in it, not a fault.
  */
 export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
-    const files: AppFiles = { abide: [], published: new Map() }
-    walk(root, '', undefined, files, refuse)
+    const files: AppFiles = {
+        abide: [],
+        handlers: [],
+        modules: [],
+        published: new Map(),
+    }
+    // 23.22, 38.25 — a root that is its package's directory holds the package's own files beside its
+    // pages.
+    const packaged = existsSync(`${root}/package.json`)
+    walk(root, '', undefined, files, refuse, packaged)
     files.abide.sort()
+    files.handlers.sort()
+    files.modules.sort()
     return files
 }
 
@@ -57,6 +76,7 @@ function walk(
     reserved: { path: string; name: string } | undefined,
     files: AppFiles,
     refuse: Refuse,
+    packaged = false,
 ): void {
     let entries: Dirent[]
     try {
@@ -71,7 +91,14 @@ function walk(
         if (entry.isDirectory()) {
             let within = reserved
             if (RESERVED_DIRECTORIES.has(entry.name)) {
-                if (reserved !== undefined)
+                // 23.16 — `server` nests in the fences that hold code.
+                if (
+                    reserved !== undefined &&
+                    !(
+                        entry.name === SERVER_DIRECTORY &&
+                        HOLDS_SERVER.has(reserved.name)
+                    )
+                )
                     refuse(
                         path,
                         `abide: ${path} is a ${entry.name} directory under the ${reserved.name} directory ${reserved.path}. RULEBOOK 23.16.`,
@@ -87,21 +114,49 @@ function walk(
             )
             continue
         }
-        if (path.endsWith('.abide')) files.abide.push(path)
+        const abide = path.endsWith('.abide')
+        if (abide) files.abide.push(path)
         if (reserved === undefined) {
+            if (!abide && !isModule(path)) {
+                if (packaged && relative === '' && !path.endsWith('.ts'))
+                    continue
+                refuse(
+                    path,
+                    `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages and handler files alone. Move it into a lib directory beside it. RULEBOOK 23.22.`,
+                )
+                continue
+            }
+            if (!abide) files.handlers.push(path)
             // 23.17 — anything that could answer here would answer in abide's own namespace.
-            if (path.endsWith('.abide'))
-                refuseFrameworkRoute(routeOf(path), path, refuse)
-        } else if (fileKind(entry.name) !== 'component')
+            refuseFrameworkRoute(routeOf(path), path, refuse)
+        } else if (DIRECTORY_FILES.has(entry.name))
             refuse(
                 path,
-                `abide: ${path} is a ${entry.name} under the ${reserved.name} directory ${reserved.path}, where nothing has an address. RULEBOOK 23.18.`,
+                `abide: ${path} is under the ${reserved.name} directory ${reserved.path}, where nothing has an address, and ${entry.name} is a route's name. RULEBOOK 23.18.`,
             )
         else if (reserved.name === PUBLIC_DIRECTORY)
             files.published.set(path, publicAddress(path, reserved.path))
+        else if (
+            (reserved.name === SERVER_DIRECTORY ||
+                reserved.name === LIB_DIRECTORY) &&
+            isModule(path)
+        )
+            files.modules.push(path)
     }
 }
 
+/**
+ * Whether `path` names a module the app runs — neither a declaration nor a test: directly in an
+ * address directory, a handler file rather than a stray.
+ */
+function isModule(path: string): boolean {
+    return (
+        path.endsWith('.ts') &&
+        !path.endsWith('.d.ts') &&
+        !path.endsWith('.test.ts')
+    )
+}
+
 /** Refuses `source` where `route` lies in the framework's own namespace. 23.17. */
 export function refuseFrameworkRoute(
     route: string,
@@ -150,18 +205,21 @@ export function abideUnder(root: string): string[] {
 }
 
 /**
- * Whether a `.abide` lies anywhere under `root` — stopping at the first.
+ * Whether an app lies under `root`: a `.abide` anywhere or a handler file, stopping at the first.
  *
  * 38.26's question, asked of a root before anything is built from it, so asking it of a large tree
  * is as cheap as the tree allows.
  */
-export function holdsAbide(root: string): boolean {
-    return !abideFilesUnder(root, '').next().done
+export function holdsApp(root: string): boolean {
+    return !abideFilesUnder(root, '', true).next().done
 }
 
+// Every `.abide` under `directory` — and, where `handlers`, every handler file outside a fence.
 function* abideFilesUnder(
     directory: string,
     relative: string,
+    handlers = false,
+    fenced = false,
 ): Generator<string> {
     let entries: Dirent[]
     try {
@@ -173,7 +231,16 @@ function* abideFilesUnder(
         if (skipped(entry.name)) continue
         const path = `${relative}${entry.name}`
         if (entry.isDirectory())
-            yield* abideFilesUnder(`${directory}/${entry.name}`, `${path}/`)
-        else if (path.endsWith('.abide')) yield path
+            yield* abideFilesUnder(
+                `${directory}/${entry.name}`,
+                `${path}/`,
+                handlers,
+                fenced || RESERVED_DIRECTORIES.has(entry.name),
+            )
+        else if (
+            path.endsWith('.abide') ||
+            (handlers && !fenced && isModule(path))
+        )
+            yield path
     }
 }

package/src/server/commands.ts

@@ -33,7 +33,7 @@ type SourceCommands = Record<
     | 'dev'
     | 'build'
     | 'check'
-    | 'sync'
+    | 'routes'
     | 'compile'
     | 'bundle'
     | 'lsp',
@@ -151,9 +151,9 @@ function commandsOf(host: Host): Row[] {
             'check',
         ),
         fromSource(
-            'sync',
-            'write the types a .ts reads a .abide by, into .abide/types',
-            'sync',
+            'routes [--json]',
+            'every address the app answers, its file, and where each hook is filed',
+            'routes',
         ),
         fromSource(
             'compile',
@@ -227,6 +227,7 @@ function parsed(argv: string[]) {
             method: { type: 'string' },
             target: { type: 'string' },
             platforms: { type: 'string' },
+            json: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
         },
         allowPositionals: true,

package/src/server/componentModules.d.ts

@@ -1,8 +1,7 @@
 // 35.4 — what a `.ts` holds where it imports a `.abide`: the component, called with its props to
 // bind them, answering the `Component` `render` takes (`abideModules`). A wildcard, so the props
 // are not checked here; a declaration in a module would be an augmentation, which takes no wildcard.
-// The names a `.abide` exports are typed by what 34.24 writes, which an app's tsconfig reaches
-// before this.
+// The component is all a `.abide` exports (34.17).
 declare module '*.abide' {
     const component: (
         props?: Record<string, unknown>,

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/generatedSurfaces.ts

@@ -29,7 +29,7 @@ import { type Listed, surfaceOf } from './surfaceOf.ts'
 const OPENAPI_LOG = namedLogger('abide:openapi')
 const MCP_LOG = namedLogger('abide:mcp')
 
-// What MCP and OpenAPI add to a listing: whether the handler is keyed.
+// What OpenAPI adds to a listing: whether the handler is keyed.
 type Published = Listed & { keyed: boolean }
 
 /** Every handler `surface` lists (`surfaceOf`). */
@@ -212,18 +212,8 @@ export function openApi(
     return Object.keys(document().paths).length > 0 ? document : undefined
 }
 
-/** What the MCP surface publishes: a tool per call that takes args or writes, a resource per read. */
-type Tools = { tools: Published[]; resources: Published[] }
+const published = new WeakMap<Map<string, Mounted>, Reactive<Published[]>>()
 
-const published = new WeakMap<Map<string, Mounted>, Reactive<Tools>>()
-
-function toolsOf(handlers: Map<string, Mounted>): Tools {
-    const found: Tools = { tools: [], resources: [] }
-    for (const one of listed(handlers, 'mcp'))
-        if (one.keyed || one.method !== 'GET') found.tools.push(one)
-        else found.resources.push(one)
-    return found
-}
 
 type JsonRpc = {
     jsonrpc: '2.0'
@@ -264,18 +254,20 @@ export class McpSurface {
 
     /** Whether the route table publishes any handler to it. 20.7. */
     get opened(): boolean {
-        const { tools, resources } = this.#published()
-        return tools.length > 0 || resources.length > 0
+        return this.#published().length > 0
     }
 
-    #published(): Tools {
-        return overTable(published, this.#handlers, toolsOf)()
+    #published(): Published[] {
+        // Every handler the MCP surface lists, each a tool — a read as much as a mutation. 20.9.
+        return overTable(published, this.#handlers, (handlers) =>
+            listed(handlers, 'mcp'),
+        )()
     }
 
     /** Every tool it lists. 20.9. */
     list(): ToolDefinition[] {
         const listing: ToolDefinition[] = []
-        for (const tool of this.#published().tools) {
+        for (const tool of this.#published()) {
             if (tool.description === undefined)
                 MCP_LOG.warning(
                     `${tool.name} is published with no description.`,
@@ -305,7 +297,7 @@ export class McpSurface {
     }
 
     #tool(name: unknown): Published | undefined {
-        return this.#published().tools.find((one) => one.name === name)
+        return this.#published().find((one) => one.name === name)
     }
 
     async #called(
@@ -335,7 +327,7 @@ export class McpSurface {
                 return {
                     result: {
                         protocolVersion: MCP_PROTOCOL_VERSION,
-                        capabilities: { tools: {}, resources: {} },
+                        capabilities: { tools: {} },
                         serverInfo: appIdentity(),
                     },
                 }
@@ -343,19 +335,6 @@ export class McpSurface {
                 return { result: {} }
             case 'tools/list':
                 return { result: { tools: this.list() } }
-            case 'resources/list':
-                return {
-                    result: {
-                        resources: this.#published().resources.map(
-                            (resource) => ({
-                                uri: `abide:${resource.address}`,
-                                name: resource.name,
-                                description: resource.description ?? '',
-                                mimeType: 'application/json',
-                            }),
-                        ),
-                    },
-                }
             case 'tools/call': {
                 const tool = this.#tool(params?.name)
                 if (tool === undefined)
@@ -375,25 +354,6 @@ export class McpSurface {
                     },
                 }
             }
-            case 'resources/read': {
-                const uri = String(params?.uri ?? '')
-                const resource = this.#published().resources.find(
-                    (one) => `abide:${one.address}` === uri,
-                )
-                if (resource === undefined)
-                    return mcpFailure(-32602, `No resource at ${uri}.`)
-                const { text, failed } = await this.#called(
-                    resource,
-                    undefined,
-                    asker,
-                )
-                if (failed) return mcpFailure(-32603, text)
-                return {
-                    result: {
-                        contents: [{ uri, mimeType: 'application/json', text }],
-                    },
-                }
-            }
             default:
                 return mcpFailure(-32601, `No method ${method}.`)
         }
@@ -404,8 +364,7 @@ export class McpSurface {
  * Answers one MCP JSON-RPC request over `surface`, or `undefined` where it publishes nothing.
  *
  * 20.9 — THE STREAMABLE-HTTP MCP ENDPOINT, answering JSON-RPC over `POST`, as the request's own
- * caller: a handler that takes no args is a resource, read at its address; one that takes args, and
- * every mutation, is a tool.
+ * caller: every handler it lists is a tool, a read as much as a mutation.
  */
 export async function answerMcp(
     surface: McpSurface,

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)