@weftui/router 0.30.0 → 0.31.0

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

@@ -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`
 
@@ -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

@@ -7,11 +7,9 @@ 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, Subscribable } from "@weftui/core";
@@ -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
 

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):
 
 ```typescript
 import { Router } from "@weftui/router";
@@ -21,7 +21,7 @@ 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.
+The route's **descriptor** (segment, `path`/`query` 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, fetched on the server during render and on the client on navigation. Only the **matched branch's** chunks are ever loaded.
 
 `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(...)`.
 
@@ -48,14 +48,117 @@ A descriptor file that still `import`s the impl statically gains nothing: the bu
 
 - **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.
+- **Synchronous revisits.** `Router.lazy` memoizes its load per slot. The first render triggers the `import()`; every later render (including a revisit after navigating away) reuses the resolved module.
+
+```typescript
+// One slot, created once. Its loader Promise resolves on first render and is
+// reused on every later render, including back-navigation to this route.
+const page = Router.lazy(() => import("./doc-page").then((m) => m.DocPage));
+
+Router.route("docs/intro", { component: page });
+```
 
 ## 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.
+
+  ```typescript
+  Router.layout(
+    { component: Router.lazy(() => import("./admin-shell").then((m) => m.AdminShell)) },
+    [settingsRoute, usersRoute],
+  );
+  ```
+
 - **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.
 
+## Complete example
+
+A client-only app with two routes: `Home` (eager) and `Lazy` (split into its own chunk). 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 lazy routing demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```typescript
+// src/lazy-page.ts
+/**
+ * The lazily-loaded page body. Kept in its own module so the dynamic
+ * `import()` in `app.ts` is a real code-split point, not just a wrapper
+ * around a statically-imported value.
+ */
+import { Component, h } from "@weftui/core";
+
+export const LazyPage = Component.make(() =>
+  h.section({ id: "page" }, [h.h2("Lazy page"), h.p("Loaded on demand.")]),
+);
+```
+
+```typescript
+// src/app.ts
+/**
+ * Client-only lazy-routing demo: a Home route declared eagerly, and a Lazy
+ * route whose component is code-split via `Router.lazy`. Side-effect-free (no
+ * mount call), so `main.ts` and any test can import `App` directly.
+ */
+import { Component, h } from "@weftui/core";
+import { href, Router } from "@weftui/router";
+
+const homeRoute = Router.route("", {
+  component: Component.make(() => h.section({ id: "page" }, [h.h2("Home")])),
+});
+
+const lazyRoute = Router.route("lazy", {
+  component: Router.lazy(() => import("./lazy-page").then((m) => m.LazyPage)),
+});
+
+const Shell = Component.gen(function* () {
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ id: "app" }, [
+    h.nav([h.a({ href: href(homeRoute) }, "Home"), " · ", h.a({ href: href(lazyRoute) }, "Lazy")]),
+    h.main([outlet]),
+  ]);
+});
+
+export const App = Router.router(Router.layout({ component: Shell }, [homeRoute, lazyRoute]), {
+  notFound: () => h.section({ id: "page" }, [h.h2("404: page not found")]),
+});
+```
+
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the lazy-routing demo into `#root`. No server render
+ * to hydrate, so this uses `WeftApp.mount`, not `hydrate`.
+ */
+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));
+```
+
+Load `/`, open the network panel, then click "Lazy": `lazy-page`'s chunk fetches only on that click, not on initial load. Click "Home" then "Lazy" again and no second fetch fires: the slot's memo serves the resolved component.
+
 ## See also
 
 - [`Router.lazy` API reference](https://weftui.dev/docs/reference/router#routerlazy)

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

@@ -7,9 +7,9 @@ description: Drive inline styles from streams (a single property, or a whole sty
 
 # Style Reactively
 
-**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.
+**Goal:** animate or react to state in an element's inline style without re-rendering.
 
-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 either level: a single property's value, or the whole object. CSS `transition` composes naturally, because a stream emission patches the existing DOM node in place.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -34,27 +34,155 @@ const AnimatedHue = () => {
 };
 ```
 
-## Three modes
+## Per-property streams
 
-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:
+Give one or more keys a `Stream` value and leave the rest as plain strings. Each reactive key subscribes independently, so two properties can animate off unrelated sources on the same element:
 
 ```typescript
-const pulse = Stream.make(1, 0.5).pipe(
-  Stream.schedule(Schedule.spaced("800 millis")),
-  Stream.forever,
+const size = Stream.iterate(100, (s) => (s >= 150 ? 100 : s + 10)).pipe(
+  Stream.schedule(Schedule.spaced("200 millis")),
 );
 
-h.div({ style: { ...pulse, transition: "opacity 0.4s ease-in-out" } }, "Pulse");
+h.div({
+  style: {
+    width: Stream.map(size, (s) => `${s}px`),
+    height: Stream.map(size, (s) => `${s}px`),
+    transition: "width 0.2s, height 0.2s",
+  },
+});
+```
+
+A key without a stream stays static: an ordinary `style: { backgroundColor: "#667eea" }` never updates.
+
+## Whole-object streams
+
+Give `style` itself a `Stream` that emits complete style objects. Each emission replaces every property on the element, so it's the right shape for changes that move several properties together:
+
+```typescript
+const theme = Stream.make(
+  { backgroundColor: "#667eea", transform: "scale(1)" },
+  { backgroundColor: "#764ba2", transform: "scale(1.1)" },
+).pipe(Stream.schedule(Schedule.spaced("1 second")), Stream.forever);
+
+h.div({
+  // fold the static `transition` into every emitted object: the renderer
+  // clears and resets all style properties on each emission, so a sibling
+  // key can't survive alongside it. Spreading `theme` into a style object
+  // literal doesn't work either, since that copies the Stream's own fields,
+  // not the values it emits.
+  style: Stream.map(theme, (s) => ({ ...s, transition: "all 0.3s ease" })),
+});
+```
+
+## Reactive classes
+
+`Props.cx` (from `@weftui/dom`) builds a class string from static names and `{ className: condition }` records, where a condition may be a stream:
+
+```typescript
+import { h } from "@weftui/core";
+import { Props } from "@weftui/dom";
+
+h.div({ class: Props.cx("demo-box", { "demo-box--active": isActiveStream }) });
 ```
 
+See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup) for merging `class` across two prop bags.
+
 ## Notes
 
 - **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).
+- **CSS transitions just work.** A stream emission patches the DOM node directly (no re-render), so the browser applies `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:
+
+```typescript
+Stream.iterate(0, (n) => n + 1).pipe(
+  Stream.schedule(Schedule.spaced("100 millis")),
+  Stream.forever,
+);
+```
+
+Combine with any Effect timing you like.
+
+## Complete example
+
+A page with one per-property demo (hue cycling) and one whole-object demo (theme switch), mounted into an empty `#root`. This is the whole file set, copy/paste runnable in a `vite` + `@weftui/core` 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 reactive styles demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```typescript
+// src/app.ts
+/**
+ * Reactive styles demo: a per-property hue cycle and a whole-object theme
+ * switch. Side-effect-free (no mount call), so `main.ts` and any test can
+ * import `App` directly.
+ */
+import { h } from "@weftui/core";
+import { Schedule, Stream } from "effect";
+
+const AnimatedHue = () => {
+  const hue = Stream.iterate(0, (h) => (h + 2) % 360).pipe(
+    Stream.schedule(Schedule.spaced("50 millis")),
+  );
+
+  return h.div(
+    {
+      style: {
+        backgroundColor: Stream.map(hue, (h) => `hsl(${h}, 70%, 60%)`),
+        transition: "background-color 0.05s",
+        padding: "1rem",
+      },
+    },
+    "Hue",
+  );
+};
+
+const ThemeSwitch = () => {
+  const theme = Stream.make(
+    { backgroundColor: "#667eea", transform: "scale(1)" },
+    { backgroundColor: "#764ba2", transform: "scale(1.1)" },
+  ).pipe(Stream.schedule(Schedule.spaced("1 second")), Stream.forever);
+
+  return h.div(
+    {
+      style: Stream.map(theme, (s) => ({ ...s, transition: "all 0.3s ease", padding: "1rem" })),
+    },
+    "Theme",
+  );
+};
+
+export const App = () => h.div([AnimatedHue(), ThemeSwitch()]);
+```
+
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the reactive styles 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