[aralroca]

What

Navigation becomes what it was always meant to feel like: the server flushes the page as it renders, the client diffs it as it arrives, rapid clicks cancel the in-flight navigation (the last one wins), and prefetching is configurable from `janux.config.ts` with Speculation Rules emitted by default. Live on https://janux.build.

Streaming SSR (the actual fix for "streaming doesn't feel like streaming")

• `renderToStream` — HTML flushes as it is produced, in document order, with sibling islands still loading their sources in parallel (a slow source holds back its own island, not the page). Joined chunks are byte-identical to `renderToString(...).html`, and `renderToString` is implemented as its drain. `cancel()` stops an abandoned render instead of paying for every island of a closed connection.
• The shell splits into prelude/epilogue — title, meta and styles resolve from the route before the body renders, so the `` goes out as the first chunk; snapshots, island map and i18n payload follow the body. A byte-identity test keeps the streamed response and the buffered document from ever disagreeing.
• `handlePage` answers with a `ReadableStream`; chunks coalesce on genuine renderer pauses (one flush per static run, not one write per tag). A render that fails after the first flush cannot change the status line anymore, so it reports in-page (`janux:error` + closed document; no auto-reload — a deterministic error would just repeat). Before the first flush it is still a normal 500. The Vite dev adapter pipes instead of buffering, honours backpressure, and survives a client that disconnects with the socket full.
• Measured on the docs site: `<title>` at 8ms and first `

  ` at 59ms where previously nothing left the server until the last byte existed.

The renderer's internal design is ordered emitters (not async generators): siblings run under the exact `Promise.all` scheduling the string renderer always had — which is what keeps nested island key assignment aligned with the client's synchronous depth-first traversal (pinned by test; a generator-based draft assigned keys in yield order and two same-typed nested islands could swap state) — while the leftmost unfinished child streams straight through.

Abortable navigations (rapid clicks)

Navigations are serialized and each one cancels the one before it: the superseded fetch dies with its Navigation API signal, and a prefetched body — which has no fetch signal of its own — is wrapped so the navigation's signal kills it too (`abortableStream`). A superseded navigation never reports `after`, never disposes an island, and never wins over the last click. Verified in real Chrome: click two sidebar entries faster than the pages arrive → the last one lands, the assistant stays open, same live instance.

This surfaced two upstream bugs in `diff-dom-streaming`, both fixed with TDD in brisa-build/diff-dom-streaming#23 (v0.6.8):

• the walker never applied the body progressively when content hangs off an open last child (`` after `` — i.e. every real page): only the `` streamed;
• an erroring stream left `diff()` hanging forever — one aborted navigation froze SPA navigation until a hard reload.

Prefetch + Speculation Rules, configurable

```ts
export default defineConfig({
navigation: {
spa: true, // default: true
prefetch: { ttl: 60_000 }, // or false
speculationRules: { eagerness: 'moderate', exclude: ['/logout'] },
},
});
```

• `janux.config.ts` finally reaches the client, through a keyed shell script (`jx-config`).
• The shell emits `<script type="speculationrules">` by default (prefetch-only, `moderate`). Their cache only serves browser-driven document navigations — never a `fetch()` — so once `boot()` intercepts, the rules are narrowed to `a[data-native]` links (otherwise Chrome speculates documents the SPA path never uses, and hover fetches each page twice). Navigation responses ship them already narrowed, so the client's rescope is a no-op and the browser keeps its speculation candidates across the swap. Browsers without the Navigation API keep the document-wide rules — exactly the ones the API helps most.
• Hover prefetch keeps the stream (the diff consumes it directly), is capped at 8 warmed pages with evicted bodies cancelled (a hover tour must not pile up open connections), respects Save-Data, and is skipped where no Navigation API would ever consume it.
• A static page's single `<script>` tag is now the rules' JSON, which the browser reads as data: still zero JavaScript, and the page type that benefits most.

Persisted islands

A `persist` island the destination page does not render is disposed — that is the contract — but it reads as "my assistant closed itself", so it now warns naming the island and the route. Documented: render it from a shared layout and it survives the whole session.

Tests & docs

• 3,333 tests green (unit + conformance corpus + docs truth guards), typecheck clean.
• New browser e2e suite (`e2e/streaming-navigation.e2e.test.ts`, real Chrome via Playwright `channel: 'chrome'`): a navigation paints its heading mid-stream while the tail provably hasn't arrived; the assistant survives navigation open and same-instance; rapid navigations drop the superseded one; stylesheets never accumulate. CI builds the docs app first so the suite can't pass by silently skipping.
• Docs updated with executable page tests: streaming (`guide/ssr-and-resumability`), navigation config, prefetch/speculation rules, persist contract (`guide/navigation`), `renderToStream`/`speculationRules` reference (`reference/core-api`).

Depends on

• diff-dom-streaming 0.6.8 (fix: stream the body progressively past an open last node, and reject instead of hanging on stream errors brisa-build/diff-dom-streaming#23) published to npm, then a one-line bump here (`^0.6.8`). The e2e suite is red with 0.6.7 by design — it describes the behavior the two upstream fixes provide. janux.build already runs the fixed build (deployed prebuilt).

Follow-ups (noted, out of scope)

• Merge the three per-navigation `MutationObserver`s in `navigate.ts` into one; `sweepDisconnected` is O(islands × document).
• Generalize the restore-after-diff family via `diff-dom-streaming`'s `shouldIgnoreNode`.
• `Node.moveBefore()` for keyed moves (feat: support to experimental Node#moveBefore() API  brisa-build/diff-dom-streaming#9).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.