@abide/abide 0.33.0 → 0.34.0

package/src/lib/ui/compile/lowerContext.ts

@@ -15,9 +15,13 @@ fix lands here once instead of in lockstep across `generateBuild`/`generateSSR`.
 SSR's effect-stripping stays a caller-side wrap (`stripEffects`), the one real
 asymmetry; the node-walk skeletons stay in each back-end.
 */
-export function lowerContext(stateNames: ReadonlySet<string>, derivedNames: ReadonlySet<string>) {
+export function lowerContext(
+    stateNames: ReadonlySet<string>,
+    derivedNames: ReadonlySet<string>,
+    computedNames: ReadonlySet<string> = new Set(),
+) {
     /* Branch-scoped signal bindings (from nested `<script>`s) — they deref to
-       `.value` like a `derived`. Pushed while a branch's script + markup compile,
+       `.value` like a `computed`. Pushed while a branch's script + markup compile,
        popped after, so they shadow only within that subtree. */
     const localDerived = new Set<string>()
     const derefScope = (): ReadonlySet<string> =>
@@ -28,16 +32,52 @@ export function lowerContext(stateNames: ReadonlySet<string>, derivedNames: Read
        expression, not a block of labeled statements, through both rewrite passes;
        the wrapper is then peeled back off. */
     function expression(code: string): string {
-        const renamed = renameSignalRefs(`(${code})`, stateNames, derefScope())
+        const renamed = renameSignalRefs(`(${code})`, stateNames, derefScope(), computedNames)
         return unwrapParens(lowerDocAccess(renamed, 'model').trim().replace(/;$/, ''))
     }
 
     /* As above but keeps the trailing `;` for a statement/handler body. */
     function statement(code: string): string {
-        const renamed = renameSignalRefs(code, stateNames, derefScope())
+        const renamed = renameSignalRefs(code, stateNames, derefScope(), computedNames)
         return lowerDocAccess(renamed, 'model').trim()
     }
 
+    /* A two-way bind target is either an LVALUE (`count`, `model.lines[i]`) — reads as
+       itself, writes by assignment — or an ACCESSOR object from `bind:value={{ get, set }}`
+       — reads via `.get()`, writes via `.set(v)`. The accessor is the only way to bind a
+       value whose write goes somewhere other than the read target (the replacement for the
+       old writable `computed(compute, set)` lens). A read-only `computed` is NOT an lvalue,
+       so binding one bare is a compile error pointing at the accessor form. */
+    const isAccessorBind = (code: string): boolean => code.trim().startsWith('{')
+
+    function guardWritableBind(code: string): void {
+        const name = code.trim()
+        if (computedNames.has(name)) {
+            throw new Error(
+                `bind: \`${name}\` is a read-only computed — bind a writable target, or an accessor: bind:value={{ get: () => ${name}, set: (next) => { /* write the source */ } }}`,
+            )
+        }
+    }
+
+    /* The expression a two-way bind reads its current value from. */
+    function bindRead(code: string): string {
+        if (isAccessorBind(code)) {
+            return `(${expression(code)}).get()`
+        }
+        guardWritableBind(code)
+        return expression(code)
+    }
+
+    /* The statement a two-way bind runs to write `valueExpr` (a raw runtime expression,
+       e.g. `el.value`) back into its target. */
+    function bindWrite(code: string, valueExpr: string): string {
+        if (isAccessorBind(code)) {
+            return `(${expression(code)}).set(${valueExpr});`
+        }
+        guardWritableBind(code)
+        return statement(`${code} = ${valueExpr}`)
+    }
+
     /* Adds any `<script>` children's binding names to the deref scope (so the script
        bodies and the branch's markup auto-deref them), runs `body` within that scope,
        then pops the names it added. Returns whatever `body` produces. */
@@ -60,5 +100,5 @@ export function lowerContext(stateNames: ReadonlySet<string>, derivedNames: Read
         return result
     }
 
-    return { expression, statement, withNestedScripts }
+    return { expression, statement, withNestedScripts, bindRead, bindWrite }
 }

package/src/lib/ui/compile/prepareNestedScript.ts

@@ -3,7 +3,7 @@ import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
 
 /*
 The signal binding names a `<script>` nested in a control-flow branch declares
-(`state`/`linked`/`derived`/`prop`). The back-end adds them to the deref scope so both the
+(`state`/`linked`/`computed`/`prop`). The back-end adds them to the deref scope so both the
 script body and the branch's markup rewrite `{a}` → `a.value` — these stay PLAIN
 signals (local to the branch's render, owned by its scope, re-seeded from the
 in-scope data each mount), unlike the top-level component script which desugars to
@@ -30,15 +30,19 @@ export function nestedBindingNames(code: string): Set<string> {
     return names
 }
 
-/* The callee name of a `NAME = state(...)` / `derived(...)` / `prop(...)` declaration. */
+/* The callee name of a `NAME = state(...)` / `computed(...)` / `prop(...)` declaration —
+   bare or the explicit scope form (`scope().state(...)` / `c.state(...)`), receiver-agnostic. */
 function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
     const initializer = declaration.initializer
-    if (
-        initializer !== undefined &&
-        ts.isCallExpression(initializer) &&
-        ts.isIdentifier(initializer.expression)
-    ) {
-        return initializer.expression.text
+    if (initializer === undefined || !ts.isCallExpression(initializer)) {
+        return undefined
+    }
+    const callee = initializer.expression
+    if (ts.isIdentifier(callee)) {
+        return callee.text
+    }
+    if (ts.isPropertyAccessExpression(callee)) {
+        return callee.name.text
     }
     return undefined
 }

package/src/lib/ui/compile/renameSignalRefs.ts

@@ -3,7 +3,7 @@ import ts from 'typescript'
 /*
 Rewrites references to a component's signal bindings into the document form the
 rest of the pipeline understands: a `state` binding `count` becomes `model.count`
-(data access `lowerDocAccess` then lowers to a patch/read), and a `derived`
+(data access `lowerDocAccess` then lowers to a patch/read), and a `computed`
 binding `total` becomes `total.value`. Only value-position identifiers are
 touched — declaration names, parameter names, and property names are collected
 into a skip set first, and object shorthand (`{ count }`) is expanded to
@@ -14,6 +14,7 @@ export function renameSignalRefs(
     code: string,
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
+    computedNames: ReadonlySet<string> = new Set(),
 ): string {
     const source = ts.createSourceFile('component.ts', code, ts.ScriptTarget.Latest, true)
 
@@ -47,13 +48,23 @@ export function renameSignalRefs(
             const visit = (node: ts.Node): ts.Node => {
                 /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`. */
                 if (ts.isShorthandPropertyAssignment(node)) {
-                    const replacement = referenceFor(node.name.text, stateNames, derivedNames)
+                    const replacement = referenceFor(
+                        node.name.text,
+                        stateNames,
+                        derivedNames,
+                        computedNames,
+                    )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
                     }
                 }
                 if (ts.isIdentifier(node) && !skip.has(node)) {
-                    const replacement = referenceFor(node.text, stateNames, derivedNames)
+                    const replacement = referenceFor(
+                        node.text,
+                        stateNames,
+                        derivedNames,
+                        computedNames,
+                    )
                     if (replacement !== undefined) {
                         return replacement
                     }
@@ -69,15 +80,21 @@ export function renameSignalRefs(
     return output
 }
 
-/* `model.<name>` for a state binding, `<name>.value` for a derived one, else undefined. */
+/* `model.<name>` for a state binding, `<name>()` for a computed doc-slot (the
+   string-free reader `scope().derive` returns), `<name>.value` for a runtime cell
+   (linked / lens / transform-state), else undefined. */
 function referenceFor(
     name: string,
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
+    computedNames: ReadonlySet<string>,
 ): ts.Expression | undefined {
     if (stateNames.has(name)) {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('model'), name)
     }
+    if (computedNames.has(name)) {
+        return ts.factory.createCallExpression(ts.factory.createIdentifier(name), undefined, [])
+    }
     if (derivedNames.has(name)) {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(name), 'value')
     }

package/src/lib/ui/compile/skeletonable.ts

@@ -1,19 +1,6 @@
+import { isControlFlow } from './isControlFlow.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
-/* A control-flow block — `if`/`each`/`await`/`switch`/`try`. In a skeleton it mounts at an
-   `<!--a-->` anchor cloned into the located parent at the block's position (see
-   `anchorCursor`), so a block can sit ANYWHERE among static siblings — no contiguity or
-   prefix-shape constraint. */
-function isControlFlow(node: TemplateNode): boolean {
-    return (
-        node.kind === 'if' ||
-        node.kind === 'each' ||
-        node.kind === 'await' ||
-        node.kind === 'switch' ||
-        node.kind === 'try'
-    )
-}
-
 /* Whether a subtree is skeleton STRUCTURE — anything the parser-backed clone can carry with
    its holes mounted in place: elements, `<style>`, text (static OR reactive), child
    components (their wrapper element is positioned in the skeleton), control-flow blocks and

package/src/lib/ui/compile/types/AnalyzedComponent.ts

@@ -13,6 +13,7 @@ export type AnalyzedComponent = {
     imports: string
     stateNames: Set<string>
     derivedNames: Set<string>
+    computedNames: Set<string>
     nodes: TemplateNode[]
     /* One entry per non-empty `<style>` in the template (in source order): the scope
        attribute its covered elements carry (annotated onto `nodes`) and the scoped

package/src/lib/ui/computed.ts

@@ -0,0 +1,32 @@
+import { createComputedNode } from './runtime/createComputedNode.ts'
+import { OWNER } from './runtime/OWNER.ts'
+import { readNode } from './runtime/readNode.ts'
+import type { Computed } from './runtime/types/Computed.ts'
+import { unlinkDeps } from './runtime/unlinkDeps.ts'
+
+/*
+A reactive cell computed from other cells — the abide replacement for `$derived`.
+Named `computed` (not `derived`) and ALWAYS read-only: unlike Svelte's reassignable
+`$derived`, a computed is purely a function of its inputs, the way Vue/Angular
+`computed` is. There is no local store and nothing to assign — a write to a computed
+would be a write to its *sources*, which is expressed at the binding site instead
+(`bind:value={{ get, set }}`), where the write actually originates. Lazy: it
+recomputes on read only when a dependency changed, and never serializes (it is
+re-derived from its inputs on resume). Read via `.value`.
+*/
+export function computed<T>(compute: () => T): Computed<T> {
+    const node = createComputedNode(compute as () => unknown)
+    /* Tear down with the enclosing scope, the way an effect does. A computed only
+       unlinks from its sources when it re-runs (`runNode` re-tracking); one read
+       once and then abandoned never re-runs, so absent this it would sit in its
+       source signals' subscriber lists forever — re-marked dirty on every write to
+       them — for the source's lifetime. Outside a scope it owns its own life (no-op). */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => unlinkDeps(node))
+    }
+    return {
+        get value(): T {
+            return readNode(node) as T
+        },
+    }
+}

package/src/lib/ui/createScope.ts

@@ -0,0 +1,91 @@
+import { computed } from './computed.ts'
+import { history } from './history.ts'
+import { linked } from './linked.ts'
+import { persist as persistDoc } from './persist.ts'
+import { createDoc } from './runtime/createDoc.ts'
+import type { Doc } from './runtime/types/Doc.ts'
+import { state } from './state.ts'
+import { sync } from './sync.ts'
+import type { History } from './types/History.ts'
+import type { PersistHandle } from './types/PersistHandle.ts'
+import type { Scope } from './types/Scope.ts'
+
+/* A process-stable counter id. The serialization-stable LEXICAL id (route +
+   component + tree position) that `persistent`/`sync` want across reloads/peers
+   is stamped by the compiler later; until then a scope's id is unique within a
+   run — enough for in-session undo and the bus, and as an explicit key's fallback. */
+let nextId = 0
+
+/*
+Builds a lexical scope. Its data is a document — created eagerly from `initial`,
+or (when `awaiting`) ADOPTED from the first `doc()` a component body creates under
+it, so a scope can wrap the component's own model without changing the data
+lowering. Data methods mirror `Doc` and delegate to that document; capabilities
+are lazy (`undoable`/`persistent` attach `history`/`persist` to it on first call);
+`child` nests; `dispose` tears the subtree down children-first.
+*/
+export function createScope(
+    initial: unknown = {},
+    parent: Scope | undefined = undefined,
+    awaiting = false,
+): Scope {
+    /* Eager unless awaiting adoption; `data()` lazily mints an empty doc if a body
+       never created one (a stateless component that still reaches for its scope). */
+    let document: Doc | undefined = awaiting ? undefined : createDoc(initial)
+    const data = (): Doc => (document ??= createDoc({}))
+    const id = parent === undefined ? `scope-${nextId++}` : `${parent.id}.${nextId++}`
+    const children: Scope[] = []
+    let past: History | undefined
+    let persistence: PersistHandle | undefined
+    let unsync: (() => void) | undefined
+
+    const self: Scope = {
+        id,
+        parent,
+        read: (path) => data().read(path),
+        replace: (path, value) => data().replace(path, value),
+        add: (path, value) => data().add(path, value),
+        remove: (path) => data().remove(path),
+        apply: (patch) => data().apply(patch),
+        cell: (path) => data().cell(path),
+        derive: (path, compute) => data().derive(path, compute),
+        snapshot: () => data().snapshot(),
+        /* The `.value`-cell signal forms, namespaced under the scope — standalone
+           non-serializing cells (owned by the render scope), reached only here. */
+        state,
+        linked,
+        computed,
+        child: (childInitial = {}) => {
+            const created = createScope(childInitial, self)
+            children.push(created)
+            return created
+        },
+        root: () => (parent === undefined ? self : parent.root()),
+        record: (options) => {
+            past ??= history(data(), options)
+        },
+        persist: (key) => {
+            persistence ??= persistDoc(data(), key ?? id)
+        },
+        broadcast: (transport) => {
+            unsync ??= sync(data(), transport)
+        },
+        undo: () => past?.undo(),
+        redo: () => past?.redo(),
+        canUndo: () => past?.canUndo() ?? false,
+        canRedo: () => past?.canRedo() ?? false,
+        dispose: () => {
+            for (const created of children) {
+                created.dispose()
+            }
+            children.length = 0
+            past?.dispose()
+            past = undefined
+            persistence?.dispose()
+            persistence = undefined
+            unsync?.()
+            unsync = undefined
+        },
+    }
+    return self
+}

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

@@ -13,7 +13,7 @@ the parent's claim cursor there, so the block claims its own server range in pla
 block ignores the returned reference on hydrate). `parentNode` is the located element the
 anchor was cloned into.
 */
-// @readme plumbing
+// @documentation plumbing
 export function anchorCursor(anchor: Node): Node | null {
     const reference = anchor.nextSibling
     const hydration = RENDER.hydration

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

@@ -14,7 +14,7 @@ On hydrate the builder runs against the server-rendered nodes between the
 claim them in place. The cursor is advanced past the open marker before, and past
 the close marker after, so the markers themselves are skipped.
 */
-// @readme plumbing
+// @documentation plumbing
 export function appendSnippet(parent: Node, read: () => unknown): void {
     const builder = snippetPayload(read())
     if (typeof builder !== 'function') {

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

@@ -7,7 +7,7 @@ mode), or claimed from the server-rendered text (hydrate mode). As with reactive
 text, a merged SSR text node is split at this literal's length so the next claim
 lines up; nothing is bound since the text never changes.
 */
-// @readme plumbing
+// @documentation plumbing
 export function appendStatic(parent: Node, value: string, splitAlways = false): void {
     const hydration = RENDER.hydration
     if (hydration !== undefined) {

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

@@ -20,7 +20,7 @@ between `<!--abide:html-->`/`<!--/abide:html-->` markers are adopted (hydrate),
 a change re-parses and swaps. A binding is text or raw for its lifetime (decided by
 its first value), so plain text — the common case — stays a cheap single node.
 */
-// @readme plumbing
+// @documentation plumbing
 export function appendText(parent: Node, read: () => unknown, splitAlways = false): void {
     /* A snippet call (`{row(args)}`) mounts its builder; a `html\`\`` value inserts
        raw markup; everything else is escaped text — decided by the first value. */

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

@@ -21,7 +21,7 @@ Hydrate delegates to `appendText` with the cursor temporarily pointed at the anc
 content (the server rendered `<!--a-->value`, so the value is the anchor's next sibling),
 reusing its text-split / snippet / raw-html claiming.
 */
-// @readme plumbing
+// @documentation plumbing
 export function appendTextAt(anchor: Node, read: () => unknown): void {
     const parent = anchor.parentNode as Node
     if (RENDER.hydration !== undefined) {

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

@@ -9,7 +9,7 @@ the pending nodes between the markers, and inserts the resolved content in their
 place. The pending shell painted instantly; this swaps in each value as it
 arrives — completing the out-of-order streaming loop on the client.
 */
-// @readme plumbing
+// @documentation plumbing
 export function applyResolved(root: Element, frame: string): void {
     const holder = document.createElement('div')
     holder.innerHTML = frame

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

@@ -1,3 +1,5 @@
+import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
+import { inScope } from '../runtime/inScope.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { toTeardown } from '../runtime/toTeardown.ts'
 import type { EffectResult } from '../runtime/types/EffectResult.ts'
@@ -11,10 +13,13 @@ the attachment sets up. Node-lifetime, not reactive — for param reactivity put
 async; its teardown then runs once the promise settles. Runtime target for an
 `attach={…}` binding.
 */
-// @readme plumbing
+// @documentation plumbing
 export function attach(element: Element, attachment: (node: Element) => EffectResult): void {
+    /* The attachment body runs now (scope already current); pin the teardown, which
+       fires on dispose, so an ambient `scope()` in it resolves the component. */
+    const captured = CURRENT_SCOPE.current
     const teardown = toTeardown(attachment(element))
     if (teardown !== undefined && OWNER.current !== undefined) {
-        OWNER.current.push(teardown)
+        OWNER.current.push(() => inScope(captured, teardown))
     }
 }

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

@@ -6,7 +6,7 @@ and false/null/undefined removes it (the standard present/absent semantics);
 anything else is stringified. One effect per bound attribute, so only the
 changed attribute touches the DOM.
 */
-// @readme plumbing
+// @documentation plumbing
 export function attr(element: Element, name: string, read: () => unknown): void {
     effect(() => {
         const value = read()

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

@@ -25,7 +25,7 @@ Hydration adopts in place, by precedence:
 After the first (adopting) run, later invalidations swap content before an anchor
 parked just before the close marker.
 */
-// @readme plumbing
+// @documentation plumbing
 export function awaitBlock(
     parent: Node,
     id: number,

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

@@ -17,7 +17,7 @@ claim cursor past the run's top-level nodes (nothing inside binds, so none need
 claiming individually). The node count comes from the parsed template, which has
 the same top-level node count as the server markup.
 */
-// @readme plumbing
+// @documentation plumbing
 export function cloneStatic(parent: Node, html: string): void {
     /* When `parent` is a foreign element built imperatively, the run's markup has no
        foreign ancestor of its own, so a bare `<path>` would parse into the HTML

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

@@ -1,5 +1,6 @@
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
+import { claimExpected } from '../runtime/claimExpected.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
@@ -26,7 +27,7 @@ On hydrate the SSR rows are already in place and in order: each row claims its
 markers and content where they sit (no reordering), the anchor parks after them,
 and the first reconcile is skipped.
 */
-// @readme plumbing
+// @documentation plumbing
 export function each<T>(
     parent: Node,
     items: () => Iterable<T>,
@@ -44,10 +45,10 @@ export function each<T>(
     const buildRow = (item: T): EachRow => {
         const hydration = RENDER.hydration
         if (hydration !== undefined) {
-            const start = claimChild(hydration, parent) as Node
+            const start = claimExpected(hydration, parent, 'each row start marker')
             hydration.next.set(parent, start.nextSibling)
             const dispose = scope(() => render(parent, item))
-            const end = claimChild(hydration, parent) as Node
+            const end = claimExpected(hydration, parent, 'each row end marker')
             hydration.next.set(parent, end.nextSibling)
             return { start, end, dispose }
         }

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

@@ -21,7 +21,7 @@ On a mid-stream rejection the already-streamed rows stay and the `<template catc
 branch (`renderCatch`) renders after them; absent a catch branch the rejection
 surfaces (re-throws), mirroring `<template await>`.
 */
-// @readme plumbing
+// @documentation plumbing
 export function eachAsync<T>(
     parent: Node,
     items: () => AsyncIterable<T>,

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

@@ -1,3 +1,5 @@
+import { createScope } from '../createScope.ts'
+import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
 import { enterRenderPass } from '../runtime/enterRenderPass.ts'
 import { exitRenderPass } from '../runtime/exitRenderPass.ts'
 import { RENDER } from '../runtime/RENDER.ts'
@@ -11,24 +13,36 @@ 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`.
++ text + bindings), `if`/`else`, keyed `each`, `switch`, `try`, and child
+components (with slots) — they hydrate automatically because the wrapper is
+claimed while hydration is still active. `await` adopts too when it can resume
+the value (a streamed `RESUME[id]` or a warm-sync/cache read); only a genuinely-
+pending `await` — no resume, not cache-warm — discards its boundary and builds
+the pending branch fresh (see `awaitBlock`).
 */
-// @readme plumbing
+// @documentation plumbing
 export function hydrate(host: Element, build: (host: Element) => void): () => void {
     const previous = RENDER.hydration
     RENDER.hydration = { next: new Map() }
     enterRenderPass()
+    /* Same lexical scope establishment as `mount` — a hydrated component owns a scope
+       too, adopting the model its build adopts. */
+    const parentScope = CURRENT_SCOPE.current
+    const lexical = createScope({}, parentScope, true)
+    CURRENT_SCOPE.current = lexical
     try {
-        return scope(() => {
+        const stop = scope(() => {
             try {
                 build(host)
             } finally {
                 exitRenderPass()
+                CURRENT_SCOPE.current = parentScope
             }
         })
+        return () => {
+            stop()
+            lexical.dispose()
+        }
     } finally {
         RENDER.hydration = previous
     }

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

@@ -1,3 +1,5 @@
+import { createScope } from '../createScope.ts'
+import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
 import { enterRenderPass } from '../runtime/enterRenderPass.ts'
 import { exitRenderPass } from '../runtime/exitRenderPass.ts'
 import { scope } from '../runtime/scope.ts'
@@ -12,18 +14,27 @@ 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
+// @documentation plumbing
 export function mount(host: Element, build: (host: Element) => void): () => void {
     enterRenderPass()
+    /* Establish this component's lexical scope, nested under the enclosing one, in
+       `awaiting` mode so it adopts the model doc the build's first `doc()` creates.
+       `scope()` and its capabilities resolve to it during the build; the previous
+       scope is restored after (synchronous build, so the restore is exact). */
+    const parentScope = CURRENT_SCOPE.current
+    const lexical = createScope({}, parentScope, true)
+    CURRENT_SCOPE.current = lexical
     const stop = scope(() => {
         try {
             build(host)
         } finally {
             exitRenderPass()
+            CURRENT_SCOPE.current = parentScope
         }
     })
     return () => {
         stop()
+        lexical.dispose()
         host.textContent = ''
     }
 }

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

@@ -1,3 +1,4 @@
+import { captureModelDoc } from '../runtime/captureModelDoc.ts'
 import { hotReloadEnabled } from '../runtime/hotReloadEnabled.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { registerHotInstance } from '../runtime/registerHotInstance.ts'
@@ -13,7 +14,7 @@ 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
+// @documentation plumbing
 export function mountChild(
     host: Element,
     factory: UiComponent,
@@ -24,7 +25,10 @@ export function mountChild(
         factory(host, props)
         return
     }
-    const instance = { host, factory, props, dispose: factory(host, props) }
+    /* Capture the component's model alongside its disposer, so a later swap can carry
+       its state across (see `hotReplace`). */
+    const { dispose, model } = captureModelDoc(() => factory(host, props))
+    const instance = { host, factory, props, dispose, model }
     const remove = registerHotInstance(moduleId, instance)
     OWNER.current?.push(() => {
         instance.dispose()

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

@@ -14,7 +14,7 @@ claiming.
 Create fills the range before the end marker; hydrate adopts the server range in place
 (claiming from the parked cursor). Mirrors `when` without the conditional swap.
 */
-// @readme plumbing
+// @documentation plumbing
 export function mountSlot(
     parent: Node,
     render: (host: Node) => void,

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

@@ -1,15 +1,21 @@
+import { CURRENT_SCOPE } from '../runtime/CURRENT_SCOPE.ts'
+import { inScope } from '../runtime/inScope.ts'
 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.
+lowered patches (`model.replace(...)`) run. The handler is pinned to the scope it
+was attached under, so an ambient `scope()` inside it (e.g. `scope().undo()`)
+resolves the component, not whatever is current when the event fires.
 */
-// @readme plumbing
+// @documentation plumbing
 export function on(element: Element, type: string, handler: EventListener): void {
-    element.addEventListener(type, handler)
+    const captured = CURRENT_SCOPE.current
+    const wrapped: EventListener = (event) => inScope(captured, () => handler(event))
+    element.addEventListener(type, wrapped)
     if (OWNER.current !== undefined) {
-        OWNER.current.push(() => element.removeEventListener(type, handler))
+        OWNER.current.push(() => element.removeEventListener(type, wrapped))
     }
 }