@weftui/router 0.30.0 → 0.31.0

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

@@ -7,11 +7,9 @@ description: Boundary.rpc, server-resolved and client-refreshable data; the cont
 
 # RPC Data Boundaries
 
-`Boundary.rpc` is Weft's primitive for **server-resolved, client-refreshable** data. One [`Rpc`](https://github.com/Effect-TS/effect/tree/main/packages/rpc) from the app's merged `RpcGroup` backs a single render boundary across four lifecycles: server-side render, hydrate-replay, client refetch, and client-first SPA mount. The rpc's `_tag` is the boundary's stable identity and its payload schema the typed input.
+`Boundary.rpc` is Weft's primitive for **server-resolved, client-refreshable** data. One [`Rpc`](https://github.com/Effect-TS/effect/tree/main/packages/rpc) from the app's merged `RpcGroup` backs a single render boundary across four lifecycles: server-side render, hydrate-replay, client refetch, and client-first SPA mount.
 
-## Overview
-
-A `Boundary.rpc` is a **thin consumer**. It carries an rpc, a payload thunk, and a `render` that receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea). The renderer resolves the rpc through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam (provided by `@weftui/router`). The same rpc serves every lifecycle, so SSR-replay, refetch, and client-first mount are one mechanism, not three.
+## Quick example
 
 ```typescript
 import { Boundary, h, Subscribable } from "@weftui/core";
@@ -33,9 +31,11 @@ Boundary.rpc(
 );
 ```
 
+`render` receives a reactive [`Resource`](https://weftui.dev/docs/reference/core#resourcea), resolved through the ambient [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam that `@weftui/router` provides. The same rpc serves every lifecycle, so SSR-replay, refetch, and client-first mount are one mechanism, not three.
+
 ## The contract / handler split
 
-The rpc **contract** (pure Schema) is shared with the client. The rpc **handler**, the only code that touches server-only services, lives in a Layer the client never imports. Tree-shaking keeps it and its transitive imports out of the browser bundle. The split is enforced structurally by which files each entry imports, not by a bundler plugin.
+The rpc **contract** (pure Schema) is shared with the client. The rpc **handler**, the only code that touches server-only services, lives in a Layer the client never imports. Tree-shaking keeps it and its transitive imports out of the browser bundle:
 
 ```typescript
 // data/inventory.ts
@@ -68,11 +68,11 @@ export const StockLive = StockRpcs.toLayer({
 }).pipe(Layer.provide(InventoryLive));
 ```
 
-Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Service`) when they might be referenced from universal code. The brand makes a leak into `render` a compile error at the `hydrate` call site rather than a runtime surprise.
+The split is enforced structurally by which files each entry imports, not by a bundler plugin. Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Service`) when they might be referenced from universal code: the brand makes a leak into `render` a compile error at the `hydrate` call site, rather than a runtime surprise.
 
 ## Wiring the router
 
-`Boundary.rpc` resolves through the ambient `AppRpcClientTag` seam, which `@weftui/router` provides on both sides. Pass the **merged group** to both, plus the **handler Layer** on the server.
+Pass the **merged group** to both sides, plus the **handler Layer** on the server:
 
 ```typescript
 // entry-server.ts: in-process client over the handlers + POST /_eui/rpc endpoint
@@ -100,7 +100,7 @@ void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 - **Server** ([`RouterServer`](https://weftui.dev/docs/reference/router#routerserver)) mounts the handler Layer at `POST /_eui/rpc`, so a client refetch re-runs it on the server. It also exposes an in-process client over the same handlers for SSR resolution, never a network hop.
 - **Client** ([`RouterLive`](https://weftui.dev/docs/reference/router#routerlive)) provides a network flat rpc client over the merged group, posting to `<origin>/_eui/rpc`.
 
-In a **router-less mount** there is no `AppRpcClientTag`, so a `Boundary.rpc` resolves to a typed, descriptive "needs router/rpc" error (not a defect).
+In a **router-less mount** there is no `AppRpcClientTag`, so a `Boundary.rpc` resolves to a typed, descriptive "needs router/rpc" error, not a defect.
 
 ## The four lifecycles
 
@@ -111,7 +111,13 @@ In a **router-less mount** there is no `AppRpcClientTag`, so a `Boundary.rpc` re
 | **Refetch**            | `resource.refetch`                      | Call the rpc again over `POST /_eui/rpc` (re-runs the handler on the server), patch the subtree in place (stale-on-error).                           |
 | **Client-first mount** | SPA nav into a boundary with no payload | Render `options.fallback`, fork the rpc call, swap in `render(resource)` once it resolves.                                                           |
 
-Because the SSR path seeds `value` await-first (it emits the seed immediately), the SSR HTML and the adopted DOM are byte-identical. There is **no fallback flash** on the SSR/hydrate path. `fallback` shows only on a client-first mount.
+Because the SSR path seeds `value` await-first, the SSR HTML and the adopted DOM are byte-identical. There is **no fallback flash** on the SSR/hydrate path; `fallback` renders only on a client-first mount:
+
+```typescript
+Boundary.rpc(GetStock, () => ({ id: product.id }), render, {
+  fallback: h.p("loading stock…"), // unused on SSR/hydrate; shown only client-first
+});
+```
 
 ## The `Resource` handle
 
@@ -133,7 +139,7 @@ Because the SSR path seeds `value` await-first (it emits the seed immediately),
   ]);
 ```
 
-Wire `refetch` to an event with `onclick: () => resource.refetch`. The handler returns the Effect, which the renderer runs in a detached fiber. A failed refetch leaves the previous `value` intact (stale-on-error); it does **not** unmount the subtree or raise into a failure `Boundary`.
+Wire `refetch` to an event with `onclick: () => resource.refetch`. The handler returns the Effect, which the renderer runs in a detached fiber. A failed refetch leaves the previous `value` intact (stale-on-error): it does **not** unmount the subtree or raise into a failure `Boundary`.
 
 ### Channel algebra
 
@@ -147,22 +153,169 @@ Boundary.rpc<R extends Rpc.Any, C extends Node<any, any>>(
 ```
 
 - **Error** = `render`'s error union plus the rpc's typed `Rpc.Error<R>` (`never` for an rpc with no `error` schema).
-- **Requirement** = exactly `render`'s `R`, **untouched**. There is no `provide`/`RServer` to discharge (the handler lives in the rpc Layer) and no `Exclude` is applied. A server-only tag leaked into `render` stays in `R`, where `hydrate`'s `AssertNoServerOnly` rejects it.
+- **Requirement** = exactly `render`'s `R`, **untouched**: there is no `provide`/`RServer` to discharge (the handler lives in the rpc Layer) and no `Exclude` is applied. A server-only tag leaked into `render` stays in `R`, where `hydrate`'s `AssertNoServerOnly` rejects it.
 
 ## Typed-failure replay
 
-If the rpc declares an `error` schema, a resolved rpc **error** on the SSR pass is `errorSchema`-encoded into an inline failure payload. The nearest enclosing **failure `Boundary`** renders its fallback.
+Give the rpc an `error` schema and a resolved rpc **error** on the SSR pass is `errorSchema`-encoded into an inline failure payload:
 
-On the client, `hydrate` decodes that payload and re-raises the same error into the same boundary. The identical fallback DOM is reproduced, flash-free and without re-resolving the rpc (replay, never retry).
+```typescript
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { Schema } from "effect";
+
+export class OutOfStock extends Schema.TaggedErrorClass<OutOfStock>()("OutOfStock", {
+  reason: Schema.String,
+}) {}
+
+export const GetStock = Rpc.make("GetStock", {
+  payload: StockKey,
+  success: Stock,
+  error: OutOfStock,
+});
+```
+
+The nearest enclosing **failure `Boundary`** renders its fallback. On the client, `hydrate` decodes that payload and re-raises the same error into the same boundary, reproducing the identical fallback DOM, flash-free and without re-resolving the rpc (replay, never retry):
 
 ```typescript
 Boundary.catchTag({ tag: "OutOfStock", fallback: (e) => h.p({ class: "error" }, e.reason) }, [
-  Boundary.rpc(GetStock, () => ({ id: product.id }), (resource) => /* … */),
+  Boundary.rpc(
+    GetStock,
+    () => ({ id: product.id }),
+    (resource) => h.p([Stream.map(Subscribable.changes(resource.value), (s) => String(s.units))]),
+  ),
 ]);
 ```
 
 A transport **defect** (no `Cause.findErrorOption`), or an rpc with no `error` schema, is **not** replayed; it propagates: a server-side fallback and a client mismatch.
 
+## Full example
+
+A `/products/:id` page with a refetchable live-stock `Boundary.rpc`, sealed into a single-route router app. This is the whole file set for the router + rpc parts (drop it alongside a dev server that bridges `entry-server.ts`'s `handler` into Vite or any Web-platform server; see [`examples/router-ssr/server.ts`](https://github.com/stefvw93/weft/blob/main/examples/router-ssr/server.ts) and its co-located [`vite.config.ts`](https://github.com/stefvw93/weft/blob/main/examples/router-ssr/vite.config.ts) for a working one).
+
+```typescript
+// src/data/inventory.ts
+/**
+ * The product's live stock: rpc contract + server-only handler. See "The
+ * contract / handler split" above for why this file is safe to import from
+ * both `app.ts` (contract only) and `entry-server.ts` (contract + handler).
+ */
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { Context, Effect, Layer, Schema } from "effect";
+
+export const Stock = Schema.Struct({ units: Schema.Number });
+export const StockKey = Schema.Struct({ id: Schema.Number });
+export const GetStock = Rpc.make("GetStock", { payload: StockKey, success: Stock });
+export const StockRpcs = RpcGroup.make(GetStock);
+
+class Inventory extends Context.Service<
+  Inventory,
+  { readonly stockFor: (id: number) => Effect.Effect<typeof Stock.Type> }
+>()("Inventory") {}
+
+const InventoryLive = Layer.succeed(Inventory, {
+  stockFor: (id) => Effect.succeed({ units: 7 + (id % 5) }),
+});
+
+export const StockLive = StockRpcs.toLayer({
+  GetStock: (payload) => Effect.flatMap(Inventory, (inv) => inv.stockFor(payload.id)),
+}).pipe(Layer.provide(InventoryLive));
+```
+
+```typescript
+// src/app.ts
+/**
+ * Shared, isomorphic router app: one `/products/:id` page with a refetchable
+ * live-stock `Boundary.rpc`. Side-effect-free (no mount/hydrate call), so
+ * both entries and any test can import `App` directly.
+ */
+import { Boundary, Component, h, Subscribable } from "@weftui/core";
+import { notFound, Router } from "@weftui/router";
+import { Schema, Stream } from "effect";
+import { GetStock } from "./data/inventory";
+
+const idParam = { id: Schema.NumberFromString };
+
+const productRoute = Router.route("products/:id", {
+  path: idParam,
+  component: ({ path }) => {
+    if (!Number.isFinite(path.id) || path.id < 0) return notFound();
+    return Boundary.rpc(
+      GetStock,
+      () => ({ id: path.id }),
+      (resource) =>
+        h.section({ id: "page" }, [
+          h.h2(`Product ${path.id}`),
+          h.p([
+            "in stock: ",
+            h.span([Stream.map(Subscribable.changes(resource.value), (s) => String(s.units))]),
+          ]),
+          h.button({ type: "button", onclick: () => resource.refetch }, "Refresh stock"),
+        ]),
+      { fallback: h.p("loading stock…") },
+    );
+  },
+});
+
+const Shell = Component.gen(function* () {
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ id: "app" }, [outlet]);
+});
+
+export const App = Router.router(Router.layout({ component: Shell }, [productRoute]), {
+  notFound: () => h.section({ id: "page" }, [h.h2("404: page not found")]),
+});
+```
+
+```typescript
+// src/entry-server.ts
+/**
+ * Server entry: renders the matched route to a hydratable HTML document,
+ * wiring the rpc's shared group and its server-only handler Layer.
+ */
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { RouterServer } from "@weftui/router/server";
+import { Effect } from "effect";
+import { App } from "./app";
+import { StockLive, StockRpcs } from "./data/inventory";
+
+const rpc = { group: StockRpcs, handlers: StockLive } as const;
+
+const documentShell = Component.gen(function* () {
+  const app = yield* Router.Outlet;
+  return yield* h.html({ lang: "en" }, [
+    h.head([h.meta({ charset: "utf-8" }), h.title("Weft shop")]),
+    h.body([
+      h.div({ id: "root" }, [app]),
+      h.script({ type: "module", src: "/src/entry-client.ts" }),
+    ]),
+  ]);
+});
+
+export const render = (url: string): Promise<{ html: string; status: number }> =>
+  Effect.runPromise(RouterServer.render(App, { document: documentShell, rpc, url }));
+
+export const handler = RouterServer.toWebHandler(App, { document: documentShell, rpc });
+```
+
+```typescript
+// src/entry-client.ts
+/**
+ * Client entry: hydrates the server-rendered markup in `#root`, wiring the
+ * rpc's shared group so `resource.refetch` posts to `/_eui/rpc`.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { Effect } from "effect";
+import { App } from "./app";
+import { StockRpcs } from "./data/inventory";
+
+const root = document.getElementById("root")!;
+
+const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
+```
+
 ## When to use
 
 - **`Boundary.rpc`**: data resolved on the server (behind a server-only service, credential, or private network) and rendered into the initial HTML. It stays **refreshable** on the client over the same rpc.

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

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

@@ -7,9 +7,7 @@ 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, Subscribable } from "@weftui/core";
@@ -25,18 +23,32 @@ h.ul([
 ]);
 ```
 
-- **`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
+
+```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
+}
+```
+
+- **`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).
 
-## Why not `map`?
+## Why not `map`
 
-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.
+```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)));
+```
 
-`List.each` reconciles by key instead, so DOM identity (and the focus/scroll/typed-input state attached to it) survives across updates.
+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: Subscribable.changes(rows), by: (row) => row.id }, (row) =>
@@ -44,7 +56,101 @@ List.each({ of: Subscribable.changes(rows), by: (row) => row.id }, (row) =>
 );
 ```
 
-> **⚠️ 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