@weftui/core 0.30.0 → 0.31.1

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

@@ -7,11 +7,135 @@ description: Build a controlled form with SubscriptionRef field state, reactive
 
 # 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.
+**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 `SubscriptionRef.changes(ref)` stream, and return an `Effect` from `onsubmit` (after `preventDefault`).
+```typescript
+import { h } from "@weftui/core";
+import { Effect, SubscriptionRef } from "effect";
+
+const Field = () =>
+  Effect.gen(function* () {
+    const value = yield* SubscriptionRef.make("");
+
+    return yield* h.div([
+      h.input({
+        type: "text",
+        oninput: (e) => SubscriptionRef.set(value, e.currentTarget.value),
+      }),
+      h.div(["You typed: ", SubscriptionRef.changes(value)]),
+    ]);
+  });
+```
+
+Each field is a `SubscriptionRef`: `oninput` writes it, `SubscriptionRef.changes` streams it back into the tree. `e.currentTarget` is typed to the element itself (`HTMLInputElement` here), so no cast is needed.
+
+## Reactive validation
+
+Derive an error stream from the field's `changes`. Decode with [`Schema`](https://effect.website/docs/schema/introduction) and turn the `Result` into UI with `Result.match`:
+
+```typescript
+import { Result, Schema, Stream, SubscriptionRef } from "effect";
+
+const Email = Schema.String.pipe(
+  Schema.check(Schema.makeFilter((s) => (s.includes("@") ? undefined : "Must contain @"))),
+  Schema.check(Schema.makeFilter((s) => (s.includes(".") ? undefined : "Must contain a domain"))),
+);
+
+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), {
+    onFailure: (e) => e.message.split(":").pop()?.trim() ?? "Invalid",
+    onSuccess: () => null,
+  });
+});
+
+h.span([Stream.map(error, (err) => (err ? h.span({ class: "error-text" }, err) : null))]);
+```
+
+This re-runs on every keystroke, not just on blur or submit. A node or `null` in a child slot renders the error or nothing.
+
+## Submit as an Effect
+
+`onsubmit` calls `e.preventDefault()`, then **returns** an `Effect` (it is not `yield*`-ed inline). The renderer runs it in a detached fiber:
 
 ```typescript
+import { Effect, SubscriptionRef } from "effect";
+
+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" }), h.button({ type: "submit" }, "Login")],
+);
+```
+
+Read a field imperatively inside the handler with `SubscriptionRef.get`, rather than threading its current value in from outside:
+
+```typescript
+onsubmit: (e) => {
+  e.preventDefault();
+  return Effect.gen(function* () {
+    const u = yield* SubscriptionRef.get(usernameRef);
+    const p = yield* SubscriptionRef.get(passwordRef);
+    yield* login(u, p);
+  });
+},
+```
+
+## Cross-field validation
+
+Combine two fields' `changes` streams with `Stream.zipLatestWith` before mapping to a result:
+
+```typescript
+import { Stream, SubscriptionRef } from "effect";
+
+const isValid = Stream.zipLatestWith(
+  SubscriptionRef.changes(usernameRef),
+  SubscriptionRef.changes(passwordRef),
+  (u, p) => u.length > 0 && p.length > 0,
+);
+
+h.button({ type: "submit" }, [
+  Stream.map(isValid, (valid) => (valid ? "Register" : "Fill all fields")),
+]);
+```
+
+Nest another `zipLatestWith` to bring in a third field.
+
+## Complete example
+
+A login form: one validated email field, a submit button disabled by nothing (validity only changes its label), and a status line. This is the whole file set, copy/paste runnable in a `vite` + `@weftui/core`/`@weftui/dom` project.
+
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Weft form handling demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```typescript
+// src/app.ts
+/**
+ * Login form: a validated email field with reactive Schema errors, and an
+ * Effect-returning submit handler. Side-effect-free (no mount call), so
+ * `main.ts` and any test can import `App` directly.
+ */
 import { h } from "@weftui/core";
 import { Effect, Result, Schema, Stream, SubscriptionRef } from "effect";
 
@@ -20,14 +144,13 @@ const Email = Schema.String.pipe(
   Schema.check(Schema.makeFilter((s) => (s.includes(".") ? undefined : "Must contain a domain"))),
 );
 
-const LoginForm = () =>
+export const App = () =>
   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(SubscriptionRef.changes(email), (value) => {
-      if (value.length === 0) return null; // don't nag an empty field
+      if (value.length === 0) return null;
       return Result.match(Schema.decodeUnknownResult(Email)(value), {
         onFailure: (e) => e.message.split(":").pop()?.trim() ?? "Invalid",
         onSuccess: () => null,
@@ -48,7 +171,7 @@ const LoginForm = () =>
       [
         h.input({
           type: "email",
-          oninput: (e) => SubscriptionRef.set(email, (e.target as HTMLInputElement).value),
+          oninput: (e) => SubscriptionRef.set(email, e.currentTarget.value),
         }),
         Stream.map(error, (err) => (err ? h.span({ class: "error-text" }, err) : null)),
         h.button({ type: "submit" }, "Login"),
@@ -58,19 +181,23 @@ 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.
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the form demo into #root.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
 
-## Variations
+const root = document.getElementById("root")!;
 
-- **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.
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
 
 ## 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
+- [Author Components](https://weftui.dev/docs/how-to/author-components): components with internal state and instance scope
 - [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

@@ -13,7 +13,7 @@ Return a `Stream<Node>` that emits the loading node first and the resolved node
 
 ```typescript
 import { h } from "@weftui/core";
-import { Effect, Stream } from "effect";
+import { Effect, pipe, Stream } from "effect";
 
 interface User {
   id: number;
@@ -32,7 +32,8 @@ const UserCard = ({ id }: { id: number }) =>
   Stream.concat(
     Stream.make(h.div({ class: "loading" }, `Loading user ${id}…`)),
     Stream.fromEffect(
-      fetchUser(id).pipe(
+      pipe(
+        fetchUser(id),
         Effect.flatMap((user) => h.div({ class: "user-card" }, [h.h3(user.name), h.p(user.email)])),
         Effect.catch((error) => h.div({ class: "error" }, `Error: ${error.message}`)),
       ),
@@ -47,16 +48,119 @@ const UserCard = ({ id }: { id: number }) =>
 - **`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, with no orchestration needed.
 
+## Full example
+
+The whole file set: `UserCard` mounted twice, one instance failing on purpose (`id: 3`) to show the fallback. Copy/paste runnable in a `vite` + `@weftui/core` + `@weftui/dom` project.
+
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Async user card</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```typescript
+// src/app.ts
+/**
+ * Renders a loading placeholder, then a fetched user card, or an error
+ * fallback if the fetch fails. Side-effect-free (no mount call), so
+ * `main.ts` and any test can import `App` directly.
+ */
+import { h } from "@weftui/core";
+import { Effect, pipe, 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(
+      pipe(
+        fetchUser(id),
+        Effect.flatMap((user) => h.div({ class: "user-card" }, [h.h3(user.name), h.p(user.email)])),
+        Effect.catch((error) => h.div({ class: "error" }, `Error: ${error.message}`)),
+      ),
+    ),
+  );
+
+export const App = () => h.div({ id: "app" }, [UserCard({ id: 1 }), UserCard({ id: 3 })]);
+```
+
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the async user card demo into `#root`.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+
+const root = document.getElementById("root")!;
+
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
+
 ## 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: each async sibling owns its own loading state and its own fallback. When several async siblings should share **one fallback** and swap in together, wrap them in a suspense boundary instead:
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+
+Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading…") }, [
+  UserCard({ id: 1 }),
+  UserCard({ id: 2 }),
+]);
+```
+
+`Boundary.suspend` waits for **all** children to emit before swapping in, so there's no partial flicker between siblings. See [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) for the full model.
+
+When the data must resolve on the **server** and replay on hydrate without a second request, use [`Boundary.rpc`](https://weftui.dev/docs/how-to/load-data-with-rpc) instead. Both boundaries are client-only otherwise; 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 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:
+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 leaf's own **body** instead changes that:
+
+```typescript
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { Schema } from "effect";
+
+// Streaming: fetchUser lives on a child (UserCard); the leaf commits immediately.
+const streamingLeaf = ({ path }: { path: { id: number } }) =>
+  h.article([h.h1("User"), UserCard({ id: path.id })]);
+
+// Blocking: fetchUser lives in the leaf's own body; navigation waits for it.
+const blockingLeaf = Component.gen(function* () {
+  const { id } = yield* Router.params({ id: Schema.NumberFromString });
+  const user = yield* fetchUser(id);
+  return yield* h.article([h.h1("User"), h.p(user.name)]);
+});
+```
 
-- **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.
+- **`blockingLeaf`** 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.
+- **`streamingLeaf`** is streaming. The leaf commits immediately and the region fills in place once `UserCard`'s 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.
 

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

@@ -7,11 +7,9 @@ description: Boundary.rpc, server-resolved and client-refreshable data; the cont
 
 # 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.
+`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.
 
-## 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.
+## Quick example
 
 ```typescript
 import { Boundary, h, Subscribable } from "@weftui/core";
@@ -33,9 +31,11 @@ Boundary.rpc(
 );
 ```
 
+`render` receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea), resolved through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam that `@weftui/router` provides. The same rpc serves every lifecycle, so SSR-replay, refetch, and client-first mount are one mechanism, not three.
+
 ## 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:
 
 ```typescript
 // data/inventory.ts
@@ -68,11 +68,11 @@ 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.
+The split is enforced structurally by which files each entry imports, not by a bundler plugin. 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.
+Pass the **merged group** to both sides, plus the **handler Layer** on the server:
 
 ```typescript
 // entry-server.ts: in-process client over the handlers + POST /_eui/rpc endpoint
@@ -100,7 +100,7 @@ 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. 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).
+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
 
@@ -111,7 +111,13 @@ 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, the SSR HTML and the adopted DOM are byte-identical. There is **no fallback flash** on the SSR/hydrate path; `fallback` renders only on a client-first mount:
+
+```typescript
+Boundary.rpc(GetStock, () => ({ id: product.id }), render, {
+  fallback: h.p("loading stock…"), // unused on SSR/hydrate; shown only client-first
+});
+```
 
 ## The `Resource` handle
 
@@ -133,7 +139,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,22 +153,169 @@ 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. The nearest enclosing **failure `Boundary`** renders its fallback.
+Give the rpc an `error` schema and a resolved rpc **error** on the SSR pass is `errorSchema`-encoded into an inline failure payload:
 
-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
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { Schema } from "effect";
+
+export class OutOfStock extends Schema.TaggedError<OutOfStock>()("OutOfStock", {
+  reason: Schema.String,
+}) {}
+
+export const GetStock = Rpc.make("GetStock", {
+  payload: StockKey,
+  success: Stock,
+  error: OutOfStock,
+});
+```
+
+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) => /* … */),
+  Boundary.rpc(
+    GetStock,
+    () => ({ id: product.id }),
+    (resource) => h.p([Stream.map(Subscribable.changes(resource.value), (s) => String(s.units))]),
+  ),
 ]);
 ```
 
 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.
 
+## Full example
+
+A `/products/:id` page with a refetchable live-stock `Boundary.rpc`, sealed into a single-route router app. This is the whole file set for the router + rpc parts (drop it alongside a dev server that bridges `entry-server.ts`'s `handler` into Vite or any Web-platform server; see [`examples/router-ssr/server.ts`](https://github.com/stefvw93/weft/blob/main/examples/router-ssr/server.ts) and its co-located [`vite.config.ts`](https://github.com/stefvw93/weft/blob/main/examples/router-ssr/vite.config.ts) for a working one).
+
+```typescript
+// src/data/inventory.ts
+/**
+ * The product's live stock: rpc contract + server-only handler. See "The
+ * contract / handler split" above for why this file is safe to import from
+ * both `app.ts` (contract only) and `entry-server.ts` (contract + handler).
+ */
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { Context, Effect, Layer, Schema } from "effect";
+
+export const Stock = Schema.Struct({ units: Schema.Number });
+export const StockKey = Schema.Struct({ id: Schema.Number });
+export const GetStock = Rpc.make("GetStock", { payload: StockKey, success: Stock });
+export const StockRpcs = RpcGroup.make(GetStock);
+
+class Inventory extends Context.Service<
+  Inventory,
+  { readonly stockFor: (id: number) => Effect.Effect<typeof Stock.Type> }
+>()("Inventory") {}
+
+const InventoryLive = Layer.succeed(Inventory, {
+  stockFor: (id) => Effect.succeed({ units: 7 + (id % 5) }),
+});
+
+export const StockLive = StockRpcs.toLayer({
+  GetStock: (payload) => Effect.flatMap(Inventory, (inv) => inv.stockFor(payload.id)),
+}).pipe(Layer.provide(InventoryLive));
+```
+
+```typescript
+// src/app.ts
+/**
+ * Shared, isomorphic router app: one `/products/:id` page with a refetchable
+ * live-stock `Boundary.rpc`. Side-effect-free (no mount/hydrate call), so
+ * both entries and any test can import `App` directly.
+ */
+import { Boundary, Component, h, Subscribable } from "@weftui/core";
+import { notFound, Router } from "@weftui/router";
+import { Schema, Stream } from "effect";
+import { GetStock } from "./data/inventory";
+
+const idParam = { id: Schema.NumberFromString };
+
+const productRoute = Router.route("products/:id", {
+  path: idParam,
+  component: ({ path }) => {
+    if (!Number.isFinite(path.id) || path.id < 0) return notFound();
+    return Boundary.rpc(
+      GetStock,
+      () => ({ id: path.id }),
+      (resource) =>
+        h.section({ id: "page" }, [
+          h.h2(`Product ${path.id}`),
+          h.p([
+            "in stock: ",
+            h.span([Stream.map(Subscribable.changes(resource.value), (s) => String(s.units))]),
+          ]),
+          h.button({ type: "button", onclick: () => resource.refetch }, "Refresh stock"),
+        ]),
+      { fallback: h.p("loading stock…") },
+    );
+  },
+});
+
+const Shell = Component.gen(function* () {
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ id: "app" }, [outlet]);
+});
+
+export const App = Router.router(Router.layout({ component: Shell }, [productRoute]), {
+  notFound: () => h.section({ id: "page" }, [h.h2("404: page not found")]),
+});
+```
+
+```typescript
+// src/entry-server.ts
+/**
+ * Server entry: renders the matched route to a hydratable HTML document,
+ * wiring the rpc's shared group and its server-only handler Layer.
+ */
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { RouterServer } from "@weftui/router/server";
+import { Effect } from "effect";
+import { App } from "./app";
+import { StockLive, StockRpcs } from "./data/inventory";
+
+const rpc = { group: StockRpcs, handlers: StockLive } as const;
+
+const documentShell = Component.gen(function* () {
+  const app = yield* Router.Outlet;
+  return yield* h.html({ lang: "en" }, [
+    h.head([h.meta({ charset: "utf-8" }), h.title("Weft shop")]),
+    h.body([
+      h.div({ id: "root" }, [app]),
+      h.script({ type: "module", src: "/src/entry-client.ts" }),
+    ]),
+  ]);
+});
+
+export const render = (url: string): Promise<{ html: string; status: number }> =>
+  Effect.runPromise(RouterServer.render(App, { document: documentShell, rpc, url }));
+
+export const handler = RouterServer.toWebHandler(App, { document: documentShell, rpc });
+```
+
+```typescript
+// src/entry-client.ts
+/**
+ * Client entry: hydrates the server-rendered markup in `#root`, wiring the
+ * rpc's shared group so `resource.refetch` posts to `/_eui/rpc`.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { Effect } from "effect";
+import { App } from "./app";
+import { StockRpcs } from "./data/inventory";
+
+const root = document.getElementById("root")!;
+
+const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
+```
+
 ## 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. It stays **refreshable** on the client over the same rpc.