@weftui/router 0.26.1 → 0.26.2

package/docs/how-to/load-async-data.md

@@ -0,0 +1,70 @@
+---
+title: Load Async Data
+order: 9
+section: how-to
+description: Show a loading state then resolved content with Stream.concat, and turn a failed fetch into a fallback node with Effect.catchAll — all client-side.
+---
+
+# Load Async Data
+
+**Goal:** render a loading placeholder, then the fetched content, and a fallback if the fetch fails — for data that loads **on the client**.
+
+Return a `Stream<Node>` that emits the loading node first and the resolved node second, sequenced with `Stream.concat`. Handle failure inside the effect with `Effect.catchAll`, which maps the error to a fallback node.
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, Stream } from "effect";
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const fetchUser = (id: number): Effect.Effect<User, Error> =>
+  Effect.gen(function* () {
+    yield* Effect.sleep("1000 millis");
+    if (id === 3) return yield* Effect.fail(new Error("User not found"));
+    return { id, name: `User ${id}`, email: `user${id}@example.com` };
+  });
+
+const UserCard = ({ id }: { id: number }) =>
+  Stream.concat(
+    Stream.make(h.div({ class: "loading" }, `Loading user ${id}…`)),
+    Stream.fromEffect(
+      fetchUser(id).pipe(
+        Effect.flatMap((user) => h.div({ class: "user-card" }, [h.h3(user.name), h.p(user.email)])),
+        Effect.catchAll((error) => h.div({ class: "error" }, `Error: ${error.message}`)),
+      ),
+    ),
+  );
+```
+
+## How it works
+
+- **`Stream.concat`** sequences two streams: `Stream.make(loadingNode)` emits once immediately, then `Stream.fromEffect(effect)` emits the resolved node when the effect completes. The renderer swaps the DOM in place on the second emission.
+- **`Effect.flatMap((data) => h.div(...))`** builds the content node from the data — `h.*` returns a `Node`, which is an `Effect`, so it composes directly in the pipeline.
+- **`Effect.catchAll((error) => node)`** converts the error channel into a fallback node, so the stream always yields something renderable. The failure never escapes to the mount.
+- **Parallel loading is automatic:** place several async components as siblings and their fetches run concurrently — no orchestration needed.
+
+## When to reach for a boundary instead
+
+This is the raw, per-region pattern. When you need **one fallback for several async siblings** (all-or-nothing), use [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense). When the data must be resolved on the **server** and replayed on hydrate without a second request, use [`Boundary.rpc`](https://weftui.dev/docs/how-to/load-data-with-rpc) instead — this recipe is purely client-side.
+
+## Blocking on navigation vs streaming in place
+
+The `Stream.concat` placeholder above lives on a **child** node, so it always streams in after mount — it never delays a navigation commit. If the component above is a route's leaf, moving the `fetchUser` call into the **body** instead changes that:
+
+- **Await in the leaf's own body** — commit-blocking. Navigating to the route pre-runs its component effect to completion before the URL commits: the previous page stays mounted for the fetch, and [`Router.navigating`](https://weftui.dev/docs/reference/router#routernavigating) reports the window.
+- **The `Stream.concat` placeholder pattern above, kept as a child** — streaming. The leaf commits immediately and the region fills in place once the effect resolves.
+
+Choose blocking for **primary route content the page is meaningless without** (an article body, a user's profile) — the old page stays visible with no blank or skeleton. Choose streaming for **secondary or slow regions** where partial content is still useful (a comments panel, a "related" rail) — the commit isn't held hostage by one slow fetch.
+
+See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for rendering pending UI during the blocking window, and the router reference's [Blocking vs streaming data](https://weftui.dev/docs/reference/router#blocking-vs-streaming-data) for the full model.
+
+## See also
+
+- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) — coordinating multiple async regions
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `Stream`/`Effect` as node-producing children
+- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) — the pending signal for the commit-blocking window
+- [examples/async-data-loading](https://github.com/stefvw93/weft/tree/main/examples/async-data-loading) — loading states, retry, parallel and sequential loads with error boundaries

package/docs/how-to/load-data-with-rpc.md

@@ -0,0 +1,172 @@
+---
+title: RPC Data Boundaries
+order: 3
+section: how-to
+description: Boundary.rpc — server-resolved, client-refreshable data; the contract/handler split and the Resource handle's four lifecycles.
+---
+
+# RPC Data Boundaries
+
+`Boundary.rpc` is Weft's primitive for **server-resolved, client-refreshable** data. One [`Rpc`](https://github.com/Effect-TS/effect/tree/main/packages/rpc) from the app's merged `RpcGroup` backs a single render boundary across four lifecycles: server-side render, hydrate-replay, client refetch, and client-first SPA mount. The rpc's `_tag` is the boundary's stable identity and its payload schema the typed input.
+
+## Overview
+
+A `Boundary.rpc` is a **thin consumer**. It carries an rpc, a payload thunk, and a `render` that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea); the renderer resolves the rpc through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam (provided by `@weftui/router`). The same rpc serves every lifecycle, so SSR-replay, refetch, and client-first mount are one mechanism, not three.
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+import { Stream } from "effect";
+import { GetStock } from "./data/inventory";
+
+Boundary.rpc(
+  GetStock, // the rpc — its _tag + schemas drive the boundary
+  () => ({ id: product.id }), // payload thunk — a fresh typed input per call
+  (
+    resource, // render — receives a reactive Resource, not a bare value
+  ) =>
+    h.p([
+      "in stock: ",
+      h.span([Stream.map(resource.value.changes, (s) => String(s.units))]),
+      h.button({ type: "button", onclick: () => resource.refetch }, "Refresh"),
+    ]),
+  { fallback: h.p("loading stock…") }, // shown only on a client-first mount
+);
+```
+
+## The contract / handler split
+
+The rpc **contract** (pure Schema) is shared with the client. The rpc **handler** — the only code that touches server-only services — lives in a Layer the client never imports; tree-shaking keeps it and its transitive imports out of the browser bundle. The split is enforced structurally by which files each entry imports, not by a bundler plugin.
+
+```typescript
+// data/inventory.ts
+import { Rpc, RpcGroup } from "@effect/rpc";
+import { Context, Effect, Layer, Schema } from "effect";
+
+// --- Contract (shareable with the client) ---
+export const Stock = Schema.Struct({ units: Schema.Number });
+export const StockKey = Schema.Struct({ id: Schema.Number });
+
+// `_tag` ("GetStock") = the stable boundary id; payload schema = the typed input.
+export const GetStock = Rpc.make("GetStock", { payload: StockKey, success: Stock });
+
+// The app's merged RpcGroup — shared by both the client and server router wiring.
+export const StockRpcs = RpcGroup.make(GetStock);
+
+// --- Handler (server-only; the client never imports this) ---
+class Inventory extends Context.Tag("Inventory")<
+  Inventory,
+  { readonly stockFor: (id: number) => Effect.Effect<typeof Stock.Type> }
+>() {}
+
+const InventoryLive = Layer.succeed(Inventory, {
+  stockFor: (id) => Effect.succeed({ units: 7 + (id % 5) }),
+});
+
+// `toLayer` binds each rpc to its handler; `Layer.provide` discharges its deps so R = never.
+export const StockLive = StockRpcs.toLayer({
+  GetStock: (payload) => Effect.flatMap(Inventory, (inv) => inv.stockFor(payload.id)),
+}).pipe(Layer.provide(InventoryLive));
+```
+
+Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Tag`) when they might be referenced from universal code: the brand makes a leak into `render` a compile error at the `hydrate` call site rather than a runtime surprise.
+
+## Wiring the router
+
+`Boundary.rpc` resolves through the ambient `AppRpcClientTag` seam, which `@weftui/router` provides on both sides. Pass the **merged group** to both, plus the **handler Layer** on the server.
+
+```typescript
+// entry-server.ts — in-process client over the handlers + POST /_eui/rpc endpoint
+import { RouterServer } from "@weftui/router/server";
+import { StockLive, StockRpcs } from "./data/inventory";
+
+const rpc = { group: StockRpcs, handlers: StockLive } as const;
+
+export const handler = RouterServer.toWebHandler(App, { document: documentShell, rpc });
+export const render = (url: string) =>
+  Effect.runPromise(RouterServer.render(App, { document: documentShell, rpc, url }));
+```
+
+```typescript
+// entry-client.ts — network client posting to /_eui/rpc
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { StockRpcs } from "./data/inventory";
+
+const runtime = ManagedRuntime.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void runtime.runPromise(hydrate(RouterApp(App), root));
+```
+
+- **Server** ([`RouterServer`](https://weftui.dev/docs/reference/router#routerserver)) mounts the handler Layer at `POST /_eui/rpc` (so a client refetch re-runs it on the server) **and** exposes an in-process client over the same handlers for SSR resolution — never a network hop.
+- **Client** ([`RouterLive`](https://weftui.dev/docs/reference/router#routerlive)) provides a network flat rpc client over the merged group, posting to `<origin>/_eui/rpc`.
+
+In a **router-less mount** there is no `AppRpcClientTag`, so a `Boundary.rpc` resolves to a typed, descriptive "needs router/rpc" error (not a defect).
+
+## The four lifecycles
+
+| Lifecycle              | Trigger                                 | What happens                                                                                                                                         |
+| ---------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **SSR**                | server render                           | Resolve the rpc in-process, `successSchema`-encode the result inline as `<script type="application/json">`, render `render(seededResource)` to HTML. |
+| **Hydrate**            | `hydrate` on the client                 | Read the inline payload at the cursor, `successSchema`-decode it, seed the `Resource`, adopt the DOM. **Never re-calls the rpc** (replay).           |
+| **Refetch**            | `resource.refetch`                      | Call the rpc again over `POST /_eui/rpc` (re-runs the handler on the server), patch the subtree in place (stale-on-error).                           |
+| **Client-first mount** | SPA nav into a boundary with no payload | Render `options.fallback`, fork the rpc call, swap in `render(resource)` once it resolves.                                                           |
+
+Because the SSR path seeds `value` await-first (it emits the seed immediately), the SSR HTML and the adopted DOM are byte-identical — there is **no fallback flash** on the SSR/hydrate path. `fallback` shows only on a client-first mount.
+
+## The `Resource` handle
+
+`render` receives a [`Resource<A>`](https://weftui.dev/docs/reference/core#resourcea) (`A` = the rpc's decoded success), not a bare value. After hydrate the region is live:
+
+| Field     | What it gives you                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------------- |
+| `value`   | A `Subscribable` of the current data — seeded with the SSR payload, updated on a successful refetch. |
+| `refetch` | An `Effect<void>` that re-resolves the rpc with a fresh `payload()` and pushes the new `value`.      |
+| `pending` | A `Subscribable<boolean>` — `true` while a refetch is in flight.                                     |
+| `error`   | A `Subscribable<Option<unknown>>` — `Some` with the last refetch error (stale-on-error).             |
+
+```typescript
+(resource) =>
+  h.section({ class: "product" }, [
+    h.span([Stream.map(resource.value.changes, (s) => String(s.units))]),
+    h.span([Stream.map(resource.pending.changes, (p) => (p ? "refreshing…" : ""))]),
+    h.button({ type: "button", onclick: () => resource.refetch }, "Refresh stock"),
+  ]);
+```
+
+Wire `refetch` to an event with `onclick: () => resource.refetch` — the handler returns the Effect, which the renderer runs in a detached fiber. A failed refetch leaves the previous `value` intact (stale-on-error); it does **not** unmount the subtree or raise into a failure `Boundary`.
+
+### Channel algebra
+
+```typescript
+Boundary.rpc<R extends Rpc.Any, C extends Node<any, any>>(
+  rpc: R,
+  payload: () => Rpc.Payload<R>,
+  render: (resource: Resource<Rpc.Success<R>>) => C,
+  options?: { fallback?: Renderable },
+): Node<Node.Error<C> | Rpc.Error<R>, Node.Context<C>>;
+```
+
+- **Error** = `render`'s error union plus the rpc's typed `Rpc.Error<R>` (`never` for an rpc with no `error` schema).
+- **Requirement** = exactly `render`'s `R`, **untouched**. There is no `provide`/`RServer` to discharge (the handler lives in the rpc Layer) and no `Exclude` is applied — a server-only tag leaked into `render` stays in `R`, where `hydrate`'s `AssertNoServerOnly` rejects it.
+
+## Typed-failure replay
+
+If the rpc declares an `error` schema, a resolved rpc **error** on the SSR pass is `errorSchema`-encoded into an inline failure payload, and the nearest enclosing **failure `Boundary`** renders its fallback. On the client, `hydrate` decodes that payload and re-raises the same error into the same boundary, reproducing the identical fallback DOM — flash-free and without re-resolving the rpc (replay, never retry).
+
+```typescript
+Boundary.catchTag({ tag: "OutOfStock", fallback: (e) => h.p({ class: "error" }, e.reason) }, [
+  Boundary.rpc(GetStock, () => ({ id: product.id }), (resource) => /* … */),
+]);
+```
+
+A transport **defect** (no `Cause.failureOption`), or an rpc with no `error` schema, is **not** replayed; it propagates — a server-side fallback and a client mismatch.
+
+## When to use
+
+- **`Boundary.rpc`** — data resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML, then **refreshable** on the client over the same rpc.
+- **`Boundary.suspend`** — async data that loads purely on the client; see the [Boundary API](https://weftui.dev/docs/reference/core#boundarysuspend).
+
+## See also
+
+- [`Boundary.rpc` API reference](https://weftui.dev/docs/reference/core#boundaryrpc) — signature, `Resource`, `RpcOptions`, `AppRpcClientTag`
+- [Server-Side Rendering](https://weftui.dev/docs/how-to/render-on-the-server) — the SSR + hydration model this builds on
+- [Routing](https://weftui.dev/docs/how-to/add-routing) — `@weftui/router`, which provides the `AppRpcClientTag` seam
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable shop with an SSR-replayed, refetchable live-stock `Boundary.rpc`

package/docs/how-to/provide-services.md

@@ -0,0 +1,124 @@
+---
+title: Provide Services
+order: 12
+section: how-to
+description: Provide plain and scoped Layers to a mounted app — the direct mount for value layers, mountScoped plus a shutdown signal for scoped layers, and a ManagedRuntime as an alternative.
+---
+
+# Provide Services
+
+**Goal:** provide a `Layer` to the mounted app so its components can read services with `yield* Service`.
+
+Which recipe to reach for depends on whether the layer has anything to release. A plain value layer (`Layer.succeed`, `Layer.effect` with no `acquireRelease`) can be provided directly at the mount — there is nothing to leak. A **scoped** layer (`Layer.scoped`, anything backed by `acquireRelease`) needs the mount to outlive the effect's own resolution — see [Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) for why.
+
+## Recipe 1 — plain value layers with `mount`
+
+Provide the layer directly around `mount` and run with `runPromise`. This is the common case and needs nothing else.
+
+```typescript
+import { mount } from "@weftui/dom/client";
+import { Effect, pipe } from "effect";
+import { App } from "./app";
+import { ThemeServiceLive } from "./theme-service";
+
+const root = document.getElementById("root")!;
+
+const program = pipe(mount(App(), root), Effect.provide(ThemeServiceLive));
+
+Effect.runPromise(program);
+```
+
+## Recipe 2 — scoped layers with `mountScoped`
+
+Provide the scoped layer **outside** a long-lived scoped region, mount inside that region with `mountScoped`, and keep the region open with `Effect.never` or `Deferred.await` on a shutdown signal. Drive the whole thing with `runFork`, not `runPromise` — the program never settles on its own.
+
+```typescript
+import { mountScoped } from "@weftui/dom/client";
+import { Deferred, Effect, Fiber, pipe } from "effect";
+import { App } from "./app";
+import { AppLive } from "./app-live";
+
+const root = document.getElementById("root")!;
+
+const program = pipe(
+  Effect.scoped(
+    Effect.gen(function* () {
+      yield* mountScoped(App(), root);
+      yield* Effect.never; // keeps the region — and AppLive — alive
+    }),
+  ),
+  Effect.provide(AppLive), // OUTSIDE the scoped region: outlives initial render
+);
+
+const fiber = Effect.runFork(program);
+
+// later, e.g. on a "sign out" action or test teardown:
+// await Effect.runPromise(Fiber.interrupt(fiber));
+```
+
+Interrupting `fiber` closes the inner scope first — running `mountScoped`'s finalizer, which calls `unmount` — and only then releases `AppLive`. Swap `Effect.never` for `Deferred.await(shutdown)` when something in the app should be able to request shutdown itself:
+
+```typescript
+const shutdown = await Effect.runPromise(Deferred.make<void>());
+
+const program = pipe(
+  Effect.scoped(
+    Effect.gen(function* () {
+      yield* mountScoped(App(), root);
+      yield* Deferred.await(shutdown); // resolves when shutdown is signalled
+    }),
+  ),
+  Effect.provide(AppLive),
+);
+Effect.runFork(program);
+
+// elsewhere, to request shutdown:
+// await Effect.runPromise(Deferred.succeed(shutdown, undefined));
+```
+
+`hydrateScoped` is the SSR counterpart — same composition, swap `mountScoped` for `hydrateScoped`.
+
+## Recipe 3 — `ManagedRuntime` with plain `mount`
+
+Build a `ManagedRuntime` from the scoped layer and mount with plain `mount`, running through the runtime instead of `Effect.runPromise` directly. The layer lives until `runtime.dispose()` — an explicit call, rather than a scope closing.
+
+```typescript
+import { mount } from "@weftui/dom/client";
+import { ManagedRuntime } from "effect";
+import { App } from "./app";
+import { AppLive } from "./app-live";
+
+const root = document.getElementById("root")!;
+const runtime = ManagedRuntime.make(AppLive);
+
+await runtime.runPromise(mount(App(), root));
+
+// later:
+// await runtime.dispose();
+```
+
+This reads closer to Recipe 1 at the call site and is a good fit when the surrounding app (a framework integration, a test harness) already manages a runtime's lifecycle for you.
+
+## Anti-patterns
+
+Both of these compile and both dispose the scoped layer while the app is still running — the mounted tree keeps its subscriptions and handlers, but they now read from a released service.
+
+```typescript
+// ❌ plain mount: the layer releases the instant runPromise settles
+Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
+```
+
+```typescript
+// ❌ mountScoped, but the scoped region closes as soon as the mount effect
+// resolves — nothing keeps it open, so this is no better than plain mount
+Effect.runPromise(mountScoped(App(), root).pipe(Effect.provide(SomeScopedLayer), Effect.scoped));
+```
+
+In both cases the tell is the same: nothing in the composition keeps a scope open past the point where the mount Effect itself resolves. Recipe 2's `Effect.never` (or `Deferred.await`) is doing the one piece of work these anti-patterns are missing.
+
+## See also
+
+- [Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) — why the mount effect resolving early matters for scoped layers
+- [Services and Context](https://weftui.dev/docs/explanation/services-and-context) — how `R` accumulates and discharges at the mount
+- [`mountScoped` / `hydrateScoped` reference](https://weftui.dev/docs/reference/dom#mountscoped) — signatures and error unions
+- [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) — a real scoped layer (`Registry.layer`) mounted with this composition

package/docs/how-to/render-keyed-lists.md

@@ -0,0 +1,51 @@
+---
+title: Render Keyed Lists
+order: 5
+section: how-to
+description: Render a reactive collection with List.each so reordering, inserting, and removing items reuses and moves existing DOM instead of rebuilding the region.
+---
+
+# Render Keyed Lists
+
+**Goal:** render a list whose items reorder, insert, or remove over time, without rebuilding the whole region (which would lose focus, scroll, and input state in the surviving rows).
+
+Use [`List.each`](https://weftui.dev/docs/reference/core#listeach), the keyed-list combinator. It renders each item **once per key** and reconciles across emissions — a reorder _moves_ existing DOM nodes, an insert adds one, a remove drops one, and untouched rows are left entirely alone.
+
+```typescript
+import { h, List } from "@weftui/core";
+import { Stream } from "effect";
+
+declare const rows: Subscribable.Subscribable<ReadonlyArray<{ id: number; name: string }>>;
+
+h.ul([
+  List.each(
+    { of: rows.changes, by: (row) => row.id }, // key by stable identity
+    (row) => h.li(row.name),
+  ),
+]);
+```
+
+- **`of`** — the list source: any `Stream`, `Effect`, or `Subscribable` of an `Iterable`. Each emission is materialized to an array to fix order, then reconciled by key.
+- **`by`** — projects each item to its reconciliation key, compared via Effect's `Equal`/`Hash`. Omit it and the item itself is the key (structural for `Data`, by reference otherwise).
+
+## Why not `map`?
+
+Mapping items by hand — `Stream.map(rows.changes, (rs) => rs.map(r => h.li(r.name)))` — produces a **new children array on every emission**, so the renderer rebuilds the whole region: every row's DOM node is recreated even if only one item moved. `List.each` reconciles by key instead, so DOM identity (and the focus/scroll/typed-input state attached to it) survives across updates.
+
+## Refresh a row's content
+
+Because `render` runs **exactly once per key**, reconciliation never re-runs it for a kept row — so it never refreshes that row's content on its own. To make a row's content reactive, thread a `Stream` **inside** the row rather than expecting a re-render:
+
+```typescript
+List.each({ of: rows.changes, by: (row) => row.id }, (row) =>
+  h.li([h.span([Stream.map(row.status.changes, (s) => s)])]),
+);
+```
+
+> **⚠️ Index-key footgun.** Keying by index (`by: (_, i) => i`) reuses rows positionally, so after a reorder each position keeps its old content and you see stale rows. Prefer a stable identity key (`by: (item) => item.id`).
+
+## See also
+
+- [`List.each` API reference](https://weftui.dev/docs/reference/core#listeach) — full signature, `List.Options`, and the descriptor shape
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the stream-shaped sources `of` accepts
+- [examples/keyed-list](https://github.com/stefvw93/weft/tree/main/examples/keyed-list) — a runnable keyed list with reordering and a browser test

package/docs/how-to/render-on-the-server.md

@@ -0,0 +1,86 @@
+---
+title: Server-Side Rendering
+order: 2
+section: how-to
+description: renderToString / renderToStringHydratable / streaming variants, hydrate, and the server/client split.
+---
+
+# Server-Side Rendering
+
+Weft renders on the server and **hydrates** on the client: the server produces HTML (plus inline data), and the browser adopts that existing DOM in place rather than re-creating it. [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) extends this to **rpc-backed server data** — resolve an rpc on the server, serialize its result into the HTML, replay it on the client without a second request, and then keep the region live for refetch.
+
+## The two halves
+
+- **Server** — `@weftui/dom/server` renders an app node to an HTML string (or stream). The _hydratable_ variants additionally emit the inline data each reactive region and `Boundary.rpc` needs to resume on the client.
+- **Client** — `@weftui/dom/client`'s `hydrate` walks the server DOM, adopts it, wires up reactivity and event handlers, and resumes from the inline data. It does **not** re-render from scratch.
+
+```typescript
+// server entry
+import { renderToStringHydratable } from "@weftui/dom/server";
+import { Effect } from "effect";
+import { App } from "./app";
+
+export const render = (): Promise<string> => Effect.runPromise(renderToStringHydratable(App()));
+```
+
+```typescript
+// client entry
+import { hydrate } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+
+const root = document.getElementById("root")!;
+void Effect.runPromise(hydrate(App(), root));
+```
+
+The same side-effect-free `App` is imported by both entries — splice the server HTML into your template's outlet, ship it, and let the client entry hydrate it.
+
+`@weftui/dom/server` exports four renderers:
+
+|                                        | String                     | Stream                     |
+| -------------------------------------- | -------------------------- | -------------------------- |
+| **Plain** (no JS / no hydration)       | `renderToString`           | `renderToStream`           |
+| **Hydratable** (emits inline payloads) | `renderToStringHydratable` | `renderToStreamHydratable` |
+
+Use a hydratable renderer whenever the client will call `hydrate`. The plain renderers produce complete, JS-free HTML with no payload scripts.
+
+## Loading server data with `Boundary.rpc`
+
+SSR's natural companion is `Boundary.rpc`: it resolves an rpc **on the server**, serializes the result into the same HTML this page produces, and replays it on the client during `hydrate` — no second request, no fallback flash — then keeps the region live for `refetch`. It is the data half of the same server/client split described above: the rpc **contract** (pure Schema) is shared, while its **handler** lives in a server-only Layer the client never imports.
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+import { Stream } from "effect";
+import { GetStock } from "./data/inventory";
+
+const StockPanel = (productId: number) =>
+  Boundary.rpc(
+    GetStock,
+    () => ({ id: productId }), // a fresh typed payload per call (SSR / refetch / mount)
+    (resource) =>
+      h.p([
+        "in stock: ",
+        h.span([Stream.map(resource.value.changes, (stock) => String(stock.units))]),
+        h.button({ type: "button", onclick: () => resource.refetch }, "Refresh"),
+      ]),
+    { fallback: h.p("loading stock…") }, // shown only on a client-first SPA mount
+  );
+```
+
+Under SSR the server resolves the rpc in-process, `successSchema`-encodes the result inline as `<script type="application/json">`, and renders in place; `hydrate` reads that payload positionally, seeds the `Resource`, and adopts the DOM **without re-calling the rpc** (replay, never retry). The full model — the contract/handler split, router wiring, the four lifecycles, the `Resource` handle, and typed-failure replay — lives in one place: the [RPC Data Boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc). This page does not repeat it.
+
+> **Note.** `Boundary.rpc` resolves through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam, which `@weftui/router` provides on both sides. In a router-less mount there is no seam, so the boundary resolves to a descriptive "needs router/rpc" error (not a defect).
+
+## When to use
+
+- **`Boundary.rpc`** — data that must be resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML, then **refreshable** on the client (refetch / client-first SPA mount) over the same rpc.
+- **`Boundary.suspend`** — async data that loads on the client (or streams the shell then fills); see the [Boundary API](https://weftui.dev/docs/reference/core#boundarysuspend).
+
+## See also
+
+- [rpc data boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc) — the full `Boundary.rpc` walkthrough: contract/handler split, router wiring, the four lifecycles, and typed-failure replay
+- [Routing](https://weftui.dev/docs/how-to/add-routing) — `@weftui/router` builds on this SSR + hydration model for full-page nested routing
+- [`Boundary.rpc` API reference](https://weftui.dev/docs/reference/core#boundaryrpc)
+- [`ServerTag` API reference](https://weftui.dev/docs/reference/core#servertag)
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable shop with an SSR-replayed, refetchable live-stock `Boundary.rpc`
+- [examples/ssr-hydration](https://github.com/stefvw93/weft/tree/main/examples/ssr-hydration) — SSR + hydration without server data loading

package/docs/how-to/show-navigation-progress.md

@@ -0,0 +1,65 @@
+---
+title: Show Navigation Progress
+order: 7
+section: how-to
+description: Render a pending indicator (e.g. a top progress bar) during a deferred-commit navigation by reading the router's Router.navigating signal.
+---
+
+# Show Navigation Progress
+
+**Goal:** show a progress indicator while a [lazy route](https://weftui.dev/docs/how-to/split-routes-lazily) resolves its chunk and data, so a slow network is visible instead of feeling frozen.
+
+When you navigate to a route, the router is **deferred-commit**: it resolves the target branch's chunk (if the component is `Router.lazy`) **and the matched leaf's own component effect** — including any data the leaf awaits in its body — _before_ swapping the URL, keeping the previous page mounted for the whole window. That resolve window is exposed as a reactive signal, [`Router.navigating`](https://weftui.dev/docs/reference/router#routernavigating), that you read to render pending UI.
+
+```typescript
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { Stream } from "effect";
+
+const Shell = Component.gen(function* () {
+  const outlet = yield* Router.Outlet;
+  const nav = yield* Router.navigatingStream;
+  return yield* h.div({ id: "app" }, [
+    h.div({
+      id: "nav-progress",
+      "aria-hidden": "true",
+      class: Stream.map(nav.changes, (s) =>
+        s._tag === "Navigating" ? "nav-progress is-navigating" : "nav-progress",
+      ),
+    }),
+    h.main([outlet]),
+  ]);
+});
+```
+
+Thread the signal into a persistent layout (the outermost `Shell` is ideal, since it never re-renders across navigations), and style the pending class however you like — a top bar, a cursor change, a dimmed outlet.
+
+## The signal
+
+`NavState` is a two-state machine:
+
+```typescript
+type NavState = { readonly _tag: "Idle" } | { readonly _tag: "Navigating"; readonly to: string };
+```
+
+Read it two ways, mirroring `Router.params` / `Router.paramsStream`:
+
+- `Router.navigating` — the `Subscribable<NavState>` on the `Router` service.
+- `Router.navigatingStream` — an `Effect` resolving that `Subscribable`, for use in a `Component.gen` body (as above).
+
+The `to` field on `Navigating` is the target URL, if you want to label _where_ the app is going.
+
+## Behavior to expect
+
+- **Only navigations with real async work flip it.** A branch with no `Router.lazy` node and a leaf whose effect resolves synchronously (no async work, or a memoized revisit) commits in the same tick, and `navigating` stays `Idle` — an entirely eager app never sees `Navigating`, and adding the reader costs nothing.
+- **Latest-wins.** Rapid successive navigations commit only the newest; a superseded navigation never resets the signal (the newer one owns it).
+- **Back/forward.** `popstate` into a route with async work also resolves before committing, so the indicator shows for browser back/forward too.
+- **Failure resets it.** A rejected chunk load or a failing leaf pre-run (a typed error such as `notFound()`, or a defect) resets `navigating` to `Idle` (it never sticks on), then surfaces through normal error/defect handling.
+- **Server renders `Idle`.** Server render is buffered, so `navigating` is a client-only concern; the server supplies a constant `Idle` so the same `Shell` type-checks and renders on both sides.
+- **No built-in anti-flash delay.** The signal flips as soon as an async window opens, so a borderline-fast navigation can flash the indicator briefly. If you want to only show it past a threshold, delay the reveal in CSS rather than in the signal — e.g. `transition-delay: 200ms` on `.is-navigating` — so genuinely fast navigations never flicker.
+
+## See also
+
+- [`Router.navigating` API reference](https://weftui.dev/docs/reference/router#routernavigating)
+- [Split Routes Lazily](https://weftui.dev/docs/how-to/split-routes-lazily) — the `Router.lazy` deferred-commit navigation this reports on
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — wires this exact progress bar in its `Shell` (`components/shell.ts`), with a `pending-navigation.browser.test.ts`

package/docs/how-to/split-routes-lazily.md

@@ -0,0 +1,62 @@
+---
+title: Split Routes Lazily
+order: 6
+section: how-to
+description: Code-split a route's component into its own chunk with Router.lazy, keeping the descriptor eager so matching, href, and SSR stay unchanged.
+---
+
+# Split Routes Lazily
+
+**Goal:** keep a heavy page's render code (and its dependencies) out of the initial bundle, loading it only when its route is actually rendered.
+
+Wrap the route's `component` in [`Router.lazy`](https://weftui.dev/docs/reference/router#routerlazy). The route **descriptor** (its segment and param schemas) stays eager so the matcher, `href`, and the server's dispatch API still see it statically — only the component body is split into its own chunk.
+
+```typescript
+import { Router } from "@weftui/router";
+import { Schema } from "effect";
+
+Router.route("docs/:category/:slug", {
+  path: { category: Schema.String, slug: Schema.String },
+  component: Router.lazy(() => import("./doc-page").then((m) => m.DocPage)),
+});
+```
+
+The chunk loads on the server during render and on the client on navigation; only the **matched branch's** chunks are ever fetched. `E`/`R` are preserved — a lazy route has the exact same channels as the same component declared eagerly, so an unmet service requirement is still a compile error at `Router.router(...)`.
+
+## Make the split real
+
+`Router.lazy` only splits if the dynamic `import()` is the **only eager path** to the heavy module. Keep the `Router.route(…)` descriptor in an eagerly-imported file, and move the component implementation (and its heavy deps) into a separate module referenced _only_ through `Router.lazy(() => import("./impl"))`:
+
+```typescript
+// routes.ts — eager, tiny: just the descriptor
+export const docsRoute = Router.route("docs/:category/:slug", {
+  path: { category: Schema.String, slug: Schema.String },
+  component: Router.lazy(() => import("./doc-page-impl").then((m) => m.DocsPage)),
+});
+
+// doc-page-impl.ts — heavy: pulled into its own chunk, never in the initial graph
+export const DocsPage = Component.gen(function* () {
+  /* renderHast, code highlighting, … */
+});
+```
+
+A descriptor file that still `import`s the impl statically gains nothing — the bundler keeps it in the initial graph.
+
+## What you get for free
+
+- **Flash-free hydration.** On a directly-loaded lazy route, the client re-invokes the same slot, awaits the chunk, and adopts the server DOM in place — the first production matches, so nothing is mutated.
+- **Blank-free navigation.** Client navigation is **deferred-commit**: the router resolves the target branch's chunk **and the matched leaf's own component effect** _before_ committing the URL, so the previous page stays mounted through both the fetch and any data the leaf awaits, and the swap is a single tick. See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for the `Router.navigating` signal this exposes.
+- **Synchronous revisits.** `Router.lazy` memoizes its load per slot, so a second visit to a loaded route commits immediately.
+
+## Edge cases
+
+- **Lazy layouts.** A `Router.layout({ component: Router.lazy(...) })` splits too — each lazy node in the matched branch is awaited; nodes outside it never load.
+- **Chunk-load failure is a defect.** If the `import()` rejects (offline, or a stale client requesting a chunk a new deploy removed), it dies as a defect and surfaces through normal defect handling — it never hangs or silently 404s. The rejection is memoized, so the route keeps failing until a reload (the deploy-skew case).
+- **Not a lazy _subtree_.** Only the component is lazy; you cannot defer a whole `RouteNode` behind an `import()`, because the matcher needs every leaf's segment and param schema before anything loads.
+
+## See also
+
+- [`Router.lazy` API reference](https://weftui.dev/docs/reference/router#routerlazy)
+- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) — the deferred-commit `Router.navigating` signal
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — authoring the route tree `Router.lazy` plugs into
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — includes a `Router.lazy` page (`lazy-page.ts`) with a browser test