@weftui/core 0.27.1 → 0.29.0

package/docs/reference/router.md

@@ -2,7 +2,7 @@
 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.
+description: "Full API surface for @weftui/router: universal nested routing, type-safe href, layouts, and SSR entry points."
 ---
 
 # @weftui/router API Reference
@@ -23,9 +23,9 @@ Three entry points mirror `@weftui/dom`:
 
 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.
+- **`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`. It is `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`
 
@@ -36,22 +36,24 @@ Router.route<Path, Query, 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).
+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.
+- **Handler-arg props**: declare `(props: `[`RouteHandlerProps<Path, Query>`](#types)`)` and the router passes the decoded `{ path, query }` straight in. `path`/`query` are 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.
+// 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.
+// 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* () {
@@ -67,7 +69,9 @@ const userRouteDI = Router.route("users/:id", {
 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.
+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`
 
@@ -85,12 +89,14 @@ Router.lazy<S extends ComponentSlot>(
 ): () => 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 })`.
+Wraps a dynamic-import loader as a component slot. The 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`.
+- **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)). The previous page stays mounted through both the fetch and any data the leaf awaits, so 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`, so 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`.
 
@@ -105,7 +111,9 @@ Router.params<F extends Fields>(fields: F): Effect<FieldsType<F>, RouterParamsEr
 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.
+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`
 
@@ -114,7 +122,9 @@ Router.paramsStream<F extends Fields>(fields: F): Effect<Subscribable<FieldsType
 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.
+The **reactive** counterparts. Each resolves a `Subscribable<FieldsType<F>>` derived from `currentMatch.changes`. A component can render `[(yield* Router.queryStream(fields)).changes]` and update **in place** even when the outlet keeps the same leaf mounted. That is 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`
 
@@ -130,24 +140,28 @@ readonly navigating: Subscribable.Subscribable<NavState>;
 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`.
+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, then back to `Idle` on commit. One signal covers both the code and data windows.
 
-- **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.
+`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`. 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:
+A leaf `component` is already an `Effect`; there is no separate loader. 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.
+- **`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.
+// 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;
@@ -155,7 +169,7 @@ const DocPage = Component.gen(function* () {
   return yield* h.article([h.h1(doc.title), h.div({ innerHTML: doc.html })]);
 });
 
-// Streaming — the await lives on a child; the leaf commits immediately.
+// 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;
@@ -171,9 +185,11 @@ const DocPage = Component.gen(function* () {
 });
 ```
 
-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.
+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.
 
-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.
+Pre-run failures (`notFound()`, a typed error, or a defect) still commit the URL. They 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.
 
@@ -201,9 +217,9 @@ href(postsRoute, { path: { id: 1 }, query: { sort: "new" } }); // "/users/1/post
 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.
+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).
+`RouterApp` requires `Router` in its environment. Provide it via `RouterLive` (client) or `RouterServer` (server), not `Effect.provide` at the node level. Services under `WeftApp` come exclusively from the app's layer, not ambient `Effect.provide`.
 
 ### `outletNode` (a.k.a. `RouterOutlet`)
 
@@ -211,9 +227,9 @@ The universal router root node — render this on both server and client. Wraps
 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`.
+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`
+## Client: `@weftui/router/client`
 
 ### `RouterLive`
 
@@ -224,11 +240,15 @@ RouterLive(
 ): 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/unstable/rpc`. Pass the same merged `group` the server wires into [`RouterServer`](#routerserver). **Scoped** — it must outlive the mount, so provide it through a `ManagedRuntime`:
+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`). This lets `@weftui/dom` 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/unstable/rpc`. Pass the same merged `group` the server wires into [`RouterServer`](#routerserver).
+
+**Scoped**: it must outlive the mount. Give it to `WeftApp.make` and the app runtime owns its lifetime (built lazily on first mount, released at `WeftApp.dispose`):
 
 ```typescript
-const runtime = ManagedRuntime.make(RouterLive(App, { rpc: { group: StockRpcs } }));
-void runtime.runPromise(hydrate(RouterApp(App), root));
+const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 ```
 
 ### Programmatic navigation
@@ -245,10 +265,10 @@ patchQuery(partial: Record<string, unknown>, options?: NavigateOptions): Effect<
 
 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.
+- **`navigate(ref, args)`**: go to a leaf route `ref` with typed `{ path, query }`. Builds the URL via [`href`](#href) (so it round-trips with `match`) and pushes the History entry, or replaces it with `options.replace`. 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";
@@ -260,7 +280,9 @@ yield * patchQuery({ sort: "old" }); // keeps the current path + other query fie
 
 ### Scroll reset
 
-Every client-committed navigation whose path differs from the previously committed path — `navigate`, `push`, `replace`, and the link interceptor — resets `window.scrollTo(0, 0)` synchronously at commit. Query-only navigations (`setQuery` / `patchQuery`, or any push/replace to the same path) preserve scroll. `popstate` (`back` / `forward`) never resets; the browser's own `history.scrollRestoration: "auto"` restores the prior offset for those entries. Server rendering is unaffected. Not configurable — there is no `NavigateOptions` field to opt out.
+Every client-committed navigation whose path differs from the previously committed path (`navigate`, `push`, `replace`, and the link interceptor) resets `window.scrollTo(0, 0)` synchronously at commit. Query-only navigations (`setQuery` / `patchQuery`, or any push/replace to the same path) preserve scroll.
+
+`popstate` (`back` / `forward`) never resets; the browser's own `history.scrollRestoration: "auto"` restores the prior offset for those entries. Server rendering is unaffected. Not configurable: there is no `NavigateOptions` field to opt out.
 
 ### `installLinkInterceptor`
 
@@ -268,9 +290,9 @@ Every client-committed navigation whose path differs from the previously committ
 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.
+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`). It leaves modified clicks, `target=_blank`, `download`, external origins, same-document navigations, and non-matching hrefs to the browser.
 
-## Server — `@weftui/router/server`
+## Server: `@weftui/router/server`
 
 ### `RouterServer`
 
@@ -281,14 +303,14 @@ RouterServer.render(def, options: { document; rpc; url }): Effect<{ html; status
 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.
+Dispatch runs through the `def.httpApi` spine via `HttpApiBuilder`: platform owns request→leaf matching and path/query decode. Each leaf handler then 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`.
+- **`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.
+- **`rpc`** is the app's [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) data foundation: `{ group: RpcGroup<any>; handlers: Layer<any, never, never> }`. That is 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. 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.
+> 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`. That is the single source of truth both the server dispatch and the client matcher / derived `HttpApiClient` read from.
 
 ## Errors
 
@@ -338,7 +360,7 @@ These power the runtime and are exported for tooling/tests; most apps never touc
 | `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`.                                 |
+| `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.                                                                                                   |
@@ -346,7 +368,7 @@ These power the runtime and are exported for tooling/tests; most apps never touc
 
 ## 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`
+- [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
+- [`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

@@ -2,14 +2,12 @@
 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.
+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.
+We assume you know [Effect](https://effect.website/docs/getting-started/introduction) fundamentals. Weft is Effect for the UI, so we will not re-explain `Effect.gen`, services, or streams from scratch.
 
 ## Install
 
@@ -23,28 +21,29 @@ Weft tracks Effect 4's beta line. This release is built and tested against `effe
 
 ## 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:
+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 { WeftApp } 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")!));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, 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.
+- `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).
+- `WeftApp.make()` creates a Weft app synchronously, with no layer to build yet. `WeftApp.mount(app, node, target)` renders the node into `target`, building real DOM and starting any reactive streams. It returns `Effect<RootHandle, …>` with `R = never`, so a bare `Effect.runPromise` runs it with no `Effect.provide` needed. You will give `WeftApp.make` a `Layer` once components need services: see [Services and Async](https://weftui.dev/docs/tutorial/03-services-and-async).
+- 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
+- [Reactivity →](https://weftui.dev/docs/tutorial/02-reactivity): make the UI change over time with `SubscriptionRef` and streams

package/docs/tutorial/02-reactivity.md

@@ -7,7 +7,7 @@ description: Add component-local state with SubscriptionRef and weave its stream
 
 # 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.**
+[Previously](https://weftui.dev/docs/tutorial/01-your-first-app) we mounted a static component. Now we make it change over time. This is the defining move in Weft: **weave a stream through the tree, and only that point updates.**
 
 ## Local state with `SubscriptionRef`
 
@@ -15,7 +15,7 @@ Use Effect's `SubscriptionRef` for component-local state. `SubscriptionRef.chang
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect, SubscriptionRef } from "effect";
 
 const Counter = () =>
@@ -29,18 +29,21 @@ const Counter = () =>
     ]);
   });
 
-void Effect.runPromise(mount(Counter(), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, 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.
+`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 `SubscriptionRef.changes(count)` 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.
+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 `SubscriptionRef.changes(count)` 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.** `[SubscriptionRef.changes(count)]` — 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.
+> **Note.** In `[SubscriptionRef.changes(count)]` 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
 
@@ -50,8 +53,8 @@ Because `SubscriptionRef.changes(count)` returns a `Stream`, you shape reactive
 h.span([Stream.map(SubscriptionRef.changes(count), (n) => `Count: ${n}`)]);
 ```
 
-Anywhere you would compute a derived value, map the stream instead — the derivation stays reactive.
+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
+- [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

@@ -7,16 +7,16 @@ description: Give handlers access to services from the environment, and render a
 
 # 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.
+[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:
+An event handler can **return an Effect**. That Effect runs in the app's environment, so it can read any service the app's layer provides:
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
-import { Context, Effect, Layer, pipe } from "effect";
+import { WeftApp } from "@weftui/dom/client";
+import { Context, Effect, Layer } from "effect";
 
 class Logger extends Context.Service<Logger, { log: (message: string) => Effect.Effect<void> }>()(
   "Logger",
@@ -38,13 +38,14 @@ const LogButton = () =>
     "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)),
-);
+// Give the app the layer: every handler in every root can now read Logger.
+const app = WeftApp.make(LoggerLive);
+void Effect.runPromise(WeftApp.mount(app, LogButton(), document.getElementById("root")!));
 ```
 
-`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).
+`Logger` entered the tree's requirement channel the moment `LogButton` read it. You discharged it **once**, by passing `LoggerLive` to `WeftApp.make`. Provide too little and it is a compile error. The type of `app` (and so of `WeftApp.mount(app, LogButton(), …)`) names exactly which service is missing.
+
+Services come exclusively from the app's layer: an `Effect.provide` wrapped around the `mount` call does **not** reach components or handlers. 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
 
@@ -52,7 +53,7 @@ A component can return a **`Stream<Node>`** to show different content over time.
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect, Stream } from "effect";
 
 const AsyncGreeting = ({ name }: { name: string }) =>
@@ -66,11 +67,16 @@ const AsyncGreeting = ({ name }: { name: string }) =>
     ),
   );
 
-void Effect.runPromise(mount(AsyncGreeting({ name: "World" }), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(
+  WeftApp.mount(app, 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.
+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. To coordinate _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
+- [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

@@ -2,12 +2,12 @@
 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.
+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.
+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
 
@@ -25,11 +25,13 @@ const SafeWidget = () =>
   ]);
 ```
 
-There are six failure-catch variants — `catch`, `catchCause`, `catchTag`, `catchTags`, `catchFilter`, `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).
+There are six failure-catch variants, mirroring Effect's own error operators: `catch`, `catchCause`, `catchTag`, `catchTags`, `catchFilter`, `catchIf`. 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:
+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). `hydrate` adopts that existing DOM and resumes reactivity:
 
 ```typescript
 // server entry
@@ -42,14 +44,22 @@ export const render = () => Effect.runPromise(renderToStringHydratable(App()));
 
 ```typescript
 // client entry
-import { hydrate } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect } from "effect";
 import { App } from "./app";
 
-void Effect.runPromise(hydrate(App(), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.hydrate(app, 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.
+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:
+
+1. Resolve an rpc on the server.
+2. Serialize its result into the HTML.
+3. Replay it on hydrate.
+4. Keep the region live for refetch.
 
 ## You're done
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weftui/core",
-  "version": "0.27.1",
-  "description": "Element builders and combinators for Weft — reactive UI, woven from Effect",
+  "version": "0.29.0",
+  "description": "Element builders and combinators for Weft: reactive UI, woven from Effect",
   "keywords": [
     "combinators",
     "dom",
@@ -41,13 +41,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.1",
     "csstype": "^3.2.3",
     "effect": "4.0.0-beta.98",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2",
-    "vite-plus": "0.2.2"
+    "tstyche": "^7.2.2",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.5",
+    "vite-plus": "0.2.5"
   },
   "peerDependencies": {
     "effect": ">=4.0.0-beta.98 <4.0.0"