@weftui/router 0.30.0 → 0.31.0

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

@@ -7,29 +7,26 @@ description: "Use Props.merge to combine a behavior prop bag with your own marku
 
 # Compose Behavior and Markup
 
-**Goal:** share behavior (aria wiring, handlers, refs, reactive state) without
-giving up ownership of the element it applies to.
+`Props.merge` combines a behavior's prop bag (aria wiring, handlers, refs, reactive state) with markup you own, without either side losing what it contributed.
 
 ## 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 can't combine two prop bags safely:
 
-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.
+```ts
+const merged = { ...behavior, ...mine };
+// mine.onclick replaces behavior.onclick entirely, and mine.ref replaces
+// behavior.ref entirely. Nothing warns you.
+```
 
-`Props.merge` reconciles both bags instead.
+`Props.merge` reconciles the collision per key instead of silently dropping a side.
 
 ## 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.
+A behavior primitive is a plain Effect that yields a prop bag. There's no component wrapper and no hook rules, so you `yield*` it anywhere and hold the result:
 
 ```ts
-import { Effect, Option, SubscriptionRef } from "effect";
+import { Effect, Option, Stream, SubscriptionRef } from "effect";
 
 const makeDisclosure = () =>
   Effect.gen(function* () {
@@ -38,7 +35,11 @@ const makeDisclosure = () =>
 
     const trigger = {
       ref: anchor,
-      "aria-expanded": SubscriptionRef.changes(isOpen),
+      // A boolean value renders as presence-only (`setAttribute(name, "")`),
+      // which is wrong for `aria-*`. Map to the literal string instead.
+      "aria-expanded": Stream.map(SubscriptionRef.changes(isOpen), (open) =>
+        open ? ("true" as const) : ("false" as const),
+      ),
       onclick: () => SubscriptionRef.update(isOpen, (open) => !open),
     };
 
@@ -46,13 +47,11 @@ const makeDisclosure = () =>
   });
 ```
 
-`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.
+`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
+## Merge onto your element
 
-You write the element. The bag merges onto it.
+You write the element; the bag merges onto it:
 
 ```ts
 import { h } from "@weftui/core";
@@ -74,24 +73,32 @@ const Panel = () =>
   });
 ```
 
-Three rules earn their keep in that one call:
+- **Handlers chain.** The disclosure toggles, then `trackClick` runs; a failure in one never blocks the other.
+- **Refs fan out.** `anchor` and `measure` both receive the element; spread would have kept only one.
+- **`class` takes a reactive condition.** `btn--open` follows `isOpen` through `Props.cx`.
+
+Type an inline handler's event explicitly (`(ev: MouseEvent)` above). `merge` doesn't know which element the bag will land on, so it can't infer it.
+
+## Per-key rules
+
+| Key           | Rule                                                                                         |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| `on*`         | Chained left to right. Both bodies run; failures from both sides are aggregated.             |
+| `class`       | Concatenated. All-static stays a `string`; either side reactive makes it a `Stream<string>`. |
+| `style`       | Two per-property objects merge per key, right wins. Any other shape is last-wins.            |
+| `ref`         | Fan out: concatenates into an array, and every ref receives the element.                     |
+| anything else | Last-wins.                                                                                   |
 
-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.
+```ts
+Props.merge({ style: { color: "red" } }, { style: { fontWeight: "bold" } });
+// => { style: { color: "red", fontWeight: "bold" } }
+```
 
-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.
+A key present on only one side passes through untouched.
 
-## Typed errors flow through
+## Typed errors and services 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.
+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;
@@ -109,35 +116,115 @@ 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.
+- **`false` on a handler is an explicit opt-out and wins.** `null`/`undefined` mean "not provided", so the other side survives instead:
+
+  ```ts
+  Props.merge({ onclick: () => track() }, { onclick: false }); // handler is off
+  ```
+
+- **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 above.
 
-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.
+## Complete example
+
+A disclosure behavior merged onto a caller-owned button, with a click counter and a ref the behavior doesn't know about. 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>Compose behavior and markup demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```typescript
+// src/app.ts
+/**
+ * Disclosure behavior (open state, anchor ref, toggle handler) merged onto a
+ * button the caller owns: its own class, its own click counter, its own ref.
+ * Side-effect-free (no mount call), so `main.ts` and any test can import
+ * `App` directly.
+ */
+import { h } from "@weftui/core";
+import { Props } from "@weftui/dom";
+import { Effect, Option, Stream, 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": Stream.map(SubscriptionRef.changes(isOpen), (open) =>
+        open ? ("true" as const) : ("false" as const),
+      ),
+      onclick: () => SubscriptionRef.update(isOpen, (open) => !open),
+    };
+
+    return { isOpen, trigger };
+  });
+
+export const App = () =>
+  Effect.gen(function* () {
+    const disclosure = yield* makeDisclosure();
+    const measure = yield* SubscriptionRef.make(Option.none<HTMLElement>());
+    const clicks = yield* SubscriptionRef.make(0);
+
+    return yield* h.div({ id: "app" }, [
+      h.button(
+        Props.merge(disclosure.trigger, {
+          class: Props.cx("btn", { "btn--open": SubscriptionRef.changes(disclosure.isOpen) }),
+          onclick: () => SubscriptionRef.update(clicks, (n) => n + 1),
+          ref: measure,
+        }),
+        "Details",
+      ),
+      h.p([
+        "clicked ",
+        Stream.map(SubscriptionRef.changes(clicks), String),
+        " times · ref fan-out: ",
+        Stream.map(SubscriptionRef.changes(measure), (captured) =>
+          Option.isSome(captured) ? "captured" : "pending",
+        ),
+      ]),
+    ]);
+  });
+```
+
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the 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 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.
+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 only earns its cost 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.
+`Props.merge` is pure: calling it has no side effects and subscribes nothing. A merged `class` that turns out reactive is a `Stream` description, not a live subscription. 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>`.
+- [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`

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.