@weftui/core 0.28.0 → 0.30.0

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

@@ -2,16 +2,16 @@
 title: Provide Services
 order: 12
 section: how-to
-description: Provide plain and scoped Layers to a WeftApp — app layers for the common case, scoped layers that just work, memoMap sharing, and binding an app's lifetime to a scope.
+description: "Provide plain and scoped Layers to a WeftApp: app layers for the common case, scoped layers that just work, memoMap sharing, and binding an app's lifetime to a scope."
 ---
 
 # Provide Services
 
 **Goal:** provide a `Layer` to a `WeftApp` so its components can read services with `yield* Service`.
 
-## Recipe 1 — app layers
+## 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`. 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.
 
 ```typescript
 import { WeftApp } from "@weftui/dom/client";
@@ -25,11 +25,13 @@ const app = WeftApp.make(ThemeServiceLive);
 void Effect.runPromise(WeftApp.mount(app, App(), root));
 ```
 
-## Recipe 2 — scoped layers just work
+## 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. There is no `mountScoped`, no `Effect.never`, no manual scope threading.
+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.
 
-`AtomRegistry.layer` (from `effect/unstable/reactivity`) is a real scoped layer — its atom subscriptions are fibers forked for the app's whole lifetime:
+There is no `mountScoped`, no `Effect.never`, no manual scope threading.
+
+`AtomRegistry.layer` (from `effect/unstable/reactivity`) is a real scoped layer. Its atom subscriptions are fibers forked for the app's whole lifetime:
 
 ```typescript
 import { WeftApp } from "@weftui/dom/client";
@@ -41,7 +43,7 @@ const app = WeftApp.make(AtomRegistry.layer);
 void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
-`RouterLive` (from `@weftui/router/client`) is another — it owns the `popstate` listener and the same-origin link-click interceptor for as long as the app runs:
+`RouterLive` (from `@weftui/router/client`) is another. It owns the `popstate` listener and the same-origin link-click interceptor for as long as the app runs:
 
 ```typescript
 const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
@@ -50,9 +52,9 @@ void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 
 Both examples are runnable in full at [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) and [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr).
 
-## Recipe 3 — sharing layer memoization with `memoMap`
+## Recipe 3: sharing layer memoization with `memoMap`
 
-`WeftApp.make(layer, { memoMap })` accepts an explicit `Layer.MemoMap`, so multiple `WeftApp` instances can share layer construction — for example, building one app per test case while reusing an expensive shared dependency's memoized build across them:
+`WeftApp.make(layer, { memoMap })` accepts an explicit `Layer.MemoMap`, so multiple `WeftApp` instances can share layer construction. For example, build one app per test case while reusing an expensive shared dependency's memoized build across them:
 
 ```typescript
 import { WeftApp } from "@weftui/dom/client";
@@ -66,9 +68,9 @@ const appB = WeftApp.make(SharedLive, { memoMap });
 
 Most apps have exactly one `WeftApp` and never need this option.
 
-## Recipe 4 — binding an app's lifetime to a scope
+## Recipe 4: binding an app's lifetime to a scope
 
-There is deliberately no `makeScoped`. To tie an app's disposal to a `Scope` you already manage — a framework integration or a test harness that owns one — compose it yourself with `Effect.acquireRelease`:
+There is deliberately no `makeScoped`. To tie an app's disposal to a `Scope` you already manage (a framework integration or a test harness that owns one), compose it yourself with `Effect.acquireRelease`:
 
 ```typescript
 import { Effect } from "effect";
@@ -81,22 +83,22 @@ 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).
+`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).
 
 ## Anti-pattern: `Effect.provide` around the mount call
 
 ```typescript
 // ❌ does nothing useful: WeftApp.mount's R is always `never`, and services
-// come exclusively from the app layer — a wrapped Effect.provide never
+// come exclusively from the app layer: a wrapped Effect.provide never
 // reaches components, handlers, or stream subscriptions
 Effect.runPromise(pipe(WeftApp.mount(app, App(), root), Effect.provide(SomeLayer)));
 ```
 
-`WeftApp.mount`/`WeftApp.hydrate` return an effect whose requirement channel is always `never` — there is no `R` left for `Effect.provide` to discharge. Any service a component needs must be in the layer passed to `WeftApp.make`.
+`WeftApp.mount`/`WeftApp.hydrate` return an effect whose requirement channel is always `never`, so there is no `R` left for `Effect.provide` to discharge. Any service a component needs must be in the layer passed to `WeftApp.make`.
 
 ## See also
 
-- [Services and Context](https://weftui.dev/docs/explanation/services-and-context) — how `R` accumulates and discharges at `WeftApp.make`, and why scoped layers no longer need special handling
-- [`WeftApp` reference](https://weftui.dev/docs/reference/dom) — full signatures for `make`, `mount`, `hydrate`, `dispose`
-- [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) — a real scoped layer (`AtomRegistry.layer`)
-- [examples/shared-state-islands](https://github.com/stefvw93/weft/tree/main/examples/shared-state-islands) — one app layer shared by reference across multiple mounted roots
+- [Services and Context](https://weftui.dev/docs/explanation/services-and-context): how `R` accumulates and discharges at `WeftApp.make`, and why scoped layers no longer need special handling
+- [`WeftApp` reference](https://weftui.dev/docs/reference/dom): full signatures for `make`, `mount`, `hydrate`, `dispose`
+- [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom): a real scoped layer (`AtomRegistry.layer`)
+- [examples/shared-state-islands](https://github.com/stefvw93/weft/tree/main/examples/shared-state-islands): one app layer shared by reference across multiple mounted roots

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

@@ -9,36 +9,38 @@ description: Render a reactive collection with List.each so reordering, insertin
 
 **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.
+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.
 
 ```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`** — 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).
+- **`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).
 
 ## Why not `map`?
 
-Mapping items by hand — `Stream.map(rows.changes, (rs) => rs.map(r => h.li(r.name)))` — produces a **new children array on every emission**, so the renderer rebuilds the whole region: every row's DOM node is recreated even if only one item moved. `List.each` reconciles by key instead, so DOM identity (and the focus/scroll/typed-input state attached to it) survives across updates.
+Mapping items by hand (`Stream.map(Subscribable.changes(rows), (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.
+
+`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:
+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:
 
 ```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)])]),
 );
 ```
 
@@ -46,6 +48,6 @@ List.each({ of: rows.changes, by: (row) => row.id }, (row) =>
 
 ## See also
 
-- [`List.each` API reference](https://weftui.dev/docs/reference/core#listeach) — full signature, `List.Options`, and the descriptor shape
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the stream-shaped sources `of` accepts
-- [examples/keyed-list](https://github.com/stefvw93/weft/tree/main/examples/keyed-list) — a runnable keyed list with reordering and a browser test
+- [`List.each` API reference](https://weftui.dev/docs/reference/core#listeach): full signature, `List.Options`, and the descriptor shape
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the stream-shaped sources `of` accepts
+- [examples/keyed-list](https://github.com/stefvw93/weft/tree/main/examples/keyed-list): a runnable keyed list with reordering and a browser test

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

@@ -7,12 +7,14 @@ 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. [`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, replay it on the client without a second request, and then keep the region live for refetch.
+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.
+
+[`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 additionally 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.
+- **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
@@ -34,7 +36,7 @@ const app = WeftApp.make();
 void Effect.runPromise(WeftApp.hydrate(app, App(), root));
 ```
 
-The same side-effect-free `App` is imported by both entries — splice the server HTML into your template's outlet, ship it, and let the client entry hydrate it.
+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.
 
 `@weftui/dom/server` exports four renderers:
 
@@ -47,10 +49,12 @@ Use a hydratable renderer whenever the client will call `hydrate`. The plain ren
 
 ## Loading server data with `Boundary.rpc`
 
-SSR's natural companion is `Boundary.rpc`: it resolves an rpc **on the server**, serializes the result into the same HTML this page produces, and replays it on the client during `hydrate` — no second request, no fallback flash — then keeps the region live for `refetch`. It is the data half of the same server/client split described above: the rpc **contract** (pure Schema) is shared, while its **handler** lives in a server-only Layer the client never imports.
+`Boundary.rpc` resolves an rpc **on the server**, serializes the result into the same HTML this page produces, and replays it on the client during `hydrate`. There is no second request and no fallback flash, and the region stays live for `refetch`.
+
+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";
 
@@ -61,27 +65,27 @@ 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
   );
 ```
 
-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 — the contract/handler split, router wiring, the four lifecycles, the `Resource` handle, and typed-failure replay — lives in one place: the [RPC Data Boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc). This page does not repeat it.
+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).
 
 ## When to use
 
-- **`Boundary.rpc`** — data that must be resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML, then **refreshable** on the client (refetch / client-first SPA mount) over the same rpc.
-- **`Boundary.suspend`** — async data that loads on the client (or streams the shell then fills); see the [Boundary API](https://weftui.dev/docs/reference/core#boundarysuspend).
+- **`Boundary.rpc`**: data that must be resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML, then **refreshable** on the client (refetch / client-first SPA mount) over the same rpc.
+- **`Boundary.suspend`**: async data that loads on the client (or streams the shell then fills); see the [Boundary API](https://weftui.dev/docs/reference/core#boundarysuspend).
 
 ## See also
 
-- [rpc data boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc) — the full `Boundary.rpc` walkthrough: contract/handler split, router wiring, the four lifecycles, and typed-failure replay
-- [Routing](https://weftui.dev/docs/how-to/add-routing) — `@weftui/router` builds on this SSR + hydration model for full-page nested routing
+- [rpc data boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc): the full `Boundary.rpc` walkthrough, covering the contract/handler split, router wiring, the four lifecycles, and typed-failure replay
+- [Routing](https://weftui.dev/docs/how-to/add-routing): `@weftui/router` builds on this SSR + hydration model for full-page nested routing
 - [`Boundary.rpc` API reference](https://weftui.dev/docs/reference/core#boundaryrpc)
 - [`ServerTag` API reference](https://weftui.dev/docs/reference/core#servertag)
-- [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`
-- [examples/ssr-hydration](https://github.com/stefvw93/weft/tree/main/examples/ssr-hydration) — SSR + hydration without server data loading
+- [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`
+- [examples/ssr-hydration](https://github.com/stefvw93/weft/tree/main/examples/ssr-hydration): SSR + hydration without server data loading

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

@@ -9,10 +9,12 @@ description: Render a pending indicator (e.g. a top progress bar) during a defer
 
 **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.
 
-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 — _before_ swapping 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.
+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.
 
 ```typescript
-import { Component, h } from "@weftui/core";
+import { Component, h, Subscribable } from "@weftui/core";
 import { Router } from "@weftui/router";
 import { Stream } from "effect";
 
@@ -23,7 +25,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",
       ),
     }),
@@ -32,7 +34,7 @@ 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.
+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
 
@@ -44,22 +46,22 @@ 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.navigating`: the `Subscribable<NavState>` on the `Router` service.
+- `Router.navigatingStream`: an `Effect` resolving that `Subscribable`, for use in a `Component.gen` body (as above).
 
 The `to` field on `Navigating` is the target URL, if you want to label _where_ the app is going.
 
 ## Behavior to expect
 
-- **Only navigations with real async work flip it.** A branch with no `Router.lazy` node and a leaf whose effect resolves synchronously (no async work, or a memoized revisit) commits in the same tick, and `navigating` stays `Idle` — an entirely eager app never sees `Navigating`, and adding the reader costs nothing.
+- **Only navigations with real async work flip it.** A branch with no `Router.lazy` node and a leaf whose effect resolves synchronously (no async work, or a memoized revisit) commits in the same tick, and `navigating` stays `Idle`. An entirely eager app never sees `Navigating`, and adding the reader costs nothing.
 - **Latest-wins.** Rapid successive navigations commit only the newest; a superseded navigation never resets the signal (the newer one owns it).
 - **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. 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.
 
 ## See also
 
 - [`Router.navigating` API reference](https://weftui.dev/docs/reference/router#routernavigating)
-- [Split Routes Lazily](https://weftui.dev/docs/how-to/split-routes-lazily) — the `Router.lazy` deferred-commit navigation this reports on
-- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — wires this exact progress bar in its `Shell` (`components/shell.ts`), with a `pending-navigation.browser.test.ts`
+- [Split Routes Lazily](https://weftui.dev/docs/how-to/split-routes-lazily): the `Router.lazy` deferred-commit navigation this reports on
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr): wires this exact progress bar in its `Shell` (`components/shell.ts`), with a `pending-navigation.browser.test.ts`

package/docs/how-to/split-routes-lazily.md

@@ -9,7 +9,7 @@ description: Code-split a route's component into its own chunk with Router.lazy,
 
 **Goal:** keep a heavy page's render code (and its dependencies) out of the initial bundle, loading it only when its route is actually rendered.
 
-Wrap the route's `component` in [`Router.lazy`](https://weftui.dev/docs/reference/router#routerlazy). The route **descriptor** (its segment and param schemas) stays eager so the matcher, `href`, and the server's dispatch API still see it statically — only the component body is split into its own chunk.
+Wrap the route's `component` in [`Router.lazy`](https://weftui.dev/docs/reference/router#routerlazy). The route **descriptor** (its segment and param schemas) stays eager, so the matcher, `href`, and the server's dispatch API still see it statically. Only the component body is split into its own chunk.
 
 ```typescript
 import { Router } from "@weftui/router";
@@ -21,42 +21,44 @@ Router.route("docs/:category/:slug", {
 });
 ```
 
-The chunk loads on the server during render and on the client on navigation; only the **matched branch's** chunks are ever fetched. `E`/`R` are preserved — a lazy route has the exact same channels as the same component declared eagerly, so an unmet service requirement is still a compile error at `Router.router(...)`.
+The chunk loads on the server during render and on the client on navigation. Only the **matched branch's** chunks are ever fetched.
+
+`E`/`R` are preserved: a lazy route has the exact same channels as the same component declared eagerly. An unmet service requirement is still a compile error at `Router.router(...)`.
 
 ## Make the split real
 
-`Router.lazy` only splits if the dynamic `import()` is the **only eager path** to the heavy module. Keep the `Router.route(…)` descriptor in an eagerly-imported file, and move the component implementation (and its heavy deps) into a separate module referenced _only_ through `Router.lazy(() => import("./impl"))`:
+`Router.lazy` only splits if the dynamic `import()` is the **only eager path** to the heavy module. Keep the `Router.route(…)` descriptor in an eagerly-imported file. Move the component implementation (and its heavy deps) into a separate module referenced _only_ through `Router.lazy(() => import("./impl"))`:
 
 ```typescript
-// routes.ts — eager, tiny: just the descriptor
+// routes.ts: eager and tiny, just the descriptor
 export const docsRoute = Router.route("docs/:category/:slug", {
   path: { category: Schema.String, slug: Schema.String },
   component: Router.lazy(() => import("./doc-page-impl").then((m) => m.DocsPage)),
 });
 
-// doc-page-impl.ts — heavy: pulled into its own chunk, never in the initial graph
+// doc-page-impl.ts: heavy, pulled into its own chunk, never in the initial graph
 export const DocsPage = Component.gen(function* () {
   /* renderHast, code highlighting, … */
 });
 ```
 
-A descriptor file that still `import`s the impl statically gains nothing — the bundler keeps it in the initial graph.
+A descriptor file that still `import`s the impl statically gains nothing: the bundler keeps it in the initial graph.
 
 ## What you get for free
 
-- **Flash-free hydration.** On a directly-loaded lazy route, the client re-invokes the same slot, awaits the chunk, and adopts the server DOM in place — the first production matches, so nothing is mutated.
-- **Blank-free navigation.** Client navigation is **deferred-commit**: the router resolves the target branch's chunk **and the matched leaf's own component effect** _before_ committing the URL, so the previous page stays mounted through both the fetch and any data the leaf awaits, and the swap is a single tick. See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for the `Router.navigating` signal this exposes.
+- **Flash-free hydration.** On a directly-loaded lazy route, the client re-invokes the same slot, awaits the chunk, and adopts the server DOM in place. The first production matches, so nothing is mutated.
+- **Blank-free navigation.** Client navigation is **deferred-commit**: the router resolves the target branch's chunk **and the matched leaf's own component effect** _before_ committing the URL. The previous page stays mounted through the fetch and any data the leaf awaits, and the swap is a single tick. See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for the `Router.navigating` signal this exposes.
 - **Synchronous revisits.** `Router.lazy` memoizes its load per slot, so a second visit to a loaded route commits immediately.
 
 ## Edge cases
 
-- **Lazy layouts.** A `Router.layout({ component: Router.lazy(...) })` splits too — each lazy node in the matched branch is awaited; nodes outside it never load.
-- **Chunk-load failure is a defect.** If the `import()` rejects (offline, or a stale client requesting a chunk a new deploy removed), it dies as a defect and surfaces through normal defect handling — it never hangs or silently 404s. The rejection is memoized, so the route keeps failing until a reload (the deploy-skew case).
-- **Not a lazy _subtree_.** Only the component is lazy; you cannot defer a whole `RouteNode` behind an `import()`, because the matcher needs every leaf's segment and param schema before anything loads.
+- **Lazy layouts.** A `Router.layout({ component: Router.lazy(...) })` splits too. Each lazy node in the matched branch is awaited; nodes outside it never load.
+- **Chunk-load failure is a defect.** If the `import()` rejects (offline, or a stale client requesting a chunk a new deploy removed), it dies as a defect and surfaces through normal defect handling. It never hangs or silently 404s. The rejection is memoized, so the route keeps failing until a reload (the deploy-skew case).
+- **Not a lazy _subtree_.** Only the component is lazy. You cannot defer a whole `RouteNode` behind an `import()`; the matcher needs every leaf's segment and param schema before anything loads.
 
 ## See also
 
 - [`Router.lazy` API reference](https://weftui.dev/docs/reference/router#routerlazy)
-- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) — the deferred-commit `Router.navigating` signal
-- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — authoring the route tree `Router.lazy` plugs into
-- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — includes a `Router.lazy` page (`lazy-page.ts`) with a browser test
+- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress): the deferred-commit `Router.navigating` signal
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing): authoring the route tree `Router.lazy` plugs into
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr): includes a `Router.lazy` page (`lazy-page.ts`) with a browser test

package/docs/how-to/style-reactively.md

@@ -2,14 +2,14 @@
 title: Style Reactively
 order: 10
 section: how-to
-description: Drive inline styles from streams — a single property, or a whole style object — so the DOM updates in place with CSS transitions.
+description: Drive inline styles from streams (a single property, or a whole style object) so the DOM updates in place with CSS transitions.
 ---
 
 # Style Reactively
 
-**Goal:** animate or react to state in an element's inline style without re-rendering — a single CSS property, or a whole style object, driven by a stream.
+**Goal:** animate or react to state in an element's inline style without re-rendering. Drive a single CSS property, or a whole style object, from a stream.
 
-The `style` prop accepts the [`Source`](https://weftui.dev/docs/explanation/reactive-primitives) vocabulary at any level: a property value can be a stream, and you can spread a stream of style objects. CSS `transition` composes naturally, because the renderer mutates the existing node in place.
+The `style` prop accepts the [`Source`](https://weftui.dev/docs/explanation/reactive-primitives) vocabulary at any level. A property value can be a stream, and you can spread a stream of style objects. CSS `transition` composes naturally, because the renderer mutates the existing node in place.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -36,9 +36,9 @@ const AnimatedHue = () => {
 
 ## Three modes
 
-1. **A single property as a stream** — as above: one key's value is a `Stream`, the others are static strings. Each stream property is subscribed independently.
-2. **A static object** — an ordinary `style: { backgroundColor: "#667eea" }` with no streams; nothing updates.
-3. **A whole style object as a stream** — spread a stream that emits complete style objects, merged with static props:
+1. **A single property as a stream.** As above: one key's value is a `Stream`, the others are static strings. Each stream property is subscribed independently.
+2. **A static object.** An ordinary `style: { backgroundColor: "#667eea" }` with no streams; nothing updates.
+3. **A whole style object as a stream.** Spread a stream that emits complete style objects, merged with static props:
 
 ```typescript
 const pulse = Stream.make(1, 0.5).pipe(
@@ -49,15 +49,15 @@ const pulse = Stream.make(1, 0.5).pipe(
 h.div({ style: { ...pulse, transition: "opacity 0.4s ease-in-out" } }, "Pulse");
 ```
 
-Each emitted object is merged with the static properties on the element.
-
 ## Notes
 
-- **Property names are camelCase** (`backgroundColor`, `boxShadow`) — the same keys as the DOM `style` object.
-- **CSS transitions just work.** Because a stream emission patches the DOM node directly (no re-render), the browser applies the `transition` as it would for any style mutation.
-- **Pace with `Schedule`.** `Stream.iterate`/`Stream.make` paced by `Stream.schedule(Schedule.spaced(…))` and looped with `Stream.forever` is the idiom for time-based style animation; combine with any Effect timing you like.
+- **Property names are camelCase** (`backgroundColor`, `boxShadow`), the same keys as the DOM `style` object.
+- **CSS transitions just work.** A stream emission patches the DOM node directly (no re-render), so the browser applies the `transition` as it would for any style mutation.
+- **Pace with `Schedule`.** The idiom for time-based style animation: `Stream.iterate`/`Stream.make` paced by `Stream.schedule(Schedule.spaced(…))` and looped with `Stream.forever`. Combine with any Effect timing you like.
+- **Classes have a reactive builder too.** `Props.cx` builds a class string from strings, falsy values, nested arrays, and `{ className: condition }` records, where a condition may be a stream. Merging two bags that both carry `class` concatenates them. See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup).
 
 ## See also
 
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — reactive style props and the `Source` vocabulary
-- [examples/reactive-styles](https://github.com/stefvw93/weft/tree/main/examples/reactive-styles) — per-property and whole-object stream styles with CSS transitions
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): reactive style props and the `Source` vocabulary
+- [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup): `Props.cx` and merging `class` across two prop bags
+- [examples/reactive-styles](https://github.com/stefvw93/weft/tree/main/examples/reactive-styles): per-property and whole-object stream styles with CSS transitions

package/docs/how-to/use-element-refs.md

@@ -7,9 +7,9 @@ description: Capture a DOM element with the ref prop into a SubscriptionRef<Opti
 
 # Use Element Refs
 
-**Goal:** get a handle to a real DOM element — to focus it, measure it, or call an imperative browser API on it.
+**Goal:** get a handle to a real DOM element, to focus it, measure it, or call an imperative browser API on it.
 
-Declare a `SubscriptionRef<Option<HTMLElement>>`, attach it with the `ref` prop, and either **react** to the element appearing (a scoped observer on `SubscriptionRef.changes(ref)`) or **read** it later inside a handler.
+Declare a `SubscriptionRef<Option<HTMLElement>>` and attach it with the `ref` prop. Then either **react** to the element appearing (a scoped observer on `SubscriptionRef.changes(ref)`) or **read** it later inside a handler.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -34,9 +34,9 @@ const AutoFocusInput = () =>
 
 ## How it works
 
-- **The `ref` prop** takes a `SubscriptionRef<Option<T>>`. The renderer sets it to `Option.some(element)` **once**, when the element is created — so the ref is an `Option`: `None` until mount, `Some(el)` after.
-- **React to mount** by observing `SubscriptionRef.changes(ref)`: `Stream.filter(Option.isSome)` waits for the element, `Stream.take(1)` takes just the first appearance, and `Stream.runForEach` does the imperative work. This is the equivalent of a mount effect.
-- **Use `Effect.forkScoped`, not `Effect.forkChild`.** `forkScoped` ties the observer fiber to the component's **instance scope** (the ambient `Scope` the renderer provides), so it lives as long as the component is mounted. A bare `Effect.forkChild` binds to the transient component-body fiber and is interrupted the instant the generator returns — the observer would never fire.
+- **The `ref` prop** takes a `SubscriptionRef<Option<T>>`. The renderer sets it to `Option.some(element)` **once**, when the element is created. The ref is therefore an `Option`: `None` until mount, `Some(el)` after.
+- **React to mount** by observing `SubscriptionRef.changes(ref)`. `Stream.filter(Option.isSome)` waits for the element, `Stream.take(1)` takes just the first appearance, and `Stream.runForEach` does the imperative work. This is the equivalent of a mount effect.
+- **Use `Effect.forkScoped`, not `Effect.forkChild`.** `forkScoped` ties the observer fiber to the component's **instance scope** (the ambient `Scope` the renderer provides). It lives as long as the component is mounted. A bare `Effect.forkChild` binds to the transient component-body fiber and is interrupted the instant the generator returns, so the observer would never fire.
 
 ## Read a ref imperatively
 
@@ -54,10 +54,12 @@ const scroll = () =>
 
 - A plain `Ref` suffices if you **only** read the element imperatively; use `SubscriptionRef` when you need to **react** to it becoming available.
 - Refs are set once at element creation and are not cleared on unmount.
+- **Several refs can share one element.** `ref` also accepts an array, and every entry receives the element: `h.div({ ref: [measure, focus] })`. `Props.merge` produces such an array when both bags carry a `ref`, so a shared behavior's ref and your own can coexist. See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup).
 - Coming from React: `SubscriptionRef.make<Option<T>>(Option.none())` ↔ `useRef<T>(null)`; the `Stream.filter(Option.isSome)` observer ↔ a `useEffect` mount guard.
 
 ## See also
 
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `SubscriptionRef` and `SubscriptionRef.changes`
-- [Author Components](https://weftui.dev/docs/how-to/author-components) — instance scope and `Effect.forkScoped`
-- [examples/element-ref](https://github.com/stefvw93/weft/tree/main/examples/element-ref) — auto-focus, element measurement, and imperative scroll via refs
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): `SubscriptionRef` and `SubscriptionRef.changes`
+- [Author Components](https://weftui.dev/docs/how-to/author-components): instance scope and `Effect.forkScoped`
+- [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup): merging a shared behavior's `ref` with your own
+- [examples/element-ref](https://github.com/stefvw93/weft/tree/main/examples/element-ref): auto-focus, element measurement, and imperative scroll via refs

package/docs/index.md

@@ -2,40 +2,42 @@
 
 **Reactive UI, woven from Effect.**
 
-Weft is an Effect-native reactive DOM library — in the browser and on the server. `Node<E, R>` is `Effect.Effect<ElementDescriptor, E, R>`: every element is an Effect, so error and requirement channels accumulate through the tree, all Effect combinators apply to nodes directly, and services flow from mount through the whole app. Streams drive every update — there is no virtual DOM — and the same tree renders to HTML on the server and `hydrate()`s in place on the client, flash-free. No JSX.
+Weft is an Effect-native reactive DOM library, in the browser and on the server. `Node<E, R>` is `Effect.Effect<ElementDescriptor, E, R>`: every element is an Effect. Error and requirement channels accumulate through the tree, all Effect combinators apply to nodes directly, and services flow from mount through the whole app.
+
+Streams drive every update; there is no virtual DOM. The same tree renders to HTML on the server and `hydrate()`s in place on the client, flash-free. No JSX.
 
 The docs follow the [Diátaxis](https://diataxis.fr) model. Pick your entry point by what you are trying to do:
 
 ## Start here
 
-**[→ Tutorial](https://weftui.dev/docs/tutorial/01-your-first-app)** — a four-step guided path from a static component to a server-rendered, error-handled app. Start here if you are new to Weft:
+**[→ Tutorial](https://weftui.dev/docs/tutorial/01-your-first-app)**: a four-step guided path from a static component to a server-rendered, error-handled app. Start here if you are new to Weft:
 
-1. [Your First App](https://weftui.dev/docs/tutorial/01-your-first-app) — `h` and `WeftApp`
-2. [Reactivity](https://weftui.dev/docs/tutorial/02-reactivity) — `SubscriptionRef` and streams
-3. [Services and Async](https://weftui.dev/docs/tutorial/03-services-and-async) — handlers, services, async loading
-4. [Errors and Server Rendering](https://weftui.dev/docs/tutorial/04-errors-and-server) — boundaries and SSR
+1. [Your First App](https://weftui.dev/docs/tutorial/01-your-first-app): `h` and `WeftApp`
+2. [Reactivity](https://weftui.dev/docs/tutorial/02-reactivity): `SubscriptionRef` and streams
+3. [Services and Async](https://weftui.dev/docs/tutorial/03-services-and-async): handlers, services, async loading
+4. [Errors and Server Rendering](https://weftui.dev/docs/tutorial/04-errors-and-server): boundaries and SSR
 
 ## The four quadrants
 
-|                                                   |                                                                                                                                                                                     |
-| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **[Tutorial](https://weftui.dev/docs/tutorial/01-your-first-app)**     | Learning-oriented. One guided path, start to finish.                                                                                                                                |
-| **[How-to guides](https://weftui.dev/docs/how-to/author-components)**  | Task-oriented. Author components, render on the server, load data with rpc, add routing — plus recipes for forms, async data, keyed lists, reactive styles, refs, and lazy routing. |
-| **[Explanation](https://weftui.dev/docs/explanation/rendering-model)** | Understanding-oriented. The rendering model, the combinator API, reactive primitives, boundaries, and services & context.                                                           |
-| **[Reference](https://weftui.dev/docs/reference/core)**                | Information-oriented. Full API: [`@weftui/core`](https://weftui.dev/docs/reference/core), [`@weftui/dom`](https://weftui.dev/docs/reference/dom), [`@weftui/router`](https://weftui.dev/docs/reference/router).                                    |
+|                                                   |                                                                                                                                                                                    |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Tutorial](https://weftui.dev/docs/tutorial/01-your-first-app)**     | Learning-oriented. One guided path, start to finish.                                                                                                                               |
+| **[How-to guides](https://weftui.dev/docs/how-to/author-components)**  | Task-oriented. Author components, render on the server, load data with rpc, add routing. Plus recipes for forms, async data, keyed lists, reactive styles, refs, and lazy routing. |
+| **[Explanation](https://weftui.dev/docs/explanation/rendering-model)** | Understanding-oriented. The rendering model, the combinator API, reactive primitives, boundaries, and services & context.                                                          |
+| **[Reference](https://weftui.dev/docs/reference/core)**                | Information-oriented. Full API: [`@weftui/core`](https://weftui.dev/docs/reference/core), [`@weftui/dom`](https://weftui.dev/docs/reference/dom), [`@weftui/router`](https://weftui.dev/docs/reference/router).                                   |
 
-New to the model itself? Read [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why there is no virtual DOM, and what "streams are the weft" means.
+New to the model itself? Read [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): why there is no virtual DOM, and what "streams are the weft" means.
 
 ## Packages
 
 Three published packages make up Weft's public API, plus one build-time plugin:
 
-- **`@weftui/core`** — element builders (`h`), components, sources/streams, and boundaries. Start here.
-- **`@weftui/dom`** — the renderer: `./client` (`WeftApp.mount`/`WeftApp.hydrate`) and `./server` (`renderToString*`).
-- **`@weftui/router`** — universal nested routing, `Router.lazy`, and the rpc seam.
-- **`@weftui/vite`** — a build-time Vite plugin (tooling, not a runtime API).
+- **`@weftui/core`**: element builders (`h`), components, sources/streams, and boundaries. Start here.
+- **`@weftui/dom`**: the renderer, with `./client` (`WeftApp.mount`/`WeftApp.hydrate`) and `./server` (`renderToString*`) entry points.
+- **`@weftui/router`**: universal nested routing, `Router.lazy`, and the rpc seam.
+- **`@weftui/vite`**: a build-time Vite plugin (tooling, not a runtime API).
 
-`@weftui/base` is an internal, currently-empty stub — it has no public primitives; ignore it.
+`@weftui/base` is an internal, currently-empty stub with no public primitives. Ignore it.
 
 ## Examples