@abide/abide 0.57.1 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # abide
 
+## 0.58.0
+
+### Minor Changes
+
+- 3941314: address every component mount as its own hydration boundary so a structural desync inside a child recovers at that one boundary instead of discarding the whole page (ADR-0049)
+
+    A component's range now ships as `<!--abide:c:PATH-->…<!--/abide:c:PATH-->` (the child's render-path) in place of the anonymous `<!--[-->…<!--]-->`. On a hydration desync inside the child — including a client-true / server-false `{#if}` gating an element's presence (`pending(...)`, `refreshing(...)`, any state fed by a client-only effect) — `mountChild` discards just that boundary and remounts the child fresh, rather than throwing out of hydrate and cold-rebuilding the entire page. Structural gating on client-asymmetric probes is therefore now safe (it degrades to a local remount). `cloneStatic` now verifies its claimed hydration run against the template's top-level shape, so a purely-static gated element throws (and recovers) instead of silently mis-claiming a diverged branch. No public API change; the SSR wire format for component mounts changes (server and client ship together and stay congruent).
+
 ## 0.57.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.57.1",
+    "version": "0.58.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

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

@@ -616,16 +616,22 @@ export function generateSSR(
                 )
             }
             /* Non-hoistable child (off the top-level spine): await inline at its structural position,
-               sequential, as before — never streams. */
+               sequential, as before — never streams. Bracket its html in the ADDRESSED boundary
+               (ADR-0049) `abide:c:CHILDPATH` in place of the anonymous `[`/`]` — CHILDPATH is the
+               child's render-path (`$$renderPath(ordinal)`), the same id the client's `mountChild`
+               composes — so a hydration desync inside the child recovers AT this boundary instead of
+               reaching the router and discarding the whole page. */
             const result = nextVar('$child')
+            const childPath = nextVar('$cpath')
             return (
                 anchor +
-                push(target, RANGE_OPEN) +
+                `const ${childPath} = $$renderPath(${ordinal});\n` +
+                `${target}.push('<!--abide:c:' + ${childPath} + '-->');\n` +
                 `const ${result} = await ${renderExpr};\n` +
                 `${target}.push(${result}.html);\n` +
                 `for (const $a of ${result}.awaits) { $awaits.push($a); }\n` +
                 `Object.assign($resume, ${result}.resume);\n` +
-                push(target, RANGE_CLOSE)
+                `${target}.push('<!--/abide:c:' + ${childPath} + '-->');\n`
             )
         }
         if (node.kind === 'element' && node.tag === OUTLET_TAG) {

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

@@ -0,0 +1,27 @@
+import { scope } from '../runtime/scope.ts'
+import type { UiProps } from '../runtime/types/UiProps.ts'
+import { disposeRange } from './disposeRange.ts'
+import { openMarker } from './openMarker.ts'
+import { withScope } from './withScope.ts'
+
+/*
+Adopts a component's server range IN PLACE during hydration, given its already-claimed
+`start` marker and the `closeData` of the marker that ends the range. Establishes the
+child's lexical scope + render pass (`withScope`), builds claiming the existing nodes,
+then claims the end marker the build's content stops before — the hydrate half of
+`mountRange`, factored out so `mountChild`'s ADDRESSED adopt (`abide:c:PATH` brackets,
+ADR-0049) and `mountRange`'s anonymous `[`/`]` adopt share ONE implementation and can't
+drift. A build throw is leak-safe: `withScope`/`scope` dispose the partial scope before
+rethrowing, so the caller's `discardAndRebuild` recovery starts clean.
+*/
+export function adoptRange(
+    parent: Node,
+    build: (host: Node, props?: UiProps) => void,
+    props: UiProps | undefined,
+    start: Comment,
+    closeData: string,
+): { start: Comment; end: Comment; dispose: () => void } {
+    const scoped = withScope(() => scope(() => build(parent, props)))
+    const end = openMarker(parent, closeData)
+    return { start, end, dispose: disposeRange(scoped, start, end) }
+}

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

@@ -1,5 +1,7 @@
+import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
 import { claimRun } from '../runtime/claimRun.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { reportHydrationDivergence } from '../runtime/reportHydrationDivergence.ts'
 import { foreignWrapperTag } from './foreignWrapperTag.ts'
 import { templateFor } from './templateFor.ts'
 
@@ -29,10 +31,39 @@ export function cloneStatic(parent: Node, html: string): void {
     const source = wrapper === undefined ? template.content : (template.content.firstChild as Node)
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        claimRun(hydration, parent, source.childNodes.length)
+        /* Claim the run AND verify its top-level shape. A static clone is byte-identical to the
+           server markup, so it can only DIVERGE when a client-asymmetric gate above it (a sync
+           `{#if}`/`{#switch}` whose condition differs SSR↔client — `{#if pending()}`) rendered a
+           different branch on the server, leaving the claim cursor on foreign nodes. Unverified,
+           `claimRun` would SILENTLY adopt them — wrong nodes wired, cursor desynced for every later
+           sibling; assert the node names instead and throw the standard structural desync (like
+           `claimExpected`) so an addressed component boundary (ADR-0049) recovers locally. */
+        const claimed: Node[] = []
+        claimRun(hydration, parent, source.childNodes.length, claimed)
+        assertStaticRun(claimed, source.childNodes)
         return
     }
     for (const child of source.childNodes) {
         parent.appendChild(child.cloneNode(true))
     }
 }
+
+/* Throw a structural hydration desync when a claimed static run doesn't match its template's
+   top-level nodes (a short run, or a differing node at any position — an element vs the comment
+   marker of a diverged branch). Named on the `hydrate` channel first, then thrown so the nearest
+   addressed boundary can discard-and-rebuild. */
+function assertStaticRun(claimed: Node[], expected: NodeListOf<ChildNode>): void {
+    const short = claimed.length !== expected.length
+    for (let index = 0; index < expected.length; index += 1) {
+        const want = (expected[index] as Node).nodeName
+        if (short || (claimed[index] as Node).nodeName !== want) {
+            reportHydrationDivergence('static structure desync', {
+                expected: want,
+                got: short ? '(missing)' : (claimed[index] as Node).nodeName,
+            })
+            throw new Error(
+                `[abide] hydration desync at ${CURRENT_PATH.current || '(root)'}: expected a static ${want} node here, but the server DOM had a different node — SSR markup and the client build disagree on structure at this position.`,
+            )
+        }
+    }
+}

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

@@ -5,9 +5,9 @@ import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
    `+1` opening a range, `-1` closing one, `0` for any other comment. A control-flow
    block's rendered content sits between an OPEN and CLOSE comment — `[`…`]` for each
    rows / if / switch / slot ranges, named `abide:…`…`/abide:…` for await / try /
-   snippet / html; the skeleton's own anchor (`a`) sits OUTSIDE any range, so it scores
-   `0`. Keeping the rule here means a new marker family updates one place, so the two
-   scans can never disagree on what nests. */
+   snippet / html / component-mount (`abide:c:`, ADR-0049); the skeleton's own anchor
+   (`a`) sits OUTSIDE any range, so it scores `0`. Keeping the rule here means a new
+   marker family updates one place, so the two scans can never disagree on what nests. */
 export function markerDepthDelta(data: string): number {
     if (data === RANGE_CLOSE || data.startsWith('/abide:')) {
         return -1

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

@@ -3,8 +3,10 @@ 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 { reportHydrationDivergence } from '../runtime/reportHydrationDivergence.ts'
 import type { UiComponent } from '../runtime/types/UiComponent.ts'
 import { withOptionalPath } from '../runtime/withOptionalPath.ts'
+import { adoptRange } from './adoptRange.ts'
 import { commentData } from './commentData.ts'
 import { discardAndRebuild } from './discardAndRebuild.ts'
 import { mountRange } from './mountRange.ts'
@@ -20,8 +22,12 @@ The server decides per render whether a HOISTABLE child (ADR-0039) inlined (fast
 streamed (still-pending), and the client build can't know which — nor whether this child was
 hoistable at all — so hydrate mode probes the cursor:
 
-  - `<!--[-->` (RANGE_OPEN) next → the server INLINED the child (every non-hoistable child,
-    and a hoistable one whose flight settled); adopt its range in place.
+  - `<!--abide:c:CHILDPATH-->` next → the server INLINED the child in its ADDRESSED boundary
+    (ADR-0049 — every non-streamed child); claim the boundary open, adopt the range in place,
+    claim the close. A structural desync INSIDE the child (a client-true / server-false `{#if}`
+    gating an element's presence) throws through the build — recover by discarding just this
+    boundary and remounting the child fresh (`discardAndRebuild`), so the desync costs one
+    component instead of reaching the router and discarding the whole page.
   - `<!--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.
@@ -46,27 +52,56 @@ export function mountChild(
     ordinal?: number,
 ): void {
     const run = <T>(build: () => T): T => withOptionalPath(ordinal, build)
-    const mount = (): { dispose: () => void } =>
-        run(() => mountRange(parent, factory.build, props, before))
+    /* Both boundary ids are the child's render-path, computed here exactly as the server wrote it
+       (`renderPath(ordinal)`), so SSR and client agree with no counter. */
+    const childPath = run(() => CURRENT_PATH.current)
+    const addressed = { open: `abide:c:${childPath}`, close: `/abide:c:${childPath}` }
+    /* Mount the child's range in its ADDRESSED boundary (ADR-0049) — the create path and the
+       inline-recovery rebuild, so a client-only mount is byte-congruent with the SSR markup and a
+       desync has a named close to discard to. */
+    const mountAddressed = (where: Node | null): { dispose: () => void } =>
+        run(() => mountRange(parent, factory.build, props, where, addressed))
+    /* Mount into an anonymous `[ … ]` range — the swapped-in inner range of a STREAMED child, whose
+       own address is the outer `abide:await` pair. */
+    const mountAnon = (where: Node | null): { dispose: () => void } =>
+        run(() => mountRange(parent, factory.build, props, where))
 
     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()
+        /* Call mountAddressed() first, THEN register its dispose — pushing the call result inline
+           would short-circuit (never mounting) when there is no owner. */
+        const handle = mountAddressed(before)
         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)
+    /* Probe the cursor without consuming it, and classify what the server emitted here by the
+       marker data. */
     const cursor = claimChild(hydration, parent)
-    const streamed = cursor !== null && commentData(cursor) === `abide:await:${childPath}`
+    const marker = cursor !== null ? commentData(cursor) : undefined
 
-    if (!streamed) {
-        /* INLINE — the server inlined the child's `[ … ]` range; adopt it in place. */
-        const handle = mount()
-        OWNER.current?.push(handle.dispose)
+    if (marker !== `abide:await:${childPath}`) {
+        /* INLINE (ADR-0049) — claim the addressed open, adopt the child's range in place. A
+           structural desync inside the child throws through the build; recover by discarding just
+           THIS boundary and remounting fresh, so the desync costs one component, not the page. The
+           partial scope a throwing build stranded is already disposed (`withScope`/`scope`), so the
+           cold rebuild starts clean. */
+        const open = openMarker(parent, addressed.open)
+        try {
+            const handle = run(() =>
+                adoptRange(parent, factory.build, props, open, addressed.close),
+            )
+            OWNER.current?.push(handle.dispose)
+        } catch (error) {
+            reportHydrationDivergence('component boundary recovered — remounting', {
+                path: childPath,
+                error,
+            })
+            const handle = discardAndRebuild(hydration, parent, open, addressed.close, (after) =>
+                mountAddressed(after),
+            )
+            OWNER.current?.push(handle.dispose)
+        }
         return
     }
 
@@ -75,7 +110,7 @@ export function mountChild(
     const inner = claimChild(hydration, parent)
     const warm = inner !== null && commentData(inner) === RANGE_OPEN
     if (warm) {
-        const handle = mount()
+        const handle = mountAnon(before)
         openMarker(parent, `/abide:await:${childPath}`)
         OWNER.current?.push(handle.dispose)
         return
@@ -88,7 +123,7 @@ export function mountChild(
         parent,
         open,
         `/abide:await:${childPath}`,
-        (after) => run(() => mountRange(parent, factory.build, props, after)),
+        (after) => mountAnon(after),
     )
     OWNER.current?.push(handle.dispose)
 }

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

@@ -1,11 +1,9 @@
 import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
-import { scope } from '../runtime/scope.ts'
 import type { UiProps } from '../runtime/types/UiProps.ts'
-import { disposeRange } from './disposeRange.ts'
+import { adoptRange } from './adoptRange.ts'
 import { fillRange } from './fillRange.ts'
 import { openMarker } from './openMarker.ts'
-import { withScope } from './withScope.ts'
 
 /*
 Mounts a nested child component as a marker-bounded range — the wrapper-free
@@ -22,6 +20,12 @@ marker — mirrors `mountSlot`/`when`). `before` (a skeleton-located node, the b
 `anchorCursor`) places the range among static siblings on create; hydrate ignores it
 (the claim cursor drives placement). Returns the markers + a disposer so the hot path
 can rebuild in place.
+
+`bracket` names the range's boundary markers. It defaults to the anonymous `[`/`]` a
+control-flow re-fill and the swapped-in inner range of a streamed child use; `mountChild`
+passes the ADDRESSED `abide:c:PATH` pair (ADR-0049) so a component's range carries its own
+render-path — the same markers on create and SSR (congruent) and a named close a desync can
+discard to.
 */
 // @documentation plumbing
 export function mountRange(
@@ -29,17 +33,16 @@ export function mountRange(
     build: (host: Node, props?: UiProps) => void,
     props: UiProps | undefined,
     before: Node | null = null,
+    bracket: { open: string; close: string } = DEFAULT_BRACKET,
 ): { start: Comment; end: Comment; dispose: () => void } {
     const hydration = RENDER.hydration
-    const start = openMarker(parent, RANGE_OPEN, before)
+    const start = openMarker(parent, bracket.open, before)
     if (hydration === undefined) {
-        const end = openMarker(parent, RANGE_CLOSE, before)
+        const end = openMarker(parent, bracket.close, before)
         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(() => scope(() => build(parent, props)))
-    const end = openMarker(parent, RANGE_CLOSE)
-    return { start, end, dispose: disposeRange(scoped, start, end) }
+    /* Hydrate: adopt the server range in place, claiming `bracket.close` as the end marker. */
+    return adoptRange(parent, build, props, start, bracket.close)
 }
+
+const DEFAULT_BRACKET = { open: RANGE_OPEN, close: RANGE_CLOSE }

package/src/lib/ui/finalizeStreamedChildren.ts

@@ -1,13 +1,7 @@
 import type { FlightPromise } from './flight.ts'
-import { RANGE_CLOSE, RANGE_OPEN } from './runtime/RANGE_MARKER.ts'
 import type { ResumeEntry } from './runtime/RESUME.ts'
 import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
 
-/* Comment-wrapped range markers — imported from the shared constant (not a local literal) so the
-   inline branch below can never drift from `generateSSR`'s own range emit. */
-const OPEN = `<!--${RANGE_OPEN}-->`
-const CLOSE = `<!--${RANGE_CLOSE}-->`
-
 /* One hoistable child render staged by generateSSR: the reserved index in its output array, the
    array itself, the child's render-path (the streamed boundary id), and its in-flight render. */
 export type StagedChild = {
@@ -24,9 +18,9 @@ hoistable child was started as an isolated `$$flight` in the prefix and its outp
 (an empty `$out` slot); here we fill that slot per child:
 
 - A flight that has already SETTLED (a synchronous / warm-cache child, or a fast read) inlines its
-  html into the reserved slot as `<!--[-->…<!--]-->` — BYTE-IDENTICAL to the pre-ADR-0039 inline
-  `await Child.render()` path, so an all-fast page's wire and hydration are unchanged. Its awaits /
-  resume merge exactly as the inline path did.
+  html into the reserved slot in the child's addressed `abide:c:CHILDPATH` boundary (ADR-0049) —
+  the same shape `generateSSR`'s non-hoistable inline path emits, so an all-fast page adopts and
+  recovers uniformly. Its awaits / resume merge exactly as the inline path did.
 - A flight settled REJECTED rethrows here — same as a rejecting inline await (500 before flush).
 - A still-PENDING flight (genuine I/O) STREAMS: the slot gets an empty `abide:await:CHILDPATH`
   boundary, and an html-only SsrAwait is pushed so `renderToStream` flushes the shell now and streams
@@ -53,7 +47,12 @@ export async function finalizeStreamedChildren(
     for (const staged of slots) {
         if (staged.flight.settled && staged.flight.error === undefined) {
             const rendered = staged.flight.value as SsrRender
-            staged.out[staged.slot] = OPEN + rendered.html + CLOSE
+            /* Inline the settled html in the child's ADDRESSED boundary (ADR-0049) — the same
+               `abide:c:CHILDPATH` shape `generateSSR`'s non-hoistable path emits, so the client's
+               `mountChild` adopts a hoistable-settled and a non-hoistable child identically (it can't
+               know which the server chose) and either recovers at this boundary on a desync. */
+            staged.out[staged.slot] =
+                `<!--abide:c:${staged.id}-->${rendered.html}<!--/abide:c:${staged.id}-->`
             mergeChildRender(rendered, awaits, resume)
         } else if (staged.flight.settled) {
             throw staged.flight.error

package/src/lib/ui/runtime/RANGE_MARKER.ts

@@ -7,7 +7,9 @@
 
    A control-flow block's rendered content sits between an OPEN (`[`) and CLOSE (`]`)
    comment; a snippet interpolation between `abide:snippet` / `/abide:snippet` (matching
-   `skeleton`'s `abide:` / `/abide:` named-boundary convention, like `OUTLET_MARKER`).
+   `skeleton`'s `abide:` / `/abide:` named-boundary convention, like `OUTLET_MARKER`); a
+   component mount between the ADDRESSED pair `abide:c:PATH` / `/abide:c:PATH` (PATH the
+   child's render-path — ADR-0049 — so a desync inside recovers at that one boundary).
    The skeleton's own positioning anchor (`a`) sits OUTSIDE any such range. */
 export const RANGE_OPEN = '['
 export const RANGE_CLOSE = ']'