@abide/abide 0.28.0

package/src/lib/ui/dom/eachAsync.ts

@@ -0,0 +1,153 @@
+import { effect } from '../effect.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { OWNER } from '../runtime/OWNER.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+import type { EachRow } from './types/EachRow.ts'
+
+/*
+Async keyed list — the runtime for `<template each await key=>`. Like `each`, but
+over an AsyncIterable: rows append and reconcile by key as the iterator yields, so
+a live stream (an `async function*` rpc, a socket feed) lands row by row. Keying by
+identity lets a re-yielded key reuse its node and inner effects rather than append a
+duplicate.
+
+SSR renders no rows — async sources are client-time (an infinite stream would hang
+SSR) — so hydration just parks the anchor before the next sibling (like an empty
+sync each) and the client drains the iterable. A reactive re-run (a cache
+invalidate, or the iterable expression changing) bumps the generation so a prior
+in-flight drain stops appending; departed keys are pruned once a drain completes
+(an infinite stream never prunes — rows accumulate / update in place).
+
+On a mid-stream rejection the already-streamed rows stay and the `<template catch>`
+branch (`renderCatch`) renders after them; absent a catch branch the rejection
+surfaces (re-throws) instead of being swallowed (mirrors `<template await>`).
+*/
+// @readme plumbing
+export function eachAsync<T>(
+    parent: Node,
+    items: () => AsyncIterable<T>,
+    keyOf: (item: T) => string,
+    render: (parent: Node, item: T) => Node,
+    /* Absent → an iterator rejection surfaces instead of rendering a catch branch. */
+    renderCatch: ((parent: Node, error: unknown) => Node[]) | undefined,
+): void {
+    const rows = new Map<string, EachRow>()
+
+    /* Build one row in its own scope so its bindings dispose when it leaves. Rows are
+       always created (never on the server), so this runs after hydration has ended. */
+    const buildRow = (item: T): EachRow => {
+        let node: Node | undefined
+        const dispose = scope(() => {
+            node = render(parent, item)
+        })
+        return { node: node as Node, dispose }
+    }
+
+    const hydration = RENDER.hydration
+    const anchor = document.createTextNode('')
+    if (hydration !== undefined) {
+        parent.insertBefore(anchor, claimChild(hydration, parent)) // no server rows to claim
+    } else {
+        parent.appendChild(anchor)
+    }
+
+    /* The mounted `<template catch>` range, disposed when a fresh run re-streams. */
+    let errorRange: { nodes: Node[]; dispose: () => void } | undefined
+    const clearError = (): void => {
+        if (errorRange !== undefined) {
+            errorRange.dispose()
+            for (const node of errorRange.nodes) {
+                parent.removeChild(node)
+            }
+            errorRange = undefined
+        }
+    }
+
+    /* Bumped each run so a superseded drain stops appending and pruning. */
+    let generation = 0
+    /* The live iterator, held so a re-run or teardown can `return()` it — closing
+       the source (a generator's `finally`, a socket) and resolving any pending
+       `next()`. Bumping `generation` alone can't reach a drain parked on `await
+       iterator.next()`: an idle infinite stream never yields again, so the loop
+       never re-checks `generation` — it dangles on the microtask queue forever. */
+    let iterator: AsyncIterator<T> | undefined
+    effect(() => {
+        generation += 1
+        const generationAtStart = generation
+        iterator?.return?.() // close the superseded run's iterator before re-streaming
+        iterator = undefined
+        clearError() // a fresh run drops a prior error branch
+        const iterable = items() // read (subscribe) synchronously
+        const present = new Set<string>()
+        const drain = async (): Promise<void> => {
+            const active = iterable[Symbol.asyncIterator]()
+            iterator = active
+            while (true) {
+                const result = await active.next()
+                /* A re-run or teardown bumped the generation while we awaited. */
+                if (generationAtStart !== generation) {
+                    return
+                }
+                if (result.done === true) {
+                    break
+                }
+                const key = keyOf(result.value)
+                present.add(key)
+                /* A re-yielded key rebuilds the row from the new value, swapping the old
+                   node out (v1 has no in-place field patch — rows bind plain snapshots). */
+                const stale = rows.get(key)
+                const row = buildRow(result.value)
+                rows.set(key, row)
+                if (stale !== undefined) {
+                    stale.dispose()
+                    parent.removeChild(stale.node)
+                }
+                parent.insertBefore(row.node, anchor) // arrival order, before the anchor
+            }
+            for (const [key, row] of rows) {
+                if (!present.has(key)) {
+                    row.dispose()
+                    parent.removeChild(row.node)
+                    rows.delete(key)
+                }
+            }
+        }
+        drain().catch((error: unknown) => {
+            if (generationAtStart !== generation) {
+                return
+            }
+            /* No catch branch → surface the rejection (mirrors `<template await>`). */
+            if (renderCatch === undefined) {
+                throw error
+            }
+            /* Keep the streamed rows; render the catch branch after them, at the anchor. */
+            let nodes: Node[] = []
+            const dispose = scope(() => {
+                nodes = renderCatch(parent, error)
+            })
+            for (const node of nodes) {
+                parent.insertBefore(node, anchor)
+            }
+            errorRange = { nodes, dispose }
+        })
+    })
+
+    /* Stop the live stream when the enclosing scope tears down. The effect's own
+       disposer only unsubscribes from `items()` — it leaves the running `drain()`
+       pulling rows into a now-detached parent forever. Bump the generation so the
+       drain abandons its loop, `return()` the iterator to release the source and any
+       pending `next()`, drop the error branch, and dispose every surviving row. */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => {
+            generation += 1
+            iterator?.return?.()
+            iterator = undefined
+            clearError()
+            for (const row of rows.values()) {
+                row.dispose()
+            }
+            rows.clear()
+        })
+    }
+}

package/src/lib/ui/dom/hydrate.ts

@@ -0,0 +1,35 @@
+import { enterRenderPass } from '../runtime/enterRenderPass.ts'
+import { exitRenderPass } from '../runtime/exitRenderPass.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+
+/*
+Adopts existing server-rendered DOM instead of rebuilding it. Runs `build(host)`
+with a claim cursor active, so the dom helpers (openChild/appendText/appendStatic)
+take the existing nodes rather than creating new ones — attaching event listeners
+and reactive effects to the server's markup in place (no re-render, preserved
+focus/scroll). Returns a disposer.
+
+Adopts the server DOM in place across the framework: static structure (elements
++ text + bindings), `if`/`else`, keyed `each`, `switch`, and child components
+(with slots) — they hydrate automatically because the wrapper is claimed while
+hydration is still active. The only block not yet adopted is `await` (it
+interacts with the streamed stream-swap); a component using `await` should `mount`.
+*/
+// @readme plumbing
+export function hydrate(host: Element, build: (host: Element) => void): () => void {
+    const previous = RENDER.hydration
+    RENDER.hydration = { next: new Map() }
+    enterRenderPass()
+    try {
+        return scope(() => {
+            try {
+                build(host)
+            } finally {
+                exitRenderPass()
+            }
+        })
+    } finally {
+        RENDER.hydration = previous
+    }
+}

package/src/lib/ui/dom/mount.ts

@@ -0,0 +1,29 @@
+import { enterRenderPass } from '../runtime/enterRenderPass.ts'
+import { exitRenderPass } from '../runtime/exitRenderPass.ts'
+import { scope } from '../runtime/scope.ts'
+
+/*
+Mounts a component into `host`: runs `build(host)` under an ownership scope so
+every binding it creates is collected, and returns a disposer that stops all
+reactivity and clears the host. `build` appends its nodes to `host` (via the dom
+bindings below). This is the runtime entry the compiler's component output calls.
+
+Brackets a render pass so the outermost mount resets the block-id counter and an
+inlined child component's mount continues it — keeping await/try ids aligned with
+the SSR stream (see `enterRenderPass`).
+*/
+// @readme plumbing
+export function mount(host: Element, build: (host: Element) => void): () => void {
+    enterRenderPass()
+    const stop = scope(() => {
+        try {
+            build(host)
+        } finally {
+            exitRenderPass()
+        }
+    })
+    return () => {
+        stop()
+        host.textContent = ''
+    }
+}

package/src/lib/ui/dom/mountChild.ts

@@ -0,0 +1,33 @@
+import { hotReloadEnabled } from '../runtime/hotReloadEnabled.ts'
+import { OWNER } from '../runtime/OWNER.ts'
+import { registerHotInstance } from '../runtime/registerHotInstance.ts'
+import type { UiComponent } from '../runtime/types/UiComponent.ts'
+
+/*
+Mounts a child component into its wrapper host. Plain path (production, and dev
+without the hot bridge): run the factory — exactly the bare call the compiler used
+to emit. Hot path (hotReloadEnabled and the factory carries a module id): keep the
+mount disposer and record the instance so an edit can dispose + re-run it in place,
+and file a cleanup with the mounting owner so the record and its scope leave
+together when the parent (or branch/row) tears down. The factory already mounts
+under its own scope (see `mount`), so the recorded disposer tears down just this
+instance.
+*/
+// @readme plumbing
+export function mountChild(
+    host: Element,
+    factory: UiComponent,
+    props: Parameters<UiComponent>[1],
+): void {
+    const moduleId = factory.__abideId
+    if (!hotReloadEnabled.current || moduleId === undefined) {
+        factory(host, props)
+        return
+    }
+    const instance = { host, factory, props, dispose: factory(host, props) }
+    const remove = registerHotInstance(moduleId, instance)
+    OWNER.current?.push(() => {
+        instance.dispose()
+        remove()
+    })
+}

package/src/lib/ui/dom/on.ts

@@ -0,0 +1,15 @@
+import { OWNER } from '../runtime/OWNER.ts'
+
+/*
+Attaches an event listener and registers its removal with the current ownership
+scope, so a component's listeners detach when it disposes. This is the runtime
+target for an `onclick={…}` binding; the handler body is where the compiler's
+lowered patches (`model.replace(...)`) run.
+*/
+// @readme plumbing
+export function on(element: Element, type: string, handler: EventListener): void {
+    element.addEventListener(type, handler)
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => element.removeEventListener(type, handler))
+    }
+}

package/src/lib/ui/dom/openChild.ts

@@ -0,0 +1,22 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+
+/*
+Opens a child element of `parent`: creates and appends it (create mode), or claims
+the existing server-rendered node at the parent's current build position (hydrate
+mode), advancing the claim pointer. Returns the element so bindings and children
+attach to it. The compiler emits this for every element so the same build code
+serves both modes.
+*/
+// @readme plumbing
+export function openChild(parent: Node, tag: string): Element {
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        const current = claimChild(hydration, parent)
+        hydration.next.set(parent, current === null ? null : current.nextSibling)
+        return current as unknown as Element
+    }
+    const element = document.createElement(tag)
+    parent.appendChild(element)
+    return element
+}

package/src/lib/ui/dom/openRoot.ts

@@ -0,0 +1,20 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+
+/*
+Opens the root element of a control-flow branch/row, which the block inserts
+itself. In create mode it returns a detached element (the block does the
+insert); in hydrate mode it claims the existing server-rendered root from the
+parent's claim pointer (in place — the block adopts it). The compiler emits this
+for `each`/`if`/`switch`/`await` branch roots so adoption and creation share code.
+*/
+// @readme plumbing
+export function openRoot(parent: Node, tag: string): Element {
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        const current = claimChild(hydration, parent)
+        hydration.next.set(parent, current === null ? null : current.nextSibling)
+        return current as unknown as Element
+    }
+    return document.createElement(tag)
+}

package/src/lib/ui/dom/switchBlock.ts

@@ -0,0 +1,75 @@
+import { effect } from '../effect.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+import type { SwitchCase } from './types/SwitchCase.ts'
+
+/*
+Multi-branch binding — the runtime for `<template switch>`. An effect evaluates
+the subject, picks the first case whose `match` equals it (strict `===`), falling
+back to the default (`match` undefined); the chosen branch renders in its own
+scope, anchored for placement. A branch is a RANGE of element roots, tracked as a
+node array so a multi-root case inserts/removes as a unit. Staying on the same
+branch across a subject change leaves it mounted; switching disposes the old.
+
+On hydrate it adopts the case the server rendered (in place) and anchors after it;
+the effect's first run picks the same case and is a no-op, later changes swap fresh.
+*/
+// @readme plumbing
+export function switchBlock(parent: Node, subject: () => unknown, cases: SwitchCase[]): void {
+    const hydration = RENDER.hydration
+    let active: { nodes: Node[]; dispose: () => void } | undefined
+    let activeIndex = -1
+    let anchor: Node
+
+    const build = (chosen: SwitchCase): { nodes: Node[]; dispose: () => void } => {
+        let nodes: Node[] = []
+        const dispose = scope(() => {
+            nodes = chosen.render(parent)
+        })
+        return { nodes, dispose }
+    }
+
+    const select = (value: unknown): number => {
+        const matched = cases.findIndex(
+            (entry) => entry.match !== undefined && entry.match() === value,
+        )
+        return matched === -1 ? cases.findIndex((entry) => entry.match === undefined) : matched
+    }
+
+    if (hydration !== undefined) {
+        activeIndex = select(subject())
+        const chosen = activeIndex === -1 ? undefined : cases[activeIndex]
+        if (chosen !== undefined) {
+            active = build(chosen)
+        }
+        anchor = document.createTextNode('')
+        parent.insertBefore(anchor, claimChild(hydration, parent))
+    } else {
+        anchor = document.createTextNode('')
+        parent.appendChild(anchor)
+    }
+
+    effect(() => {
+        const index = select(subject())
+        if (index === activeIndex) {
+            return
+        }
+        if (active !== undefined) {
+            active.dispose()
+            for (const node of active.nodes) {
+                parent.removeChild(node)
+            }
+            active = undefined
+        }
+        activeIndex = index
+        const chosen = index === -1 ? undefined : cases[index]
+        if (chosen === undefined) {
+            return
+        }
+        active = build(chosen)
+        for (const node of active.nodes) {
+            parent.insertBefore(node, anchor)
+        }
+    })
+}

package/src/lib/ui/dom/text.ts

@@ -0,0 +1,20 @@
+import { effect } from '../effect.ts'
+
+/*
+A text node whose content tracks `read()`. The effect captures whatever reactive
+cells `read` touches, so the node — and only this node — re-renders when they
+change: one text node, one effect — fine-grained granularity.
+
+Plain-text only — `read()` is coerced with String(). For a `{expr}` interpolation
+that may yield an `html\`…\`` or snippet value the compiler emits `appendText`,
+which branches on the branded value and inserts raw markup; `text` cannot host
+multiple nodes and would stringify such a value to `[object Object]`.
+*/
+// @readme plumbing
+export function text(read: () => unknown): Text {
+    const node = document.createTextNode('')
+    effect(() => {
+        node.data = String(read())
+    })
+    return node
+}

package/src/lib/ui/dom/tryBlock.ts

@@ -0,0 +1,112 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { OWNER } from '../runtime/OWNER.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+
+/*
+Synchronous error boundary — the runtime for `<template try>`. Builds the guarded
+subtree (`renderTry`); if building it throws — including a throw from an initial
+reactive read, since effects run during build — it tears down the partial scope
+and builds `renderCatch(error)` instead. Both branches are a range of element
+roots tracked together. No `renderCatch` (no `<template catch>`) re-throws, so the
+error propagates to the nearest enclosing boundary (or the server 500 / stream).
+
+Catches throws during the BUILD of the subtree (mount, hydrate adoption, and the
+initial reactive reads). A throw in a later effect re-run is outside this lexical
+build and is not caught here.
+
+On hydrate it claims the SSR boundary (`<!--abide:try:N-->…<!--/abide:try:N-->`):
+the happy path adopts the guarded nodes in place; a throw discards the boundary's
+server nodes and builds the catch fresh.
+*/
+// @readme plumbing
+export function tryBlock(
+    parent: Node,
+    id: number,
+    renderTry: (parent: Node) => Node[],
+    renderCatch?: (parent: Node, error: unknown) => Node[],
+): void {
+    /* Run a build under a fresh ownership scope; on throw, tear down the partial
+       effects/listeners it registered and rethrow so the caller can fall back. */
+    const buildScoped = (build: () => Node[]): Node[] => {
+        const previous = OWNER.current
+        const disposers: Array<() => void> = []
+        OWNER.current = disposers
+        try {
+            const nodes = build()
+            OWNER.current = previous
+            return nodes
+        } catch (error) {
+            OWNER.current = previous
+            for (let index = disposers.length - 1; index >= 0; index -= 1) {
+                disposers[index]?.()
+            }
+            throw error
+        }
+    }
+
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        const open = claimChild(hydration, parent)
+        hydration.next.set(parent, open?.nextSibling ?? null) // advance past the open marker
+        try {
+            buildScoped(() => renderTry(parent)) // claims the guarded nodes in place
+            const close = claimChild(hydration, parent) // claim the close marker
+            hydration.next.set(parent, close?.nextSibling ?? null)
+        } catch (error) {
+            /* The server rendered (or partially built) something that didn't adopt —
+               drop the whole boundary and build the catch fresh in its place. */
+            const after = discardBoundary(parent, open, `/abide:try:${id}`, hydration)
+            if (renderCatch === undefined) {
+                throw error
+            }
+            const previous = RENDER.hydration
+            RENDER.hydration = undefined
+            try {
+                for (const node of buildScoped(() => renderCatch(parent, error))) {
+                    parent.insertBefore(node, after)
+                }
+            } finally {
+                RENDER.hydration = previous
+            }
+        }
+        return
+    }
+
+    let nodes: Node[]
+    try {
+        nodes = buildScoped(() => renderTry(parent))
+    } catch (error) {
+        if (renderCatch === undefined) {
+            throw error
+        }
+        nodes = buildScoped(() => renderCatch(parent, error))
+    }
+    for (const node of nodes) {
+        parent.appendChild(node)
+    }
+}
+
+/* Remove the SSR boundary — open marker through close marker (inclusive) — and
+   park the hydration cursor on the node after it, returning that node so a fresh
+   catch can be inserted in the boundary's place. */
+function discardBoundary(
+    parent: Node,
+    open: Node | null,
+    closeData: string,
+    hydration: NonNullable<(typeof RENDER)['hydration']>,
+): Node | null {
+    let node = open
+    let after: Node | null = null
+    while (node !== null) {
+        const next = node.nextSibling
+        const isClose = (node as { data?: string }).data === closeData
+        parent.removeChild(node)
+        if (isClose) {
+            after = next
+            break
+        }
+        node = next
+    }
+    hydration.next.set(parent, after)
+    return after
+}

package/src/lib/ui/dom/types/EachRow.ts

@@ -0,0 +1,3 @@
+/* A live row in a keyed list: its top node (for placement/removal) and the
+   disposer for the bindings created in its ownership scope. */
+export type EachRow = { node: Node; dispose: () => void }

package/src/lib/ui/dom/types/SwitchCase.ts

@@ -0,0 +1,6 @@
+/* One branch of a `switch`: `match` returns the value this case selects on
+   (undefined = the default branch); `render` builds the branch's element roots. */
+export type SwitchCase = {
+    match: (() => unknown) | undefined
+    render: (parent: Node) => Node[]
+}

package/src/lib/ui/dom/when.ts

@@ -0,0 +1,73 @@
+import { effect } from '../effect.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+
+/*
+Conditional binding — the runtime for `<template if>` (with optional `else`). An
+effect tracks `condition()` and mounts the matching branch (`render` truthy,
+`renderElse` falsy), anchored for placement; only a truthy↔falsy flip swaps. A
+branch is a RANGE of element roots (one or more), tracked as a node array so a
+multi-root branch inserts/removes as a unit.
+
+On hydrate it adopts the branch the server rendered: it runs the matching render
+in place (its roots claim the existing nodes), then inserts an anchor after them
+for future toggles. The effect's first run sees the same branch and is a no-op;
+later toggles (after hydration ends) build fresh.
+*/
+// @readme plumbing
+export function when(
+    parent: Node,
+    condition: () => unknown,
+    render: (parent: Node) => Node[],
+    renderElse?: (parent: Node) => Node[],
+): void {
+    const hydration = RENDER.hydration
+    let active: { nodes: Node[]; dispose: () => void } | undefined
+    let activeBranch: 'then' | 'else' | undefined
+    let anchor: Node
+
+    const build = (chosen: (parent: Node) => Node[]): { nodes: Node[]; dispose: () => void } => {
+        let nodes: Node[] = []
+        const dispose = scope(() => {
+            nodes = chosen(parent)
+        })
+        return { nodes, dispose }
+    }
+
+    if (hydration !== undefined) {
+        activeBranch = condition() ? 'then' : 'else'
+        const chosen = activeBranch === 'then' ? render : renderElse
+        if (chosen !== undefined) {
+            active = build(chosen) // roots claim the SSR nodes in place
+        }
+        anchor = document.createTextNode('')
+        parent.insertBefore(anchor, claimChild(hydration, parent))
+    } else {
+        anchor = document.createTextNode('')
+        parent.appendChild(anchor)
+    }
+
+    effect(() => {
+        const branch = condition() ? 'then' : 'else'
+        if (branch === activeBranch) {
+            return
+        }
+        if (active !== undefined) {
+            active.dispose()
+            for (const node of active.nodes) {
+                parent.removeChild(node)
+            }
+            active = undefined
+        }
+        activeBranch = branch
+        const chosen = branch === 'then' ? render : renderElse
+        if (chosen === undefined) {
+            return
+        }
+        active = build(chosen)
+        for (const node of active.nodes) {
+            parent.insertBefore(node, anchor)
+        }
+    })
+}

package/src/lib/ui/effect.ts

@@ -0,0 +1,16 @@
+import { createEffectNode } from './runtime/createEffectNode.ts'
+import type { EffectResult } from './runtime/types/EffectResult.ts'
+
+/*
+Runs `fn` now, capturing every reactive cell it reads, then re-runs it whenever
+any of those change. `fn` may return a teardown — run before each re-run and on
+dispose — and may be async (its teardown then runs once the promise settles, but
+only the reads before its first `await` are tracked). Returns a dispose that runs
+the final teardown and detaches it from the graph. This is abide's from-scratch
+effect primitive: the open-on-first-read / close-on-last-reader lifecycle,
+grounded in abide's own reactive core.
+*/
+// @readme plumbing
+export function effect(fn: () => EffectResult): () => void {
+    return createEffectNode(fn)
+}