@abide/abide 0.58.0 → 0.101.0

package/src/server/hooks.ts

@@ -0,0 +1,190 @@
+// SECTION 37 — THE LIFECYCLE HOOKS, called from `src/server/app.ts` rather than exported from it
+// (37.1). Each call files its function here and hands back what unfiles it; `createApp` reads what
+// is filed once the app module has run.
+//
+// PROCESS-WIDE, like the module that calls them: `app.ts` is evaluated once per process, so a
+// second `App` in it boots under the same hooks (42.12's sharing, from the other side).
+
+import { type Failed, isFailed } from '#shared/Failed.ts'
+import { namedLogger } from '#shared/log.ts'
+import type { Middleware } from '#shared/Middleware.ts'
+import { aborted, refuse } from '#shared/refuse.ts'
+import type { Schema } from '#shared/Schema.ts'
+import { config } from './config.ts'
+import { currentRequestScope } from './requestScope.ts'
+
+export type AppRung = Middleware<{ request: Request }, Response>
+
+export type Env = Record<string, string | undefined>
+export type ConfigDefaults = (env: Env) => unknown
+export type ConfigOptions = { schema?: Schema<unknown> }
+
+type Wrapper = (inner: () => Promise<void>) => void | Promise<void>
+
+/** Everything the lifecycle hooks filed, for `createApp` to read once the app module has run. */
+export const HOOKS = {
+    rungs: [] as AppRung[],
+    starts: [] as Wrapper[],
+    stops: [] as Wrapper[],
+    errors: [] as ((error: unknown) => unknown)[],
+    health: [] as (() => unknown)[],
+    config: undefined as
+        | {
+              defaults: ConfigDefaults | null
+              options: ConfigOptions | undefined
+          }
+        | undefined,
+    principal: undefined as
+        | ((claims: unknown) => unknown | Promise<unknown>)
+        | undefined,
+}
+
+const LIFECYCLE_LOG = namedLogger('abide:lifecycle')
+const CONFIG_LOG = namedLogger('abide:config')
+const PRINCIPAL_LOG = namedLogger('abide:principal')
+
+function filed<T>(list: T[], item: T): () => void {
+    list.push(item)
+    return () => {
+        const at = list.indexOf(item)
+        if (at !== -1) list.splice(at, 1)
+    }
+}
+
+/**
+ * Files middleware rungs the app runs before routing; returns what unfiles them.
+ *
+ * 37.3 — pre-routing, over the request and the response, in the order registered.
+ */
+export function middleware(...rungs: AppRung[]): () => void {
+    const unfile: (() => void)[] = []
+    for (const rung of rungs) unfile.push(filed(HOOKS.rungs, rung))
+    return () => {
+        for (const undo of unfile) undo()
+    }
+}
+
+/**
+ * Files a hook wrapping the app's boot; returns what unfiles it.
+ *
+ * 37.4 — wraps `createApp`. `start` is the boot; a hook that never calls it boots nothing.
+ */
+export function onStart(
+    fn: (start: () => Promise<void>) => void | Promise<void>,
+): () => void {
+    return filed(HOOKS.starts, fn)
+}
+
+/**
+ * Files a hook wrapping the app's teardown; returns what unfiles it.
+ *
+ * 37.4 — wraps `App.stop`'s teardown.
+ */
+export function onStop(
+    fn: (stop: () => Promise<void>) => void | Promise<void>,
+): () => void {
+    return filed(HOOKS.stops, fn)
+}
+
+/**
+ * Files a hook handed every unexpected error; returns what unfiles it.
+ *
+ * 37.5.
+ */
+export function onError(fn: (error: unknown) => unknown): () => void {
+    return filed(HOOKS.errors, fn)
+}
+
+/**
+ * Files a health reporter whose account is merged over the baseline; returns what unfiles it.
+ *
+ * 25.2.
+ */
+export function onHealth(report: () => unknown | Promise<unknown>): () => void {
+    return filed(HOOKS.health, report)
+}
+
+/**
+ * Sets the app's config defaults and schema; returns what unsets them.
+ *
+ * 27.6, 37.7 — a second replaces the first, schema and all, and says so. 27.10 — the read after
+ * either is resolved under what is filed now, not what was filed when `config` was last read.
+ */
+export function onConfig(
+    fn: ConfigDefaults | null,
+    options?: ConfigOptions,
+): () => void {
+    if (HOOKS.config !== undefined)
+        CONFIG_LOG.warning(
+            'a second onConfig replaced the first, and its schema with it. RULEBOOK 27.6.',
+        )
+    const entry = { defaults: fn, options }
+    HOOKS.config = entry
+    config.invalidate()
+    return () => {
+        if (HOOKS.config !== entry) return
+        HOOKS.config = undefined
+        config.invalidate()
+    }
+}
+
+/**
+ * Sets the function resolving a principal from its claims; returns what unsets it.
+ *
+ * 37.7 — a second replaces the first, and says so.
+ */
+export function onPrincipal(
+    resolve: (claims: unknown) => unknown | Promise<unknown>,
+): () => void {
+    if (HOOKS.principal !== undefined)
+        PRINCIPAL_LOG.warning(
+            'a second onPrincipal replaced the first. RULEBOOK 37.7.',
+        )
+    HOOKS.principal = resolve
+    return () => {
+        if (HOOKS.principal === resolve) HOOKS.principal = undefined
+    }
+}
+
+/**
+ * Logs an unexpected error and hands it to every `onError` hook.
+ *
+ * 37.5 — AN UNEXPECTED ERROR IS ALWAYS WRITTEN, and every `onError` is then handed it. A hook that
+ * throws is itself written rather than let loose on the request that was already failing.
+ */
+export function reportUnexpected(error: unknown): void {
+    LIFECYCLE_LOG.error(error)
+    handOnError(error)
+}
+
+/**
+ * Hands an error to every `onError` hook, writing nothing of its own.
+ *
+ * 12.6 — the half of 37.5 a failure already warned on its own namespace is owed.
+ */
+export function handOnError(error: unknown): void {
+    for (const hook of HOOKS.errors)
+        try {
+            hook(error)
+        } catch (thrown) {
+            LIFECYCLE_LOG.error('an onError hook threw', thrown)
+        }
+}
+
+/**
+ * The `Failed` a thrown error answers with: a refusal as it is, anything else a reported 500.
+ *
+ * 16.40 — a refusal at its own status. 16.41 — anything else is the server's fault, and says
+ * nothing about itself to the caller: the log and `onError` get it (37.5).
+ *
+ * 16.63 — A CLIENT THAT LEFT IS NOT A FAULT: once the request's signal has aborted, what was thrown
+ * is the cancellation arriving, so it answers `aborted` and is not reported — a handler's throw and a
+ * page render's alike, because both answer here.
+ */
+export function failureOf(error: unknown): Failed<string, unknown> {
+    if (isFailed(error)) return error
+    if (currentRequestScope()?.request?.signal.aborted === true)
+        return aborted()
+    reportUnexpected(error)
+    return refuse(500)
+}

package/src/server/index.ts

@@ -0,0 +1,87 @@
+// The server seam — what an app reaches through `@abide/abide/server`.
+// Request handling, SSR and the rpc boundary. Nothing here may be reached from the client
+// entry's static closure.
+//
+// THE COMPILER IS NOT HERE — it has its own #compiler seam. This module is public surface, so a
+// compiler under it is one `export *` from being an app's dependency. `packages/abide/tests/compiler.test.ts` holds that apart.
+
+import { installServer } from './installServer.ts'
+
+// THE WHOLE ISOMORPHIC SURFACE, re-exported rather than owned. A server module imports `GET` and
+// `reactive` through this one specifier — the same callable, by the same name, that `@abide/abide`
+// hands a page. It is also every run-time half an
+// emitted module reaches through here: 32.1's escaping and 32.2's `raw`, which both sides render
+// markup with, 32.20's `safeUrl`, and 31.8's `writePath`.
+export * from '#shared'
+export {
+    type Clients,
+    DELETE,
+    GET,
+    PATCH,
+    POST,
+    PUT,
+    type Rpc,
+    type RpcOptions,
+} from '#shared/rpc.ts'
+// 18.11 — one write a patch made, as a followed `GET`'s `patch` carries it.
+export type { PatchOp } from '#shared/reactive/PATCH_SINKS.ts'
+// 45 — a conversation with a model, piped through a handler, and the two providers abide ships.
+export {
+    type AssistantEvent,
+    type AssistantMessage,
+    type AssistantOptions,
+    assistant,
+    type Provider,
+    type Toolbox,
+    type ToolDefinition,
+} from './assistant.ts'
+export { type ClaudeApiConfig, claudeApi } from './claudeApi.ts'
+export {
+    type BridgeStatus,
+    type ClaudeCodeConfig,
+    claudeCode,
+} from './claudeCode.ts'
+// 27 — the resolved configuration.
+export { type Config, config } from './config.ts'
+// 42 — the app object, and 37's hooks an `src/server/app.ts` calls.
+export { type App, createApp } from './createApp.ts'
+export {
+    type ConfigDefaults,
+    type ConfigOptions,
+    type Env,
+    middleware,
+    onConfig,
+    onError,
+    onHealth,
+    onPrincipal,
+    onStart,
+    onStop,
+} from './hooks.ts'
+// 23.10 — whether a host answers, asked before a call to it.
+export { reachable } from './reachable.ts'
+export { type Component, render, type Shell } from './render.ts'
+// 38.83 — the props `src/bundle/launch.abide` is rendered with.
+export type { ConfigField } from './configFields.ts'
+export type { Launch } from './launcherPage.ts'
+// 32.17's run-time half: one invocation, rendered where it stands, with the anchors that make the
+// child's markup one thing for the client to walk to.
+export { renderComponent } from './renderComponent.ts'
+// 22.1 — the request being served, the response being built for it, and the listening server.
+export { request, response, server } from './requestScope.ts'
+// 17 — the response helpers, each a write through `response`.
+export {
+    bytes,
+    json,
+    jsonl,
+    page,
+    type RedirectStatus,
+    redirect,
+    sse,
+    type Values,
+} from './responseHelpers.ts'
+// 24 — the trace this work belongs to.
+export { trace } from './trace.ts'
+
+// AN APP THAT IMPORTS `@abide/abide/server` IS ON A SERVER, booted or not: its own tests render, call and
+// read `config` through these names without `createApp`.
+installServer()

package/src/server/installServer.ts

@@ -0,0 +1,47 @@
+// EVERY SLOT `#shared` LEAVES FOR A SERVER, filled from one place rather than as a side effect of
+// whichever server module a process happened to import — a compiler or a test that reaches one of
+// them for a function is not made a server by it. Called where a server is entered: `bootApp`,
+// `abide run`, and `@abide/abide/server`, which an app imports to be one. Filling the same functions again
+// changes nothing, so each entry calls it. Three are filled elsewhere: `SCOPING.provider` at
+// `requestScope.ts`'s import (its comment says why), `RPC_SERVER.raw` per boot, and
+// `LISTENING.timeout` by the dev worker alone.
+
+import { COOKIES } from '#shared/cookies.ts'
+import { CSP } from '#shared/csp.ts'
+import { HEALTH } from '#shared/health.ts'
+import { APP_NAME, TRACE } from '#shared/log.ts'
+import { MOUNT } from '#shared/mount.ts'
+import { PRINCIPAL } from '#shared/principal.ts'
+import { RPC_SERVER } from '#shared/RPC_SERVER.ts'
+import { UNEXPECTED } from '#shared/UNEXPECTED.ts'
+import { reachedInRender } from './answerRequest.ts'
+import { environmentTimeout } from './answerRpc.ts'
+import { broadcast, feedFromServed, swept } from './answerSocket.ts'
+import { configuredMount, derivedAppName } from './config.ts'
+import { cspRung, nonce } from './csp.ts'
+import { handOnError } from './hooks.ts'
+import { SERVER_PRINCIPAL } from './principal.ts'
+import { reportHealth } from './reportHealth.ts'
+import { handlerTook, request, requestCookies } from './requestScope.ts'
+import { trace } from './trace.ts'
+
+export function installServer(): void {
+    COOKIES.current = requestCookies
+    MOUNT.current = configuredMount
+    // Every log line written inside a scope carries its trace id.
+    TRACE.current = trace
+    APP_NAME.derived = derivedAppName
+    UNEXPECTED.report = handOnError
+    HEALTH.report = reportHealth
+    CSP.rung = cspRung
+    CSP.nonce = nonce
+    Object.assign(PRINCIPAL, SERVER_PRINCIPAL)
+    // 16.11 — the request a handler's rung is handed.
+    RPC_SERVER.request = request
+    RPC_SERVER.timeout = environmentTimeout
+    RPC_SERVER.reached = reachedInRender
+    RPC_SERVER.broadcast = broadcast
+    RPC_SERVER.swept = swept
+    RPC_SERVER.served = feedFromServed
+    RPC_SERVER.handled = handlerTook
+}

package/src/server/launcherOptions.ts

@@ -0,0 +1,62 @@
+// 38.81 — `src/bundle/launcher.json`: the window the desktop app opens and the forms its launcher
+// offers. Read when `abide bundle` runs and carried in the executable, which reads nothing from the
+// source tree when it starts (38.45).
+
+/** What `src/bundle/launcher.json` may set, each with its default filled in. */
+export type LauncherOptions = {
+    name: string | undefined
+    width: number
+    height: number
+    minWidth: number
+    minHeight: number
+    start: boolean
+    connect: boolean
+}
+
+const SIZES = ['width', 'height', 'minWidth', 'minHeight'] as const
+const FORMS = ['start', 'connect'] as const
+
+/** The launcher options under `root`, or the refusal naming what is wrong with them. */
+export async function launcherOptionsUnder(
+    root: string,
+): Promise<LauncherOptions | string> {
+    const options: LauncherOptions = {
+        name: undefined,
+        width: 1100,
+        height: 760,
+        minWidth: 480,
+        minHeight: 360,
+        start: true,
+        connect: true,
+    }
+    const file = Bun.file(`${root}/bundle/launcher.json`)
+    if (!(await file.exists())) return options
+    let given: unknown
+    try {
+        given = await file.json()
+    } catch (thrown) {
+        return `src/bundle/launcher.json is not JSON — ${(thrown as Error).message}`
+    }
+    if (given === null || typeof given !== 'object' || Array.isArray(given))
+        return 'src/bundle/launcher.json holds an object'
+    for (const [key, value] of Object.entries(given)) {
+        if (key === 'name' && typeof value === 'string') options.name = value
+        else if (
+            (SIZES as readonly string[]).includes(key) &&
+            typeof value === 'number' &&
+            value > 0
+        )
+            options[key as (typeof SIZES)[number]] = value
+        else if (
+            (FORMS as readonly string[]).includes(key) &&
+            typeof value === 'boolean'
+        )
+            options[key as (typeof FORMS)[number]] = value
+        else
+            return `src/bundle/launcher.json: \`${key}\` is not a launcher option, or ${JSON.stringify(value)} is not a value it takes`
+    }
+    // 38.82.
+    if (!options.start && !options.connect)
+        return 'src/bundle/launcher.json turns off both start and connect, which leaves the launcher nothing to do'
+    return options
+}

package/src/server/launcherPage.ts

@@ -0,0 +1,156 @@
+// 38.72 — THE DESKTOP LAUNCHER'S OWN PAGE: start the app here, under the configuration the form
+// holds, or connect to one running elsewhere. The app's own screen and not abide's, so it speaks
+// the platform's look rather than the docs site's.
+
+import { escapeAttribute, escapeText } from '#shared/escapeText.ts'
+import type { ConfigField } from './configFields.ts'
+
+/**
+ * What a launch page is rendered with: `src/bundle/launch.abide`'s props, and the built-in page's.
+ *
+ * 38.84 — a form the launcher does not offer has no address to post to.
+ */
+export type Launch = {
+    /** The app's name, as `launcher.json` gives it or as its package does. */
+    name: string
+    /** Where the start form posts, or `undefined` where `launcher.json` turns starting off. */
+    start: string | undefined
+    /** Where the connect form posts, or `undefined` where `launcher.json` turns connecting off. */
+    connect: string | undefined
+    fields: ConfigField[]
+    /** The URL the last connect was given. */
+    url: string
+    /** What went wrong with the last start or connect, and against which form. */
+    failure:
+        | {
+              form: 'start' | 'connect'
+              message: string
+              issues: Record<string, string[]>
+          }
+        | undefined
+    /** The form the page opens on. */
+    focus: 'start' | 'connect'
+}
+
+/** The built-in launcher page as markup. */
+export function launcherPage(page: Launch): string {
+    const startFailure =
+        page.failure?.form === 'start' ? page.failure : undefined
+    const connectFailure =
+        page.failure?.form === 'connect' ? page.failure : undefined
+    let inputs = ''
+    for (const field of page.fields) {
+        const issues = startFailure?.issues[field.name] ?? []
+        const id = `field-${escapeAttribute(field.name)}`
+        const name = escapeAttribute(field.name)
+        let control: string
+        if (field.input === 'checkbox')
+            control = `<input type="hidden" name="${name}" value="false"><input id="${id}" type="checkbox" name="${name}" value="true"${field.value === 'true' ? ' checked' : ''}>`
+        else if (field.input === 'select') {
+            let options = ''
+            for (const option of field.options ?? [])
+                options += `<option${option === field.value ? ' selected' : ''}>${escapeText(option)}</option>`
+            control = `<select id="${id}" name="${name}"${field.required ? ' required' : ''}>${options}</select>`
+        } else
+            control = `<input id="${id}" type="${field.input}" name="${name}" value="${escapeAttribute(field.value)}"${field.required ? ' required' : ''}${field.input === 'number' ? ' step="any"' : ''} autocomplete="off" spellcheck="false">`
+        inputs += `
+            <div class="field${field.input === 'checkbox' ? ' check' : ''}${issues.length > 0 ? ' invalid' : ''}">
+                <label for="${id}">${escapeText(field.label)}</label>
+                ${control}
+                ${field.description === undefined ? '' : `<p class="hint">${escapeText(field.description)}</p>`}
+                ${issues.map((issue) => `<p class="issue">${escapeText(issue)}</p>`).join('')}
+            </div>`
+    }
+    // 27.7's issues under `''` are the whole document's — a refinement across fields — and no
+    // field shows them.
+    const failureLine = (
+        failure:
+            | { message: string; issues: Record<string, string[]> }
+            | undefined,
+    ): string => {
+        if (failure === undefined) return ''
+        let line = `<p class="failure" role="alert">${escapeText(failure.message)}</p>`
+        for (const issue of failure.issues[''] ?? [])
+            line += `<p class="issue">${escapeText(issue)}</p>`
+        return line
+    }
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeText(page.name)}</title>
+<style>
+:root { color-scheme: light dark; --ground: #f5f5f7; --card: #fff; --ink: #1d1d1f; --muted: #6e6e73; --line: #d2d2d7; --accent: #0a84ff; --bad: #d70015; }
+@media (prefers-color-scheme: dark) { :root { --ground: #1c1c1e; --card: #2c2c2e; --ink: #f5f5f7; --muted: #98989d; --line: #3a3a3c; --bad: #ff6961; } }
+* { box-sizing: border-box; }
+html, body { margin: 0; height: 100%; }
+body { font: 13px/1.4 -apple-system, BlinkMacSystemFont, system-ui, sans-serif; background: var(--ground); color: var(--ink); display: flex; align-items: flex-start; justify-content: center; padding: 48px 24px; overflow-y: auto; -webkit-user-select: none; user-select: none; }
+main { width: 100%; max-width: 440px; }
+h1 { font-size: 22px; font-weight: 600; margin: 0 0 4px; letter-spacing: -0.01em; }
+.lede { color: var(--muted); margin: 0 0 24px; }
+section { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 20px; margin-bottom: 16px; }
+section.focus { border-color: var(--accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 20%, transparent); }
+h2 { font-size: 15px; font-weight: 600; margin: 0 0 4px; }
+section > p.about { color: var(--muted); margin: 0 0 16px; }
+.field { display: grid; gap: 4px; margin-bottom: 12px; }
+.field.check { grid-template-columns: auto 1fr; align-items: center; column-gap: 8px; }
+.field.check label { order: 2; }
+.field.check input[type=checkbox] { order: 1; margin: 0; }
+.field.check .hint, .field.check .issue { grid-column: 1 / -1; order: 3; }
+label { font-weight: 500; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+input[type=text], input[type=number], input[type=password], input[type=url], select { font: inherit; color: inherit; background: var(--ground); border: 1px solid var(--line); border-radius: 6px; padding: 6px 8px; width: 100%; -webkit-user-select: text; user-select: text; }
+input:focus, select:focus { outline: 3px solid color-mix(in srgb, var(--accent) 35%, transparent); outline-offset: 0; border-color: var(--accent); }
+.invalid input, .invalid select { border-color: var(--bad); }
+.hint { color: var(--muted); margin: 0; font-size: 12px; }
+.issue, .failure { color: var(--bad); margin: 0; font-size: 12px; }
+.failure { margin-bottom: 12px; -webkit-user-select: text; user-select: text; }
+.actions { display: flex; justify-content: flex-end; margin-top: 16px; }
+button { font: inherit; font-weight: 500; color: #fff; background: var(--accent); border: 0; border-radius: 6px; padding: 6px 16px; cursor: default; }
+button:active { filter: brightness(0.9); }
+button[disabled] { opacity: 0.6; }
+.empty { color: var(--muted); margin: 0; }
+</style>
+</head>
+<body>
+<main>
+    <h1>${escapeText(page.name)}</h1>
+    <p class="lede">${page.start === undefined ? 'Connect to the app where it is running.' : page.connect === undefined ? 'Start the app on this computer.' : 'Start the app on this computer, or connect to one already running.'}</p>
+${
+    page.start === undefined
+        ? ''
+        : `    <section id="start"${page.focus === 'start' ? ' class="focus"' : ''}>
+        <h2>Start</h2>
+        <p class="about">Runs the app here, with this configuration.</p>
+        <form method="post" action="${escapeAttribute(page.start)}">
+            ${failureLine(startFailure)}
+            ${inputs === '' ? '<p class="empty">This app takes no configuration.</p>' : inputs}
+            <div class="actions"><button type="submit">Start</button></div>
+        </form>
+    </section>`
+}
+    ${
+        page.connect === undefined
+            ? ''
+            : `    <section id="connect"${page.focus === 'connect' ? ' class="focus"' : ''}>
+        <h2>Connect</h2>
+        <p class="about">Opens the app running at another address.</p>
+        <form method="post" action="${escapeAttribute(page.connect)}">
+            ${failureLine(connectFailure)}
+            <div class="field${connectFailure === undefined ? '' : ' invalid'}">
+                <label for="connect-url">URL</label>
+                <input id="connect-url" type="url" name="url" value="${escapeAttribute(page.url)}" placeholder="https://" required autocomplete="off" spellcheck="false">
+            </div>
+            <div class="actions"><button type="submit">Connect</button></div>
+        </form>
+    </section>`
+    }
+</main>
+<script>
+for (const form of document.forms) form.addEventListener('submit', () => { for (const button of form.querySelectorAll('button')) { button.disabled = true; button.textContent = button.textContent === 'Start' ? 'Starting…' : 'Connecting…' } })
+document.querySelector('${page.focus === 'connect' ? '#connect-url' : '#start input:not([type=hidden]), #start select'}')?.focus()
+</script>
+</body>
+</html>
+`
+}

package/src/server/manifestOf.ts

@@ -0,0 +1,114 @@
+// 38.5 AND 38.29 — THE MANIFEST: the files the entry was written under, and each module a route
+// loads in a browser to every chunk that module needs before it can run. Read off the bundler's
+// own metafile rather than off the emitted code, so a chunk the bundler hoisted into a shared file
+// is in the list because the bundler says it is imported, not because a pattern over its output
+// happened to match.
+//
+// THE ENTRY'S NAME IS HERE BECAUSE A BUILD HASHES IT (38.5). `abide dev` names it by its source
+// (38.17) and reads it off this all the same, so the tags the document carries come from one
+// place in both lanes rather than from a constant in one and a lookup in the other.
+//
+// THE STATIC CLOSURE AND NOTHING ELSE. An `import-statement` edge is a chunk the module cannot
+// run without; a `dynamic-import` edge is a destination somebody may never navigate to, and
+// preloading it is the whole route table on every page.
+//
+// THE ENTRY IS LEFT OUT of every list, because the document already loads it by name (38.23) and
+// a preload of the same address is a second request line for bytes already on their way.
+
+import { resolve } from 'node:path' // bun exposes no path helpers of its own
+import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
+
+export type Manifest = {
+    /** The entry's file name, or undefined where the bundle has none — a dev build that failed. */
+    entry: string | undefined
+    /**
+     * The stylesheet the bundler collected under the entry, or undefined where none was imported.
+     *
+     * 38.24.
+     */
+    stylesheet: string | undefined
+    /** A module's path below `base` to the chunk file names it needs, its own first. */
+    chunks: Record<string, string[]>
+}
+
+export const NO_MANIFEST: Manifest = {
+    entry: undefined,
+    stylesheet: undefined,
+    chunks: {},
+}
+
+/**
+ * The manifest read off a bundle's metafile: the entry, its stylesheet, and each module's chunks.
+ *
+ * `base` IS THE TREE THE ROUTE TABLE NAMES MODULES BELOW. The metafile names a file on disk
+ * relative to the working directory with symlinks resolved, and a module a plugin served under its
+ * namespace as the plugin spelled it — so `abide build` passes its output's real path, and
+ * `abide dev` passes the virtual directory its plugin resolves into.
+ */
+export function manifestOf(
+    metafile: Bun.BuildMetafile,
+    base: string,
+): Manifest {
+    const manifest: Manifest = { ...NO_MANIFEST, chunks: {} }
+    const imports = new Map<string, string[]>()
+    const modules = new Map<string, string>()
+    const prefix = `${base}/`
+    for (const [output, described] of Object.entries(metafile.outputs)) {
+        if (!isModule(output)) continue
+        const statically: string[] = []
+        for (const edge of described.imports)
+            if (isModule(edge.path) && edge.kind === 'import-statement')
+                statically.push(chunkName(edge.path))
+        imports.set(chunkName(output), statically)
+
+        if (described.entryPoint === undefined) continue
+        const path = resolve(described.entryPoint.replace(/^[\w-]{2,}:/, ''))
+        if (!path.startsWith(prefix)) continue
+        const module = path.slice(prefix.length)
+        modules.set(module, chunkName(output))
+        if (module !== `${CLIENT_ENTRY}.ts`) continue
+        manifest.entry = chunkName(output)
+        // NOT IN bun-types, and in the metafile: the stylesheet an entry's CSS was collected into.
+        const sheet = (described as { cssBundle?: string }).cssBundle
+        manifest.stylesheet = sheet === undefined ? undefined : chunkName(sheet)
+    }
+
+    for (const [module, output] of modules) {
+        // THE ENTRY IS WALKED AND NOT LISTED: what it imports statically is as unfetched as the
+        // page's own chunk until the entry has arrived.
+        const needed: string[] = []
+        const seen = new Set<string>()
+        const stack = [output]
+        for (let next = stack.pop(); next !== undefined; next = stack.pop()) {
+            if (seen.has(next)) continue
+            seen.add(next)
+            if (next !== manifest.entry) needed.push(next)
+            for (const imported of imports.get(next) ?? []) stack.push(imported)
+        }
+        manifest.chunks[module] = needed
+    }
+    return manifest
+}
+
+/** Every chunk the modules need, once each, in the order they were first asked for. */
+export function chunksOf(modules: string[], manifest: Manifest): string[] {
+    const chunks = new Set<string>()
+    for (const module of modules)
+        for (const chunk of manifest.chunks[module] ?? []) chunks.add(chunk)
+    return [...chunks]
+}
+
+/**
+ * Whether a bundler output is a script module rather than a stylesheet.
+ *
+ * A MODULE, NOT A STYLESHEET. The bundler reports the CSS it collected both as a static import of
+ * the entry and as an output whose entry point IS the entry — so unfiltered it is fetched as a
+ * script, and it takes the entry's own place in the manifest. 38.24 links it already.
+ */
+function isModule(output: string): boolean {
+    return output.endsWith('.js')
+}
+
+function chunkName(output: string): string {
+    return output.startsWith('./') ? output.slice(2) : output
+}