@abide/abide 0.58.0 → 0.101.0

package/src/shared/cookies.ts

@@ -0,0 +1,271 @@
+// SECTION 22 — `cookies`, on both sides: the request's cookies on a server, the document's in a
+// browser, each a jar shaped as bun's `CookieMap`. A read by name tracks THAT name (22.4) and a write
+// wakes that name's readers alone (22.5): a version per name, bumped on a write, is what a read
+// subscribes to — the values themselves are a plain map.
+//
+// WHERE THE JAR COMES FROM IS A SLOT the server fills (`#server/installServer.ts`), for `TRACE`'s
+// reason: this seam cannot name the request scope, and a browser bundle must not reach it.
+
+import { decodedOrKept } from './decodedOrKept.ts'
+import { type Reactive, reactive } from './reactive/index.ts'
+
+type CookieInit = Bun.CookieInit
+type CookieStoreDeleteOptions = Bun.CookieStoreDeleteOptions
+
+/**
+ * A cookie jar shaped as bun's `CookieMap`, whose reads track the name they read (22.4, 22.5).
+ */
+export class Cookies implements Iterable<[string, string]> {
+    held: Map<string, string>
+    versions: Map<string, Reactive<number>>
+    /** Any change at all, for a reader of the whole jar — `size`, the iterators, `toJSON`. */
+    every: Reactive<number>
+    /** Where a write goes: onto the response on a server, into `document.cookie` in a browser. */
+    sink: (serialized: string) => void
+    writes: string[]
+    inBrowser: boolean
+
+    constructor(
+        header: string,
+        sink: (serialized: string) => void,
+        inBrowser: boolean,
+    ) {
+        this.held = parseCookies(header)
+        this.versions = new Map()
+        this.every = reactive(0)
+        this.sink = sink
+        this.writes = []
+        this.inBrowser = inBrowser
+    }
+
+    /** The named cookie's value, or `null` — a read that tracks that name (22.4). */
+    get(name: string): string | null {
+        this.versionOf(name)()
+        return this.held.get(name) ?? null
+    }
+
+    has(name: string): boolean {
+        this.versionOf(name)()
+        return this.held.has(name)
+    }
+
+    set(name: string, value: string, options?: CookieInit): void
+    set(options: CookieInit): void
+    set(
+        first: string | CookieInit,
+        value?: string,
+        options?: CookieInit,
+    ): void {
+        const init: CookieInit =
+            typeof first === 'string'
+                ? { ...options, name: first, value: value ?? '' }
+                : first
+        const name = init.name ?? ''
+        if (name === '')
+            throw new Error('abide: cookies().set was given no name.')
+        const expired =
+            init.maxAge !== undefined && init.maxAge <= 0
+                ? true
+                : init.expires !== undefined &&
+                  new Date(init.expires).getTime() <= Date.now()
+        this.write(name, init, expired ? undefined : (init.value ?? ''))
+    }
+
+    delete(name: string): void
+    delete(options: CookieStoreDeleteOptions): void
+    delete(name: string, options: Omit<CookieStoreDeleteOptions, 'name'>): void
+    delete(
+        first: string | CookieStoreDeleteOptions,
+        options?: Omit<CookieStoreDeleteOptions, 'name'>,
+    ): void {
+        const given =
+            typeof first === 'string' ? { ...options, name: first } : first
+        const expired: CookieInit = { name: given.name, value: '', expires: 0 }
+        if (given.path !== undefined) expired.path = given.path
+        if (given.domain !== undefined && given.domain !== null)
+            expired.domain = given.domain
+        this.write(given.name, expired, undefined)
+    }
+
+    get size(): number {
+        this.every()
+        return this.held.size
+    }
+
+    toJSON(): Record<string, string> {
+        this.every()
+        return Object.fromEntries(this.held)
+    }
+
+    /**
+     * The `set-cookie` lines this jar has written, in order — a server's alone.
+     *
+     * A browser's jar lives as long as the page and its writes went into the document, so it keeps
+     * none: held, they grew one line per write with nothing to read them.
+     */
+    toSetCookieHeaders(): string[] {
+        return [...this.writes]
+    }
+
+    entries(): IterableIterator<[string, string]> {
+        this.every()
+        return this.held.entries()
+    }
+
+    keys(): IterableIterator<string> {
+        this.every()
+        return this.held.keys()
+    }
+
+    values(): IterableIterator<string> {
+        this.every()
+        return this.held.values()
+    }
+
+    forEach(
+        callback: (value: string, key: string, map: Cookies) => void,
+    ): void {
+        this.every()
+        for (const [key, value] of this.held) callback(value, key, this)
+    }
+
+    [Symbol.iterator](): IterableIterator<[string, string]> {
+        return this.entries()
+    }
+
+    versionOf(name: string): Reactive<number> {
+        let version = this.versions.get(name)
+        if (version === undefined) {
+            version = reactive(0)
+            this.versions.set(name, version)
+        }
+        return version
+    }
+
+    /** Wakes that name's readers, and the whole jar's (22.5). */
+    changed(name: string): void {
+        const version = this.versions.get(name)
+        if (version !== undefined) version.set((version.peek() ?? 0) + 1)
+        this.every.set((this.every.peek() ?? 0) + 1)
+    }
+
+    // The sink FIRST: a write it refuses (22.10) leaves the jar as it was.
+    write(name: string, init: CookieInit, value: string | undefined): void {
+        const serialized = serializeCookie(init, this.inBrowser)
+        this.sink(serialized)
+        if (!this.inBrowser) this.writes.push(serialized)
+        if (value === undefined) this.held.delete(name)
+        else this.held.set(name, value)
+        this.changed(name)
+    }
+}
+
+/**
+ * Whether a cookie is `Secure` when its options do not say.
+ *
+ * 22.3 — `secure` DEFAULTS FROM `NODE_ENV` on a server; a browser has no environment, and the page's
+ * own protocol is the same question asked of the one thing it does have.
+ */
+function secureByDefault(inBrowser: boolean): boolean {
+    if (inBrowser) return location.protocol === 'https:'
+    return (
+        typeof process !== 'undefined' && process.env.NODE_ENV === 'production'
+    )
+}
+
+/** One `set-cookie` line for a write, with 22.3's defaults filled in. */
+export function serializeCookie(init: CookieInit, inBrowser: boolean): string {
+    let line = `${init.name}=${encodeURIComponent(init.value ?? '')}`
+    line += `; Path=${init.path ?? '/'}`
+    if (init.domain !== undefined) line += `; Domain=${init.domain}`
+    if (init.expires !== undefined)
+        line += `; Expires=${new Date(init.expires).toUTCString()}`
+    if (init.maxAge !== undefined) line += `; Max-Age=${init.maxAge}`
+    if (init.secure ?? secureByDefault(inBrowser)) line += '; Secure'
+    // 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')}`
+    if (init.partitioned === true) line += '; Partitioned'
+    return line
+}
+
+function capitalised(sameSite: string): string {
+    return sameSite.charAt(0).toUpperCase() + sameSite.slice(1)
+}
+
+/**
+ * A `Cookie` header, or `document.cookie`, as a map of decoded values.
+ *
+ * THE JAR HOLDS VALUES DECODED, whichever path fills it: `serializeCookie` encodes, and the header,
+ * `document.cookie` and a `cookieStore` change all carry the encoded text.
+ */
+function parseCookies(header: string): Map<string, string> {
+    const parsed = new Map<string, string>()
+    for (const pair of header.split(';')) {
+        const at = pair.indexOf('=')
+        if (at === -1) continue
+        const name = pair.slice(0, at).trim()
+        if (name === '') continue
+        parsed.set(name, decodedOrKept(pair.slice(at + 1).trim()))
+    }
+    return parsed
+}
+
+/**
+ * The slot `cookies()` reads its jar through: the document's by default, the request's once the
+ * server fills it (`#server/installServer.ts`).
+ */
+export const COOKIES: { current: () => Cookies } = {
+    current: browserCookies,
+}
+
+let documentJar: Cookies | undefined
+
+/**
+ * The document's jar, one per page, built on first ask.
+ *
+ * 22.6 — where the browser reports a change made outside this jar
+ * (another tab, a server's `set-cookie`), that name's readers wake; 22.7 — where it does not, nothing
+ * does, and the jar is what it last read.
+ */
+export function browserCookies(): Cookies {
+    if (documentJar !== undefined) return documentJar
+    if (typeof document === 'undefined')
+        throw new Error(
+            'abide: cookies() was called outside a request, and on a server it reads the request being served. RULEBOOK 22.8.',
+        )
+    const jar = new Cookies(
+        document.cookie,
+        (serialized) => {
+            // biome-ignore lint/suspicious/noDocumentCookie: the Cookie Store API is asynchronous and missing from some browsers, and a read of the jar is synchronous.
+            document.cookie = serialized
+        },
+        true,
+    )
+    documentJar = jar
+    const store = (globalThis as { cookieStore?: EventTarget }).cookieStore
+    store?.addEventListener('change', (event) => {
+        const { changed = [], deleted = [] } = event as unknown as {
+            changed?: { name: string; value?: string }[]
+            deleted?: { name: string }[]
+        }
+        for (const cookie of changed) {
+            const value = decodedOrKept(cookie.value ?? '')
+            if (jar.held.get(cookie.name) === value) continue
+            jar.held.set(cookie.name, value)
+            jar.changed(cookie.name)
+        }
+        for (const cookie of deleted) {
+            if (!jar.held.has(cookie.name)) continue
+            jar.held.delete(cookie.name)
+            jar.changed(cookie.name)
+        }
+    })
+    return jar
+}
+
+/** The cookies of the request being served, or of the document (22.2). */
+export function cookies(): Cookies {
+    return COOKIES.current()
+}

package/src/shared/csp.ts

@@ -0,0 +1,55 @@
+// SECTION 29 — THE CONTENT SECURITY POLICY, by one name on both sides. The rung and the nonce a
+// response carries are the server's (`#server/csp.ts`, which `installServer` fills `CSP` with); a browser has no response to
+// mint one for, so `csp.nonce` answers the one its document was served with, which is what a
+// binding that wrote it on the server hydrates to.
+
+import type { Middleware } from './Middleware.ts'
+
+type Rung = Middleware<{ request: Request }, Response>
+
+/**
+ * The server's content-security-policy half, as slots `#server/installServer.ts` fills from
+ * `#server/csp.ts`.
+ *
+ * Until it does, `rung` refuses and `nonce` reads the document's.
+ */
+export const CSP: {
+    rung: (sources: Record<string, string[]> | undefined) => Rung
+    nonce: () => string
+} = {
+    rung: () => {
+        throw new Error(
+            'abide: csp is a server rung, and it was run in a browser. RULEBOOK 29.1.',
+        )
+    },
+    nonce: documentNonce,
+}
+
+/**
+ * The nonce this document's scripts were served with, or `''`.
+ *
+ * 29.11. A browser blanks the `nonce` ATTRIBUTE once the document is parsed and keeps the value in
+ * the element's `nonce` property, so the property is read first; a DOM with no such property (the
+ * emulator the tests render into) still has the attribute.
+ */
+export function documentNonce(): string {
+    const script = document.querySelector<HTMLScriptElement>('script[nonce]')
+    return script?.nonce || script?.getAttribute('nonce') || ''
+}
+
+/**
+ * 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.
+ */
+export const csp = Object.assign(
+    (sources?: Record<string, string[]>): Rung => {
+        let built: Rung | undefined
+        return (next, ctx) => {
+            built ??= CSP.rung(sources)
+            return built(next, ctx)
+        }
+    },
+    { nonce: (): string => CSP.nonce() },
+)

package/src/shared/decodedOrKept.ts

@@ -0,0 +1,14 @@
+/**
+ * Text percent-decoded, or as it came where it will not decode.
+ *
+ * A malformed escape names nothing better than its own spelling. Text with no `%` has nothing to
+ * decode.
+ */
+export function decodedOrKept(text: string): string {
+    if (!text.includes('%')) return text
+    try {
+        return decodeURIComponent(text)
+    } catch {
+        return text
+    }
+}

package/src/shared/escapeText.ts

@@ -0,0 +1,103 @@
+// 32.1 — `{expr}` renders escaped. In #shared because BOTH sides parse markup now: the server
+// writes the document, and a client swapping a `{#if}` branch re-renders that region's markup.
+// A text run is still written through `data`, which is not a parse and needs none of this —
+// `escapeless` in #ui is that path, and the two sitting apart is what keeps them from being
+// confused for one another.
+
+import { RAW_WRITES, Raw, textOf } from './Raw.ts'
+
+// The common slot holds nothing to escape, so the scan is the fast path and the rewrite is
+// 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:
+// 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.
+const SPECIAL = /[&<>]/
+
+/** A slot value as markup text: escaped, or a `Raw`'s html as it is. */
+export function escapeText(value: unknown): string {
+    // 32.26 — a branded raw value renders unescaped, and the brand is read FIRST: `String(value)`
+    // below turns a `Raw` into its html and the scan then escapes exactly the markup the brand
+    // was put on to keep. What the check costs is in `Raw.ts`, and why it is counted is `markupRun`.
+    if (value instanceof Raw) {
+        RAW_WRITES.count += 1
+        return value.html
+    }
+    return escapeMarkup(value == null ? '' : String(value))
+}
+
+// The rewrite alone, with no brand read — the one both slot and attribute escaping run.
+function escapeMarkup(text: string): string {
+    const at = text.search(SPECIAL)
+    if (at === -1) return text
+
+    // SLICED, NOT APPENDED PER CHARACTER. The tail after an escape is copied in one piece, so the
+    // concatenation count is the number of ESCAPES rather than the length — 4x on a 2 KB string
+    // carrying one, and the difference grows with what follows it.
+    let out = text.slice(0, at)
+    let cut = at
+    for (let i = at; i < text.length; i += 1) {
+        const code = text.charCodeAt(i)
+        if (code !== 38 && code !== 60 && code !== 62) continue
+        if (i > cut) out += text.slice(cut, i)
+        out += code === 38 ? '&amp;' : code === 60 ? '&lt;' : '&gt;'
+        cut = i + 1
+    }
+    return cut < text.length ? out + text.slice(cut) : out
+}
+
+/**
+ * A value escaped for a double-quoted attribute, a `Raw` included.
+ *
+ * The same rewrite as a slot's, plus the quote that would end it. A separate function rather than
+ * a flag: the flag would be read on every slot to answer a question the call site already knows.
+ *
+ * 32.26 IS A SLOT'S CLAUSE, NOT AN ATTRIBUTE'S. Delegating straight to `escapeText` handed the
+ * brand this path too, so `<iframe srcdoc={raw(html)}>` copied markup into a value a browser
+ * parses as a document, and `title={raw('AT&T')}` lost the `&` encoding — which is the only thing
+ * standing behind `safeUrl`'s scheme check, per 32.28. A `Raw` here is escaped like the string it
+ * holds, which is why this runs the rewrite rather than `escapeText`.
+ */
+export function escapeAttribute(value: unknown): string {
+    return escapeQuote(escapeMarkup(textOf(value)))
+}
+
+/**
+ * Text with only its `"` encoded: the one rewrite the author's own attribute text takes.
+ *
+ * 32.27 — it is markup, so its `&` stays a reference, and only the `"` that would end the
+ * attribute is encoded.
+ */
+export function escapeQuote(text: string): string {
+    return text.includes('"') ? text.replaceAll('"', '&quot;') : text
+}
+
+/**
+ * A `style:prop` value escaped for markup and cut at its first `;`.
+ *
+ * 32.10 — A `style:prop` SETS ONE PROPERTY, and `;` is the one character that lets a value say
+ * otherwise. The attribute escaping cannot see it, because `;` is ordinary in every other
+ * attribute: `style:color={v}` with `v` off the wire wrote `color: red; position: fixed; top: 0;
+ * …` — seven declarations from the slot that declares one, and an overlay over the page. Cut at
+ * the separator rather than encoded, because there is no encoding of `;` a CSS parser reads as a
+ * literal semicolon inside a value.
+ */
+export function escapeStyleValue(value: unknown): string {
+    return oneStyleValue(escapeAttribute(value))
+}
+
+/**
+ * Text up to its first `;`: one style declaration's value, with no escaping.
+ *
+ * The cut ALONE, with no escaping in front of it, because the client writes a `style:prop` through
+ * the CSSOM and that is not a parse (`setStyleProperty`). Lifted out rather than copied: the guard
+ * in `escapeStyleValue` and the client's write have to drop at the same character, and a CSSOM
+ * that refuses the whole value where the server kept its first declaration is the two disagreeing
+ * about what one `style:prop` rendered.
+ */
+export function oneStyleValue(text: string): string {
+    const end = text.indexOf(';')
+    return end === -1 ? text : text.slice(0, end)
+}

package/src/shared/framing.ts

@@ -0,0 +1,131 @@
+// 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.
+
+/**
+ * What precedes a chunk's JSON on its line: nothing for jsonl, `data: ` for sse, and `null` where
+ * the answer is not framed at all.
+ */
+export function framingPrefix(type: string | null | undefined): string | null {
+    if (
+        type?.startsWith('application/jsonl') ||
+        type?.startsWith('application/x-ndjson')
+    )
+        return ''
+    if (type?.startsWith('text/event-stream')) return 'data: '
+    return null
+}
+
+/**
+ * Whether an answer at `type` is read as bytes rather than as JSON: anything neither JSON nor framed.
+ *
+ * 16.34 — A BINARY IS `application/octet-stream`, OR A `Blob`'s OWN TYPE, so the bytes are named by
+ * what an answer is not rather than by one type. An answer naming no type is read as JSON.
+ */
+export function carriesBytes(type: string | null | undefined): boolean {
+    if (type === null || type === undefined || type === '') return false
+    if (framingPrefix(type) !== null) return false
+    const semicolon = type.indexOf(';')
+    const essence = semicolon === -1 ? type : type.slice(0, semicolon)
+    return essence !== 'application/json' && !essence.endsWith('+json')
+}
+
+/**
+ * A streamed answer's chunks: each JSON value its framing carried, or, for bytes (16.46), each
+ * `Uint8Array` as it was read — bytes have no framing to split them back into the chunks the
+ * handler yielded.
+ */
+export function answerChunks(
+    body: ReadableStream<Uint8Array>,
+    type: string | null | undefined,
+): AsyncIterable<unknown> {
+    return carriesBytes(type)
+        ? bytesStream(body)
+        : framedStream(body, framingPrefix(type) ?? '')
+}
+
+/**
+ * A body's reads, yielded as they land.
+ *
+ * Through a reader rather than the stream's own async iterator, which not every browser ships.
+ */
+async function* bytesStream(
+    body: ReadableStream<Uint8Array>,
+): AsyncGenerator<Uint8Array> {
+    const reader = body.getReader()
+    try {
+        for (;;) {
+            const { done, value } = await reader.read()
+            if (done) return
+            yield value
+        }
+    } finally {
+        void reader.cancel().catch(() => {})
+    }
+}
+
+/** 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)
+    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
+ * nothing left to hand anything.
+ */
+export async function* framedStream(
+    body: ReadableStream<Uint8Array>,
+    prefix: string,
+): AsyncGenerator<unknown> {
+    const reader = body.getReader()
+    const decoder = new TextDecoder()
+    const chunks: unknown[] = []
+    let buffered = ''
+    try {
+        for (;;) {
+            const { done, value } = await reader.read()
+            const decoded = done
+                ? decoder.decode()
+                : decoder.decode(value, { stream: true })
+            // A long line across many reads is held unscanned until its newline lands, or each read
+            // rescans everything before it.
+            if (!done && !decoded.includes('\n')) {
+                buffered += decoded
+                continue
+            }
+            buffered = readLines(buffered + decoded, prefix, done, chunks)
+            yield* chunks
+            chunks.length = 0
+            if (done) return
+        }
+    } finally {
+        void reader.cancel().catch(() => {})
+    }
+}
+
+/**
+ * Parses each complete line of `text` into `chunks`, and the unfinished last one too where `ended`.
+ *
+ * Answers what is left of `text` after the last newline.
+ */
+function readLines(
+    text: string,
+    prefix: string,
+    ended: boolean,
+    chunks: unknown[],
+): 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 (newline === -1) return ''
+        start = newline + 1
+    }
+}

package/src/shared/headKeyOf.ts

@@ -0,0 +1,34 @@
+/**
+ * A head contribution's merge key, or `undefined` where it has none.
+ *
+ * 39.11 — ONE GRAMMAR, because two lanes decide by it and they have to agree about which
+ * contribution replaces which: the COMPILER keys a `<head>` child at build time to apply 39.12
+ * within a file, and the CLIENT keys the standing document head against an incoming page's on a
+ * navigation (39.6). A second spelling is a navigation appending a duplicate `<title>` where the
+ * server replaced one — silent, and visible only in a browser.
+ *
+ * THE TAG IS LOWERCASE and the attribute lookup is the caller's, which is the only thing the two
+ * lanes genuinely differ on: the compiler reads a static attribute off a template node, the client
+ * a resolved one off an element. The lookup answers in `getAttribute`'s terms — `null` is ABSENT —
+ * and `undefined` is PRESENT BUT UNKNOWN to this lane (an expression, at build time). The two are
+ * different answers: an absent `href` is part of a `<link>`'s key, and an unknown `name` outranks
+ * whatever `property` says, so either leaves the contribution with no key here.
+ */
+export function headKeyOf(
+    lowerTag: string,
+    attribute: (name: string) => string | null | undefined,
+): string | undefined {
+    if (lowerTag === 'title' || lowerTag === 'base') return lowerTag
+    if (lowerTag === 'meta') {
+        const named = attribute('name')
+        const key = named === null ? attribute('property') : named
+        return key == null ? undefined : `meta ${key}`
+    }
+    if (lowerTag !== 'link') return undefined
+    const rel = attribute('rel')
+    const href = attribute('href')
+    if (rel == null || href === undefined) return undefined
+    // An ABSENT `href` is part of the key rather than a hole in it — two `<link rel="canonical">`
+    // share one — so the trailing space stays whether or not there is an href to put after it.
+    return `link ${rel} ${href ?? ''}`
+}

package/src/shared/health.ts

@@ -0,0 +1,51 @@
+// SECTION 25 — THE ACCOUNT OF THE APP, on both sides, as an `Rpc` taking no args: the server reports
+// it (`#server/reportHealth.ts`, which `installServer` fills `HEALTH` with), and a browser loads it from `/__abide/health` —
+// the handler abide mounts there, seeded as any handler is (25.3).
+//
+// A PARAMETER NOTHING PASSES, so the value is keyed and the call is what runs it (16.4): a body
+// declaring none would run where it is built (1.7), and every page would load an account it never
+// asked for. The same one key `wire` reaches an unkeyed handler by.
+//
+// PURE, for `online`'s reason: an app that never names `health` does not ship it.
+
+import { HEALTH_ADDRESS } from './ADDRESSES.ts'
+import type { Failed } from './Failed.ts'
+import { declare, type Rpc } from './rpc.ts'
+import { seededDocument } from './seededDocument.ts'
+
+/** 25.4 — the account, which an app widens with what its `onHealth` adds, by declaration merging. */
+export interface Health {
+    version: string
+    abide: string
+    startedAt: string
+}
+
+/**
+ * The slot `health` reports through: a browser's fetch, which the server replaces.
+ *
+ * A refused fetch is returned, so `health` refuses as any handler's copy does (15.5); a seed the
+ * server painted settled is answered at once (41.27).
+ */
+export const HEALTH: {
+    report: () =>
+        | Health
+        | Failed<string, unknown>
+        | Promise<Health | Failed<string, unknown>>
+} = {
+    report: browserHealthReport,
+}
+
+/** A browser's `HEALTH.report`: the seeded answer to `/__abide/health`. */
+export function browserHealthReport():
+    | Health
+    | Failed<string, unknown>
+    | Promise<Health | Failed<string, unknown>> {
+    return seededDocument<Health>(HEALTH_ADDRESS)
+}
+
+/** The account of the app this call is in. */
+export const health: Rpc<Health, undefined> = /* @__PURE__ */ declare('GET')(
+    (_none: undefined) => HEALTH.report(),
+    // 20.1 — no generated surface: abide mounts it, not the app's tree.
+    { clients: { ui: false, mcp: false, cli: false, openapi: false } },
+) as Rpc<Health, undefined>