@abide/abide 0.38.0 → 0.38.1

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

@@ -0,0 +1,38 @@
+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 { fillRange } from './fillRange.ts'
+import { withScope } from './withScope.ts'
+
+/*
+Mounts a chain layer (layout or page) into an EXISTING outlet boundary — the markers
+a parent layout's `<slot/>` left (`outlet`), or the router's root boundary in `#app`.
+The router fills these boundaries instead of mounting into a host element, so the whole
+page/layout chain composes through one range model (no `<abide-outlet>` wrapper).
+
+Create: build the layer's content into a fragment that lands just before `close`
+(`fillRange`). Hydrate: claim the server content in place — park the parent cursor at
+`open.nextSibling` and let the build adopt the existing nodes (the outlet markers
+themselves are located via `PENDING_OUTLET`, not claimed through the cursor). The disposer
+stops the layer's reactivity and clears the boundary — the router calls it to tear a
+divergent layer down before rebuilding the same boundary.
+*/
+// @documentation plumbing
+export function fillBoundary(
+    open: Comment,
+    close: Comment,
+    build: (host: Node, props?: UiProps) => void,
+    props: UiProps | undefined,
+    label: string | undefined,
+): { dispose: () => void } {
+    const hydration = RENDER.hydration
+    if (hydration === undefined) {
+        return fillRange(open, close, build, props, label)
+    }
+    /* Hydrate: adopt the server content between the markers in place. */
+    const parent = open.parentNode as Node
+    hydration.next.set(parent, open.nextSibling)
+    const scoped = withScope(label, () => scope(() => build(parent, props)))
+    return { dispose: disposeRange(scoped, open, close) }
+}

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

@@ -0,0 +1,30 @@
+import type { UiProps } from '../runtime/types/UiProps.ts'
+import { disposeRange } from './disposeRange.ts'
+import { fillBefore } from './fillBefore.ts'
+import { withScope } from './withScope.ts'
+
+/*
+Builds a component's content fresh between two existing range markers (the create
+path), under the component's own lexical scope and render pass — the range analog of
+`mount` for a nested child. `build` appends into a fragment (via `fillBefore`) that
+lands just before `end`, so the content sits in the `[ … ]` range the child mounts
+into rather than at the parent's tail; that range is what makes a component
+selector-transparent (a true direct child of its parent, no `<abide-name>` wrapper).
+
+Brackets a render pass (a nested child continues the parent's block-id counter) and
+establishes the child's lexical scope in `awaiting` mode so it adopts the model doc
+its first `doc()` creates. The disposer stops the content's reactivity, disposes the
+lexical scope, and clears the range — leaving the markers, so a hot swap rebuilds in
+place. Shared by `mountRange` (create branch) and `hotReplace` (re-fill on edit).
+*/
+// @documentation plumbing
+export function fillRange(
+    start: Comment,
+    end: Comment,
+    build: (host: Node, props?: UiProps) => void,
+    props: UiProps | undefined,
+    label: string | undefined,
+): { start: Comment; end: Comment; dispose: () => void } {
+    const scoped = withScope(label, () => fillBefore(end, (fragment) => build(fragment, props)))
+    return { start, end, dispose: disposeRange(scoped, start, end) }
+}

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

@@ -1,10 +1,7 @@
-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'
 import { scope } from '../runtime/scope.ts'
 import { scopeLabel } from './scopeLabel.ts'
+import { withScope } from './withScope.ts'
 
 /*
 Adopts existing server-rendered DOM instead of rebuilding it. Runs `build(host)`
@@ -15,31 +12,24 @@ focus/scroll). Returns a disposer.
 
 Adopts the server DOM in place across the framework: static structure (elements
 + 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
+components (with slots) — they hydrate automatically because a child's marker range
+is claimed while hydration is still active (see `mountRange`). `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`).
 */
 // @documentation plumbing
-export function hydrate(host: Element, build: (host: Element) => void): () => void {
+export function hydrate(
+    host: Element,
+    build: (host: Element, props: unknown) => void,
+    props?: unknown,
+): () => 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, scopeLabel(host))
-    CURRENT_SCOPE.current = lexical
     try {
-        const stop = scope(() => {
-            try {
-                build(host)
-            } finally {
-                exitRenderPass()
-                CURRENT_SCOPE.current = parentScope
-            }
-        })
+        /* Same shared mount core as `mount` (see `withScope`) — a hydrated component owns a
+           scope too, adopting the model its build adopts — run with the claim cursor active. */
+        const { stop, lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
         return () => {
             stop()
             lexical.dispose()

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

@@ -1,38 +1,29 @@
-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'
 import { scopeLabel } from './scopeLabel.ts'
+import { withScope } from './withScope.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.
+Mounts a top-level page/layout into `host` (the router's outlet/root element): runs
+`build(host, props)` 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 router calls; a NESTED child instead mounts as a marker range (see
+`mountRange`), so it leaves no wrapper element.
 
 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`).
 */
 // @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, scopeLabel(host))
-    CURRENT_SCOPE.current = lexical
-    const stop = scope(() => {
-        try {
-            build(host)
-        } finally {
-            exitRenderPass()
-            CURRENT_SCOPE.current = parentScope
-        }
-    })
+export function mount(
+    host: Element,
+    build: (host: Element, props: unknown) => void,
+    props?: unknown,
+): () => void {
+    /* 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 { stop, lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
     return () => {
         stop()
         lexical.dispose()

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

@@ -3,32 +3,45 @@ 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 { mountRange } from './mountRange.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.
+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
+leave together when the parent (or branch/row) tears down.
 */
 // @documentation plumbing
 export function mountChild(
-    host: Element,
+    parent: Node,
     factory: UiComponent,
     props: Parameters<UiComponent>[1],
+    before: Node | null = null,
+    label?: string,
 ): void {
     const moduleId = factory.__abideId
     if (!hotReloadEnabled.current || moduleId === undefined) {
-        factory(host, props)
+        mountRange(parent, factory.build, props, before, label)
         return
     }
-    /* 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 }
+    /* 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()

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

@@ -0,0 +1,45 @@
+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 { 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
+replacement for the old `<abide-name display:contents>` host. A component positions
+and hydrates exactly like a control-flow block: its content lives in a `[ … ]` range,
+so the child's real root is a TRUE direct child of the parent and structural CSS
+(`>`, `:first-child`, `space-x`, grid placement) reaches it with no indirection —
+which `display:contents` could never give, since it hides the wrapper from layout but
+not from the selector tree.
+
+Create fills the range before the end marker (`fillRange`); hydrate claims the server
+range in place (claim the start marker, build claims the content, claim the end
+marker — mirrors `mountSlot`/`when`). `before` (a skeleton-located node, the block's
+`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.
+*/
+// @documentation plumbing
+export function mountRange(
+    parent: Node,
+    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, '[', before)
+    if (hydration === undefined) {
+        const end = openMarker(parent, ']', before)
+        return fillRange(start, end, build, props, label)
+    }
+    /* 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 end = openMarker(parent, ']')
+    return { start, end, dispose: disposeRange(scoped, start, end) }
+}

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

@@ -0,0 +1,62 @@
+import { claimExpected } from '../runtime/claimExpected.ts'
+import { OUTLET_CLOSE, OUTLET_OPEN } from '../runtime/OUTLET_MARKER.ts'
+import { PENDING_OUTLET } from '../runtime/PENDING_OUTLET.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { commentData } from './commentData.ts'
+
+/*
+A layout's `<slot/>` outlet: an empty `<!--abide:outlet-->`…`<!--/abide:outlet-->`
+boundary the router fills with the next chain layer (`fillBoundary`). No wrapper
+element, so the filled child lays out as a direct child of the slot's parent.
+
+Create: insert the empty boundary at `before` (the anchor's cursor). Hydrate: claim the
+open marker, then SKIP the server-rendered child content — the router re-claims it when
+it fills the boundary — by advancing the parent's claim cursor past the MATCHING close
+(depth-counting nested outlets), so the layout's own claims after the slot stay aligned.
+Records the boundary in `PENDING_OUTLET` (and returns it) so the router learns where the
+next chain layer mounts without scanning the DOM.
+*/
+// @documentation plumbing
+export function outlet(
+    parent: Node,
+    before: Node | null = null,
+): { open: Comment; close: Comment } {
+    const hydration = RENDER.hydration
+    if (hydration === undefined) {
+        const open = document.createComment(OUTLET_OPEN)
+        const close = document.createComment(OUTLET_CLOSE)
+        parent.insertBefore(open, before)
+        parent.insertBefore(close, before)
+        PENDING_OUTLET.current = { open, close }
+        return { open, close }
+    }
+    const open = claimExpected(hydration, parent, 'outlet open marker') as Comment
+    /* Skip to the matching close: depth-count outlet markers (nested child-layer slots
+       are balanced), so a layout wrapping another layout skips its WHOLE subtree. */
+    let depth = 1
+    let node: Node | null = open.nextSibling
+    while (node !== null) {
+        const data = commentData(node)
+        if (data === OUTLET_OPEN) {
+            depth += 1
+        } else if (data === OUTLET_CLOSE) {
+            depth -= 1
+            if (depth === 0) {
+                break
+            }
+        }
+        node = node.nextSibling
+    }
+    /* No matching close — the server stream ended inside the slot (a mid-render error
+       or truncation). Throw AT the divergence like `claimExpected`, rather than store a
+       null close that a later `clearBetween(open, null)` would over-clear to end-of-parent. */
+    if (node === null) {
+        throw new Error(
+            '[abide] hydration desync: outlet open marker has no matching close — the server DOM is truncated inside a layout slot.',
+        )
+    }
+    const close = node as Comment
+    hydration.next.set(parent, close.nextSibling)
+    PENDING_OUTLET.current = { open, close }
+    return { open, close }
+}

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

@@ -1,10 +1,12 @@
 /*
-The human-readable name for the scope a mount/hydrate establishes, derived from
-its host element's tag. A nested component mounts into its `abide-<name>` wrapper
-(see `componentWrapperTag`), so stripping the `abide-` prefix recovers the
-component name; any other host (a page/layout outlet) yields its lowercased tag.
-Dev-only — feeds the inspector's Reactive tab so a scope reads `<Counter>` rather
-than an opaque counter id. Returns undefined when there's no element to name from.
+The human-readable name for the scope the direct-mount entry (`mount`/`hydrate`)
+establishes, derived from its host element's tag. The router instead fills layers into
+marker boundaries with no host element, so it passes each layer's route key as an
+explicit label (`fillBoundary`); a nested child likewise passes its component name (see
+`mountRange`). The `abide-` prefix strip turns a framework host tag like `abide-resolve`
+into `resolve`; any other host yields its lowercased tag. Dev-only — feeds the
+inspector's Reactive tab a readable scope name. Returns undefined when there's no element
+to name from.
 */
 import { COMPONENT_WRAPPER_PREFIX } from '../COMPONENT_WRAPPER_PREFIX.ts'
 

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

@@ -1,7 +1,7 @@
-import { COMPONENT_WRAPPER_PREFIX } from '../COMPONENT_WRAPPER_PREFIX.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { HOLE_ATTRIBUTE } from '../runtime/HOLE_ATTRIBUTE.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { commentData } from './commentData.ts'
 import { foreignWrapperTag } from './foreignWrapperTag.ts'
 import type { SkeletonHoles } from './types/SkeletonHoles.ts'
 
@@ -27,28 +27,6 @@ function isElement(node: Node): node is Element {
     return typeof (node as Element).hasAttribute === 'function'
 }
 
-/* A child component's mount wrapper (`abide-<name>`, see `componentWrapperTag`). Its
-   content is a SEPARATE skeleton (the child's own), so the parent's walks must treat it
-   as opaque: in the shallow skeleton it's an empty leaf, so the compiler counts no
-   anchors inside it; on hydrate it's populated, so a descent would over-collect the
-   child's anchors and shift every parent index past it (same hazard as a block range,
-   but bounded by the wrapper element instead of `[`…`]` markers). */
-function isComponentWrapper(node: Node): boolean {
-    return (
-        isElement(node) && (node.tagName ?? '').toLowerCase().startsWith(COMPONENT_WRAPPER_PREFIX)
-    )
-}
-
-/* A comment node's data, or undefined for elements/text. A comment is a node that is
-   neither an element (`hasAttribute`) nor a text node (`splitText`); the mini-dom
-   exposes no `nodeType`, so detect by method. */
-function commentData(node: Node): string | undefined {
-    if (isElement(node) || typeof (node as Text).splitText === 'function') {
-        return undefined
-    }
-    return (node as Comment).data
-}
-
 /* Block-range boundary markers. A control-flow block's rendered content sits between an
    OPEN and CLOSE comment: `[`…`]` for each rows / if / switch / slot ranges, and named
    `abide:…`…`/abide:…` boundaries for await / try / snippet / html. The skeleton's own
@@ -116,19 +94,22 @@ function indexElementHoles(container: Node, prefix: number[], paths: number[][])
    In hydrate mode the claimed tree is FULLY EXPANDED — a nested block's rendered content
    (each rows, branches, await/try boundaries) sits inline — so a naive descent would also
    collect the inner block's anchors, which belong to that block's OWN skeleton, shifting
-   every index past the first block. Block content is bounded by range markers, so track
-   depth per sibling list and take an anchor (and recurse into an element) only at depth 0,
-   where the skeleton's own structure lives. In create mode the clone is shallow (the blocks
-   have not built yet — no markers), so depth stays 0 and this is a plain document scan. */
+   every index past the first block. Block AND child-component content is bounded by range
+   markers (a component mounts as a `[`…`]` range at its anchor, like a block — see
+   `mountRange`), so track depth per sibling list and take an anchor (and recurse into an
+   element) only at depth 0, where the skeleton's own structure lives. In create mode the
+   clone is shallow (the ranges have not built yet — no markers), so depth stays 0 and this
+   is a plain document scan. */
 function scanAnchors(nodes: ArrayLike<Node>, anchors: Node[]): void {
     let depth = 0
     for (let index = 0; index < nodes.length; index += 1) {
         const node = nodes[index] as Node
         const data = commentData(node)
         if (data === undefined) {
-            /* Recurse into this skeleton's own elements, but NOT a child component's
-               wrapper — its anchors belong to the child's skeleton (see above). */
-            if (isElement(node) && depth === 0 && !isComponentWrapper(node)) {
+            /* Recurse into this skeleton's own elements at depth 0. A child component's
+               content sits inside its `[`…`]` range (depth > 0), so it is skipped like any
+               block range — its anchors belong to the child's own skeleton. */
+            if (isElement(node) && depth === 0) {
                 scanAnchors(node.childNodes, anchors)
             }
         } else if (isCloseMarker(data)) {

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

@@ -0,0 +1,33 @@
+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 type { Scope } from '../types/Scope.ts'
+
+/*
+The shared mount core every page/layout/component build path runs (`mount`, `hydrate`,
+`fillRange`, `mountRange`, `fillBoundary`). Establishes the layer's lexical scope nested
+under the current one in `awaiting` mode — so it adopts the model doc its first `doc()`
+creates — brackets a render pass — so its `await`/`try` block ids draw from the shared
+counter in SSR-stream order — runs `build`, then restores the previous scope (synchronous
+build, so the restore is exact). `build` returns its reactivity stopper (from `scope` or
+`fillBefore`); the caller composes its own DOM teardown (clear host vs clear range) around
+the returned `stop`/`lexical`, keeping the one scope/render-pass contract in a single place.
+*/
+export function withScope(
+    label: string | undefined,
+    build: () => () => void,
+): { stop: () => void; lexical: Scope } {
+    const parentScope = CURRENT_SCOPE.current
+    const lexical = createScope({}, parentScope, true, label)
+    enterRenderPass()
+    CURRENT_SCOPE.current = lexical
+    let stop: () => void = () => undefined
+    try {
+        stop = build()
+    } finally {
+        exitRenderPass()
+        CURRENT_SCOPE.current = parentScope
+    }
+    return { stop, lexical }
+}

package/src/lib/ui/installHotBridge.ts

@@ -16,6 +16,7 @@ import { mount } from './dom/mount.ts'
 import { mountChild } from './dom/mountChild.ts'
 import { mountSlot } from './dom/mountSlot.ts'
 import { on } from './dom/on.ts'
+import { outlet } from './dom/outlet.ts'
 import { skeleton } from './dom/skeleton.ts'
 import { switchBlock } from './dom/switchBlock.ts'
 import { tryBlock } from './dom/tryBlock.ts'
@@ -67,6 +68,7 @@ export function installHotBridge(): void {
         tryBlock,
         switchBlock,
         mountSlot,
+        outlet,
         mountChild,
         hydrate,
         escapeKey,

package/src/lib/ui/renderChain.ts

@@ -1,12 +1,13 @@
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
-import { OUTLET_TAG } from './runtime/OUTLET_TAG.ts'
+import { OUTLET_CLOSE, OUTLET_OPEN } from './runtime/OUTLET_MARKER.ts'
 import type { SsrRender } from './runtime/types/SsrRender.ts'
 import type { UiComponent } from './runtime/types/UiComponent.ts'
 
-const OUTLET_OPEN = `<${OUTLET_TAG}>`
-const OUTLET_CLOSE = `</${OUTLET_TAG}>`
-const OUTLET_PLACEHOLDER = `${OUTLET_OPEN}${OUTLET_CLOSE}`
+const OPEN = `<!--${OUTLET_OPEN}-->`
+const CLOSE = `<!--${OUTLET_CLOSE}-->`
+/* A layout's empty outlet boundary, before the child layer is folded in. */
+const OUTLET_PLACEHOLDER = `${OPEN}${CLOSE}`
 
 /*
 Server-renders a route's layout chain wrapped around its page into one SsrRender.
@@ -17,12 +18,13 @@ across all layers draws a unique id from the shared counter — in the same
 layer-sequential order the client hydrates them, keeping the streamed fragments and
 the resume manifest aligned.
 
-The html nests inner-to-outer: each parent's empty `<abide-outlet>` is filled with
-the accumulated child html — the outlet ELEMENT is kept (it stays the live mount
-container the client router fills/hydrates the child into, found by tag), so the
-SSR DOM and the client-nested DOM match exactly. Awaits concatenate (already
-uniquely numbered); state merges. A single component renders unchanged — its own
-render with no wrapping. A layout missing its `<slot/>` is a build error surfaced here.
+The html nests inner-to-outer: each parent layout's empty outlet boundary
+(`<!--abide:outlet--><!--/abide:outlet-->`) is filled with the accumulated child html —
+no `<abide-outlet>` ELEMENT, so the filled child lays out as a direct child of the
+slot's parent (the router mounts/hydrates it as a marker range, see `outlet`/`fillBoundary`).
+The whole chain is wrapped in a ROOT boundary the router fills into `#app`. Awaits
+concatenate (already uniquely numbered); state merges. A layout missing its `<slot/>` is
+a build error surfaced here.
 */
 export function renderChain(views: UiComponent[], params: Record<string, string>): SsrRender {
     enterRenderPass()
@@ -31,16 +33,22 @@ export function renderChain(views: UiComponent[], params: Record<string, string>
         let html = renders[renders.length - 1]?.html ?? ''
         for (let index = renders.length - 2; index >= 0; index -= 1) {
             const parent = renders[index] as SsrRender
-            if (!parent.html.includes(OUTLET_PLACEHOLDER)) {
+            /* EXACTLY one outlet, not at-least-one: `.replace` fills only the first, and
+               the client router fills the LAST `outlet()` call's boundary (`PENDING_OUTLET`),
+               so a second outlet would mount the SSR child and the hydrated child into
+               DIFFERENT slots — a silent desync. Throw at build instead. */
+            if (parent.html.split(OUTLET_PLACEHOLDER).length - 1 !== 1) {
                 throw new Error('[abide] a layout.abide must contain exactly one <slot/> outlet')
             }
-            /* Fill the outlet element (keep it), function replacement so `$&`/`$\`` in
-               the child html insert literally. */
+            /* Fold the child between the outlet markers (function replacement so `$&`/`$\``
+               in the child html insert literally). */
             const child = html
-            html = parent.html.replace(OUTLET_PLACEHOLDER, () => OUTLET_OPEN + child + OUTLET_CLOSE)
+            html = parent.html.replace(OUTLET_PLACEHOLDER, () => OPEN + child + CLOSE)
         }
         return {
-            html,
+            /* Root boundary — the router fills `#app` by claiming/creating this same
+               boundary and mounting the outermost layer (or lone page) into it. */
+            html: OPEN + html + CLOSE,
             awaits: renders.flatMap((render) => render.awaits),
             state: Object.assign({}, ...renders.map((render) => render.state)),
         }