@abide/abide 0.101.0 → 0.103.0

package/src/server/withAbideSources.ts

@@ -0,0 +1,117 @@
+import { relative, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { COMPONENT_NAMESPACE, type Compilation } from './abideModules.ts'
+import { COMPONENT_QUERY } from './MODULE_QUERIES.ts'
+import {
+    decodeMappings,
+    encodeMappings,
+    placeAt,
+    type Segment,
+} from './sourceMappings.ts'
+
+const NAMESPACED = `${COMPONENT_NAMESPACE}:`
+
+// THE PARSER IS IMPORTED ON THE FIRST MAP ASKED FOR, not with the dev worker each reload boots:
+// only a debugger reads one.
+let parser: Promise<typeof import('#compiler/parseAbide.ts')> | undefined
+
+/**
+ * 38.97 — a client chunk's source map, with every position in a module compiled from a `.abide`
+ * placed in the `.abide` instead.
+ *
+ * Bun maps the chunk to the modules it bundled and reads no map those carry, so the second step is
+ * taken here. A position in the module's own scaffolding — what no `.abide` line wrote — stays in
+ * the compiled module, which is still listed, so a debugger steps through it rather than losing it.
+ */
+export async function withAbideSources(
+    mapText: string,
+    compilation: Compilation,
+    root: string,
+): Promise<string> {
+    const map = JSON.parse(mapText) as {
+        sources: string[]
+        sourcesContent?: (string | null)[]
+        mappings: string
+    }
+    const sources = map.sources
+    const contents = map.sourcesContent ?? []
+    // Per bundled source, its module's map and the index its `.abide` is listed at.
+    const placed: ({ lines: Segment[][]; index: number } | undefined)[] = []
+    const listed = new Map<string, number>()
+    const reads: Promise<void>[] = []
+    const originals = sources.length
+    for (let index = 0; index < originals; index += 1) {
+        // Bun names a bundled source from where the command runs, and a component module — which
+        // the plugin served at its `.abide`'s path — by its namespace and that path.
+        const named = sources[index] as string
+        const component = named.startsWith(NAMESPACED)
+        const abide = resolve(
+            component ? named.slice(NAMESPACED.length) : named,
+        )
+        const mappings = component
+            ? compilation.files[relative(root, abide)]?.clientMappings
+            : undefined
+        if (mappings === undefined) {
+            placed.push(undefined)
+            continue
+        }
+        // The module bun bundled is named apart from the `.abide` it is placed in, which shares
+        // its path.
+        sources[index] = `${relative(process.cwd(), abide)}${COMPONENT_QUERY}`
+        let at = listed.get(abide)
+        if (at === undefined) {
+            at = sources.length
+            listed.set(abide, at)
+            // Named as bun names its own, from where the command runs; read from where it is.
+            sources.push(relative(process.cwd(), abide))
+            const slot = at
+            parser ??= import('#compiler/parseAbide.ts')
+            reads.push(
+                Promise.all([Bun.file(abide).text(), parser]).then(
+                    ([text, { parseAbide }]) => {
+                        contents[slot] = withoutServerBlocks(text, parseAbide)
+                    },
+                ),
+            )
+        }
+        placed.push({ lines: decodeMappings(mappings), index: at })
+    }
+    if (listed.size === 0) return mapText
+    await Promise.all(reads)
+    for (let index = contents.length; index < sources.length; index += 1)
+        contents[index] ??= null
+    const lines = decodeMappings(map.mappings)
+    for (const segments of lines)
+        for (const segment of segments) {
+            const module = placed[segment[1]]
+            if (module === undefined) continue
+            const from = placeAt(module.lines, segment[2], segment[3])
+            if (from === undefined) continue
+            segment[1] = module.index
+            segment[2] = from[0]
+            segment[3] = from[1]
+        }
+    map.sourcesContent = contents
+    map.mappings = encodeMappings(lines)
+    return JSON.stringify(map)
+}
+
+/**
+ * 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.
+ */
+function withoutServerBlocks(
+    text: string,
+    parseAbide: typeof import('#compiler/parseAbide.ts').parseAbide,
+): string {
+    const file = parseAbide(text)
+    let blanked = ''
+    let at = 0
+    for (let index = 0; index < file.servers.length; index += 1) {
+        const start = file.origins.servers[index] as number
+        const end = start + (file.servers[index] as string).length
+        blanked += `${text.slice(at, start)}${text.slice(start, end).replace(/[^\n]/g, '')}`
+        at = end
+    }
+    return blanked + text.slice(at)
+}

package/src/shared/ADDRESSES.ts

@@ -7,32 +7,32 @@
 /**
  * The namespace every framework address lives under.
  *
- * UNDER `/__abide`, which is the namespace the framework's own addresses live in (19.1, 20.5,
- * 25.1). That is what makes a route table and an asset table incapable of colliding: a page is a
- * directory under `pages/` and no directory there can be named `__abide` without an author
- * writing it, so nothing has to be checked at build time and nothing can be shadowed at run time.
- * 38.21 is the clause.
+ * UNDER `/__abide`, which is the namespace the framework's own addresses live in (20.5, 25.1).
+ * That is what keeps the app's routes and abide's own addresses from colliding: a route whose first
+ * segment is `__abide` is refused at build (23.17), so nothing can be shadowed at run time. 38.20
+ * is the clause.
  */
 export const ABIDE_ADDRESS = '/__abide'
 
 /**
  * Where the browser bundle is served.
  *
- * The bundle's own address below `ABIDE_ADDRESS` (38.17, 38.21). One request path answers
+ * The bundle's own address below `ABIDE_ADDRESS` (38.16, 38.20). One request path answers
  * everything under `ABIDE_ADDRESS` and the command supplying the app decides what is there, so a
- * command with a second address of its own — the reload client `abide dev` serves (38.18) — adds
+ * command with a second address of its own — the reload client `abide dev` serves (38.17) — adds
  * one rather than a lane.
  */
 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. */
 export const OPENAPI_ADDRESS = `${ABIDE_ADDRESS}/openapi.json`
 /** The MCP endpoint. */
 export const MCP_ADDRESS = `${ABIDE_ADDRESS}/mcp`
-/** The stream of log records. */
-export const LOGS_ADDRESS = `${ABIDE_ADDRESS}/logs`
 /** The health check. */
 export const HEALTH_ADDRESS = `${ABIDE_ADDRESS}/health`
 /** Where a visitor's Claude Code bridge pairs, and is relayed turns (45.13). */
@@ -41,19 +41,11 @@ export const BRIDGE_ADDRESS = `${ABIDE_ADDRESS}/bridge`
 /**
  * The socket the dev reload client holds open.
  *
- * 38.18 — the LISTENER upgrades it on the main thread and the dev WORKER serves the script that
+ * 38.17 — the LISTENER upgrades it on the main thread and the dev WORKER serves the script that
  * opens it.
  */
 export const DEV_ADDRESS = `${ABIDE_ADDRESS}/dev`
 
-/**
- * Where a `server/rpc` handler is answered over http.
- *
- * 16.2 — its path below that directory, then its export name (19.1). The build writes the address
- * into the browser's wrapper and the server answers at it.
- */
-export const RPC_ADDRESS = `${ABIDE_ADDRESS}/rpc`
-
 /**
  * Where the one web socket a page follows its `GET`s over is served, below the app's root.
  *

package/src/shared/APP_META.ts

@@ -0,0 +1,7 @@
+/**
+ * The `<meta>` the server writes the app's name into, and a browser's logger reads it back from, so
+ * `log.named` prefixes the same name on both sides.
+ *
+ * 28.4.
+ */
+export const APP_META = 'abide-app'

package/src/shared/CopyOptions.ts

@@ -4,7 +4,7 @@
  * 18.4 — WHAT A `GET`'s VALUE DECLARES THAT ITS BROWSER COPY HAS TO BEHAVE BY, as the build reads
  * it off the declaration and writes it into the wrapper: data, because it crosses as text.
  * `structural` is named rather than carried, being abide's own comparator on both sides; an app's
- * own has no serialisation and stays the server's, as a function `by` or `tags` does.
+ * own has no serialization and stays the server's, as a function `by` or `tags` does.
  */
 export type CopyOptions = {
     by?: string

package/src/shared/DEBUG_META.ts

@@ -1,6 +1,6 @@
 /**
  * The `<meta>` the server writes `DEBUG` into, and a browser reads it back from.
  *
- * 28.11.
+ * 28.10.
  */
 export const DEBUG_META = 'abide-debug'

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

@@ -0,0 +1,24 @@
+// 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'
+
+/** A file under one is answered as authored, at the path above it. */
+export const PUBLIC_DIRECTORY = 'public'
+
+/** 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/cookies.ts

@@ -185,12 +185,12 @@ export function serializeCookie(init: CookieInit, inBrowser: boolean): string {
     // A page's own script cannot set an `HttpOnly` cookie, and a browser drops the whole line that
     // asks to — so the attribute is a server's alone.
     if (init.httpOnly === true && !inBrowser) line += '; HttpOnly'
-    line += `; SameSite=${capitalised(init.sameSite ?? 'lax')}`
+    line += `; SameSite=${capitalized(init.sameSite ?? 'lax')}`
     if (init.partitioned === true) line += '; Partitioned'
     return line
 }
 
-function capitalised(sameSite: string): string {
+function capitalized(sameSite: string): string {
     return sameSite.charAt(0).toUpperCase() + sameSite.slice(1)
 }
 

package/src/shared/csp.ts

@@ -41,7 +41,7 @@ export function documentNonce(): string {
  * A middleware rung that sets the content security policy, and `csp.nonce()` for the current one.
  *
  * THE RUNG IS BUILT ON ITS FIRST REQUEST, because an app's `middleware` can be read before the
- * server half has filled `CSP`: `app.ts` is one more module, and nothing orders it after that one.
+ * server half has filled `CSP`: the root `layout.abide` is one more module, and nothing orders it after that one.
  */
 export const csp = Object.assign(
     (sources?: Record<string, string[]>): Rung => {

package/src/shared/escapeText.ts

@@ -10,7 +10,7 @@ import { RAW_WRITES, Raw, textOf } from './Raw.ts'
 // the fallback: a clean string is returned as it arrived, with no allocation.
 //
 // THE DETECTION IS THE ENGINE'S, not a `charCodeAt` loop. The hand-written scan is one JS
-// iteration per character where this is vectorised, and it lost on the case it was written for:
+// iteration per character where this is vectorized, and it lost on the case it was written for:
 // 5x on a clean 74-character slot and 14x on a clean 320-character one, over two runs that did
 // not swap places. The share is named — `escapeText` is 74-86% of a 500-row x 4-slot markup
 // build, and the whole build moves 1.7x.

package/src/shared/filledPath.ts

@@ -0,0 +1,85 @@
+// A ROUTE'S PATH WITH ITS PARAMETERS WRITTEN IN, for the two things that build an address from a
+// route: `url`, from a page's literal (30.1), and a call, from its handler's route (16.9).
+
+import { parseRoutePattern, type Segment } from './routePattern.ts'
+
+/**
+ * `pattern` with each parameter `params` names written in as a path segment, or `/` for none.
+ *
+ * `spelled` is how the caller is named where a parameter is refused — `url('/x/[id]')`, or a
+ * handler's route — and `refused` what is thrown for it: an `Error` naming the clause, by default.
+ */
+export function filledPath(
+    pattern: string,
+    params: Record<string, unknown>,
+    spelled: string,
+    refused: (name: string, message: string) => unknown = thrownError,
+): string {
+    return filledSegments(parseRoutePattern(pattern), params, spelled, refused)
+}
+
+/** `filledPath` over a route already parsed, for a caller that fills the same route per call. */
+export function filledSegments(
+    segments: Segment[],
+    params: Record<string, unknown>,
+    spelled: string,
+    refused: (name: string, message: string) => unknown,
+): string {
+    let address = ''
+    for (const segment of segments) {
+        if (segment.kind === 'static') {
+            address += `/${segment.name}`
+            continue
+        }
+        const value = params[segment.name]
+        if (value === undefined || value === null || value === '') {
+            // 30.4 — an optional left out omits its segment, and so does an empty rest (30.5).
+            if (segment.kind !== 'required') continue
+            throw refused(
+                segment.name,
+                `abide: ${spelled} was given no '${segment.name}', and the route requires it. RULEBOOK 30.3.`,
+            )
+        }
+        if (segment.kind === 'rest' && Array.isArray(value)) {
+            for (const each of value)
+                address += `/${encodedSegment(spelled, segment.name, each, refused)}`
+            continue
+        }
+        address += `/${encodedSegment(spelled, segment.name, value, refused)}`
+    }
+    return address === '' ? '/' : address
+}
+
+/** The names of `pattern`'s parameters — what a call takes out of its args and into the path (16.66). */
+export function parametersOf(pattern: string): Set<string> {
+    const names = new Set<string>()
+    for (const segment of parseRoutePattern(pattern))
+        if (segment.kind !== 'static') names.add(segment.name)
+    return names
+}
+
+/**
+ * A param value encoded as one path segment; `.` and `..` are refused.
+ *
+ * 30.19 — A VALUE OF `.` OR `..` HAS NO SPELLING AS A SEGMENT: the URL parser collapses it as a
+ * dot-segment, and `%2E` / `%2E%2E` with it, so the address would land on another route. Refused
+ * rather than written, as a missing required segment is (30.3).
+ */
+function encodedSegment(
+    spelled: string,
+    name: string,
+    value: unknown,
+    refused: (name: string, message: string) => unknown,
+): string {
+    const text = String(value)
+    if (text === '.' || text === '..')
+        throw refused(
+            name,
+            `abide: ${spelled} was given '${text}' for '${name}', and no address carries it as a segment — the URL parser resolves it to another route. RULEBOOK 30.19.`,
+        )
+    return encodeURIComponent(text)
+}
+
+function thrownError(_name: string, message: string): Error {
+    return new Error(message)
+}

package/src/shared/framing.ts

@@ -1,6 +1,34 @@
 // 16.32 — A FRAMED ANSWER, read one JSON value per line: the whole line for jsonl, the `data:` line of
 // each event for sse. A line that does not carry the prefix — an sse `event:` line, a blank line — is
 // skipped. One line reader behind both a body read to the end and one read as it lands.
+//
+// 16.68 — AND ITS LAST FRAME MAY BE A REFUSAL: one that reached the stream after it had answered, so
+// after its status was sent. An sse `event: refusal` and the Problem Details on its `data:` line, or a
+// jsonl line `{"$refusal": <Problem Details>}` — read here as the refusal, thrown where it lands.
+
+import { failedFrom, isProblem, type Problem } from './Failed.ts'
+
+/** The key a jsonl line carries a refusal under (16.68). */
+const REFUSAL_KEY = '$refusal'
+
+/** A framed stream's last frame, as the server writes it for a refusal (16.68). */
+export function refusalFrame(problem: Problem, prefix: string): string {
+    return prefix === ''
+        ? `${JSON.stringify({ [REFUSAL_KEY]: problem })}\n`
+        : `event: refusal\n${prefix}${JSON.stringify(problem)}\n\n`
+}
+
+// What a read of one framed body carries from one line to the next: whether an sse event named the
+// data line after it a refusal.
+type Reading = { refusal: boolean }
+
+// A refusal's frame, read: thrown where it lands among the chunks.
+class Refused {
+    problem: Problem
+    constructor(problem: Problem) {
+        this.problem = problem
+    }
+}
 
 /**
  * What precedes a chunk's JSON on its line: nothing for jsonl, `data: ` for sse, and `null` where
@@ -67,14 +95,16 @@ async function* bytesStream(
 /** The chunks a framed text carried, every line of it complete. */
 export function framedChunks(text: string, prefix: string): unknown[] {
     const chunks: unknown[] = []
-    readLines(text, prefix, true, chunks)
+    readLines(text, prefix, true, chunks, { refusal: false })
+    for (const chunk of chunks)
+        if (chunk instanceof Refused) throw failedFrom(chunk.problem)
     return chunks
 }
 
 /**
  * A framed body's chunks, yielded as each line completes.
  *
- * Cancelled when the reader stops reading — a refresh starts a new run and the old one's reader has
+ * Canceled when the reader stops reading — a refresh starts a new run and the old one's reader has
  * nothing left to hand anything.
  */
 export async function* framedStream(
@@ -84,6 +114,7 @@ export async function* framedStream(
     const reader = body.getReader()
     const decoder = new TextDecoder()
     const chunks: unknown[] = []
+    const reading: Reading = { refusal: false }
     let buffered = ''
     try {
         for (;;) {
@@ -97,8 +128,17 @@ export async function* framedStream(
                 buffered += decoded
                 continue
             }
-            buffered = readLines(buffered + decoded, prefix, done, chunks)
-            yield* chunks
+            buffered = readLines(
+                buffered + decoded,
+                prefix,
+                done,
+                chunks,
+                reading,
+            )
+            for (const chunk of chunks) {
+                if (chunk instanceof Refused) throw failedFrom(chunk.problem)
+                yield chunk
+            }
             chunks.length = 0
             if (done) return
         }
@@ -117,15 +157,48 @@ function readLines(
     prefix: string,
     ended: boolean,
     chunks: unknown[],
+    reading: Reading,
 ): string {
     let start = 0
     for (;;) {
         const newline = text.indexOf('\n', start)
         if (newline === -1 && !ended) return text.slice(start)
         const end = newline === -1 ? text.length : newline
-        if (end > start && text.startsWith(prefix, start))
-            chunks.push(JSON.parse(text.slice(start + prefix.length, end)))
+        if (prefix !== '' && text.startsWith('event: refusal', start))
+            reading.refusal = true
+        else if (end > start && text.startsWith(prefix, start)) {
+            const value: unknown = JSON.parse(
+                text.slice(start + prefix.length, end),
+            )
+            chunks.push(refusalIn(value, prefix, reading) ?? value)
+            reading.refusal = false
+        }
         if (newline === -1) return ''
         start = newline + 1
     }
 }
+
+// The refusal a value carries as its frame: the data line an sse event named one, or a jsonl line
+// holding the one reserved key and Problem Details under it.
+function refusalIn(
+    value: unknown,
+    prefix: string,
+    reading: Reading,
+): Refused | undefined {
+    if (prefix !== '')
+        return reading.refusal && isProblem(value)
+            ? new Refused(value)
+            : undefined
+    // Per chunk: the reserved key is tested before any key list is built.
+    if (
+        value === null ||
+        typeof value !== 'object' ||
+        !Object.hasOwn(value, REFUSAL_KEY)
+    )
+        return undefined
+    const keys = Object.keys(value)
+    const problem = (value as Record<string, unknown>)[REFUSAL_KEY]
+    return keys.length === 1 && isProblem(problem)
+        ? new Refused(problem)
+        : undefined
+}

package/src/shared/headKeyOf.ts

@@ -20,6 +20,8 @@ export function headKeyOf(
 ): string | undefined {
     if (lowerTag === 'title' || lowerTag === 'base') return lowerTag
     if (lowerTag === 'meta') {
+        // One encoding a document, so a layout's replaces the default document's.
+        if (attribute('charset') != null) return 'meta charset'
         const named = attribute('name')
         const key = named === null ? attribute('property') : named
         return key == null ? undefined : `meta ${key}`

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.89 — 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/shared/log.ts

@@ -1,14 +1,15 @@
 // SECTION 28 — the logger, on both sides. A line is written to the console AND published to
-// `log.records` (28.1), so a subscriber — `abide logs`, a test, a page — sees exactly what the
+// `log.records` (28.1), so a subscriber — a handler, a test, a page — sees exactly what the
 // terminal saw.
 //
 // THE RECORDS ARE BUILT ON FIRST ASK. The reactive core warns through this module, so a
 // `reactive` built at this module's evaluation would be a cycle evaluated in the wrong order;
 // built on the first line or the first read of `log.records`, the core has long since loaded.
 //
-// 28.11, 28.12 — IN A BROWSER, `DEBUG` IS THE DOCUMENT'S: the server names it in a `<meta>` it writes
+// 28.10, 28.11 — IN A BROWSER, `DEBUG` IS THE DOCUMENT'S: the server names it in a `<meta>` it writes
 // into the head, and the browser's own stored `debug` answers only where the document carries none.
 
+import { APP_META } from './APP_META.ts'
 import { DEBUG_META } from './DEBUG_META.ts'
 import { paint } from './paint.ts'
 import { type Reactive, reactive } from './reactive/index.ts'
@@ -53,7 +54,7 @@ function recordsValue(): Reactive<LogRecord[]> {
             Number.isInteger(configured) && configured >= 0
                 ? configured
                 : DEFAULT_BUFFER
-        // 28.1 — one array for the process, which `/__abide/logs` follows (28.2).
+        // 28.1 — one array for the process.
         records = reactive<LogRecord[]>([], { global: true })
     }
     return records
@@ -62,7 +63,7 @@ function recordsValue(): Reactive<LogRecord[]> {
 /**
  * Appends `record` to `log.records`, trimming to the buffer it keeps.
  *
- * THE TRIM IS AMORTISED: grown to twice the buffer and cut back in one move, rather than a `shift`
+ * THE TRIM IS AMORTIZED: grown to twice the buffer and cut back in one move, rather than a `shift`
  * per line that moves every record still held.
  */
 function keep(list: LogRecord[], record: LogRecord): void {
@@ -81,14 +82,26 @@ function keep(list: LogRecord[], record: LogRecord): void {
  */
 let documentDebugRead: string | undefined
 
+let documentAppRead: string | undefined
+
 function environment(name: string): string | undefined {
     if (typeof process !== 'undefined') return process.env[name]
+    // 28.4 — the app's name, as the server wrote it into the document.
+    if (name === 'APP_NAME') {
+        documentAppRead ??=
+            (typeof document === 'undefined'
+                ? undefined
+                : document
+                      .querySelector(`meta[name="${APP_META}"]`)
+                      ?.getAttribute('content')) ?? ''
+        return documentAppRead === '' ? undefined : documentAppRead
+    }
     if (name !== 'DEBUG') return undefined
     documentDebugRead ??= documentDebug() ?? ''
     return documentDebugRead
 }
 
-/** The document's `DEBUG`, or the browser's own stored one where it carries none (28.11, 28.12). */
+/** The document's `DEBUG`, or the browser's own stored one where it carries none (28.10, 28.11). */
 export function documentDebug(): string | undefined {
     if (typeof document === 'undefined') return undefined
     const named = document
@@ -106,7 +119,7 @@ export function documentDebug(): string | undefined {
 /**
  * The compiled `DEBUG` patterns: namespaces included, and namespaces excluded.
  *
- * 28.10 — THE debug-npm GRAMMAR: a list split on commas or whitespace, `*` any run of characters,
+ * 28.9 — THE debug-npm GRAMMAR: a list split on commas or whitespace, `*` any run of characters,
  * and a leading `-` an exclusion that beats every inclusion. Compiled once per distinct `DEBUG`.
  */
 type Gate = { include: RegExp[]; exclude: RegExp[] }
@@ -131,7 +144,7 @@ function currentGate(): Gate {
     return gate
 }
 
-/** Whether `DEBUG` enables a namespace's gated lines (28.7). */
+/** Whether `DEBUG` enables a namespace's gated lines (28.6). */
 function isEnabled(namespace: string): boolean {
     const { include, exclude } = currentGate()
     for (const pattern of exclude) if (pattern.test(namespace)) return false
@@ -215,12 +228,12 @@ function write(
     recordsValue().patch((list) => keep(list, record))
 }
 
-/** A logger under `namespace`, which 28.5 builds from the app's name and 28.9 from `abide:`. */
+/** A logger under `namespace`, which 28.4 builds from the app's name and 28.8 from `abide:`. */
 export function namedLogger(namespace: string): Logger {
     return loggerOver(() => namespace)
 }
 
-/** Both lanes' render logger (28.9): the server's escalations and 32.20's dropped URLs. */
+/** Both lanes' render logger (28.8): the server's escalations and 32.20's dropped URLs. */
 export const RENDER_LOG = namedLogger('abide:render')
 
 /**
@@ -229,7 +242,7 @@ export const RENDER_LOG = namedLogger('abide:render')
  * The namespace is ASKED per line rather than held, which is all `log` needs over a named logger.
  */
 function loggerOver(namespaceOf: () => string): Logger {
-    // 28.3 — the bare call always writes. 28.4 — so do warnings and errors.
+    // 28.2 — the bare call always writes. 28.3 — so do warnings and errors.
     const logger = ((...args: unknown[]): void => {
         write(namespaceOf(), 'info', args)
     }) as Logger
@@ -243,7 +256,7 @@ function loggerOver(namespaceOf: () => string): Logger {
     }
     logger.warning = (...args) => write(namespaceOf(), 'warning', args)
     logger.error = (...args) => write(namespaceOf(), 'error', args)
-    // 28.5 — another segment, below this one. 28.13 — asked per line too, so a logger named at module
+    // 28.4 — another segment, below this one. 28.12 — asked per line too, so a logger named at module
     // load, before the app's name resolved, writes under the name once it has.
     logger.named = (name) => loggerOver(() => `${namespaceOf()}:${name}`)
     logger.enabled = () => isEnabled(namespaceOf())
@@ -254,14 +267,15 @@ function loggerOver(namespaceOf: () => string): Logger {
 /**
  * The slot the derived app name is read through, filled by the server's `config`.
  *
- * 28.5 — the app's name is the root every `log.named` hangs off: the environment's, or what 27.3
+ * 28.4 — the app's name is the root every `log.named` hangs off: the environment's, or what 27.3
  * derived, which the server's `config` fills in here.
  */
 export const APP_NAME: { derived: () => string | undefined } = {
     derived: () => undefined,
 }
 
-function appName(): string {
+/** The name every `log.named` hangs off: the environment's, or the one the app derived (28.4). */
+export function appName(): string {
     return environment('APP_NAME') ?? APP_NAME.derived() ?? 'app'
 }