@abide/abide 0.38.0 → 0.39.0

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

@@ -25,7 +25,14 @@ export function localStoragePersistence(): PersistenceStore | undefined {
             }
         },
         save: (key, snapshot) => {
-            localStorage.setItem(key, JSON.stringify(snapshot))
+            /* Swallow a failed write (QuotaExceededError, storage disabled mid-session) —
+               it fires from a debounced flush / pagehide handler with no caller to catch it,
+               and a dropped persist must not crash the app. */
+            try {
+                localStorage.setItem(key, JSON.stringify(snapshot))
+            } catch {
+                // best-effort persistence
+            }
         },
         remove: (key) => {
             localStorage.removeItem(key)

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

@@ -15,11 +15,16 @@ export function toTeardown(result: EffectResult): Teardown | undefined {
     }
     if (result instanceof Promise) {
         return () => {
-            result.then((teardown) => {
-                if (typeof teardown === 'function') {
-                    teardown()
-                }
-            })
+            /* Swallow a rejection: an async body that rejected (e.g. an aborted RPC) must
+               not surface as an unhandled rejection when the teardown runs at dispose. */
+            result.then(
+                (teardown) => {
+                    if (typeof teardown === 'function') {
+                        teardown()
+                    }
+                },
+                () => undefined,
+            )
         }
     }
     return undefined

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

@@ -0,0 +1,8 @@
+/* The per-request SSR render context, threaded through a layout chain and every
+   child component a page inlines. `next` is the block-id counter: each `await`/`try`
+   block draws from it in depth-first document order — the SAME order the client
+   allocates ids during its synchronous hydration walk, so the streamed fragments and
+   the `RESUME` manifest line up. Request-local (not a module global) because SSR
+   render is async — a blocking `await` yields, and a shared global counter would
+   interleave across concurrent requests. */
+export type RenderContext = { next: number }

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

@@ -1,22 +1,27 @@
-/* One pending await block captured during SSR: its boundary id, the promise to
-   await, and the string-renderers for the resolved value / error. `blocking` (a
-   `then` on the `await` tag) makes `renderToStream` settle it BEFORE the first flush,
-   splicing the resolved branch into its empty boundary; absent → streamed after.
-   `catch` is absent when the block has no catch branch — a rejection then surfaces
-   to the stream/error path instead of rendering an empty branch. */
+import type { ResumeEntry } from '../RESUME.ts'
+
+/* One STREAMING await block captured during SSR (no `then` on the `await` tag): its
+   boundary id, the promise to await, and the async string-renderers for the resolved
+   value / error. `renderToStream` flushes each resolved fragment out of order. The
+   renderers are async so a nested `await` block inside the branch composes. `catch`
+   is absent when the block has no catch branch — a rejection then surfaces to the
+   stream/error path instead of rendering an empty branch. (Blocking awaits — a `then`
+   on the tag — never land here: they render inline during the async render pass and
+   seed `SsrRender.resume`.) */
 export type SsrAwait = {
     id: number
-    blocking?: boolean
     promise: () => unknown
-    then: (value: unknown) => string
-    catch?: (error: unknown) => string
+    then: (value: unknown) => Promise<string>
+    catch?: (error: unknown) => Promise<string>
 }
 
 /* The result of a component's server `render()`: the pending-shell HTML, the
-   serializable document snapshot for client resume, and the await blocks to
-   stream. */
+   serializable document snapshot for client resume, the STREAMING await blocks to
+   flush out of order, and `resume` — the inline-rendered BLOCKING await values keyed
+   by boundary id, seeded into the manifest so hydration adopts them without a refetch. */
 export type SsrRender = {
     html: string
     state: unknown
     awaits: SsrAwait[]
+    resume: Record<number, ResumeEntry>
 }

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

@@ -1,3 +1,4 @@
+import type { RenderContext } from './RenderContext.ts'
 import type { SsrRender } from './SsrRender.ts'
 import type { UiProps } from './UiProps.ts'
 
@@ -7,8 +8,18 @@ for SSR and the hydration hooks. This is the shape `compileModule` emits and the
 page/route registries carry — abide-ui's compiled-component shape.
 */
 export type UiComponent = ((host: Element, props?: UiProps) => () => void) & {
-    render: (props?: UiProps) => SsrRender
+    /* `ctx` is the request-local block-id counter, threaded so a child's ids share the
+       page's depth-first numbering; omitted at the top level (a fresh counter defaults
+       in). Returns a Promise when the component has an inline `await` (a blocking `{#await
+       … then}` block or a child render); otherwise renders synchronously. Callers `await`
+       it either way (awaiting a sync value just returns it). */
+    render: (props?: UiProps, ctx?: RenderContext) => SsrRender | Promise<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/compile/escapeHtml.ts

@@ -1,15 +0,0 @@
-/*
-HTML-escapes a compile-time-constant string — a static attribute value or static
-text — the same five characters the runtime `$esc` handles. Shared by the SSR
-generator and the static-clone skeleton generator so server markup and the client
-clone template can't diverge on escaping. Static text reaches here already
-entity-decoded (see parseTemplate), so escaping round-trips it through the HTML
-parser to the same plain text the client would build directly.
-*/
-export function escapeHtml(value: string): string {
-    return value.replace(
-        /[&<>"']/g,
-        (char) =>
-            ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char,
-    )
-}

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