@abide/abide 0.38.0 → 0.38.1

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

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

@@ -2,28 +2,27 @@ import { PATCH_BUS } from './PATCH_BUS.ts'
 import type { Doc } from './types/Doc.ts'
 
 /*
-Runs a component `build` and returns its disposer alongside the component's own
-`model` document — the serializable `state` doc, needed so a hot swap can carry
-its value across (see `hotReplace`). The model is found, not threaded: a component
-seeds its `model` first (the desugared `const model = doc({})` + its init patches
-run before any child mounts or control-flow blocks), so the FIRST patch announced
-on the bus during the build names it. A component with no `state` mints no model
-and emits nothing first — `model` is then `undefined` and there is nothing to
-preserve. Used only on the hot path; the subscription is torn down with the build.
+Runs a component `build` and returns its result (the mount handle / disposer)
+alongside the component's own `model` document — the serializable `state` doc,
+needed so a hot swap can carry its value across (see `hotReplace`). The model is
+found, not threaded: a component seeds its `model` first (the desugared
+`const model = doc({})` + its init patches run before any child mounts or
+control-flow blocks), so the FIRST patch announced on the bus during the build names
+it. A component with no `state` mints no model and emits nothing first — `model` is
+then `undefined` and there is nothing to preserve. Used only on the hot path; the
+subscription is torn down with the build.
 */
-export function captureModelDoc(build: () => () => void): {
-    dispose: () => void
+export function captureModelDoc<T>(build: () => T): {
+    value: T
     model: Doc | undefined
 } {
     let model: Doc | undefined
     const unsubscribe = PATCH_BUS.subscribe((event) => {
         model ??= event.doc
     })
-    let dispose: () => void = () => undefined
     try {
-        dispose = build()
+        return { value: build(), model }
     } finally {
         unsubscribe()
     }
-    return { dispose, model }
 }

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

@@ -1,3 +1,4 @@
+import { fillRange } from '../dom/fillRange.ts'
 import { captureModelDoc } from './captureModelDoc.ts'
 import { hotInstances } from './hotInstances.ts'
 import { seedModelDoc } from './seedModelDoc.ts'
@@ -5,14 +6,15 @@ import type { UiComponent } from './types/UiComponent.ts'
 
 /*
 Swaps every live instance of an edited component to its new factory. Per instance:
-snapshot its model, dispose the current scope and its DOM (the mount disposer clears
-the host), re-run `next` into the same host with the same props, then re-seed the
-fresh model from the snapshot — so the user's in-progress `state` survives the edit
-(state above the boundary already survives: props are thunks re-reading the parent's
-live signals). The hot module calls this on load with its freshly compiled `next`.
-Returns whether it swapped at least one instance: false (the edited component has
-none mounted — e.g. a router-mounted page, or a hidden branch) tells the caller to
-fall back to a full reload, since nothing on screen would update.
+snapshot its model, dispose the current scope and clear its DOM range (the disposer
+leaves the `start`/`end` markers in place), re-fill the SAME range with the new
+module's `build` and the same props, then re-seed the fresh model from the snapshot —
+so the user's in-progress `state` survives the edit (state above the boundary already
+survives: props are thunks re-reading the parent's live signals). The hot module
+calls this on load with its freshly compiled `next`. Returns whether it swapped at
+least one instance: false (the edited component has none mounted — e.g. a
+router-mounted page, or a hidden branch) tells the caller to fall back to a full
+reload, since nothing on screen would update.
 */
 export function hotReplace(moduleId: string, next: UiComponent): boolean {
     const set = hotInstances.get(moduleId)
@@ -23,8 +25,10 @@ export function hotReplace(moduleId: string, next: UiComponent): boolean {
         const saved = instance.model?.snapshot()
         instance.dispose()
         instance.factory = next
-        const { dispose, model } = captureModelDoc(() => next(instance.host, instance.props))
-        instance.dispose = dispose
+        const { value: handle, model } = captureModelDoc(() =>
+            fillRange(instance.start, instance.end, next.build, instance.props, instance.label),
+        )
+        instance.dispose = handle.dispose
         instance.model = model
         if (saved !== undefined && model !== undefined) {
             seedModelDoc(model, saved)

package/src/lib/ui/runtime/types/HotInstance.ts

@@ -2,15 +2,19 @@ import type { Doc } from './Doc.ts'
 import type { UiComponent } from './UiComponent.ts'
 
 /*
-A live component instance the hot-reload registry tracks: its wrapper host, the
-factory that built it, the props (thunks re-read on a swap so the parent's live
-state still flows through), the disposer for its current scope + DOM, and its own
-`model` document (`undefined` when the component has no `state`) — snapshotted
-before a swap and re-seeded after, so the user's in-progress state survives the
-edit. A swap mutates `factory`/`dispose`/`model` in place (see `hotReplace`).
+A live component instance the hot-reload registry tracks: the `start`/`end` markers
+bounding its DOM range (the wrapper-free mount, see `mountRange`), its `label` (the
+scope name), the factory that built it, the props (thunks re-read on a swap so the
+parent's live state still flows through), the disposer for its current scope + DOM,
+and its own `model` document (`undefined` when the component has no `state`) —
+snapshotted before a swap and re-seeded after, so the user's in-progress state
+survives the edit. A swap re-fills the SAME range and mutates `factory`/`dispose`/
+`model` in place (see `hotReplace`).
 */
 export type HotInstance = {
-    host: Element
+    start: Comment
+    end: Comment
+    label: string | undefined
     factory: UiComponent
     props: Parameters<UiComponent>[1]
     dispose: () => void

package/src/lib/ui/runtime/types/Route.ts

@@ -1,8 +1,9 @@
-/* A routable page: mounts into a host (optionally with props) and may return a
-   disposer the router calls when navigating away. A compiled `.abide` default
-   export also carries `hydrate` (adopt SSR in place) and `hydratable` (false when
-   the page has an `await` block), which the router uses for the initial render. */
+/* A routable page/layout. Callable to mount directly into a host (the direct-mount
+   API), but the router instead uses `build` — the bare client build — to fill the
+   layer into its outlet boundary as a marker range (no `<abide-outlet>` wrapper; see
+   `fillBoundary`/`outlet`). `hydratable` (false when the page has an `await` block)
+   tells the router whether the first paint adopts the SSR DOM in place. */
 export type Route = ((host: Element, props?: unknown) => (() => void) | undefined) & {
-    hydrate?: (host: Element, props?: unknown) => () => void
+    build: (host: Node, props?: unknown) => void
     hydratable?: boolean
 }

package/src/lib/ui/runtime/types/UiComponent.ts

@@ -9,6 +9,11 @@ page/route registries carry — abide-ui's compiled-component shape.
 export type UiComponent = ((host: Element, props?: UiProps) => () => void) & {
     render: (props?: UiProps) => SsrRender
     hydrate?: (host: Element, props?: UiProps) => () => void
+    /* The bare client build (`(host, props) => void`) — appends the component's nodes
+       to `host`. A nested child mounts it into a marker range (`mountRange`/`mountChild`)
+       instead of the wrapped `mount`, and `hotReplace` re-fills a range with the new
+       module's `build` on edit. */
+    build: (host: Node, props?: UiProps) => void
     hydratable?: boolean
     /* Stable module id (project-relative source path) stamped by `compileModule`,
        keying the component in the hot-reload registry — see `mountChild`. */

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

@@ -1,15 +0,0 @@
-/*
-The element tag a component instance mounts into: always `abide-<name>` lowercased. The
-`abide-` prefix makes every wrapper a valid custom element (contains a hyphen) — never
-void, no content model — so it holds the component's own markup untouched and hydrates
-cleanly, regardless of whether the name collides with an HTML element (`Button`, `Input`).
-Emitted with `display:contents` (see the back-ends) so the wrapper stays out of layout: a
-pure mount host whose real root lays out as a direct child of the parent, keeping the
-component invisible to `grid`/`subgrid`/`flex`. Both back-ends call this so the SSR string
-and the client build agree on the wrapper.
-*/
-import { COMPONENT_WRAPPER_PREFIX } from '../COMPONENT_WRAPPER_PREFIX.ts'
-
-export function componentWrapperTag(name: string): string {
-    return `${COMPONENT_WRAPPER_PREFIX}${name.toLowerCase()}`
-}

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

@@ -1,22 +0,0 @@
-import { OUTLET_TAG } from './OUTLET_TAG.ts'
-
-/*
-The first `<abide-outlet>` in `root`'s subtree, in document order — the position
-the router fills with the next layer of a route's layout chain. A depth-first walk
-over `children` rather than `querySelector`: the router runs against real DOM and
-the test mini-DOM alike, and only the former has `querySelector`. Tag comparison is
-case-insensitive (the real DOM uppercases `tagName`, the mini-DOM keeps it as
-created). Returns undefined when the layout declares no `<slot/>`.
-*/
-export function firstOutlet(root: Element): Element | undefined {
-    for (const child of root.children) {
-        if (child.tagName.toLowerCase() === OUTLET_TAG) {
-            return child
-        }
-        const nested = firstOutlet(child)
-        if (nested !== undefined) {
-            return nested
-        }
-    }
-    return undefined
-}