@weftui/router 0.26.1 → 0.26.2

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

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

package/docs/how-to/author-components.md

@@ -0,0 +1,264 @@
+---
+title: Component Authoring
+order: 1
+section: how-to
+description: Plain functions vs. Component.gen / Component.make, instance scope, fragments, render-prop children, and service requirements.
+---
+
+# Component Authoring
+
+Weft components are plain TypeScript functions that return a `Node<E, R>`. This guide covers the two ways to define them and when to choose each.
+
+## Plain functions
+
+The simplest component is just a function:
+
+```typescript
+import { h } from "@weftui/core";
+
+function Greeting({ name }: { name: string }) {
+  return h.p(`Hello, ${name}!`);
+}
+
+// Call it like a function
+Greeting({ name: "World" });
+```
+
+Use a plain function when:
+
+- Props are all static (strings, numbers, plain functions)
+- The component has no internal state
+- You don't need the caller's reactive prop types to propagate
+
+## Components with internal state
+
+When a component needs reactive state, use `Effect.gen` to set it up before building the tree. The component function still runs once — the setup happens at mount time:
+
+```typescript
+import { h } from "@weftui/core";
+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) }, "+"),
+    ]);
+  });
+```
+
+The return type here is `Effect.Effect<Node, never, never>` — itself a valid `Node`, so it composes naturally with other tree-building calls. As soon as such a component is reused or takes props, prefer wrapping the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below) so the caller's reactive prop and children channels flow into its node type.
+
+## Component scope and background effects
+
+Every component instance is rendered under its own **instance scope** — a child of the
+mount scope created fresh for that instance. Anything bound to the instance scope lives
+exactly as long as the component is mounted and is torn down automatically when the
+component unmounts (or when the whole tree unmounts via the `MountHandle`). The renderer
+provides this scope as the ambient `Scope.Scope` while it evaluates the component body,
+so it is already in context when you need it.
+
+This matters the moment a component starts **background work** — a subscription, an
+observer of a `ref`, a polling timer, anything you `fork`. The rule:
+
+> Fork background work with **`Effect.forkScoped`**, never a bare `Effect.fork`.
+
+`Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for
+the component's lifetime and is interrupted on unmount. A bare `Effect.fork` instead
+attaches the fiber to the component-body fiber — the one that runs your `Effect.gen` to
+produce the tree. That fiber completes the instant the gen returns its node, so the
+forked work is cancelled almost immediately.
+
+Concretely, an observer that runs an effect when a `ref`'s element mounts:
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, Option, pipe, Stream, SubscriptionRef } from "effect";
+
+const AutoFocusInput = () =>
+  Effect.gen(function* () {
+    const inputRef = yield* SubscriptionRef.make<Option.Option<HTMLInputElement>>(Option.none());
+
+    yield* pipe(
+      inputRef.changes,
+      Stream.filter(Option.isSome),
+      Stream.take(1),
+      Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
+      Effect.forkScoped, // ✅ tied to the instance scope — survives until unmount
+      // Effect.fork,     // ❌ tied to the body fiber — interrupted when the gen returns
+    );
+
+    return yield* h.input({ ref: inputRef, type: "text" });
+  });
+```
+
+You do not manage the scope yourself: you do not create it, close it, or pass it
+around. `forkScoped` reads it from context, and unmount closes it for you. If you ever
+fork outside a component body (rare), you must supply a `Scope.Scope` yourself — the
+type system will tell you, because `forkScoped` carries a `Scope.Scope` requirement.
+
+See `examples/element-ref` for the auto-focus, measure, and canvas recipes built on
+this pattern.
+
+## `Component.gen` / `Component.make` for reusable components
+
+When you want the caller's reactive prop types to flow into the returned node's type, use one of the `Component` factories. Both have the same call semantics; pick the body style that fits:
+
+- **`Component.make`** — body is a plain function returning any `Effect` (typically a `Node`). Use for one-liners and pipe compositions.
+- **`Component.gen`** — body is a generator. Use when you need `yield*` to set up local state or pull from services.
+
+```typescript
+import { Component, h, Source } from "@weftui/core";
+
+interface CardProps {
+  title: Source.Source<string>;
+  body?: Source.Source<string>;
+}
+
+const Card = Component.make((props: CardProps) =>
+  h.div({ class: "card" }, [
+    h.h3({ class: "card-title" }, [props.title]),
+    props.body ? h.p({ class: "card-body" }, [props.body]) : null,
+  ]),
+);
+```
+
+`Source.Source<string>` is Weft's caller-facing prop vocabulary — a single type covering a static `string`, a `Stream<string>`, an `Effect<string>`, or a `Subscribable<string>` — so you don't hand-write `string | Stream.Stream<string> | …` on every prop. Passing a `Source` straight to `h` (as above) is all you need when the value is just spliced into the tree; the renderer normalizes it.
+
+Now the caller's stream types are visible in the returned node:
+
+```typescript
+declare const titleStream: Stream.Stream<string, never, I18nService>;
+
+// Node<never, I18nService> — I18nService requirement flows out
+const card = Card({ title: titleStream });
+```
+
+Without a `Component` factory, a plain function's return type is fixed at definition time and won't reflect the caller's reactive prop types.
+
+### Body `E`/`R` inference
+
+You don't declare the body's `E`/`R` channels explicitly — they're inferred from the returned (or yielded) effect:
+
+- The body's `E`/`R` come from whatever effects appear inside.
+- The caller's reactive prop channels and reactive children channels are unioned on top at the call site.
+- Static prop values (`string`, `number`, plain functions) contribute `never`.
+
+### Children: array or function
+
+Both factories accept an optional second `children` argument, typed as:
+
+```typescript
+type Component.Children<Input = never> =
+  | readonly Renderable[]
+  | ((input: Input) => readonly Renderable[]);
+```
+
+The function form is the render-prop / slot pattern — the component invokes the function with whatever input it chooses, and the returned array's `E`/`R` propagate out:
+
+```typescript
+const ItemList = Component.make(
+  (props: { items: readonly string[] }, renderItem: (item: string) => readonly Renderable[]) =>
+    h.ul(props.items.flatMap(renderItem)),
+);
+
+ItemList({ items: ["a", "b"] }, (item) => [h.li(item)]);
+```
+
+## Props typing
+
+For a prop that accepts both static and reactive values, type it as [`Source.Source<T>`](https://weftui.dev/docs/reference/core#source-namespace) rather than hand-writing the union. `Source.Source<T>` **is** that union — `T | Stream<T> | Effect<T> | Subscribable<T>` — so the caller can pass a plain value or any reactive shape interchangeably, and you write it once:
+
+```typescript
+import { Source } from "@weftui/core";
+
+interface ButtonProps {
+  label: Source.Source<string>; // static or reactive text
+  disabled?: Source.Source<boolean>; // static or reactive boolean
+  onclick?: () => void | Effect.Effect<void>; // plain or Effect-returning handler
+}
+```
+
+When a caller passes a plain string, the component's node type has `never` for that prop's channels. When they pass a `Stream.Stream<string, never, SomeService>`, `SomeService` appears in the `R` channel — the extraction is exactly `Source.Success` / `Source.Error` / `Source.Context`.
+
+### Reading a `Source` in the body
+
+Splicing a `Source` straight into `h` (`[props.label]`) is enough when you only place it in the tree. When the body needs to **read or derive** from the value — combine two props, feed a stream operator, drive logic — normalize it first with [`Source.toSubscribable`](https://weftui.dev/docs/reference/core#sourcetosubscribablesource-key), which turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
+
+```typescript
+import { Component, h, Source } from "@weftui/core";
+import { Stream } from "effect";
+
+const LoudLabel = Component.gen(function* (props: { label: Source.Source<string> }) {
+  const label = yield* Source.toSubscribable(props.label); // Subscribable<string>
+  // Now derive from it like any Subscribable — static, Effect, and Stream inputs all work.
+  return yield* h.strong([Stream.map(label.changes, (text) => text.toUpperCase())]);
+});
+```
+
+`toSubscribable` is scoped: a `Stream` prop is pumped by a fiber that terminates with the component's instance scope, an `Effect` prop is memoized, an existing `Subscribable` is threaded through by reference, and a static value emits once. It is the same normalization the renderer applies to props internally — reach for it whenever you need the value as a `Subscribable` instead of leaving it opaque.
+
+## Composing components
+
+Call component functions directly inside a children array:
+
+```typescript
+import { h } from "@weftui/core";
+
+function App() {
+  return h.div({ class: "app" }, [
+    Header({ title: "My App" }),
+    h.main([Sidebar(), h.article([Content({ id: 1 })])]),
+    Footer(),
+  ]);
+}
+```
+
+Children arrays accumulate `E`/`R` from all their members. The parent node's type reflects the union of all children's channels.
+
+## Components that require services
+
+If a component's render function uses a service via `yield*`, that service appears in the component's `CompR` parameter:
+
+```typescript
+import { Component, h } from "@weftui/core";
+
+const UserAvatar = Component.gen(function* (props: { userId: string }) {
+  const userService = yield* UserService;
+  const user = yield* userService.getUser(props.userId);
+  return yield* h.img({ src: user.avatarUrl, alt: user.name });
+});
+
+// Node<never, UserService> — regardless of what the caller passes
+const avatar = UserAvatar({ userId: "123" });
+```
+
+Provide the service at the mount boundary:
+
+```typescript
+void Effect.runPromise(
+  mount(App(), document.getElementById("root")!).pipe(Effect.provide(UserServiceLive)),
+);
+```
+
+## Returning fragments
+
+When a component needs to return multiple sibling elements without a wrapper, use `h.fragment`:
+
+```typescript
+import { h } from "@weftui/core";
+
+const TableCells = ({ row }: { row: Row }) =>
+  h.fragment([h.td(row.name), h.td(row.value), h.td(row.status)]);
+```
+
+`h.fragment` returns a `Node<E, R>` that accumulates channels from all its children.
+
+## See also
+
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — `h`, `h.fragment`, and how `E`/`R` accumulate
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the `Source` vocabulary props accept
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — route components are `Component` slots
+- [`@weftui/core` reference](https://weftui.dev/docs/reference/core) — `Component`, `Source`, and the full surface

package/docs/how-to/handle-forms.md

@@ -0,0 +1,76 @@
+---
+title: Handle Forms
+order: 8
+section: how-to
+description: Build a controlled form with SubscriptionRef field state, reactive Schema validation, and an Effect-returning submit handler.
+---
+
+# Handle Forms
+
+**Goal:** a controlled form whose inputs drive `SubscriptionRef` state, whose errors update reactively as the user types, and whose submit runs an Effect.
+
+Each field is a `SubscriptionRef`. Bind it with `oninput`, derive validation from its `.changes` stream, and return an `Effect` from `onsubmit` (after `preventDefault`).
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, Either, Schema, Stream, SubscriptionRef } from "effect";
+
+const Email = Schema.String.pipe(
+  Schema.filter((s) => s.includes("@"), { message: () => "Must contain @" }),
+  Schema.filter((s) => s.includes("."), { message: () => "Must contain a domain" }),
+);
+
+const LoginForm = () =>
+  Effect.gen(function* () {
+    const email = yield* SubscriptionRef.make("");
+    const status = yield* SubscriptionRef.make<string | null>(null);
+
+    // Validation is a stream derived from the field — it re-runs as the user types.
+    const error = Stream.map(email.changes, (value) => {
+      if (value.length === 0) return null; // don't nag an empty field
+      return Either.match(Schema.decodeUnknownEither(Email)(value), {
+        onLeft: (e) => e.message.split(":").pop()?.trim() ?? "Invalid",
+        onRight: () => null,
+      });
+    });
+
+    return yield* h.form(
+      {
+        onsubmit: (e) => {
+          e.preventDefault();
+          return Effect.gen(function* () {
+            yield* SubscriptionRef.set(status, "Submitting…");
+            yield* Effect.sleep("1500 millis");
+            yield* SubscriptionRef.set(status, "Login successful!");
+          });
+        },
+      },
+      [
+        h.input({
+          type: "email",
+          oninput: (e) => SubscriptionRef.set(email, (e.target as HTMLInputElement).value),
+        }),
+        Stream.map(error, (err) => (err ? h.span({ class: "error-text" }, err) : null)),
+        h.button({ type: "submit" }, "Login"),
+        h.div([Stream.map(status.changes, (s) => (s ? h.span(s) : null))]),
+      ],
+    );
+  });
+```
+
+## How it works
+
+- **Field state** is a `SubscriptionRef.make("")`; `oninput` writes the current value with `SubscriptionRef.set`. Because the input is driven by the ref, it is a controlled input.
+- **Validation is reactive**, not on-blur or on-submit only: `Stream.map(email.changes, …)` produces an error string (or `null`) on every keystroke. Use [`Schema`](https://effect.website/docs/schema/introduction) to decode — `Schema.decodeUnknownEither(schema)(value)` returns an `Either`, and `Either.match` turns it into UI. A node or `null` in a child slot renders the error or nothing.
+- **Submit returns an Effect.** `onsubmit` calls `e.preventDefault()` and then **returns** an `Effect` (it is not `yield*`-ed inline) — the renderer runs it in a detached fiber, so it can `SubscriptionRef.set`, `Effect.sleep`, read fields with `SubscriptionRef.get`, or call a service.
+
+## Variations
+
+- **Cross-field rules** (e.g. "passwords match") combine two fields with `Stream.zipLatestWith` before mapping to an error.
+- **Read a field imperatively** inside the submit handler with `yield* SubscriptionRef.get(field)` rather than threading it through.
+
+## See also
+
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `SubscriptionRef.changes` and stream-shaped children
+- [Author Components](https://weftui.dev/docs/how-to/author-components) — Effect-returning and service-aware handlers
+- [examples/form-handling](https://github.com/stefvw93/weft/tree/main/examples/form-handling) — a runnable multi-field form with Schema validation and an async submit