@abide/abide 0.44.1 → 0.46.0

package/src/lib/shared/cache.ts

@@ -12,6 +12,7 @@ import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { producerKey } from './producerKey.ts'
 import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import { REPLAYABLE_METHODS } from './REPLAYABLE_METHODS.ts'
+import { recordCacheKey } from './recordCacheKey.ts'
 import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
@@ -198,8 +199,22 @@ export function cache<Args, Return>(
         reader of the key, so one mutating it would corrupt the others. A live
         fetch hands each reader a fresh object; cloning keeps warm reads the same.
         */
-        if (!isRaw && existing?.value !== undefined) {
-            return Promise.resolve(cloneWarmValue(existing.value)) as Promise<Return>
+        if (
+            !isRaw &&
+            existing !== undefined &&
+            (existing.value !== undefined || existing.warm !== undefined)
+        ) {
+            /* A deferred seed carries a lazy materializer instead of a decoded value: decode
+               it here, on the first read that needs it (off the hydration path), and cache the
+               result onto the entry so later reads skip the decode. Drop the materializer once
+               used — its closure pins the raw body string, so keeping it alongside the decoded
+               value would double memory for exactly the large payloads deferral targets. */
+            const warmValue = existing.value !== undefined ? existing.value : existing.warm?.()
+            existing.value = warmValue
+            existing.warm = undefined
+            const warmed = Promise.resolve(cloneWarmValue(warmValue)) as Promise<Return>
+            recordCacheKey(warmed, key)
+            return warmed
         }
         const responsePromise = invokeRemote(
             store,
@@ -209,7 +224,14 @@ export function cache<Args, Return>(
             args,
             options,
         )
-        return isRaw ? responsePromise : (responsePromise.then(decodeResponse) as Promise<Return>)
+        if (isRaw) {
+            return responsePromise
+        }
+        /* Tag the decoded value promise with its key so the SSR resume path can recognise a
+           cache-backed await value and defer a large one to a `{ defer, key }` marker. */
+        const decoded = responsePromise.then(decodeResponse) as Promise<Return>
+        recordCacheKey(decoded, key)
+        return decoded
     }
     /* Non-enumerable brand; selectorMatcher and the re-wrap guard read it. */
     Object.defineProperty(read, CACHE_WRAPPED, { value: fn })
@@ -812,7 +834,7 @@ function settleRefetchFailure(store: CacheStore, entry: CacheEntry, status?: num
 }
 
 /* Folds new tags into an entry's existing set without duplicating them. */
-function mergeTags(existing: Set<string> | undefined, incoming: string | string[]): Set<string> {
+function mergeTags(existing: Set<string> | undefined, incoming: string[]): Set<string> {
     return new Set([...(existing ?? []), ...toTagSet(incoming)])
 }
 

package/src/lib/shared/cacheEntryFromSnapshot.ts

@@ -19,18 +19,38 @@ export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
         statusText: entry.statusText,
         headers,
     })
+    /* Deferred seed: decode nothing now — hand back a memoized materializer the first read
+       invokes, so hydration pays no payload decode. Eager seed: decode up front as before. */
+    const warm = entry.lazy
+        ? memoizeWarm(() => warmValueFromSnapshot(entry.status, headers, entry.body))
+        : undefined
     return {
         key: entry.key,
         promise: Promise.resolve(response),
         request: new Request(entry.url, { method: entry.method }),
         ttl: undefined,
         expiresAt: undefined,
-        value: warmValueFromSnapshot(entry.status, headers, entry.body),
+        value: entry.lazy ? undefined : warmValueFromSnapshot(entry.status, headers, entry.body),
+        warm,
         settled: true,
         hydrated: true,
     }
 }
 
+/* Wraps a warm decode so it runs at most once — the materialized value (including a
+   legitimate undefined for a non-warmable status) is cached after the first call. */
+function memoizeWarm(decode: () => unknown): () => unknown {
+    let materialized = false
+    let value: unknown
+    return () => {
+        if (!materialized) {
+            value = decode()
+            materialized = true
+        }
+        return value
+    }
+}
+
 /*
 Synchronously decodes a snapshot body so the warm entry reads without a
 microtask hop on first render. The json/text branches go through the shared

package/src/lib/shared/cacheKeyOf.ts

@@ -0,0 +1,7 @@
+import { cacheKeyStore } from './cacheKeyStore.ts'
+
+/* The store key behind a cache() read's promise, or undefined if it carries none
+   (a producer read, a raw Response read, or a non-cache promise). */
+export function cacheKeyOf(promise: Promise<unknown>): string | undefined {
+    return cacheKeyStore.get(promise)
+}

package/src/lib/shared/cacheKeyStore.ts

@@ -0,0 +1,8 @@
+/*
+WeakMap recording the cache key behind a `cache()` read's returned promise, so a
+consumer holding only the promise can recover its key. Mirrors remoteMetaStore (which
+records the synthesized Request the same way). The SSR resume path uses it to decide
+whether a `{#await cache()}` value is a large cache-backed read it can defer — shipping a
+`{ defer, key }` marker instead of the value. Collected with the promise.
+*/
+export const cacheKeyStore = new WeakMap<Promise<unknown>, string>()

package/src/lib/shared/httpErrorFor.ts

@@ -4,7 +4,7 @@ import { HttpError } from './HttpError.ts'
 
 /*
 Builds the HttpError for a non-2xx response, parsing a typed-error body
-(`{ $abideError, data }`, emitted by `error(errors.x(...))` and validation 422)
+(`{ $abideError, data }`, emitted by an `error.typed(...)` constructor and validation 422)
 onto `.kind` / `.data`. Reads a clone so the original `response.body` stays
 unread for callers that inspect it. A non-JSON or malformed body leaves
 `.kind` / `.data` undefined (a plain `error(status, text)`). Shared by the

package/src/lib/shared/recordCacheKey.ts

@@ -0,0 +1,6 @@
+import { cacheKeyStore } from './cacheKeyStore.ts'
+
+/* Tags a cache() read's returned promise with its store key (see cacheKeyStore). */
+export function recordCacheKey(promise: Promise<unknown>, key: string): void {
+    cacheKeyStore.set(promise, key)
+}

package/src/lib/shared/toTagSet.ts

@@ -1,4 +1,4 @@
-/* Normalizes a tags option (one tag or many) to a Set for O(1) membership. */
-export function toTagSet(tags: string | string[]): Set<string> {
-    return new Set(typeof tags === 'string' ? [tags] : tags)
+/* Normalizes a tags option to a Set for O(1) membership. */
+export function toTagSet(tags: string[]): Set<string> {
+    return new Set(tags)
 }

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

@@ -59,9 +59,24 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
+    /*
+    Lazy warm materializer (Tier 2 deferred seed): a memoized thunk that decodes the
+    shipped body into the warm value on first call, so a deferred snapshot pays no decode
+    at hydration — only when a read actually needs the value. `value` stays undefined until
+    then; the read gate treats an entry with `warm` set as warm without invoking it. Eager
+    snapshots set `value` and leave this undefined.
+    */
+    warm?: () => unknown
     tags?: Set<string>
     settled?: boolean
     hydrated?: boolean
+    /*
+    Marks that the SSR resume path deferred this entry's `{#await cache()}` value — shipped a
+    `{ defer, key }` marker instead of inlining it. The post-stream snapshot drain reads it to
+    ship the body as a LAZY seed (decoded on first read, not at hydration). Set server-side
+    only, on the request-scoped entry, during the stream.
+    */
+    deferred?: boolean
     refreshing?: boolean
     invalidation?: InvalidationState
 }

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

@@ -6,10 +6,10 @@ milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
 dedupe only (entry dropped once the promise settles — the mutation idiom:
 in-flight coalescing and pending() visibility, nothing retained), any other
 number = TTL.
-`tags` is one or more free-form labels grouping unrelated calls so one
-`cache.invalidate({ tags })` drops every entry sharing any of them — pass an
-array when a call belongs to multiple invalidation groups. A unique tag (e.g. a
-uuid) shared by a set of calls gives them their own private invalidation group.
+`tags` is an array of free-form labels grouping unrelated calls so one
+`cache.invalidate({ tags })` drops every entry sharing any of them — list
+multiple when a call belongs to multiple invalidation groups. A unique tag (e.g.
+a uuid) shared by a set of calls gives them their own private invalidation group.
 
 `global` opts the entry into the process-level store instead of the default
 request-scoped one (server) — so a value computed in one request is reused by
@@ -37,7 +37,7 @@ uncheckable — set `swr` only on a producer that is a pure read.
 */
 export type CacheOptions = {
     ttl?: number
-    tags?: string | string[]
+    tags?: string[]
     global?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
 }

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

@@ -14,4 +14,9 @@ export type CacheSnapshotEntry = {
     statusText: string
     headers: Array<[string, string]>
     body: string
+    /* Deferred seed (Tier 2): the client stores the body but does NOT decode it at boot —
+       the warm value is materialized lazily on the first read, off the hydration path. Set
+       by the server for a deferred `{#await cache()}` whose value ships via a `{defer,key}`
+       resume marker instead of inline, so hydration touches neither copy's decode. */
+    lazy?: boolean
 }

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

@@ -1,11 +1,11 @@
 import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
 
 /*
-A rpc's declared error set, keyed by error NAME (not status, so two errors can
-share a status). Each entry names its HTTP `status` and an optional `data`
-schema whose inferred input the error constructor requires. Passed as the rpc's
-`errors` opt; the client derives a typed `Result` union from it (see
-`RpcErrorUnion`), and the handler receives matching constructors (see
-`ErrorConstructors`).
+A rpc's error set, keyed by error NAME (not status, so two errors can share a
+status). Each entry names its HTTP `status` and an optional `data` schema whose
+inferred input the error constructor requires. Built at the type level from the
+`error.typed(...)` constructors a handler RETURNS (see `TypedError` +
+`InferredErrors` in RpcHelper); the client's `rpc.isError` narrows `.kind` /
+`.data` off it (see `RpcErrorGuard`).
 */
 export type ErrorSpec = Record<string, { status: number; data?: StandardSchemaV1 }>

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

@@ -43,6 +43,7 @@ export type RemoteFunction<
     Args,
     Return,
     Errors extends ErrorSpec = Record<never, never>,
+    Durable extends boolean = false,
 > = RemoteCallable<Args, Return> & {
     readonly method: HttpMethod
     readonly url: string
@@ -56,7 +57,10 @@ export type RemoteFunction<
        per-rpc replacement for a global guard, since the error name → data type mapping
        lives in the rpc's own spec. */
     readonly isError: RpcErrorGuard<Errors>
-    /* Present only on a durable (`outbox`) RPC's client proxy: callable for the reactive
-       list of undelivered entries, with `retry()` to drain the queue. Undefined otherwise. */
-    readonly outbox?: Outbox<Args>
-}
+} /* `outbox` presence follows the `outbox: true` opt: the mutating helper threads `Durable`
+     into the return type so a DURABLE rpc's `.outbox` is the required queue face (no optional
+     chain). A non-durable rpc keeps it optional — assignable to a durable one everywhere a
+     bare `RemoteFunction<Args, Return>` slot (cache selectors, registries) is expected, since
+     required→optional widens cleanly and no call site had to learn the `Durable` bit. */ & (Durable extends true
+        ? { readonly outbox: Outbox<Args> }
+        : { readonly outbox?: Outbox<Args> })

package/src/lib/ui/compile/UI_RUNTIME_IMPORTS.ts

@@ -35,6 +35,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'eachAsync', specifier: 'ui/dom/eachAsync', alias: '$$eachAsync' },
     { name: 'when', specifier: 'ui/dom/when', alias: '$$when' },
     { name: 'awaitBlock', specifier: 'ui/dom/awaitBlock', alias: '$$awaitBlock' },
+    { name: 'deferResume', specifier: 'ui/deferResume', alias: '$$deferResume' },
     { name: 'tryBlock', specifier: 'ui/dom/tryBlock', alias: '$$tryBlock' },
     { name: 'switchBlock', specifier: 'ui/dom/switchBlock', alias: '$$switchBlock' },
     { name: 'mountSlot', specifier: 'ui/dom/mountSlot', alias: '$$mountSlot' },

package/src/lib/ui/compile/generateBuild.ts

@@ -558,7 +558,11 @@ export function generateBuild(
         parentVar: string,
         before: string,
     ): string {
-        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)});\n`
+        /* `client:idle`/`client:visible` → the island trigger, the 6th mountChild arg. Omitted
+           (the common case) leaves the call byte-identical to before — eager hydration. */
+        const trigger =
+            node.clientTrigger !== undefined ? `, ${JSON.stringify(node.clientTrigger)}` : ''
+        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)}${trigger});\n`
     }
 
     /* An await block: pending → resolved(value) / error branches. Each branch is a

package/src/lib/ui/compile/generateSSR.ts

@@ -527,10 +527,15 @@ export function generateSSR(
            `withBindings` shadow models, so a reference to the binding reads the plain
            local rather than the (unresolved) component signal it shadows. */
         const resolved = nextVar('$av')
+        /* Keep the promise object: a cache() read tagged it with its store key, which
+           `$$deferResume` reads to defer a cache-backed value (ship a `{defer,key}` marker +
+           lazy seed) instead of inlining it — the blocking form's contract. */
+        const promiseVar = nextVar('$ap')
         let code = `const ${id} = $ctx.next++;\n`
         code += `${target}.push("<!--abide:await:" + ${id} + "-->");\n`
         code += `try {\n`
-        code += `const ${resolved} = await (${lowerExpression(node.promise)});\n`
+        code += `const ${promiseVar} = (${lowerExpression(node.promise)});\n`
+        code += `const ${resolved} = await ${promiseVar};\n`
         code += `{\n`
         code += `const ${plan.resolvedAs} = ${resolved};\n`
         code += withBindings(withShadow, plan.resolvedBindings, ssrBindingKind, () =>
@@ -540,7 +545,7 @@ export function generateSSR(
            shadow — matching the catch branch below, so a finally expression naming the
            same identifier as the `then` binding reads the component signal, not the local. */
         code += branchContent(plan.finallyChildren, target)
-        code += `$resume[${id}] = { ok: true, value: ${plan.resolvedAs} };\n`
+        code += `$resume[${id}] = $$deferResume(${promiseVar}, ${plan.resolvedAs});\n`
         code += `}\n`
         if (plan.surfaceRejection) {
             /* No catch/finally → let the rejection surface instead of an empty branch. */
@@ -564,7 +569,9 @@ export function generateSSR(
        `await` block inside the branch composes. `finally` appends after the outcome,
        matching the client's concatenated node range. Neither catch nor finally → omit
        `catch` so a rejection surfaces (renderToStream re-throws); a finally-only block
-       keeps a catch renderer that renders just finally. */
+       keeps a catch renderer that renders just finally. A cache-backed streaming value is
+       DEFERRED at settle time (renderToStream ships a `{defer,key}` marker + lazy body, the
+       client adopts the streamed branch inert) — the machinery here is unchanged. */
     function generateStreamingAwait(
         node: Extract<TemplateNode, { kind: 'await' }>,
         target: string,

package/src/lib/ui/compile/parseTemplate.ts

@@ -640,12 +640,25 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
            its children become slot content (rendered where the child puts <slot>). */
         if (UPPERCASE_START.test(tag)) {
             const slotted = selfClosing ? [] : readChildren(tag)
+            /* `client:idle` / `client:visible` are island directives (bare) — pull them out of
+               the attributes so they never round-trip as props; only the build back-end reads
+               the trigger. Any other `client:*` falls through as a prop (a prop-check error). */
+            const clientAttr = attrs.find(
+                (attr) =>
+                    attr.kind === 'static' &&
+                    (attr.name === 'client:idle' || attr.name === 'client:visible'),
+            )
+            const clientTrigger =
+                clientAttr?.kind === 'static'
+                    ? (clientAttr.name.slice('client:'.length) as 'idle' | 'visible')
+                    : undefined
             return {
                 kind: 'component',
                 name: tag,
                 loc: baseOffset + tagStart,
-                props: toProps(attrs),
+                props: toProps(attrs.filter((attr) => attr !== clientAttr)),
                 children: slotted,
+                clientTrigger,
             }
         }
         /* `{...expr}` spreads onto a component (its props) or a native element (its

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -80,6 +80,11 @@ export type TemplateNode =
              the prop name's source offset — the anchor for an excess-prop diagnostic. */
           props: { name: string; code: string; loc?: number; nameLoc?: number; spread?: boolean }[]
           children: TemplateNode[]
+          /* `client:idle` / `client:visible` on the tag → hydrate this child as an island
+             (server markup kept, build deferred to the trigger). Extracted from the attributes
+             so it never becomes a prop; the build back-end passes it to `mountChild`, SSR and
+             the prop check ignore it (an island renders fully on the server). */
+          clientTrigger?: 'idle' | 'visible'
       }
     | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
     /* A branch of a `<template switch>` (`match` set) or `<template if>` chain. Inside an

package/src/lib/ui/createScope.ts

@@ -5,6 +5,7 @@ import { linked } from './linked.ts'
 import { persist as persistDoc } from './persist.ts'
 import { createDoc } from './runtime/createDoc.ts'
 import { liveScopes } from './runtime/liveScopes.ts'
+import type { Cell } from './runtime/types/Cell.ts'
 import type { Doc } from './runtime/types/Doc.ts'
 import { state } from './state.ts'
 import { sync } from './sync.ts'
@@ -49,7 +50,11 @@ export function createScope(
     let persistence: PersistHandle | undefined
     let unsync: (() => void) | undefined
 
-    const self: Scope = {
+    /* `cell` is not on the public `Scope` type — it is the compiler-only leaf the
+       cell-hoisting lowering targets (`const _cell0 = $$scope().cell("path")`, see
+       `hoistCells`). It stays on the runtime object but off the documented surface,
+       so authors reach data through `read`/`replace`/`derive`, not a raw cell handle. */
+    const self: Scope & { cell: <T>(path: string) => Cell<T> } = {
         id,
         label,
         parent,
@@ -79,7 +84,7 @@ export function createScope(
         },
         root: () => (parent === undefined ? self : parent.root()),
         /* Reference store — no tracking, so a lookup never subscribes; reactivity comes
-           from what is shared (a cell/scope), not from the share. */
+           from what is shared (a scope, whose doc is reactive), not from the share. */
         share: (key, value) => {
             shared.set(key, value)
         },
@@ -109,8 +114,10 @@ export function createScope(
                 owned[index]?.()
             }
             owned.length = 0
-            for (const created of children) {
-                created.dispose()
+            /* Children reverse too (last created first), so a later child that captured an
+               earlier sibling tears down before the sibling it depends on — LIFO like `owned`. */
+            for (let index = children.length - 1; index >= 0; index -= 1) {
+                children[index]?.dispose()
             }
             children.length = 0
             shared.clear()

package/src/lib/ui/deferResume.ts

@@ -0,0 +1,36 @@
+import { activeCacheStore } from '../shared/activeCacheStore.ts'
+import { cacheKeyOf } from '../shared/cacheKeyOf.ts'
+import { DEFER_MIN_ARRAY_LENGTH } from '../shared/DEFER_MIN_ARRAY_LENGTH.ts'
+import { snapshotShippable } from '../shared/snapshotShippable.ts'
+import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
+
+/*
+The resume-manifest entry for a blocking `{#await expr then value}`. When the awaited value
+is a shippable cache-backed read, DEFER it: flag the store entry so its SSR snapshot seeds
+lazily (the body is decoded on first read, not at hydration) and return a `{ defer, key }`
+marker in place of the value. Hydration then adopts the server branch inert and decodes
+neither copy — the blocking form's contract: "render it on the server, keep the page, refetch
+only when I read or invalidate it." A non-cache value (a plain promise, a computation) or a
+cache read whose entry can't ship inlines its value as before. Server-only in practice — the
+client codegen never calls it. */
+// @documentation plumbing
+export function deferResume(promise: unknown, value: unknown): ResumeEntry | DeferMarker {
+    const isPromise =
+        promise !== null && typeof (promise as { then?: unknown })?.then === 'function'
+    const key = isPromise ? cacheKeyOf(promise as Promise<unknown>) : undefined
+    if (key === undefined) {
+        return { ok: true, value }
+    }
+    const entry = activeCacheStore().entries.get(key)
+    if (entry === undefined || !snapshotShippable(entry)) {
+        return { ok: true, value }
+    }
+    /* Only defer a genuinely large grid: below the threshold, inline the value and hydrate
+       eagerly — the block is interactive from the first frame, no inert phase, no wake. This is
+       what keeps a modest searchable list live instead of frozen-until-idle (the reported gap). */
+    if (!Array.isArray(value) || value.length < DEFER_MIN_ARRAY_LENGTH) {
+        return { ok: true, value }
+    }
+    entry.deferred = true
+    return { defer: true, key }
+}

package/src/lib/ui/dom/appendText.ts

@@ -36,21 +36,36 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
     }
     const hydration = RENDER.hydration
     if (hydration !== undefined) {
-        const node = claimChild(hydration, parent) as unknown as Text
+        const claimed = claimChild(hydration, parent)
         const value = String(read())
+        /* A value that first rendered empty produced NO server text node, so the cursor
+           points at the following node (an element/comment) or past the end (null) — not a
+           text node to claim. Bind to a Text node either way: claim the merged SSR node when
+           one is here, else synthesize an empty one at the cursor and leave the claimed node
+           for the next consumer (a following element hole, a sibling binding, or nothing).
+           Without this the bind effect below derefs a null/element `node`. A text node is
+           detected by `splitText` (not `nodeType`), so the test mini-dom is covered too. */
+        const isText = claimed !== null && typeof (claimed as Text).splitText === 'function'
+        const node = (
+            isText ? claimed : parent.insertBefore(document.createTextNode(''), claimed)
+        ) as Text
         /* Peel this binding's text off the merged SSR node. A non-final binding in a
            run (`splitAlways`) splits even when it consumes the whole node, leaving an
            empty node for the next binding — otherwise an interpolation that renders to
            empty string (or whose followers do) has no node and the next claim grabs the
            wrong sibling. The final binding keeps `<` so it doesn't leave a stray node a
-           following element would claim. */
+           following element would claim. A synthesized node is already this binding's own,
+           so it never splits. */
         if (
-            node !== null &&
+            isText &&
             (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
         ) {
             node.splitText(value.length)
         }
-        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        /* Advance past the claimed text node; for a synthesized node leave the cursor on the
+           still-unclaimed `claimed` node it was inserted before (an element/comment, or null
+           at the end). */
+        hydration.next.set(parent, isText ? node.nextSibling : claimed)
         effect(() => {
             node.data = String(read())
         })