@weftui/router 0.26.1 → 0.26.3

package/README.md

@@ -0,0 +1,59 @@
+# @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.                   |
+
+Client-side navigation to a different path resets the window scroll to the top at commit; query-only navigations and browser back/forward preserve it (the latter via the browser's native `history.scrollRestoration`).
+
+## 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/dist/client/index.js

@@ -86,6 +86,10 @@ function RouterLive(def, options = {}) {
 		let committedScope;
 		let router;
 		const collectPreloads = (m) => m._tag !== "Matched" ? [] : [m.leaf.component, ...m.leaf.layoutChain.map((l) => l.component)].map(getPreload).filter((p) => p !== void 0);
+		const pathOf = (url) => {
+			const qIndex = url.indexOf("?");
+			return qIndex === -1 ? url : url.slice(0, qIndex);
+		};
 		const commitUrl = (normalized, replace) => Effect.sync(() => {
 			if (replace) window.history.replaceState(null, "", normalized);
 			else window.history.pushState(null, "", normalized);
@@ -137,8 +141,10 @@ function RouterLive(def, options = {}) {
 				url: normalized,
 				exit
 			});
+			const previousUrl = yield* SubscriptionRef.get(urlRef);
 			if (pushUrl) yield* commitUrl(normalized, replace);
 			yield* SubscriptionRef.set(urlRef, normalized);
+			if (pushUrl && pathOf(previousUrl) !== pathOf(normalized)) yield* Effect.sync(() => window.scrollTo(0, 0));
 			if (emitted) yield* SubscriptionRef.set(navRef, { _tag: "Idle" });
 		});
 		const navigate = (to, options) => commitTo(normalizeTo(to), true, options?.replace === true);

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`