@abide/abide 0.58.0 → 0.101.0

package/src/ui/Scope.ts

@@ -0,0 +1,115 @@
+import {
+    type Disposer,
+    type Effect,
+    watchTracked,
+} from '#shared/reactive/watch.ts'
+
+/** What a scope built under a `{#try}` binds through — its `TryRegion` (32.16). */
+type Boundary = {
+    guard<T>(run: () => T, again: () => unknown): T | undefined
+}
+
+/** The boundary a scope built now falls under, or `undefined` outside every `{#try}` body. */
+export const BOUNDARY: { current: Boundary | undefined } = {
+    current: undefined,
+}
+
+/**
+ * Anything a scope can stop below itself.
+ *
+ * Another `Scope` — an arm's, a row's, an invoked component's — or a `{#for}`'s `List`, which stops
+ * every row it still holds. Structural rather than a base class: `List` is a record in another
+ * module and `stop` is all the two share.
+ */
+export type Stoppable = { stop(): void }
+
+/**
+ * The bindings a region opens, held so whatever replaces the region can stop them.
+ *
+ * Without it a swap or a removed row leaves the old readers alive: they wake on every write, write
+ * into nodes that are no longer in the document, and the page looks right while doing the work
+ * twice over.
+ *
+ * A RECORD RATHER THAN A CLOSURE PER ROW: one object with methods on its prototype, where closures
+ * cost an array and three allocations a row — the collector, the stop and the stop it handed back.
+ */
+export class Scope {
+    /**
+     * 12.4, 12.13 — a setup's watches land here as it opens them (`collectWatches`): the scope is
+     * made before the setup runs, so a watch has one owner from the moment it opens.
+     */
+    stops: Disposer[] = []
+    /**
+     * The scopes opened beneath this one, or `undefined` until one is.
+     *
+     * 12.4 and 12.13 — a region's own disposers are not all it owns: an arm, a row and an invoked
+     * component each open a scope of their own, and the thing that knows when those leave is the
+     * region holding their nodes. `undefined` until one is actually opened — most scopes hold only
+     * disposers, and a second array a row is the allocation this class exists not to spend.
+     */
+    children: Stoppable[] | undefined = undefined
+    /**
+     * The `{#try}` this scope was built under, or `undefined`.
+     *
+     * 32.16 — read once at construction.
+     */
+    boundary: Boundary | undefined = BOUNDARY.current
+
+    watch(effect: Effect): void {
+        const boundary = this.boundary
+        if (boundary === undefined) {
+            this.stops.push(watchTracked(effect))
+            return
+        }
+        // UNDER A BOUNDARY, a throw is the boundary's and the scopes a re-run builds are too, and a
+        // failed binding is retried by running it again.
+        this.stops.push(watchTracked(() => boundary.guard(effect, effect)))
+    }
+
+    /**
+     * Takes ownership of a child scope or list; answers the child it was handed.
+     *
+     * 12.4 — A `watch` REGISTERED INSIDE A COMPONENT IS OWNED BY THAT COMPONENT, and what can
+     * remove a component's nodes is the region that invoked it. The child is held rather than
+     * drained: a component that itself holds an arm or a list owns scopes of its own, and moving
+     * only its disposers out would leave those where nothing can reach them.
+     *
+     * `undefined` IS A STATIC CHILD — a component with nothing live returns nothing to own.
+     */
+    own<T extends Stoppable | undefined>(child: T): T {
+        if (child === undefined) return child
+        if (this.children === undefined) this.children = []
+        this.children.push(child)
+        return child
+    }
+
+    /**
+     * Stops every binding and child this scope holds, and clears them.
+     *
+     * CLEARED AS IT GOES, so stopping twice is stopping once: an arm's scope is stopped by its own
+     * swap and again by the region above it when that region leaves, and 12.1 gives a `Disposer`
+     * one run at teardown rather than one per path that reaches it. It is also what lets a block
+     * hold ONE scope for its whole life and refill it on every swap.
+     *
+     * `from` KEEPS THE SETUP'S: a mount that refused (41.10) stops what IT opened and rebuilds, and
+     * the setup ahead of it — whose watches are the first `from` stops — does not run again.
+     */
+    stop(from = 0): void {
+        const stops = this.stops
+        for (let index = from; index < stops.length; index += 1)
+            (stops[index] as Disposer)()
+        stops.length = from
+        const children = this.children
+        if (children === undefined) return
+        for (const child of children) child.stop()
+        children.length = 0
+    }
+}
+
+/**
+ * A shared scope with nothing in it; stopping it is a no-op.
+ *
+ * What a mount whose body binds nothing answers, and what a row holds until its mount returns —
+ * `stop` on it is a no-op, so any number of owners can hold it.
+ */
+export const EMPTY_SCOPE = new Scope()

package/src/ui/TryRegion.ts

@@ -0,0 +1,278 @@
+// 32.16 — A `{#try}`'s REGION AND ITS BOUNDARY, one record. Every scope built while the body mounts
+// carries it (`Scope`), so a binding anywhere in the body that throws is caught here rather than
+// escaping — and the whole body is replaced by the catch arm, not the one hole that raised it.
+//
+// WHAT FAILED IS RETRIED. What threw is kept watching what it read, and the first run that does not
+// throw is the body coming back: a rate typed wrong and then right shows the message and then the
+// figure, without anything else arranging that. A binding is retried by running it again; a body
+// that failed as it was built or mounted is retried by MOUNTING it again (`remount`), because only a
+// mount runs the components in it, and one that mounts is the body kept.
+//
+// What anything outside sees is `follow` (the region's watch), `guard` (a scope's binding under
+// it), `stop` and the `failure` the catch binds; the retry is this module's alone.
+
+import { namedArm } from '#shared/armAnchor.ts'
+import { type Reactive, reactive } from '#shared/reactive/index.ts'
+import { NotLanded } from '#shared/reactive/NotLanded.ts'
+import { untracked } from '#shared/reactive/tracking.ts'
+import { type Disposer, watchTracked } from '#shared/reactive/watch.ts'
+import { type Arm, type ArmMakers, ArmRegion } from './ArmRegion.ts'
+import { Mismatch } from './Mismatch.ts'
+import {
+    fillRegion,
+    isEmptyRegion,
+    type Region,
+    removeUntil,
+} from './regions.ts'
+import { BOUNDARY, type Scope, type Stoppable } from './Scope.ts'
+
+/**
+ * The body until something in it fails, then the catch until the failure clears. Arm `0` is the
+ * body and `1` the catch, which is handed the failure.
+ *
+ * THE BODY BUILDS AND MOUNTS UNDER THE BOUNDARY, the catch outside it — a catch arm that throws is
+ * not its own catch's to swallow. A failure raised while a swap builds the body does not wake the
+ * watch, so the swap reads the failure again and goes round: a body that failed as it was built is
+ * not mounted, and one that failed as it mounted is replaced.
+ *
+ * AND THE FIRST SWAP HYDRATES THE ARM THE SERVER PAINTED. The body it adopts; the catch — which its
+ * anchor names as arm 1 (`namedArm`) — it keeps until the body has been tried behind it
+ * (`mountBehind`), and adopts where the body fails here too, so the catch the server sent is the
+ * one on the page. A body that succeeds here after failing there replaces it. So 41.24 is already
+ * this region's shape — its open names the arm — and `paintedOther` is never asked here.
+ */
+export class TryRegion extends ArmRegion {
+    readonly failure: Reactive<unknown>
+    /** Only a mount runs the components in a body, so a failed body is retried by mounting it again. */
+    private readonly remount: () => void
+    private retry: Disposer | undefined
+    /** What the retry re-runs, recorded by `fail` and watched once the catch stands (`startRetry`). */
+    private pending: (() => unknown) | undefined
+    /** A body a retry mounted, for the swap to take in place of building one. */
+    private standing: Stoppable | undefined
+    /**
+     * Whether a mount is being tried behind what stands (`mountBehind`), so a binding failing in it
+     * is recorded for the try rather than failing the boundary.
+     */
+    private trying: boolean
+    private triedFailed: boolean
+    private triedError: unknown
+    private triedAgain: (() => unknown) | undefined
+
+    constructor(region: Region, owner: Scope, arms: ArmMakers) {
+        super(region, owner, arms, true)
+        this.failure = reactive<unknown>(undefined)
+        this.remount = () => {
+            this.standing = this.mountBehind(
+                (arms[0] as ArmMakers[number])(undefined),
+            )
+        }
+        this.retry = undefined
+        this.pending = undefined
+        this.standing = undefined
+        this.trying = false
+        this.triedFailed = false
+        this.triedError = undefined
+        this.triedAgain = undefined
+        owner.own(this)
+    }
+
+    /**
+     * The region's watch: only the failure decides which arm.
+     *
+     * 32.16, 41.10 — OVER A CATCH THE SERVER PAINTED, THE RETRY'S FIRST RUN IS THE HYDRATION: it
+     * mounts the body behind the catch (`remount`), so the one attempt both decides the arm and
+     * subscribes the retry to what the body read. A body that fails there sets the failure the catch
+     * binds, and the catch is adopted; one that mounts is left standing for the swap. A value still
+     * in flight decides neither, and the attempt is run again under this watch, whose run it aborts
+     * as it would anywhere (2.12) — so this watch is what the value landing wakes.
+     */
+    follow(): void {
+        if (this.at === undefined && namedArm(this.region.open.data) === 1) {
+            this.pending = this.remount
+            this.startRetry()
+            if (
+                this.failure.peek() === undefined &&
+                this.standing === undefined
+            ) {
+                this.stop()
+                this.remount()
+            }
+        }
+        this.show(this.failure() === undefined ? 0 : 1)
+    }
+
+    /**
+     * Runs a mount or a binding under this boundary; a throw fails it and answers `undefined`.
+     *
+     * Every scope it builds carries it, and a throw straight out of the mount — a handler or a node
+     * reference that failed as it was bound — is the boundary's too. A hydration mismatch is not a
+     * failure of the body, and is left to the caller that rebuilds; and a value still in flight is
+     * not a failure either: it aborts the run as it would anywhere (2.12).
+     *
+     * `again` IS WHAT A RETRY RE-RUNS: the binding that threw, or the body mounted again.
+     */
+    guard<T>(run: () => T, again: () => unknown): T | undefined {
+        const previous = BOUNDARY.current
+        BOUNDARY.current = this
+        try {
+            return run()
+        } catch (thrown) {
+            if (thrown instanceof Mismatch || thrown instanceof NotLanded)
+                throw thrown
+            this.fail(thrown, again)
+            return undefined
+        } finally {
+            BOUNDARY.current = previous
+        }
+    }
+
+    /** Stops the retry. The arm's scope is stopped by the owner holding it, beside this. */
+    stop(): void {
+        this.retry?.()
+        this.retry = undefined
+    }
+
+    override swap(first: unknown): void {
+        const region = this.region
+        const scope = this.scope as Scope
+        let next = first
+        while (next !== this.at) {
+            const painted = this.at === undefined && !isEmptyRegion(region)
+            this.at = next
+            const arm = (this.arms[next as number] as ArmMakers[number])(
+                this.failure.peek(),
+            )
+            const standing = next === 0 ? this.standing : undefined
+            if (standing !== undefined) {
+                this.standing = undefined
+                scope.stop()
+                scope.own(standing)
+                continue
+            }
+            if (!painted) {
+                scope.stop()
+                if (
+                    next === 0 &&
+                    this.guard(() => {
+                        fillRegion(region, arm.build)
+                        return true
+                    }, this.remount) === undefined
+                ) {
+                    next = 1
+                    continue
+                }
+                if (next === 1) fillRegion(region, arm.build)
+            }
+            scope.own(
+                next === 0
+                    ? this.guard(() => arm.mount(region), this.remount)
+                    : arm.mount(region),
+            )
+            if (next === 1) this.startRetry()
+            next = this.failure.peek() === undefined ? 0 : 1
+        }
+    }
+
+    private fail(error: unknown, again: () => unknown): void {
+        if (this.trying) {
+            if (this.triedFailed) return
+            this.triedFailed = true
+            this.triedError = error
+            this.triedAgain = again
+            return
+        }
+        this.stop()
+        this.pending = again
+        this.failure.set(error)
+    }
+
+    /**
+     * Watches what failed, once the catch stands.
+     *
+     * NOT FROM `fail`: a failure is raised in the middle of a swap, with the failed body still in the
+     * region, and a retry mounting a body there would be mounting it beside that one. Once the catch
+     * stands, a run that does not throw IS the body coming back, the first run included.
+     */
+    private startRetry(): void {
+        const again = this.pending
+        if (again === undefined) return
+        this.pending = undefined
+        const retry = watchTracked(() => {
+            try {
+                again()
+            } catch (thrown) {
+                if (thrown instanceof NotLanded) throw thrown
+                // A caught region's first run is the one that finds the failure (`follow`).
+                if (this.failure.peek() === undefined) this.failure.set(thrown)
+                return
+            }
+            untracked(TryRegion.recover, this, undefined)
+        })
+        // A first run that recovered has already been stopped by `recover`, before it was held.
+        if (this.failure.peek() === undefined) retry()
+        else this.retry = retry
+    }
+
+    /**
+     * Mounts the body BEHIND what the region holds, and keeps whichever stands after.
+     *
+     * 32.16, 41.10 — the client cannot know its body throws until the body has MOUNTED: an invoked
+     * component is an empty anchor pair to its parent's build (`emitBuild`) and runs its setup and
+     * its template at mount, so building the body is not evaluating it. So the body is built after
+     * the region's last node and mounted there, and what stood — the catch the server painted, or a
+     * catch the browser showed — stays until it has: a body that mounts drops it, and one that fails
+     * is dropped instead and its failure thrown. A throw in the build inserts nothing (`fillRegion`
+     * builds before it inserts).
+     *
+     * A BINDING THAT FAILS IN IT is run again here, where the caller's tracking sees what it read —
+     * a retry's watch — because the binding's own watch goes with the body it is dropped with.
+     */
+    private mountBehind(arm: Arm): Stoppable | undefined {
+        const region = this.region
+        // THE LAST NODE STANDING IS THE BODY'S OPEN ANCHOR, whatever kind of node it is: a build
+        // and a mount read nothing of their root's open but its `nextSibling`. The region's own open
+        // where nothing stands.
+        const body = {
+            open: region.close.previousSibling as Comment,
+            close: region.close,
+        }
+        const previous = BOUNDARY.current
+        BOUNDARY.current = this
+        this.trying = true
+        this.triedFailed = false
+        let mounted: Stoppable | undefined
+        try {
+            fillRegion(body, arm.build)
+            mounted = arm.mount(body)
+        } catch (thrown) {
+            fillRegion(body)
+            if (thrown instanceof Mismatch || thrown instanceof NotLanded)
+                throw thrown
+            this.triedFailed = true
+            this.triedError = thrown
+            this.triedAgain = undefined
+        } finally {
+            BOUNDARY.current = previous
+            this.trying = false
+        }
+        if (!this.triedFailed) {
+            removeUntil(region.open.nextSibling, body.open.nextSibling)
+            return mounted
+        }
+        const again = this.triedAgain
+        this.triedAgain = undefined
+        if (again !== undefined)
+            try {
+                again()
+            } catch {}
+        mounted?.stop()
+        fillRegion(body)
+        throw this.triedError
+    }
+
+    private static recover(region: TryRegion): void {
+        region.stop()
+        region.failure.set(undefined)
+    }
+}

package/src/ui/adoptWalk.ts

@@ -0,0 +1,126 @@
+import { RAW_CLOSE, RAW_OPEN } from '#shared/ANCHORS.ts'
+import { Mismatch } from './Mismatch.ts'
+import { type RawRun, rawCloseOf, rawRunEndingAt } from './RawRun.ts'
+import { closeOf, opensRegion, type Region } from './regions.ts'
+
+// WHERE A NODE IS WHEN THE SERVER ALREADY WROTE IT — the adopt half of every region's mount: the
+// page, an arm, a slot, a caller's children and every row. The compiler emits it from the walk that
+// wrote the markup (`Cursor`) — the same positions a row's build is made from — so where a node
+// stands is never computed twice.
+//
+// THE GUARANTEE IS ABOUT PROVENANCE, NOT ABOUT RUNTIME SHAPE. A painter object reached the same
+// end through runtime polymorphism and charged 1.5x a row for it (`bun run bench:reorder`, against
+// inline construction) — a 2-shape property load per node, forever, for something a compiler can
+// settle at build time.
+//
+// TWO KINDS OF HELPER. `runHere` and `regionHere` are STEPS the walk takes and never throw: on
+// a page the walk stands outside every guard, so a node missing near the top must not take every
+// binding below it down too. `elementHere`, `textHere` and `regionFound` are CHECKS a unit makes
+// on the node it was handed, and they are where 41.10 refuses.
+//
+// SO THESE ARE HELPERS AND NOT AN INTERFACE. One shape each, no `this`, nothing to dispatch on —
+// small enough for an engine to inline, where a method on one of two painter classes is not.
+//
+// AND THE CHECKS ARE WHAT KEEP A DISAGREEMENT LOCAL. The walk steps past a node of the wrong KIND
+// by position, as a path did, so only the unit that needed it is refused (41.10). A node MISSING
+// or EXTRA shifts everything after it in that parent — for a walk and for a path alike — and the
+// kind check catches the shift wherever it lands on a different kind. What no check can see is a
+// text node standing where a different text node was due, and that is what the equivalence gates
+// (`nesting.test.ts`, `corpusRuns.test.ts`) are for.
+
+/** The node the walk stands on, checked to be a `<tag>` element; throws `Mismatch` otherwise. */
+export function elementHere(
+    node: Node | null | undefined,
+    tag: string,
+): Element {
+    if (
+        node == null ||
+        node.nodeType !== 1 ||
+        (node as Element).localName !== tag
+    )
+        throw new Mismatch(
+            `abide: expected <${tag}> where the client walked, so the client and the server disagree about this region's shape (41.10).`,
+        )
+    return node as Element
+}
+
+/**
+ * A run, checked: its text node, or the `RawRun` around it where it holds markup.
+ *
+ * Where the run holds markup (32.26) the pair is read back from the closing anchor the walk stood
+ * on (`runHere`). A run the server rendered as no node was put back by the walk as it passed, so by
+ * the time a binding asks something is there — and where the walk could not put one back, this is
+ * what refuses.
+ */
+export function textHere(node: Node | null | undefined): Text | RawRun {
+    if (node != null) {
+        if (node.nodeType === 3) return node as Text
+        if (node.nodeType === 8 && (node as Comment).data === RAW_CLOSE) {
+            const run = rawRunEndingAt(node as Comment)
+            if (run !== null) return run
+        }
+    }
+    throw new Mismatch(
+        "abide: text was due where the server wrote none, so the client and the server disagree about this region's shape (41.10).",
+    )
+}
+
+/**
+ * Where a run that can hold markup ends; a step that never throws.
+ *
+ * A STEP, for the reason every step is one. A run the server wrote as text is its one node; a run
+ * it wrote holding markup (32.26) is an anchor pair with any number of nodes between, and the walk
+ * stands on the CLOSE, so the position after it is found by `nextSibling` either way and nothing
+ * about the cursor changes.
+ *
+ * AND 32.23'S HOLE, where `parent` is given: a BLANK run — every part an expression, each unlanded
+ * (32.23 leaves what it last rendered, which is nothing yet) or stringifying to '' — is written by
+ * the server as no node, and still has to be a position, because every sibling after it is found from it — so the walk puts it back as it
+ * passes, whether or not anything binds it. A run that is not blank passes no parent and is never
+ * put back. `textHere` is the CHECK a binding makes; this is the step a walk takes, and on a page
+ * the walk is outside every guard, so a throw here would take down every unit after it rather than
+ * the one that disagreed.
+ *
+ * A node put back at the TOP of a row needs nothing more: a row with several top-level nodes is the
+ * RANGE from its anchor to the next (`rows.ts`), and the node is put back inside it.
+ */
+export function runHere(
+    node: Node | null | undefined,
+    parent: Node | null | undefined,
+): Node | null | undefined {
+    if (node != null) {
+        if (node.nodeType === 3) return node
+        if (node.nodeType === 8 && (node as Comment).data === RAW_OPEN)
+            return rawCloseOf(node) ?? node
+    }
+    if (parent == null) return node
+    const made = (parent.ownerDocument as Document).createTextNode('')
+    parent.insertBefore(made, node ?? null)
+    return made
+}
+
+/**
+ * The region whose anchor pair the walk stands on, or `undefined`; a step that never throws.
+ *
+ * Taken where the walk stands rather than counted to from a root, and never throwing for
+ * `runHere`'s reason: the walk continues from the pair's CLOSE, so a region the server did not
+ * write here answers `undefined` and the walk carries on as far as it can. What refuses is
+ * `regionFound`, in the unit that needed the region.
+ *
+ * The close is the one at DEPTH ZERO: a region nested inside this one has anchors of its own.
+ */
+export function regionHere(node: Node | null | undefined): Region | undefined {
+    if (node == null || node.nodeType !== 8) return undefined
+    if (!opensRegion((node as Comment).data)) return undefined
+    const close = closeOf(node)
+    return close === null ? undefined : { open: node as Comment, close }
+}
+
+/** The region a step found, checked to be there; throws `Mismatch` where it is not. */
+export function regionFound(region: Region | undefined): Region {
+    if (region === undefined)
+        throw new Mismatch(
+            "abide: a region was due where the client walked, so the client and the server disagree about this region's shape (41.10).",
+        )
+    return region
+}

package/src/ui/applyHead.ts

@@ -0,0 +1,146 @@
+// 39.6 — ON A CLIENT NAVIGATION THE INCOMING PAGE'S KEYED CONTRIBUTIONS REPLACE THE OUTGOING
+// PAGE'S BY KEY. The outgoing page's were written by a server on the first load and by this
+// function on every one after, so they are found the same way either time: by their key, read off
+// the document. Nothing is added to the head to mark ownership — a marker would be a fact about
+// the framework in a document an author writes, and the key is already what decides.
+//
+// 39.5 — A CONTRIBUTION WITH NO KEY APPENDS. It cannot replace anything, because there is nothing
+// it could be said to be the same as, and dropping it instead would lose the one kind of
+// contribution a page makes several of.
+
+import { headKeyOf } from '#shared/headKeyOf.ts'
+import { markupNodes } from './parseMarkup.ts'
+import type { Scope } from './Scope.ts'
+
+export function applyHead(markup: string): void {
+    const head = document.head
+    if (markup === '') return
+    const incoming = markupNodes(head, markup)
+    const standingByKey = standingKeys(head)
+    for (const node of incoming) {
+        if (node.nodeType !== 1) {
+            head.appendChild(node)
+            continue
+        }
+        const element = node as Element
+        const key = headKey(element)
+        if (key === undefined) {
+            head.appendChild(element)
+            continue
+        }
+        const standing = standingByKey.get(key)
+        if (standing === undefined) {
+            head.appendChild(element)
+            standingByKey.set(key, element)
+            continue
+        }
+        // WHAT THE TWO PAGES SHARE IS NOT TOUCHED. `hydrate` skips `applyHead` outright because
+        // re-applying a `<link rel=stylesheet>` refetches it and flashes the document unstyled —
+        // and a navigation between two pages carrying the same stylesheet, viewport or icon walks
+        // into that same cost per contribution. An identical node is the one case where the
+        // cheaper arm is to do nothing at all.
+        if (standing.outerHTML === element.outerHTML) continue
+        head.replaceChild(element, standing)
+        standingByKey.set(key, element)
+    }
+}
+
+/**
+ * Puts back, or removes, what the leaving levels keyed and the arriving ones do not.
+ *
+ * 39.14 — THE NEXT-OUTER CONTRIBUTOR'S VALUE, OR NONE. `leaving` and `arriving` are the heads of
+ * the levels a navigation stopped and mounted; `outer` is every contributor standing above them,
+ * outermost first — the shell's keyed entries, then each kept layout's — so the LAST entry for a
+ * key in it is the one the server would paint there (39.4). What the arriving levels key they have
+ * already written (39.6), so only the keys they are silent on are touched.
+ *
+ * THE COMMON NAVIGATION ENDS AT THE FIRST RETURN: two pages that both key a `<title>` withdraw
+ * nothing, and `outer` is neither built nor parsed.
+ */
+export function withdrawHead(
+    leaving: string,
+    arriving: string,
+    outer: () => string,
+): void {
+    if (leaving === '') return
+    const head = document.head
+    const withdrawn = keyedIn(head, leaving)
+    for (const key of keyedIn(head, arriving).keys()) withdrawn.delete(key)
+    if (withdrawn.size === 0) return
+    const restored = keyedIn(head, outer())
+    const standingByKey = standingKeys(head)
+    for (const key of withdrawn.keys()) {
+        const standing = standingByKey.get(key)
+        const next = restored.get(key)
+        if (next === undefined) standing?.remove()
+        else if (standing === undefined) head.appendChild(next)
+        // The same node as `applyHead`'s: a stylesheet put back as itself is not refetched.
+        else if (standing.outerHTML !== next.outerHTML)
+            head.replaceChild(next, standing)
+    }
+}
+
+/** The keyed elements `markup` parses to, by key, the last holding each (39.4). */
+function keyedIn(head: HTMLHeadElement, markup: string): Map<string, Element> {
+    const keyed = new Map<string, Element>()
+    if (markup === '') return keyed
+    for (const node of markupNodes(head, markup))
+        if (node.nodeType === 1) {
+            const key = headKey(node as Element)
+            if (key !== undefined) keyed.set(key, node as Element)
+        }
+    return keyed
+}
+
+/**
+ * The head's keyed elements by key, the first holding each.
+ *
+ * KEYED ONCE, NOT ONCE PER CONTRIBUTION. Walking the head per incoming node asked `headKey` — a
+ * `toLowerCase` and a fresh closure per call — for every standing element times every arriving
+ * one. One pass builds the index and each contribution is then a lookup.
+ */
+function standingKeys(head: HTMLHeadElement): Map<string, Element> {
+    const standingByKey = new Map<string, Element>()
+    for (
+        let node = head.firstElementChild;
+        node !== null;
+        node = node.nextElementSibling
+    ) {
+        const key = headKey(node)
+        // 39.12 WITHIN THE STANDING HEAD: the FIRST element holding a key is the one a
+        // contribution replaces, which is the node the per-contribution walk returned.
+        if (key !== undefined && !standingByKey.has(key))
+            standingByKey.set(key, node)
+    }
+    return standingByKey
+}
+
+/**
+ * The key a head element replaces by, or `undefined` for one that appends.
+ *
+ * 39.11 THROUGH THE ONE GRAMMAR (`headKeyOf`), asked with a RESOLVED attribute. The compiler
+ * answers the same question for a STATIC one and appends where it cannot (`<meta name={x}>` has a
+ * name only the run time knows) — here every attribute is resolved, so a contribution the compiler
+ * had to append arrives with a key. That is the same rule reaching further, not a different one.
+ */
+function headKey(element: Element): string | undefined {
+    return headKeyOf(element.tagName.toLowerCase(), (name) =>
+        element.getAttribute(name),
+    )
+}
+
+/**
+ * Keeps a level's head written from `markup` for as long as `scope` lives.
+ *
+ * 39.13 — A HEAD THAT READS A VALUE FOLLOWS IT for as long as its level is mounted, which is the
+ * scope's life. The first run only subscribes: the head it would write is already there, written
+ * by the server or applied by the level's mount ahead of its fill (39.6).
+ */
+export function liveHead(scope: Scope, markup: () => string): void {
+    let subscribing = true
+    scope.watch(() => {
+        const text = markup()
+        if (subscribing) subscribing = false
+        else applyHead(text)
+    })
+}