@abide/abide 0.34.2 → 0.35.0

package/AGENTS.md

@@ -164,7 +164,7 @@ Reactive state is owned by a scope and declared explicitly through it: `const co
 - `scope().state(initial, transform?)` — local truth. Plain `state(x)` lowers to a serializable `model` (= `scope()`) doc slot. `state(x, transform)` is a write-coercion gate (`.value` cell).
 - `scope().linked(seed, transform?)` — a `.value` cell seeded reactively from upstream (Angular's `linkedSignal`): owns a local value, reseeds when the `seed` thunk's deps change, edits stay local. Non-serializing — reseeds on resume.
 - `scope().computed(compute)` → a read-only computed **doc slot** (`scope().derive("name", compute)`), referenced as `name()` (string-free reader): re-computed on resume, never serialized/journalled. Always read-only (no `set` overload) — a writable computed is expressed at the binding site (`bind:value={{ get, set }}`), where the write actually originates.
-- `prop('name')` → a read-only computed doc slot over the parent thunk (`scope().derive`), referenced as `name()`.
+- `const { a = default, b: alias } = props<Shape>()` → the prop reader (the only one): destructure the parent-passed props; each binding is a read-only computed doc slot over its parent thunk (read as `a()`), an `= default` supplies the fallback when the prop is absent, `b: alias` renames. The optional `<Shape>` type argument is the parent-facing prop shape (default `Record<string, any>`). Bare `prop(...)` is a compile error pointing here.
 - `abide/ui/effect(fn)` → run now, re-run on dependency change; `fn` may return teardown / be async; returns dispose. (`effect` IS still a public export.)
 - `abide/ui/scope(address?)` → `Scope` — **the data + capability seam; the only public way to reach reactive state.** The reactive document (immutable path-addressed tree, every change a patch — JSON Pointer keys via `escapeKey`, so a key may contain `/`) is now *internal* (`doc`/`createDoc`): a scope wraps one and mirrors its interface — `read`/`replace`/`add`/`remove`/`cell`/`derive`/`snapshot` (data; `derive(path, compute)` is a computed slot, never stored/serialized/journalled), `child`/`root`/`parent` (tree), `dispose`. Every applied patch is announced on an internal process-global patch bus (`PATCH_BUS`) carrying `{ doc, patch, inverse }` — the single tap undo / persistence / sync consume; computed recomputes never reach it. Capabilities route where the scope's changes go — `record({ limit? })` to an undo journal (then `undo`/`redo`/`canUndo`/`canRedo`), `persist(key?)` to durable storage (key defaults to the scope `id`), `broadcast(transport)` to peers. A passable value (`<Child parentScope={scope}/>`). `scope()` = the ambient current scope — `mount`/`hydrate` (client) and `enterScope`/`exitScope` (SSR, per render) establish one per component; the lowering emits `const model = scope()`, so `scope()`'s data IS the component's `state`; `scope('/')` = the root. Resolves correctly inside event handlers, effects, and attach teardowns (they pin the scope they were registered under).
 
@@ -186,8 +186,8 @@ Reactive state is owned by a scope and declared explicitly through it: `const co
 Valid HTML with `<script>` + native `<template>` control flow + scoped `<style>`.
 - **Bindings:** `{expr}` text, `name={expr}` attr, `onclick={fn}`, `bind:value={…}` / `bind:checked` / `bind:group`, `attach={fn}` (node-lifetime attachment — the dual of `on`; the `use:`-action / `{@attach}` equivalent, lowered to `ui/dom/attach`). A two-way `bind:` target is an **lvalue** (`count`, `model.lines[i]`) or an **accessor object** `bind:value={{ get, set }}` (reads via `get()`, writes via `set(v)`) — the only way to two-way-bind derived state; binding a read-only `computed` is a compile error.
 - **Control flow (native `<template>`):** `if` with a nested `else` (the `<template else>` is a CHILD of its `<template if>`, not a sibling), `each={list} as="x" key="x.id"`, `await={p}`/`then`/`catch`, `switch`/`case`/`default`.
-- **A branch is a lexical scope:** any control-flow branch may host its own nested `<script>` and `<style>`. The nested `<script>` declares branch-local **plain** signals (`state`/`computed`/`linked`/`prop`) — owned by the branch's render scope, re-seeded each mount (not the serializable top-level `doc`) — with the branch's binding in scope (`then`/`catch`'s `as` value, the `each` `as`/`key` row), so it can derive from the awaited/iterated value; its bindings cover the branch subtree and later siblings auto-deref them. The nested `<style>` is scoped to that branch alone (its own `data-a-<hash>`), not the whole component.
-- **Components:** capitalised tags (`<Layout title=…>`); children fill `<slot/>`; props are reactive (passed as thunks). A component has no directives — every attribute is a prop under its written name (so `onclick=`/`bind:open=`/`attach=` pass through as props, e.g. callbacks, not the DOM-element directives those are on a lowercase tag) and is type-checked against the child's declared props. `prop('name')` reads a typed component prop (the parent-supplied thunk, reactive + read-only); route params come from the `page` proxy (`page.params.name`), not `prop()`.
+- **A branch is a lexical scope:** any control-flow branch may host its own nested `<script>` and `<style>`. The nested `<script>` declares branch-local **plain** signals (`state`/`computed`/`linked`) — owned by the branch's render scope, re-seeded each mount (not the serializable top-level `doc`) — with the branch's binding in scope (`then`/`catch`'s `as` value, the `each` `as`/`key` row), so it can derive from the awaited/iterated value; its bindings cover the branch subtree and later siblings auto-deref them. The nested `<style>` is scoped to that branch alone (its own `data-a-<hash>`), not the whole component.
+- **Components:** capitalised tags (`<Layout title=…>`); children fill `<slot/>`; props are reactive (passed as thunks). A component has no directives — every attribute is a prop under its written name (so `onclick=`/`bind:open=`/`attach=` pass through as props, e.g. callbacks, not the DOM-element directives those are on a lowercase tag) and is type-checked against the child's declared props. `const { name } = props<Shape>()` reads typed component props (parent-supplied thunks, reactive + read-only); route params come from the `page` proxy (`page.params.name`), not `props()`.
 - **Snippets / named slots:** `<template name="x" args={…}>` declares a reusable named builder (the `snippet()` form), rendered like a function — covers named slots / `{@render}`.
 - **Reactivity:** write plain assignment (`count += 1`, `items.push(x)`); the compiler lowers it to patches. Deep-field edits wake only that field.
 - **SSR:** byte-identical HTML string; `renderToStream` ships the shell then streams `<template await>` fragments out of order; `hydrate` adopts the server DOM in place — static structure, `if`/`else`, keyed `each`, `switch`, `try`, and child components/slots all claim existing nodes (no re-render; focus/scroll/input preserved). The one cold-rebuild case left is a genuinely-pending `await` that is neither resumable (`RESUME[id]`) nor cache-warm — it discards the boundary and builds the pending branch fresh; an `await` over a `cache`d read is warm on resume and adopts without a flash.

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # abide
 
+## 0.35.0
+
+### Minor Changes
+
+- [`c7ad3be`](https://github.com/briancray/abide/commit/c7ad3be781797ec3e2e4f66892f0711624d4a40f) - Breaking: replace prop() with destructuring props() as the sole prop reader ([`bb050d2`](https://github.com/briancray/abide/commit/bb050d2cd5b235212423f70ceef29dd8b53fcfc7))
+
+### Patch Changes
+
+- [`c7ad3be`](https://github.com/briancray/abide/commit/c7ad3be781797ec3e2e4f66892f0711624d4a40f) - make the streamed-gzip and preload-manifest sources typecheck ([`d5b093d`](https://github.com/briancray/abide/commit/d5b093dd37d3f0a2c381389d9308eddd1267cb2b))
+
+- [`b8a0080`](https://github.com/briancray/abide/commit/b8a00807d29dfcacd299b1fe30797dba74166684) - feat(ui): a bare attribute on a child component now coerces to `true` instead of the empty string. `<Toggle on />` passes `on: true`, matching HTML's presence-means-true semantics and a `boolean` prop's declared type (previously it passed `""`, which the type-checking shadow flagged against `on: boolean` — leaving no way to write a bare boolean that both read naturally and type-checked). An explicit `<Toggle on="" />` still passes the empty string, and native DOM elements are unchanged (`<button disabled>` still serialises to `disabled=""`). Behavior change: a component reading a bare prop and expecting `""` now receives `true`.
+
+- [`a0474f3`](https://github.com/briancray/abide/commit/a0474f3eca36d101b4c5a0b35edb8ffa7f02c906) - fix(ui): JSON-Pointer-escape reactive-document path keys so a key containing `/` or `~` addresses one segment instead of mis-splitting. `lowerDocAccess` lowered `model.byId[key]` to a raw `/`-joined path (`"byId/" + key`), and `model["a/b"]` to a raw literal — but the read side (`walkPath`) splits on `/` and `unescapeKey`s each segment. So a composite key (a date, a URL id, a slash-bearing string) round-tripped wrong: `model.byId["a/b"]` read/removed `byId → a → b` instead of the `"a/b"` entry. The `escapeKey` helper was written for exactly this (its doc cites "a URL id, a date, a composite key") and AGENTS.md documents scope keys as escaped — but it was never called.
+
+    The lowering now escapes both halves: literal keys at compile time (`model["a/b"]` → `read("byId/a~1b")`), dynamic segments at runtime (`model.byId[key]` → `read("byId/" + escapeKey(key))`). `escapeKey` joins `UI_RUNTIME_IMPORTS` (DCE-filtered, so only emitted when a component uses a dynamic/special key) and is exported at `abide/ui/runtime/escapeKey`; it now coerces (`String(key)`) since a dynamic segment is often a numeric array index. Plain identifier/index paths are unaffected.
+
+- [`d188eae`](https://github.com/briancray/abide/commit/d188eaeffd75ba80e30c3c16db714d4582c06468) - perf(ssr): preload the client entry in `<head>` so it downloads during a streamed render. The entry `<script type="module">` sits before `</body>`, which on a streaming page (top-level `{#await}`) arrives only after the whole stream — so the browser couldn't start fetching the bundle until the stream closed. `injectShellAssets` now also emits `<link rel="modulepreload" href="/_app/client.js">` in `<head>` (rebased + hashed like the other entry refs), overlapping the entry transfer with the streamed body. Execution still defers to parse-end (module script), so hydration ordering — including the trailing `__abideResolve(...)` cache seeds — is unchanged.
+
+- [`d188eae`](https://github.com/briancray/abide/commit/d188eaeffd75ba80e30c3c16db714d4582c06468) - perf(ssr): preload the client entry's static runtime chunks in `<head>` so the whole hydration graph downloads during a streamed render. The entry `modulepreload` only covered `client.js` itself; its ~dozen static `clientEntry-<hash>.js` runtime chunks (one abide-ui primitive each, split out by `splitting:true`) are discovered only after the browser downloads and _parses_ the entry — which on a streamed page is ~stream-close — so the runtime waterfalled in a second wave after the body finished. `rewriteHashedClientEntries` now reads the built entry, extracts its static import specifiers (regex excludes dynamic `import("./page-…")`, so route chunks stay lazy and code-splitting still pays off), and emits a `<link rel="modulepreload">` for each into `<head>`. The runtime graph now transfers alongside the entry during the stream, so hydration is network-ready at stream-close instead of waterfalling after it. Builds on the entry-preload + per-chunk-flushing-gzip work that made `<head>` decodable mid-stream.
+
+- [`e507a8b`](https://github.com/briancray/abide/commit/e507a8bd0ba5072974d472b4123193510b8f6257) - perf(ssr): preload the matched route's page + layout chunks (and their runtime deps) per render so the whole hydration chain downloads during a streamed render. The shell's `modulepreload`s cover the entry's shared runtime, but a route's page/layout chunks are dynamically imported — the browser can't discover them until it has downloaded, parsed, and _run_ the entry, which on a streamed page is ~stream-close, so the route's chunks (and the runtime only they import) waterfalled in a second wave after the body finished. A new `buildPreloadManifest` parses the built bundle once at server boot — route → chunk from the entry's compiled pages/layouts manifest, the static-import closure from each chunk's source — into a `route → chunks` map (excluding the entry graph the shell already preloads, reading disk under dev/`abide start` or the embedded gzip asset map for standalone compile). `createUiPageRenderer` injects a `<link rel="modulepreload">` per chunk into `<head>` for the matched route (page + full layout chain), rebased onto the mount base, in both the streamed and buffered paths. The route's whole chain now transfers alongside the entry during the stream, so hydration is network-ready at stream-close. Degrades to the entry-only preload when the bundle is absent or unparseable.
+
+- [`40dce51`](https://github.com/briancray/abide/commit/40dce514a4a46a507310ebb5007a73d875f1232d) - fix(ui): make signal-ref lowering lexically scope-aware so a callback parameter (or nested local) that shadows a component signal is no longer rewritten to the signal's doc form. Previously `renameSignalRefs` skipped only declaration-site identifiers, so in a component with `prop('option')`, a callback like `list.map(option => option.toUpperCase())` had its loop variable rewritten to `option()` — throwing `option is not a function` at runtime against the array element. The rewrite now threads a per-branch shadowed-name set down the AST (function/arrow params, nested `let`/`const`/`function`/`class`, `for`-headers, `catch` bindings), leaving inner references untouched while un-shadowed signals still lower.
+
+- [`e121179`](https://github.com/briancray/abide/commit/e121179965b9bd833a2148c61dd7828970eb8262) - fix(ssr): compress streamed SSR documents with a per-chunk-flushing gzip so the head reaches the browser decodable mid-stream. `gzipResponse` piped every dynamic body through the web `CompressionStream`, which buffers until its deflate window fills — for a streamed `text/html` page that held the whole head until ~stream close, so the browser couldn't preload-scan the entry/CSS links or paint the pending shell until the document nearly finished (defeating streaming for every gzip-accepting client, i.e. all browsers; curl missed it by not sending `Accept-Encoding: gzip`). The renderer now marks its streamed document (`STREAMED_HTML_HEADER`, stripped before send) and `gzipResponse` routes it through `flushingGzipStream` (node:zlib gzip with `Z_SYNC_FLUSH` after each chunk — the web `CompressionStream` exposes no flush). Buffered responses keep the one-shot `CompressionStream` (best ratio). Net: streamed pages stay compressed **and** flush progressively — head decodes in ~2 ms instead of ~stream-end.
+
+- [`2246463`](https://github.com/briancray/abide/commit/22464634a78febe8dde20d612fd96dcdffc01620) - fix(cache): seed the client cache store for streamed `{#await}` reads so they hydrate warm instead of refetching. The SSR snapshot only inlined entries settled by render-return into `__SSR__.cache`; a `<template await>` read shipped its resolved tuple to `window.__abideResume` for no-flash DOM adoption, but its cache key was never seeded. `awaitBlock`'s effect re-reads the promise on the first hydrate pass (to subscribe the key for `cache.invalidate`), so that read cold-missed straight to the network — correct first paint, redundant fetch per streamed block.
+
+    The root cause is a timing one: a `{#await cache()}` expression is a thunk the SSR stream runs lazily, so its cache entry is created (and settled) _during_ the stream — after the render-return snapshot, which is therefore empty for it. The renderer now snapshots the store again once the stream has drained and emits an inline `__abideResolve(...)` chunk per entry (a warm `CacheSnapshotEntry`, or a `{ key, miss }` marker for an unshippable body → live refetch), keyed-diffed against what already shipped inline. `startClient` seeds both partitions through one sink (`seedStreamedResolution`) before the deferred bundle hydrates, so the subscription read resolves synchronously and adopts the SSR DOM with no wire round-trip.
+
+    Also hardens the reserved bundle-side stream path so it can't silently reintroduce the refetch: `startClient` installs a live, store-connected `window.__abideResolve`, and `applyResolved` seeds the store from `<abide-cache>` data frames (a script set via innerHTML never runs, so a bundle-consumed stream — streaming SPA navigation, socket-delivered SSR — carries the cache channel as data) — pairing the cache seed with the DOM swap.
+
+    Internal cleanup: `serializeCacheSnapshot` now returns `CacheSnapshotEntry[]` (the settled snapshots) instead of an `{ inline, pending }` partition. The `pending` half encoded the false premise that a `{#await}` read is in-flight at render-return — it is created lazily mid-stream, so `pending` only ever caught the rare eagerly-fired-unawaited read. The unused `CacheSnapshot` type is removed.
+
+    Guarded by a real-HTTP-entrypoint integration test (`bootTestServer` → `createServer` → stream) that reads a gated verb through `cache()` inside `{#await}` and asserts the warm `__abideResolve(...)` seed ships over the wire while `__SSR__.cache` stays empty — it reproduces the original cold-miss when the seed pass is reverted.
+
 ## 0.34.2
 
 ### Patch Changes

package/README.md

@@ -75,7 +75,7 @@ For clients that can't speak the ws multiplex, each socket has an HTTP face at `
 
 ## Components
 
-Components are `.abide` files — valid HTML with `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. Reactive state is reached through `scope()` (`scope().state(v)`, `scope().computed(fn)`); `prop` and `effect` are in scope without import. This page reads the verb above through `cache()`, tails the socket live, and exercises most of the template grammar:
+Components are `.abide` files — valid HTML with `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. Reactive state is reached through `scope()` (`scope().state(v)`, `scope().computed(fn)`); props are read by destructuring `props()` (`const { room } = props()`), and `effect` is in scope without import. This page reads the verb above through `cache()`, tails the socket live, and exercises most of the template grammar:
 
 ```html
 <script>
@@ -86,7 +86,7 @@ import { publishChat } from '$server/rpc/publishChat.ts'
 import { chat } from '$server/sockets/chat.ts'
 import Avatar from '$ui/Avatar.abide'
 
-let room = prop('room')                                            // typed via src/.abide/routes.d.ts
+const { room } = props()                                           // typed via src/.abide/routes.d.ts
 const history = scope().computed(() => cache(getMessages)({ room })) // SSR snapshot + reactive refetch
 const latest = scope().computed(() => tail(chat))                  // re-renders on every new frame
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.34.2",
+    "version": "0.35.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -99,6 +99,7 @@
         "./ui/dom/tryBlock": "./src/lib/ui/dom/tryBlock.ts",
         "./ui/dom/switchBlock": "./src/lib/ui/dom/switchBlock.ts",
         "./ui/dom/applyResolved": "./src/lib/ui/dom/applyResolved.ts",
+        "./ui/runtime/escapeKey": "./src/lib/ui/runtime/escapeKey.ts",
         "./ui/runtime/nextBlockId": "./src/lib/ui/runtime/nextBlockId.ts",
         "./ui/runtime/enterRenderPass": "./src/lib/ui/runtime/enterRenderPass.ts",
         "./ui/runtime/exitRenderPass": "./src/lib/ui/runtime/exitRenderPass.ts",

package/src/abideResolverPlugin.ts

@@ -848,10 +848,17 @@ async function loadShell(cwd: string): Promise<string> {
 /*
 Injects the framework's client entry references so app.html stays a clean
 template — page structure plus the SSR markers, no framework asset bookkeeping.
-The css <link> lands before </head>, the module <script> before </body>. Each is
-skipped when the shell already carries that reference, so a custom app.html that
-still spells the tags out (or one already processed) doesn't get a duplicate.
-rewriteHashedClientEntries then swaps both for the hashed entry filenames.
+The css <link> and the entry's <link rel="modulepreload"> land before </head>,
+the module <script> before </body>. Each is skipped when the shell already
+carries that reference, so a custom app.html that still spells the tags out (or
+one already processed) doesn't get a duplicate. rewriteHashedClientEntries then
+swaps every reference for the hashed entry filenames.
+
+The modulepreload makes the browser fetch the entry during a streamed render —
+the closing </body> <script> tag arrives only after the whole stream, so without
+it the entry download is serialized after the body. Execution still defers to
+parse-end (module script), so hydration ordering is unchanged; only the transfer
+overlaps the stream.
 */
 function injectShellAssets(shell: string): string {
     let result = shell
@@ -863,7 +870,16 @@ function injectShellAssets(shell: string): string {
             'src/ui/app.html has no </head>',
         )
     }
-    if (!result.includes('/_app/client.js')) {
+    if (!result.includes('rel="modulepreload"')) {
+        result = injectBeforeTag(
+            result,
+            '<link rel="modulepreload" href="/_app/client.js" />',
+            'head',
+            'src/ui/app.html has no </head>',
+        )
+    }
+    // Guard on `src=` so the modulepreload's matching href doesn't mask a missing <script>.
+    if (!result.includes('src="/_app/client.js"')) {
         result = injectBeforeTag(
             result,
             '<script type="module" src="/_app/client.js"></script>',
@@ -898,9 +914,10 @@ function injectBeforeTag(
 Scans `dist/_app/` for the hashed client entry filenames produced by
 build.ts (e.g. `client-abc12345.js`, `client-abc12345.css`) and swaps the
 shell's literal `/_app/client.js` and `/_app/client.css` references for
-them. When the directory is missing (someone running the server before a
-build) the shell is returned unchanged so the existing broken-asset
-behaviour is preserved.
+them. The js reference appears twice (the modulepreload <link> and the entry
+<script>), so replaceAll covers both. When the directory is missing (someone
+running the server before a build) the shell is returned unchanged so the
+existing broken-asset behaviour is preserved.
 */
 async function rewriteHashedClientEntries(shell: string, cwd: string): Promise<string> {
     const appDir = `${cwd}/dist/_app`
@@ -914,10 +931,37 @@ async function rewriteHashedClientEntries(shell: string, cwd: string): Promise<s
     const cssEntry = entries.find((file) => /^client-[a-z0-9]+\.css$/i.test(file))
     let result = shell
     if (jsEntry) {
-        result = result.replace('/_app/client.js', `/_app/${jsEntry}`)
+        result = result.replaceAll('/_app/client.js', `/_app/${jsEntry}`)
+        result = await injectEntryDepPreloads(result, `${appDir}/${jsEntry}`)
     }
     if (cssEntry) {
         result = result.replace('/_app/client.css', `/_app/${cssEntry}`)
     }
     return result
 }
+
+/* Static-import specifiers in the built entry: `import {…} from "./chunk.js"` and
+   side-effect `import "./chunk.js"`, minified (no spaces) or not. The leading
+   `import` plus the `[^"'()]` guard excludes dynamic `import("./page-….js")`, so
+   only the runtime graph matches — route chunks stay lazy. */
+const ENTRY_STATIC_IMPORT = /import\s*(?:[^"'()]*?\bfrom\s*)?["']\.\/([\w.-]+\.js)["']/g
+
+/*
+SPIKE: preload the entry's static dependency chunks. The entry <script> statically
+imports the abide-ui runtime as ~60 one-export `clientEntry-<hash>.js` chunks; the
+browser can't discover them until it has downloaded and PARSED the entry, which on a
+streamed page is ~stream-close — so the runtime waterfalls in a second wave after the
+body finishes. Emitting a <link rel="modulepreload"> for each static dep into <head>
+lets the whole graph transfer DURING the stream alongside the entry, so hydration is
+network-ready at stream-close instead of after it. Route chunks (`import("./page-…")`)
+are dynamic, so they don't match and stay lazy — code-splitting still pays off.
+*/
+async function injectEntryDepPreloads(shell: string, entryPath: string): Promise<string> {
+    const source = await Bun.file(entryPath).text()
+    const deps = [...new Set([...source.matchAll(ENTRY_STATIC_IMPORT)].map((match) => match[1]))]
+    if (deps.length === 0) {
+        return shell
+    }
+    const links = deps.map((dep) => `<link rel="modulepreload" href="/_app/${dep}" />`).join('\n')
+    return injectBeforeTag(shell, links, 'head', 'src/ui/app.html has no </head>')
+}

package/src/lib/server/runtime/STREAMED_HTML_HEADER.ts

@@ -0,0 +1,13 @@
+/*
+Internal response-header marker the streaming SSR renderer stamps on its
+progressively-flushed `text/html` document. `gzipResponse` reads it to pick a
+per-chunk-flushing gzip over the buffering web CompressionStream (then strips it
+before send): a plain CompressionStream holds the head until its deflate window
+flushes, defeating progressive delivery — the browser can't preload-scan the head
+or paint the pending shell until the stream nearly closes. A streamed `text/html`
+body is otherwise indistinguishable from a buffered one (both expose a
+ReadableStream), and `isStreamingResponse` can't be widened to cover it without
+also opting these pages out of the idle-timeout cap they rely on (see
+disableIdleTimeoutForStream).
+*/
+export const STREAMED_HTML_HEADER = 'abide-streamed-html'

package/src/lib/server/runtime/buildPreloadManifest.ts

@@ -0,0 +1,151 @@
+import { existsSync } from 'node:fs'
+import { Glob, gunzipSync } from 'bun'
+import { layoutChainForRoute } from '../../shared/layoutChainForRoute.ts'
+import type { Assets } from './types/Assets.ts'
+
+/* A static-import specifier in a built chunk: `import {…} from "./chunk.js"` and
+   side-effect `import "./chunk.js"`, minified or not. The leading `import` plus the
+   `[^"'()]` guard excludes dynamic `import("./page-….js")` — so only the runtime graph
+   matches, never a lazy route chunk. Mirrors the shell injector in abideResolverPlugin. */
+const STATIC_IMPORT = /import\s*(?:[^"'()]*?\bfrom\s*)?["']\.\/([\w.-]+\.js)["']/g
+
+/* A pages/layouts manifest entry in the entry chunk:
+   `"<route>": () => import("./page-<hash>.js")` (page chunk) or the layout form.
+   The route/layout key plus its lazily-loaded chunk — the only place route → chunk is
+   recorded, since every page chunk shares the `page-` stem and can't be told apart by name. */
+const ROUTE_CHUNK = /"(\/[^"]*)"\s*:\s*\(\)\s*=>\s*import\("\.\/((?:page|layout)-[\w.-]+\.js)"\)/g
+
+/* Reads a `_app` chunk's source by filename — gunzipped from the embedded asset map
+   (standalone compile) or off disk (dev + `abide start`). Undefined on a miss. */
+function chunkReader(
+    distDir: string,
+    assets?: Assets,
+): (name: string) => Promise<string | undefined> {
+    if (assets) {
+        return async (name) => {
+            const bytes = assets[`/_app/${name}`]
+            return bytes ? new TextDecoder().decode(gunzipSync(bytes)) : undefined
+        }
+    }
+    return async (name) => {
+        const file = Bun.file(`${distDir}/_app/${name}`)
+        return (await file.exists()) ? file.text() : undefined
+    }
+}
+
+/* The hashed client entry filename (`client-<hash>.js`), from the asset map or disk. */
+async function findEntry(distDir: string, assets?: Assets): Promise<string | undefined> {
+    const isEntry = (name: string): boolean => /^client-[a-z0-9]+\.js$/i.test(name)
+    if (assets) {
+        const key = Object.keys(assets).find((path) => isEntry(path.replace('/_app/', '')))
+        return key?.replace('/_app/', '')
+    }
+    if (!existsSync(`${distDir}/_app`)) {
+        return undefined
+    }
+    const names = await Array.fromAsync(
+        new Glob('client-*.js').scan({ cwd: `${distDir}/_app`, onlyFiles: true }),
+    )
+    return names.find(isEntry)
+}
+
+/*
+Maps each page route to the extra `_app` chunks worth preloading for it: the route's
+page chunk, its layout-chain chunks, and the transitive static-import closure of each
+— minus the entry's own static graph, which the shell already preloads. Built once at
+server boot from the built bundle (the route → chunk mapping lives in the entry's
+compiled pages/layouts manifest; the static graph is parsed from each chunk's source).
+
+Those route chunks are dynamically imported by the entry, so the browser can't discover
+them until it has downloaded, parsed, and RUN the entry — on a streamed page that's
+~stream-close. Preloading them per render (the renderer knows the matched route) lets
+the route's whole chain transfer DURING the stream, so hydration is network-ready at
+stream-close instead of waterfalling after it. Returns an empty map when the bundle is
+absent or unparseable, so rendering degrades to the entry-only preload.
+*/
+export async function buildPreloadManifest({
+    distDir,
+    assets,
+}: {
+    distDir: string
+    assets?: Assets
+}): Promise<Record<string, string[]>> {
+    const read = chunkReader(distDir, assets)
+    const entryName = await findEntry(distDir, assets)
+    const entrySource = entryName ? await read(entryName) : undefined
+    if (entryName === undefined || entrySource === undefined) {
+        return {}
+    }
+
+    /* route/layout key → its lazy chunk, split by the page-/layout- stem. */
+    const pageChunk: Record<string, string> = {}
+    const layoutChunk: Record<string, string> = {}
+    for (const match of entrySource.matchAll(ROUTE_CHUNK)) {
+        /* Both capture groups are present whenever the regex matches. */
+        const key = match[1] as string
+        const chunk = match[2] as string
+        if (chunk.startsWith('page-')) {
+            pageChunk[key] = chunk
+        } else {
+            layoutChunk[key] = chunk
+        }
+    }
+
+    /* Memoised direct static imports per chunk; closure walks them to a fixpoint. */
+    const directCache = new Map<string, Promise<string[]>>()
+    const direct = (name: string): Promise<string[]> => {
+        const cached = directCache.get(name)
+        if (cached) {
+            return cached
+        }
+        const deps = read(name).then((source) =>
+            source
+                ? [
+                      ...new Set(
+                          [...source.matchAll(STATIC_IMPORT)].map((match) => match[1] as string),
+                      ),
+                  ]
+                : [],
+        )
+        directCache.set(name, deps)
+        return deps
+    }
+    const closure = async (name: string): Promise<Set<string>> => {
+        const seen = new Set<string>()
+        const queue = [name]
+        while (queue.length > 0) {
+            const current = queue.shift() as string
+            if (seen.has(current)) {
+                continue
+            }
+            seen.add(current)
+            for (const dependency of await direct(current)) {
+                if (!seen.has(dependency)) {
+                    queue.push(dependency)
+                }
+            }
+        }
+        return seen
+    }
+
+    /* The entry + its static runtime — already preloaded by the shell, so excluded. */
+    const excluded = await closure(entryName)
+    const layoutKeys = Object.keys(layoutChunk)
+    const manifest: Record<string, string[]> = {}
+    for (const route of Object.keys(pageChunk)) {
+        const chunks = new Set<string>(await closure(pageChunk[route] as string))
+        for (const key of layoutChainForRoute(route, layoutKeys)) {
+            const chunk = layoutChunk[key]
+            if (chunk) {
+                for (const dependency of await closure(chunk)) {
+                    chunks.add(dependency)
+                }
+            }
+        }
+        const preload = [...chunks].filter((chunk) => !excluded.has(chunk))
+        if (preload.length > 0) {
+            manifest[route] = preload
+        }
+    }
+    return manifest
+}

package/src/lib/server/runtime/createServer.ts

@@ -34,6 +34,7 @@ import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
 import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
 import { buildHealthPayload } from './buildHealthPayload.ts'
 import { buildOpenApiSpec } from './buildOpenApiSpec.ts'
+import { buildPreloadManifest } from './buildPreloadManifest.ts'
 import { createAppAssetServer } from './createAppAssetServer.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
 import { createRouteDispatcher } from './createRouteDispatcher.ts'
@@ -205,7 +206,7 @@ export async function createServer({
     browser would render; the asset servers glob public/ and the build tree
     (embedded gzip map in a compiled binary, dist/ on disk).
     */
-    const [clientFingerprint, servePublicAsset, serveAppAsset] = await Promise.all([
+    const [clientFingerprint, servePublicAsset, serveAppAsset, routePreloads] = await Promise.all([
         dev
             ? devClientFingerprint({
                   srcDir: `${process.cwd()}/src`,
@@ -216,6 +217,7 @@ export async function createServer({
             : undefined,
         createPublicAssetServer({ publicDir, publicAssets }),
         createAppAssetServer({ distDir, assets }),
+        buildPreloadManifest({ distDir, assets }),
     ])
     setRegistryManifests({ rpc, sockets, prompts })
     setMcpResourceServer(createMcpResourceServer({ resourcesDir, mcpResources }))
@@ -279,6 +281,7 @@ export async function createServer({
         clientTimeout: parseBoundedEnvInt(process.env.ABIDE_CLIENT_TIMEOUT, 1, 600_000),
         pages,
         layouts,
+        routePreloads,
         /* The wire payload, rebuilt per marked render — the __SSR__ health seed must match what /__abide/health serves. */
         healthPayload: (request) => buildHealthPayload(request, { app, appName, appVersion }),
     })

package/src/lib/server/runtime/createUiPageRenderer.ts

@@ -1,14 +1,20 @@
 import { appNameSlot } from '../../shared/appNameSlot.ts'
 import { SSR_CACHE_CONTROL } from '../../shared/CACHE_CONTROL_VALUES.ts'
 import { formatTraceparent } from '../../shared/formatTraceparent.ts'
+import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
 import { layoutChainForRoute } from '../../shared/layoutChainForRoute.ts'
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { StreamedResolution } from '../../shared/types/StreamedResolution.ts'
 import { renderChain } from '../../ui/renderChain.ts'
 import { renderToStream } from '../../ui/renderToStream.ts'
 import type { UiComponent } from '../../ui/runtime/types/UiComponent.ts'
 import { pageUrlFromStore } from './pageUrlFromStore.ts'
 import { SSR_SWAP_SCRIPT } from './SSR_SWAP_SCRIPT.ts'
+import { STREAMED_HTML_HEADER } from './STREAMED_HTML_HEADER.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
 import { serializeCacheSnapshot } from './serializeCacheSnapshot.ts'
+import { streamCacheResolutions } from './streamCacheResolutions.ts'
 import type { RequestStore } from './types/RequestStore.ts'
 
 /* A abide-ui page module: its default export is the compiled component. */
@@ -21,6 +27,19 @@ function wantsJson(request: Request): boolean {
     return (request.headers.get('accept') ?? '').includes('application/json')
 }
 
+/* Defines `window.__abideResolve` ahead of the body: the vanilla collector each
+   streamed cache resolution calls, buffering payloads for startClient to drain into
+   the store before hydration (the bundle is deferred, so it runs after every chunk). */
+const CACHE_RESOLVE_SCRIPT =
+    'window.__abideResolve=function(r){(window.__abideResumeCache=window.__abideResumeCache||[]).push(r)}'
+
+/* One streamed cache resolution as an inline `__abideResolve(...)` call. `<` is escaped
+   (as in encodeResume) so a body value can't close the script early. */
+function resolveChunk(resolution: StreamedResolution): string {
+    const payload = JSON.stringify(resolution).replace(/</g, '\\u003c')
+    return `<script>__abideResolve(${payload})</script>`
+}
+
 /*
 The abide-ui SSR document renderer. A matched route + params in, a finished HTML
 Response out.
@@ -30,9 +49,16 @@ await blocks STREAMS: the pending shell flushes first, then each resolved fragme
 (`<abide-resolve>` carrying a JSON `<script>`) as its promise settles, swapped into its boundary
 by the inline SSR_SWAP_SCRIPT — which also registers the value into the resume
 manifest so client hydration adopts it without re-fetching (see abide/ui/awaitBlock).
+Then, once the stream has run every `{#await}` thunk (creating and settling its cache
+entry mid-stream, after the render-return snapshot), each such entry streams an inline
+`__abideResolve(...)` chunk — a warm snapshot, or a `{ key, miss }` marker for an
+unshippable body (→ live refetch) — seeding the client store before the deferred bundle
+so the block's subscription read is warm (no refetch).
 
 `__SSR__` carries the route/params, mount base, trace, app name, client timeout,
-and the settled cache snapshot (the client seeds its tab store from it). A route's
+and the render-return cache snapshot (top-level `await` reads; the client seeds its tab
+store from it). `{#await}` reads aren't settled yet at render-return — they arrive over
+the stream as above. A route's
 `layout.abide` files wrap the page outermost-first (every ancestor directory's
 layout applies); the chain server-renders as one document via `renderChain`, the
 page folded into each layout's `<slot/>` outlet. The client router re-resolves the
@@ -44,6 +70,7 @@ export function createUiPageRenderer({
     clientTimeout,
     pages,
     layouts,
+    routePreloads = {},
     healthPayload,
 }: {
     shell: string
@@ -51,6 +78,7 @@ export function createUiPageRenderer({
     clientTimeout: number | undefined
     pages: Record<string, LoadPage>
     layouts: Record<string, LoadPage>
+    routePreloads?: Record<string, string[]>
     healthPayload: (request: Request) => Promise<Record<string, unknown>>
 }): {
     renderPage: (
@@ -65,13 +93,15 @@ export function createUiPageRenderer({
         stack?: string,
     ) => Promise<Response | undefined>
 } {
-    /* Build the __SSR__ <script> the client (startClient) reads on boot. */
+    /* Build the __SSR__ <script> the client (startClient) reads on boot. The inline
+       (settled) cache partition is computed once by the caller and threaded in, so the
+       streaming branch can also drain the pending partition over the same render. */
     async function stateTag(
         routeUrl: string,
         params: Record<string, string>,
         store: RequestStore,
+        inline: CacheSnapshotEntry[],
     ): Promise<string> {
-        const { inline } = await serializeCacheSnapshot(store.cache)
         const health = store.healthRead ? await healthPayload(store.req) : undefined
         const payload = safeJsonForScript({
             route: routeUrl,
@@ -86,6 +116,32 @@ export function createUiPageRenderer({
         return `<script>window.__SSR__ = ${payload};</script>`
     }
 
+    /* Per-route `<link rel=modulepreload>`s for the route's page + layout-chain chunks
+       and their route-only static runtime deps (the shell already preloads the entry's
+       shared runtime). Those chunks are dynamically imported by the entry, so the browser
+       discovers them only after the entry runs at parse-end ≈ stream-close; preloading them
+       in <head> overlaps their transfer with the stream. Rebased onto the mount base like
+       the shell's own `/_app/` refs. Cached per route — the set is render-invariant. */
+    const preloadLinkCache = new Map<string, string>()
+    function routePreloadLinks(routeUrl: string): string {
+        const cached = preloadLinkCache.get(routeUrl)
+        if (cached !== undefined) {
+            return cached
+        }
+        const links = (routePreloads[routeUrl] ?? [])
+            .map((chunk) => `<link rel="modulepreload" href="${base}/_app/${chunk}" />`)
+            .join('')
+        preloadLinkCache.set(routeUrl, links)
+        return links
+    }
+
+    /* Splices the route preloads in before the shell's </head> (case-insensitive, like the
+       build-time injector). A no-op when there are none or the shell carries no </head>. */
+    function injectRoutePreloads(html: string, routeUrl: string): string {
+        const links = routePreloadLinks(routeUrl)
+        return links === '' ? html : html.replace(/<\/head>/i, `${links}</head>`)
+    }
+
     async function renderPage(
         routeUrl: string,
         params: Record<string, string>,
@@ -117,14 +173,24 @@ export function createUiPageRenderer({
             params,
         )
 
+        /* Snapshot the cache settled by render-return — top-level `await` reads (render
+           blocked on them) — into __SSR__. A `{#await}` read is NOT here: its expression
+           is a thunk `renderToStream` runs lazily, so its entry is created mid-stream and
+           seeded after the drain (see below). */
+        const inline = await serializeCacheSnapshot(store.cache)
+        const inlinedKeys = new Set(inline.map((entry) => entry.key))
+
         /* No await blocks → render synchronously, ship buffered. */
         if (ssr.awaits.length === 0) {
-            const html = shell.replace(SSR_MARKER, (_match, key: string) =>
-                key === 'body' ? ssr.html : key === 'state' ? '' : '',
+            const html = injectRoutePreloads(
+                shell.replace(SSR_MARKER, (_match, key: string) =>
+                    key === 'body' ? ssr.html : key === 'state' ? '' : '',
+                ),
+                routeUrl,
             )
             const withState = html.replace(
                 '</body>',
-                `${await stateTag(routeUrl, params, store)}</body>`,
+                `${await stateTag(routeUrl, params, store, inline)}</body>`,
             )
             return new Response(withState, {
                 headers: {
@@ -139,9 +205,14 @@ export function createUiPageRenderer({
            Fill head/state but LEAVE the body marker intact — it's the split point for
            streaming the page body into `#app`; consuming it here would append the body
            after the whole shell (outside `#app`), breaking hydration. */
-        const head = `<script>${SSR_SWAP_SCRIPT}</script>${await stateTag(routeUrl, params, store)}`
-        const filled = shell.replace(/<!--ssr:(head|state)-->/g, (_match, key: string) =>
-            key === 'head' ? head : '',
+        const head =
+            `<script>${SSR_SWAP_SCRIPT}${CACHE_RESOLVE_SCRIPT}</script>` +
+            `${await stateTag(routeUrl, params, store, inline)}`
+        const filled = injectRoutePreloads(
+            shell.replace(/<!--ssr:(head|state)-->/g, (_match, key: string) =>
+                key === 'head' ? head : '',
+            ),
+            routeUrl,
         )
         const [before, after] = filled.split(BODY_MARKER)
         const encoder = new TextEncoder()
@@ -158,6 +229,26 @@ export function createUiPageRenderer({
                         )
                         first = false
                     }
+                    /* The {#await} reads created (and settled) their cache entries DURING the
+                       stream — the await expression is a thunk `renderToStream` ran lazily —
+                       so they missed the render-return snapshot. Drain them now: each lands an
+                       inline `__abideResolve(...)` chunk (a warm snapshot, or a `{ key, miss }`
+                       marker for an unshippable body → live refetch) before the deferred
+                       bundle, so startClient seeds the store and the block's subscription read
+                       is warm. Skip keys already shipped inline in __SSR__. */
+                    const streamedEntries = Array.from(store.cache.entries.values()).filter(
+                        (entry: CacheEntry) =>
+                            entry.settled === true &&
+                            entry.request !== undefined &&
+                            isReplayableMethod(entry.request.method.toUpperCase()) &&
+                            !inlinedKeys.has(entry.key),
+                    )
+                    for await (const resolution of streamCacheResolutions(
+                        store.cache,
+                        streamedEntries,
+                    )) {
+                        controller.enqueue(encoder.encode(resolveChunk(resolution)))
+                    }
                     controller.enqueue(encoder.encode(after ?? ''))
                     controller.close()
                 },
@@ -166,6 +257,10 @@ export function createUiPageRenderer({
                 headers: {
                     'Content-Type': 'text/html; charset=utf-8',
                     'Cache-Control': SSR_CACHE_CONTROL,
+                    /* Mark the progressively-flushed document so gzipResponse compresses it
+                       with a per-chunk-flushing gzip (the plain CompressionStream buffers the
+                       head and defeats streaming); the marker is stripped before send. */
+                    [STREAMED_HTML_HEADER]: '1',
                 },
             },
         )