@abide/abide 0.49.0 → 0.50.0

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

@@ -1,5 +1,4 @@
 import { scope } from '../runtime/scope.ts'
-import { scopeLabel } from './scopeLabel.ts'
 import { withScope } from './withScope.ts'
 
 /*
@@ -23,7 +22,7 @@ export function mount(
     /* Establish this component's lexical scope (nested, `awaiting` so it adopts the model
        doc the build's first `doc()` creates) and render pass, run the build under it, and
        restore the previous scope — the shared mount core (see `withScope`). */
-    const { lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
+    const { lexical } = withScope(() => scope(() => build(host, props)))
     return () => {
         lexical.dispose()
         host.textContent = ''

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

@@ -1,25 +1,12 @@
-import { captureModelDoc } from '../runtime/captureModelDoc.ts'
-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'
+import { withOptionalPath } from '../runtime/withOptionalPath.ts'
 import { mountRange } from './mountRange.ts'
 
-/* Build-time flag the production client defines false (see build.ts `define`) so the hot
-   path below — and its captureModelDoc/registerHotInstance imports — dead-code-eliminate
-   (`!false` folds to a constant the minifier can prove) instead of shipping behind a runtime
-   flag it can't. Dev defines it true; the test preload sets it on globalThis so the bare
-   reference resolves to true there, leaving `hotReloadEnabled` alone in charge as before. */
-declare const __ABIDE_DEV__: boolean
-
 /*
 Mounts a child component as a marker-bounded range at `before` in `parent` — no
 wrapper element, so the child's root is a true direct child of the parent (see
-`mountRange`). Plain path (production, and dev without the hot bridge): just run the
-range mount with the component's own `build`. Hot path (hotReloadEnabled and the
-factory carries a module id): keep the mount handle (its range markers + disposer)
-and record the instance so an edit can re-fill the same range in place (see
-`hotReplace`), and file a cleanup with the mounting owner so the record and its scope
+`mountRange`). Files the range's dispose with the mounting owner so its scope and DOM
 leave together when the parent (or branch/row) tears down.
 */
 // @documentation plumbing
@@ -28,30 +15,12 @@ export function mountChild(
     factory: UiComponent,
     props: Parameters<UiComponent>[1],
     before: Node | null = null,
-    label?: string,
+    /* The compiler's source-order ordinal for this `<Child/>` mount site — pushed onto the render
+       path so the child's scope (and its cells) get a serialization-stable id under this parent
+       (two same-type siblings differ by ordinal; the same site across `{#each}` rows differs by the
+       row key the each block already pushed). Absent (a non-compiled caller) → no path segment. */
+    ordinal?: number,
 ): void {
-    const moduleId = factory.__abideId
-    if (!__ABIDE_DEV__ || !hotReloadEnabled.current || moduleId === undefined) {
-        mountRange(parent, factory.build, props, before, label)
-        return
-    }
-    /* Capture the component's model alongside its mount handle, so a later swap can
-       carry its state across (see `hotReplace`). */
-    const { value: handle, model } = captureModelDoc(() =>
-        mountRange(parent, factory.build, props, before, label),
-    )
-    const instance = {
-        factory,
-        props,
-        label,
-        start: handle.start,
-        end: handle.end,
-        dispose: handle.dispose,
-        model,
-    }
-    const remove = registerHotInstance(moduleId, instance)
-    OWNER.current?.push(() => {
-        instance.dispose()
-        remove()
-    })
+    const handle = withOptionalPath(ordinal, () => mountRange(parent, factory.build, props, before))
+    OWNER.current?.push(handle.dispose)
 }

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

@@ -29,18 +29,17 @@ export function mountRange(
     build: (host: Node, props?: UiProps) => void,
     props: UiProps | undefined,
     before: Node | null = null,
-    label: string | undefined = undefined,
 ): { start: Comment; end: Comment; dispose: () => void } {
     const hydration = RENDER.hydration
     const start = openMarker(parent, RANGE_OPEN, before)
     if (hydration === undefined) {
         const end = openMarker(parent, RANGE_CLOSE, before)
-        return fillRange(start, end, build, props, label)
+        return fillRange(start, end, build, props)
     }
     /* Hydrate: adopt the server range in place. Establish the child's lexical scope
        and render pass (same as `fillRange`), build claiming the existing nodes, then
        claim the end marker the build's content stops before. */
-    const scoped = withScope(label, () => scope(() => build(parent, props)))
+    const scoped = withScope(() => scope(() => build(parent, props)))
     const end = openMarker(parent, RANGE_CLOSE)
     return { start, end, dispose: disposeRange(scoped, start, end) }
 }

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

@@ -0,0 +1,84 @@
+import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { OWNER } from '../runtime/OWNER.ts'
+import { RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import type { UiComponent } from '../runtime/types/UiComponent.ts'
+import { withOptionalPath } from '../runtime/withOptionalPath.ts'
+import { withoutHydration } from '../runtime/withoutHydration.ts'
+import { discardBoundary } from './discardBoundary.ts'
+import { mountRange } from './mountRange.ts'
+import { openMarker } from './openMarker.ts'
+
+/*
+The client mount for a HOISTABLE child (ADR-0039) — a DUAL-MODE adopter. The server decides per
+render whether a hoistable child inlined (fast/settled) or streamed (still-pending), and the client
+build can't know which, so this probes the hydration cursor:
+
+  - `<!--[-->` (RANGE_OPEN) next → the server INLINED the child; adopt its range exactly as
+    `mountChild` does (byte-identical to the pre-ADR-0039 path).
+  - `<!--abide:await:CHILDPATH-->` next → the server STREAMED it; `__abideSwap` has already spliced
+    the child's `<!--[-->…<!--]-->` between the boundary markers before the bundle ran, so claim the
+    boundary open, adopt the inner range in place, claim the boundary close.
+  - no hydration (a client-side navigation) → a plain create-mode mount, like `mountChild`.
+
+CHILDPATH is the child's render-path — `withPath(ordinal, () => CURRENT_PATH.current)` — computed the
+same way the server's `renderPath(ordinal)` wrote the boundary id, so the two agree with no counter.
+A streamed child re-mounts (no RESUME value of its own — the boundary is html-only); nested `{#await}`
+blocks and async cells inside it adopt through their own existing channels.
+*/
+// @documentation plumbing
+export function mountStreamedChild(
+    parent: Node,
+    factory: UiComponent,
+    props: Parameters<UiComponent>[1],
+    before: Node | null = null,
+    ordinal?: number,
+): void {
+    const run = <T>(build: () => T): T => withOptionalPath(ordinal, build)
+    const mount = (): { dispose: () => void } =>
+        run(() => mountRange(parent, factory.build, props, before))
+
+    const hydration = RENDER.hydration
+    if (hydration === undefined) {
+        /* Call mount() first, THEN register its dispose — `OWNER.current?.push(mount())` would
+           short-circuit the whole expression (never mounting) when there is no owner. */
+        const handle = mount()
+        OWNER.current?.push(handle.dispose)
+        return
+    }
+
+    /* Probe the cursor without consuming it. Streamed iff the next node is this child's boundary. */
+    const childPath = run(() => CURRENT_PATH.current)
+    const cursor = claimChild(hydration, parent)
+    const streamed =
+        cursor !== null &&
+        cursor.nodeType === 8 &&
+        (cursor as Comment).data === `abide:await:${childPath}`
+
+    if (!streamed) {
+        /* INLINE — the server inlined a settled child; adopt its `[ … ]` range in place. */
+        const handle = mount()
+        OWNER.current?.push(handle.dispose)
+        return
+    }
+
+    /* STREAMED — claim the boundary open (advances the cursor to the swapped-in `[`). */
+    const open = openMarker(parent, `abide:await:${childPath}`)
+    const inner = claimChild(hydration, parent)
+    const warm = inner !== null && inner.nodeType === 8 && (inner as Comment).data === RANGE_OPEN
+    if (warm) {
+        const handle = mount()
+        openMarker(parent, `/abide:await:${childPath}`)
+        OWNER.current?.push(handle.dispose)
+        return
+    }
+    /* COLD (defensive — renderToStream drains every await before closing, so a warm boundary is the
+       deterministic path). The fragment never arrived: discard the empty boundary and create-mount
+       the child fresh at that position; its streamed cells resolve post-mount via receiveStreamedCell. */
+    const after = discardBoundary(parent, open, `/abide:await:${childPath}`, hydration)
+    const handle = withoutHydration(() =>
+        run(() => mountRange(parent, factory.build, props, after)),
+    )
+    OWNER.current?.push(handle.dispose)
+}

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

@@ -1,9 +1,13 @@
 import { effect } from '../effect.ts'
+import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
 import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
+import { withPathFrom } from '../runtime/withPathFrom.ts'
+import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
+import { matchingRangeClose } from './matchingRangeClose.ts'
 import { openMarker } from './openMarker.ts'
 import { replaceRange } from './replaceRange.ts'
 
@@ -35,6 +39,15 @@ export function mountSwappableRange<Key>(
     key: () => Key,
     contentFor: (key: Key) => ((parent: Node) => void) | undefined,
     before: Node | null = null,
+    /* The chosen branch MAY differ between SSR and the client's first render — set only for an
+       ASYNC subject (a bare async `{#if}`/`{#switch}`, or an async cond-chain branch), whose cell
+       can be settled on the server (a barrier-baked value) yet pending on the client, so each side
+       selects a different branch. Adopting SSR nodes in place then orphans them (they are neither
+       claimed nor cleared) and the next swap duplicates. When set, hydration DISCARDS the SSR range
+       content and builds the client's branch fresh instead — correct regardless of what the server
+       rendered. Left false for a sync range, where SSR and client always agree and in-place
+       adoption (node reuse, preserved focus/scroll) is safe. */
+    mayDiverge = false,
 ): void {
     const hydration = RENDER.hydration
     /* The live branch's scope, registered with the owner so it disposes on owner
@@ -44,10 +57,39 @@ export function mountSwappableRange<Key>(
     let activeKey: Key
     let end: Comment
 
+    /* Capture the render path at construction (this block's ancestry), and wrap each chosen
+       branch's builder so its content builds under `basePath/branchKey` — the key is the swap
+       discriminator (`'then'`/`'else'` or a case index), so a component/cell in one branch gets a
+       distinct, stable id from the other, re-established on every reactive swap (when the ambient
+       path is gone). An empty branch (`undefined`) needs no wrap. */
+    const basePath = CURRENT_PATH.current
+    const chosenFor = (branchKey: Key): ((parent: Node) => void) | undefined => {
+        const content = contentFor(branchKey)
+        if (content === undefined) {
+            return undefined
+        }
+        return (host) => withPathFrom(basePath, String(branchKey), () => content(host))
+    }
+
     const start = openMarker(parent, RANGE_OPEN, before)
-    if (hydration !== undefined) {
+    if (hydration !== undefined && mayDiverge) {
+        /* Async range: don't trust the SSR content to match the client's branch. Discard the
+           server's rendered range (balanced `[`…`]`), park the cursor on the real close so it
+           claims correctly, then build the client's chosen branch FRESH (`fillBefore` clears the
+           claim cursor for the build). Usually the client is pending here → nothing built → an
+           empty range the later reactive swap fills, matching a clean create. */
+        activeKey = key()
+        const chosen = chosenFor(activeKey)
+        const matchedEnd = matchingRangeClose(start)
+        clearBetween(start, matchedEnd)
+        hydration.next.set(parent, matchedEnd)
+        end = openMarker(parent, RANGE_CLOSE)
+        if (chosen !== undefined) {
+            dispose = group.track(fillBefore(end, chosen))
+        }
+    } else if (hydration !== undefined) {
         activeKey = key()
-        const chosen = contentFor(activeKey)
+        const chosen = chosenFor(activeKey)
         if (chosen !== undefined) {
             dispose = group.track(scope(() => chosen(parent))) // content claims the SSR nodes in place
         }
@@ -55,7 +97,7 @@ export function mountSwappableRange<Key>(
     } else {
         end = openMarker(parent, RANGE_CLOSE, before)
         activeKey = key()
-        const chosen = contentFor(activeKey)
+        const chosen = chosenFor(activeKey)
         if (chosen !== undefined) {
             dispose = group.track(fillBefore(end, chosen))
         }
@@ -67,7 +109,7 @@ export function mountSwappableRange<Key>(
             return
         }
         activeKey = next
-        const chosen = contentFor(next)
+        const chosen = chosenFor(next)
         /* Null `dispose` before `replaceRange` builds the new branch: a reentrant swap
            during that build (an effect in the new content writing the source) would
            otherwise re-enter with the already-disposed disposer and clear it twice. */

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

@@ -0,0 +1,65 @@
+import type { Doc } from '../runtime/types/Doc.ts'
+import { readCall } from './readCall.ts'
+
+/*
+An in-place-mutating container method lowered on a reactive-document value. The
+doc-access lowering rewrites e.g. `model.items.splice(i, 1)` to
+`$$mutateDocContainer(model, "items", "splice", [i, 1])` rather than the bare
+`$$readCall(model.read("items"), …)` it emits for non-mutating calls. The reason:
+`read` returns the live tree value by reference, so a bare `.splice()`/`.sort()`/
+`.add()`/`.set()`/… would mutate the document in place while never emitting a
+patch — so no reader would re-render (`.push` is the one already-handled exception,
+lowered to `add` patches). Cloning the container, applying the mutation to the copy,
+and writing it back through `replace` emits a real patch: readers wake.
+
+Covers the three mutable containers the doc codec serializes (encodeRefJson):
+Array (cloned by `slice`), Map (`new Map`) and Set (`new Set`) — the mutating
+method names are disjoint across the three (`pop`/`splice`/… vs `add`/`set`/…), so
+the caller routes them all here and the actual kind is decided at runtime by the
+value's type, no compile-time check needed. Element identity is preserved for
+untouched entries (a shallow copy), so a keyed `{#for}` reconciles instead of
+rebuilding. The native method's return value (spliced-out elements, the new
+length, the deleted flag, …) is returned unchanged.
+*/
+// @documentation plumbing
+export function mutateDocContainer(
+    doc: Doc,
+    path: string,
+    member: string,
+    args: unknown[],
+): unknown {
+    const current = doc.read<unknown>(path)
+    const copy = cloneContainer(current)
+    /* Not a container we clone (array/Map/Set) — fall back to the guarded in-place call so
+       the author still gets readCall's authored-scope error message (a plain doc object has
+       no methods, so this is the same throw the bare call would raise). */
+    if (copy === undefined) {
+        return readCall(current, path, member, args)
+    }
+    const method = (copy as unknown as Record<string, unknown>)[member]
+    if (typeof method !== 'function') {
+        throw new TypeError(
+            `abide: cannot call .${member}() — "${path}".${member} is not a function (got ${typeof method})`,
+        )
+    }
+    const returned = (method as (...callArgs: unknown[]) => unknown).apply(copy, args)
+    doc.replace(path, copy)
+    return returned
+}
+
+/* A shallow clone of a mutable doc container, or undefined when the value is not one — the
+   shallow copy preserves element/entry identity so keyed reconciliation survives the patch. */
+function cloneContainer(
+    current: unknown,
+): unknown[] | Map<unknown, unknown> | Set<unknown> | undefined {
+    if (Array.isArray(current)) {
+        return current.slice()
+    }
+    if (current instanceof Map) {
+        return new Map(current)
+    }
+    if (current instanceof Set) {
+        return new Set(current)
+    }
+    return undefined
+}

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

@@ -8,8 +8,8 @@ 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. 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.
+was attached under, so an ambient `scope()` inside it resolves the component, not
+whatever is current when the event fires.
 */
 // @documentation plumbing
 export function on(element: Element, type: string, handler: EventListener): void {

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

@@ -0,0 +1,40 @@
+import { isAsyncCell } from '../../shared/isAsyncCell.ts'
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+import { AsyncCellError } from '../runtime/AsyncCellError.ts'
+
+/*
+Unified read for a `computed`/`linked` reference the compiler lowers to `$$readCell(NAME)`:
+an async cell (`AsyncComputed`/`AsyncState`) yields its latest retained value, a `derive`
+reader (a function) is called, and a sync `Computed`/`State` yields its `.value`. One read
+shape lets a `linked`/`computed` binding auto-track whichever source it resolved to — a
+settling promise, a stream, or a plain value — with no read-site branching in codegen.
+
+For an async cell this is a **throwing peek** (ADR-0019 D3.2), the value-aware rule that
+routes a "nothing to render" error to the nearest `{#try}`:
+  - error AND no retained value → throw `AsyncCellError` (carries the cell for keep-the-watch);
+  - error WITH a retained value → the value (a failed background refresh stays visible — SWR);
+  - pending (no value) → `undefined`;
+  - resolved → the value.
+The throw is a codegen behaviour only — `cell.peek()`/`cell.error()` in JS never throw; the
+author handles an error locally via the probes, or lets it reach a `{#try}`.
+*/
+// @documentation plumbing
+export function readCell(cell: unknown): unknown {
+    if (isAsyncCell(cell)) {
+        const asyncCell = cell as AsyncComputed<unknown>
+        const value = asyncCell.peek()
+        /* A retained value wins over an error (SWR) and over pending — return it. Only when
+           nothing is retained does an error become "nothing to render" and throw. */
+        if (value === undefined) {
+            const error = asyncCell.error()
+            if (error !== undefined) {
+                throw new AsyncCellError(asyncCell, error)
+            }
+        }
+        return value
+    }
+    if (typeof cell === 'function') {
+        return (cell as () => unknown)()
+    }
+    return (cell as { value: unknown }).value
+}

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

@@ -18,22 +18,45 @@ export function switchBlock(
     subject: () => unknown,
     cases: SwitchCase[],
     before: Node | null = null,
+    isPending?: () => boolean,
 ): void {
-    /* Pick the first case matching the subject (`===`), else the default (`match`
-       undefined), else -1 for no match. */
+    /* Walk the cases in source order (the same order a `{#if}`/`{:elseif}` chain reads): the
+       first whose own async condition is still `pending()` HOLDS the chain — returns -1, so no
+       later branch renders on a not-yet-known earlier condition; the first whose `match() ===`
+       the subject wins; a match-less `default` is the fallback once every case settled without a
+       match. A plain `{#switch}` (no per-case `pending`) reduces to first-match-else-default. */
     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
+        let fallback = -1
+        for (let index = 0; index < cases.length; index++) {
+            const entry = cases[index]
+            if (entry === undefined) {
+                continue
+            }
+            if (entry.pending?.()) {
+                return -1
+            }
+            if (entry.match === undefined) {
+                fallback = index
+            } else if (entry.match() === value) {
+                return index
+            }
+        }
+        return fallback
     }
     mountSwappableRange(
         parent,
-        () => select(subject()),
+        /* A pending bare async subject (compiler-supplied `isPending`) selects no case — not
+           even the default — so the block renders nothing until the cell settles, rather than
+           conflating "still loading" with a subject that matched the default. */
+        () => (isPending?.() === true ? -1 : select(subject())),
         (index) => {
             const chosen = index === -1 ? undefined : cases[index]
             return chosen && ((p) => chosen.render(p))
         },
         before,
+        /* Any async subject/branch (a bare async subject, or an async `{:else if}` in a cond-chain)
+           can select a different branch on the server than the pending client, so hydration must
+           discard the SSR range rather than adopt it in place. */
+        isPending !== undefined || cases.some((entry) => entry.pending !== undefined),
     )
 }