@weftui/dom 0.26.0 → 0.26.2

package/docs/reference/router.md

@@ -0,0 +1,348 @@
+---
+title: "@weftui/router"
+order: 3
+section: reference
+description: Full API surface for @weftui/router — universal nested routing, type-safe href, layouts, and SSR entry points.
+---
+
+# @weftui/router API Reference
+
+Universal nested router for Weft. See the [Routing guide](https://weftui.dev/docs/how-to/add-routing) for a narrative walkthrough.
+
+Three entry points mirror `@weftui/dom`:
+
+| Import                  | Use                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------- |
+| `@weftui/router`        | Shared authoring + universal nodes (`Router`, `href`, `RouterApp`, errors).         |
+| `@weftui/router/client` | Client runtime (`RouterLive`, programmatic `navigate`/`push`/…, re-exported nodes). |
+| `@weftui/router/server` | Server rendering (`RouterServer`).                                                  |
+
+## `Router`
+
+`Router` is both an Effect `Context.Tag` and the authoring namespace; the two roles merge by declaration. `yield* Router` reads the per-render service; `Router.route(…)` authors a tree.
+
+The service value carries:
+
+- **`currentMatch`** — the current match as a hot `Subscribable<RouteMatch>`; drives the outlet.
+- **`navigate(to, options?)`** — navigates to a path (with optional query). `options.replace` swaps `pushState` for `replaceState`. On the client this updates History state and re-renders the affected outlet; on the server it is a no-op.
+- **`httpApiClient`** — the derived [`RouterHttpApiClient`](#types) as an `Option`: `Option.some` on the client (`RouterLive`) for network work (route prefetch, future loaders), `Option.none` on the server (it is itself the origin). SPA URL→leaf resolution does **not** use this — it stays local via the shared matcher.
+
+### `Router.route`
+
+```typescript
+Router.route<Path, Query, S>(
+  segment: string,
+  config: { path?: Path; query?: Query; component: S },
+): RouteNode<Path, Query, E, R>;
+```
+
+Declares a leaf page. `segment` is relative to the parent and may contain `:name` placeholders. `component` is a [`ComponentSlot`](#types) — its `E`/`R` channels are recovered and propagate up the tree. The returned `RouteNode` is also the reference passed to [`href`](#href).
+
+A leaf `component` reads the live match in **either** of two forms:
+
+- **Handler-arg props** — declare `(props: `[`RouteHandlerProps<Path, Query>`](#types)`)` and the router passes the decoded `{ path, query }` straight in (`path`/`query` inferred from the route's `path`/`query` fields). A plain zero-arg thunk works too, ignoring the props.
+- **Dependency injection** — a `Component.make` / `Component.gen` component reading the live match via [`Router.params`](#routerparams--routerquery) / `Router.query`. Required for layouts/deep nodes, which can't take handler args.
+
+```typescript
+// Handler-arg props — decoded { path, query } passed in directly.
+const userRoute = Router.route("users/:id", {
+  path: { id: Schema.NumberFromString },
+  query: { tab: Schema.optional(Schema.String) },
+  component: ({ path, query }) => h.div(`User ${path.id} (${query.tab ?? "info"})`),
+});
+
+// Dependency injection — read the match anywhere via Router.params / Router.query.
+const userRouteDI = 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}`);
+  }),
+});
+```
+
+### `Router.layout`
+
+```typescript
+Router.layout<C, S>(config: { component: S }, children: C): LayoutNode<E, R>;
+```
+
+Declares a layout — purely UI nesting, owning **no path or segment**. `component` splices the injected outlet via `yield* Router.Outlet`. `Router.Outlet` is excluded from the layout's aggregate requirement channel (the router discharges it per render); the subtree's real channels are unioned in.
+
+### `Router.router`
+
+```typescript
+Router.router<T, NF>(root: T, options: { notFound: () => NF }): RouterDef<E, R>;
+```
+
+Seals a route tree into a [`RouterDef`](#types), compiling it eagerly (so leaf references are stamped for `href`) and capturing the app-level not-found page. The tree's aggregate channels (plus the not-found page's) ride on the returned `RouterDef`'s phantom `E`/`R`.
+
+### `Router.lazy`
+
+```typescript
+Router.lazy<S extends ComponentSlot>(
+  load: () => Promise<S>,
+): () => Node<Node.Error<SlotNode<S>>, Node.Context<SlotNode<S>>>;
+```
+
+Wraps a dynamic-import loader as a component slot, so a route's **component** is code-split into its own chunk while the **descriptor** (segment + param schemas) stays eager. `load` returns a `Promise` resolving the component — typically `() => import("./page").then((m) => m.Page)`. Drops directly into `Router.route({ component })` and `Router.layout({ component })`.
+
+- **Channels preserved.** The returned slot's `E`/`R` equal the resolved component's, so a lazy route has the identical type to declaring it eagerly (an unmet requirement is still a compile error at `Router.router`).
+- **Only the matched branch loads**, on the server during render and on the client on navigation. Client navigation is **deferred-commit**: the chunk **and the leaf component's own effect** resolve _before_ the URL commits (see [`Router.navigating`](#routernavigating) and [Blocking vs streaming data](#blocking-vs-streaming-data)), so the previous page stays mounted through both the fetch and any data the leaf awaits, and the swap is blank-free. The load `Promise` is memoized per slot, so revisits are synchronous.
+- **A rejected `load` is a defect** (`Effect.promise` dies) — a deploy-skew/offline condition surfaced through normal defect handling, kept off the `E` channel; the rejection is memoized (no silent retry).
+- The resolved value should be a `Component` (`Component.make`/`Component.gen`); a bare `() => Node` thunk loses its channels through the loader `Promise` — wrap it in `Component.make`.
+
+See the [Split Routes Lazily](https://weftui.dev/docs/how-to/split-routes-lazily) how-to and `packages/router/src/lazy-component.specs.md`.
+
+### `Router.Outlet`
+
+A `Context.Tag` whose value is the node to splice for the next level down. A layout (or the server document shell) reads it with `const outlet = yield* Router.Outlet`. Typed **opaque** as `Node<never, never>`, and discharged by the router at render time, so it never appears in a reader's aggregate requirement channel.
+
+### `Router.params` / `Router.query`
+
+```typescript
+Router.params<F extends Fields>(fields: F): Effect<FieldsType<F>, RouterParamsError, Router>;
+Router.query<F extends Fields>(fields: F): Effect<FieldsType<F>, RouterParamsError, Router>;
+```
+
+Snapshot accessors that read the **live match** (`currentMatch.get`) and pick the requested `fields` keys from the decoded path/query. The matcher already decoded the values against the leaf's full schema, so they are returned directly (no re-validation). Readable from **any** component, not just the leaf — this is the dependency-injection path layouts and deep nodes use (leaves can instead take [handler-arg props](#routerroute)). They fail with a [`RouterParamsError`](#routerparamserror) (`source: "path" | "query"`, plus the requested `keys`) when no route matches.
+
+### `Router.paramsStream` / `Router.queryStream`
+
+```typescript
+Router.paramsStream<F extends Fields>(fields: F): Effect<Subscribable<FieldsType<F>>, never, Router>;
+Router.queryStream<F extends Fields>(fields: F): Effect<Subscribable<FieldsType<F>>, never, Router>;
+```
+
+The **reactive** counterparts. Each resolves a `Subscribable<FieldsType<F>>` derived from `currentMatch.changes`, so a component can render `[(yield* Router.queryStream(fields)).changes]` and update **in place** even when the outlet keeps the same leaf mounted — exactly the query-only case (`setQuery` / `patchQuery`) a snapshot `Router.query` would miss. Resilient across navigations: a `NotFound` match yields the empty subset rather than failing, so the stream stays live.
+
+### `Router.navigating`
+
+```typescript
+type NavState =
+  | { readonly _tag: "Idle" }
+  | { readonly _tag: "Navigating"; readonly to: string };
+
+// on the Router service:
+readonly navigating: Subscribable.Subscribable<NavState>;
+
+// accessor, mirroring paramsStream/queryStream:
+Router.navigatingStream: Effect<Subscribable<NavState>, never, Router>;
+```
+
+The reactive navigation-state signal, for rendering pending UI (a top progress bar, dimmed outlet) during a **deferred-commit** navigation. It transitions `Idle → Navigating{ to }` while the router resolves the target branch's [`Router.lazy`](#routerlazy) chunk **and** the matched leaf's own component effect, and back to `Idle` on commit — one signal covering both the code and data windows. `NavState` is exported from `@weftui/router` and `@weftui/router/client`.
+
+- **Eager navigations never flip it** — a branch with no lazy node and a synchronously-resolving leaf commits synchronously and `navigating` stays `Idle`, so reading it costs nothing in an eager app.
+- **Synchronous resolutions never emit `Navigating`** — a revisit with both the chunk and the leaf's effect memoized (or an eager leaf with no async work) still commits in the same tick; the signal only flips when a resolution is genuinely async.
+- **Latest-wins** across rapid navigations (a superseded navigation never resets it and its pre-run is interrupted); **popstate** (back/forward) into a lazy or data-fetching route also reports; a **rejected chunk load or a failing leaf pre-run** (typed error or defect) resets it to `Idle` before the failure surfaces through the normal render error path.
+- **Server-side it is a constant `Idle`** (server render is buffered), so a component reading it type-checks and renders on both sides.
+
+See the [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) how-to, the [Blocking vs streaming data](#blocking-vs-streaming-data) section below, and `packages/router/src/resolve-before-commit.specs.md`.
+
+### Blocking vs streaming data
+
+A leaf `component` is already an `Effect` — there is no separate loader — so where you put an await decides whether it blocks the navigation commit or streams in afterward:
+
+- **`yield*` in the component body** → commit-blocking. The pre-run executes the leaf's effect to completion before the URL commits; the previous page stays mounted for the whole window, and `Router.navigating` reports `Navigating{ to }` for its duration.
+- **An `Effect`/`Stream` placed as a child node** → streaming. The commit is not delayed; the leaf mounts immediately and the child region fills in place once its own effect resolves.
+
+```typescript
+// Blocking — the await is in the leaf's own body; navigation waits for it.
+const DocPage = Component.gen(function* () {
+  const { category, slug } = yield* Router.params({ category: Schema.String, slug: Schema.String });
+  const docs = yield* Docs;
+  const doc = yield* docs.load(category, slug);
+  return yield* h.article([h.h1(doc.title), h.div({ innerHTML: doc.html })]);
+});
+
+// Streaming — the await lives on a child; the leaf commits immediately.
+const DocPage = Component.gen(function* () {
+  const { category, slug } = yield* Router.params({ category: Schema.String, slug: Schema.String });
+  const docs = yield* Docs;
+  return yield* h.article([
+    h.h1("Docs"),
+    Stream.concat(
+      Stream.make(h.p({ class: "loading" }, "Loading…")),
+      Stream.fromEffect(
+        Effect.map(docs.load(category, slug), (doc) => h.div({ innerHTML: doc.html })),
+      ),
+    ),
+  ]);
+});
+```
+
+Choose blocking for primary content the page is meaningless without (an article body, a product's price) — the old page stays visible with no blank or skeleton. Choose streaming for secondary or slow regions where partial content is still useful (a comments panel, a "related" rail) — the commit isn't held hostage by one slow fetch.
+
+Only the matched **leaf** is pre-run this way; layout components in the branch get their chunks preloaded but their bodies still run at render, post-commit (unchanged layouts don't re-render across navigations, so this rarely matters in practice). Pre-run failures — `notFound()`, a typed error, or a defect — still commit the URL and replay through the normal render error path (the nearest `Boundary`, or the router's 404 boundary) without re-running the component.
+
+See [Load Async Data](https://weftui.dev/docs/how-to/load-async-data#blocking-on-navigation-vs-streaming-in-place) and [RPC Data Boundaries](https://weftui.dev/docs/how-to/load-data-with-rpc) for the streaming patterns in full.
+
+## `href`
+
+```typescript
+href<Path, Query>(ref: RouteNode<Path, Query>, args?: HrefArgs<Path, Query>): string;
+```
+
+Builds a type-safe URL for a leaf route reference. Path params encode into the pattern; query values encode through the query schema into a key-sorted search string. Round-trips with the matcher.
+
+- `path` is **required** when its decoded type has required keys; `query` is optional when every query field is optional (`HrefArgs`).
+- Throws if the leaf belongs to a tree that has not been sealed with `Router.router()`.
+
+```typescript
+href(userRoute, { path: { id: 42 } }); // "/users/42"
+href(postsRoute, { path: { id: 1 }, query: { sort: "new" } }); // "/users/1/posts?sort=new"
+```
+
+## Universal nodes
+
+### `RouterApp`
+
+```typescript
+RouterApp<E, R>(def: RouterDef<E, R>): Node<Exclude<E, RouterNotFound>, R | Router>;
+```
+
+The universal router root node — render this on both server and client. Wraps the nested outlet in the router's internal not-found boundary, so a `RouterNotFound` raised by a page renders the configured `notFound` page in place. Server dispatch runs through `HttpApiBuilder`: a page-raised `RouterNotFound` and a no-match surface their 404 through the platform request pipeline.
+
+`RouterApp` requires `Router` in its environment — provide it via `RouterLive` (client) or `RouterServer` (server), not `Effect.provide` at the node level (that would release the scoped layer immediately).
+
+### `outletNode` (a.k.a. `RouterOutlet`)
+
+```typescript
+outletNode<E, R>(def: RouterDef<E, R>): Node<E | RouterNotFound, R | Router>;
+```
+
+The bare nested-outlet node without the internal not-found boundary — for callers placing their own not-found handling. Re-exported from `@weftui/router/client` as `RouterOutlet`.
+
+## Client — `@weftui/router/client`
+
+### `RouterLive`
+
+```typescript
+RouterLive(
+  def: RouterDef,
+  options: { rpc: { group: RpcGroup<any> }; baseUrl?: string | URL },
+): Layer.Layer<Router | AppRpcClientTag>;
+```
+
+The client `Router` layer, backed by the History API. Seeds a `SubscriptionRef` from `window.location`, listens for `popstate`, installs the same-origin link-click interceptor, and derives the `HttpApiClient` exposed as `Router.httpApiClient` (over `FetchHttpClient`; `baseUrl` defaults to same-origin). Alongside `Router` it also provides the core [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam — a **network** flat rpc client over the app's merged `RpcGroup` (`RpcClient.make` → `POST /_eui/rpc`) — so `@weftui/dom` can resolve a [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) (hydrated refetch and client-first SPA mount) without depending on this package or `@effect/rpc`. Pass the same merged `group` the server wires into [`RouterServer`](#routerserver). **Scoped** — it must outlive the mount, so provide it through a `ManagedRuntime`:
+
+```typescript
+const runtime = ManagedRuntime.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void runtime.runPromise(hydrate(RouterApp(App), root));
+```
+
+### Programmatic navigation
+
+```typescript
+navigate<Path, Query>(ref: RouteNode<Path, Query>, ...args): Effect<void, never, Router>;
+push(to: string): Effect<void, never, Router>;
+replace(to: string): Effect<void, never, Router>;
+back(): Effect<void>;
+forward(): Effect<void>;
+setQuery(query: Record<string, unknown>, options?: NavigateOptions): Effect<void, never, Router>;
+patchQuery(partial: Record<string, unknown>, options?: NavigateOptions): Effect<void, never, Router>;
+```
+
+Typed programmatic navigation, all run within the `RouterLive` layer (except `back`/`forward`, which only touch `window.history`):
+
+- **`navigate(ref, args)`** — go to a leaf route `ref` with typed `{ path, query }`, building the URL via [`href`](#href) (so it round-trips with `match`) and pushing — or, with `options.replace`, replacing — the History entry. Same requiredness rules as `href`: `path` required when the route has path params, `query` optional when every field is optional.
+- **`push` / `replace`** — go to a raw `path + search` string, pushing or replacing the History entry.
+- **`back` / `forward`** — step through History (`history.go(±1)`); the `popstate` handler resyncs.
+- **`setQuery` / `patchQuery`** — change the current route's query in place, re-encoding through the matched leaf's `querySchema` (the path is kept, so the leaf stays mounted and reactive `queryStream` readers update). `setQuery` replaces the query; `patchQuery` merges. No-op when no route is matched.
+
+```typescript
+import { navigate, patchQuery, push } from "@weftui/router/client";
+
+yield * navigate(userRoute, { path: { id: 42 }, query: { tab: "posts" } });
+yield * push("/users/1/posts?sort=new");
+yield * patchQuery({ sort: "old" }); // keeps the current path + other query fields
+```
+
+### `installLinkInterceptor`
+
+```typescript
+installLinkInterceptor(def: RouterDef, navigate: (to: string) => Effect<void>): Effect<void, never, Scope>;
+```
+
+The delegated click interceptor `RouterLive` installs for you. Exposed for advanced/manual wiring. Intercepts plain same-origin clicks whose href resolves to a route (resolved against `def`); leaves modified clicks, `target=_blank`, `download`, external origins, same-document navigations, and non-matching hrefs to the browser.
+
+## Server — `@weftui/router/server`
+
+### `RouterServer`
+
+A namespace for server-side rendering of a `RouterDef`.
+
+```typescript
+RouterServer.render(def, options: { document; rpc; url }): Effect<{ html; status }, Error>;
+RouterServer.toWebHandler(def, options: { document; rpc }): (request: Request) => Promise<Response>;
+```
+
+Dispatch runs through the `def.httpApi` spine via `HttpApiBuilder`: platform owns request→leaf matching and path/query decode, then each leaf handler builds a fixed-match server `Router` and renders the universal outlet to hydratable HTML.
+
+- **`toWebHandler`** returns a Web `fetch`-style handler `(Request) => Promise<Response>` that dispatches through `HttpApiBuilder.toWebHandler` and replies `text/html`. Suitable for bridging into a dev server (Vite) or any Web-platform server.
+- **`render`** drives that handler for a single `url`, returning `{ html, status }` with `<!DOCTYPE html>` prepended. `status` is sourced from the platform pipeline — `200`, or `404` for a no-match / a page-raised `RouterNotFound`.
+- **`document`** is a [`ComponentSlot`](#types) that splices the app via `yield* Router.Outlet`; the router provides both `Router.Outlet` (the app, per request) and `Router`.
+- **`rpc`** is the app's [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) data foundation: `{ group: RpcGroup<any>; handlers: Layer<any, never, never> }` — the merged `RpcGroup` (shared with the client) plus its server-only handler Layer (`group.toLayer(...)` ⊕ its dependencies). `toWebHandler` serves the handlers at `POST /_eui/rpc` (so a client refetch / client-first mount re-runs them on the server), and an in-process client over the same handlers (backing the [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam) resolves SSR boundaries in-process — never over the network.
+
+> The `HttpApi` is not generated on the server — it is built once when the tree is sealed (`buildHttpApi` during `Router.router`) and lives on `def.httpApi` as the single source of truth both the server dispatch and the client matcher / derived `HttpApiClient` read from.
+
+## Errors
+
+### `RouterNotFound`
+
+`Schema.TaggedError` with an optional `path: string`. Raised by [`notFound`](#notfound) or when no route matches. Caught by the router's internal not-found boundary; export it to place your own `Boundary.catchTag("RouterNotFound", …)` (a nearer user boundary wins).
+
+### `RouterParamsError`
+
+`Schema.TaggedError` with `source: "path" | "query"` and `keys: readonly string[]`. Raised by `Router.params` / `Router.query` when the live match doesn't satisfy the requested fields. Bubbles into the tree's aggregate error channel.
+
+### `notFound`
+
+```typescript
+notFound(path?: string): Effect<never, RouterNotFound>;
+```
+
+Short-circuits the current page render with a `RouterNotFound`. Callable from any page or layout `component`; the server responds with HTTP 404.
+
+### `isRouterNotFound`
+
+```typescript
+isRouterNotFound(u: unknown): u is RouterNotFound;
+```
+
+Type guard recognising a `RouterNotFound` value regardless of its prototype.
+
+## Compilation & matching (advanced)
+
+These power the runtime and are exported for tooling/tests; most apps never touch them directly.
+
+| Export                      | Description                                                                                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `compile(def)`              | Walks a tree into flat `CompiledLeaf`s with merged path/query schemas and layout chains.                                                                                       |
+| `buildHttpApi(leaves)`      | Builds the authoritative `HttpApi` (one `"pages"` group, a GET endpoint per leaf with `setPath`/`setUrlParams` + 404). Called by `Router.router`; the result is `def.httpApi`. |
+| `leafRegistry`              | `WeakMap<RouteNode, CompiledLeaf>` read by `href` to resolve a leaf's pattern/schemas.                                                                                         |
+| `match(compiled, url)`      | Resolves a URL to a `RouteMatch` (`Matched` with decoded `path`/`query`, or `NotFound`).                                                                                       |
+| `compileMatchers(compiled)` | Precompiles per-leaf regex matchers.                                                                                                                                           |
+
+## Types
+
+| Type                                                             | Description                                                                                                                 |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `RouterDef<E, R>`                                                | A sealed, compiled router. The unit passed to client and server; phantom `E`/`R` carry the tree's aggregate channels.       |
+| `RouteNode<Path, Query, E, R>` / `LayoutNode<E, R>` / `TreeNode` | Authored tree nodes.                                                                                                        |
+| `ComponentSlot<N>`                                               | A `(props: any) => N` callable producing a `Node`; accepts a plain thunk or a `Component.make` / `Component.gen` component. |
+| `RouteHandlerProps<Path, Query>`                                 | The `{ path, query }` decoded match a leaf `component` may declare as handler-arg props.                                    |
+| `RouteMatch`                                                     | `{ _tag: "Matched"; leaf; path; query; url }` or `{ _tag: "NotFound"; url }`.                                               |
+| `HrefArgs<Path, Query>`                                          | The `href` argument object; `path`/`query` become optional when their decoded type has no required keys.                    |
+| `NavigateOptions`                                                | `{ replace?: boolean }` — for `navigate` / `setQuery` / `patchQuery` and `Router.navigate`.                                 |
+| `RouterHttpApiClient`                                            | The platform `HttpApiClient` derived from a router's `HttpApi` spine (carried opaquely on `Router.httpApiClient`).          |
+| `Fields` / `FieldsType<F>`                                       | `Schema.Struct.Fields` and the `Type` side of its `Schema.Struct`.                                                          |
+| `Compiled` / `CompiledLeaf` / `CompiledLayout`                   | The compiled tree shapes.                                                                                                   |
+| `RouterOptions`                                                  | Options for `Router.router` (`notFound`).                                                                                   |
+
+## See also
+
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — the narrative guide to authoring a route tree
+- [Split Routes Lazily](https://weftui.dev/docs/how-to/split-routes-lazily) · [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) — `Router.lazy` and `Router.navigating`
+- [`@weftui/core` reference](https://weftui.dev/docs/reference/core) · [`@weftui/dom` reference](https://weftui.dev/docs/reference/dom)
+- [`packages/router/router.specs.md`](https://github.com/stefvw93/weft/blob/main/packages/router/router.specs.md) — the full specification

package/docs/tutorial/01-your-first-app.md

@@ -0,0 +1,48 @@
+---
+title: Your First App
+order: 1
+section: tutorial
+description: Install Weft, build a component with the h namespace, and mount it — the smallest possible Weft app.
+---
+
+# Your First App
+
+This is the first step of a four-part tutorial that builds up a Weft app from a static component to a server-rendered, error-handled one. By the end you will have touched every core idea; each step adds exactly one.
+
+We assume you know [Effect](https://effect.website/docs/getting-started/introduction) fundamentals — Weft is Effect for the UI, and we will not re-explain `Effect.gen`, services, or streams from scratch.
+
+## Install
+
+```bash
+npm install @weftui/core @weftui/dom effect
+```
+
+`@weftui/core` gives you the element builders and combinators; `@weftui/dom` renders them (its `./client` entry mounts in the browser). `effect` is the peer everything is built on.
+
+## Build a component
+
+A **component is a plain function you call** — there is no JSX and no `<Component/>` deferral. It returns a `Node`, which is just an `Effect` that produces a DOM node:
+
+```typescript
+import { h } from "@weftui/core";
+import { mount } from "@weftui/dom/client";
+import { Effect } from "effect";
+
+function App() {
+  return h.div({ class: "app" }, [h.h1("Hello, Weft"), h.p("A minimal app.")]);
+}
+
+void Effect.runPromise(mount(App(), document.getElementById("root")!));
+```
+
+The `h` namespace is the entry point: every property (`h.div`, `h.h1`, `h.button`, …) is a builder for that HTML tag. A builder takes optional props and children, and returns a `Node`.
+
+## What just happened
+
+- `App()` returns a **`Node<never, never>`** — the two type parameters are the error channel (`E`) and the requirement channel (`R`), both `never` here because this component neither fails nor needs a service. As your app grows, those channels accumulate what it can fail with and what it depends on. That is the whole point of Weft's types — see [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model).
+- `mount(node, target)` renders the node into `target`, building real DOM and starting any reactive streams. It returns an `Effect<MountHandle>`; run it with your Effect runtime (`Effect.runPromise` is fine for a script).
+- The component function runs **once**. Nothing here re-runs on a timer or a state change — because there is no state yet. That comes next.
+
+## Next
+
+- [Reactivity →](https://weftui.dev/docs/tutorial/02-reactivity) — make the UI change over time with `SubscriptionRef` and streams

package/docs/tutorial/02-reactivity.md

@@ -0,0 +1,57 @@
+---
+title: Reactivity
+order: 2
+section: tutorial
+description: Add component-local state with SubscriptionRef and weave its stream of changes into the tree so the DOM updates in place.
+---
+
+# Reactivity
+
+[Previously](https://weftui.dev/docs/tutorial/01-your-first-app) we mounted a static component. Now we make it change over time — the defining move in Weft: **weave a stream through the tree, and only that point updates.**
+
+## Local state with `SubscriptionRef`
+
+Use Effect's `SubscriptionRef` for component-local state. Its `.changes` property is a `Stream` that emits the current value and then every update. Pass that stream as a child or prop and the DOM at that spot becomes live:
+
+```typescript
+import { h } from "@weftui/core";
+import { mount } from "@weftui/dom/client";
+import { Effect, SubscriptionRef } from "effect";
+
+const Counter = () =>
+  Effect.gen(function* () {
+    const count = yield* SubscriptionRef.make(0);
+
+    return yield* h.div([
+      h.span([count.changes]),
+      h.button({ onclick: () => SubscriptionRef.update(count, (n) => n + 1) }, "+"),
+      h.button({ onclick: () => SubscriptionRef.update(count, (n) => n - 1) }, "-"),
+    ]);
+  });
+
+void Effect.runPromise(mount(Counter(), document.getElementById("root")!));
+```
+
+`Effect.gen` lets you `yield*` the `SubscriptionRef` to set up state **before** building the tree. Because a `Node` is an `Effect`, the component body is an ordinary generator — no hooks, no dependency arrays.
+
+## The key idea: the body runs once
+
+The `Counter` function runs **exactly once**. It creates the ref, builds the tree, and returns. After that, nothing re-invokes it — the only thing that changes the DOM is the `count.changes` stream woven into the `h.span`. When you click `+`, `SubscriptionRef.update` pushes a new value, the stream emits, and the renderer patches _just that span's text_ in place. No diff, no re-render, no sibling touched.
+
+This is what "streams are the weft" means in practice: reactivity is local to exactly where you thread a stream. Everything else is static. The full model is [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model); the vocabulary of stream-shaped values is [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives).
+
+> **Note.** `[count.changes]` — the stream is passed as a child array. Static values (`"Hello"`, `5`) work in the same position and simply never change. The rule is uniform: a plain value is static, a stream-shaped value is reactive.
+
+## Deriving values
+
+Because `.changes` is a `Stream`, you shape reactive text with ordinary stream operators:
+
+```typescript
+h.span([Stream.map(count.changes, (n) => `Count: ${n}`)]);
+```
+
+Anywhere you would compute a derived value, map the stream instead — the derivation stays reactive.
+
+## Next
+
+- [Services and Async →](https://weftui.dev/docs/tutorial/03-services-and-async) — pull dependencies from the environment and render async loading states

package/docs/tutorial/03-services-and-async.md

@@ -0,0 +1,77 @@
+---
+title: Services and Async
+order: 3
+section: tutorial
+description: Give handlers access to services from the environment, and render async loading states by returning a Stream of nodes.
+---
+
+# Services and Async
+
+[So far](https://weftui.dev/docs/tutorial/02-reactivity) our state has been self-contained. Real apps talk to services and wait on async work. Both fall out of the same fact — a `Node` is an `Effect` — so both use plain Effect.
+
+## Handlers that use services
+
+An event handler can **return an Effect**, and that Effect runs in the component's environment — so it can read any service you provide at the mount boundary:
+
+```typescript
+import { h } from "@weftui/core";
+import { mount } from "@weftui/dom/client";
+import { Context, Effect, Layer, pipe } from "effect";
+
+class Logger extends Context.Tag("Logger")<
+  Logger,
+  { log: (message: string) => Effect.Effect<void> }
+>() {}
+
+const LoggerLive = Layer.succeed(Logger, {
+  log: (message) => Effect.sync(() => console.log(message)),
+});
+
+const LogButton = () =>
+  h.button(
+    {
+      onclick: () =>
+        Effect.gen(function* () {
+          const logger = yield* Logger;
+          yield* logger.log("Button clicked");
+        }),
+    },
+    "Log",
+  );
+
+// Provide the layer at mount — every handler in the tree can now read Logger.
+void Effect.runPromise(
+  pipe(mount(LogButton(), document.getElementById("root")!), Effect.provide(LoggerLive)),
+);
+```
+
+`Logger` entered the tree's requirement channel the moment `LogButton` read it, and you discharged it **once**, at `mount`, with `Effect.provide`. Provide too little and it is a compile error at the mount call. This is Weft's entire dependency-injection story — it is just Effect's. The deeper treatment is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
+
+## Async loading states
+
+A component can return a **`Stream<Node>`** to show different content over time. Sequence a loading placeholder before the resolved content with `Stream.concat`:
+
+```typescript
+import { h } from "@weftui/core";
+import { mount } from "@weftui/dom/client";
+import { Effect, Stream } from "effect";
+
+const AsyncGreeting = ({ name }: { name: string }) =>
+  Stream.concat(
+    Stream.make(h.span("Loading…")),
+    Stream.fromEffect(
+      Effect.gen(function* () {
+        yield* Effect.sleep("1 second");
+        return yield* h.span(`Hello, ${name}!`);
+      }),
+    ),
+  );
+
+void Effect.runPromise(mount(AsyncGreeting({ name: "World" }), document.getElementById("root")!));
+```
+
+The stream emits the loading node first, then the resolved node — the renderer swaps the DOM in place on the second emission. This is the raw mechanism; for coordinating _several_ async regions with a single fallback, reach for [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense), which you will meet in the next step.
+
+## Next
+
+- [Errors and Server Rendering →](https://weftui.dev/docs/tutorial/04-errors-and-server) — catch failures with boundaries and render on the server

package/docs/tutorial/04-errors-and-server.md

@@ -0,0 +1,61 @@
+---
+title: Errors and Server Rendering
+order: 4
+section: tutorial
+description: Catch rendering-path failures with Boundary, then render on the server and hydrate — the last step of the tutorial.
+---
+
+# Errors and Server Rendering
+
+The final step. [We can now](https://weftui.dev/docs/tutorial/03-services-and-async) use services and async; here we handle what happens when async work **fails**, and how the same tree renders on the server.
+
+## Error boundaries
+
+A component's failures accumulate on its `E` channel. Wrap a subtree in a `Boundary.*` variant to intercept them and render a fallback instead of failing the mount:
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+import { Data, Effect } from "effect";
+
+class ApiError extends Data.TaggedError("ApiError")<{ status: number }> {}
+
+const SafeWidget = () =>
+  Boundary.catchAll({ fallback: (e) => h.div({ class: "error" }, `Request failed: ${e.status}`) }, [
+    Effect.fail(new ApiError({ status: 503 })),
+  ]);
+```
+
+There are six failure-catch variants — `catchAll`, `catchAllCause`, `catchTag`, `catchTags`, `catchSome`, `catchIf` — mirroring Effect's own error operators. A failure that a boundary does not match re-raises to the **nearest enclosing** boundary; if none catches it, the mount fails. The conceptual model (and why the boundary's type reflects exactly which failures are handled) is [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense).
+
+## Render on the server
+
+The same component tree renders to HTML on the server and **hydrates in place** on the client — no re-render, no flash. The server produces markup (plus inline data), and `hydrate` adopts that existing DOM and resumes reactivity:
+
+```typescript
+// server entry
+import { renderToStringHydratable } from "@weftui/dom/server";
+import { Effect } from "effect";
+import { App } from "./app";
+
+export const render = () => Effect.runPromise(renderToStringHydratable(App()));
+```
+
+```typescript
+// client entry
+import { hydrate } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+
+void Effect.runPromise(hydrate(App(), document.getElementById("root")!));
+```
+
+The same side-effect-free `App` is imported by both entries. For server-resolved data that replays into the client without a second request, `Boundary.rpc` extends this model — resolve an rpc on the server, serialize its result into the HTML, replay it on hydrate, then keep the region live for refetch.
+
+## You're done
+
+You have built up every core idea: components and `h`, reactive state and streams, services and async, boundaries and SSR. Where to go next depends on what you are doing:
+
+- **Understand the model** → [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model), [The Combinator API](https://weftui.dev/docs/explanation/combinator-api), [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives)
+- **Get a task done** → [Author Components](https://weftui.dev/docs/how-to/author-components), [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server), [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc), [Add Routing](https://weftui.dev/docs/how-to/add-routing)
+- **Look up an API** → [`@weftui/core`](https://weftui.dev/docs/reference/core), [`@weftui/dom`](https://weftui.dev/docs/reference/dom), [`@weftui/router`](https://weftui.dev/docs/reference/router)
+- **Read runnable code** → [examples/](https://github.com/stefvw93/weft/tree/main/examples)

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "@weftui/dom",
-  "version": "0.26.0",
-  "description": "Client-side DOM renderer for Weft",
+  "version": "0.26.2",
+  "description": "DOM renderer for Weft — mount and hydrate in the browser, render to string or stream on the server",
+  "keywords": [
+    "dom",
+    "effect",
+    "hydration",
+    "renderer",
+    "ssr",
+    "weft"
+  ],
+  "homepage": "https://weftui.dev",
+  "bugs": {
+    "url": "https://github.com/stefvw93/weft/issues"
+  },
   "license": "MIT",
   "author": "Stef van Wijchen",
   "repository": {
     "type": "git",
-    "url": "https://github.com/stefvw93/weft"
+    "url": "https://github.com/stefvw93/weft",
+    "directory": "packages/dom"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "type": "module",
   "exports": {
@@ -30,7 +44,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@weftui/core": "0.26.0"
+    "@weftui/core": "0.26.2"
   },
   "devDependencies": {
     "@effect/rpc": "^0.75.1",