@abide/abide 0.44.1 → 0.46.0

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

@@ -11,6 +11,12 @@ drains the captured one — so an effect that dirties further effects re-queues
 for the next pass rather than mutating the array mid-iteration; loops until the
 graph settles. The swap reuses the drained array as the next spare, so a steady
 flush allocates nothing.
+
+Raises `batchDepth` for the whole drain so a write inside an effect body queues
+rather than re-entering the flush: `trigger` gates its flush on `batchDepth === 0`,
+and re-entry would run a just-dirtied effect nested — ahead of effects already in
+this pass and on a JS stack that grows with the write chain. Suppressed, the
+newly-dirtied effect falls to the `do…while` and runs in queue (creation) order.
 */
 export function flushEffects(): void {
     /* Empty-queue fast path allocates nothing — only the length check, matching the
@@ -20,6 +26,18 @@ export function flushEffects(): void {
     if (REACTIVE_CONTEXT.pendingEffects.length === 0) {
         return
     }
+    /* Always entered at depth 0 (trigger/batch-exit gate on it); the bump makes the
+       drain non-reentrant, restored in `finally` so a throwing effect body can't strand
+       the graph batched. */
+    REACTIVE_CONTEXT.batchDepth += 1
+    try {
+        drain()
+    } finally {
+        REACTIVE_CONTEXT.batchDepth -= 1
+    }
+}
+
+function drain(): void {
     let spare: ReactiveNode[] = []
     do {
         const batch = REACTIVE_CONTEXT.pendingEffects

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

@@ -0,0 +1,40 @@
+import { OWNER } from './OWNER.ts'
+
+/*
+A monotonic generation an async block checks before a late continuation touches the DOM. It
+answers one question — "is the work I started still the current work?" — and is bumped on the
+two events that both invalidate in-flight work: a reactive `renew()` (a re-run supersedes the
+prior promise/drain) and the enclosing OWNER's teardown (a settle after disposal must be
+DROPPED, not run `place`/`insertBefore` on a now-detached anchor → NotFoundError). `onTeardown`
+releases extra resources at teardown (e.g. an async iterator's `return()`).
+
+Extracted from the byte-identical guard hand-rolled in `awaitBlock` and `eachAsync`. The
+teardown half is the load-bearing one: a re-run bump alone leaves a promise/drain that settles
+AFTER disposal to still pass the liveness check and crash on the dead anchor — the bug both
+sites independently had to grow.
+*/
+export function generationGuard(onTeardown?: () => void): {
+    renew: () => number
+    token: () => number
+    live: (captured: number) => boolean
+} {
+    let generation = 0
+    /* The teardown bump is load-bearing: without it a promise/drain settling after the owner
+       disposes still passes `live(captured)` and touches a detached anchor. */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => {
+            generation += 1
+            onTeardown?.()
+        })
+    }
+    return {
+        /* Supersede any in-flight generation; call at the start of each (re-)run. Returns the
+           new token so a runner can capture it in the same statement. */
+        renew: () => (generation += 1),
+        /* The live generation to capture before an await and compare after — for when the
+           renew and the capture happen in different functions (as in awaitBlock's render). */
+        token: () => generation,
+        /* Whether `captured` is still the live generation — safe to touch the DOM. */
+        live: (captured: number) => captured === generation,
+    }
+}

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

@@ -34,7 +34,15 @@ export function runNode(node: ReactiveNode): unknown {
            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. */
+           members' `status` is bumped — so walking it live is safe.
+
+           This bumps status directly, bypassing `mark` — it neither enqueues effects nor
+           propagates CHECK onward, yet nothing is missed: this recompute only happens
+           while settling a subscriber that was itself reached from the originating
+           write's `mark` propagation, which already CHECK-marked (and so enqueued) every
+           effect in this cone on their CLEAN→CHECK edge. So every subscriber here is
+           already CHECK/queued; the direct write only UPGRADES it CHECK→DIRTY so its own
+           settle recomputes instead of memoising back to CLEAN. */
         if (!Object.is(node.value, next)) {
             node.value = next
             let link = node.subsHead

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

@@ -0,0 +1,28 @@
+import { whenIdle } from './whenIdle.ts'
+import { whenVisible } from './whenVisible.ts'
+
+/*
+Schedule a one-shot wake for a deferred (inert-hydrated) region by trigger — the single
+trigger-selection both the await block and component islands share. `'visible'` (and `'auto'`)
+wake on scroll-in when the DOM can be measured (a real IntersectionObserver) and the region has
+an element to observe: a below-the-fold region decodes only when reached, one never scrolled to
+costs nothing. Otherwise — `'idle'`, no observer, or an empty branch — wake on idle: off the
+critical boot path but soon, so the region never lingers inert. Returns a cancel to drop a
+pending wake on teardown.
+
+`'auto'` is the await block's policy (defer decides, position decides trigger); `'idle'` /
+`'visible'` are an island's explicit `client:` choice.
+*/
+export function scheduleWake(
+    trigger: 'idle' | 'visible' | 'auto',
+    element: Element | undefined,
+    wake: () => void,
+): () => void {
+    const hasObserver =
+        typeof (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver ===
+        'function'
+    if (trigger !== 'idle' && hasObserver && element !== undefined) {
+        return whenVisible(element, wake)
+    }
+    return whenIdle(wake)
+}

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

@@ -1,4 +1,4 @@
-import type { ResumeEntry } from '../RESUME.ts'
+import type { DeferMarker, 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
@@ -18,10 +18,11 @@ export type SsrAwait = {
 /* The result of a component's server `render()`: the pending-shell HTML, the
    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. */
+   by boundary id, seeded into the manifest so hydration adopts them without a refetch. A
+   deferred (cache-backed) blocking value is a `DeferMarker` in place of the value. */
 export type SsrRender = {
     html: string
     state: unknown
     awaits: SsrAwait[]
-    resume: Record<number, ResumeEntry>
+    resume: Record<number, ResumeEntry | DeferMarker>
 }

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

@@ -0,0 +1,21 @@
+/*
+Run `callback` once, in the first idle gap after the current frame — the client-side
+trigger a deferred (inert-hydrated) region uses to wake itself: boot stays cheap (no
+decode, no effects), then the region belatedly comes alive off the critical path,
+before a human can act on it. `requestIdleCallback` when the runtime has it (a `timeout`
+guarantees it fires even under sustained load); a `setTimeout(0)` macrotask otherwise
+(Safari < 16.4, test DOMs), which still clears the boot frame. Returns a cancel to drop
+the pending wake on teardown, so a region torn down before idle does no late work.
+*/
+export function whenIdle(callback: () => void, timeoutMs = 200): () => void {
+    const globalWithIdle = globalThis as {
+        requestIdleCallback?: (cb: () => void, options?: { timeout: number }) => number
+        cancelIdleCallback?: (handle: number) => void
+    }
+    if (typeof globalWithIdle.requestIdleCallback === 'function') {
+        const handle = globalWithIdle.requestIdleCallback(callback, { timeout: timeoutMs })
+        return () => globalWithIdle.cancelIdleCallback?.(handle)
+    }
+    const handle = setTimeout(callback, 0)
+    return () => clearTimeout(handle)
+}

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

@@ -0,0 +1,105 @@
+/*
+Run `callback` once, the first time `element` enters (or is already within) the viewport —
+the trigger a below-the-fold deferred region uses to wake only when scrolled into view, so a
+grid the user never reaches costs nothing. A synchronous fire where the observer is absent
+(SSR/test DOMs), which keeps the region from staying inert where visibility can't be measured.
+Returns a cancel to drop a pending watch on teardown. Fires at most once.
+
+ONE shared IntersectionObserver backs every watcher (a grid of N islands registers N elements
+on one observer, not N observers), and wakes are BATCHED off the observer callback into a
+frame-flush capped at `WAKE_BUDGET_PER_FRAME`: a wake rebuilds DOM, so running it inside the
+observer callback would force a synchronous layout that shifts other elements across the
+margin and re-fires the observer — a cascade that locks the main thread at grid scale. Queuing
+to a rAF and spending a bounded number per frame breaks that loop and keeps each frame cheap;
+overflow spills to the next frame, so even a whole grid scrolled into view at once stays
+responsive.
+*/
+// A screenful of margin so a region is live by the time it's actually read.
+const ROOT_MARGIN = '256px'
+// Max wakes (DOM rebuilds) per frame — the ceiling that keeps a flush off the critical path.
+const WAKE_BUDGET_PER_FRAME = 40
+
+let sharedObserver: IntersectionObserver | undefined
+/* The IntersectionObserver constructor `sharedObserver` was built from. Identity only changes
+   when a test swaps `globalThis.IntersectionObserver`; on a change the observer + its pending
+   registrations are rebuilt, so module state doesn't leak across tests. */
+let sharedObserverCtor: unknown
+const wakeByElement = new Map<Element, () => void>()
+const readyWakes = new Set<() => void>()
+let flushScheduled = false
+
+/* Next animation frame (browser) or macrotask (test/SSR) — the flush cadence. */
+function scheduleFrame(run: () => void): void {
+    const globalWithRaf = globalThis as { requestAnimationFrame?: (cb: () => void) => number }
+    if (typeof globalWithRaf.requestAnimationFrame === 'function') {
+        globalWithRaf.requestAnimationFrame(run)
+    } else {
+        setTimeout(run, 0)
+    }
+}
+
+/* Spend up to the per-frame budget of queued wakes; reschedule if any remain. */
+function flushWakes(): void {
+    flushScheduled = false
+    let processed = 0
+    for (const wake of readyWakes) {
+        readyWakes.delete(wake)
+        wake()
+        processed += 1
+        if (processed >= WAKE_BUDGET_PER_FRAME) {
+            break
+        }
+    }
+    scheduleFlush()
+}
+
+function scheduleFlush(): void {
+    if (flushScheduled || readyWakes.size === 0) {
+        return
+    }
+    flushScheduled = true
+    scheduleFrame(flushWakes)
+}
+
+/* Queue every newly-intersecting element's wake — never run it here (see the cascade note). */
+function onIntersections(entries: IntersectionObserverEntry[]): void {
+    for (const entry of entries) {
+        if (entry.isIntersecting) {
+            const wake = wakeByElement.get(entry.target)
+            if (wake !== undefined) {
+                wakeByElement.delete(entry.target)
+                sharedObserver?.unobserve(entry.target)
+                readyWakes.add(wake)
+            }
+        }
+    }
+    scheduleFlush()
+}
+
+function observerFor(observerConstructor: typeof IntersectionObserver): IntersectionObserver {
+    if (sharedObserver === undefined || sharedObserverCtor !== observerConstructor) {
+        wakeByElement.clear()
+        readyWakes.clear()
+        sharedObserver = new observerConstructor(onIntersections, { rootMargin: ROOT_MARGIN })
+        sharedObserverCtor = observerConstructor
+    }
+    return sharedObserver
+}
+
+export function whenVisible(element: Element, callback: () => void): () => void {
+    const observerConstructor = (
+        globalThis as { IntersectionObserver?: typeof IntersectionObserver }
+    ).IntersectionObserver
+    if (typeof observerConstructor !== 'function') {
+        callback()
+        return () => undefined
+    }
+    const observer = observerFor(observerConstructor)
+    wakeByElement.set(element, callback)
+    observer.observe(element)
+    return () => {
+        wakeByElement.delete(element)
+        readyWakes.delete(callback)
+        observer.unobserve(element)
+    }
+}

package/src/lib/ui/scope.ts

@@ -3,17 +3,15 @@ import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
 import type { Scope } from './types/Scope.ts'
 
 /*
-Resolves a lexical scope. `scope()` returns the current one — established per
-lexical level by the compiler, so it reads "where you are" with no handle. Outside
-any scope (boot, a script) it mints a detached root once and reuses it. `scope('/')`
-returns the root of the current tree (the app-global scope). The returned value is
-passable: hand it to a child or a helper and it can read/extend/undo that scope.
+Resolves the current lexical scope — established per lexical level by the compiler,
+so it reads "where you are" with no handle. Outside any scope (boot, a script) it
+mints a detached root once and reuses it. The returned value is passable: hand it to
+a child or a helper and it can read/extend/undo that scope (walk up via `.root()`).
 */
 // @documentation reactive-state
-export function scope(address?: string): Scope {
+export function scope(): Scope {
     if (!CURRENT_SCOPE.current) {
         CURRENT_SCOPE.current = createScope()
     }
-    const current = CURRENT_SCOPE.current
-    return address === '/' ? current.root() : current
+    return CURRENT_SCOPE.current
 }

package/src/lib/ui/tryEncodeResume.ts

@@ -1,5 +1,5 @@
 import { encodeRefJson } from '../shared/encodeRefJson.ts'
-import type { ResumeEntry } from './runtime/RESUME.ts'
+import type { DeferMarker, 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),
@@ -7,7 +7,10 @@ import type { ResumeEntry } from './runtime/RESUME.ts'
    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 {
+export function tryEncodeResume(
+    entry: ResumeEntry | DeferMarker,
+    id: number | string,
+): string | undefined {
     try {
         return encodeRefJson(entry)
     } catch (cause) {

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

@@ -1,7 +1,6 @@
 import type { computed } from '../computed.ts'
 import type { effect } from '../effect.ts'
 import type { linked } from '../linked.ts'
-import type { Cell } from '../runtime/types/Cell.ts'
 import type { Patch } from '../runtime/types/Patch.ts'
 import type { state } from '../state.ts'
 import type { SyncTransport } from './SyncTransport.ts'
@@ -9,7 +8,7 @@ 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
+remove/derive/apply/snapshot) so the compiler can target a scope as a
 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} />`.
@@ -33,7 +32,6 @@ export type Scope = {
     add: (path: string, value: unknown) => void
     remove: (path: string) => void
     apply: (patch: Patch) => void
-    cell: <T>(path: string) => Cell<T>
     derive: <T>(path: string, compute: () => T) => () => T
     snapshot: () => unknown
     /* The reactive primitives — namespaced under the scope, but AMBIENT-bound, not
@@ -64,7 +62,8 @@ export type 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. */
+       by reference, so reactive context = share a scope (its doc is reactive), not a
+       plain object snapshot. */
     share: (key: string, value: unknown) => void
     shared: <T>(key: string) => T | undefined
     /* capabilities — enable where the scope's changes go */

package/src/lib/server/rpc/buildErrorConstructors.ts

@@ -1,19 +0,0 @@
-import type { ErrorConstructors } from '../../shared/types/ErrorConstructors.ts'
-import type { ErrorSpec } from '../../shared/types/ErrorSpec.ts'
-
-/*
-Turns a rpc's declared `ErrorSpec` into the constructor object handed to the
-handler (`(args, { errors })`). Each constructor stamps its name + status onto an
-`ErrorDescriptor` carrying the call's `data`, which `error()` serializes as the
-`{ $abideError, data }` body. Receiver-agnostic on data: a nullary error ignores
-the (absent) argument.
-*/
-export function buildErrorConstructors<Spec extends ErrorSpec>(
-    spec: Spec,
-): ErrorConstructors<Spec> {
-    const entries = Object.entries(spec).map(([name, { status }]) => [
-        name,
-        (data: unknown) => ({ $abideError: name, status, data }),
-    ])
-    return Object.fromEntries(entries) as ErrorConstructors<Spec>
-}

package/src/lib/shared/types/ErrorConstructors.ts

@@ -1,17 +0,0 @@
-import type { ErrorDescriptor } from './ErrorDescriptor.ts'
-import type { ErrorSpec } from './ErrorSpec.ts'
-import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
-
-/*
-The constructors handed to the handler via its second arg (`(args, { errors })`),
-derived from the rpc's `ErrorSpec`. An entry with a `data` schema makes its
-constructor require that schema's inferred input; an entry without one is nullary.
-Each returns a typed `ErrorDescriptor` to pass to `error()`.
-*/
-export type ErrorConstructors<Spec extends ErrorSpec> = {
-    [Name in keyof Spec & string]: Spec[Name]['data'] extends StandardSchemaV1
-        ? (
-              data: StandardSchemaV1.InferInput<Spec[Name]['data']>,
-          ) => ErrorDescriptor<Name, StandardSchemaV1.InferInput<Spec[Name]['data']>>
-        : () => ErrorDescriptor<Name, undefined>
-}

package/src/lib/shared/types/ErrorDescriptor.ts

@@ -1,10 +0,0 @@
-/*
-What a rpc error constructor returns: a plain descriptor (NOT a Response), so it
-flows through the single `error()` funnel — `return error(errors.invalidCoupon({…}))`.
-`error()` reads `status` off it and serializes `{ $abideError: name, data }` as the body.
-*/
-export type ErrorDescriptor<Name extends string = string, Data = unknown> = {
-    readonly $abideError: Name
-    readonly status: number
-    readonly data: Data
-}