@weftui/router 0.26.0 → 0.26.2

package/README.md

@@ -0,0 +1,57 @@
+# @weftui/router
+
+> Universal nested router for [Weft](https://weftui.dev) — one route tree, rendered on the server and the client, with type-safe params and `href`s.
+
+Maps a URL to a nested page tree that renders identically on the server (`@weftui/router/server`) and the client (`@weftui/router/client`). Route params and query are decoded through [Effect Schema](https://effect.website/docs/schema/introduction/), `href` builds type-safe URLs that round-trip with the matcher, layouts persist across navigations, and `Router.lazy` code-splits a branch while keeping its descriptor eager.
+
+Three entry points mirror `@weftui/dom`: `@weftui/router` (authoring + universal nodes), `@weftui/router/client` (History-backed runtime), `@weftui/router/server` (SSR dispatch).
+
+## Installation
+
+```bash
+npm install @weftui/core @weftui/dom @weftui/router effect
+```
+
+`effect` is a peer dependency; `@weftui/core` and `@weftui/dom` provide the tree and renderer.
+
+## Key exports
+
+| Export                           | What it does                                                                            |
+| -------------------------------- | --------------------------------------------------------------------------------------- |
+| `Router.route` / `Router.layout` | Author a leaf page (with `:param` segments + schemas) or a UI-only nesting layout.      |
+| `Router.router`                  | Seals a route tree into a `RouterDef` and captures the app-level not-found page.        |
+| `Router.lazy`                    | Code-splits a route's component into its own chunk; only the matched branch loads.      |
+| `Router.params` / `Router.query` | Read the live match (snapshot); `…Stream` variants for reactive query-in-place updates. |
+| `Router.navigating`              | Reactive `Idle`/`Navigating` signal for pending UI during deferred-commit navigation.   |
+| `href(ref, args)`                | Builds a type-safe URL for a leaf route reference.                                      |
+| `RouterApp` / `RouterOutlet`     | The universal router root node — render on both server and client.                      |
+| `RouterLive` (client)            | History-backed `Router` layer; also provides the `AppRpcClientTag` seam.                |
+| `RouterServer` (server)          | `RouterServer.render` / `RouterServer.toWebHandler` for SSR dispatch.                   |
+
+## Example
+
+```typescript
+import { h } from "@weftui/core";
+import { Router, href } from "@weftui/router";
+import { Schema } from "effect";
+
+const userRoute = Router.route("users/:id", {
+  path: { id: Schema.NumberFromString },
+  component: ({ path }) => h.div(`User ${path.id}`),
+});
+
+const App = Router.router(userRoute, { notFound: () => h.div("Not found") });
+
+href(userRoute, { path: { id: 42 } }); // "/users/42"
+```
+
+## Documentation
+
+- Full docs: **https://weftui.dev**
+- `@weftui/router` API reference: **https://weftui.dev/docs/reference/router**
+- Routing guide: **https://weftui.dev/docs/how-to/add-routing**
+- Bundled with this package: see the [`./docs`](./docs) directory in `node_modules/@weftui/router/docs` — the complete tutorial, how-to, explanation, and reference tree ships on disk for offline and agent use.
+
+## License
+
+MIT © Stef van Wijchen

package/docs/explanation/boundaries-and-suspense.md

@@ -0,0 +1,91 @@
+---
+title: Boundaries and Suspense
+order: 4
+section: explanation
+description: How Weft models failure, async, and server data as boundary nodes in the same tree — failure-catch variants, Boundary.suspend, and Boundary.rpc, and how their E/R channels behave.
+---
+
+# Boundaries and Suspense
+
+A **boundary** is a node that intercepts something flowing through the tree — an error, a pending async child, or a server-resolved value — and decides what the DOM shows in its place. Because a boundary is itself a `Node<E, R>` ([nodes are Effects](https://weftui.dev/docs/explanation/rendering-model)), it composes exactly like any other element: you nest it, and its children's channels flow through it under a transformation the boundary defines.
+
+The `Boundary` namespace has three kinds. This page is the conceptual map; the [core reference](https://weftui.dev/docs/reference/core#boundary-namespace) has the full signatures.
+
+## Failure boundaries
+
+A component's `E` channel accumulates up the tree. A **failure boundary** is where you _discharge_ some of that `E`: it wraps children and, if one of them fails, renders a fallback instead of letting the failure propagate to the mount.
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+
+Boundary.catchAll({ fallback: (e) => h.div({ class: "error" }, `Failed: ${e.message}`) }, [
+  RiskyWidget(),
+]);
+```
+
+There are six failure-catch variants, mirroring Effect's own error operators so the mental model transfers directly:
+
+| Variant                  | Catches                                    |
+| ------------------------ | ------------------------------------------ |
+| `catchAll`               | every failure in `E`                       |
+| `catchAllCause`          | the full `Cause` (defects included)        |
+| `catchTag` / `catchTags` | one / several tagged errors by `_tag`      |
+| `catchSome` / `catchIf`  | a selected subset, by `Option` / predicate |
+
+The channel algebra is the whole reason they exist: `catchTag("Foo", …)` removes `Foo` from the children's `E` and adds whatever the fallback needs — so the type of the boundary node reflects exactly which failures are still live and which were handled. An unhandled failure re-raises to the **nearest enclosing** boundary; if none catches it at **mount time**, mounting fails. Boundaries nest, so an inner `catchTag` can handle a specific case while an outer `catchAll` sweeps the rest.
+
+### Post-mount failures with no enclosing boundary
+
+The routing above describes what happens while a node is being built. Once mounted, a reactive region — an attribute, child, or list stream, or a hydrated equivalent — keeps running for the lifetime of its scope, and it can still fail later: a `Stream` backing a `Boundary.rpc` resource might raise `RouterNotFound` after a client-side navigation, for instance. If a `BoundaryContext` encloses the region, the failure routes to it exactly as above, and the boundary's fallback swaps in.
+
+If no boundary encloses it, there is nothing to swap to. Weft does not synthesize one: the region's DOM keeps its last rendered content, and the subscription fiber's failure exit is left **unobserved**. The Effect runtime itself then reports it — `"Fiber terminated with an unhandled error"` — because Weft raises that fiber's `FiberRef.unhandledErrorLogLevel` from the ambient default (`Debug`) to `LogLevel.Error` and annotates the log with `weft.region`, identifying the failing region by kind and identity (e.g. `attribute:class`, `child:stream-3`, `list:stream-2`, `hydrate:stream-1 (/products/42)`). This fires for typed failures and defects alike, in both dev and prod, exactly once per failing region. Interruption — the ordinary case of unmount tearing down the region's scope — is never reported; only genuine failures are.
+
+This is deliberate: rather than a Weft-specific error-reporting config, visibility is controlled by the same knobs any Effect program uses — `Logger.withMinimumLogLevel` to filter it, `Effect.withUnhandledErrorLogLevel` to change how loudly (or quietly) unhandled fiber exits are reported elsewhere in your program. A stream that can fail and has no enclosing boundary is a stream whose failures you've chosen not to route into the UI — the log is what tells you that decision has consequences at runtime.
+
+## Suspense boundaries
+
+`Boundary.suspend` wraps async children and shows a `fallback` until **all** of them have emitted their first value, then swaps atomically — either everything is visible or nothing is. This prevents partial flicker when sibling async regions resolve at different times.
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+
+Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading…") }, [
+  AsyncCard({ id: 1 }),
+  AsyncCard({ id: 2 }),
+]);
+```
+
+A suspense boundary is transparent to the type channels: its node is `Node<ChildrenE, ChildrenR>` — the children's `E`/`R` pass straight through, exactly as they would for a plain `h.*` parent. It changes _timing_ (when the children become visible), not _types_.
+
+On the server, `renderToStreamHydratable` emits the fallback inline and appends patch scripts as children resolve; on the client, `hydrate` sees through the boundary and adopts the already-resolved DOM directly.
+
+> **Note.** There is no `Suspense` export — the API is `Boundary.suspend(props, children)`. Reach for it for async that loads **on the client**; for data that must resolve on the **server** and hydrate without a second request, use `Boundary.rpc` (below).
+
+## The rpc boundary
+
+`Boundary.rpc` is the server-data boundary: it resolves one `Rpc` on the server, serializes the result into the HTML, replays it on the client during `hydrate` (no second request, no flash), and then keeps the region live for `refetch`. Conceptually it is the same idea as the other boundaries — a node that decides what renders in a subtree — but the thing it intercepts is a **round-trip to a server handler**, and instead of a children array it takes a `render` function that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea).
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+import { Stream } from "effect";
+
+Boundary.rpc(
+  GetStock,
+  () => ({ id: productId }),
+  (resource) => h.span([Stream.map(resource.value.changes, (s) => String(s.units))]),
+  { fallback: h.p("loading…") },
+);
+```
+
+Unlike the failure and suspense boundaries, `Boundary.rpc` is not self-contained: it resolves through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam that `@weftui/router` provides on both sides. Its channel behavior is also distinct — the rpc's typed `error` schema joins the node's `E` (replayable through an enclosing failure boundary), while `render`'s `R` passes through untouched. The full model — the contract/handler split, the four lifecycles, typed-failure replay — is a **how-to**, not repeated here: [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc).
+
+## One tree, three interceptors
+
+The unifying idea: failure, async pending state, and server data are not three separate subsystems bolted onto the renderer. They are three **boundary nodes** in the one tree, each intercepting a different thing flowing through it, each with channel behavior you can read off its type. That is why they nest freely — a `Boundary.catchTag` can wrap a `Boundary.rpc` to catch its typed failure, and a `Boundary.suspend` can wrap async siblings that themselves contain rpc boundaries.
+
+## See also
+
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why a boundary is just a node in a static tree
+- [`Boundary` API reference](https://weftui.dev/docs/reference/core#boundary-namespace) — every variant's signature and channel algebra
+- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc) — the full `Boundary.rpc` walkthrough and its four lifecycles
+- [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server) — how suspense and rpc boundaries stream and hydrate

package/docs/explanation/combinator-api.md

@@ -0,0 +1,164 @@
+---
+title: The Combinator API
+order: 2
+section: explanation
+description: How h, h.fragment, and Component.gen / Component.make work; why Node is an Effect; how E and R accumulate through a tree.
+---
+
+# The Combinator API
+
+Weft builds UI trees by calling builder functions. Because component return types stay as generic `Effect.Effect<ElementDescriptor, E, R>`, the error channel (`E`) and requirements channel (`R`) propagate through the entire tree — visible to the type checker, satisfiable at the mount boundary. JSX collapses every component's return type to an opaque `JSX.Element`, erasing both channels; the combinator API exists specifically to keep them intact.
+
+## Nodes are Effects
+
+`Node<E, R>` is defined as:
+
+```typescript
+type Node<E = never, R = never> = Effect.Effect<ElementDescriptor, E, R>;
+```
+
+Nodes are first-class Effects. Everything in the Effect ecosystem works on them directly:
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect } from "effect";
+
+// yield* in Effect.gen — R propagates into the generator's context
+const node = yield * h.div({ class: "container" }, "Hello");
+
+// pipe — chain Effect operators directly
+const provided = pipe(h.div(userStream), Effect.provide(UserServiceLive));
+
+// Effect.flatMap — sequence node creation with async logic
+const card = pipe(
+  fetchCard(id),
+  Effect.flatMap((data) => h.div({ class: "card" }, data.title)),
+);
+```
+
+## The `h` namespace
+
+`h` is a proxy object where every property is an element builder. Access any HTML or SVG tag name as `h.tagName`:
+
+```typescript
+import { h } from "@weftui/core";
+
+h.div({ class: "container" }, [h.span("Hello"), h.p("World")]);
+h.input({ type: "text", placeholder: "Search..." });
+h.button({ type: "button", onclick: () => handleClick() }, "Submit");
+```
+
+Each builder accepts these call signatures:
+
+```typescript
+// props + children array
+h.div(props, children: Node[])
+
+// props + single string or number child
+h.div(props, child: string | number)
+
+// props only
+h.div(props)
+
+// children only (no props)
+h.div(children: Node[])
+
+// single string or number child
+h.div("five")
+h.div(5)
+
+// no props, no children
+h.div()
+```
+
+### How `E` and `R` accumulate
+
+Reactive prop values (any `Stream`, `Effect`, or `Subscribable`) contribute their channels to the node:
+
+```typescript
+declare const colorStream: Stream.Stream<string, never, ThemeService>;
+
+// Node<never, ThemeService> — R comes from the stream prop
+const box = h.div({ style: { color: colorStream } }, "Hello");
+```
+
+Children contribute their channels too, and siblings union their channels:
+
+```typescript
+declare const nodeA: Node<never, ServiceA>;
+declare const nodeB: Node<never, ServiceB>;
+
+// Node<never, ServiceA | ServiceB>
+const parent = h.div([nodeA, nodeB]);
+```
+
+Static values (strings, numbers, plain functions) contribute `never` to both channels.
+
+## `h.fragment`
+
+`h.fragment` groups children without emitting a wrapper element. Use it when a component needs to return multiple sibling nodes:
+
+```typescript
+import { h } from "@weftui/core";
+
+// Renders as three adjacent <td> elements with no wrapping element
+const TableRow = ({ user }: { user: User }) =>
+  h.fragment([h.td(user.name), h.td(user.role), h.td(user.status)]);
+```
+
+## Custom components with `Component.gen` / `Component.make`
+
+Plain functions work fine for simple components, but the `Component` factories provide type-level wiring so the caller's reactive prop types contribute their `E`/`R` to the returned node. Pick `Component.make` for a plain-function body and `Component.gen` for a generator body (when you need `yield*` to set up local state or pull from services).
+
+```typescript
+import { Component, h } from "@weftui/core";
+import { Stream } from "effect";
+
+interface ButtonProps {
+  label: string | Stream.Stream<string>;
+  onclick?: () => void;
+}
+
+const Button = Component.make((props: ButtonProps) =>
+  h.button({ onclick: props.onclick }, [props.label]),
+);
+
+// When called with a stream prop, the stream's R flows into the node type:
+declare const labelStream: Stream.Stream<string, never, I18nService>;
+
+// Node<never, I18nService>
+const btn = Button({ label: labelStream });
+```
+
+Components also accept an optional `children` argument, either as `readonly Renderable[]` or as a `(input) => readonly Renderable[]` function (render-prop pattern). `E`/`R` from children — including the array returned by a function-children call — accumulate on the resulting node.
+
+Without `Component`, a plain function's return type is fixed at definition time and does not reflect the caller's reactive prop types.
+
+See [component-authoring.md](https://weftui.dev/docs/how-to/author-components) for a full walkthrough.
+
+## Suspense boundaries
+
+`Boundary.suspend` wraps async children and shows a fallback until all of them have emitted their first value:
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+
+Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading...") }, [
+  AsyncCard({ id: 1 }),
+  AsyncCard({ id: 2 }),
+]);
+```
+
+The fallback is replaced atomically — either all children are visible or none are. This prevents partial flicker when multiple async siblings resolve at different times. The boundary's node type is `Node<ChildrenE, ChildrenR>`: the children's `E`/`R` channels accumulate onto it, exactly as they would for a plain `h.*` parent.
+
+On the server, `renderToStreamHydratable` emits the fallback inline and appends patch scripts as children resolve. On the client, `hydrate` sees through `Boundary.suspend` boundaries and adopts the already-resolved DOM directly.
+
+`Boundary.suspend` is one of the boundary combinators — see the [core reference](https://weftui.dev/docs/reference/core#boundarysuspend) for the full `Boundary.*` surface, including the failure-catch variants and `Boundary.rpc`.
+
+## See also
+
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why a `Node` is an `Effect` and how the tree renders
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the `Source` vocabulary that reactive props and children accept
+- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) — the boundary combinators as tree nodes
+- [Author Components](https://weftui.dev/docs/how-to/author-components) — `Component.gen` / `Component.make` in practice
+- [`@weftui/core` reference](https://weftui.dev/docs/reference/core)

package/docs/explanation/reactive-primitives.md

@@ -0,0 +1,162 @@
+---
+title: Reactive Primitives
+order: 3
+section: explanation
+description: The Source<A, E, R> vocabulary; Stream, Effect, and Subscribable as prop values and children; derived streams, reactive styles, and NoPropValue.
+---
+
+# Reactive Primitives
+
+The unified `Source` vocabulary is what lets static values, Effects, Streams, and Subscribables be used interchangeably wherever reactivity is supported — props, children, and style values all accept the same type.
+
+Weft accepts a `Source` for prop values and children. Any of these is valid wherever reactivity is supported:
+
+- A plain static value (`string`, `number`, `boolean`, ...)
+- An `Effect.Effect<A, E, R>` — runs once and resolves to a value
+- A `Stream.Stream<A, E, R>` — each emission replaces the previous value
+- A `Subscribable<A, E, R>` — like a hot stream; already has a "current value"
+
+The `Source<A, E, R>` type captures this union:
+
+```typescript
+type Source<A, E, R> = A | Effect.Effect<A, E, R> | Stream.Stream<A, E, R> | Subscribable<A, E, R>;
+```
+
+## Static values
+
+Static props behave exactly as you'd expect — set once and never updated:
+
+```typescript
+h.div({ class: "container", id: "root" }, "Hello");
+```
+
+## Effect props
+
+When a prop value is an `Effect`, it runs once and the resulting value is applied:
+
+```typescript
+const username = Effect.map(fetchProfile(), (p) => p.name);
+
+// Renders the username once it resolves
+h.span([username]);
+```
+
+The `E` and `R` channels of the Effect flow into the node's own channels.
+
+## Stream props and children
+
+Streams are the primary reactive primitive. Each emission replaces the previous value in the DOM — no diffing, direct DOM update:
+
+```typescript
+import { SubscriptionRef, Stream } from "effect";
+
+const count = yield * SubscriptionRef.make(0);
+
+// count.changes is a Stream<number> — each new value updates the text node
+h.span([count.changes]);
+
+// Stream as a prop — each emission sets the attribute
+const isDisabled = Stream.map(count.changes, (n) => n >= 10);
+h.button({ disabled: isDisabled }, "Submit");
+```
+
+Streams can also supply entire child arrays. Each emission replaces the previous set of children:
+
+```typescript
+const todos = yield * SubscriptionRef.make<string[]>([]);
+
+h.ul([Stream.map(todos.changes, (list) => list.map((item) => h.li(item)))]);
+```
+
+## Derived streams
+
+Because `.changes` is a plain `Stream`, the full Stream API applies:
+
+```typescript
+const count = yield * SubscriptionRef.make(0);
+
+const doubled = Stream.map(count.changes, (n) => n * 2);
+const formatted = Stream.map(count.changes, (n) => `Count: ${n}`);
+const isHigh = Stream.map(count.changes, (n) => n > 10);
+
+h.div([
+  h.p([count.changes]),
+  h.p([doubled]),
+  h.p([formatted]),
+  h.p({ style: { color: Stream.map(isHigh, (b) => (b ? "red" : "black")) } }, "Status"),
+]);
+```
+
+Multiple refs can be combined with `Stream.zipLatestWith`, `Stream.merge`, or other combinators:
+
+```typescript
+const firstName = yield * SubscriptionRef.make("");
+const lastName = yield * SubscriptionRef.make("");
+
+const fullName = Stream.zipLatestWith(firstName.changes, lastName.changes, (first, last) =>
+  `${first} ${last}`.trim(),
+);
+```
+
+## Reactive styles
+
+The `style` prop accepts the same `Source` vocabulary at any level:
+
+```typescript
+// Individual property as a stream
+h.div({
+  style: {
+    color: colorStream, // Stream<string>
+    opacity: opacityStream, // Stream<number>
+    fontWeight: "bold", // static
+  },
+});
+
+// Entire style object as a stream
+h.div({ style: styleObjectStream });
+
+// Combine a whole-object stream with a static property.
+// A whole-object stream replaces every property on each emit, so fold the
+// static value into each emitted object with Stream.map — you cannot spread the
+// Stream itself into a style object (that copies the Stream's internals, not
+// its emitted style keys).
+h.div({
+  style: Stream.map(styleObjectStream, (s) => ({
+    ...s, // reactive properties
+    transition: "all 0.3s", // static, applied on every emit
+  })),
+});
+
+// For a mix of static and per-property reactive values, use per-property
+// streams alongside static siblings instead:
+h.div({
+  style: {
+    transform: transformStream, // reactive, per-property
+    transition: "all 0.3s", // static
+  },
+});
+```
+
+## NoPropValue
+
+When a `Stream` prop ends before emitting, the renderer raises a `NoPropValue` tagged error. This carries an optional `key` field identifying which prop triggered it:
+
+```typescript
+// Handle at the mount boundary if needed. `Effect.catchTag` matches the error
+// by its string tag, so no `NoPropValue` import is required here.
+pipe(
+  mount(App(), root),
+  Effect.catchTag("NoPropValue", (e) =>
+    Effect.logWarning(`Prop stream ended before emitting: ${e.key}`),
+  ),
+);
+```
+
+In practice you only encounter `NoPropValue` if you use a finite `Stream` as a prop and it ends before emitting — e.g., `Stream.empty` or `Stream.take(0, stream)`. Most usage with `SubscriptionRef.changes` or infinite streams never raises it.
+
+## See also
+
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — streams as the weft woven through a static tree
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how reactive props and children contribute `E`/`R`
+- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively) and [Render Keyed Lists](https://weftui.dev/docs/how-to/render-keyed-lists) — reactive props and collections in practice
+- [`Source` reference](https://weftui.dev/docs/reference/core#source-namespace) — the `Source` type and `Source.toSubscribable`

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)