@abide/abide 0.37.0 → 0.38.1

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/mountSlot.ts

@@ -1,5 +1,6 @@
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
 
@@ -21,12 +22,16 @@ export function mountSlot(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The slot content's scope, registered with the owner so its effects/listeners
+       dispose on owner teardown (a navigation) — the slot never toggles, so the
+       group only ever tracks this one child. */
+    const group = scopeGroup()
     openMarker(parent, '[', before)
     if (hydration !== undefined) {
-        scope(() => render(parent)) // content claims the SSR range in place
+        group.track(scope(() => render(parent))) // content claims the SSR range in place
         openMarker(parent, ']')
     } else {
         const end = openMarker(parent, ']', before)
-        fillBefore(end, render)
+        group.track(fillBefore(end, render))
     }
 }

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,15 +1,21 @@
 /*
-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'
+
 export function scopeLabel(host: Element): string | undefined {
     const tag = host.tagName?.toLowerCase()
     if (tag === undefined) {
         return undefined
     }
-    return tag.startsWith('abide-') ? tag.slice('abide-'.length) : tag
+    return tag.startsWith(COMPONENT_WRAPPER_PREFIX)
+        ? tag.slice(COMPONENT_WRAPPER_PREFIX.length)
+        : tag
 }

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

@@ -1,6 +1,7 @@
 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'
 
@@ -26,26 +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('abide-')
-}
-
-/* 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
@@ -113,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/persist.ts

@@ -1,3 +1,4 @@
+import { escapeKey } from './runtime/escapeKey.ts'
 import { localStoragePersistence } from './runtime/localStoragePersistence.ts'
 import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
 import type { Doc } from './runtime/types/Doc.ts'
@@ -99,8 +100,10 @@ export function persist(
 function restore(doc: Doc, saved: unknown): void {
     const current = doc.snapshot()
     if (isPlainObject(saved) && isPlainObject(current)) {
+        /* `replace` takes a `/`-delimited escaped path, so a top-level key containing
+           `/` or `~` must be escaped to a single segment or it'd be mis-routed. */
         for (const key of Object.keys(saved)) {
-            doc.replace(key, saved[key])
+            doc.replace(escapeKey(key), saved[key])
         }
         return
     }

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)),
         }

package/src/lib/ui/router.ts

@@ -1,12 +1,15 @@
 import { layoutChainForRoute } from '../shared/layoutChainForRoute.ts'
+import { fillBoundary } from './dom/fillBoundary.ts'
+import { outlet } from './dom/outlet.ts'
 import { effect } from './effect.ts'
 import { matchRoute } from './matchRoute.ts'
 import { navigate } from './navigate.ts'
 import { clientPage } from './runtime/clientPage.ts'
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
-import { firstOutlet } from './runtime/firstOutlet.ts'
 import { historyEntries } from './runtime/historyEntries.ts'
+import { PENDING_OUTLET } from './runtime/PENDING_OUTLET.ts'
+import { RENDER } from './runtime/RENDER.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 import type { AbideHistoryState } from './runtime/types/AbideHistoryState.ts'
 import type { NavVerdict } from './runtime/types/NavVerdict.ts'
@@ -14,13 +17,15 @@ import type { Route } from './runtime/types/Route.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
 import { untrack } from './runtime/untrack.ts'
 
-/* A layout mounted in the active chain: its route key (the directory URL — its
-   identity for the diff), the disposer that stops its reactivity, and the outlet
-   element the next layer mounts into. */
-type MountedLayout = { key: string; dispose: () => void; outlet: Element }
+/* An outlet boundary — the `<!--abide:outlet-->`…`<!--/abide:outlet-->` marker pair a
+   layer's content lives between (a layout's `<slot/>`, or the router's root boundary in
+   the mount host). The next chain layer fills it; no `<abide-outlet>` element. */
+type Boundary = { open: Comment; close: Comment }
 
-/* A layout mount that returns no disposer still needs one for the chain teardown. */
-const noop = (): void => {}
+/* A layout mounted in the active chain: its route key (the directory URL — its identity
+   for the diff), the disposer that stops its reactivity and clears its content, and the
+   boundary of its own `<slot/>` — where the next layer mounts. */
+type MountedLayout = { key: string; dispose: () => void; slot: Boundary }
 
 /* The destination URL for a navigation `path`. On the server / headless there is no
    `location`, so resolve against a localhost origin; in the browser, against the real
@@ -68,6 +73,10 @@ export function router(
     /* The mounted layout chain (outermost first) + the page disposer. */
     const mountedLayouts: MountedLayout[] = []
     let disposePage: (() => void) | undefined
+    /* The root outlet boundary in `host` (`#app`) the outermost layer fills — established
+       once on the first mount (claimed from the SSR DOM when hydrating, created otherwise)
+       and reused across navigations, since `#app` itself never re-mounts. */
+    let rootBoundary: Boundary | undefined
     const patterns = Object.keys(loaders).filter((key) => key !== '*')
     const layoutKeys = Object.keys(layoutLoaders)
 
@@ -90,60 +99,94 @@ export function router(
     const resolvePage = resolver(loaders)
     const resolveLayout = resolver(layoutLoaders)
 
-    /* Tear down the page and every layout from `index` inward (innermost first), then
-       return the container the rebuild mounts into — the surviving layout's outlet, or
-       `host` when the whole chain goes. */
-    const disposeFrom = (index: number): Element => {
+    /* Tear down the page and every layout from `index` inward (innermost first). Each
+       layer's disposer stops its reactivity and clears its content from its boundary
+       (the outermost cleared range removes the inner DOM too — harmless double-clears).
+       Leaves the boundary markers in place so the rebuild fills the same boundary. */
+    const disposeFrom = (index: number): void => {
         disposePage?.()
         disposePage = undefined
         for (let depth = mountedLayouts.length - 1; depth >= index; depth -= 1) {
             mountedLayouts[depth]?.dispose()
         }
-        const base = index === 0 ? host : (mountedLayouts[index - 1] as MountedLayout).outlet
         mountedLayouts.length = index
-        return base
     }
 
-    /* Mount (or hydrate) the chain tail — layouts `[index..]` then the page — into
-       `base`, threading each layer into the previous one's outlet. Hydration brackets
-       ONE render pass across all layers so await/try block ids stay unique and aligned
-       with the SSR stream; a fresh mount needs no shared pass. */
+    /* The outlet boundary the layer at `index` fills: the root boundary for the outermost
+       layer, else the surviving parent layout's `<slot/>`. */
+    const baseBoundary = (index: number): Boundary =>
+        index === 0 ? (rootBoundary as Boundary) : (mountedLayouts[index - 1] as MountedLayout).slot
+
+    /* Build (or hydrate) the chain tail — layouts `[index..]` then the page — filling each
+       layer into the previous one's `<slot/>` boundary (the root boundary for the
+       outermost). `outlet()` records each layer's own slot in `PENDING_OUTLET` as the
+       layer builds, so the next layer knows where to mount — no DOM scan. Hydration
+       brackets ONE render pass + claim cursor across all layers so await/try block ids
+       stay unique and aligned with the SSR stream; a fresh mount needs no shared pass. */
     const buildFrom = (
-        base: Element,
         index: number,
         chainKeys: string[],
         layoutViews: Route[],
         pageView: Route | undefined,
+        pageKey: string,
         params: Record<string, string>,
         hydrating: boolean,
     ): void => {
         const run = (): void => {
-            let container = base
+            /* Establish the root boundary on the first mount — `outlet(host)` claims the
+               SSR root boundary (hydrating) or creates it (fresh), recording it in
+               `PENDING_OUTLET`. Reused across navigations thereafter. A fresh first mount
+               (no claim cursor — e.g. a non-hydratable page whose SSR shell can't be
+               adopted) discards whatever the server put in `#app` first, so the created
+               boundary is the only content. */
+            if (rootBoundary === undefined) {
+                if (RENDER.hydration === undefined) {
+                    host.textContent = ''
+                }
+                outlet(host)
+                rootBoundary = PENDING_OUTLET.current as Boundary
+            }
+            let boundary = baseBoundary(index)
             for (let depth = index; depth < layoutViews.length; depth += 1) {
                 const view = layoutViews[depth] as Route
-                const dispose = hydrating
-                    ? (view.hydrate as NonNullable<Route['hydrate']>)(container, params)
-                    : (view(container, params) ?? noop)
-                const outlet = firstOutlet(container)
-                if (outlet === undefined) {
+                PENDING_OUTLET.current = undefined
+                const { dispose } = fillBoundary(
+                    boundary.open,
+                    boundary.close,
+                    view.build,
+                    params,
+                    /* The layout's route key names its scope in the inspector's Reactive tab
+                       (no host element to read a tag from — see `scopeLabel`). */
+                    chainKeys[depth],
+                )
+                const slot = PENDING_OUTLET.current
+                if (slot === undefined) {
                     throw new Error('[abide] a layout.abide must contain a <slot/> outlet')
                 }
-                mountedLayouts.push({ key: chainKeys[depth] as string, dispose, outlet })
-                container = outlet
+                mountedLayouts.push({ key: chainKeys[depth] as string, dispose, slot })
+                boundary = slot
             }
             if (pageView === undefined) {
                 return
             }
-            disposePage = hydrating
-                ? (pageView.hydrate as NonNullable<Route['hydrate']>)(container, params)
-                : (pageView(container, params) ?? undefined)
+            disposePage = fillBoundary(
+                boundary.open,
+                boundary.close,
+                pageView.build,
+                params,
+                /* The page's route key names its scope in the inspector (see above). */
+                pageKey,
+            ).dispose
         }
         if (hydrating) {
+            const previous = RENDER.hydration
+            RENDER.hydration = { next: new Map() }
             enterRenderPass()
             try {
                 run()
             } finally {
                 exitRenderPass()
+                RENDER.hydration = previous
             }
             return
         }
@@ -329,11 +372,11 @@ export function router(
                 ) {
                     divergence += 1
                 }
-                const hydrating =
-                    first && pageView?.hydratable === true && pageView.hydrate !== undefined
+                const hydrating = first && pageView?.hydratable === true
                 first = false
-                /* The DOM mutation a navigation makes: tear the divergent chain down,
-                   clear its DOM (a fresh mount; hydration adopts in place), rebuild. */
+                /* The DOM mutation a navigation makes: tear the divergent chain down
+                   (clearing its content from its boundary) and rebuild into the same
+                   boundary (hydration adopts in place). */
                 const swap = (): void => {
                     /* Tear the outgoing page + divergent layouts down BEFORE publishing the
                        new snapshot. Publishing first would re-run the doomed leaf page's
@@ -341,13 +384,10 @@ export function router(
                        `undefined`, e.g. `Number(page.params.id)` → NaN → a bogus request)
                        while it's still mounted. Disposing first kills that scope; surviving
                        prefix layouts then update in place on publish. */
-                    const base = disposeFrom(divergence)
+                    disposeFrom(divergence)
                     const url = resolveUrl(path)
                     clientPage.value = { route: chainRoute, params, url, navigating: false }
-                    if (!hydrating) {
-                        base.textContent = ''
-                    }
-                    buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
+                    buildFrom(divergence, chainKeys, layoutViews, pageView, key, params, hydrating)
                     /* Reapply the destination entry's scroll once its DOM exists — a
                        back/forward restores its offset, a fresh nav scrolls to the `#hash`
                        anchor (now built) or the top. Runs on the initial paint too: with

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

@@ -0,0 +1,10 @@
+/* The comment-marker boundary a layout's `<slot/>` outlet lowers to — replacing the old
+   `<abide-outlet>` ELEMENT, so the next chain layer the router fills in lays out as a true
+   direct child of the slot's parent (no wrapper box breaking the layout's flex/grid/`:first-child`).
+
+   `abide:outlet` / `/abide:outlet` deliberately match `skeleton`'s `isOpenMarker`/`isCloseMarker`
+   (the `abide:` / `/abide:` convention), so a layout's own hole-scanning treats the outlet's
+   future child content as a balanced range and skips it — exactly like an `await`/`try` boundary.
+   The router fills the boundary with the next layer (see `outlet`/`fillBoundary`). */
+export const OUTLET_OPEN = 'abide:outlet'
+export const OUTLET_CLOSE = '/abide:outlet'

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

@@ -1,8 +1,7 @@
-/* The element a layout's `<slot/>` lowers to: an empty structural container the
-   router fills with the next layer of the route's layout chain (the nested layout
-   or the page). SSR emits it empty so the renderer can fold the child's html into
-   it; on the client the router mounts/hydrates the child into it and finds it by
-   tag. Shared by both compiler back-ends, the SSR chain composer, and the router so
-   they all agree on the marker. */
+/* The compile-time AST tag a layout's `<slot/>` is rewritten to (`asOutlet`). It is a
+   sentinel only — never a rendered element: both compiler back-ends lower it to an empty
+   `<!--abide:outlet-->`…`<!--/abide:outlet-->` comment boundary (`outlet` on the client,
+   the marker string in SSR) the router fills with the next chain layer. Shared by both
+   back-ends and `skeletonContext` so they all agree which node is the outlet. */
 // @documentation plumbing
 export const OUTLET_TAG = 'abide-outlet'

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

@@ -0,0 +1,8 @@
+/* The outlet boundary the most recent `outlet()` call established (a layout's `<slot/>`
+   fill point, or the router's root boundary in `#app`). The router reads it right after
+   building/claiming a layer — synchronously, so it is exactly that layer's single slot —
+   to learn where the NEXT chain layer mounts, without scanning the DOM. A layer with no
+   slot (the leaf page) leaves it whatever the router reset it to. */
+export const PENDING_OUTLET: { current: { open: Comment; close: Comment } | undefined } = {
+    current: undefined,
+}