@weftui/dom 0.26.0 → 0.26.2

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

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

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

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

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

@@ -0,0 +1,70 @@
+---
+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.catchAll — 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**.
+
+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.catchAll`, which maps the error to a fallback node.
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, Stream } from "effect";
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const fetchUser = (id: number): Effect.Effect<User, Error> =>
+  Effect.gen(function* () {
+    yield* Effect.sleep("1000 millis");
+    if (id === 3) return yield* Effect.fail(new Error("User not found"));
+    return { id, name: `User ${id}`, email: `user${id}@example.com` };
+  });
+
+const UserCard = ({ id }: { id: number }) =>
+  Stream.concat(
+    Stream.make(h.div({ class: "loading" }, `Loading user ${id}…`)),
+    Stream.fromEffect(
+      fetchUser(id).pipe(
+        Effect.flatMap((user) => h.div({ class: "user-card" }, [h.h3(user.name), h.p(user.email)])),
+        Effect.catchAll((error) => h.div({ class: "error" }, `Error: ${error.message}`)),
+      ),
+    ),
+  );
+```
+
+## 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.catchAll((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.
+
+## 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.
+
+## 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:
+
+- **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.
+
+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

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

@@ -0,0 +1,172 @@
+---
+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.
+---
+
+# RPC Data Boundaries
+
+`Boundary.rpc` is Weft's primitive for **server-resolved, client-refreshable** data. One [`Rpc`](https://github.com/Effect-TS/effect/tree/main/packages/rpc) from the app's merged `RpcGroup` backs a single render boundary across four lifecycles: server-side render, hydrate-replay, client refetch, and client-first SPA mount. The rpc's `_tag` is the boundary's stable identity and its payload schema the typed input.
+
+## 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.
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+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
+  (
+    resource, // render — receives a reactive Resource, not a bare value
+  ) =>
+    h.p([
+      "in stock: ",
+      h.span([Stream.map(resource.value.changes, (s) => String(s.units))]),
+      h.button({ type: "button", onclick: () => resource.refetch }, "Refresh"),
+    ]),
+  { fallback: h.p("loading stock…") }, // shown only on a client-first mount
+);
+```
+
+## 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.
+
+```typescript
+// data/inventory.ts
+import { Rpc, RpcGroup } from "@effect/rpc";
+import { Context, Effect, Layer, Schema } from "effect";
+
+// --- Contract (shareable with the client) ---
+export const Stock = Schema.Struct({ units: Schema.Number });
+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.
+export const StockRpcs = RpcGroup.make(GetStock);
+
+// --- Handler (server-only; the client never imports this) ---
+class Inventory extends Context.Tag("Inventory")<
+  Inventory,
+  { readonly stockFor: (id: number) => Effect.Effect<typeof Stock.Type> }
+>() {}
+
+const InventoryLive = Layer.succeed(Inventory, {
+  stockFor: (id) => Effect.succeed({ units: 7 + (id % 5) }),
+});
+
+// `toLayer` binds each rpc to its handler; `Layer.provide` discharges its deps so R = never.
+export const StockLive = StockRpcs.toLayer({
+  GetStock: (payload) => Effect.flatMap(Inventory, (inv) => inv.stockFor(payload.id)),
+}).pipe(Layer.provide(InventoryLive));
+```
+
+Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Tag`) 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
+import { RouterServer } from "@weftui/router/server";
+import { StockLive, StockRpcs } from "./data/inventory";
+
+const rpc = { group: StockRpcs, handlers: StockLive } as const;
+
+export const handler = RouterServer.toWebHandler(App, { document: documentShell, rpc });
+export const render = (url: string) =>
+  Effect.runPromise(RouterServer.render(App, { document: documentShell, rpc, url }));
+```
+
+```typescript
+// entry-client.ts — network client posting to /_eui/rpc
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { StockRpcs } from "./data/inventory";
+
+const runtime = ManagedRuntime.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void runtime.runPromise(hydrate(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.
+- **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).
+
+## The four lifecycles
+
+| Lifecycle              | Trigger                                 | What happens                                                                                                                                         |
+| ---------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **SSR**                | server render                           | Resolve the rpc in-process, `successSchema`-encode the result inline as `<script type="application/json">`, render `render(seededResource)` to HTML. |
+| **Hydrate**            | `hydrate` on the client                 | Read the inline payload at the cursor, `successSchema`-decode it, seed the `Resource`, adopt the DOM. **Never re-calls the rpc** (replay).           |
+| **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.
+
+## 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).             |
+
+```typescript
+(resource) =>
+  h.section({ class: "product" }, [
+    h.span([Stream.map(resource.value.changes, (s) => String(s.units))]),
+    h.span([Stream.map(resource.pending.changes, (p) => (p ? "refreshing…" : ""))]),
+    h.button({ type: "button", onclick: () => resource.refetch }, "Refresh stock"),
+  ]);
+```
+
+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
+
+```typescript
+Boundary.rpc<R extends Rpc.Any, C extends Node<any, any>>(
+  rpc: R,
+  payload: () => Rpc.Payload<R>,
+  render: (resource: Resource<Rpc.Success<R>>) => C,
+  options?: { fallback?: Renderable },
+): Node<Node.Error<C> | Rpc.Error<R>, Node.Context<C>>;
+```
+
+- **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.
+
+## 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).
+
+```typescript
+Boundary.catchTag({ tag: "OutOfStock", fallback: (e) => h.p({ class: "error" }, e.reason) }, [
+  Boundary.rpc(GetStock, () => ({ id: product.id }), (resource) => /* … */),
+]);
+```
+
+A transport **defect** (no `Cause.failureOption`), 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).
+
+## 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`