@abide/abide 0.39.0 → 0.40.0

package/src/lib/ui/navigate.ts

@@ -1,6 +1,13 @@
 import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 
+/* Options for `navigate`. `replace` swaps the current history entry instead of pushing.
+   `keepScroll` carries the live scroll offset onto the destination so it isn't reset. */
+export type NavigateOptions = {
+    replace?: boolean
+    keepScroll?: boolean
+}
+
 /* Navigates to `path`: writes a history entry (when available) and updates the
    reactive route, which re-mounts the matching page via `router`. `replace` swaps
    the current entry instead of pushing — used when honouring a server redirect, so
@@ -9,16 +16,34 @@ import { runtimePath } from './runtime/runtimePath.ts'
    teardown the rebuild does. A push leaves the current entry behind — its scroll is
    bucketed so back restores it — and mints a fresh id. A replace destroys the current
    entry and lands fresh content (a redirect), so its saved scroll no longer applies:
-   the bucket is discarded and the id kept, so the new page restores to top/anchor. */
+   the bucket is discarded and the id kept, so the new page restores to top/anchor.
+   `keepScroll` opts the destination out of that reset — for an in-page URL swap (e.g.
+   selecting another episode on the same detail page) where a top jump is jarring: the
+   live offset is bucketed under the destination entry id, so the post-rebuild `restore`
+   reapplies it instead of scrolling to top. */
 // @documentation navigate
-export function navigate(path: string, replace = false): void {
+export function navigate(
+    path: string,
+    { replace = false, keepScroll = false }: NavigateOptions = {},
+): void {
     if (typeof history !== 'undefined') {
         if (replace) {
-            historyEntries.discard()
+            /* keepScroll buckets the live offset under the (unchanged) entry id so
+               restore reapplies it; otherwise the superseded content drops its bucket. */
+            if (keepScroll) {
+                historyEntries.save()
+            } else {
+                historyEntries.discard()
+            }
             history.replaceState({ abideEntry: historyEntries.current }, '', path)
         } else {
             historyEntries.save()
             history.pushState({ abideEntry: historyEntries.next() }, '', path)
+            /* Re-bucket the same offset under the freshly minted id so the pushed entry
+               restores to it rather than to top. */
+            if (keepScroll) {
+                historyEntries.save()
+            }
         }
     }
     runtimePath.value = path

package/src/lib/ui/renderToStream.ts

@@ -1,6 +1,7 @@
 import { resumeSeedScript } from './resumeSeedScript.ts'
 import type { ResumeEntry } from './runtime/RESUME.ts'
 import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
+import { tryEncodeResume } from './tryEncodeResume.ts'
 
 /*
 Out-of-order SSR streaming. Yields the shell first (so the browser paints
@@ -69,10 +70,15 @@ export async function* renderToStream(
         const resolved = await Promise.race(inflight.values())
         inflight.delete(resolved.id)
         enqueueNew()
-        const encoded = encodeResume(resolved.resume)
+        /* An unserializable value (e.g. a cyclic media tree) streams its rendered HTML
+           with NO seed script: both swap consumers (SSR_SWAP_SCRIPT, applyResolved) skip
+           registration when the leading child isn't a parseable script, so hydration
+           re-runs this one branch's promise — degrading to a refetch instead of aborting
+           the whole stream. */
+        const encoded = encodeStreamResume(resolved.resume, resolved.id)
         yield resumeSeedScript(resumeDelta()) +
             `<abide-resolve data-id="${resolved.id}">` +
-            `<script type="application/json">${encoded}</script>` +
+            (encoded === undefined ? '' : `<script type="application/json">${encoded}</script>`) +
             `${resolved.html}</abide-resolve>`
     }
 }
@@ -105,11 +111,13 @@ function settle(block: SsrAwait): Promise<Settled> {
     )
 }
 
-/* JSON for a `<script type="application/json">` data block: script content is raw
-   text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
-   literal `</script>` from closing the block early — quotes stay raw. Far cheaper
-   than attribute escaping (no full-string `"`/`&` passes) and JSON.parse decodes it
-   back. `applyResolved`/the inline swap script read it via `.textContent`. */
-function encodeResume(resume: ResumeEntry): string {
-    return JSON.stringify(resume).replace(/</g, '\\u003c')
+/* ref-json for a `<script type="application/json">` data block: script content is
+   raw text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
+   literal `</script>` from closing the block early — quotes stay raw, and the escape
+   survives `decodeRefJson`'s inner JSON.parse since `<` only ever appears inside JSON
+   strings. `tryEncodeResume` handles the serialize-or-refetch policy (undefined → no
+   script → the swap consumers skip registration → hydration re-runs that one promise).
+   `applyResolved`/the inline swap script store it via `.textContent`; `awaitBlock` decodes it. */
+function encodeStreamResume(resume: ResumeEntry, id: number): string | undefined {
+    return tryEncodeResume(resume, id)?.replace(/</g, '\\u003c')
 }

package/src/lib/ui/resumeSeedScript.ts

@@ -1,17 +1,27 @@
 import { safeJsonForScript } from '../shared/safeJsonForScript.ts'
 import type { ResumeEntry } from './runtime/RESUME.ts'
+import { tryEncodeResume } from './tryEncodeResume.ts'
 
 /* A self-contained `<script>` seeding the await-resume manifest with the blocking
    values rendered inline on the server, so client hydration adopts each resolved
    branch instead of re-running its promise. Empty when nothing blocking resolved.
-   The payload runs as JS (`Object.assign`), so it's encoded via `safeJsonForScript`
-   — escaping `<`, `-->`, and U+2028/U+2029 so a serialized body value can't close
-   the script early or parse as a line terminator. Shared by the buffered
-   (`createUiPageRenderer`) and streaming (`renderToStream`) paths. */
+   Each entry is ref-json-encoded to a string (decoded at read in `awaitBlock`); the
+   id→string map runs as JS (`Object.assign`), so it's wrapped in `safeJsonForScript`
+   — escaping `<`, `-->`, and U+2028/U+2029 so an encoded value can't close the script
+   early or parse as a line terminator. Shared by the buffered (`createUiPageRenderer`)
+   and streaming (`renderToStream`) paths. */
 // @documentation plumbing
 export function resumeSeedScript(resume: Record<number, ResumeEntry>): string {
-    if (Object.keys(resume).length === 0) {
+    /* ref-json (not JSON) so a value carrying cycles or shared back-references — a
+       media tree with parent↔child links — seeds instead of being dropped. `tryEncodeResume`
+       drops just an unserializable entry (the client re-runs that one branch's promise),
+       keeping every other branch seeded rather than blanking the whole page. */
+    const encoded = Object.entries(resume).flatMap(([id, entry]) => {
+        const text = tryEncodeResume(entry, id)
+        return text === undefined ? [] : [[id, text] as const]
+    })
+    if (encoded.length === 0) {
         return ''
     }
-    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${safeJsonForScript(resume)})</script>`
+    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${safeJsonForScript(Object.fromEntries(encoded))})</script>`
 }

package/src/lib/ui/router.ts

@@ -351,7 +351,7 @@ export function router(
                     /* 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)
+                        navigate(decision.path, { replace: true })
                         return
                     }
                     /* handle() blocked it / redirected off-origin / the probe failed:

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/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,7 +25,7 @@ export function localStoragePersistence(): PersistenceStore | undefined {
                 return undefined
             }
             try {
-                return JSON.parse(raw)
+                return decodeRefJson(raw)
             } catch {
                 return undefined
             }
@@ -29,7 +35,7 @@ export function localStoragePersistence(): PersistenceStore | undefined {
                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))
+                localStorage.setItem(key, encodeRefJson(snapshot))
             } catch {
                 // best-effort persistence
             }

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