@abide/abide 0.124.1 → 0.125.0

package/src/server/serveDev.ts

@@ -32,6 +32,7 @@ import { IDLE_TIMEOUT_SECONDS } from './IDLE_TIMEOUT_SECONDS.ts'
 import { muxSocketOptions, sendOrClose, upgraded } from './muxUpgrade.ts'
 import { placeOf } from './placement.ts'
 import { plainAnswer } from './plainAnswer.ts'
+import type { ReceivedFrom } from './requestScope.ts'
 import { askOver } from './responseRelay.ts'
 import { SETTLE_MILLISECONDS } from './SETTLE_MILLISECONDS.ts'
 
@@ -43,6 +44,8 @@ export type DevOptions = {
      */
     root: string
     port?: number | undefined
+    /** 38.136 — the interface the listener binds, every one where `undefined`. */
+    hostname?: string | undefined
 }
 
 // The app's process, spoken to in its own protocol.
@@ -63,7 +66,13 @@ const LAST_DEV_PORT = 3099
 // An app-mux socket's data: the id the worker knows its connection by, and what `Mux.connect` reads
 // off the upgrade. `undefined` on the reload client's.
 type Carried =
-    { connection: number; url: string; headers: [string, string][] } | undefined
+    | {
+          connection: number
+          url: string
+          headers: [string, string][]
+          from: ReceivedFrom
+      }
+    | undefined
 
 /**
  * `abide dev`'s listener, compiling the app here and serving it from a child process.
@@ -268,6 +277,9 @@ export async function serveDev(
     let muxOptions = muxSocketOptions()
     const serving = (port: number | undefined): Bun.Serve.Options<Carried> => ({
         ...(port === undefined ? {} : { port }),
+        ...(options.hostname === undefined
+            ? {}
+            : { hostname: options.hostname }),
         // 16.54, as `App.listen` lifts it: the worker behind this is where the ceiling is read.
         maxRequestBodySize: Number.MAX_SAFE_INTEGER,
         // 16.56 — the bound a request received whole lifts and its answer puts back (16.23).
@@ -281,10 +293,12 @@ export async function serveDev(
             const mux =
                 asked !== DEV_ADDRESS &&
                 request.headers.get('upgrade') === 'websocket'
-            if (!mux && asked !== DEV_ADDRESS) return relay.ask(request)
+            // 22.12 — the peer, which only this process can see, crosses with the request.
+            const from = listening.requestIP(request)
+            if (!mux && asked !== DEV_ADDRESS) return relay.ask(request, from)
             // 37.3 — THE MUX'S UPGRADE IS ASKED OF THE APP FIRST, whose lane runs in the worker.
             if (mux && ready) {
-                const answered = await relay.ask(request)
+                const answered = await relay.ask(request, from)
                 if (!relay.admitted(answered)) return answered
             }
             // NOT WHILE THE APP IS COMPILING. The reload client and the browser's mux both read a
@@ -298,6 +312,7 @@ export async function serveDev(
                     connection: nextConnection,
                     url: request.url,
                     headers: [...request.headers.entries()],
+                    from,
                 }
             }
             return upgraded(listening, request, data)

package/src/server/sqliteStore.ts

@@ -0,0 +1,65 @@
+import { Database } from 'bun:sqlite'
+
+import type { Store } from '#shared'
+import type { Schema } from '#shared/Schema.ts'
+import { expiresAfter, storedValue } from '#shared/storedValue.ts'
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** One connection per path a store names, so a `Keyed` building a store per entry opens one file. */
+const OPENED = new Map<string, Database>()
+
+/**
+ * A `Store` kept in a row of a `bun:sqlite` table, under `key`.
+ *
+ * 8.25 — the table is made where it is missing, and its shape is the store's: the key, the value as
+ * JSON, and the deadline 8.26 reads, as epoch milliseconds or `NULL` for never.
+ */
+export function sqliteStore<Stored>(
+    database: Database | string,
+    key: string,
+    options?: { table?: string; schema?: Schema<Stored> },
+): Store<Stored> {
+    const table = options?.table ?? 'abide_store'
+    if (!IDENTIFIER.test(table))
+        throw new Error(
+            `sqliteStore's table ${JSON.stringify(table)} is not an SQL identifier.`,
+        )
+    const db = typeof database === 'string' ? opened(database) : database
+    db.run(
+        `CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires INTEGER)`,
+    )
+    const schema = options?.schema as Schema<unknown> | undefined
+    const where = `${table}[${JSON.stringify(key)}]`
+    return {
+        get: () => {
+            const row = db
+                .query(`SELECT value, expires FROM ${table} WHERE key = ?`)
+                .get(key) as { value: string; expires: number | null } | null
+            if (row === null) return undefined
+            const value = storedValue(
+                { value: JSON.parse(row.value), expires: row.expires },
+                schema,
+                where,
+            )
+            // 8.26 — a row past its deadline is gone, not merely skipped.
+            if (value === undefined)
+                db.query(`DELETE FROM ${table} WHERE key = ?`).run(key)
+            return value as Stored | undefined
+        },
+        set: (value, retention) => {
+            db.query(
+                `INSERT INTO ${table} (key, value, expires) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires = excluded.expires`,
+            ).run(key, JSON.stringify(value), expiresAfter(retention.ttl))
+        },
+    }
+}
+
+function opened(path: string): Database {
+    let db = OPENED.get(path)
+    if (db === undefined) {
+        db = new Database(path, { create: true })
+        OPENED.set(path, db)
+    }
+    return db
+}

package/src/server/testMount.ts

@@ -36,6 +36,7 @@ export async function mount(component: Component): Promise<Mounted> {
         throw new Error(
             'abide: mount renders into a DOM, and this process has none. Preload `@abide/harness/preload` ahead of `@abide/abide/test` in bunfig.toml. RULEBOOK 38.119.',
         )
+    // 12.5 — the server pass's watches stop once its document is written, as any render's do.
     const html = new TextDecoder().decode(await render(component))
     // After the `<body …>` open tag, whatever attributes the component wrote onto it (35.15).
     document.body.innerHTML = html.slice(

package/src/shared/AssistantEvent.ts

@@ -0,0 +1,40 @@
+// SECTION 44 — WHAT A CONVERSATION IS MADE OF, on both sides: the transcript a page sends and the
+// events `assistant` yields back to it. Types alone, so the browser names what `ask()` hands it
+// without reaching for the server's entry.
+
+import type { Method } from './rpc.ts'
+
+/** A piece of a turn: words, or an image as base64 with its type. */
+export type AssistantContent =
+    | { type: 'text'; text: string }
+    | { type: 'image'; data: string; mimeType: string }
+
+/** One turn of the transcript a caller sends: its words, or its pieces in order. */
+export type AssistantMessage = {
+    role: 'user' | 'assistant'
+    content: string | AssistantContent[]
+}
+
+/** What a conversation yields, the same from every provider. */
+export type AssistantEvent =
+    | { type: 'text'; text: string }
+    | {
+          type: 'tool'
+          id: string
+          name: string
+          handler: { method: Method; address: string } | undefined
+      }
+    | { type: 'input'; id: string; input: unknown }
+    | {
+          type: 'result'
+          id: string
+          text: string
+          failed: boolean
+          handler: { method: Method; address: string } | undefined
+          value: unknown
+      }
+    | {
+          type: 'done'
+          stop: string
+          usage: { input: number; output: number }
+      }

package/src/shared/BrowserHooks.ts

@@ -0,0 +1,73 @@
+// 37.16, 37.18, 37.21 — A HOOK A COMPONENT FILES IN THE BROWSER, for as long as it stands, and what
+// it is handed: `onError`'s and `onRefusal`'s (37.22-37.25) are filed and handed by this one class,
+// so the two cannot come apart on where they file, whom they hand first, or what a throw does.
+
+import { namedLogger } from './log.ts'
+import { serverStops } from './reactive/scoping.ts'
+import { owned, settingUp } from './reactive/watch.ts'
+
+const LIFECYCLE_LOG = namedLogger('abide:lifecycle')
+
+/** The hooks of one name filed in this browser, and the walk that hands them what they hear. */
+export class BrowserHooks<Handed extends unknown[]> {
+    // IN THE ORDER FILED, which is outermost first: a layout's setup runs before the page inside it.
+    private readonly filed: { hook: (...handed: Handed) => unknown }[] = []
+    private readonly name: string
+    /** 37.21 — what a call that could never file throws. */
+    private readonly misplaced: string
+    /** Run before the first hook is filed — `onError`'s listeners. */
+    private first: (() => void) | undefined
+
+    constructor(name: string, misplaced: string, first?: () => void) {
+        this.name = name
+        this.misplaced = misplaced
+        this.first = first
+    }
+
+    /** Whether no hook is filed. */
+    empty(): boolean {
+        return this.filed.length === 0
+    }
+
+    /** Files `hook` while the calling component stands; returns what unfiles it. */
+    file(hook: (...handed: Handed) => unknown): () => void {
+        if (!settingUp()) {
+            // ONLY A BROWSER COLLECTS A SETUP, so a server's render — in a process with a document
+            // or without one — files nothing.
+            if (serverStops() !== undefined) return () => {}
+            // 37.21 — ANYWHERE ELSE IT COULD NEVER FILE: a call outside a component's setup has
+            // nothing to stand for.
+            throw new Error(this.misplaced)
+        }
+        if (this.first !== undefined) {
+            const first = this.first
+            this.first = undefined
+            first()
+        }
+        const entry = { hook }
+        const filed = this.filed
+        filed.push(entry)
+        return owned(() => {
+            const at = filed.indexOf(entry)
+            if (at !== -1) filed.splice(at, 1)
+        })
+    }
+
+    /**
+     * 37.17, 37.18 — hands every hook filed what it hears, NEAREST FIRST, which is the last filed. A
+     * hook that throws is written rather than handed on, where it would surface as uncaught.
+     */
+    hand(...handed: Handed): void {
+        const filed = this.filed
+        for (let at = filed.length - 1; at >= 0; at -= 1) {
+            // A hook that unfiled one on its way leaves the walk past the end.
+            const entry = filed[at]
+            if (entry === undefined) continue
+            try {
+                entry.hook(...handed)
+            } catch (thrown) {
+                LIFECYCLE_LOG.error(`an ${this.name} hook threw`, thrown)
+            }
+        }
+    }
+}

package/src/shared/CURRENT_ROUTER.ts

@@ -1,11 +1,13 @@
 /**
- * What a router offers `navigate`: a way to go to a URL.
+ * What a router offers `navigate`: a way to go to a URL, and a way to step the history.
  *
  * Named for what it DOES rather than what it is: `Navigator` is a DOM global, and a routing file
  * is the one place a reader would take the two for each other.
  */
 export type Navigable = {
     go(url: URL | string, options: NavigateOptions): Promise<void>
+    /** 30.38 — steps the history by `by` entries, settling once the step has arrived. */
+    step(by: number): Promise<void>
 }
 
 export type NavigateOptions = { replace?: boolean; keepScroll?: boolean }

package/src/shared/Issues.ts

@@ -11,6 +11,8 @@
 // nowhere to key by, and `{ '': string[] }` for that case is a wrapper every reader would
 // have to unwrap.
 
+import type { Rpc } from './rpc.ts'
+
 type Down = [0, 0, 1, 2, 3, 4]
 
 /**
@@ -43,7 +45,13 @@ export type Paths<T, Limit extends number = 5> = Limit extends 0
 
 /**
  * A refusal's messages keyed by path, `''` for the whole value, or a bare list over a scalar.
+ *
+ * 19.26 — over an `Rpc`, the `Issues` of what it is called with: a form holding a handler's
+ * refusal names the handler rather than spelling its `Args`.
  */
-export type Issues<T> = T extends object
-    ? Partial<Record<Paths<T> | '', string[]>>
-    : string[]
+export type Issues<T> =
+    T extends Rpc<infer _Value, infer Args, infer _Failures, infer _Produced>
+        ? Issues<Args>
+        : T extends object
+          ? Partial<Record<Paths<T> | '', string[]>>
+          : string[]

package/src/shared/Middleware.ts

@@ -7,18 +7,18 @@ import type { Failed } from './Failed.ts'
  * A rung written once for every lane whose context carries `Extra`: generic over the context it is
  * handed and over what `next` answers, so it passes `next()`'s answer on, refuses in its place, or
  * answers with an `Answer` of its own.
+ *
+ * `Refused` is what it may refuse with; a rung naming its refusals carries them onto the `Rpc` its
+ * handler is declared with (16.86), where one left at `Failed<string, unknown>` carries none.
  */
-export type Middleware<Answer = never, Extra extends object = object> = <
-    Given extends { request: Request } & Extra,
-    Result,
->(
+export type Middleware<
+    Answer = never,
+    Extra extends object = object,
+    Refused extends Failed<string, unknown> = Failed<string, unknown>,
+> = <Given extends { request: Request } & Extra, Result>(
     next: (ctx?: Given) => Promise<Result>,
     ctx: Given,
-) =>
-    | Result
-    | Answer
-    | Failed<string, unknown>
-    | Promise<Result | Answer | Failed<string, unknown>>
+) => Result | Answer | Refused | Promise<Result | Answer | Refused>
 
 /** A rung as one lane composes it, over that lane's context and what its center answers. */
 export type Rung<Ctx, Result> = (

package/src/shared/UNEXPECTED.ts

@@ -4,7 +4,7 @@
  * 12.6 — filled by `#server/installServer.ts` with the `onError` hooks and nothing else: the core warns on
  * its own namespace, so the lifecycle log is not written a second time. A leaf, for `RPC_SERVER`'s
  * reason: the reactive core reports through it and a browser bundle must not reach what fills it.
- * `null` in a browser, which has no `onError`.
+ * In a browser, filled by the first `onError` filed there (37.16), and `null` until one is.
  */
 export const UNEXPECTED: { report: ((error: unknown) => void) | null } = {
     report: null,

package/src/shared/answerOf.ts

@@ -12,6 +12,7 @@ import {
     framingOf,
 } from './framing.ts'
 import { KEPT_HEADER } from './KEPT_HEADER.ts'
+import { refused, type RefusedCall } from './onRefusal.ts'
 import { principalRotated } from './principalRotated.ts'
 import { refuse } from './refuse.ts'
 import type { RpcRequest } from './rpcRequest.ts'
@@ -179,13 +180,14 @@ function answerFrom(
  * What a call's body hands back: the value, nothing (16.31), or the refusal it was answered with.
  *
  * The refusal (15.1) is rebuilt as the `Failed` the server returned. RETURNED, so the value refuses
- * (15.5) rather than failing the way a network error does.
+ * (15.5) rather than failing the way a network error does — and handed to `onRefusal` (37.24) on
+ * its way, `call` being the request it answers.
  *
  * 16.32 — A FRAMED STREAM IS COLLECTED INTO THE CHUNKS IT CARRIED, which is the value a streaming
  * handler holds once its run has closed — for a copy the build did not mark as streaming, whose
  * value is one production. A marked one reads its body as it lands (`framedStream`).
  */
-export function answered(answer: Answer): unknown {
+export function answered(answer: Answer, call: RefusedCall): unknown {
     if (answer.status === 204) return undefined
     if (answer.ok) {
         // 16.34 — a binary decodes back to the bytes it was.
@@ -200,6 +202,9 @@ export function answered(answer: Answer): unknown {
         body = undefined
     }
     if (answer.ok) return body
-    if (isProblem(body)) return failedFrom(body)
-    return refuse(answer.status, answer.statusText || undefined)
+    const refusal = isProblem(body)
+        ? failedFrom(body)
+        : refuse(answer.status, answer.statusText || undefined)
+    refused(refusal, call)
+    return refusal
 }

package/src/shared/imagePiece.ts

@@ -0,0 +1,85 @@
+// 44.52-44.55 — AN IMAGE A VISITOR PASTES, DROPS OR PICKS, as the piece a turn carries it in. In
+// the browser it is drawn down to what a model looks at, so a full-size screenshot is not sent whole
+// with every turn of the transcript; where nothing can draw (a server) it goes as it is.
+
+import type { AssistantContent } from './AssistantEvent.ts'
+import { IMAGE_TYPES } from './IMAGE_TYPES.ts'
+
+// The longest side, in pixels, a model looks at before it scales an image down itself.
+const LONG_EDGE = 1568
+const JPEG_QUALITY = 0.9
+
+/** The image files a paste or a drop carries of a type a model is shown, in order. 44.55. */
+export function imageFiles(data: DataTransfer | null): File[] {
+    const files: File[] = []
+    if (data === null) return files
+    for (const file of data.files)
+        if (IMAGE_TYPES.has(file.type)) files.push(file)
+    if (files.length > 0) return files
+    // A pasted image some browsers carry in `items` alone.
+    for (const item of data.items) {
+        if (item.kind !== 'file' || !IMAGE_TYPES.has(item.type)) continue
+        const file = item.getAsFile()
+        if (file !== null) files.push(file)
+    }
+    return files
+}
+
+/** `image` as a turn's image piece, drawn down to `LONG_EDGE` on its long side. 44.52, 44.53, 44.54. */
+export async function imagePiece(
+    image: Blob,
+): Promise<Extract<AssistantContent, { type: 'image' }>> {
+    const shown = IMAGE_TYPES.has(image.type)
+    // A GIF may move, and drawing it keeps one frame.
+    if (image.type !== 'image/gif' && typeof createImageBitmap === 'function') {
+        const drawn = await drawnDown(image, shown).catch(() => undefined)
+        if (drawn !== undefined)
+            return {
+                type: 'image',
+                data: await base64Of(drawn),
+                mimeType: drawn.type,
+            }
+    }
+    if (!shown)
+        throw new Error(
+            `abide: an image of ${image.type || 'no type'} could not be drawn as one a model is shown, ${[...IMAGE_TYPES].join(', ')}. RULEBOOK 44.54.`,
+        )
+    return { type: 'image', data: await base64Of(image), mimeType: image.type }
+}
+
+/**
+ * `image` drawn at most `LONG_EDGE` on its long side, or `undefined` where it is already that and of
+ * a type a model is shown. A photo stays a JPEG, and anything else becomes a PNG, sharp text and all —
+ * but a type a model is not shown (a HEIC) is a photo.
+ */
+async function drawnDown(
+    image: Blob,
+    shown: boolean,
+): Promise<Blob | undefined> {
+    const bitmap = await createImageBitmap(image)
+    try {
+        const scale = Math.min(
+            1,
+            LONG_EDGE / Math.max(bitmap.width, bitmap.height),
+        )
+        if (scale === 1 && shown) return undefined
+        const canvas = new OffscreenCanvas(
+            Math.round(bitmap.width * scale),
+            Math.round(bitmap.height * scale),
+        )
+        canvas
+            .getContext('2d')
+            ?.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+        const type =
+            image.type === 'image/png' || image.type === 'image/webp'
+                ? 'image/png'
+                : 'image/jpeg'
+        return await canvas.convertToBlob({ type, quality: JPEG_QUALITY })
+    } finally {
+        bitmap.close()
+    }
+}
+
+async function base64Of(blob: Blob): Promise<string> {
+    return new Uint8Array(await blob.arrayBuffer()).toBase64()
+}

package/src/shared/index.ts

@@ -10,6 +10,12 @@
 // value (15.1), so it is in this seam rather than the server's: the same object crosses a
 // wire, fills `s.error` and narrows through `s.isError`.
 
+// 44 — a conversation as a page sends it and is handed it back: the server's `assistant` yields it.
+export type {
+    AssistantContent,
+    AssistantEvent,
+    AssistantMessage,
+} from './AssistantEvent.ts'
 // 33.23 — an element's attributes, typed as a component's props.
 export type { Attributes } from './Attributes.ts'
 // 32.37 — what a value writes into an attribute, on both sides.
@@ -27,8 +33,11 @@ export { escapeAttribute, escapeStyleValue, escapeText } from './escapeText.ts'
 export { type Failed, isFailed } from './Failed.ts'
 // 25 — the account of the app.
 export { type Health, health } from './health.ts'
+// 44.52-44.55 — a pasted, dropped or picked image as a turn's piece.
+export { imageFiles, imagePiece } from './imagePiece.ts'
 export type { Issues, Paths } from './Issues.ts'
 export type { JsonValue } from './JsonValue.ts'
+export { isServer } from './isServer.ts'
 export { jsonSchema } from './jsonSchema.ts'
 // 32.15's run-time half. In this seam because BOTH sides ask it what a `{#for}` subject iterates
 // as — the server's emitted block, the client's `updateList`, and the markup a client builds for a
@@ -52,7 +61,11 @@ export {
 export { navigate } from './navigate.ts'
 export { online } from './online.ts'
 export { outbox, type QueuedCall } from './outbox.ts'
+// 37.16 — the browser's `onError`. `@abide/abide/server` exports the server's over it.
+export { onError } from './onError.ts'
 export { onMenu } from './onMenu.ts'
+// 37.22 — the browser's `onRefusal`, which has no server's.
+export { onRefusal } from './onRefusal.ts'
 export { type Principal, principal } from './principal.ts'
 // EMITTED CODE'S: a prop the child writes (33.6, 33.7), and one it hands where a `Reactive` is due (33.27).
 export {
@@ -96,6 +109,8 @@ export {
     watch,
 } from './reactive/index.ts'
 export { aborted, notFound, refuse, validationError } from './refuse.ts'
+// 44.51 — what a conversation's calls to one handler answered.
+export { resultsOf } from './resultsOf.ts'
 export { route } from './route.ts'
 export type { Schema, StandardSchemaV1 } from './Schema.ts'
 export { safeUrl } from './safeUrl.ts'
@@ -119,4 +134,6 @@ export {
     url,
 } from './url.ts'
 export { validateJson } from './validateJson.ts'
+// 8.22 — a `Store` in the browser's Web Storage, inert where there is none (8.23).
+export { webStore } from './webStore.ts'
 export { mutatePath, writePath } from './writePath.ts'

package/src/shared/isServer.ts

@@ -0,0 +1,15 @@
+// 22.11 — WHICH SIDE THE WORK RUNNING IS ON, read where it runs rather than fixed at build or load.
+//
+// NOT `typeof document`: a test process preloads a DOM and runs both halves of a page through one
+// instance of every module — `App.fetch` and `mount`'s render are a server's, `mount`'s hydration a
+// browser's — so the globals are the same on both sides and a build-time constant is one answer for
+// two. What tells them apart is what the server alone enters: a request scope, or a render (the
+// provider's `serverStops`). A process with no document at all is a server whatever it is doing.
+
+import { serverStops } from './reactive/scoping.ts'
+
+/** Whether the work running is a server's. */
+export function isServer(): boolean {
+    if (typeof document === 'undefined') return true
+    return serverStops() !== undefined
+}

package/src/shared/navigate.ts

@@ -1,7 +1,8 @@
 import { CURRENT_ROUTER, type NavigateOptions } from './CURRENT_ROUTER.ts'
 
 /**
- * Navigates the document's router to a URL without reloading; rejects where there is no router.
+ * Navigates the document's router to a URL, or steps its history by a number of entries, without
+ * reloading; rejects where there is no router.
  *
  * 30.7 — NAVIGATES, AND MUST NOT RELOAD THE DOCUMENT. The whole of that clause lives in the client
  * router; this is the app-facing name, and it sits on the isomorphic seam because that is the
@@ -11,8 +12,13 @@ import { CURRENT_ROUTER, type NavigateOptions } from './CURRENT_ROUTER.ts'
  * refuses rather than resolving quietly — a `navigate` that no-ops during a render is a page that
  * renders the wrong thing and says nothing.
  */
+export function navigate(by: number): Promise<void>
 export function navigate(
-    url: URL | string = '',
+    url?: URL | string,
+    options?: NavigateOptions,
+): Promise<void>
+export function navigate(
+    to: URL | string | number = '',
     options: NavigateOptions = {},
 ): Promise<void> {
     const router = CURRENT_ROUTER.current
@@ -22,5 +28,6 @@ export function navigate(
                 'navigate() was called with no router in this document. A browser gets one from the routes the build emitted; a server render has no document to navigate (RULEBOOK 30.7).',
             ),
         )
-    return router.go(url, options)
+    // 30.38 — A NUMBER IS A STEP THROUGH THE HISTORY, as `history.go` takes one.
+    return typeof to === 'number' ? router.step(to) : router.go(to, options)
 }

package/src/shared/onError.ts

@@ -0,0 +1,51 @@
+// 37.16, 37.17, 37.18 — THE BROWSER'S `onError`: the name and the signature `@abide/abide/server`'s
+// has, called in a `<script>` rather than a `<script server>`, and filed while the component that
+// called it stands — so a layout's hears every page below it, as the server's hears every route
+// below it. A server's is `#server/hooks.ts`'s, which `@abide/abide/server` exports over this one;
+// this one called in a server's render files nothing.
+//
+// WHAT NOTHING CAUGHT IS THE BROWSER'S OWN ACCOUNT: the window's `error` event and its
+// `unhandledrejection`, which a call's refusal no handler awaited or caught arrives as. 12.6's
+// throws are handed through `UNEXPECTED` as they are on a server, and the one of them that then
+// surfaces as uncaught (12.7) is not handed a second time.
+
+import { BrowserHooks } from './BrowserHooks.ts'
+import { UNEXPECTED } from './UNEXPECTED.ts'
+
+const HOOKS = new BrowserHooks<[error: unknown]>(
+    'onError',
+    "abide: onError of `@abide/abide` files only in a component's <script>; a <script server> or a server module files the server's, of `@abide/abide/server`. RULEBOOK 37.21.",
+    listen,
+)
+
+// What 12.6 handed and 12.7 may yet surface as uncaught, held until the task that handed it is over.
+const SURFACING: unknown[] = []
+
+/** Files `hook` for every failure nothing caught while the calling component stands; returns what unfiles it. */
+export function onError(hook: (error: unknown) => unknown): () => void {
+    return HOOKS.file(hook)
+}
+
+function listen(): void {
+    // A SERVER'S SLOT IS LEFT AS IT IS: a test with a document and a server has both lanes.
+    UNEXPECTED.report ??= handedUnexpected
+    addEventListener('error', (event) => surfaced((event as ErrorEvent).error))
+    addEventListener('unhandledrejection', (event) =>
+        surfaced((event as PromiseRejectionEvent).reason),
+    )
+}
+
+function handedUnexpected(error: unknown): void {
+    if (SURFACING.length === 0) setTimeout(() => (SURFACING.length = 0))
+    SURFACING.push(error)
+    HOOKS.hand(error)
+}
+
+function surfaced(error: unknown): void {
+    const at = SURFACING.indexOf(error)
+    if (at !== -1) {
+        SURFACING.splice(at, 1)
+        return
+    }
+    HOOKS.hand(error)
+}

package/src/shared/onRefusal.ts

@@ -0,0 +1,47 @@
+// 37.22-37.27 — THE BROWSER'S `onRefusal`: filed as the browser's `onError` is, and handed every
+// refusal a call over http is answered with in this browser — a refusal settles as the value's
+// `error` rather than throwing, so `onError` never hears one a page read.
+//
+// HANDED WHERE AN ANSWER BECOMES A `Failed`, `answered` in `answerOf.ts`, which every browser call
+// reads its answer through — a handler's `wire`, a handler abide mounts, and a call `outbox` sends —
+// so no caller carries a branch of its own. An aborted call is never answered (16.49), and a call
+// 16.81 settles to a stand-in is not refused.
+
+import { BrowserHooks } from './BrowserHooks.ts'
+import type { Failed } from './Failed.ts'
+import { untracked } from './reactive/tracking.ts'
+import type { Method } from './rpc.ts'
+
+export type RefusedCall = { method: Method; url: string }
+
+const HOOKS = new BrowserHooks<
+    [refusal: Failed<string, unknown>, call: RefusedCall]
+>(
+    'onRefusal',
+    "abide: onRefusal files only in a component's <script>. RULEBOOK 37.23.",
+)
+
+/** Files `hook` for every refusal a call is answered with while the calling component stands; returns what unfiles it. */
+export function onRefusal(
+    hook: (refusal: Failed<string, unknown>, call: RefusedCall) => unknown,
+): () => void {
+    return HOOKS.file(hook)
+}
+
+/** 37.24 — hands `refusal`, the answer to `call`, to every `onRefusal` filed. */
+export function refused(
+    refusal: Failed<string, unknown>,
+    call: RefusedCall,
+): void {
+    if (HOOKS.empty()) return
+    // UNTRACKED: an answer the server painted settled is read inside the value's body (41.27), and a
+    // hook's read there would subscribe that value to whatever the hook reads.
+    untracked(handRefused, refusal, { method: call.method, url: call.url })
+}
+
+function handRefused(
+    refusal: Failed<string, unknown>,
+    call: RefusedCall,
+): void {
+    HOOKS.hand(refusal, call)
+}