@abide/abide 0.39.0 → 0.40.1

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/runtime/readNode.ts

@@ -1,16 +1,17 @@
-import { runNode } from './runNode.ts'
 import { track } from './track.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
+import { updateIfNecessary } from './updateIfNecessary.ts'
 
 /*
-Reads a node's current value and subscribes the running observer to it. A dirty
-computed recomputes first (lazy pull); a signal returns its stored value
-directly. Tracking happens after recompute so the reader links to the computed
-itself, not its transitive deps.
+Reads a node's current value and subscribes the running observer to it. A computed
+settles first (the lazy pull — `updateIfNecessary` refreshes only the deps that
+changed, recomputing if any did); a signal has no compute and returns its stored
+value directly. Tracking happens after the settle so the reader links to the
+computed itself, not its transitive deps.
 */
 export function readNode(node: ReactiveNode): unknown {
-    if (node.compute !== undefined && node.dirty) {
-        runNode(node)
+    if (node.compute !== undefined) {
+        updateIfNecessary(node)
     }
     track(node)
     return node.value

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

@@ -1,5 +1,6 @@
 import { abortNode } from './abortNode.ts'
 import { endTracking } from './endTracking.ts'
+import { NODE_STATE } from './NODE_STATE.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
 import { reactiveAbortState } from './reactiveAbortState.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
@@ -26,8 +27,23 @@ export function runNode(node: ReactiveNode): unknown {
     const previous = REACTIVE_CONTEXT.observer
     REACTIVE_CONTEXT.observer = node
     try {
-        node.value = node.compute?.()
-        node.dirty = false
+        const next = node.compute?.()
+        /* Value memoisation: only a computed whose result actually changed marks its
+           subscribers DIRTY, so the in-progress check walk recomputes them. An
+           Object.is-equal recompute leaves them at CHECK — they settle back to CLEAN
+           on read without re-running, never waking downstream. An effect has no value
+           worth comparing and no subscribers, so this is a no-op for it (its body ran
+           inside compute above). The subscriber list isn't re-linked here — only its
+           members' `status` is bumped — so walking it live is safe. */
+        if (!Object.is(node.value, next)) {
+            node.value = next
+            let link = node.subsHead
+            while (link !== undefined) {
+                link.sub.status = NODE_STATE.DIRTY
+                link = link.nextSub
+            }
+        }
+        node.status = NODE_STATE.CLEAN
         return node.value
     } finally {
         REACTIVE_CONTEXT.observer = previous

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

@@ -1,17 +1,28 @@
 import { OWNER } from './OWNER.ts'
+import { untrack } from './untrack.ts'
 
 /*
 Runs `build` under a fresh ownership scope so every effect and listener created
 inside is collected, and returns a disposer that tears them all down in reverse
 order (children before parents). Save/restore of the previous owner makes scopes
 nest — a list row's scope sits inside its component's scope.
+
+The build runs UNTRACKED. A detached subtree is built synchronously, and when that
+build happens inside a swap effect (a control-flow block re-running `each`/`when`/
+`switch`/`await`) its top-level reads would otherwise subscribe THAT effect, so any
+in-content state change would re-run the block and rebuild the whole subtree. The
+content's own interpolations still track normally — each wraps its read in its own
+effect, which re-installs itself as the observer. Untracking here is the framework's
+invariant (a build never subscribes its builder) stated once, so no control-flow
+block has to remember it; it's a harmless no-op for top-level builds (mount/hydrate),
+where there is no surrounding observer to leak into.
 */
 export function scope(build: () => void): () => void {
     const previous = OWNER.current
     const disposers: Array<() => void> = []
     OWNER.current = disposers
     try {
-        build()
+        untrack(build)
     } finally {
         OWNER.current = previous
     }

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

@@ -1,43 +1,59 @@
 import { flushEffects } from './flushEffects.ts'
+import { NODE_STATE } from './NODE_STATE.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
 /*
-Invalidates the observer cone of a just-written node: effect observers are
-queued, computed observers are marked dirty and recursed into (their value may
-now differ, so their own observers must learn of it). Recompute is lazy — a
-computed recomputes on next read — so this pass only invalidates and collects.
-
-The subscriber list is walked live: invalidate runs no compute and no effect, so
-nothing re-subscribes (the only mutators of a subscriber list, `track` and
-`runNode`, run inside compute execution, which only `flushEffects` reaches — after
-this pass). The re-subscribe hazard belongs to the flush, where `flushEffects`
-defends with its own snapshot. `nextSub` is read before recursing, so the walk
-holds no reference a downstream pass could invalidate.
+Raises `node` to at least `status` and propagates the news up its subscriber cone.
+An effect crossing out of CLEAN is queued (whether it became CHECK or DIRTY — the
+flush decides whether it really runs). A computed crossing out of CLEAN propagates
+CHECK to *its* subscribers, so the whole cone learns a dependency *might* have
+changed; it does so exactly once (a later CHECK→DIRTY upgrade re-notifies nobody —
+its subscribers are already CHECK). No compute runs here, so no subscriber list is
+re-linked mid-walk (`track`/`runNode` run inside compute, which only the flush
+reaches). `nextSub` is read before recursing so the walk holds no edge a deeper
+pass could detach.
 */
-function invalidate(node: ReactiveNode): void {
+function mark(node: ReactiveNode, status: number): void {
+    if (node.status >= status) {
+        return
+    }
+    const wasClean = node.status === NODE_STATE.CLEAN
+    node.status = status
+    if (node.isEffect) {
+        if (wasClean) {
+            REACTIVE_CONTEXT.pendingEffects.add(node)
+        }
+        return
+    }
+    /* A computed propagates CHECK to its subscribers only on its first move out of
+       CLEAN — they are already CHECK on any later upgrade, so re-walking is wasted. */
+    if (!wasClean) {
+        return
+    }
     let link = node.subsHead
     while (link !== undefined) {
-        const observer = link.sub
         const next = link.nextSub
-        if (observer.isEffect) {
-            REACTIVE_CONTEXT.pendingEffects.add(observer)
-        } else if (!observer.dirty) {
-            observer.dirty = true
-            invalidate(observer)
-        }
+        mark(link.sub, NODE_STATE.CHECK)
         link = next
     }
 }
 
 /*
-Propagates a change forward from a just-written node. Invalidation collects the
-whole cone first; the queued effects flush once, at the outermost trigger (or,
-inside a batch, when the batch owner exits) — never mid-propagation, so an effect
-never runs against a half-invalidated graph.
+Propagates a change forward from a just-written signal: its direct subscribers read
+a value that actually changed, so they are DIRTY; the rest of their cone is CHECK
+(a transitive dependency *may* have changed — `updateIfNecessary` will verify on
+read). Recompute is lazy. The queued effects flush once, at the outermost trigger
+(or, inside a batch, when the batch owner flushes) — never mid-propagation, so an
+effect never runs against a half-marked graph.
 */
 export function trigger(node: ReactiveNode): void {
-    invalidate(node)
+    let link = node.subsHead
+    while (link !== undefined) {
+        const next = link.nextSub
+        mark(link.sub, NODE_STATE.DIRTY)
+        link = next
+    }
     if (REACTIVE_CONTEXT.batchDepth === 0) {
         flushEffects()
     }

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

@@ -20,6 +20,9 @@ export type ReactiveNode = {
     depsTail: ReactiveLink | undefined
     subsHead: ReactiveLink | undefined
     subsTail: ReactiveLink | undefined
-    dirty: boolean
+    /* The node's settle-state for push-pull propagation: CLEAN / CHECK / DIRTY (see
+       NODE_STATE). A signal is always CLEAN (no compute); a computed is born DIRTY and
+       cycles CLEAN→CHECK/DIRTY→CLEAN as deps change and reads settle it. */
+    status: number
     isEffect: boolean
 }

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

@@ -0,0 +1,40 @@
+import { NODE_STATE } from './NODE_STATE.ts'
+import { runNode } from './runNode.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Settles a node so its value is current before it is read (or, for an effect, before
+it runs at flush). CLEAN: nothing to do. CHECK: a transitive dependency *might* have
+changed — refresh each direct dependency in turn; refreshing one that truly changed
+marks this node DIRTY (`runNode` does the marking), so stop the moment that happens.
+DIRTY (set directly by a write, or by the check walk): recompute.
+
+A CHECK node whose dependencies all recompute to equal values ends CLEAN without
+recomputing — the value memoisation that stops an unchanged computed from waking its
+readers. Refreshing deps top-down *before* a recompute reads them is what keeps the
+pull glitch-free: a reader never observes a stale intermediate, because by the time
+it recomputes, every dependency it reads has already settled this pass.
+*/
+export function updateIfNecessary(node: ReactiveNode): void {
+    if (node.status === NODE_STATE.CLEAN) {
+        return
+    }
+    if (node.status === NODE_STATE.CHECK) {
+        let link = node.depsHead
+        while (link !== undefined) {
+            updateIfNecessary(link.dep)
+            /* A dep recomputed to a changed value and marked us DIRTY — no need to
+               check the rest, we already know we must recompute. */
+            if (node.status === NODE_STATE.DIRTY) {
+                break
+            }
+            link = link.nextDep
+        }
+    }
+    if (node.status === NODE_STATE.DIRTY) {
+        runNode(node)
+    } else {
+        /* CHECK with no changed dependency — the cached value still holds. */
+        node.status = NODE_STATE.CLEAN
+    }
+}

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