@weftui/dom 0.26.0 → 0.26.2

package/docs/explanation/rendering-model.md

@@ -0,0 +1,65 @@
+---
+title: The Rendering Model
+order: 1
+section: explanation
+description: Why Weft has no virtual DOM — nodes are Effects, streams are the live thread woven through a static tree, and hydration adopts server DOM in place.
+---
+
+# The Rendering Model
+
+Weft renders UI by **weaving streams through a static tree**. There is no virtual DOM, no diff, no reconciler comparing two trees each frame. This page explains the model that makes that work — and why it falls out of one definition.
+
+## Nodes are Effects
+
+The whole library rests on a single equation:
+
+```typescript
+type Node<E = never, R = never> = Effect.Effect<ElementDescriptor, E, R>;
+```
+
+Every element in a Weft tree **is an Effect**. `h.div(...)`, a component's return value, a boundary — each is an `Effect` that, when run, produces an element descriptor. Two consequences follow immediately, and they shape everything else:
+
+1. **The error (`E`) and requirement (`R`) channels accumulate through the tree.** A child that reads a service, or a prop backed by a failible stream, contributes its `R` and `E` to its parent, which contributes to _its_ parent, up to the mount boundary. The type of your app node is the exact union of everything it needs and everything it can fail with — visible to the type checker, satisfiable exactly once, at `mount`/`hydrate`. See [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) for how the accumulation works mechanically.
+2. **Every Effect combinator applies to a node directly.** `Effect.provide`, `Effect.flatMap`, `Effect.gen`, `Effect.catchAll` — none of them are special-cased for UI. A node is an ordinary Effect, so the entire Effect ecosystem composes with your view for free.
+
+JSX collapses every component to an opaque `JSX.Element`, erasing both channels. Weft keeps them, and that is the point of the whole design. (There is [no JSX](https://weftui.dev/docs/explanation/combinator-api) here — components are plain functions you _call_.)
+
+## Warp and weft
+
+The name is the metaphor. On a loom, the **warp** is the set of fixed threads held under tension; the **weft** is the live thread drawn back and forth across them to form the cloth.
+
+- Your **component tree is the warp** — the structure, fixed for the lifetime of a mounted region.
+- **Streams are the weft** — the live values drawn across that structure. A `Stream`, `Effect`, or `Subscribable` used as a prop value or child is a thread woven through a specific point in the tree.
+
+When a stream emits, only the DOM at _that_ point updates. Nothing above it re-runs; no sibling is touched; there is no tree to diff because the structure never changed — only a value threaded through one hole in it did. This is why Weft needs no virtual DOM: **the reactivity is local by construction.** The vocabulary of stream-shaped values (and how their channels flow) is [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives).
+
+> **Note.** "Only that point updates" is the default, not a manual optimization. You do not memoize regions or declare dependencies — a value is reactive exactly where you thread a stream, and static everywhere else.
+
+## Streams drive all updates
+
+There is no `setState`, no render-triggering scheduler, no "re-render this component." A region of the DOM is live **if and only if** a stream is woven into it. To make something update, you thread a stream through it; to keep something static, you pass a plain value. The renderer subscribes to each woven stream and patches its target in place on every emission — reusing the existing DOM node, patching text and attributes rather than recreating elements (identity, focus, and typed input survive an update).
+
+This also fixes the update _shape_. Because the structure is fixed, an update is always "new value into a known hole," never "reconcile these two trees." Even list rendering — where the number of children genuinely varies — is expressed as a keyed region ([`List.each`](https://weftui.dev/docs/how-to/render-keyed-lists)) that reconciles by key rather than by structural diff.
+
+## One tree, two sides, hydrate in place
+
+The same component tree renders on the server and the client:
+
+- On the **server**, the tree renders to an HTML string (or a streaming response) via `@weftui/dom/server`. The _hydratable_ renderers additionally emit the inline data each reactive region needs to resume.
+- On the **client**, `hydrate()` walks that server-rendered DOM and **adopts it in place** — it wires up reactivity and event handlers on the existing nodes rather than re-rendering. The first client production matches the adopted DOM exactly, so nothing is mutated and there is no flash.
+
+Because the same `Node<E, R>` describes both passes, there is nothing to keep in sync: the server output and the client's first render are the _same tree_ run in two environments. Services flow from the mount (or the router's render-time context) through the tree to wherever a component reads them, on both sides. The mechanics of the two-sided render live in [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server); the service flow is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
+
+## Why this matters
+
+- **No diff cost.** Updates are O(changed value), not O(tree). There is no reconciliation pass to pay for.
+- **Local reasoning.** A stream woven at one point cannot affect another. What is reactive is exactly what you made reactive.
+- **Type-honest edges.** The app node's `E`/`R` is the whole app's error and dependency surface, checked at compile time and discharged once at the edge.
+- **Flash-free SSR by construction.** Hydration adopts rather than replaces, because the tree is identical on both sides.
+
+## See also
+
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how `E`/`R` accumulate; why `Node` is an `Effect`; `h` and components
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the stream-shaped values you weave through the tree
+- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) — how failure and async are modeled as nodes in the same tree
+- [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server) — the server/client split and `hydrate`

package/docs/explanation/services-and-context.md

@@ -0,0 +1,91 @@
+---
+title: Services and Context
+order: 5
+section: explanation
+description: How Effect services reach components — the requirement channel, discharging R at the mount, the router's render-time context seam, and ServerTag server-only brands.
+---
+
+# Services and Context
+
+Weft has no separate dependency-injection system. It uses Effect's — a component that needs a service reads it with `yield* Service`, and because [a node is an Effect](https://weftui.dev/docs/explanation/rendering-model), that requirement rides the node's `R` channel up the tree to a single point where you provide it. This page explains how a service travels from where you provide it to where a component reads it, and the two seams that make that work across the server/client boundary.
+
+## R accumulates, then discharges once
+
+When a component does `yield* ThemeService`, `ThemeService` enters that node's requirement channel. It accumulates through every parent — a boundary, a layout, the app node — until the whole tree's `R` is the union of everything any component needs. You satisfy it in **one** place, at the edge:
+
+```typescript
+import { Effect } from "effect";
+import { mount } from "@weftui/dom/client";
+
+const handle = pipe(
+  mount(App(), document.getElementById("root")!),
+  Effect.provide(ThemeServiceLive),
+);
+```
+
+Provide too little and it is a compile error at the mount call — the type of `App()` names exactly which service is missing. This is the same discipline as any Effect program: `R` is a promise the type checker holds you to, discharged at the program's boundary, not sprinkled through the tree.
+
+Services flow **down** from that provide point to every reader, including across reactive boundaries: a stream woven into a prop carries its own `R`, and a handler that reads a service resolves it from the same context. There is no prop-drilling and no context-provider component — the requirement channel _is_ the wiring.
+
+## Layer lifetime at the mount
+
+The `ThemeServiceLive` example above works because `mount`'s effect and the service's lifetime coincide by accident: `ThemeServiceLive` is a plain value layer with nothing to release, so it makes no difference whether it is "alive" for one tick or the whole session. That accident stops holding the moment the layer is **scoped** — built with `Layer.scoped`, backed by an `acquireRelease` — because `mount`'s effect resolves right after the tree's **initial render**, not when the app stops running. Streams, event handlers, and forked work all keep running on the mount's runtime long after that Effect has settled.
+
+`Effect.provide(scopedLayer)` is `acquireUseRelease` sugar: acquire, run the wrapped effect, then release **when that effect completes**. Wrap it directly around `mount`, and the release runs at mount-resolve — while the mounted tree is still reading from the now-disposed service:
+
+```typescript
+// ❌ the layer's finalizers run the instant runPromise settles, while the
+// mounted tree keeps running — every subscription now reads a disposed service
+Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
+```
+
+This is exactly what happened with effect-atom's `Registry.layer` in the [`effect-atom` example](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) (issue #122): every atom-driven region rendered empty, with no error, because the registry the streams read from had already been disposed.
+
+The fix is to give the scoped layer a lifetime that matches the app, not the initial render: provide it **outside** a scoped region that stays open for as long as the app should run, and mount inside that region with `mountScoped` (which ties `unmount` to the region's scope instead of to the resolution of the mount effect). An `Effect.never` (or `Deferred.await` on a shutdown signal) keeps the region — and therefore the layer — alive until something explicitly closes it. See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for the recipe, including the `ManagedRuntime` alternative when a scoped region isn't a good fit.
+
+## The router's render-time context seam
+
+A plain `mount`/`hydrate` discharges `R` at the call site. But under `@weftui/router`, the tree does not render in the context of the effect that called `render` — each request dispatches through platform's HTTP layer in its own managed context, and the reactive outlet drains in the top render context, not in any intermediate node's. Providing a service _ambiently_ around the render would be lost before it reached a route component.
+
+So the router exposes an explicit **`context` seam** — a `Layer` threaded to the document shell and every route, layout, and leaf:
+
+```typescript
+class Greeting extends Context.Tag("Greeting")<Greeting, { text: string }>() {}
+
+// server entry
+RouterServer.render(App, { document, url, context: Layer.succeed(Greeting, { text: "hi" }) });
+
+// client entry — same seam, so the hydrated tree reads the same services
+RouterLive(App, { context: DocsLive });
+```
+
+The seam is **symmetric** (same shape on both sides) and **type-tracked**: the def's aggregate residual `R` is discharged here, so a missing provide is a compile error rather than a runtime 500. The residual is `AppServices<R>` — the def's `R` minus what the router itself threads (`Router`, `Router.Outlet`, `AppRpcClientTag`). An app with no app-services needs no `context`; a loosely-typed `RouterDef<any, any>` may omit it. This is how the website provides its `Docs` service to every page — see [Add Routing](https://weftui.dev/docs/how-to/add-routing).
+
+## Server-only services: `ServerTag`
+
+Some services must _never_ run in the browser — a database handle, a private credential, an rpc handler's backing store. Declare those with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) instead of `Context.Tag`. It behaves exactly like `Context.Tag`, but its identifier carries a **server-only brand**.
+
+The brand's job is to turn a leak into a **compile error at the `hydrate` call site**. A `Boundary.rpc` handler legitimately reads server-only services on the server, but they must not survive into client code: since `render` only ever touches the _decoded result_ (never the service), a correctly-written boundary keeps its output `R` free of the brand. If a branded tag ever leaks into `render` and reaches the client requirement channel, `hydrate`'s `AssertNoServerOnly` resolves `R` to a compile-error sentinel — you learn at build time, not from a runtime defect.
+
+```typescript
+import { ServerTag } from "@weftui/core";
+
+// Only ever provided on the server; a leak into client code fails to compile.
+class Db extends ServerTag("Db")<Db, { query: (sql: string) => Effect.Effect<Row[]> }>() {}
+```
+
+## The whole picture
+
+- A component reads a service with `yield* Service`; the requirement enters `R`.
+- `R` accumulates through the tree and is discharged **once** — at `mount`/`hydrate`, or through the router's `context` seam.
+- The same services flow to the same components on the server and the client, because it is the same tree.
+- `ServerTag` brands the services that must stay server-side, enforced at the `hydrate` boundary.
+
+## See also
+
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why services flow through the tree at all
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how `R` accumulates from children and reactive props
+- [Provide Services](https://weftui.dev/docs/how-to/provide-services) — recipes for value layers, scoped layers with `mountScoped`, and `ManagedRuntime`
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — providing app services through the router `context` seam
+- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc) — where `ServerTag` and the rpc handler Layer meet
+- [`ServerTag` API reference](https://weftui.dev/docs/reference/core#servertag)

package/docs/how-to/add-routing.md

@@ -0,0 +1,296 @@
+---
+title: Routing
+order: 4
+section: how-to
+description: "@weftui/router — universal nested routing, Router.route / Router.layout / Router.router, type-safe href, layouts, and programmatic navigation."
+---
+
+# Routing
+
+`@weftui/router` is a universal (server + client) nested router for Weft. It maps a URL to a rendered `Node` tree on both sides:
+
+- **Server** — matches an incoming request path, renders the matched nested page to hydratable HTML, and responds with `text/html` (HTTP 404 for not-found).
+- **Client** — matches `window.location`, swaps pages reactively via the History API, and keeps unchanged ancestor layouts mounted across navigations.
+
+The package mirrors `@weftui/dom`: a shared (universal) root, a `./client` entry, and a `./server` entry.
+
+```bash
+npm install @weftui/router
+```
+
+## The mental model
+
+A route's **component is its handler** — a page is a component that renders, and its `component` slot is invoked at render time on whichever side the request arrives. Server-resolved data stays with [`Boundary.rpc`](https://weftui.dev/docs/how-to/load-data-with-rpc); client-side async stays with `Boundary.suspend`.
+
+You author an **explicit nested route tree** with three namespaced combinators — mirroring the `h.div` / `Component.gen` / `Boundary.catchTag` surface — and seal it once:
+
+| Combinator                                            | Builds                                                            |
+| ----------------------------------------------------- | ----------------------------------------------------------------- |
+| `Router.route(segment, { path?, query?, component })` | A leaf page.                                                      |
+| `Router.layout({ component }, children)`              | A layout that wraps an outlet (purely UI nesting — owns no path). |
+| `Router.router(root, { notFound })`                   | Seals the tree into a `RouterDef`.                                |
+
+The tree is the source of truth. The same sealed `RouterDef` drives both server and client.
+
+## Authoring routes
+
+Every `component` slot is a **`ComponentSlot`** — a callable producing a `Node`, passed **uncalled**. Use [`Component.make` / `Component.gen`](https://weftui.dev/docs/how-to/author-components) (or a plain `() => Node` thunk). The router invokes it at render time, which is what lets `href(…)` resolve after the tree is compiled.
+
+```typescript
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { Schema } from "effect";
+
+const About = Router.route("about", {
+  component: Component.make(() => h.h1("About")),
+});
+
+const User = Router.route("users/:id", {
+  path: { id: Schema.NumberFromString },
+  component: Component.gen(function* () {
+    const { id } = yield* Router.params({ id: Schema.NumberFromString });
+    return yield* h.div(`User ${id}`);
+  }),
+});
+```
+
+- **`segment`** is relative to the parent and may contain `:name` path-param placeholders (e.g. `"users/:id"`). A leading/trailing `/` is tolerated. Each leaf carries its full relative path (e.g. `"users/:id/settings"`).
+- **`path` / `query`** are `Schema.Struct.Fields` (a record of `name → Schema`), declared **only on routes**. The compiler covers every `:name` placeholder in `pathSchema`, defaulting to `Schema.String` when a placeholder has no declared field. Query fields are optional by default.
+
+> Authoring components with `Component.make` / `Component.gen` keeps every slot fully typed: the router never sees a `Node<any, any>`, and each component's `E`/`R` channels aggregate up through `Router.layout` / `Router.router` into the sealed `RouterDef`.
+
+## Reading the match: handler-arg props vs. injection
+
+A leaf page reads the current match's decoded `path` / `query` in **either** of two forms.
+
+### Handler-arg props (leaf pages)
+
+The router passes the decoded `{ path, query }` straight into a leaf `component` as props (typed `RouteHandlerProps<Path, Query>`, inferred from the route's `path` / `query` fields). No `Router` access, no validation step — just read the props:
+
+```typescript
+const idParam = { id: Schema.NumberFromString };
+const sortQuery = { sort: Schema.optional(Schema.String) };
+
+Router.route("users/:id/posts", {
+  path: idParam,
+  query: sortQuery,
+  // `path.id` is already a number; `query.sort` is `string | undefined`.
+  component: ({ path, query }) =>
+    h.section([h.h2(`Posts for user ${path.id}`), h.p(`sort: ${query.sort ?? "none"}`)]),
+});
+```
+
+This is the most direct form for a leaf. A plain zero-arg thunk works too — it just ignores the props.
+
+### Dependency injection (layouts and deep nodes)
+
+A **layout** sits above the leaf and so can't take handler args; it reads the match by **dependency injection** instead. `Router.params(fields)` / `Router.query(fields)` are readable from **any** component:
+
+```typescript
+// A /users/:id layout (above the leaf) reads `:id` by injection.
+const UserShell = Component.gen(function* () {
+  const { id } = yield* Router.params(idParam);
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ class: "user" }, [h.h1(`User ${id}`), outlet]);
+});
+```
+
+`Router.params(fields)` / `Router.query(fields)` read the live match and pick the requested `fields` keys (already decoded by the matcher, so no re-validation). They return the typed values, or fail with a tagged [`RouterParamsError`](#errors) (carrying `source: "path" | "query"` and the requested `keys`) when no route matches. That error bubbles into the app node's aggregate `E`, so a user may recover it with `Boundary.catchTag("RouterParamsError", …)`.
+
+> **Reactive accessors.** `Router.paramsStream(fields)` / `Router.queryStream(fields)` are the reactive counterparts — each resolves a `Subscribable` derived from `currentMatch.changes`, so a component can render `[(yield* Router.queryStream(sortQuery)).changes]` and update **in place** even when the same leaf stays mounted (the query-only case `Router.query` would miss). See [Programmatic navigation](#programmatic-navigation).
+
+## Layouts and the outlet
+
+A **layout** wraps the next level down — the **outlet** — which is also delivered by injection. A layout reads it with `yield* Router.Outlet` and places it like any `h`-style child:
+
+```typescript
+const UserShell = Component.gen(function* () {
+  const { id } = yield* Router.params(idParam);
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ class: "user" }, [h.h1(`User ${id}`), outlet]);
+});
+
+Router.layout({ component: UserShell }, [settingsRoute, postsRoute]);
+```
+
+`Router.Outlet` is typed **opaque** (`Node<never, never>`), so splicing it adds nothing to the layout's own channels — the subtree's real `E`/`R` are aggregated structurally by `Router.layout`. The router discharges the `Outlet` requirement at render time, so it never appears in a layout's (or the sealed app's) aggregate requirement channel.
+
+A layout owns **no `segment` or `path`** — all path structure lives on routes. A layout that needs a param simply reads it via `Router.params`.
+
+### Layout persistence
+
+Each nesting level renders as a reactive stream child keyed by `(pattern + the param values that level depends on)` and `dedupe`d. An unchanged ancestor layout therefore **stays mounted** across a navigation that only changes a deeper level: its DOM identity and any local state (a `SubscriptionRef`, a scroll position) survive while only the inner outlet swaps.
+
+## Sealing the tree
+
+`Router.router(root, { notFound })` compiles the tree eagerly (stamping leaf references so `href` works) and captures the app-level not-found page:
+
+```typescript
+export const App = Router.router(
+  Router.layout({ component: Shell }, [
+    homeRoute,
+    Router.layout({ component: UserShell }, [settingsRoute, postsRoute]),
+  ]),
+  { notFound: () => h.section({ id: "page" }, [h.h2("404 — page not found")]) },
+);
+```
+
+`App` is a `RouterDef` whose phantom `E`/`R` carry the aggregate channels of the whole tree (plus the not-found page) — keep `app.ts` side-effect-free (no `mount`/`hydrate`) so both entries can import it.
+
+## Type-safe links with `href`
+
+`href(leafRef, args)` builds a URL from a leaf route reference (the value returned by `Router.route`). Path params are **required** in the argument type and query is optional when every query field is optional:
+
+```typescript
+import { href } from "@weftui/router";
+
+const Home = Component.make(() =>
+  h.nav([
+    h.a({ href: href(settingsRoute, { path: { id: 1 } }) }, "User 1 settings"),
+    h.a({ href: href(postsRoute, { path: { id: 2 }, query: { sort: "new" } }) }, "User 2 posts"),
+  ]),
+);
+```
+
+Path params encode into the pattern (`/users/:id` + `{ id: 42 }` ⇒ `/users/42`); query values encode through the query schema into a key-sorted search string. `href` round-trips with the matcher. The leaf must belong to a tree sealed with `Router.router()` (which is why deferring the `component` body via `Component.make` matters — `href` runs at render time, after compile).
+
+## Not-found
+
+`notFound(path?)` short-circuits the current render with a `RouterNotFound` failure. Callable from any page or layout; the nearest enclosing not-found boundary renders the configured `notFound` page in its place, and the server responds with HTTP 404:
+
+```typescript
+import { notFound, Router } from "@weftui/router";
+
+Router.route("users/:id", {
+  path: idParam,
+  component: Component.gen(function* () {
+    const { id } = yield* Router.params(idParam);
+    if (id < 0) return yield* notFound();
+    return yield* h.div(`User ${id}`);
+  }),
+});
+```
+
+`RouterNotFound` is exported, so a `Boundary.catchTag("RouterNotFound", …)` placed inside a subtree overrides the app-level fallback for that subtree (the router's internal boundary is outermost, so a nearer user boundary wins).
+
+## Client setup
+
+On the client, provide the `Router` via `RouterLive(def)` and render `RouterApp(def)`. `RouterLive` is a **scoped layer** — it owns the `popstate` listener and the same-origin link-click interceptor — so it must outlive the mount. Provide it through a long-lived `ManagedRuntime` rather than `Effect.provide` at the node level:
+
+```typescript
+// entry-client.ts
+import { hydrate } from "@weftui/dom/client";
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { ManagedRuntime } from "effect";
+import { App } from "./app";
+
+const root = document.getElementById("root")!;
+const runtime = ManagedRuntime.make(RouterLive(App));
+void runtime.runPromise(hydrate(RouterApp(App), root));
+```
+
+For a client-only app (no SSR), swap `hydrate` for `mount` — everything else is identical.
+
+### Link interception
+
+A plain `h.a({ href })` to a same-origin, route-matching URL performs SPA navigation when clicked — no full page load. The interceptor leaves the browser's native behaviour untouched for modified clicks (ctrl/meta/shift/alt or non-left button), `target=_blank`, `download`, external origins, same-document (hash-only) navigations, and hrefs that don't resolve to a route. You don't wire anything up: `RouterLive` installs the delegated listener for the layer's lifetime and removes it on teardown.
+
+## Programmatic navigation
+
+For navigation that isn't a link click, `@weftui/router/client` exposes typed helpers. They run as `Effect`s within the `RouterLive` layer (except `back` / `forward`, which only touch `window.history`):
+
+```typescript
+import {
+  back,
+  forward,
+  navigate,
+  patchQuery,
+  push,
+  replace,
+  setQuery,
+} from "@weftui/router/client";
+
+// Typed: build the URL from a leaf ref + decoded args (same rules as `href`).
+yield * navigate(postsRoute, { path: { id: 42 }, query: { sort: "new" } });
+yield * navigate(settingsRoute, { path: { id: 42 } }, { replace: true });
+
+// Raw path + search string.
+yield * push("/users/1/posts?sort=new");
+yield * replace("/users/1/settings");
+
+// History stepping (popstate resyncs the router).
+yield * back();
+yield * forward();
+
+// Change only the current route's query, re-encoded through its query schema.
+// The path is kept, so the leaf stays mounted and `queryStream` readers update.
+yield * setQuery({ sort: "old" }); // replaces the query
+yield * patchQuery({ sort: "old" }); // merges into the current query
+```
+
+- **`navigate(ref, args)`** builds the URL via [`href`](#type-safe-links-with-href) (so it round-trips with the matcher) and pushes — or, with `{ replace: true }`, replaces — the History entry. `args` follows the same requiredness rules as `href`.
+- **`setQuery` / `patchQuery`** keep the path, so the active leaf is never remounted — pair them with `Router.queryStream` for in-place reactive updates. They are a no-op when no route is matched.
+
+## Server setup
+
+On the server, `RouterServer` matches a request URL, builds a fixed-match `Router`, renders `RouterApp` to hydratable HTML inside a **document shell**, and reports a status (404 when no route matches or a page raises `RouterNotFound`).
+
+The document shell is itself a `ComponentSlot` that splices the app via `yield* Router.Outlet` — exactly like a layout receives its outlet:
+
+```typescript
+// entry-server.ts
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { RouterServer } from "@weftui/router/server";
+import { Effect } from "effect";
+import { App } from "./app";
+
+const documentShell = Component.gen(function* () {
+  const app = yield* Router.Outlet;
+  return yield* h.html({ lang: "en" }, [
+    h.head([h.meta({ charset: "utf-8" }), h.title("My app")]),
+    h.body([
+      h.div({ id: "root" }, [app]),
+      h.script({ type: "module", src: "/src/entry-client.ts" }),
+    ]),
+  ]);
+});
+
+// { html, status } — `<!DOCTYPE html>` is prepended for you.
+export const render = (url: string) =>
+  Effect.runPromise(RouterServer.render(App, { document: documentShell, url }));
+
+// Or a Web fetch-style handler, ready to bridge into Vite or any Web server.
+export const handler = RouterServer.toWebHandler(App, { document: documentShell });
+```
+
+`render` provides both `Router.Outlet` (the app, per request) and `Router` (so the shell may read params), and renders through `renderToStringHydratable` so the client can `hydrate` in place.
+
+### `@effect/platform` is the spine
+
+The tree is the authoring surface, but `@effect/platform`'s `HttpApi` is the **single source of truth** for paths and schemas. Sealing the tree with `Router.router(...)` builds it once (`buildHttpApi`) and stamps it onto `def.httpApi`: a single `"pages"` group with one GET endpoint per leaf at its full path pattern, carrying `setPath(pathSchema)`, `setUrlParams(querySchema)`, and a `RouterNotFound → 404` error. Both sides read that one definition, so they always agree:
+
+- **Server** — `RouterServer` dispatches through `HttpApiBuilder` (platform owns request→leaf matching, path/query decode, and the 404 status).
+- **Client** — `RouterLive` derives a real `HttpApiClient` from the same `def.httpApi` (exposed as `Router.httpApiClient`) for network work. SPA URL→leaf resolution stays **local** (there is no public client-side "match this URL against my `HttpApi`" utility in platform), fed from the same endpoint definitions so it never drifts from the server.
+
+## Errors
+
+| Error               | Raised by                                                             | Recover with                                                                |
+| ------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `RouterNotFound`    | `notFound()`, or no route matched                                     | `Boundary.catchTag("RouterNotFound", …)` (or the app-level `notFound` page) |
+| `RouterParamsError` | `Router.params` / `Router.query` on a missing/invalid key or no match | `Boundary.catchTag("RouterParamsError", …)`                                 |
+
+Both are modeled as `Schema.TaggedError`, so they encode/decode across the wire the same way `Boundary.rpc` replays typed failures.
+
+## `Boundary.rpc` interplay
+
+Initial SSR navigation works end to end: the server resolves the rpc and inlines its payload, and the client replays it during `hydrate`. **Client-side** navigation into a page containing a `Boundary.rpc` has no SSR payload, so the boundary performs a **client-first mount** — it renders the boundary's `fallback`, forks the rpc call over `POST /_eui/rpc`, and swaps in the result. `@weftui/router` provides the `AppRpcClientTag` seam on both sides (network client on the client, in-process on the server), so the same rpc backs SSR-replay, refetch, and client-first mount. See the [rpc data boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc).
+
+## See also
+
+- [`@weftui/router` API reference](https://weftui.dev/docs/reference/router)
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable SSR + hydration app with nested layouts, persistent layout state, type-safe `href`s, handler-arg props, and programmatic navigation over the `@effect/platform` spine
+- [Component Authoring](https://weftui.dev/docs/how-to/author-components) — `Component.make` / `Component.gen`, the idiomatic way to write route components
+- [Server-Side Rendering](https://weftui.dev/docs/how-to/render-on-the-server) — `renderToStringHydratable`, `hydrate`, and `Boundary.rpc`
+- [RPC Data Boundaries](https://weftui.dev/docs/how-to/load-data-with-rpc) — `Boundary.rpc`, the `Resource` handle, and the four lifecycles
+- [`packages/router/router.specs.md`](https://github.com/stefvw93/weft/blob/main/packages/router/router.specs.md) — the full specification