@abide/abide 0.48.0 → 0.50.0

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

@@ -1,5 +1,5 @@
+import type { NamedAsyncIterable } from './NamedAsyncIterable.ts'
 import type { RpcOptions } from './RpcOptions.ts'
-import type { Subscribable } from './Subscribable.ts'
 
 /*
 Call signature shared by RemoteFunction and RawRemoteFunction. The base
@@ -10,24 +10,25 @@ optional-arg signature lets call sites write `fn()` instead of
 stays callable while `Args` is still generic (cache() invokes producers
 before `Args` resolves). FormData is the multipart upload escape hatch —
 see RemoteFunction. The trailing `Opts` differs by variant: the smart bare
-call (RemoteFunction) carries cache/stream options (SmartReadOptions), while
-`.raw` (RawRemoteFunction) carries per-call transport options (RpcOptions:
+call (RemoteFunction) takes no second argument at all (`Opts = never` — all
+cache/stream policy lives on the rpc definition per ADR-0020), while `.raw`
+(RawRemoteFunction) carries per-call transport options (RpcOptions:
 signal/keepalive/priority/cache/headers). The server ignores either, so the
 callable stays isomorphic.
 
 A streaming `Resolved` (an `AsyncIterable<Frame>`, branded by jsonl()/sse()) makes
-the bare call return a `Subscribable<Frame>` synchronously — the iterable IS the
+the bare call return a `NamedAsyncIterable<Frame>` synchronously — the iterable IS the
 value, consumed by `for await` or `state(fn(args))`, no `.stream()`. Every other
 `Resolved` stays `Promise<Resolved>`. `await`-ing a streaming call is a compile
-error (a Subscribable is not awaitable), which replaces the old runtime guard.
+error (a NamedAsyncIterable is not awaitable), which replaces the old runtime guard.
 */
 /* `[Resolved] extends [never]` first: a handler that only ever returns error() resolves to
    `never`, and `never extends AsyncIterable` is vacuously true — without this guard its call
-   would mistype as a Subscribable. A real streaming rpc's `Resolved` is `AsyncIterable<Frame>`. */
+   would mistype as a NamedAsyncIterable. A real streaming rpc's `Resolved` is `AsyncIterable<Frame>`. */
 type CallResult<Resolved> = [Resolved] extends [never]
     ? Promise<Resolved>
     : Resolved extends AsyncIterable<infer Frame>
-      ? Subscribable<Frame>
+      ? NamedAsyncIterable<Frame>
       : Promise<Resolved>
 
 export type RemoteCallable<Args, Resolved, Opts = RpcOptions> = ((

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

@@ -1,12 +1,12 @@
+import type { CachePolicy } from './CachePolicy.ts'
 import type { ClientFlags } from './ClientFlags.ts'
 import type { ErrorSpec } from './ErrorSpec.ts'
 import type { HttpMethod } from './HttpMethod.ts'
-import type { Outbox } from './Outbox.ts'
 import type { RawRemoteFunction } from './RawRemoteFunction.ts'
 import type { RemoteCallable } from './RemoteCallable.ts'
 import type { RpcError } from './RpcError.ts'
 import type { RpcErrorGuard } from './RpcErrorGuard.ts'
-import type { SmartReadOptions } from './SmartReadOptions.ts'
+import type { StreamPolicy } from './StreamPolicy.ts'
 
 /*
 Remote function reference produced by GET/POST/... inside an `$rpc/**`
@@ -21,7 +21,7 @@ method, same url, same args, no decode. Pass `fn.raw` to cache() to
 memoise raw Responses against the same cache key as `fn` (both share one
 stored entry — the decode just happens on the way out for callers of
 `fn`). A streaming handler (jsonl()/sse()) makes the bare call return a
-`Subscribable<Frame>` directly (the iterable IS the value) — consume it with
+`NamedAsyncIterable<Frame>` directly (the iterable IS the value) — consume it with
 `for await (… of fn(args))` or `state(fn(args))`; there is no `.stream()`, and
 `await`-ing a streaming call is a compile error. For sustained broadcast /
 pub-sub use the `abide/server/socket` primitive — HTTP rpc isn't the place for
@@ -44,23 +44,29 @@ export type RemoteFunction<
     Args,
     Return,
     Errors extends ErrorSpec = Record<never, never>,
-    Durable extends boolean = false,
-> = RemoteCallable<Args, Return, SmartReadOptions> & {
+> = RemoteCallable<Args, Return, never> & {
     readonly method: HttpMethod
     readonly url: string
     readonly clients: ClientFlags
     readonly crossOrigin?: boolean
+    /* Endpoint cache/stream policy declared on the rpc definition (ADR-0020), stamped
+       here so the smart read (readThrough) reads it as the bottom policy layer. Ships to
+       the client too — it governs client cache behaviour and is behaviour, not secrets
+       (`shared` is a client no-op). Absent on a plainly-defined rpc (method defaults only). */
+    readonly cache?: CachePolicy<Args>
+    readonly stream?: StreamPolicy
     readonly raw: RawRemoteFunction<Args>
     fetch(request: Request): Promise<Response>
     /* Type-guard a caught error against this rpc's declared `errors` (plus the framework
-       `'validation'` / `'queued'`): narrows `.kind` and, for a known kind, `.data` — the
-       per-rpc replacement for a global guard, since the error name → data type mapping
-       lives in the rpc's own spec. */
+       `'validation'`): narrows `.kind` and, for a known kind, `.data` — the 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>
     /* Pre-bound selector sugar: `fn.pending(args?)` ≡ `pending(fn, args?)`, and likewise for
        refreshing / refresh / peek — the rpc is the leading selector, bound in. The argument is
        this rpc's typed `Args` (the by-args refinement); tags / cross-cutting selection stay on
-       the globals. The bare call `fn(args, opts)` IS the cached read (was `fn.cache`), and
+       the globals. The bare call `fn(args)` IS the cached read (was `fn.cache`) — all cache
+       policy lives on the definition, so there is no second options argument, and
        `refresh(args?)` refetches keeping the stale value visible (was `invalidate`, which
        dropped). `peek(args?)` reads the retained value synchronously (a streaming rpc peeks its
        latest frame). `patch` is fetch-only, so it is omitted for a streaming rpc (a stream isn't
@@ -93,9 +99,4 @@ export type RemoteFunction<
         : {
               patch(args: Args | undefined, updater: (current: Return) => Return): void
               patch(updater: (current: Return) => Return): void
-          }) /* `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/shared/types/ResolvedCells.ts

@@ -0,0 +1,11 @@
+/*
+The per-request list of async-cell values that RESOLVED during an SSR render, each keyed by the
+cell's serialization-stable render-path id (`${scope.id}:${index}`). `createAsyncCell` pushes an
+entry when its seed settles server-side; the page renderer stamps them into `__SSR__.cells`
+(ref-json-encoded) so the client hydrates the cell WARM — reading the value instead of re-running
+the seed (no refetch, no pending flash). The sibling of `PendingAsyncCells` (the barrier's
+in-flight list); this one holds settled VALUES, read at render-return rather than awaited.
+*/
+export type ResolvedCells = {
+    entries: { key: string; value: unknown }[]
+}

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

@@ -0,0 +1,15 @@
+/*
+The build-time success-body descriptor for an rpc, derived from the handler's return type by the
+warm server program (ADR-0030). Mirrors `RpcHelper`'s `SuccessBody<R>` projection: the handler's
+`Awaited<ReturnType>` union has its `TypedError` branches dropped, and each success
+`TypedResponse<Body>` contributes its `Body`. `type` is that body rendered as a TS type string
+(the union of the surviving branches). For a streaming endpoint (`jsonl()`/`sse()` →
+`TypedResponse<AsyncIterable<Frame>>`) `streaming` is true and `type` is the per-FRAME type — the
+AsyncIterable element — so a consumer describes one streamed item rather than the iterable itself.
+The query fails open to undefined (no handler/body resolvable), matching every other server-program
+query.
+*/
+export type ReturnBody = {
+    type: string
+    streaming: boolean
+}

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

@@ -0,0 +1,23 @@
+import type { ErrorJsonSchemas } from './ErrorJsonSchemas.ts'
+import type { InputCoercion } from './InputCoercion.ts'
+import type { OutputWirePlan } from './OutputWirePlan.ts'
+
+/*
+The build-time facts the warm rpc server program resolves for one `$rpc/**` handler, gathered into
+a single named payload that `prepareRpcModule` destructures (each rewrite direction picks the fields
+it needs). Replaces a positional argument list where ordering was load-bearing — a new build stamp
+is now one field on this shape rather than a new positional slot every caller must thread. Every
+field is optional: an absent field means the warm program resolved no verdict (no program built, an
+unresolvable node), and the rewrite falls open to its char-scan / today's behaviour exactly as
+before. `streaming` overrides the char-scan streaming verdict; the rest are stamped as server opts
+(`coercion`→`coerce`, `inputSchema`→`inputJsonSchema`, `outputSchema`→`outputJsonSchema`,
+`errorSchemas`→`errorJsonSchemas`) or the client opt (`outputWirePlan`).
+*/
+export type RpcBuildStamps = {
+    streaming?: boolean
+    coercion?: InputCoercion
+    inputSchema?: Record<string, unknown>
+    outputSchema?: Record<string, unknown>
+    errorSchemas?: ErrorJsonSchemas
+    outputWirePlan?: OutputWirePlan
+}

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

@@ -1,6 +1,5 @@
 import type { HttpError } from '../HttpError.ts'
 import type { ErrorSpec } from './ErrorSpec.ts'
-import type { OutboxEntry } from './OutboxEntry.ts'
 import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
 import type { ValidationErrorData } from './ValidationErrorData.ts'
 
@@ -16,9 +15,9 @@ type DeclaredErrorData<
 /*
 A rpc's `isError` guard — branch a caught error on a kind THIS rpc knows, with the
 data type narrowed from the rpc's own `errors` spec. `rpc.isError(err, 'outOfStock')`
-narrows `.data` to that error's payload; the framework-reserved `'validation'` /
-`'queued'` to their fixed shapes; any other string narrows `.kind` only (`.data`
-stays `unknown` — it belongs to a different rpc, whose type isn't in scope here).
+narrows `.data` to that error's payload; the framework-reserved `'validation'` to its
+fixed shape; any other string narrows `.kind` only (`.data` stays `unknown` — it
+belongs to a different rpc, whose type isn't in scope here).
 
 The declared-name overload comes first so an app error shadows the reserved ones on a
 name collision, and so the kind argument autocompletes to the rpc's declared names.
@@ -32,9 +31,5 @@ export interface RpcErrorGuard<Errors extends ErrorSpec> {
         error: unknown,
         kind: 'validation',
     ): error is HttpError & { kind: 'validation'; data: ValidationErrorData }
-    (
-        error: unknown,
-        kind: 'queued',
-    ): error is HttpError & { kind: 'queued'; data: OutboxEntry<unknown> }
     <Kind extends string>(error: unknown, kind: Kind): error is HttpError & { kind: Kind }
 }

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

@@ -9,8 +9,8 @@ fan-out and a client-side ws proxy by build target. Iterating the socket
 is the live stream — no replay. `.tail(count)` opens a subscription seeded
 with the last `count` frames of the retained tail (declared via
 `{ tail: n }`; no-arg = the whole retained tail) before going live — the
-optional Subscribable retention capability a reactive `watch(socket, …)`
-seeds from. `broadcast` is isomorphic: server code broadcasts in-process
+optional NamedAsyncIterable retention capability a reactive `watch(socket, …)`
+seeds from. `publish` is isomorphic: server code publishes in-process
 and fans out to remote subscribers; client code sends a `pub` frame the
 dispatcher validates against the topic's `clientPublish` flag. `clients`
 exposes which adapter surfaces (browser / mcp / cli) advertise this
@@ -21,8 +21,8 @@ export interface Socket<T> extends AsyncIterable<T> {
     readonly clients: ClientFlags
     /* Send a frame to every subscriber (server always; client only when `clientPublish` is
        set). Isomorphic: server code fans out in-process + to remote subscribers; client code
-       sends a validated `pub` frame. */
-    broadcast(message: T): void
+       sends a validated `pub` frame. Mirrors Bun's `server.publish()`. */
+    publish(message: T): void
     tail(count?: number, hooks?: TailHooks): AsyncIterable<T>
     /* The latest retained frame, synchronously — `T | undefined` when none. The value
        member of the probe family for a stream; `peek(socket)` routes here. */

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

@@ -10,7 +10,8 @@ write-set and read-set can't drift apart on a matching-string-key handshake.
 
 Three partitions:
   - `SsrBootState` fields seed ambient slots via the exhaustive `seedBootState` map;
-  - `cache` is the inline warm-seed partition, drained through `seedResolved`;
+  - `cache` / `cells` are the warm-seed partitions (settled `cache()` values / resolved async-cell
+    values), drained into their client stores before mount;
   - `route`/`params` are stamped for inspectability and are NOT read by the client
     (the router re-resolves the route from the URL).
 */
@@ -18,4 +19,7 @@ export type SsrPayload = SsrBootState & {
     route: string
     params: Record<string, string>
     cache?: CacheSnapshotEntry[]
+    /* Async-cell values that resolved during SSR, keyed by render-path id → ref-json string.
+       `startClient` seeds these into `CELL_SEED`; a hydrating cell reads its key to warm-hydrate. */
+    cells?: Record<string, string>
 }

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

@@ -0,0 +1,11 @@
+/*
+Endpoint stream policy, declared once on a streaming rpc definition (ADR-0020).
+`n` is the replay depth — how many retained frames a fresh reader gets before
+going live, pairing with the server-side `tail` retention. Endpoint-fixed: a
+late joiner can't request deeper replay than a fresh view. No runtime consumer
+today (subscribableFromResponse ignores it); threaded onto the definition for
+completeness and future use.
+*/
+export type StreamPolicy = {
+    n?: number
+}

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

@@ -0,0 +1,19 @@
+/*
+The per-request list of STREAMING async-cell values that SETTLED during this SSR pass, each keyed by
+the cell's serialization-stable render-path id (`${scope.id}:${index}`) (ADR-0035). A streaming cell
+ships pending in the shell (excluded from the pre-mount `__SSR__.cells` warm-seed, which would
+diverge from that pending markup), so instead `createAsyncCell.settleValue` records its resolved
+VALUE here when it settles server-side. The page renderer reads this AFTER the shell — streaming an
+`__abideResolve({ cellKey, value })` chunk per entry — so the client adopts the server-resolved
+value post-hydration (no `loading…` flash) instead of only cold-re-running the seed.
+
+Values (not promises) so the drain never AWAITS — a streaming cell may legitimately stay pending
+through the whole request (the `{#if getFoo()}`-holds case), and awaiting it would hang the
+response. Only cells that settled before the drain point are streamed; one still pending is simply
+not (the client cold-runs it, unchanged). The streaming sibling of `ResolvedCells` (the BLOCKING
+warm-seed, read at render-return and stamped into `__SSR__.cells`); this one is read later in the
+stream and shipped out-of-order as chunks.
+*/
+export type StreamedCells = {
+    entries: { key: string; value: unknown }[]
+}

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

@@ -1,10 +1,28 @@
 import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
 
 /*
-Payload of one streamed `window.__abideResolve(...)` call. A full
-`CacheSnapshotEntry` settles the placeholder with warm data; a `{ key, miss }`
-marker means the server couldn't snapshot that body (binary, rejected, evicted)
-so the client settles the placeholder with a live re-fetch instead. Discriminate
-on the `miss` field.
+Payload of one streamed `window.__abideResolve(...)` call. Three arms:
+
+  - a full `CacheSnapshotEntry` (has `key` + body) settles a cache placeholder with warm data;
+  - a `{ key, miss }` marker means the server couldn't snapshot that cache body (binary, rejected,
+    evicted) so the client settles the placeholder with a live re-fetch instead;
+  - a `{ cellKey, value }` (ADR-0035) carries a STREAMING CELL's server-resolved value, keyed by its
+    render-path warm-key and `encodeRefJson`-encoded, applied post-hydration as a reactive update so
+    a non-cache peek stops flashing `loading…` on hydrate.
+  - a `{ cellSeed, value }` (ADR-0039) carries a STREAMED CHILD's blocking async-cell value that
+    resolved AFTER the head `__SSR__.cells` snapshot (its render was deferred to the drain), seeded
+    PRE-mount into `CELL_SEED` — the same warm partition as `__SSR__.cells` — so the child's cell
+    constructs resolved on hydrate rather than re-running.
+
+Discriminate on `cellSeed` then `cellKey` (cell) then `miss` (cache miss) then default (cache entry).
 */
-export type StreamedResolution = CacheSnapshotEntry | { key: string; miss: true }
+
+/* The cache arms — a warm snapshot entry or a `{ key, miss }` marker. `streamCacheResolutions`
+   yields exactly these (never the cell arm), so its element type is `CacheResolution`, keeping a
+   `.key` access on its results well-typed. */
+export type CacheResolution = CacheSnapshotEntry | { key: string; miss: true }
+
+export type StreamedResolution =
+    | CacheResolution
+    | { cellKey: string; value: string }
+    | { cellSeed: string; value: string }

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

@@ -1,5 +1,5 @@
 /*
-Hooks a `tail(count, hooks)` caller passes to a Subscribable's retention
+Hooks a `tail(count, hooks)` caller passes to a NamedAsyncIterable's retention
 capability.
 `replayed` must be signalled in-band exactly once per iteration — after the
 last replayed frame, before any live frame, and even when nothing was

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

@@ -0,0 +1,11 @@
+/*
+The wire codec kind for a single top-level Args field (ADR-0029). Generalizes ADR-0028's scalar
+`number`/`boolean` query coercion to the structured value kinds the warm server program can name
+through the type graph — a `Date` / `Set` / `Map` by symbol identity, a `bigint` by type flag.
+parseArgs revives a field's plain-JSON wire form into the runtime value the handler's declared
+type expects: an ISO string → `Date`, a numeric string → `bigint`, a JSON array → `Set`, a JSON
+entries array (or object) → `Map`. Top-level fields only in this increment — a structured value
+NESTED inside another value is not descended into. Reviving is fail-open: an unrevivable value is
+left as its JSON form, never thrown, so the plain-JSON / OpenAPI contract still works.
+*/
+export type WireKind = 'number' | 'boolean' | 'date' | 'bigint' | 'set' | 'map'

package/src/lib/shared/url.ts

@@ -116,6 +116,11 @@ function interpolate(segments: RouteSegment[], params: Query): string {
             if (segment.optional && (value === undefined || value === '')) {
                 return undefined
             }
+            /* A required `[name]`/`[...rest]` with no value would otherwise stringify to the
+               literal "undefined" and silently mis-route; fail loudly instead. */
+            if (value === undefined || value === null) {
+                throw new Error(`abide url(): missing required param "${segment.name}"`)
+            }
             const text = String(value)
             return segment.catchAll
                 ? text.split('/').map(encodeURIComponent).join('/')

package/src/lib/shared/validationHttpError.ts

@@ -0,0 +1,33 @@
+import { fieldErrorsFromIssues } from './fieldErrorsFromIssues.ts'
+import { HttpError } from './HttpError.ts'
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
+import type { ValidationErrorData } from './types/ValidationErrorData.ts'
+
+/*
+Builds the HttpError a client-side pre-flight validation failure throws (ADR-0026 D2),
+shaped IDENTICALLY to the one a caller gets when the server rejects the same input with a
+422: `kind: 'validation'`, `status: 422`, `data: ValidationErrorData` (`{ issues, fields }`),
+so an `error instanceof HttpError && error.kind === 'validation'` branch — and the
+`error.data.fields` form-error map — read the same whether the rejection came from the
+client pre-flight or the server.
+
+This is a UX optimization ONLY, never a trust boundary: the server's unconditional
+`inputSchema['~standard'].validate` → `validationError` 422 (defineRpc.ts) stays
+authoritative. A client that skips or fakes this check is still fully validated on the
+server.
+
+The `data` mapping (`fieldErrorsFromIssues`) is the same isomorphic helper the server 422
+uses; the response envelope (`{ $abideError, data }`, status 422, reason phrase) mirrors
+`typedErrorResponse('validation', 422, …)` — reconstructed here with a plain web-standard
+`Response` so the browser bundle never imports the server's Response builder. The status
+text mirrors `STATUS_TEXT[422]`.
+*/
+export function validationHttpError(issues: readonly StandardSchemaV1.Issue[]): HttpError {
+    const data: ValidationErrorData = { issues, fields: fieldErrorsFromIssues(issues) }
+    const response = new Response(JSON.stringify({ $abideError: 'validation', data }), {
+        status: 422,
+        statusText: 'Unprocessable Content',
+        headers: { 'content-type': 'application/json' },
+    })
+    return new HttpError(response, 'validation', data)
+}

package/src/lib/shared/warmSeedKey.ts

@@ -0,0 +1,16 @@
+/*
+The single source of the async-cell warm-seed key format: the `${scopeId}:${cellIndex}` string that
+pairs a cell's serialization-stable render-path scope id with its per-scope declaration ordinal.
+
+Both sides of the SSR→client handoff mint the key through THIS callable — the isomorphic
+`createAsyncCell` runs it server-side to key its `resolvedCells`/`streamedCells` entries (which the
+page renderer stamps into `__SSR__.cells` / streams as `{ cellKey }` / `{ cellSeed }` chunks), and
+client-side to look the value up in `CELL_SEED`. Because the two sides now invoke one function, the
+byte-for-byte agreement the warm-seed depends on is a shared definition rather than a template
+literal re-typed at each call site: changing the delimiter here changes it for both sides at once,
+so the SSR-text-≡-first-client-render mismatch class (ADR-0033) cannot silently reopen from a
+one-sided edit. Pure so it stays trivially testable and inlinable.
+*/
+export function warmSeedKey(scopeId: string, cellIndex: number): string {
+    return `${scopeId}:${cellIndex}`
+}

package/src/lib/shared/wireJsonReplacer.ts

@@ -0,0 +1,30 @@
+/*
+The value-directed wire ENCODE step for a rpc response body (ADR-0029 output path). A
+`JSON.stringify` replacer that rewrites the structured runtime values plain JSON can't carry into
+their honest-JSON wire form, so `json()` never drops a `Set`/`Map` to `{}` or throws on a `bigint`:
+
+  - `bigint`  → its digit string (plain JSON.stringify throws on a bigint)
+  - `Set<T>`  → a JSON array of its values (plain JSON.stringify emits `{}`)
+  - `Map<K,V>`→ a JSON array of `[K,V]` entries (uniform, carries non-string keys)
+
+A `Date` needs no branch — its native `toJSON` already rewrote it to an ISO string before the
+replacer runs. Value-directed (not type-directed), so it runs for EVERY client — a non-abide caller
+(curl / an OpenAPI SDK) receives the same honest JSON the projected schema (`jsonSchemaForType`)
+describes. It is naturally recursive: a returned array/object member surfaces through the same
+replacer, so a `Set` nested inside an object still encodes. Never throws — an ordinary value falls
+through untouched.
+*/
+export function wireJsonReplacer(_key: string, value: unknown): unknown {
+    if (typeof value === 'bigint') {
+        return value.toString()
+    }
+    if (value instanceof Set) {
+        return [...value]
+    }
+    if (value instanceof Map) {
+        /* A Map iterates as `[key, value]` pairs, so the spread yields the entries array the
+           client output plan (and the projected schema) expects. */
+        return [...value]
+    }
+    return value
+}

package/src/lib/shared/writeRpcDts.ts

@@ -1,9 +1,11 @@
+import { resolve } from 'node:path'
 import { augmentModule } from './augmentModule.ts'
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
 import { detectRpcMethod } from './detectRpcMethod.ts'
 import { fileStem } from './fileStem.ts'
 import { RPC_ARGS_TYPE } from './RPC_ARGS_TYPE.ts'
 import { rpcUrlForFile } from './rpcUrlForFile.ts'
+import type { HttpMethod } from './types/HttpMethod.ts'
 import { writeDts } from './writeDts.ts'
 
 /*
@@ -22,15 +24,23 @@ export async function writeRpcDts({
     rpcDir,
     rpcFiles,
     importName,
+    methodForModule,
 }: {
     cwd: string
     rpcDir: string
     rpcFiles: string[]
     importName: string
+    /* Warm server-program method resolver (ADR-0025 D2): reads the method off the export's
+       helper symbol so an aliased/re-exported helper resolves where `detectRpcMethod`'s
+       `RPC_EXPORT` regex misses it. Absent (no warm program) or undefined-per-file falls open to
+       the regex, byte-identical to before. */
+    methodForModule?: (modulePath: string) => HttpMethod | undefined
 }): Promise<void> {
     const pairs = await Promise.all(
         rpcFiles.map(async (file): Promise<[string, string] | undefined> => {
-            const method = detectRpcMethod(await Bun.file(`${rpcDir}/${file}`).text())
+            const method =
+                methodForModule?.(resolve(rpcDir, file)) ??
+                detectRpcMethod(await Bun.file(`${rpcDir}/${file}`).text())
             // A body rpc's args can't ride a URL — leave it out of the url() rpc map.
             if (!method || carriesBodyArgs(method)) {
                 return undefined

package/src/lib/shared/writeTestSocketsDts.ts

@@ -8,7 +8,7 @@ Emits a `.d.ts` that augments createTestApp's `SocketClient` interface with one
 entry per $socket, keyed by socket name (the same key `app.sockets.<name>`
 resolves at runtime). The `socket(...)` helper statically returns `Socket<T>`,
 so each entry is the export's own type directly — `app.sockets.chat` types as
-`Socket<ChatMessage>`, iterable for the live stream with `.tail`/`.broadcast`.
+`Socket<ChatMessage>`, iterable for the live stream with `.tail`/`.publish`.
 Written to `src/.abide/testSockets.d.ts` like its rpc sibling.
 */
 export async function writeTestSocketsDts({

package/src/lib/test/createTestApp.ts

@@ -39,8 +39,11 @@ import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
+import { pendingAsyncCellsSlot } from '../shared/pendingAsyncCellsSlot.ts'
+import { resolvedCellsSlot } from '../shared/resolvedCellsSlot.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
 import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
+import { streamedCellsSlot } from '../shared/streamedCellsSlot.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import type { Socket } from '../shared/types/Socket.ts'
 import { createTestSocketChannel } from './createTestSocketChannel.ts'
@@ -72,7 +75,7 @@ export type TestApp = {
     /* Rpc calls over HTTP, keyed by command name: `app.rpc.getProduct({ id })`. */
     rpc: RpcClient
     /* Sockets keyed by name: `app.sockets.ticker` is the Socket — iterate it for
-       the live stream, `.tail(n)` to seed, `.broadcast(m)` to send. */
+       the live stream, `.tail(n)` to seed, `.publish(m)` to send. */
     sockets: SocketClient
     /* The /__abide/health payload, decoded. */
     health: () => Promise<unknown>
@@ -101,12 +104,24 @@ export async function createTestApp(): Promise<TestApp> {
         sharedResolver: sharedCacheStoreSlot.resolver,
         pageResolver: pageSlot.resolver,
         baseResolver: baseSlot.resolver,
+        pendingAsyncCellsResolver: pendingAsyncCellsSlot.resolver,
+        resolvedCellsResolver: resolvedCellsSlot.resolver,
+        streamedCellsResolver: streamedCellsSlot.resolver,
         activeServer: serverSlot.active,
     }
 
     const sharedStore = createCacheStore()
     sharedCacheStoreSlot.resolver = () => sharedStore
     cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedStore
+    const sharedPendingAsyncCells = { promises: [] }
+    pendingAsyncCellsSlot.resolver = () =>
+        requestContext.getStore()?.pendingAsyncCells ?? sharedPendingAsyncCells
+    const sharedResolvedCells = { entries: [] }
+    resolvedCellsSlot.resolver = () =>
+        requestContext.getStore()?.resolvedCells ?? sharedResolvedCells
+    const sharedStreamedCells = { entries: [] }
+    streamedCellsSlot.resolver = () =>
+        requestContext.getStore()?.streamedCells ?? sharedStreamedCells
     pageSlot.resolver = resolvePageSnapshot
 
     /* Eager env validation, exactly as serverEntry: a top-level env(schema) in
@@ -188,6 +203,9 @@ export async function createTestApp(): Promise<TestApp> {
         sharedCacheStoreSlot.resolver = previous.sharedResolver
         pageSlot.resolver = previous.pageResolver
         baseSlot.resolver = previous.baseResolver
+        pendingAsyncCellsSlot.resolver = previous.pendingAsyncCellsResolver
+        resolvedCellsSlot.resolver = previous.resolvedCellsResolver
+        streamedCellsSlot.resolver = previous.streamedCellsResolver
         serverSlot.active = previous.activeServer
     }
 

package/src/lib/ui/README.md

@@ -61,7 +61,7 @@ write-path microbench this runs ~20× faster than a deep-proxy signal baseline.
 
 - `compileSSR` renders to an HTML string (byte-identical to the client DOM).
 - `renderToStream` streams: pending shell first, then resolved `<template await>`
-  fragments out of order as their promises settle; `applyResolved` swaps them in.
+  fragments out of order as their promises settle; the inline swap script swaps them in.
 - `hydrate` adopts the server DOM in place (no re-render) for static-structure
   components — claims existing nodes, splits merged text, wires effects/listeners.
 

package/src/lib/ui/activePendingCells.ts

@@ -0,0 +1,14 @@
+import { pendingAsyncCellsSlot } from '../shared/pendingAsyncCellsSlot.ts'
+import type { PendingAsyncCells } from '../shared/types/PendingAsyncCells.ts'
+import { cellBarrierBacking } from './runtime/cellBarrierBacking.ts'
+
+/*
+The async-cell barrier list a registration (`createAsyncCell`) or a drain (`settleAsyncCells`) should
+use RIGHT NOW: a per-render isolated list if one is active (a hoisted concurrent child render — see
+`isolateCellBarrier`), else the per-request list from `pendingAsyncCellsSlot`. The single seam both
+barrier consumers read, so an isolated render can't leak its in-flight cells into a sibling's or the
+page's drain. Undefined only when neither a render override nor a request/fallback list is installed.
+*/
+export function activePendingCells(): PendingAsyncCells | undefined {
+    return cellBarrierBacking.active.current() ?? pendingAsyncCellsSlot.get()
+}

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

@@ -0,0 +1,21 @@
+/*
+The control-block vocabulary — the ONE source of truth shared by the parser
+(`parseTemplate`'s dispatch/error) and the LSP highlighter (`structuralHeadTokens`, driven
+by the parse walk), so the keywords the highlighter colors can't drift from the blocks the
+parser accepts (the `{#snippet}` head once went uncolored because a hand-copy omitted it).
+
+`BLOCK_OPENERS` follow `{#`, `BLOCK_CONNECTORS` follow `{:`. `for await` is the async-each
+opener form the highlighter colors as one phrase (the parser reads the `await` inside a
+`for` head); it is not a distinct opener.
+*/
+export const BLOCK_OPENERS = ['if', 'for', 'await', 'switch', 'try', 'snippet'] as const
+
+export const BLOCK_CONNECTORS = [
+    'else if',
+    'else',
+    'then',
+    'catch',
+    'finally',
+    'case',
+    'default',
+] as const

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

@@ -17,7 +17,10 @@ across bundles. Emitted inline (not imported) so the generated render module is
 self-contained.
 */
 export const SSR_ESCAPE =
-    'const $esc = (v) => String(v).replace(/[&<>"\']/g, (c) => ' +
+    // Nullish escapes to empty text, never the literal `"undefined"` — a pending async
+    // read (ADR-0032 D3) renders nothing. `$attr` guards nullish before it calls `$esc`,
+    // so its whole-value undefined still drops the attribute.
+    'const $esc = (v) => (v == null ? "" : String(v)).replace(/[&<>"\']/g, (c) => ' +
     "({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;', \"'\": '&#39;' })[c]);\n" +
     'const $attr = (n, v) => (v === false || v === null || v === undefined) ? "" ' +
     ': v === true ? (" " + n) : (" " + n + \'="\' + $esc(v) + \'"\');\n' +