@weftui/router 0.28.0 → 0.29.0

package/dist/{outlet-C9N4a4_F.js → outlet-BgJmsO_g.js}

@@ -27,7 +27,7 @@ const notFound = (path) => Effect.fail(new RouterNotFound({ path }));
 const isRouterNotFound = (u) => typeof u === "object" && u !== null && "_tag" in u && u._tag === "RouterNotFound";
 /**
 * Tagged error raised by `Router.params` / `Router.query` when the live match does
-* not satisfy the requested fields — either no route is matched, or a requested
+* not satisfy the requested fields: either no route is matched, or a requested
 * key is missing / fails its schema's `Type`-side validation. `source` records
 * whether the failure was on the path params or the query, and `keys` lists the
 * requested field names for diagnostics.
@@ -93,9 +93,9 @@ function longestCommonSegmentPrefix(partsList) {
 * Pass 1 walks the tree: only **routes** contribute path parts (layouts own no
 * path), so each leaf's `parts` come solely from the route segments on its branch,
 * and its ancestor `LayoutNode`s are recorded in order. Pass 2 derives one shared
-* {@link CompiledLayout} per distinct layout node — its `patternPrefix` is the
-* longest common path prefix of that layout's subtree leaves — then assembles each
-* leaf's `layoutChain` (root → parent) and merged path schema.
+* {@link CompiledLayout} per distinct layout node, whose `patternPrefix` is the
+* longest common path prefix of that layout's subtree leaves. It then assembles
+* each leaf's `layoutChain` (root → parent) and merged path schema.
 */
 function compile(def) {
 	const leafWorks = [];
@@ -156,7 +156,7 @@ function compile(def) {
 }
 /**
 * Builds the authoritative `HttpApi` for a compiled tree (S4): a single `"pages"`
-* group whose endpoints are GET endpoints — one per leaf — at each leaf's full path
+* group holding one GET endpoint per leaf, at each leaf's full path
 * pattern, carrying `params: pathSchema`, `query: querySchema`, a
 * `Schema.String` (text/HTML) success, and a `RouterNotFound → 404` error. The tree
 * (not `HttpApi`) is the authoring surface; this is the single source of truth the
@@ -237,7 +237,7 @@ function makeLayout(config, children) {
 	};
 }
 /**
-* Brand key marking a {@link ComponentSlot} as **preloadable** — a lazy slot
+* Brand key marking a {@link ComponentSlot} as **preloadable**: a lazy slot
 * ({@link lazyComponent}) carries a `preload()` under this key. Internal to
 * `@weftui/router` (read by the client `navigate` to resolve a matched branch's
 * chunks before commit; see `pending-navigation.specs.md`); not public API.
@@ -255,24 +255,16 @@ function getPreload(slot) {
 }
 /**
 * Wraps a dynamic-import `load` as a lazy {@link ComponentSlot}: the route's descriptor
-* (`segment`, `path`/`query`) stays eager and matchable, while the component — the render
-* body and its module's deps — is split into the chunk `load` resolves. The router invokes
+* (`segment`, `path`/`query`) stays eager and matchable, while the component (the render
+* body and its module's deps) is split into the chunk `load` resolves. The router invokes
 * the returned slot at render time; it awaits `load` then renders the resolved component,
 * adopting the server DOM in place on hydration (flash-free) and fetching the chunk on
 * client navigation. Exposed as {@link Router.lazy}. See `lazy-component.specs.md`.
 *
 * The resolved value is a component slot (`Component.gen` / `Component.make`, or a
-* `() => Node` thunk) — the shape `component:` already accepts — so its `E`/`R` channels
+* `() => Node` thunk), the shape `component:` already accepts, so its `E`/`R` channels
 * are recovered via {@link SlotNode} and propagate up the tree exactly as an eager
 * component's do.
-*
-* @example
-* ```ts
-* Router.route("docs/:category/:slug", {
-*   path: { category: Schema.String, slug: Schema.String },
-*   component: Router.lazy(() => import("./doc-page").then((m) => m.DocPage)),
-* });
-* ```
 */
 function lazyComponent(load) {
 	let cached;
@@ -296,7 +288,7 @@ var Router = class extends Context.Service()("@weftui/router/Router") {};
 * reads it with `yield* Router.Outlet`.
 *
 * Typed **opaque** as `Node<never, never>` so splicing `[outlet]` adds nothing to
-* a layout's local channels — the subtree's real channels are aggregated
+* a layout's local channels: the subtree's real channels are aggregated
 * structurally by {@link makeLayout} / {@link makeRouter}, never inferred across
 * this DI boundary. Re-exported on the namespace as `Router.Outlet`.
 */
@@ -309,10 +301,10 @@ function pick(fields, record) {
 }
 /**
 * Reads the live match's **path params** for the requested `fields`. Snapshot
-* semantics — reads `yield* Router` then `currentMatch.get` — and returns the
+* semantics (reads `yield* Router`, then `currentMatch.get`), returning the
 * already-decoded values **directly**: the matcher decoded them against the leaf's
-* full path schema, so no re-validation is needed (the cast is sound — the picked
-* subset is the `Type` side of `fields`). Fails with a {@link RouterParamsError}
+* full path schema, so no re-validation is needed. The cast is sound because the
+* picked subset is the `Type` side of `fields`. Fails with a {@link RouterParamsError}
 * (`source: "path"`) only when no route is matched. Re-exported as `Router.params`.
 */
 function readParams(fields) {
@@ -398,7 +390,7 @@ const subscribeNavigating = Effect.map(Router, (router) => router.navigating);
 //#endregion
 //#region src/resolved-commit.ts
 /**
-* Internal seams for resolve-before-commit navigation — the resolved-commit
+* Internal seams for resolve-before-commit navigation: the resolved-commit
 * stash and the staged match view. See `resolve-before-commit.specs.md`.
 *
 * **Not public API.** This module is deliberately not re-exported from
@@ -419,10 +411,10 @@ const subscribeNavigating = Effect.map(Router, (router) => router.navigating);
 */
 const ResolvedCommit = Symbol.for("@weftui/router/resolved-commit");
 /**
-* Writes the stash on the (client) router instance: called by `navigate` /
-* popstate with the pre-run's `Exit`, immediately before the URL ref is set,
-* so the outlet emission triggered by that commit finds it (AC-R1/AC-R2).
-* Overwrites any stale entry — latest-wins already guarantees only the newest
+* Writes the stash on the (client) router instance. Called by `navigate` /
+* popstate with the pre-run's `Exit`, immediately before the URL ref is set, so
+* the outlet emission triggered by that commit finds it (AC-R1/AC-R2).
+* Overwrites any stale entry: latest-wins already guarantees only the newest
 * navigation reaches the commit step (AC-R6).
 */
 function setResolvedCommit(router, entry) {
@@ -430,10 +422,10 @@ function setResolvedCommit(router, entry) {
 }
 /**
 * Consumes the stash: returns the entry when its `url` equals the emission's
-* `match.url` and **clears the slot** (consume-exactly-once, AC-R2), else
-* `undefined` — a URL mismatch (stale entry) or an absent slot (server render,
-* hydration, non-navigation re-emission) falls through to the ordinary slot
-* invocation in `renderLevel`.
+* `match.url` and **clears the slot** (consume-exactly-once, AC-R2). Otherwise
+* returns `undefined`, so a URL mismatch (stale entry) or an absent slot (server
+* render, hydration, non-navigation re-emission) falls through to the ordinary
+* slot invocation in `renderLevel`.
 */
 function takeResolvedCommit(router, url) {
 	const slot = router;
@@ -444,13 +436,13 @@ function takeResolvedCommit(router, url) {
 }
 /**
 * The staged `Router` view the pre-run executes under (AC-R4): identical to
-* `router` except `currentMatch.get` resolves to the **target** match — the
-* URL ref has not moved yet, and one-shot reads (`Router.params`,
-* `Router.query`, `currentMatch.get`) inside the pre-running component body
-* must decode the destination, not the page being left. `currentMatch.changes`
-* (and `navigate` / `httpApiClient` / `navigating`) delegate to the live
-* service, so reactive subscriptions — which occur at render/mount time,
-* post-commit — observe the committed match onward.
+* `router` except `currentMatch.get` resolves to the **target** match. The URL
+* ref has not moved yet, and one-shot reads (`Router.params`, `Router.query`,
+* `currentMatch.get`) inside the pre-running component body must decode the
+* destination, not the page being left. `currentMatch.changes` (and `navigate` /
+* `httpApiClient` / `navigating`) delegate to the live service, so reactive
+* subscriptions, which occur at render/mount time post-commit, observe the
+* committed match onward.
 */
 function stageMatch(router, target) {
 	return {
@@ -462,15 +454,15 @@ function stageMatch(router, target) {
 	};
 }
 /**
-* Pre-runs a matched leaf's component effect: invokes the slot with the
-* target match's handler-arg props (`{ path, query }` — exactly what
-* `renderLevel` passes), under the {@link stageMatch | staged view}, and
-* captures the outcome as an `Exit` (AC-R1/AC-R7). The returned effect never
-* fails — failures are folded into the `Exit` for stash-and-replay — but it
-* is **interruptible**: a superseding navigation interrupts the whole pre-run
-* fiber (AC-R6). Requires the caller's runtime context (the `RouterLive`
-* layer's — `Router`, `AppRpcClientTag`, app services), which is what makes
-* the pre-run possible at all (Feasibility §1).
+* Pre-runs a matched leaf's component effect: invokes the slot with the target
+* match's handler-arg props (`{ path, query }`, exactly what `renderLevel`
+* passes), under the {@link stageMatch | staged view}, and captures the outcome
+* as an `Exit` (AC-R1/AC-R7). The returned effect never fails, since failures
+* are folded into the `Exit` for stash-and-replay, but it is **interruptible**:
+* a superseding navigation interrupts the whole pre-run fiber (AC-R6). Requires
+* the caller's runtime context (the `RouterLive` layer's: `Router`,
+* `AppRpcClientTag`, app services), which is what makes the pre-run possible at
+* all (Feasibility §1).
 */
 function preRunLeaf(router, target) {
 	return Effect.suspend(() => {

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-import { S as Router, i as RouterDef, l as ComponentSlot } from "../compile-DySac7KN.js";
+import { S as Router, i as RouterDef, l as ComponentSlot } from "../compile-Bb7AknG_.js";
 import { Effect, Layer } from "effect";
 import { AppRpcClientTag } from "@weftui/core";
 import { RpcGroup } from "effect/unstable/rpc";
@@ -8,15 +8,15 @@ import { RpcGroup } from "effect/unstable/rpc";
  * authoritative `HttpApi` spine via `HttpApiBuilder`: platform owns request→leaf
  * matching and path/query decode, then each leaf handler builds a fixed-match
  * server `Router`, renders the universal outlet to hydratable HTML, and replies
- * `text/html`. Status comes from the platform pipeline — a no-match (platform's
+ * `text/html`. Status comes from the platform pipeline: a no-match (platform's
  * `RouteNotFound`) and a page-raised `RouterNotFound` both render the configured
- * `notFound` page at HTTP 404 — so there is no render-time status side-channel.
+ * `notFound` page at HTTP 404, so there is no render-time status side-channel.
  */
 declare namespace RouterServer {
   /**
    * The app's `Boundary.rpc` data foundation: the merged `RpcGroup` contract plus
    * its server-only handler `Layer`. Wired explicitly (no co-located `load`, no
-   * registry) — `toWebHandler` serves it at `POST /_eui/rpc`, and an in-process
+   * registry): `toWebHandler` serves it at `POST /_eui/rpc`, and an in-process
    * client over the same handlers resolves SSR boundaries in-process.
    */
   export interface RpcOptions {
@@ -27,7 +27,7 @@ declare namespace RouterServer {
   }
   /**
    * Shared server options. The document shell is a {@link ComponentSlot} that splices
-   * the app via `yield* Router.Outlet` (the router provides it per request) —
+   * the app via `yield* Router.Outlet` (the router provides it per request),
    * typically `<html><head>…</head><body><div id="root">{app}</div><script …></body></html>`.
    * The router provides both `Router.Outlet` (the app, per request) and `Router` (to read
    * params), so the document may use either. Mirrors the route/layout `component` slot,
@@ -37,7 +37,7 @@ declare namespace RouterServer {
    * `context` is the render-time provide seam (spec:
    * `ambient-context-propagation.specs.md`): an app-wide `Layer` provided to the
    * document shell **and** every route/layout leaf. It is required exactly when the
-   * def carries residual app services ({@link AppServices} — its aggregate `R` minus
+   * def carries residual app services ({@link AppServices}: its aggregate `R` minus
    * the `Router` / `Router.Outlet` / `AppRpcClientTag` the router already threads) and
    * disallowed otherwise, so a missing provide is a compile error and `rpc`-only /
    * no-service apps stay unchanged (surfaced via {@link ContextOption} at each entry).
@@ -47,7 +47,7 @@ declare namespace RouterServer {
     readonly document: ComponentSlot;
     /**
      * The app's `Boundary.rpc` foundation (contract + server handlers). Optional:
-     * omit when the app has no `Boundary.rpc` — then `POST /_eui/rpc` is not
+     * omit when the app has no `Boundary.rpc`. Then `POST /_eui/rpc` is not
      * served (it falls through to page dispatch) and a stray `Boundary.rpc`
      * fails with a descriptive error instead of rendering.
      */
@@ -56,12 +56,12 @@ declare namespace RouterServer {
   /**
    * The residual app services a caller must still provide through the {@link Options.context}
    * seam: a def's aggregate requirement `R` **minus** the services the router already
-   * threads in per render — `Router` and `Router.Outlet` (provided by the outlet /
+   * threads in per render: `Router` and `Router.Outlet` (provided by the outlet /
    * document plumbing) and `AppRpcClientTag` (provided from the `rpc` option). When this
    * resolves to `never` the app has no app-wide service to inject and `context` is disallowed.
    */
   export type AppServices<R> = Exclude<R, Router | Router.Outlet | AppRpcClientTag>;
-  /** True only for the exact `any` type — a loosely-typed `RouterDef<any, any>`. */
+  /** True only for the exact `any` type: a loosely-typed `RouterDef<any, any>`. */
   type IsAny<T> = 0 extends 1 & T ? true : false;
   /**
    * Conditionally shapes the `context` field at each entry point: **required** (a

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { a as Router, f as isRouterNotFound, n as outletNode, u as RouterNotFound } from "../outlet-C9N4a4_F.js";
+import { a as Router, f as isRouterNotFound, n as outletNode, u as RouterNotFound } from "../outlet-BgJmsO_g.js";
 import { HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Cause, Effect, Exit, Layer, Option, Schema, Scope, Stream } from "effect";
 import { AppRpcClientTag, Subscribable } from "@weftui/core";
@@ -36,19 +36,19 @@ let RouterServer;
 	/**
 	* In-process {@link AppRpcClientTag} Layer over the app's handler Layer
 	* ({@link RpcTest.makeClient}, flat, no protocol/serialization). SSR
-	* `Boundary.rpc` resolution calls `call(tag, payload())` against this — the rpc
+	* `Boundary.rpc` resolution calls `call(tag, payload())` against this: the rpc
 	* runs in-process, never over the network.
 	*
 	* The render path requires the tag unconditionally, so with no `rpc` configured
-	* a stub is provided whose `call` fails descriptively — a `Boundary.rpc` in an
-	* rpc-less app surfaces the misconfiguration instead of dying opaquely.
+	* a stub is provided whose `call` fails descriptively. A `Boundary.rpc` in an
+	* rpc-less app then surfaces the misconfiguration instead of dying opaquely.
 	*/
 	function appRpcClientLayer(rpc) {
 		if (rpc === void 0) return Layer.succeed(AppRpcClientTag, AppRpcClientTag.of({ call: (tag) => Effect.fail(/* @__PURE__ */ new Error(`Boundary.rpc "${tag}" cannot resolve: no \`rpc\` option was passed to RouterServer`)) }));
 		return Layer.effect(AppRpcClientTag, Effect.map(RpcTest.makeClient(rpc.group, { flatten: true }), (flat) => AppRpcClientTag.of({ call: (tag, payload) => flat(tag, payload) }))).pipe(Layer.provide(rpc.handlers));
 	}
 	/**
-	* Renders the document shell — with `app` spliced via `Router.Outlet` — to a
+	* Renders the document shell (with `app` spliced via `Router.Outlet`) to a
 	* hydratable HTML string. The whole tree (shell + every route/layout leaf) drains
 	* in this one `renderToStringHydratable` context, so the app-wide `options.context`
 	* Layer provided here reaches the leaves too (the render-time provide seam). No
@@ -60,7 +60,7 @@ let RouterServer;
 	/**
 	* Renders the configured `notFound` page **directly** in the shell (no nested
 	* outlet, no reactive-region markers) at `status`. Mirrors the client's internal
-	* not-found boundary fallback — which replaces the whole outlet subtree — so the
+	* not-found boundary fallback, which replaces the whole outlet subtree, so the
 	* page-raised-404 HTML aligns for hydration.
 	*/
 	function renderNotFoundDirect(def, options, url, status) {
@@ -73,8 +73,8 @@ let RouterServer;
 	/**
 	* Renders the no-match case: the bare {@link outletNode} with a `NotFound` match,
 	* so the `notFound` page renders **inside** the level-0 reactive region (markers
-	* present) — matching what the client outlet produces for an unmatched URL — at
-	* HTTP 404.
+	* present) at HTTP 404, matching what the client outlet produces for an
+	* unmatched URL.
 	*/
 	function renderNoMatch(def, options, url) {
 		const router = serverRouter({
@@ -142,9 +142,9 @@ let RouterServer;
 	/**
 	* Builds (and memoizes) the platform `(Request) => Promise<Response>` handler for
 	* `def`. Dispatch runs through a **server-local** `HttpApi`: `def.httpApi`
-	* (pristine — the client and the spec read it) extended with a second `"fallback"`
+	* (pristine: the client and the spec read it) extended with a second `"fallback"`
 	* group holding one catch-all `"*"` endpoint. Platform owns matching: a request
-	* routes to the specific leaf endpoint, or — when nothing matches — to the
+	* routes to the specific leaf endpoint, or, when nothing matches, to the
 	* catch-all, which renders the configured not-found page at 404. (Platform's own
 	* unmatched path resolves a default empty 404 before any response hook can rewrite
 	* it, so the catch-all is the route that keeps no-match rendering ours.)

package/docs/explanation/boundaries-and-suspense.md

@@ -2,18 +2,20 @@
 title: Boundaries and Suspense
 order: 4
 section: explanation
-description: How Weft models failure, async, and server data as boundary nodes in the same tree — failure-catch variants, Boundary.suspend, and Boundary.rpc, and how their E/R channels behave.
+description: How Weft models failure, async, and server data as boundary nodes in the same tree. Covers failure-catch variants, Boundary.suspend, and Boundary.rpc, and how their E/R channels behave.
 ---
 
 # Boundaries and Suspense
 
-A **boundary** is a node that intercepts something flowing through the tree — an error, a pending async child, or a server-resolved value — and decides what the DOM shows in its place. Because a boundary is itself a `Node<E, R>` ([nodes are Effects](https://weftui.dev/docs/explanation/rendering-model)), it composes exactly like any other element: you nest it, and its children's channels flow through it under a transformation the boundary defines.
+A **boundary** is a node that intercepts something flowing through the tree: an error, a pending async child, or a server-resolved value. It decides what the DOM shows in its place.
+
+A boundary is itself a `Node<E, R>` ([nodes are Effects](https://weftui.dev/docs/explanation/rendering-model)), so it composes exactly like any other element. You nest it, and its children's channels flow through it under a transformation the boundary defines.
 
 The `Boundary` namespace has three kinds. This page is the conceptual map; the [core reference](https://weftui.dev/docs/reference/core#boundary-namespace) has the full signatures.
 
 ## Failure boundaries
 
-A component's `E` channel accumulates up the tree. A **failure boundary** is where you _discharge_ some of that `E`: it wraps children and, if one of them fails, renders a fallback instead of letting the failure propagate to the mount.
+A component's `E` channel accumulates up the tree. A **failure boundary** is where you _discharge_ some of that `E`. It wraps children and, if one of them fails, renders a fallback instead of letting the failure propagate to the mount.
 
 ```typescript
 import { Boundary, h } from "@weftui/core";
@@ -32,19 +34,25 @@ There are six failure-catch variants, mirroring Effect's own error operators so
 | `catchTag` / `catchTags`  | one / several tagged errors by `_tag`      |
 | `catchFilter` / `catchIf` | a selected subset, by `Filter` / predicate |
 
-The channel algebra is the whole reason they exist: `catchTag("Foo", …)` removes `Foo` from the children's `E` and adds whatever the fallback needs — so the type of the boundary node reflects exactly which failures are still live and which were handled. An unhandled failure re-raises to the **nearest enclosing** boundary; if none catches it at **mount time**, mounting fails. Boundaries nest, so an inner `catchTag` can handle a specific case while an outer `catch` sweeps the rest.
+The channel algebra is the whole reason they exist. `catchTag("Foo", …)` removes `Foo` from the children's `E` and adds whatever the fallback needs. The type of the boundary node therefore reflects exactly which failures are still live and which were handled.
+
+An unhandled failure re-raises to the **nearest enclosing** boundary; if none catches it at **mount time**, mounting fails. Boundaries nest, so an inner `catchTag` can handle a specific case while an outer `catch` sweeps the rest.
 
 ### Post-mount failures with no enclosing boundary
 
-The routing above describes what happens while a node is being built. Once mounted, a reactive region — an attribute, child, or list stream, or a hydrated equivalent — keeps running for the lifetime of its scope, and it can still fail later: a `Stream` backing a `Boundary.rpc` resource might raise `RouterNotFound` after a client-side navigation, for instance. If a `BoundaryContext` encloses the region, the failure routes to it exactly as above, and the boundary's fallback swaps in.
+The routing above describes what happens while a node is being built. Once mounted, a reactive region (an attribute, child, or list stream, or a hydrated equivalent) keeps running for the lifetime of its scope. It can still fail later: a `Stream` backing a `Boundary.rpc` resource might raise `RouterNotFound` after a client-side navigation. If a `BoundaryContext` encloses the region, the failure routes to it exactly as above, and the boundary's fallback swaps in.
+
+If no boundary encloses it, there is nothing to swap to. Weft does not synthesize one. The region's DOM keeps its last rendered content, and a watcher fiber (forked into the same scope alongside the subscription itself) observes its exit directly.
+
+When that exit is a failure whose cause is not interruption-only, Weft reports it explicitly via `Effect.logError(exit.cause)`. The log is annotated with `weft.region` to identify the failing region by kind and identity (e.g. `attribute:class`, `child:stream-3`, `list:stream-2`, `hydrate:stream-1 (/products/42)`). This fires for typed failures and defects alike, in both dev and prod, exactly once per failing region, at the `"Error"` level. Interruption (the ordinary case of unmount tearing down the region's scope) is never reported; only genuine failures are.
 
-If no boundary encloses it, there is nothing to swap to. Weft does not synthesize one: the region's DOM keeps its last rendered content, and a watcher fiber — forked into the same scope alongside the subscription itself — observes its exit directly. When that exit is a failure whose cause is not interruption-only, Weft reports it explicitly via `Effect.logError(exit.cause)`, annotated with `weft.region` to identify the failing region by kind and identity (e.g. `attribute:class`, `child:stream-3`, `list:stream-2`, `hydrate:stream-1 (/products/42)`). This fires for typed failures and defects alike, in both dev and prod, exactly once per failing region, at the `"Error"` level. Interruption — the ordinary case of unmount tearing down the region's scope — is never reported; only genuine failures are.
+This is deliberate. Rather than leave the failure to whatever the Effect runtime would do with an unobserved fiber exit, Weft observes and logs it itself. Visibility is therefore controlled by the same knobs any Effect program uses: `References.MinimumLogLevel` (provided via `Effect.provideService`) to filter it, or a custom `Logger` to route it elsewhere.
 
-This is deliberate: rather than leaving the failure to whatever the Effect runtime would otherwise do with an unobserved fiber exit, Weft observes and logs it itself, so visibility is controlled by the same knobs any Effect program uses — `References.MinimumLogLevel` (provided via `Effect.provideService`) to filter it, or a custom `Logger` to route it elsewhere. A stream that can fail and has no enclosing boundary is a stream whose failures you've chosen not to route into the UI — the log is what tells you that decision has consequences at runtime.
+A stream that can fail and has no enclosing boundary is a stream whose failures you've chosen not to route into the UI. The log is what tells you that decision has consequences at runtime.
 
 ## Suspense boundaries
 
-`Boundary.suspend` wraps async children and shows a `fallback` until **all** of them have emitted their first value, then swaps atomically — either everything is visible or nothing is. This prevents partial flicker when sibling async regions resolve at different times.
+`Boundary.suspend` wraps async children and shows a `fallback` until **all** of them have emitted their first value. Then it swaps atomically: either everything is visible or nothing is. This prevents partial flicker when sibling async regions resolve at different times.
 
 ```typescript
 import { Boundary, h } from "@weftui/core";
@@ -55,15 +63,22 @@ Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading…") }, [
 ]);
 ```
 
-A suspense boundary is transparent to the type channels: its node is `Node<ChildrenE, ChildrenR>` — the children's `E`/`R` pass straight through, exactly as they would for a plain `h.*` parent. It changes _timing_ (when the children become visible), not _types_.
+A suspense boundary is transparent to the type channels: its node is `Node<ChildrenE, ChildrenR>`. The children's `E`/`R` pass straight through, exactly as they would for a plain `h.*` parent. It changes _timing_ (when the children become visible), not _types_.
 
-On the server, `renderToStreamHydratable` emits the fallback inline and appends patch scripts as children resolve; on the client, `hydrate` sees through the boundary and adopts the already-resolved DOM directly.
+On the server, `renderToStreamHydratable` emits the fallback inline and appends patch scripts as children resolve. On the client, `hydrate` sees through the boundary and adopts the already-resolved DOM directly.
 
-> **Note.** There is no `Suspense` export — the API is `Boundary.suspend(props, children)`. Reach for it for async that loads **on the client**; for data that must resolve on the **server** and hydrate without a second request, use `Boundary.rpc` (below).
+> **Note.** There is no `Suspense` export; the API is `Boundary.suspend(props, children)`. Reach for it for async that loads **on the client**. For data that must resolve on the **server** and hydrate without a second request, use `Boundary.rpc` (below).
 
 ## The rpc boundary
 
-`Boundary.rpc` is the server-data boundary: it resolves one `Rpc` on the server, serializes the result into the HTML, replays it on the client during `hydrate` (no second request, no flash), and then keeps the region live for `refetch`. Conceptually it is the same idea as the other boundaries — a node that decides what renders in a subtree — but the thing it intercepts is a **round-trip to a server handler**, and instead of a children array it takes a `render` function that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea).
+`Boundary.rpc` is the server-data boundary. It:
+
+- resolves one `Rpc` on the server
+- serializes the result into the HTML
+- replays it on the client during `hydrate` (no second request, no flash)
+- keeps the region live for `refetch`
+
+Conceptually it is the same idea as the other boundaries: a node that decides what renders in a subtree. But the thing it intercepts is a **round-trip to a server handler**. Instead of a children array, it takes a `render` function that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea).
 
 ```typescript
 import { Boundary, h } from "@weftui/core";
@@ -77,15 +92,19 @@ Boundary.rpc(
 );
 ```
 
-Unlike the failure and suspense boundaries, `Boundary.rpc` is not self-contained: it resolves through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam that `@weftui/router` provides on both sides. Its channel behavior is also distinct — the rpc's typed `error` schema joins the node's `E` (replayable through an enclosing failure boundary), while `render`'s `R` passes through untouched. The full model — the contract/handler split, the four lifecycles, typed-failure replay — is a **how-to**, not repeated here: [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc).
+Unlike the failure and suspense boundaries, `Boundary.rpc` is not self-contained. It resolves through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam that `@weftui/router` provides on both sides.
+
+Its channel behavior is also distinct. The rpc's typed `error` schema joins the node's `E` (replayable through an enclosing failure boundary), while `render`'s `R` passes through untouched. The full model (the contract/handler split, the four lifecycles, typed-failure replay) is a **how-to**, not repeated here: [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc).
 
 ## One tree, three interceptors
 
-The unifying idea: failure, async pending state, and server data are not three separate subsystems bolted onto the renderer. They are three **boundary nodes** in the one tree, each intercepting a different thing flowing through it, each with channel behavior you can read off its type. That is why they nest freely — a `Boundary.catchTag` can wrap a `Boundary.rpc` to catch its typed failure, and a `Boundary.suspend` can wrap async siblings that themselves contain rpc boundaries.
+The unifying idea: failure, async pending state, and server data are not three separate subsystems bolted onto the renderer. They are three **boundary nodes** in the one tree, each intercepting a different thing flowing through it. Each has channel behavior you can read off its type.
+
+That is why they nest freely. A `Boundary.catchTag` can wrap a `Boundary.rpc` to catch its typed failure. A `Boundary.suspend` can wrap async siblings that themselves contain rpc boundaries.
 
 ## See also
 
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why a boundary is just a node in a static tree
-- [`Boundary` API reference](https://weftui.dev/docs/reference/core#boundary-namespace) — every variant's signature and channel algebra
-- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc) — the full `Boundary.rpc` walkthrough and its four lifecycles
-- [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server) — how suspense and rpc boundaries stream and hydrate
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): why a boundary is just a node in a static tree
+- [`Boundary` API reference](https://weftui.dev/docs/reference/core#boundary-namespace): every variant's signature and channel algebra
+- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc): the full `Boundary.rpc` walkthrough and its four lifecycles
+- [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server): how suspense and rpc boundaries stream and hydrate

package/docs/explanation/combinator-api.md

@@ -7,7 +7,9 @@ description: How h, h.fragment, and Component.gen / Component.make work; why Nod
 
 # The Combinator API
 
-Weft builds UI trees by calling builder functions. Because component return types stay as generic `Effect.Effect<ElementDescriptor, E, R>`, the error channel (`E`) and requirements channel (`R`) propagate through the entire tree — visible to the type checker, satisfiable at the mount boundary. JSX collapses every component's return type to an opaque `JSX.Element`, erasing both channels; the combinator API exists specifically to keep them intact.
+Weft builds UI trees by calling builder functions. Because component return types stay as generic `Effect.Effect<ElementDescriptor, E, R>`, the error channel (`E`) and requirements channel (`R`) propagate through the entire tree: visible to the type checker, satisfiable at the mount boundary.
+
+JSX collapses every component's return type to an opaque `JSX.Element`, erasing both channels. The combinator API exists specifically to keep them intact.
 
 ## Nodes are Effects
 
@@ -23,13 +25,13 @@ Nodes are first-class Effects. Everything in the Effect ecosystem works on them
 import { h } from "@weftui/core";
 import { Effect } from "effect";
 
-// yield* in Effect.gen — R propagates into the generator's context
+// yield* in Effect.gen: R propagates into the generator's context
 const node = yield * h.div({ class: "container" }, "Hello");
 
-// pipe — chain Effect operators directly
+// pipe: chain Effect operators directly
 const provided = pipe(h.div(userStream), Effect.provide(UserServiceLive));
 
-// Effect.flatMap — sequence node creation with async logic
+// Effect.flatMap: sequence node creation with async logic
 const card = pipe(
   fetchCard(id),
   Effect.flatMap((data) => h.div({ class: "card" }, data.title)),
@@ -78,7 +80,7 @@ Reactive prop values (any `Stream`, `Effect`, or `Subscribable`) contribute thei
 ```typescript
 declare const colorStream: Stream.Stream<string, never, ThemeService>;
 
-// Node<never, ThemeService> — R comes from the stream prop
+// Node<never, ThemeService>: R comes from the stream prop
 const box = h.div({ style: { color: colorStream } }, "Hello");
 ```
 
@@ -130,7 +132,7 @@ declare const labelStream: Stream.Stream<string, never, I18nService>;
 const btn = Button({ label: labelStream });
 ```
 
-Components also accept an optional `children` argument, either as `readonly Renderable[]` or as a `(input) => readonly Renderable[]` function (render-prop pattern). `E`/`R` from children — including the array returned by a function-children call — accumulate on the resulting node.
+Components also accept an optional `children` argument, either as `readonly Renderable[]` or as a `(input) => readonly Renderable[]` function (render-prop pattern). `E`/`R` from children, including the array returned by a function-children call, accumulate on the resulting node.
 
 Without `Component`, a plain function's return type is fixed at definition time and does not reflect the caller's reactive prop types.
 
@@ -149,16 +151,16 @@ Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading...") }, [
 ]);
 ```
 
-The fallback is replaced atomically — either all children are visible or none are. This prevents partial flicker when multiple async siblings resolve at different times. The boundary's node type is `Node<ChildrenE, ChildrenR>`: the children's `E`/`R` channels accumulate onto it, exactly as they would for a plain `h.*` parent.
+The fallback is replaced atomically: either all children are visible or none are. This prevents partial flicker when multiple async siblings resolve at different times. The boundary's node type is `Node<ChildrenE, ChildrenR>`: the children's `E`/`R` channels accumulate onto it, exactly as they would for a plain `h.*` parent.
 
 On the server, `renderToStreamHydratable` emits the fallback inline and appends patch scripts as children resolve. On the client, `hydrate` sees through `Boundary.suspend` boundaries and adopts the already-resolved DOM directly.
 
-`Boundary.suspend` is one of the boundary combinators — see the [core reference](https://weftui.dev/docs/reference/core#boundarysuspend) for the full `Boundary.*` surface, including the failure-catch variants and `Boundary.rpc`.
+`Boundary.suspend` is one of the boundary combinators. See the [core reference](https://weftui.dev/docs/reference/core#boundarysuspend) for the full `Boundary.*` surface, including the failure-catch variants and `Boundary.rpc`.
 
 ## See also
 
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why a `Node` is an `Effect` and how the tree renders
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the `Source` vocabulary that reactive props and children accept
-- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) — the boundary combinators as tree nodes
-- [Author Components](https://weftui.dev/docs/how-to/author-components) — `Component.gen` / `Component.make` in practice
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): why a `Node` is an `Effect` and how the tree renders
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the `Source` vocabulary that reactive props and children accept
+- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense): the boundary combinators as tree nodes
+- [Author Components](https://weftui.dev/docs/how-to/author-components): `Component.gen` / `Component.make` in practice
 - [`@weftui/core` reference](https://weftui.dev/docs/reference/core)

package/docs/explanation/reactive-primitives.md

@@ -7,14 +7,14 @@ description: The Source<A, E, R> vocabulary; Stream, Effect, and Subscribable as
 
 # Reactive Primitives
 
-The unified `Source` vocabulary is what lets static values, Effects, Streams, and Subscribables be used interchangeably wherever reactivity is supported — props, children, and style values all accept the same type.
+The unified `Source` vocabulary lets static values, Effects, Streams, and Subscribables be used interchangeably. Props, children, and style values all accept the same type.
 
 Weft accepts a `Source` for prop values and children. Any of these is valid wherever reactivity is supported:
 
 - A plain static value (`string`, `number`, `boolean`, ...)
-- An `Effect.Effect<A, E, R>` — runs once and resolves to a value
-- A `Stream.Stream<A, E, R>` — each emission replaces the previous value
-- A `Subscribable<A, E, R>` — like a hot stream; already has a "current value"
+- An `Effect.Effect<A, E, R>`: runs once and resolves to a value
+- A `Stream.Stream<A, E, R>`: each emission replaces the previous value
+- A `Subscribable<A, E, R>`: like a hot stream; already has a "current value"
 
 The `Source<A, E, R>` type captures this union:
 
@@ -24,7 +24,7 @@ type Source<A, E, R> = A | Effect.Effect<A, E, R> | Stream.Stream<A, E, R> | Sub
 
 ## Static values
 
-Static props behave exactly as you'd expect — set once and never updated:
+Static props are set once and never updated:
 
 ```typescript
 h.div({ class: "container", id: "root" }, "Hello");
@@ -45,17 +45,17 @@ The `E` and `R` channels of the Effect flow into the node's own channels.
 
 ## Stream props and children
 
-Streams are the primary reactive primitive. Each emission replaces the previous value in the DOM — no diffing, direct DOM update:
+Streams are the primary reactive primitive. Each emission replaces the previous value in the DOM (no diffing, direct DOM update):
 
 ```typescript
 import { SubscriptionRef, Stream } from "effect";
 
 const count = yield * SubscriptionRef.make(0);
 
-// SubscriptionRef.changes(count) is a Stream<number> — each new value updates the text node
+// SubscriptionRef.changes(count) is a Stream<number>: each new value updates the text node
 h.span([SubscriptionRef.changes(count)]);
 
-// Stream as a prop — each emission sets the attribute
+// Stream as a prop: each emission sets the attribute
 const isDisabled = Stream.map(SubscriptionRef.changes(count), (n) => n >= 10);
 h.button({ disabled: isDisabled }, "Submit");
 ```
@@ -119,7 +119,7 @@ h.div({ style: styleObjectStream });
 
 // Combine a whole-object stream with a static property.
 // A whole-object stream replaces every property on each emit, so fold the
-// static value into each emitted object with Stream.map — you cannot spread the
+// static value into each emitted object with Stream.map. You cannot spread the
 // Stream itself into a style object (that copies the Stream's internals, not
 // its emitted style keys).
 h.div({
@@ -154,11 +154,11 @@ pipe(
 );
 ```
 
-In practice you only encounter `NoPropValue` if you use a finite `Stream` as a prop and it ends before emitting — e.g., `Stream.empty` or `Stream.take(0, stream)`. Most usage with `SubscriptionRef.changes` or infinite streams never raises it.
+In practice you only encounter `NoPropValue` when a finite `Stream` prop ends before emitting (e.g., `Stream.empty` or `Stream.take(0, stream)`). Most usage with `SubscriptionRef.changes` or infinite streams never raises it.
 
 ## See also
 
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — streams as the weft woven through a static tree
-- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how reactive props and children contribute `E`/`R`
-- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively) and [Render Keyed Lists](https://weftui.dev/docs/how-to/render-keyed-lists) — reactive props and collections in practice
-- [`Source` reference](https://weftui.dev/docs/reference/core#source-namespace) — the `Source` type and `Source.toSubscribable`
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): streams as the weft woven through a static tree
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): how reactive props and children contribute `E`/`R`
+- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively) and [Render Keyed Lists](https://weftui.dev/docs/how-to/render-keyed-lists): reactive props and collections in practice
+- [`Source` reference](https://weftui.dev/docs/reference/core#source-namespace): the `Source` type and `Source.toSubscribable`