@weftui/core 0.28.0 → 0.29.0

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

@@ -32,7 +32,7 @@ Use a plain function when:
 
 ## Components with internal state
 
-When a component needs reactive state, use `Effect.gen` to set it up before building the tree. The component function still runs once — the setup happens at mount time:
+When a component needs reactive state, use `Effect.gen` to set it up before building the tree. The component function still runs once. The setup happens at mount time:
 
 ```typescript
 import { h } from "@weftui/core";
@@ -49,25 +49,28 @@ const Counter = () =>
   });
 ```
 
-The return type here is `Effect.Effect<Node, never, never>` — itself a valid `Node`, so it composes naturally with other tree-building calls. As soon as such a component is reused or takes props, prefer wrapping the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below) so the caller's reactive prop and children channels flow into its node type.
+The return type here is `Effect.Effect<Node, never, never>`, itself a valid `Node`, so it composes naturally with other tree-building calls.
+
+As soon as such a component is reused or takes props, wrap the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below). That way the caller's reactive prop and children channels flow into its node type.
 
 ## Component scope and background effects
 
-Every component instance is rendered under its own **instance scope** — a child of the
+Every component instance is rendered under its own **instance scope**, a child of the
 mount scope created fresh for that instance. Anything bound to the instance scope lives
-exactly as long as the component is mounted and is torn down automatically when the
-component unmounts (or when its root unmounts via `RootHandle.unmount()`). The renderer
-provides this scope as the ambient `Scope.Scope` while it evaluates the component body,
-so it is already in context when you need it.
+exactly as long as the component is mounted. It is torn down automatically when the
+component unmounts (or when its root unmounts via `RootHandle.unmount()`).
+
+The renderer provides this scope as the ambient `Scope.Scope` while it evaluates the
+component body, so it is already in context when you need it.
 
-This matters the moment a component starts **background work** — a subscription, an
+This matters the moment a component starts **background work**: a subscription, an
 observer of a `ref`, a polling timer, anything you `fork`. The rule:
 
 > Fork background work with **`Effect.forkScoped`**, never a bare `Effect.forkChild`.
 
 `Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for
 the component's lifetime and is interrupted on unmount. A bare `Effect.forkChild` instead
-attaches the fiber to the component-body fiber — the one that runs your `Effect.gen` to
+attaches the fiber to the component-body fiber, the one that runs your `Effect.gen` to
 produce the tree. That fiber completes the instant the gen returns its node, so the
 forked work is cancelled almost immediately.
 
@@ -86,8 +89,8 @@ const AutoFocusInput = () =>
       Stream.filter(Option.isSome),
       Stream.take(1),
       Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
-      Effect.forkScoped, // ✅ tied to the instance scope — survives until unmount
-      // Effect.forkChild, // ❌ tied to the body fiber — interrupted when the gen returns
+      Effect.forkScoped, // ✅ tied to the instance scope: survives until unmount
+      // Effect.forkChild, // ❌ tied to the body fiber: interrupted when the gen returns
     );
 
     return yield* h.input({ ref: inputRef, type: "text" });
@@ -96,7 +99,7 @@ const AutoFocusInput = () =>
 
 You do not manage the scope yourself: you do not create it, close it, or pass it
 around. `forkScoped` reads it from context, and unmount closes it for you. If you ever
-fork outside a component body (rare), you must supply a `Scope.Scope` yourself — the
+fork outside a component body (rare), you must supply a `Scope.Scope` yourself. The
 type system will tell you, because `forkScoped` carries a `Scope.Scope` requirement.
 
 See `examples/element-ref` for the auto-focus, measure, and canvas recipes built on
@@ -106,8 +109,8 @@ this pattern.
 
 When you want the caller's reactive prop types to flow into the returned node's type, use one of the `Component` factories. Both have the same call semantics; pick the body style that fits:
 
-- **`Component.make`** — body is a plain function returning any `Effect` (typically a `Node`). Use for one-liners and pipe compositions.
-- **`Component.gen`** — body is a generator. Use when you need `yield*` to set up local state or pull from services.
+- **`Component.make`**: body is a plain function returning any `Effect` (typically a `Node`). Use for one-liners and pipe compositions.
+- **`Component.gen`**: body is a generator. Use when you need `yield*` to set up local state or pull from services.
 
 ```typescript
 import { Component, h, Source } from "@weftui/core";
@@ -125,14 +128,16 @@ const Card = Component.make((props: CardProps) =>
 );
 ```
 
-`Source.Source<string>` is Weft's caller-facing prop vocabulary — a single type covering a static `string`, a `Stream<string>`, an `Effect<string>`, or a `Subscribable<string>` — so you don't hand-write `string | Stream.Stream<string> | …` on every prop. Passing a `Source` straight to `h` (as above) is all you need when the value is just spliced into the tree; the renderer normalizes it.
+`Source.Source<string>` is Weft's caller-facing prop vocabulary: a single type covering a static `string`, a `Stream<string>`, an `Effect<string>`, or a `Subscribable<string>`. You don't hand-write `string | Stream.Stream<string> | …` on every prop.
+
+Passing a `Source` straight to `h` (as above) is all you need when the value is just spliced into the tree. The renderer normalizes it.
 
 Now the caller's stream types are visible in the returned node:
 
 ```typescript
 declare const titleStream: Stream.Stream<string, never, I18nService>;
 
-// Node<never, I18nService> — I18nService requirement flows out
+// Node<never, I18nService>: I18nService requirement flows out
 const card = Card({ title: titleStream });
 ```
 
@@ -140,7 +145,7 @@ Without a `Component` factory, a plain function's return type is fixed at defini
 
 ### Body `E`/`R` inference
 
-You don't declare the body's `E`/`R` channels explicitly — they're inferred from the returned (or yielded) effect:
+You don't declare the body's `E`/`R` channels explicitly. They're inferred from the returned (or yielded) effect:
 
 - The body's `E`/`R` come from whatever effects appear inside.
 - The caller's reactive prop channels and reactive children channels are unioned on top at the call site.
@@ -156,7 +161,7 @@ type Component.Children<Input = never> =
   | ((input: Input) => readonly Renderable[]);
 ```
 
-The function form is the render-prop / slot pattern — the component invokes the function with whatever input it chooses, and the returned array's `E`/`R` propagate out:
+The function form is the render-prop / slot pattern. The component invokes the function with whatever input it chooses, and the returned array's `E`/`R` propagate out:
 
 ```typescript
 const ItemList = Component.make(
@@ -169,7 +174,7 @@ ItemList({ items: ["a", "b"] }, (item) => [h.li(item)]);
 
 ## Props typing
 
-For a prop that accepts both static and reactive values, type it as [`Source.Source<T>`](https://weftui.dev/docs/reference/core#source-namespace) rather than hand-writing the union. `Source.Source<T>` **is** that union — `T | Stream<T> | Effect<T> | Subscribable<T>` — so the caller can pass a plain value or any reactive shape interchangeably, and you write it once:
+For a prop that accepts both static and reactive values, type it as [`Source.Source<T>`](https://weftui.dev/docs/reference/core#source-namespace) rather than hand-writing the union. `Source.Source<T>` **is** that union: `T | Stream<T> | Effect<T> | Subscribable<T>`. The caller can pass a plain value or any reactive shape interchangeably, and you write it once:
 
 ```typescript
 import { Source } from "@weftui/core";
@@ -181,11 +186,11 @@ interface ButtonProps {
 }
 ```
 
-When a caller passes a plain string, the component's node type has `never` for that prop's channels. When they pass a `Stream.Stream<string, never, SomeService>`, `SomeService` appears in the `R` channel — the extraction is exactly `Source.Success` / `Source.Error` / `Source.Context`.
+When a caller passes a plain string, the component's node type has `never` for that prop's channels. When they pass a `Stream.Stream<string, never, SomeService>`, `SomeService` appears in the `R` channel. The extraction is exactly `Source.Success` / `Source.Error` / `Source.Context`.
 
 ### Reading a `Source` in the body
 
-Splicing a `Source` straight into `h` (`[props.label]`) is enough when you only place it in the tree. When the body needs to **read or derive** from the value — combine two props, feed a stream operator, drive logic — normalize it first with [`Source.toSubscribable`](https://weftui.dev/docs/reference/core#sourcetosubscribablesource-key), which turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
+Splicing a `Source` straight into `h` (`[props.label]`) is enough when you only place it in the tree. When the body needs to **read or derive** from the value (combine two props, feed a stream operator, drive logic), normalize it first with [`Source.toSubscribable`](https://weftui.dev/docs/reference/core#sourcetosubscribablesource-key). It turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
 
 ```typescript
 import { Component, h, Source } from "@weftui/core";
@@ -193,12 +198,19 @@ import { Stream } from "effect";
 
 const LoudLabel = Component.gen(function* (props: { label: Source.Source<string> }) {
   const label = yield* Source.toSubscribable(props.label); // Subscribable<string>
-  // Now derive from it like any Subscribable — static, Effect, and Stream inputs all work.
+  // Now derive from it like any Subscribable: static, Effect, and Stream inputs all work.
   return yield* h.strong([Stream.map(label.changes, (text) => text.toUpperCase())]);
 });
 ```
 
-`toSubscribable` is scoped: a `Stream` prop is pumped by a fiber that terminates with the component's instance scope, an `Effect` prop is memoized, an existing `Subscribable` is threaded through by reference, and a static value emits once. It is the same normalization the renderer applies to props internally — reach for it whenever you need the value as a `Subscribable` instead of leaving it opaque.
+`toSubscribable` is scoped:
+
+- A `Stream` prop is pumped by a fiber that terminates with the component's instance scope.
+- An `Effect` prop is memoized.
+- An existing `Subscribable` is threaded through by reference.
+- A static value emits once.
+
+It is the same normalization the renderer applies to props internally. Reach for it whenever you need the value as a `Subscribable` instead of leaving it opaque.
 
 ## Composing components
 
@@ -231,7 +243,7 @@ const UserAvatar = Component.gen(function* (props: { userId: string }) {
   return yield* h.img({ src: user.avatarUrl, alt: user.name });
 });
 
-// Node<never, UserService> — regardless of what the caller passes
+// Node<never, UserService>: regardless of what the caller passes
 const avatar = UserAvatar({ userId: "123" });
 ```
 
@@ -260,7 +272,7 @@ const TableCells = ({ row }: { row: Row }) =>
 
 ## See also
 
-- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — `h`, `h.fragment`, and how `E`/`R` accumulate
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the `Source` vocabulary props accept
-- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — route components are `Component` slots
-- [`@weftui/core` reference](https://weftui.dev/docs/reference/core) — `Component`, `Source`, and the full surface
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): `h`, `h.fragment`, and how `E`/`R` accumulate
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the `Source` vocabulary props accept
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing): route components are `Component` slots
+- [`@weftui/core` reference](https://weftui.dev/docs/reference/core): `Component`, `Source`, and the full surface

package/docs/how-to/compose-behavior-and-markup.md

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

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

@@ -25,7 +25,7 @@ const LoginForm = () =>
     const email = yield* SubscriptionRef.make("");
     const status = yield* SubscriptionRef.make<string | null>(null);
 
-    // Validation is a stream derived from the field — it re-runs as the user types.
+    // Validation is a stream derived from the field: it re-runs as the user types.
     const error = Stream.map(SubscriptionRef.changes(email), (value) => {
       if (value.length === 0) return null; // don't nag an empty field
       return Result.match(Schema.decodeUnknownResult(Email)(value), {
@@ -61,8 +61,8 @@ const LoginForm = () =>
 ## How it works
 
 - **Field state** is a `SubscriptionRef.make("")`; `oninput` writes the current value with `SubscriptionRef.set`. Because the input is driven by the ref, it is a controlled input.
-- **Validation is reactive**, not on-blur or on-submit only: `Stream.map(SubscriptionRef.changes(email), …)` produces an error string (or `null`) on every keystroke. Use [`Schema`](https://effect.website/docs/schema/introduction) to decode — `Schema.decodeUnknownResult(schema)(value)` returns a `Result`, and `Result.match` turns it into UI. A node or `null` in a child slot renders the error or nothing.
-- **Submit returns an Effect.** `onsubmit` calls `e.preventDefault()` and then **returns** an `Effect` (it is not `yield*`-ed inline) — the renderer runs it in a detached fiber, so it can `SubscriptionRef.set`, `Effect.sleep`, read fields with `SubscriptionRef.get`, or call a service.
+- **Validation is reactive**, not on-blur or on-submit only: `Stream.map(SubscriptionRef.changes(email), …)` produces an error string (or `null`) on every keystroke. Use [`Schema`](https://effect.website/docs/schema/introduction) to decode: `Schema.decodeUnknownResult(schema)(value)` returns a `Result`, and `Result.match` turns it into UI. A node or `null` in a child slot renders the error or nothing.
+- **Submit returns an Effect.** `onsubmit` calls `e.preventDefault()` and then **returns** an `Effect` (it is not `yield*`-ed inline). The renderer runs it in a detached fiber, so it can `SubscriptionRef.set`, `Effect.sleep`, read fields with `SubscriptionRef.get`, or call a service.
 
 ## Variations
 
@@ -71,6 +71,6 @@ const LoginForm = () =>
 
 ## See also
 
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `SubscriptionRef.changes` and stream-shaped children
-- [Author Components](https://weftui.dev/docs/how-to/author-components) — Effect-returning and service-aware handlers
-- [examples/form-handling](https://github.com/stefvw93/weft/tree/main/examples/form-handling) — a runnable multi-field form with Schema validation and an async submit
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): `SubscriptionRef.changes` and stream-shaped children
+- [Author Components](https://weftui.dev/docs/how-to/author-components): Effect-returning and service-aware handlers
+- [examples/form-handling](https://github.com/stefvw93/weft/tree/main/examples/form-handling): a runnable multi-field form with Schema validation and an async submit

package/docs/how-to/load-async-data.md

@@ -2,12 +2,12 @@
 title: Load Async Data
 order: 9
 section: how-to
-description: Show a loading state then resolved content with Stream.concat, and turn a failed fetch into a fallback node with Effect.catch — all client-side.
+description: Show a loading state then resolved content with Stream.concat, and turn a failed fetch into a fallback node with Effect.catch, all client-side.
 ---
 
 # Load Async Data
 
-**Goal:** render a loading placeholder, then the fetched content, and a fallback if the fetch fails — for data that loads **on the client**.
+**Goal:** render a loading placeholder, then the fetched content, and a fallback if the fetch fails, for data that loads **on the client**.
 
 Return a `Stream<Node>` that emits the loading node first and the resolved node second, sequenced with `Stream.concat`. Handle failure inside the effect with `Effect.catch`, which maps the error to a fallback node.
 
@@ -43,28 +43,30 @@ const UserCard = ({ id }: { id: number }) =>
 ## How it works
 
 - **`Stream.concat`** sequences two streams: `Stream.make(loadingNode)` emits once immediately, then `Stream.fromEffect(effect)` emits the resolved node when the effect completes. The renderer swaps the DOM in place on the second emission.
-- **`Effect.flatMap((data) => h.div(...))`** builds the content node from the data — `h.*` returns a `Node`, which is an `Effect`, so it composes directly in the pipeline.
+- **`Effect.flatMap((data) => h.div(...))`** builds the content node from the data. `h.*` returns a `Node`, which is an `Effect`, so it composes directly in the pipeline.
 - **`Effect.catch((error) => node)`** converts the error channel into a fallback node, so the stream always yields something renderable. The failure never escapes to the mount.
-- **Parallel loading is automatic:** place several async components as siblings and their fetches run concurrently — no orchestration needed.
+- **Parallel loading is automatic:** place several async components as siblings and their fetches run concurrently, with no orchestration needed.
 
 ## When to reach for a boundary instead
 
-This is the raw, per-region pattern. When you need **one fallback for several async siblings** (all-or-nothing), use [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense). When the data must be resolved on the **server** and replayed on hydrate without a second request, use [`Boundary.rpc`](https://weftui.dev/docs/how-to/load-data-with-rpc) instead — this recipe is purely client-side.
+This is the raw, per-region pattern. When you need **one fallback for several async siblings** (all-or-nothing), use [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense). When the data must be resolved on the **server** and replayed on hydrate without a second request, use [`Boundary.rpc`](https://weftui.dev/docs/how-to/load-data-with-rpc) instead. This recipe is purely client-side.
 
 ## Blocking on navigation vs streaming in place
 
-The `Stream.concat` placeholder above lives on a **child** node, so it always streams in after mount — it never delays a navigation commit. If the component above is a route's leaf, moving the `fetchUser` call into the **body** instead changes that:
+The `Stream.concat` placeholder above lives on a **child** node, so it always streams in after mount and never delays a navigation commit. If the component above is a route's leaf, moving the `fetchUser` call into the **body** instead changes that:
 
-- **Await in the leaf's own body** — commit-blocking. Navigating to the route pre-runs its component effect to completion before the URL commits: the previous page stays mounted for the fetch, and [`Router.navigating`](https://weftui.dev/docs/reference/router#routernavigating) reports the window.
-- **The `Stream.concat` placeholder pattern above, kept as a child** — streaming. The leaf commits immediately and the region fills in place once the effect resolves.
+- **Await in the leaf's own body** is commit-blocking. Navigating to the route pre-runs its component effect to completion before the URL commits: the previous page stays mounted for the fetch, and [`Router.navigating`](https://weftui.dev/docs/reference/router#routernavigating) reports the window.
+- **The `Stream.concat` placeholder pattern above, kept as a child** is streaming. The leaf commits immediately and the region fills in place once the effect resolves.
 
-Choose blocking for **primary route content the page is meaningless without** (an article body, a user's profile) — 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 route content the page is meaningless without** (an article body, a user's profile). 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.
 
 See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for rendering pending UI during the blocking window, and the router reference's [Blocking vs streaming data](https://weftui.dev/docs/reference/router#blocking-vs-streaming-data) for the full model.
 
 ## See also
 
-- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) — coordinating multiple async regions
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `Stream`/`Effect` as node-producing children
-- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) — the pending signal for the commit-blocking window
-- [examples/async-data-loading](https://github.com/stefvw93/weft/tree/main/examples/async-data-loading) — loading states, retry, parallel and sequential loads with error boundaries
+- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense): coordinating multiple async regions
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): `Stream`/`Effect` as node-producing children
+- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress): the pending signal for the commit-blocking window
+- [examples/async-data-loading](https://github.com/stefvw93/weft/tree/main/examples/async-data-loading): loading states, retry, parallel and sequential loads with error boundaries

package/docs/how-to/load-data-with-rpc.md

@@ -2,7 +2,7 @@
 title: RPC Data Boundaries
 order: 3
 section: how-to
-description: Boundary.rpc — server-resolved, client-refreshable data; the contract/handler split and the Resource handle's four lifecycles.
+description: Boundary.rpc, server-resolved and client-refreshable data; the contract/handler split and the Resource handle's four lifecycles.
 ---
 
 # RPC Data Boundaries
@@ -11,7 +11,7 @@ description: Boundary.rpc — server-resolved, client-refreshable data; the cont
 
 ## Overview
 
-A `Boundary.rpc` is a **thin consumer**. It carries an rpc, a payload thunk, and a `render` that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea); the renderer resolves the rpc through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam (provided by `@weftui/router`). The same rpc serves every lifecycle, so SSR-replay, refetch, and client-first mount are one mechanism, not three.
+A `Boundary.rpc` is a **thin consumer**. It carries an rpc, a payload thunk, and a `render` that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea). The renderer resolves the rpc through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam (provided by `@weftui/router`). The same rpc serves every lifecycle, so SSR-replay, refetch, and client-first mount are one mechanism, not three.
 
 ```typescript
 import { Boundary, h } from "@weftui/core";
@@ -19,10 +19,10 @@ import { Stream } from "effect";
 import { GetStock } from "./data/inventory";
 
 Boundary.rpc(
-  GetStock, // the rpc — its _tag + schemas drive the boundary
-  () => ({ id: product.id }), // payload thunk — a fresh typed input per call
+  GetStock, // the rpc: its _tag + schemas drive the boundary
+  () => ({ id: product.id }), // payload thunk: a fresh typed input per call
   (
-    resource, // render — receives a reactive Resource, not a bare value
+    resource, // render: receives a reactive Resource, not a bare value
   ) =>
     h.p([
       "in stock: ",
@@ -35,7 +35,7 @@ Boundary.rpc(
 
 ## The contract / handler split
 
-The rpc **contract** (pure Schema) is shared with the client. The rpc **handler** — the only code that touches server-only services — lives in a Layer the client never imports; tree-shaking keeps it and its transitive imports out of the browser bundle. The split is enforced structurally by which files each entry imports, not by a bundler plugin.
+The rpc **contract** (pure Schema) is shared with the client. The rpc **handler**, the only code that touches server-only services, lives in a Layer the client never imports. Tree-shaking keeps it and its transitive imports out of the browser bundle. The split is enforced structurally by which files each entry imports, not by a bundler plugin.
 
 ```typescript
 // data/inventory.ts
@@ -49,7 +49,7 @@ export const StockKey = Schema.Struct({ id: Schema.Number });
 // `_tag` ("GetStock") = the stable boundary id; payload schema = the typed input.
 export const GetStock = Rpc.make("GetStock", { payload: StockKey, success: Stock });
 
-// The app's merged RpcGroup — shared by both the client and server router wiring.
+// The app's merged RpcGroup: shared by both the client and server router wiring.
 export const StockRpcs = RpcGroup.make(GetStock);
 
 // --- Handler (server-only; the client never imports this) ---
@@ -68,14 +68,14 @@ export const StockLive = StockRpcs.toLayer({
 }).pipe(Layer.provide(InventoryLive));
 ```
 
-Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Service`) when they might be referenced from universal code: the brand makes a leak into `render` a compile error at the `hydrate` call site rather than a runtime surprise.
+Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Service`) when they might be referenced from universal code. The brand makes a leak into `render` a compile error at the `hydrate` call site rather than a runtime surprise.
 
 ## Wiring the router
 
 `Boundary.rpc` resolves through the ambient `AppRpcClientTag` seam, which `@weftui/router` provides on both sides. Pass the **merged group** to both, plus the **handler Layer** on the server.
 
 ```typescript
-// entry-server.ts — in-process client over the handlers + POST /_eui/rpc endpoint
+// entry-server.ts: in-process client over the handlers + POST /_eui/rpc endpoint
 import { RouterServer } from "@weftui/router/server";
 import { StockLive, StockRpcs } from "./data/inventory";
 
@@ -87,7 +87,7 @@ export const render = (url: string) =>
 ```
 
 ```typescript
-// entry-client.ts — network client posting to /_eui/rpc
+// entry-client.ts: network client posting to /_eui/rpc
 import { WeftApp } from "@weftui/dom/client";
 import { RouterApp, RouterLive } from "@weftui/router/client";
 import { Effect } from "effect";
@@ -97,7 +97,7 @@ const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
 void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 ```
 
-- **Server** ([`RouterServer`](https://weftui.dev/docs/reference/router#routerserver)) mounts the handler Layer at `POST /_eui/rpc` (so a client refetch re-runs it on the server) **and** exposes an in-process client over the same handlers for SSR resolution — never a network hop.
+- **Server** ([`RouterServer`](https://weftui.dev/docs/reference/router#routerserver)) mounts the handler Layer at `POST /_eui/rpc`, so a client refetch re-runs it on the server. It also exposes an in-process client over the same handlers for SSR resolution, never a network hop.
 - **Client** ([`RouterLive`](https://weftui.dev/docs/reference/router#routerlive)) provides a network flat rpc client over the merged group, posting to `<origin>/_eui/rpc`.
 
 In a **router-less mount** there is no `AppRpcClientTag`, so a `Boundary.rpc` resolves to a typed, descriptive "needs router/rpc" error (not a defect).
@@ -111,18 +111,18 @@ In a **router-less mount** there is no `AppRpcClientTag`, so a `Boundary.rpc` re
 | **Refetch**            | `resource.refetch`                      | Call the rpc again over `POST /_eui/rpc` (re-runs the handler on the server), patch the subtree in place (stale-on-error).                           |
 | **Client-first mount** | SPA nav into a boundary with no payload | Render `options.fallback`, fork the rpc call, swap in `render(resource)` once it resolves.                                                           |
 
-Because the SSR path seeds `value` await-first (it emits the seed immediately), the SSR HTML and the adopted DOM are byte-identical — there is **no fallback flash** on the SSR/hydrate path. `fallback` shows only on a client-first mount.
+Because the SSR path seeds `value` await-first (it emits the seed immediately), the SSR HTML and the adopted DOM are byte-identical. There is **no fallback flash** on the SSR/hydrate path. `fallback` shows only on a client-first mount.
 
 ## The `Resource` handle
 
 `render` receives a [`Resource<A>`](https://weftui.dev/docs/reference/core#resourcea) (`A` = the rpc's decoded success), not a bare value. After hydrate the region is live:
 
-| Field     | What it gives you                                                                                    |
-| --------- | ---------------------------------------------------------------------------------------------------- |
-| `value`   | A `Subscribable` of the current data — seeded with the SSR payload, updated on a successful refetch. |
-| `refetch` | An `Effect<void>` that re-resolves the rpc with a fresh `payload()` and pushes the new `value`.      |
-| `pending` | A `Subscribable<boolean>` — `true` while a refetch is in flight.                                     |
-| `error`   | A `Subscribable<Option<unknown>>` — `Some` with the last refetch error (stale-on-error).             |
+| Field     | What it gives you                                                                                   |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| `value`   | A `Subscribable` of the current data: seeded with the SSR payload, updated on a successful refetch. |
+| `refetch` | An `Effect<void>` that re-resolves the rpc with a fresh `payload()` and pushes the new `value`.     |
+| `pending` | A `Subscribable<boolean>`: `true` while a refetch is in flight.                                     |
+| `error`   | A `Subscribable<Option<unknown>>`: `Some` with the last refetch error (stale-on-error).             |
 
 ```typescript
 (resource) =>
@@ -133,7 +133,7 @@ Because the SSR path seeds `value` await-first (it emits the seed immediately),
   ]);
 ```
 
-Wire `refetch` to an event with `onclick: () => resource.refetch` — the handler returns the Effect, which the renderer runs in a detached fiber. A failed refetch leaves the previous `value` intact (stale-on-error); it does **not** unmount the subtree or raise into a failure `Boundary`.
+Wire `refetch` to an event with `onclick: () => resource.refetch`. The handler returns the Effect, which the renderer runs in a detached fiber. A failed refetch leaves the previous `value` intact (stale-on-error); it does **not** unmount the subtree or raise into a failure `Boundary`.
 
 ### Channel algebra
 
@@ -147,11 +147,13 @@ Boundary.rpc<R extends Rpc.Any, C extends Node<any, any>>(
 ```
 
 - **Error** = `render`'s error union plus the rpc's typed `Rpc.Error<R>` (`never` for an rpc with no `error` schema).
-- **Requirement** = exactly `render`'s `R`, **untouched**. There is no `provide`/`RServer` to discharge (the handler lives in the rpc Layer) and no `Exclude` is applied — a server-only tag leaked into `render` stays in `R`, where `hydrate`'s `AssertNoServerOnly` rejects it.
+- **Requirement** = exactly `render`'s `R`, **untouched**. There is no `provide`/`RServer` to discharge (the handler lives in the rpc Layer) and no `Exclude` is applied. A server-only tag leaked into `render` stays in `R`, where `hydrate`'s `AssertNoServerOnly` rejects it.
 
 ## Typed-failure replay
 
-If the rpc declares an `error` schema, a resolved rpc **error** on the SSR pass is `errorSchema`-encoded into an inline failure payload, and the nearest enclosing **failure `Boundary`** renders its fallback. On the client, `hydrate` decodes that payload and re-raises the same error into the same boundary, reproducing the identical fallback DOM — flash-free and without re-resolving the rpc (replay, never retry).
+If the rpc declares an `error` schema, a resolved rpc **error** on the SSR pass is `errorSchema`-encoded into an inline failure payload. The nearest enclosing **failure `Boundary`** renders its fallback.
+
+On the client, `hydrate` decodes that payload and re-raises the same error into the same boundary. The identical fallback DOM is reproduced, flash-free and without re-resolving the rpc (replay, never retry).
 
 ```typescript
 Boundary.catchTag({ tag: "OutOfStock", fallback: (e) => h.p({ class: "error" }, e.reason) }, [
@@ -159,16 +161,16 @@ Boundary.catchTag({ tag: "OutOfStock", fallback: (e) => h.p({ class: "error" },
 ]);
 ```
 
-A transport **defect** (no `Cause.findErrorOption`), or an rpc with no `error` schema, is **not** replayed; it propagates — a server-side fallback and a client mismatch.
+A transport **defect** (no `Cause.findErrorOption`), or an rpc with no `error` schema, is **not** replayed; it propagates: a server-side fallback and a client mismatch.
 
 ## When to use
 
-- **`Boundary.rpc`** — data resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML, then **refreshable** on the client over the same rpc.
-- **`Boundary.suspend`** — async data that loads purely on the client; see the [Boundary API](https://weftui.dev/docs/reference/core#boundarysuspend).
+- **`Boundary.rpc`**: data resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML. It stays **refreshable** on the client over the same rpc.
+- **`Boundary.suspend`**: async data that loads purely on the client; see the [Boundary API](https://weftui.dev/docs/reference/core#boundarysuspend).
 
 ## See also
 
-- [`Boundary.rpc` API reference](https://weftui.dev/docs/reference/core#boundaryrpc) — signature, `Resource`, `RpcOptions`, `AppRpcClientTag`
-- [Server-Side Rendering](https://weftui.dev/docs/how-to/render-on-the-server) — the SSR + hydration model this builds on
-- [Routing](https://weftui.dev/docs/how-to/add-routing) — `@weftui/router`, which provides the `AppRpcClientTag` seam
-- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable shop with an SSR-replayed, refetchable live-stock `Boundary.rpc`
+- [`Boundary.rpc` API reference](https://weftui.dev/docs/reference/core#boundaryrpc): signature, `Resource`, `RpcOptions`, `AppRpcClientTag`
+- [Server-Side Rendering](https://weftui.dev/docs/how-to/render-on-the-server): the SSR + hydration model this builds on
+- [Routing](https://weftui.dev/docs/how-to/add-routing): `@weftui/router`, which provides the `AppRpcClientTag` seam
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr): a runnable shop with an SSR-replayed, refetchable live-stock `Boundary.rpc`