npm - @weftui/core - Versions diffs - 0.29.0 → 0.31.0 - Mend

@weftui/core 0.29.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/dist/{index-4cTlhojA.d.ts → index-B-dPfhKZ.d.ts} +38 -20
package/dist/index.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/types/index.d.ts +1 -1
package/docs/explanation/boundaries-and-suspense.md +38 -8
package/docs/explanation/combinator-api.md +17 -11
package/docs/explanation/reactive-primitives.md +40 -13
package/docs/explanation/rendering-model.md +14 -2
package/docs/how-to/add-routing.md +299 -28
package/docs/how-to/author-components.md +71 -105
package/docs/how-to/compose-behavior-and-markup.md +141 -54
package/docs/how-to/handle-forms.md +142 -15
package/docs/how-to/load-async-data.md +110 -6
package/docs/how-to/load-data-with-rpc.md +171 -18
package/docs/how-to/provide-services.md +84 -1
package/docs/how-to/render-keyed-lists.md +120 -14
package/docs/how-to/render-on-the-server.md +113 -15
package/docs/how-to/show-navigation-progress.md +120 -14
package/docs/how-to/split-routes-lazily.md +106 -3
package/docs/how-to/style-reactively.md +141 -13
package/docs/how-to/use-element-refs.md +126 -8
package/docs/reference/core.md +22 -2
package/docs/reference/dom.md +43 -0
package/docs/reference/router.md +2 -2
package/docs/tutorial/01-your-first-app.md +43 -13
package/docs/tutorial/02-reactivity.md +29 -30
package/docs/tutorial/03-services-and-async.md +89 -38
package/docs/tutorial/04-errors-and-server.md +41 -25
package/package.json +1 -1

package/docs/how-to/provide-services.md CHANGED Viewed

@@ -11,7 +11,7 @@ description: "Provide plain and scoped Layers to a WeftApp: app layers for the c
 ## Recipe 1: app layers
-Pass the layer to `WeftApp.make`. This is the common case and needs nothing else. The layer builds lazily on first mount, and every component, event handler, and stream subscription in every root mounted from `app` can read it.
+Pass the layer to `WeftApp.make`: the common case, and it needs nothing else. The layer builds lazily on first mount; every component, event handler, and stream subscription in every root mounted from `app` can read it.
 ```typescript
 import { WeftApp } from "@weftui/dom/client";
@@ -25,6 +25,20 @@ const app = WeftApp.make(ThemeServiceLive);
 void Effect.runPromise(WeftApp.mount(app, App(), root));
 ```
+A component reads the service the same way anywhere else in Effect: `yield* Service`.
+```typescript
+import { h } from "@weftui/core";
+import { Effect } from "effect";
+import { ThemeService } from "./theme-service";
+export const App = () =>
+  Effect.gen(function* () {
+    const theme = yield* ThemeService;
+    return yield* h.div({ class: `app app--${theme.mode}` }, [h.p(`Theme: ${theme.mode}`)]);
+  });
+```
 ## Recipe 2: scoped layers just work
 A **scoped** layer (`Layer.effect` backed by `acquireRelease`, or anything else that owns a subscription, listener, or registry) needs nothing different from Recipe 1. The app owns one lazy `ManagedRuntime`. The layer builds on first mount and releases only at `WeftApp.dispose(app)`, not when any individual mount's render effect resolves.
@@ -85,9 +99,78 @@ const acquireApp = Effect.acquireRelease(
 `acquireApp` yields a `WeftApp` and registers `WeftApp.dispose` as a finalizer on whatever scope the surrounding effect runs in. Closing that scope tears the app down the same way `WeftApp.dispose` normally would (roots, then layers, then the error hub).
+## Complete example
+Recipe 1 end to end: a `ThemeService` defined with `Context.Service`, provided through `WeftApp.make`, and read by `App` with `yield* Service`. This is the whole file set, copy/paste runnable in a `vite` 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>Provide services demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+```typescript
+// src/theme-service.ts
+/** The active theme, provided app-wide by `ThemeServiceLive`. */
+import { Context, Layer } from "effect";
+export class ThemeService extends Context.Service<
+  ThemeService,
+  { readonly mode: "light" | "dark" }
+>()("ThemeService") {}
+export const ThemeServiceLive = Layer.succeed(ThemeService, { mode: "dark" });
+```
+```typescript
+// src/app.ts
+/**
+ * Reads `ThemeService` from the app layer and renders the active mode.
+ * Side-effect-free (no mount call), so `main.ts` and any test can import `App`.
+ */
+import { h } from "@weftui/core";
+import { Effect } from "effect";
+import { ThemeService } from "./theme-service";
+export const App = () =>
+  Effect.gen(function* () {
+    const theme = yield* ThemeService;
+    return yield* h.div({ class: `app app--${theme.mode}` }, [
+      h.h1("Provide Services demo"),
+      h.p(`Theme: ${theme.mode}`),
+    ]);
+  });
+```
+```typescript
+// src/main.ts
+/** Browser entry: mounts `App` with `ThemeServiceLive` provided through the app layer. */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+import { ThemeServiceLive } from "./theme-service";
+const root = document.getElementById("root")!;
+const app = WeftApp.make(ThemeServiceLive);
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
 ## Anti-pattern: `Effect.provide` around the mount call
 ```typescript
+import { Effect, pipe } from "effect";
 // ❌ does nothing useful: WeftApp.mount's R is always `never`, and services
 // come exclusively from the app layer: a wrapped Effect.provide never
 // reaches components, handlers, or stream subscriptions

package/docs/how-to/render-keyed-lists.md CHANGED Viewed

@@ -7,44 +7,150 @@ description: Render a reactive collection with List.each so reordering, insertin
 # Render Keyed Lists
-**Goal:** render a list whose items reorder, insert, or remove over time, without rebuilding the whole region (which would lose focus, scroll, and input state in the surviving rows).
-Use [`List.each`](https://weftui.dev/docs/reference/core#listeach), the keyed-list combinator. It renders each item **once per key** and reconciles across emissions. A reorder _moves_ existing DOM nodes, an insert adds one, a remove drops one, and untouched rows are left entirely alone.
+**Goal:** render a list that reorders, inserts, or removes items over time, without rebuilding the whole region and losing focus, scroll, or input state in the surviving rows.
 ```typescript
-import { h, List } from "@weftui/core";
+import { h, List, Subscribable } from "@weftui/core";
 import { Stream } from "effect";
 declare const rows: Subscribable.Subscribable<ReadonlyArray<{ id: number; name: string }>>;
 h.ul([
   List.each(
-    { of: rows.changes, by: (row) => row.id }, // key by stable identity
+    { of: Subscribable.changes(rows), by: (row) => row.id }, // key by stable identity
     (row) => h.li(row.name),
   ),
 ]);
 ```
-- **`of`** is the list source: any `Stream`, `Effect`, or `Subscribable` of an `Iterable`. Each emission is materialized to an array to fix order, then reconciled by key.
-- **`by`** projects each item to its reconciliation key, compared via Effect's `Equal`/`Hash`. Omit it and the item itself is the key (structural for `Data`, by reference otherwise).
+[`List.each`](https://weftui.dev/docs/reference/core#listeach) renders each item **once per key** and reconciles across emissions. A reorder moves existing DOM nodes, an insert adds one, a remove drops one, and untouched rows are left alone.
+## Options
-## Why not `map`?
+```typescript
+interface List.Options<S, K> {
+  readonly of: S; // Iterable<T>, or an Effect/Stream/Subscribable of one
+  readonly by?: (item: ItemOf<S>, index: number) => K; // reconciliation key
+}
+```
-Mapping items by hand (`Stream.map(rows.changes, (rs) => rs.map(r => h.li(r.name)))`) produces a **new children array on every emission**. The renderer then rebuilds the whole region: every row's DOM node is recreated even if only one item moved.
+- **`of`**: the list source. Each emission is materialized to an array to fix order, then reconciled by key.
+- **`by`**: projects each item to its reconciliation key, compared via Effect's `Equal`/`Hash`. Omit it and the item itself is the key (structural for `Data`, by reference otherwise).
-`List.each` reconciles by key instead, so DOM identity (and the focus/scroll/typed-input state attached to it) survives across updates.
+## Why not `map`
+```typescript
+// Rebuilds every row on every emission: a new children array each time.
+Stream.map(Subscribable.changes(rows), (rs) => rs.map((r) => h.li(r.name)));
+```
+The renderer diffs children by position, so a new array means every row's DOM node is recreated, even the ones that didn't move. `List.each` reconciles by key instead, so DOM identity (and the focus/scroll/typed-input state attached to it) survives across updates.
 ## Refresh a row's content
-Because `render` runs **exactly once per key**, reconciliation never re-runs it for a kept row, so it never refreshes that row's content on its own. To make a row's content reactive, thread a `Stream` **inside** the row rather than expecting a re-render:
+`render` runs **exactly once per key**, so reconciliation never re-runs it for a kept row. To make a row's content reactive, thread a `Stream` **inside** the row instead of expecting a re-render:
 ```typescript
-List.each({ of: rows.changes, by: (row) => row.id }, (row) =>
-  h.li([h.span([Stream.map(row.status.changes, (s) => s)])]),
+List.each({ of: Subscribable.changes(rows), by: (row) => row.id }, (row) =>
+  h.li([h.span([Stream.map(Subscribable.changes(row.status), (s) => s)])]),
 );
 ```
-> **⚠️ Index-key footgun.** Keying by index (`by: (_, i) => i`) reuses rows positionally, so after a reorder each position keeps its old content and you see stale rows. Prefer a stable identity key (`by: (item) => item.id`).
+## Index-key footgun
+```typescript
+// Wrong: reuses rows positionally. After a reorder, each position keeps its
+// old content, so the visible rows are stale.
+List.each({ of: Subscribable.changes(rows), by: (_row, i) => i }, renderRow);
+// Right: a stable identity key follows the item, not its position.
+List.each({ of: Subscribable.changes(rows), by: (row) => row.id }, renderRow);
+```
+## Complete example
+A shuffleable row list. Each row starts a per-row tick counter and renders an uncontrolled `<input>`; shuffling moves rows instead of recreating them, so counters keep counting and typed input keeps its value and focus.
+```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>Keyed list demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+```typescript
+// src/app.ts
+/**
+ * Keyed list demo: List.each moves existing rows on shuffle instead of
+ * rebuilding them, so each row's own tick counter keeps running and its
+ * input keeps focus and value. Side-effect-free (no mount call), so
+ * `main.ts` and any test can import `App` directly.
+ */
+import { h, List } from "@weftui/core";
+import { Effect, Schedule, Stream, SubscriptionRef } from "effect";
+interface Row {
+  readonly id: number;
+  readonly name: string;
+}
+const renderRow = (row: Row) => {
+  // Created once per key: starts a single time and keeps running across
+  // every later shuffle of this row.
+  const ticks = Stream.iterate(0, (n) => n + 1).pipe(Stream.schedule(Schedule.spaced("1 second")));
+  return h.li({ id: `row-${row.id}` }, [
+    h.span(row.name),
+    h.input({ placeholder: "type here…" }),
+    h.span(["ticks: ", ticks]),
+  ]);
+};
+export const App = () =>
+  Effect.gen(function* () {
+    const rows = yield* SubscriptionRef.make<ReadonlyArray<Row>>([
+      { id: 1, name: "Ada" },
+      { id: 2, name: "Babbage" },
+      { id: 3, name: "Curie" },
+    ]);
+    const shuffle = SubscriptionRef.update(rows, (current) =>
+      [...current].sort(() => Math.random() - 0.5),
+    );
+    return yield* h.div([
+      h.button({ onclick: () => shuffle }, "Shuffle"),
+      h.ul([List.each({ of: SubscriptionRef.changes(rows), by: (row) => row.id }, renderRow)]),
+    ]);
+  });
+```
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the keyed list demo into #root.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("#root not found");
+}
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
 ## See also

package/docs/how-to/render-on-the-server.md CHANGED Viewed

@@ -7,37 +7,48 @@ description: renderToString / renderToStringHydratable / streaming variants, hyd
 # Server-Side Rendering
-Weft renders on the server and **hydrates** on the client. The server produces HTML plus inline data, and the browser adopts that existing DOM in place rather than re-creating it.
+Weft renders on the server and hydrates on the client: the server produces HTML, and the browser adopts that existing DOM in place instead of re-creating it.
 [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) extends this to **rpc-backed server data**: resolve an rpc on the server, serialize its result into the HTML, and replay it on the client without a second request. The region then stays live for refetch.
-## The two halves
-- **Server**: `@weftui/dom/server` renders an app node to an HTML string (or stream). The _hydratable_ variants also emit the inline data each reactive region and `Boundary.rpc` needs to resume on the client.
-- **Client**: `@weftui/dom/client`'s `WeftApp.hydrate` walks the server DOM, adopts it, wires up reactivity and event handlers, and resumes from the inline data. It does **not** re-render from scratch.
 ```typescript
-// server entry
+// entry-server.ts
+import { AppRpcClientTag } from "@weftui/core";
 import { renderToStringHydratable } from "@weftui/dom/server";
-import { Effect } from "effect";
+import { Effect, Layer } from "effect";
 import { App } from "./app";
-export const render = (): Promise<string> => Effect.runPromise(renderToStringHydratable(App()));
+// Every SSR render fn requires an AppRpcClientTag in context unconditionally,
+// even when the tree has no Boundary.rpc. Discharge it with a no-op when unused.
+const NoRpc = Layer.succeed(AppRpcClientTag, {
+  call: () => Effect.die(new Error("no rpc in this app")),
+});
+export const render = (): Promise<string> =>
+  Effect.runPromise(Effect.provide(renderToStringHydratable(App()), NoRpc));
 ```
 ```typescript
-// client entry
+// entry-client.ts
 import { WeftApp } from "@weftui/dom/client";
 import { Effect } from "effect";
 import { App } from "./app";
-const root = document.getElementById("root")!;
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("#root not found");
+}
 const app = WeftApp.make();
 void Effect.runPromise(WeftApp.hydrate(app, App(), root));
 ```
 Both entries import the same side-effect-free `App`. Splice the server HTML into your template's outlet, ship it, and let the client entry hydrate it.
+When `App` renders a real `Boundary.rpc`, replace `NoRpc` with the Layer `@weftui/router`'s `RouterServer` provides (see [Loading server data with `Boundary.rpc`](#loading-server-data-with-boundaryrpc) below). `NoRpc` only exists to satisfy the type when the tree has no rpc boundaries to resolve.
+## The four renderers
 `@weftui/dom/server` exports four renderers:
 |                                        | String                     | Stream                     |
@@ -45,7 +56,83 @@ Both entries import the same side-effect-free `App`. Splice the server HTML into
 | **Plain** (no JS / no hydration)       | `renderToString`           | `renderToStream`           |
 | **Hydratable** (emits inline payloads) | `renderToStringHydratable` | `renderToStreamHydratable` |
-Use a hydratable renderer whenever the client will call `hydrate`. The plain renderers produce complete, JS-free HTML with no payload scripts.
+```typescript
+import {
+  renderToStream,
+  renderToStreamHydratable,
+  renderToString,
+  renderToStringHydratable,
+} from "@weftui/dom/server";
+```
+Use a hydratable renderer whenever the client will call `hydrate`. The plain renderers produce complete, JS-free HTML with no payload scripts, so use them for pages that never run client JS.
+All four share the same requirement channel: `Effect.Effect<string, Error, AppRpcClientTag>` for the string variants, `Stream.Stream<string, Error, AppRpcClientTag>` for the stream variants.
+## Full example
+The complete file set for an isomorphic counter: a shared `app.ts`, an SSR entry, and a hydrating client entry. This is the same shape `examples/ssr-hydration` runs; see that example for the dev server (`server.ts`) and `index.html` that bridge `entry-server.ts` into a request.
+```typescript
+// src/app.ts
+/**
+ * Shared isomorphic App. Rendered to hydratable HTML on the server and
+ * hydrated in the browser from that same markup. The `SubscriptionRef`
+ * region is flash-free: the server's first emission matches the client's
+ * first emission, so `hydrate` adopts the existing node in place.
+ */
+import { h } from "@weftui/core";
+import { Effect, SubscriptionRef } from "effect";
+export const App = (props: { initialValue: number }) =>
+  Effect.gen(function* () {
+    const count = yield* SubscriptionRef.make(props.initialValue);
+    const increment = () => SubscriptionRef.update(count, (n) => n + 1);
+    const decrement = () => SubscriptionRef.update(count, (n) => n - 1);
+    return yield* h.div([
+      h.h1("SSR + Hydration"),
+      h.div({ class: "count" }, [SubscriptionRef.changes(count)]),
+      h.button({ type: "button", onclick: () => decrement() }, "-"),
+      h.button({ type: "button", onclick: () => increment() }, "+"),
+    ]);
+  });
+```
+```typescript
+// src/entry-server.ts
+import { AppRpcClientTag } from "@weftui/core";
+import { renderToStringHydratable } from "@weftui/dom/server";
+import { Effect, Layer } from "effect";
+import { App } from "./app";
+// This app has no Boundary.rpc, but the SSR render fns require an
+// AppRpcClientTag in context unconditionally, so discharge it with a no-op.
+const NoRpc = Layer.succeed(AppRpcClientTag, {
+  call: () => Effect.die(new Error("no rpc in this example")),
+});
+/** Renders the app to a hydratable HTML string. */
+export const render = (): Promise<string> =>
+  Effect.runPromise(Effect.provide(renderToStringHydratable(App({ initialValue: 3 })), NoRpc));
+```
+```typescript
+// src/entry-client.ts
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("#root not found");
+}
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.hydrate(app, App({ initialValue: 3 }), root));
+```
+`renderToStringHydratable` wraps the `SubscriptionRef.changes(count)` region in `<!-- stream-start-N -->` / `<!-- stream-end-N -->` markers around its first emission (`3`). `WeftApp.hydrate` locates that region via the markers, adopts the existing DOM node, and resumes the stream in place: no flash, no re-render.
 ## Loading server data with `Boundary.rpc`
@@ -54,7 +141,7 @@ Use a hydratable renderer whenever the client will call `hydrate`. The plain ren
 It follows the same server/client split: the rpc **contract** (pure Schema) is shared, while its **handler** lives in a server-only Layer the client never imports.
 ```typescript
-import { Boundary, h } from "@weftui/core";
+import { Boundary, h, Subscribable } from "@weftui/core";
 import { Stream } from "effect";
 import { GetStock } from "./data/inventory";
@@ -65,7 +152,7 @@ const StockPanel = (productId: number) =>
     (resource) =>
       h.p([
         "in stock: ",
-        h.span([Stream.map(resource.value.changes, (stock) => String(stock.units))]),
+        h.span([Stream.map(Subscribable.changes(resource.value), (stock) => String(stock.units))]),
         h.button({ type: "button", onclick: () => resource.refetch }, "Refresh"),
       ]),
     { fallback: h.p("loading stock…") }, // shown only on a client-first SPA mount
@@ -74,7 +161,18 @@ const StockPanel = (productId: number) =>
 Under SSR the server resolves the rpc in-process, `successSchema`-encodes the result inline as `<script type="application/json">`, and renders in place; `hydrate` reads that payload positionally, seeds the `Resource`, and adopts the DOM **without re-calling the rpc** (replay, never retry). The full model lives in one place, the [RPC Data Boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc): the contract/handler split, router wiring, the four lifecycles, the `Resource` handle, and typed-failure replay. This page does not repeat it.
-> **Note.** `Boundary.rpc` resolves through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam, which `@weftui/router` provides on both sides. In a router-less mount there is no seam, so the boundary resolves to a descriptive "needs router/rpc" error (not a defect).
+`Boundary.rpc` resolves through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam, which `@weftui/router` provides on both sides:
+```typescript
+// client (RouterLive): network rpc client over the shared group
+const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+// server (RouterServer): same group, plus its handler Layer
+const rpc = { group: StockRpcs, handlers: StockLive };
+export const handler = RouterServer.toWebHandler(App, { document: documentShell, rpc });
+```
+In a router-less mount (like the `NoRpc` layer above) there is no seam, so the boundary resolves to a descriptive "needs router/rpc" error, not a defect.
 ## When to use

package/docs/how-to/show-navigation-progress.md CHANGED Viewed

@@ -7,14 +7,12 @@ description: Render a pending indicator (e.g. a top progress bar) during a defer
 # Show Navigation Progress
-**Goal:** show a progress indicator while a [lazy route](https://weftui.dev/docs/how-to/split-routes-lazily) resolves its chunk and data, so a slow network is visible instead of feeling frozen.
+**Goal:** show a progress indicator while a navigation resolves a [lazy route](https://weftui.dev/docs/how-to/split-routes-lazily)'s chunk or a leaf's own async data, so a slow network is visible instead of feeling frozen.
-When you navigate to a route, the router is **deferred-commit**. It resolves the target branch's chunk (if the component is `Router.lazy`) **and the matched leaf's own component effect**, including any data the leaf awaits in its body. Only then does it swap the URL, keeping the previous page mounted for the whole window.
-That resolve window is exposed as a reactive signal, [`Router.navigating`](https://weftui.dev/docs/reference/router#routernavigating), that you read to render pending UI.
+Client navigation is **deferred-commit**: the router resolves the target branch's chunk (if `Router.lazy`) and the matched leaf's own component effect before swapping the URL, so the previous page stays mounted for the whole window. Read [`Router.navigatingStream`](https://weftui.dev/docs/reference/router#routernavigating) in a persistent layout to render pending UI for that window:
 ```typescript
-import { Component, h } from "@weftui/core";
+import { Component, h, Subscribable } from "@weftui/core";
 import { Router } from "@weftui/router";
 import { Stream } from "effect";
@@ -25,7 +23,7 @@ const Shell = Component.gen(function* () {
     h.div({
       id: "nav-progress",
       "aria-hidden": "true",
-      class: Stream.map(nav.changes, (s) =>
+      class: Stream.map(Subscribable.changes(nav), (s) =>
         s._tag === "Navigating" ? "nav-progress is-navigating" : "nav-progress",
       ),
     }),
@@ -34,11 +32,9 @@ const Shell = Component.gen(function* () {
 });
 ```
-Thread the signal into a persistent layout (the outermost `Shell` is ideal, since it never re-renders across navigations), and style the pending class however you like: a top bar, a cursor change, a dimmed outlet.
-## The signal
+Put this in the outermost `Shell`, since it never re-renders across navigations, and style `.is-navigating` however you like: a top bar, a cursor change, a dimmed outlet.
-`NavState` is a two-state machine:
+## The `NavState` signal
 ```typescript
 type NavState = { readonly _tag: "Idle" } | { readonly _tag: "Navigating"; readonly to: string };
@@ -46,10 +42,120 @@ type NavState = { readonly _tag: "Idle" } | { readonly _tag: "Navigating"; reado
 Read it two ways, mirroring `Router.params` / `Router.paramsStream`:
-- `Router.navigating`: the `Subscribable<NavState>` on the `Router` service.
-- `Router.navigatingStream`: an `Effect` resolving that `Subscribable`, for use in a `Component.gen` body (as above).
+- `Router.navigatingStream`: an `Effect` resolving the `Subscribable<NavState>`, for a `Component.gen` body (as above).
+- `Router.navigating`: the raw `Subscribable<NavState>` on the `Router` service, for reading outside a component.
+`Navigating`'s `to` field is the target URL, if you want to label _where_ the app is going.
+## Full example
+A client-only app with an instant `Home` route and a `Reports` route whose component awaits its own data. That `yield*` blocks the commit, so the Shell's progress bar shows for the resolve window. This is the whole file set, copy/paste runnable in a `vite` + `@weftui/router` 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 navigation progress demo</title>
+    <style>
+      #nav-progress {
+        position: fixed;
+        top: 0;
+        left: 0;
+        height: 3px;
+        width: 0;
+        background: #06c;
+        opacity: 0;
+      }
+      #nav-progress.is-navigating {
+        width: 100%;
+        opacity: 1;
+        transition:
+          width 600ms ease-out,
+          opacity 150ms;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+```typescript
+// src/app.ts
+/**
+ * Client-only demo: a Shell layout with an instant Home route and a Reports
+ * route whose component awaits its own data before rendering. That `yield*`
+ * makes the navigation deferred-commit, so the Shell's `Router.navigatingStream`
+ * reader flips to "Navigating" for the resolve window. Side-effect-free (no
+ * mount call), so `main.ts` and any test can import `App` directly.
+ */
+import { Component, h, Subscribable } from "@weftui/core";
+import { href, Router } from "@weftui/router";
+import { Effect, Stream } from "effect";
+const homeRoute = Router.route("", {
+  component: Component.make(() => h.section({ id: "page" }, [h.h2("Home")])),
+});
+const reportsRoute = Router.route("reports", {
+  component: Component.gen(function* () {
+    // Simulates fetching a report: this `yield*` blocks the commit, so
+    // `Router.navigatingStream` reports `Navigating` for its whole duration.
+    yield* Effect.sleep("600 millis");
+    return yield* h.section({ id: "page" }, [h.h2("Quarterly report")]);
+  }),
+});
+const Shell = Component.gen(function* () {
+  const outlet = yield* Router.Outlet;
+  const nav = yield* Router.navigatingStream;
+  return yield* h.div({ id: "app" }, [
+    h.div({
+      id: "nav-progress",
+      "aria-hidden": "true",
+      class: Stream.map(Subscribable.changes(nav), (s) =>
+        s._tag === "Navigating" ? "nav-progress is-navigating" : "nav-progress",
+      ),
+    }),
+    h.nav([
+      h.a({ href: href(homeRoute) }, "Home"),
+      " · ",
+      h.a({ href: href(reportsRoute) }, "Reports"),
+    ]),
+    h.main([outlet]),
+  ]);
+});
+export const App = Router.router(Router.layout({ component: Shell }, [homeRoute, reportsRoute]), {
+  notFound: () => h.section({ id: "page" }, [h.h2("404: page not found")]),
+});
+```
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the navigation progress demo into `#root`.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { Effect } from "effect";
+import { App } from "./app";
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("#root not found");
+}
+const app = WeftApp.make(RouterLive(App));
+void Effect.runPromise(WeftApp.mount(app, RouterApp(App), root));
+```
-The `to` field on `Navigating` is the target URL, if you want to label _where_ the app is going.
+Click "Reports" and `#nav-progress` gains `is-navigating` for 600ms while `Home` stays mounted, then swaps atomically to "Quarterly report" with the bar reset to idle.
 ## Behavior to expect
@@ -58,7 +164,7 @@ The `to` field on `Navigating` is the target URL, if you want to label _where_ t
 - **Back/forward.** `popstate` into a route with async work also resolves before committing, so the indicator shows for browser back/forward too.
 - **Failure resets it.** A rejected chunk load or a failing leaf pre-run (a typed error such as `notFound()`, or a defect) resets `navigating` to `Idle` (it never sticks on), then surfaces through normal error/defect handling.
 - **Server renders `Idle`.** Server render is buffered, so `navigating` is a client-only concern; the server supplies a constant `Idle` so the same `Shell` type-checks and renders on both sides.
-- **No built-in anti-flash delay.** The signal flips as soon as an async window opens, so a borderline-fast navigation can flash the indicator briefly. If you want to only show it past a threshold, delay the reveal in CSS rather than in the signal (e.g. `transition-delay: 200ms` on `.is-navigating`), so genuinely fast navigations never flicker.
+- **No built-in anti-flash delay.** The signal flips as soon as an async window opens, so a borderline-fast navigation can flash the indicator briefly. Delay the reveal in CSS instead (e.g. `transition-delay: 200ms` on `.is-navigating`), so genuinely fast navigations never flicker.
 ## See also