@weftui/core 0.27.1 → 0.29.0

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

@@ -2,15 +2,15 @@
 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."
+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.
+- **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.
 
@@ -20,21 +20,21 @@ 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`.
+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:
+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`.                                |
+| 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.
+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 lets `href(…)` resolve after the tree is compiled.
 
 ```typescript
 import { Component, h } from "@weftui/core";
@@ -57,15 +57,15 @@ const User = Router.route("users/: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`.
+> Authoring components with `Component.make` / `Component.gen` keeps every slot fully typed: the router never sees a `Node<any, any>`. 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.
+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:
+The router passes the decoded `{ path, query }` straight into a leaf `component` as props. The props are 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 };
@@ -80,7 +80,7 @@ Router.route("users/:id/posts", {
 });
 ```
 
-This is the most direct form for a leaf. A plain zero-arg thunk works too — it just ignores the props.
+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)
 
@@ -95,13 +95,15 @@ const UserShell = Component.gen(function* () {
 });
 ```
 
-`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", …)`.
+`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. When no route matches, they fail with a tagged [`RouterParamsError`](#errors) carrying `source: "path" | "query"` and the requested `keys`.
 
-> **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).
+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`. 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:
+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* () {
@@ -113,13 +115,13 @@ const UserShell = Component.gen(function* () {
 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.
+`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`.
+A layout owns **no `segment` or `path`**; all path structure lives on routes. A layout that needs a param 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.
+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
 
@@ -131,11 +133,11 @@ export const App = Router.router(
     homeRoute,
     Router.layout({ component: UserShell }, [settingsRoute, postsRoute]),
   ]),
-  { notFound: () => h.section({ id: "page" }, [h.h2("404 — page not found")]) },
+  { 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.
+`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`
 
@@ -152,11 +154,13 @@ const Home = Component.make(() =>
 );
 ```
 
-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).
+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()`. This 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:
+`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";
@@ -171,31 +175,41 @@ Router.route("users/: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).
+`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.
 
-> **`Schema.NumberFromString` gotcha.** Decoding no longer fails on a non-numeric segment — `/users/abc` decodes `id` to `NaN` instead of missing the route. A leaf that guards a numeric param must check `Number.isFinite(id)` itself (as above); relying on the schema alone to 404 non-numeric input no longer works.
+> **`Schema.NumberFromString` gotcha.** Decoding no longer fails on a non-numeric segment: `/users/abc` decodes `id` to `NaN` instead of missing the route. A leaf that guards a numeric param must check `Number.isFinite(id)` itself (as above). Relying on the schema alone to 404 non-numeric input no longer works.
 
 ## 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:
+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.
+
+Give it to `WeftApp.make`. The app runtime owns it for the app's lifetime, built lazily on first hydrate and released only at `WeftApp.dispose`. Do not wrap `Effect.provide` around the mount/hydrate call; services come exclusively from the app layer.
 
 ```typescript
 // entry-client.ts
-import { hydrate } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { RouterApp, RouterLive } from "@weftui/router/client";
-import { ManagedRuntime } from "effect";
+import { Effect } from "effect";
 import { App } from "./app";
 
 const root = document.getElementById("root")!;
-const runtime = ManagedRuntime.make(RouterLive(App));
-void runtime.runPromise(hydrate(RouterApp(App), root));
+const app = WeftApp.make(RouterLive(App));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 ```
 
-For a client-only app (no SSR), swap `hydrate` for `mount` — everything else is identical.
+For a client-only app (no SSR), swap `WeftApp.hydrate` for `WeftApp.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.
+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` and `download`
+- external origins
+- same-document (hash-only) navigations
+- 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
 
@@ -230,24 +244,28 @@ 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.
+- **`navigate(ref, args)`** builds the URL via [`href`](#type-safe-links-with-href), so it round-trips with the matcher. It pushes the History entry, or replaces it with `{ replace: true }`. `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.
 
 ### Scroll position on navigation
 
-A client navigation whose **path** changes resets the window scroll to the top at commit — matching what a full page load would do, which a raw History `pushState`/`replaceState` otherwise doesn't. This applies uniformly to `Router.navigate`, clicking a link the [interceptor](#link-interception) handles, and the `push` / `replace` helpers.
+A client navigation whose **path** changes resets the window scroll to the top at commit. This matches a full page load, which a raw History `pushState`/`replaceState` otherwise doesn't. It applies uniformly to `Router.navigate`, clicking a link the [interceptor](#link-interception) handles, and the `push` / `replace` helpers.
 
-- **Query-only navigations preserve scroll.** `setQuery` / `patchQuery` (and any navigation that keeps the same path) don't reset — the leaf stays mounted, so there's nothing to scroll away from.
+- **Query-only navigations preserve scroll.** `setQuery` / `patchQuery` (and any navigation that keeps the same path) don't reset; the leaf stays mounted, so there's nothing to scroll away from.
 - **Back/forward is untouched.** The router never resets scroll on `popstate`; the browser's native `history.scrollRestoration: "auto"` restores the offset the entry had when the user left it.
-- **Hash navigation (`#section`) is unaffected** — it's browser-native, and the link interceptor already lets same-document/hash-only clicks fall through.
+- **Hash navigation (`#section`) is unaffected.** It's browser-native, and the link interceptor already lets same-document/hash-only clicks fall through.
 
 There's no opt-out; the behavior is hardwired.
 
 ## 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`).
+On the server, `RouterServer`:
+
+- matches a request URL and builds a fixed-match `Router`
+- renders `RouterApp` to hydratable HTML inside a **document shell**
+- 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:
+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
@@ -268,7 +286,7 @@ const documentShell = Component.gen(function* () {
   ]);
 });
 
-// { html, status } — `<!DOCTYPE html>` is prepended for you.
+// { html, status }: `<!DOCTYPE html>` is prepended for you.
 export const render = (url: string) =>
   Effect.runPromise(RouterServer.render(App, { document: documentShell, url }));
 
@@ -276,14 +294,16 @@ export const render = (url: string) =>
 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.
+`render` provides both `Router.Outlet` (the app, per request) and `Router` (so the shell may read params). It renders through `renderToStringHydratable` so the client can `hydrate` in place.
 
 ### `effect/unstable/httpapi` is the spine
 
-The tree is the authoring surface, but `effect/unstable/httpapi`'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 `params: pathSchema`, `query: querySchema`, and a `RouterNotFound → 404` error. Both sides read that one definition, so they always agree:
+The tree is the authoring surface, but `effect/unstable/httpapi`'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`.
+
+The result is a single `"pages"` group with one GET endpoint per leaf at its full path pattern, carrying `params: pathSchema`, `query: 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.
+- **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. It is fed from the same endpoint definitions, so it never drifts from the server.
 
 ## Errors
 
@@ -296,13 +316,17 @@ Both are modeled as `Schema.TaggedErrorClass`, so they encode/decode across the
 
 ## `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).
+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). 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/unstable/httpapi` 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
+- [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/unstable/httpapi` 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

@@ -32,7 +32,7 @@ Use a plain function when:
 
 ## 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:
+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";
@@ -49,25 +49,28 @@ const Counter = () =>
   });
 ```
 
-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.
+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, wrap the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below). That way 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
+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.
+exactly as long as the component is mounted. It is torn down automatically when the
+component unmounts (or when its root unmounts via `RootHandle.unmount()`).
+
+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
+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.forkChild`.
 
 `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.forkChild` instead
-attaches the fiber to the component-body fiber — the one that runs your `Effect.gen` to
+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.
 
@@ -86,8 +89,8 @@ const AutoFocusInput = () =>
       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.forkChild, // ❌ tied to the body fiber — interrupted when the gen returns
+      Effect.forkScoped, // ✅ tied to the instance scope: survives until unmount
+      // Effect.forkChild, // ❌ tied to the body fiber: interrupted when the gen returns
     );
 
     return yield* h.input({ ref: inputRef, type: "text" });
@@ -96,7 +99,7 @@ const AutoFocusInput = () =>
 
 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
+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
@@ -106,8 +109,8 @@ this pattern.
 
 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.
+- **`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";
@@ -125,14 +128,16 @@ const Card = Component.make((props: CardProps) =>
 );
 ```
 
-`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.
+`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>`. 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
+// Node<never, I18nService>: I18nService requirement flows out
 const card = Card({ title: titleStream });
 ```
 
@@ -140,7 +145,7 @@ Without a `Component` factory, a plain function's return type is fixed at defini
 
 ### Body `E`/`R` inference
 
-You don't declare the body's `E`/`R` channels explicitly — they're inferred from the returned (or yielded) effect:
+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.
@@ -156,7 +161,7 @@ type Component.Children<Input = never> =
   | ((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:
+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(
@@ -169,7 +174,7 @@ 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:
+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>`. The caller can pass a plain value or any reactive shape interchangeably, and you write it once:
 
 ```typescript
 import { Source } from "@weftui/core";
@@ -181,11 +186,11 @@ interface ButtonProps {
 }
 ```
 
-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`.
+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>`:
+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). It turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
 
 ```typescript
 import { Component, h, Source } from "@weftui/core";
@@ -193,12 +198,19 @@ 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.
+  // 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.
+`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.
+- 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
 
@@ -231,16 +243,18 @@ const UserAvatar = Component.gen(function* (props: { userId: string }) {
   return yield* h.img({ src: user.avatarUrl, alt: user.name });
 });
 
-// Node<never, UserService> — regardless of what the caller passes
+// Node<never, UserService>: regardless of what the caller passes
 const avatar = UserAvatar({ userId: "123" });
 ```
 
-Provide the service at the mount boundary:
+Give the service to the app layer:
 
 ```typescript
-void Effect.runPromise(
-  mount(App(), document.getElementById("root")!).pipe(Effect.provide(UserServiceLive)),
-);
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+
+const app = WeftApp.make(UserServiceLive);
+void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
 ## Returning fragments
@@ -258,7 +272,7 @@ const TableCells = ({ row }: { row: Row }) =>
 
 ## 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
+- [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/compose-behavior-and-markup.md

@@ -0,0 +1,144 @@
+---
+title: Compose Behavior and Markup
+order: 13
+section: how-to
+description: "Use Props.merge to combine a behavior prop bag with your own markup: chained handlers, ref fan-out, and reactive classes on one element."
+---
+
+# Compose Behavior and Markup
+
+**Goal:** share behavior (aria wiring, handlers, refs, reactive state) without
+giving up ownership of the element it applies to.
+
+## The problem
+
+Behavior and markup usually want different owners. A dropdown's keyboard
+handling, `aria-expanded` wiring and anchor ref are worth writing once. The
+button itself is yours: your classes, your text, your extra handlers.
+
+Object spread cannot combine them. `{ ...behavior, ...mine }` silently drops the
+behavior's `onclick` when you supply your own, and drops its `ref` when you
+supply yours. Nothing warns you.
+
+`Props.merge` reconciles both bags instead.
+
+## Behavior as a prop bag
+
+A behavior primitive is a plain Effect that yields a prop bag. There is no
+component wrapper and no hook rules, so you can `yield*` it anywhere and hold
+the result.
+
+```ts
+import { Effect, Option, SubscriptionRef } from "effect";
+
+const makeDisclosure = () =>
+  Effect.gen(function* () {
+    const isOpen = yield* SubscriptionRef.make(false);
+    const anchor = yield* SubscriptionRef.make(Option.none<HTMLElement>());
+
+    const trigger = {
+      ref: anchor,
+      "aria-expanded": SubscriptionRef.changes(isOpen),
+      onclick: () => SubscriptionRef.update(isOpen, (open) => !open),
+    };
+
+    return { isOpen, trigger };
+  });
+```
+
+`makeDisclosure` returns a plain object, not a `DomProps`-typed value. `merge`
+accepts it as-is: it dispatches on each key's name, not on the bag's declared
+type.
+
+## Merge it onto your element
+
+You write the element. The bag merges onto it.
+
+```ts
+import { h } from "@weftui/core";
+import { Props } from "@weftui/dom";
+
+const Panel = () =>
+  Effect.gen(function* () {
+    const disclosure = yield* makeDisclosure();
+    const measure = yield* SubscriptionRef.make(Option.none<HTMLElement>());
+
+    return yield* h.button(
+      Props.merge(disclosure.trigger, {
+        class: Props.cx("btn", { "btn--open": SubscriptionRef.changes(disclosure.isOpen) }),
+        onclick: (ev: MouseEvent) => trackClick(ev),
+        ref: measure,
+      }),
+      "Details",
+    );
+  });
+```
+
+Three rules earn their keep in that one call:
+
+1. **Handlers chain.** The disclosure toggles, then `trackClick` runs. Both
+   always run, and a failure in one does not prevent the other. A broken
+   analytics call cannot block the toggle.
+2. **Refs fan out.** `anchor` and `measure` both receive the element. Spread
+   would have kept only one, silently.
+3. **`cx` takes a reactive condition.** `btn--open` follows `isOpen`, and only
+   the class attribute updates.
+
+Type an inline handler's event explicitly, as `(ev: MouseEvent)` above. `merge`
+does not know which element the bag will land on, so it cannot infer it.
+
+## Typed errors flow through
+
+A handler that fails with a tagged error, or needs a service, keeps both
+channels through the merge. They surface on the component's `Node<E, R>`, so the
+app must provide the service and can catch the error at a boundary.
+
+```ts
+declare const rowBehavior: object;
+declare const itemId: string;
+
+const deleteItem = Effect.gen(function* () {
+  const files = yield* FileService;
+  yield* files.remove(itemId);
+});
+
+// The merged node requires FileService and can fail with whatever error
+// `files.remove` declares. Both channels flow through `merge` untouched.
+h.button(Props.merge(rowBehavior, { onclick: () => deleteItem }), "Delete");
+```
+
+## Two gotchas that differ from spread
+
+- **`false` on a handler is an explicit opt-out and wins.** `null` and
+  `undefined` mean "not provided", so the other side survives instead.
+- **Every other key is genuinely last-wins.** Forwarding an omitted optional
+  prop (`{ id: props.id }`) still overwrites a default with `undefined`, the
+  same as `{ ...base, ...override }` would. Guard at the call site if that
+  matters.
+
+The [reference](https://weftui.dev/docs/reference/dom#propsmerge) has the full per-key rule
+table, including the `style` and reactive-class cases this guide doesn't
+cover.
+
+## When to use
+
+Reach for `Props.merge` when two parties contribute props to one element: a
+shared behavior and a caller, or a base variant and a caller's override. For
+a single bag you already control, write the object directly. Merge earns its
+cost only when a key could collide.
+
+`Props.merge` is pure: calling it has no side effects and subscribes
+nothing. A merged `class` that turns out reactive is a `Stream` description.
+The renderer subscribes it once the element mounts, the same as any other
+reactive prop.
+
+## See also
+
+- [Headless Menu example](https://github.com/stefvw93/weft/tree/main/examples/headless-menu): a full behavior
+  primitive (`Menu.trigger`/`popup`/`item`) merged onto consumer-owned markup,
+  with handler chaining, ref fan-out, and a service requirement flowing
+  through the merge into `Node<E, R>`.
+- [`@weftui/dom` reference](https://weftui.dev/docs/reference/dom): the full per-key rules and `cx` grammar
+- [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs): the single-ref contract that fan-out builds on
+- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively): per-property style streams and `cx`
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): why elements are plain data you always own