@abide/abide 0.38.1 → 0.40.0

package/src/lib/ui/router.ts

@@ -224,8 +224,10 @@ export function router(
             return
         }
         const target = event.target as Element
+        /* `closest?.` is undefined when the target is a non-Element (text node, document)
+           that has no `closest`; `== null` catches both that and a genuine no-match null. */
         const link = target.closest?.('a[href]') as HTMLAnchorElement | null
-        if (link === null) {
+        if (link == null) {
             return
         }
         /* Defer to the browser for links it should own: a new-tab target, a
@@ -341,76 +343,104 @@ export function router(
                 resolvePage(key),
                 Promise.all(chainKeys.map((layoutKey) => resolveLayout(layoutKey))),
                 verdict,
-            ]).then(([pageView, resolvedLayouts, decision]) => {
-                if (token !== sequence || disposed) {
-                    return
-                }
-                /* handle() redirected: go where it pointed, replacing the blocked
+            ])
+                .then(([pageView, resolvedLayouts, decision]) => {
+                    if (token !== sequence || disposed) {
+                        return
+                    }
+                    /* handle() redirected: go where it pointed, replacing the blocked
                    URL so back doesn't trap on it. The router re-probes the target. */
-                if (decision.kind === 'redirect') {
-                    navigate(decision.path, true)
-                    return
-                }
-                /* handle() blocked it / redirected off-origin / the probe failed:
+                    if (decision.kind === 'redirect') {
+                        navigate(decision.path, { replace: true })
+                        return
+                    }
+                    /* handle() blocked it / redirected off-origin / the probe failed:
                    let the browser load the server's real response. */
-                if (decision.kind === 'reload') {
-                    if (typeof location !== 'undefined') {
-                        location.href = decision.url
+                    if (decision.kind === 'reload') {
+                        if (typeof location !== 'undefined') {
+                            location.href = decision.url
+                        }
+                        return
                     }
-                    return
-                }
-                const layoutViews = resolvedLayouts.filter(
-                    (view): view is Route => view !== undefined,
-                )
-                /* The shared prefix of layouts (same route key at the same depth) stays
+                    const layoutViews = resolvedLayouts.filter(
+                        (view): view is Route => view !== undefined,
+                    )
+                    /* The shared prefix of layouts (same route key at the same depth) stays
                    mounted; the first divergence and everything inward is rebuilt. */
-                let divergence = 0
-                while (
-                    divergence < mountedLayouts.length &&
-                    divergence < chainKeys.length &&
-                    mountedLayouts[divergence]?.key === chainKeys[divergence]
-                ) {
-                    divergence += 1
-                }
-                const hydrating = first && pageView?.hydratable === true
-                first = false
-                /* The DOM mutation a navigation makes: tear the divergent chain down
+                    let divergence = 0
+                    while (
+                        divergence < mountedLayouts.length &&
+                        divergence < chainKeys.length &&
+                        mountedLayouts[divergence]?.key === chainKeys[divergence]
+                    ) {
+                        divergence += 1
+                    }
+                    const hydrating = first && pageView?.hydratable === true
+                    first = false
+                    /* 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
+                    const swap = (): void => {
+                        /* `startViewTransition` runs this callback in a later frame, so a newer
+                           navigation may have superseded this one since the token guard above —
+                           re-check before mutating, or a stale swap clobbers the newer page. */
+                        if (token !== sequence || disposed) {
+                            return
+                        }
+                        /* Tear the outgoing page + divergent layouts down BEFORE publishing the
                        new snapshot. Publishing first would re-run the doomed leaf page's
                        computeds against the new route's params (a missing `[id]` reads back
                        `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. */
-                    disposeFrom(divergence)
-                    const url = resolveUrl(path)
-                    clientPage.value = { route: chainRoute, params, url, navigating: false }
-                    buildFrom(divergence, chainKeys, layoutViews, pageView, key, params, hydrating)
-                    /* Reapply the destination entry's scroll once its DOM exists — a
+                        disposeFrom(divergence)
+                        const url = resolveUrl(path)
+                        clientPage.value = { route: chainRoute, params, url, navigating: false }
+                        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
                        `scrollRestoration='manual'` the browser does NOT restore a reload's
                        offset, so first paint recovers it from the persisted `history.state`
                        (a fresh load with no persisted offset falls through to hash/top). */
-                    historyEntries.restore(url.hash)
-                }
-                /* Wrap the swap in a View Transition where the browser supports it, so
+                        historyEntries.restore(url.hash)
+                    }
+                    /* Wrap the swap in a View Transition where the browser supports it, so
                    the page change cross-fades (and shared `view-transition-name` elements
                    morph) — the synchronous swap is exactly the mutation the API snapshots
                    around. Skipped while hydrating: the first paint adopts SSR DOM in place,
                    not animate. CSS owns opting out (e.g. prefers-reduced-motion). */
-                if (
-                    !hydrating &&
-                    typeof document !== 'undefined' &&
-                    'startViewTransition' in document
-                ) {
-                    document.startViewTransition(swap)
-                } else {
-                    swap()
-                }
-            })
+                    if (
+                        !hydrating &&
+                        typeof document !== 'undefined' &&
+                        'startViewTransition' in document
+                    ) {
+                        document.startViewTransition(swap)
+                    } else {
+                        swap()
+                    }
+                })
+                .catch(() => {
+                    /* A page/layout chunk import (or the probe) rejected — offline, a hashed
+                   chunk filename rotated by a deploy, or a transient asset 5xx. Without
+                   this the navigating:true latched above never clears (a bound spinner
+                   spins forever) and the rejection surfaces as an unhandledrejection.
+                   Fall back to a full browser load so the server serves the target. */
+                    if (token !== sequence || disposed) {
+                        return
+                    }
+                    if (typeof location !== 'undefined') {
+                        location.href = resolveUrl(path).href
+                    }
+                })
         })
     })
 

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

@@ -1,16 +1,23 @@
 /* The await-resume manifest: the resolved value (or error) of each streamed
-   `await` block, keyed by its boundary id. The SSR stream serializes each value
+   `await` block, keyed by its boundary id. The SSR stream serializes each entry
    alongside its fragment; the client registers it (via `applyResolved` or the
    inline swap script), and hydration reads it so an `await` block adopts the
    resolved branch with the real value instead of re-running the promise.
 
-   Backed by `globalThis.__abideResume` so the inline stream-swap script (vanilla,
-   running during the stream before the bundle loads) and the framework share one
-   store: whoever runs first creates it, the other adopts the same reference. */
+   Each value is the ref-json-encoded ResumeEntry STRING, not the decoded object:
+   the entry is encoded with the ref-json codec (so a resolved value carrying cycles
+   or shared back-references survives, where JSON would drop it) and decoded lazily
+   at the read site in `awaitBlock`. Storing the raw string keeps the inline
+   stream-swap script — vanilla, running before the bundle and the codec load — able
+   to register an entry without the decoder.
+
+   Backed by `globalThis.__abideResume` so the inline stream-swap script and the
+   framework share one store: whoever runs first creates it, the other adopts the
+   same reference. */
 export type ResumeEntry = { ok: true; value: unknown } | { ok: false; error: unknown }
 
-const globalScope = globalThis as { __abideResume?: Record<number, ResumeEntry> }
+const globalScope = globalThis as { __abideResume?: Record<number, string> }
 globalScope.__abideResume ??= {}
 
 // @documentation plumbing
-export const RESUME: Record<number, ResumeEntry> = globalScope.__abideResume
+export const RESUME: Record<number, string> = globalScope.__abideResume

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

@@ -49,6 +49,11 @@ export function createEffectNode(fn: () => EffectResult): () => void {
     const dispose = () => {
         runCleanup()
         unlinkDeps(node)
+        /* Clearing compute makes runNode a no-op: an effect disposed mid-flush (by an
+           earlier effect in the same batch) is still in flushEffects' snapshot array
+           after pendingEffects.delete, so it would otherwise re-run its body and
+           re-link into the graph — a disposed effect resurrected. */
+        node.compute = undefined
         REACTIVE_CONTEXT.pendingEffects.delete(node)
     }
     if (OWNER.current !== undefined) {

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

@@ -1,12 +1,18 @@
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import type { PersistenceStore } from '../types/PersistenceStore.ts'
 
 /*
-The default `persist` backend: `localStorage` keyed by the persistence key, with
-JSON as the wire form (which also clones, so a stored snapshot can't alias the
-live tree). Returns `undefined` where there is no `localStorage` — the server, or
-a browser with storage disabled — which `persist` reads as "stay inert". A corrupt
-or unparseable entry loads as `undefined` rather than throwing, so one bad write
-can't wedge boot.
+The default `persist` backend: `localStorage` keyed by the persistence key, using
+the ref-json codec as the wire form (which also clones on decode, so a stored
+snapshot can't alias the live tree). ref-json over plain JSON because a doc
+snapshot can hold the types JSON silently coerces (Date), drops (undefined) or
+throws on (bigint, cycles, shared references) — a throw here is a swallowed save,
+i.e. silent persistence loss. Returns `undefined` where there is no `localStorage`
+— the server, or a browser with storage disabled — which `persist` reads as "stay
+inert". A corrupt or unreadable entry (including one written by an older JSON
+build) loads as `undefined` rather than throwing, so one bad write can't wedge
+boot; the next save rewrites it in ref-json form.
 */
 export function localStoragePersistence(): PersistenceStore | undefined {
     if (typeof localStorage === 'undefined') {
@@ -19,13 +25,20 @@ export function localStoragePersistence(): PersistenceStore | undefined {
                 return undefined
             }
             try {
-                return JSON.parse(raw)
+                return decodeRefJson(raw)
             } catch {
                 return 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, encodeRefJson(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/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/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,7 +8,12 @@ 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`)

package/src/lib/ui/socketChannel.ts

@@ -1,6 +1,8 @@
 import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
 import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
 import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
+import { decodeRefJson } from '../shared/decodeRefJson.ts'
+import { encodeRefJson } from '../shared/encodeRefJson.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
 import type { SocketChannel } from '../shared/types/SocketChannel.ts'
 import { withBase } from '../shared/withBase.ts'
@@ -55,7 +57,8 @@ export function getSocketChannel(): SocketChannel {
     }
 
     function send(frame: SocketClientFrame): void {
-        const message = JSON.stringify(frame)
+        // ref-json frame so a published message graph with cycles/shared refs survives the wire.
+        const message = encodeRefJson(frame)
         if (ws && ws.readyState === WebSocket.OPEN) {
             ws.send(message)
             return
@@ -90,7 +93,7 @@ export function getSocketChannel(): SocketChannel {
         ws.addEventListener('message', (event) => {
             let frame: SocketServerFrame
             try {
-                frame = JSON.parse(event.data) as SocketServerFrame
+                frame = decodeRefJson(event.data) as SocketServerFrame
             } catch {
                 return
             }

package/src/lib/ui/tryEncodeResume.ts

@@ -0,0 +1,20 @@
+import { encodeRefJson } from '../shared/encodeRefJson.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
+
+/* ref-json-encode an await-resume entry, or `undefined` if it can't be serialized.
+   encodeRefJson is total (cycles become back-references, functions fold to undefined),
+   but a pathological throw must not blank the surrounding seed/stream — drop just this
+   entry and warn, so the client re-runs that one branch's promise while every other
+   branch stays seeded. Shared by the streaming (`renderToStream`) and buffered/seed
+   (`resumeSeedScript`) paths so the serialize-or-refetch policy lives in one place. */
+export function tryEncodeResume(entry: ResumeEntry, id: number | string): string | undefined {
+    try {
+        return encodeRefJson(entry)
+    } catch (cause) {
+        console.warn(
+            `[abide] resume for await ${id} is not serializable; client will refetch it`,
+            cause,
+        )
+        return undefined
+    }
+}

package/src/lib/ui/types/Scope.ts

@@ -9,9 +9,9 @@ import type { SyncTransport } from './SyncTransport.ts'
 A lexical scope: the unit that owns a region's reactive data, its lifetime, and
 the capabilities applied to it. Its data surface MIRRORS `Doc` (read/replace/add/
 remove/cell/derive/apply/snapshot) so the compiler can target a scope as a
-component's data binding directly. It nests (`child`/`root`), and carries the
-capability surface as methods so a scope is a passable value:
-`<Child parentScope={scope} />`.
+component's data binding directly. It nests (`child`/`root`), passes values
+down the tree as context (`share`/`shared`), and carries the capability surface as
+methods so a scope is a passable value: `<Child parentScope={scope} />`.
 
 Capabilities route where the scope's changes go: `record()` to an undo journal,
 `persist()` to durable storage, `broadcast()` to peers — declared once, then
@@ -46,6 +46,12 @@ export type Scope = {
     /* tree */
     child: (initial?: unknown) => Scope
     root: () => Scope
+    /* context — values shared DOWN the tree (not in the reactive doc, which doesn't
+       inherit): `share` puts a named value on this scope; `shared` reads the closest
+       ancestor (self included) that has the key, undefined if none. The value is held
+       by reference, so reactive context = share a `cell`/scope, not a plain object. */
+    share: (key: string, value: unknown) => void
+    shared: <T>(key: string) => T | undefined
     /* capabilities — enable where the scope's changes go */
     record: (options?: { limit?: number }) => void
     persist: (key?: string) => void

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