@abide/abide 0.37.0 → 0.38.1

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

@@ -14,6 +14,13 @@ import { unescapeKey } from './unescapeKey.ts'
 import { walkPath } from './walkPath.ts'
 import { writeNode } from './writeNode.ts'
 
+/* `path` minus its last segment — the parent container's path, '' at the root.
+   The same string `segments.slice(0, -1).join('/')` rebuilds, by one slice. */
+function parentPathOf(path: string): string {
+    const lastSlash = path.lastIndexOf('/')
+    return lastSlash === -1 ? '' : path.slice(0, lastSlash)
+}
+
 /*
 Builds a reactive document over `initial`. Each path read for the first time
 mints a signal node; the node is the notification token, the (mutable) tree is
@@ -132,10 +139,7 @@ export function createDoc(initial: unknown): Doc {
            remove (computed post-apply, below, to resolve an array append's index). */
         const before = PATCH_BUS.active ? walkPath(tree, patch.path) : undefined
         tree = applyPatchToTree(tree, patch, segments)
-        /* parentPath is patch.path minus its last segment — the same string
-           `segments.slice(0, -1).join('/')` rebuilds, taken by one slice instead. */
-        const lastSlash = patch.path.lastIndexOf('/')
-        const parentPath = lastSlash === -1 ? '' : patch.path.slice(0, lastSlash)
+        const parentPath = parentPathOf(patch.path)
         const parentValue = walkPath(tree, parentPath).value
         const leafKey = segments[segments.length - 1] as string | undefined
         /* A structural change (add/remove, or an array element replaced by index)
@@ -194,8 +198,7 @@ export function createDoc(initial: unknown): Doc {
         before: ReturnType<typeof walkPath> | undefined,
     ): Patch | undefined {
         if (patch.op === 'add') {
-            const lastSlash = patch.path.lastIndexOf('/')
-            const parentPath = lastSlash === -1 ? '' : patch.path.slice(0, lastSlash)
+            const parentPath = parentPathOf(patch.path)
             const parent = walkPath(tree, parentPath).value
             const resolved =
                 Array.isArray(parent) && patch.path.endsWith('/-')
@@ -223,9 +226,19 @@ export function createDoc(initial: unknown): Doc {
         const node = nodeFor(path)
         const segments = path.split('/').map(unescapeKey)
         const leafKey = segments[segments.length - 1] as string
+        /* Auto-vivify missing ancestor objects so binding a nested path on a doc
+           booted shallow (e.g. `state({})`) doesn't crash, and a later `set` writes
+           into the LIVE tree (so snapshot/persist see it). Mirrors the container
+           assumption applyPatchToTree makes — except the patch path is authored, this
+           walk is compiler-emitted, so the intermediates may not exist yet. */
         let parent = tree as Record<string, unknown>
         for (const segment of segments.slice(0, -1)) {
-            parent = parent[segment] as Record<string, unknown>
+            let next = parent[segment]
+            if (next === null || typeof next !== 'object') {
+                next = {}
+                parent[segment] = next
+            }
+            parent = next as Record<string, unknown>
         }
         return {
             get: () => readNode(node) as T,

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

@@ -18,5 +18,14 @@ export function seedStreamedResolution(resolution: StreamedResolution): void {
     if ('miss' in resolution) {
         return
     }
-    activeCacheStore().entries.set(resolution.key, cacheEntryFromSnapshot(resolution))
+    /* Only seed when nothing live holds the key — or when the existing entry is itself
+       an unconsumed hydrated seed (`hydrated === true`, cleared by the first cache()
+       read). A live/settled non-hydrated entry is authoritative; clobbering it with a
+       stale snapshot would drop a fresher value (e.g. one a live fetch already wrote). */
+    const { entries } = activeCacheStore()
+    const existing = entries.get(resolution.key)
+    if (existing !== undefined && existing.hydrated !== true) {
+        return
+    }
+    entries.set(resolution.key, cacheEntryFromSnapshot(resolution))
 }

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

@@ -1,13 +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.
-*/
-export function componentWrapperTag(name: string): string {
-    return `abide-${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
-}