@weftui/dom 0.26.0 → 0.26.2

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

@@ -0,0 +1,124 @@
+---
+title: Provide Services
+order: 12
+section: how-to
+description: Provide plain and scoped Layers to a mounted app — the direct mount for value layers, mountScoped plus a shutdown signal for scoped layers, and a ManagedRuntime as an alternative.
+---
+
+# Provide Services
+
+**Goal:** provide a `Layer` to the mounted app so its components can read services with `yield* Service`.
+
+Which recipe to reach for depends on whether the layer has anything to release. A plain value layer (`Layer.succeed`, `Layer.effect` with no `acquireRelease`) can be provided directly at the mount — there is nothing to leak. A **scoped** layer (`Layer.scoped`, anything backed by `acquireRelease`) needs the mount to outlive the effect's own resolution — see [Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) for why.
+
+## Recipe 1 — plain value layers with `mount`
+
+Provide the layer directly around `mount` and run with `runPromise`. This is the common case and needs nothing else.
+
+```typescript
+import { mount } from "@weftui/dom/client";
+import { Effect, pipe } from "effect";
+import { App } from "./app";
+import { ThemeServiceLive } from "./theme-service";
+
+const root = document.getElementById("root")!;
+
+const program = pipe(mount(App(), root), Effect.provide(ThemeServiceLive));
+
+Effect.runPromise(program);
+```
+
+## Recipe 2 — scoped layers with `mountScoped`
+
+Provide the scoped layer **outside** a long-lived scoped region, mount inside that region with `mountScoped`, and keep the region open with `Effect.never` or `Deferred.await` on a shutdown signal. Drive the whole thing with `runFork`, not `runPromise` — the program never settles on its own.
+
+```typescript
+import { mountScoped } from "@weftui/dom/client";
+import { Deferred, Effect, Fiber, pipe } from "effect";
+import { App } from "./app";
+import { AppLive } from "./app-live";
+
+const root = document.getElementById("root")!;
+
+const program = pipe(
+  Effect.scoped(
+    Effect.gen(function* () {
+      yield* mountScoped(App(), root);
+      yield* Effect.never; // keeps the region — and AppLive — alive
+    }),
+  ),
+  Effect.provide(AppLive), // OUTSIDE the scoped region: outlives initial render
+);
+
+const fiber = Effect.runFork(program);
+
+// later, e.g. on a "sign out" action or test teardown:
+// await Effect.runPromise(Fiber.interrupt(fiber));
+```
+
+Interrupting `fiber` closes the inner scope first — running `mountScoped`'s finalizer, which calls `unmount` — and only then releases `AppLive`. Swap `Effect.never` for `Deferred.await(shutdown)` when something in the app should be able to request shutdown itself:
+
+```typescript
+const shutdown = await Effect.runPromise(Deferred.make<void>());
+
+const program = pipe(
+  Effect.scoped(
+    Effect.gen(function* () {
+      yield* mountScoped(App(), root);
+      yield* Deferred.await(shutdown); // resolves when shutdown is signalled
+    }),
+  ),
+  Effect.provide(AppLive),
+);
+Effect.runFork(program);
+
+// elsewhere, to request shutdown:
+// await Effect.runPromise(Deferred.succeed(shutdown, undefined));
+```
+
+`hydrateScoped` is the SSR counterpart — same composition, swap `mountScoped` for `hydrateScoped`.
+
+## Recipe 3 — `ManagedRuntime` with plain `mount`
+
+Build a `ManagedRuntime` from the scoped layer and mount with plain `mount`, running through the runtime instead of `Effect.runPromise` directly. The layer lives until `runtime.dispose()` — an explicit call, rather than a scope closing.
+
+```typescript
+import { mount } from "@weftui/dom/client";
+import { ManagedRuntime } from "effect";
+import { App } from "./app";
+import { AppLive } from "./app-live";
+
+const root = document.getElementById("root")!;
+const runtime = ManagedRuntime.make(AppLive);
+
+await runtime.runPromise(mount(App(), root));
+
+// later:
+// await runtime.dispose();
+```
+
+This reads closer to Recipe 1 at the call site and is a good fit when the surrounding app (a framework integration, a test harness) already manages a runtime's lifecycle for you.
+
+## Anti-patterns
+
+Both of these compile and both dispose the scoped layer while the app is still running — the mounted tree keeps its subscriptions and handlers, but they now read from a released service.
+
+```typescript
+// ❌ plain mount: the layer releases the instant runPromise settles
+Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
+```
+
+```typescript
+// ❌ mountScoped, but the scoped region closes as soon as the mount effect
+// resolves — nothing keeps it open, so this is no better than plain mount
+Effect.runPromise(mountScoped(App(), root).pipe(Effect.provide(SomeScopedLayer), Effect.scoped));
+```
+
+In both cases the tell is the same: nothing in the composition keeps a scope open past the point where the mount Effect itself resolves. Recipe 2's `Effect.never` (or `Deferred.await`) is doing the one piece of work these anti-patterns are missing.
+
+## See also
+
+- [Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) — why the mount effect resolving early matters for scoped layers
+- [Services and Context](https://weftui.dev/docs/explanation/services-and-context) — how `R` accumulates and discharges at the mount
+- [`mountScoped` / `hydrateScoped` reference](https://weftui.dev/docs/reference/dom#mountscoped) — signatures and error unions
+- [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) — a real scoped layer (`Registry.layer`) mounted with this composition

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

@@ -0,0 +1,51 @@
+---
+title: Render Keyed Lists
+order: 5
+section: how-to
+description: Render a reactive collection with List.each so reordering, inserting, and removing items reuses and moves existing DOM instead of rebuilding the region.
+---
+
+# 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.
+
+```typescript
+import { h, List } 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
+    (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).
+
+## 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.
+
+## 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:
+
+```typescript
+List.each({ of: rows.changes, by: (row) => row.id }, (row) =>
+  h.li([h.span([Stream.map(row.status.changes, (s) => s)])]),
+);
+```
+
+> **⚠️ Index-key footgun.** Keying by index (`by: (_, i) => i`) reuses rows positionally, so after a reorder each position keeps its old content and you see stale rows. Prefer a stable identity key (`by: (item) => item.id`).
+
+## 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

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

@@ -0,0 +1,86 @@
+---
+title: Server-Side Rendering
+order: 2
+section: how-to
+description: renderToString / renderToStringHydratable / streaming variants, hydrate, and the server/client split.
+---
+
+# 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.
+
+## 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 `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
+import { renderToStringHydratable } from "@weftui/dom/server";
+import { Effect } from "effect";
+import { App } from "./app";
+
+export const render = (): Promise<string> => Effect.runPromise(renderToStringHydratable(App()));
+```
+
+```typescript
+// client entry
+import { hydrate } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+
+const root = document.getElementById("root")!;
+void Effect.runPromise(hydrate(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.
+
+`@weftui/dom/server` exports four renderers:
+
+|                                        | String                     | Stream                     |
+| -------------------------------------- | -------------------------- | -------------------------- |
+| **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.
+
+## 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.
+
+```typescript
+import { Boundary, h } from "@weftui/core";
+import { Stream } from "effect";
+import { GetStock } from "./data/inventory";
+
+const StockPanel = (productId: number) =>
+  Boundary.rpc(
+    GetStock,
+    () => ({ id: productId }), // a fresh typed payload per call (SSR / refetch / mount)
+    (resource) =>
+      h.p([
+        "in stock: ",
+        h.span([Stream.map(resource.value.changes, (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.
+
+> **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).
+
+## 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
+- [`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

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

@@ -0,0 +1,65 @@
+---
+title: Show Navigation Progress
+order: 7
+section: how-to
+description: Render a pending indicator (e.g. a top progress bar) during a deferred-commit navigation by reading the router's Router.navigating signal.
+---
+
+# 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.
+
+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.
+
+```typescript
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { Stream } from "effect";
+
+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(nav.changes, (s) =>
+        s._tag === "Navigating" ? "nav-progress is-navigating" : "nav-progress",
+      ),
+    }),
+    h.main([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
+
+`NavState` is a two-state machine:
+
+```typescript
+type NavState = { readonly _tag: "Idle" } | { readonly _tag: "Navigating"; readonly to: string };
+```
+
+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).
+
+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.
+- **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.
+
+## 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`

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

@@ -0,0 +1,62 @@
+---
+title: Split Routes Lazily
+order: 6
+section: how-to
+description: Code-split a route's component into its own chunk with Router.lazy, keeping the descriptor eager so matching, href, and SSR stay unchanged.
+---
+
+# Split Routes Lazily
+
+**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.
+
+```typescript
+import { Router } from "@weftui/router";
+import { Schema } from "effect";
+
+Router.route("docs/:category/:slug", {
+  path: { category: Schema.String, slug: Schema.String },
+  component: Router.lazy(() => import("./doc-page").then((m) => m.DocPage)),
+});
+```
+
+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(...)`.
+
+## 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"))`:
+
+```typescript
+// routes.ts — eager, 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
+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.
+
+## 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.
+- **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.
+
+## 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

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

@@ -0,0 +1,63 @@
+---
+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.
+---
+
+# 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.
+
+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";
+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(
+    {
+      class: "demo-box",
+      style: {
+        // one property is reactive; the rest are static
+        backgroundColor: Stream.map(hue, (h) => `hsl(${h}, 70%, 60%)`),
+        transition: "background-color 0.05s",
+      },
+    },
+    "Hue",
+  );
+};
+```
+
+## 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:
+
+```typescript
+const pulse = Stream.make(1, 0.5).pipe(
+  Stream.schedule(Schedule.spaced("800 millis")),
+  Stream.forever,
+);
+
+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.
+
+## 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

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

@@ -0,0 +1,63 @@
+---
+title: Use Element Refs
+order: 11
+section: how-to
+description: Capture a DOM element with the ref prop into a SubscriptionRef<Option<HTMLElement>>, then react to its mount with a scoped observer or read it imperatively.
+---
+
+# 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.
+
+Declare a `SubscriptionRef<Option<HTMLElement>>`, attach it with the `ref` prop, and either **react** to the element appearing (a scoped observer on `.changes`) or **read** it later inside a handler.
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, Option, pipe, Stream, SubscriptionRef } from "effect";
+
+const AutoFocusInput = () =>
+  Effect.gen(function* () {
+    const inputRef = yield* SubscriptionRef.make<Option.Option<HTMLInputElement>>(Option.none());
+
+    // Observe the element becoming available, once, and focus it.
+    yield* pipe(
+      inputRef.changes,
+      Stream.filter(Option.isSome),
+      Stream.take(1),
+      Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
+      Effect.forkScoped, // ← ties the observer to the component's instance scope
+    );
+
+    return yield* h.input({ ref: inputRef, type: "text", placeholder: "I'm focused!" });
+  });
+```
+
+## 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 `ref.changes`: `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.fork`.** `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.fork` binds to the transient component-body fiber and is interrupted the instant the generator returns — the observer would never fire.
+
+## Read a ref imperatively
+
+When you only need the element later (e.g. in a click handler), skip the observer and read the ref on demand:
+
+```typescript
+const scroll = () =>
+  Effect.gen(function* () {
+    const el = yield* SubscriptionRef.get(targetRef);
+    if (Option.isSome(el)) el.value.scrollIntoView({ behavior: "smooth" });
+  });
+```
+
+## Notes
+
+- 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.
+- 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 `.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

package/docs/index.md

@@ -0,0 +1,59 @@
+# Weft Documentation
+
+**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.
+
+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:
+
+1. [Your First App](https://weftui.dev/docs/tutorial/01-your-first-app) — `h` and `mount`
+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).                                    |
+
+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` (`mount`/`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/base` is an internal, currently-empty stub — it has no public primitives; ignore it.
+
+## Examples
+
+The [`examples/`](https://github.com/stefvw93/weft/tree/main/examples) directory contains standalone runnable apps. Each covers a specific pattern and ships with a browser test:
+
+| Example                      | What it shows                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `async-data-loading`         | Loading states, retry, error boundaries with Stream and Effect                       |
+| `declarative-event-handlers` | Plain, Effect-returning, service-aware, and reactive handlers                        |
+| `element-ref`                | DOM refs with `SubscriptionRef<Option<HTMLElement>>`                                 |
+| `error-boundary`             | All six failure-catch `Boundary.*` variants                                          |
+| `form-handling`              | Reactive inputs, Schema validation, Effect submit handlers                           |
+| `keyed-list`                 | Keyed list rendering with `List.each`                                                |
+| `list-rendering`             | Static and stream-based lists, fragments, nested iterables                           |
+| `reactive-styles`            | Per-property and whole-object stream styles, CSS transitions                         |
+| `router-ssr`                 | Universal nested routing with SSR, hydration, layouts, `Boundary.rpc`, `Router.lazy` |
+| `server-boundary`            | `Boundary.rpc` client-first mount + refetch, router-less                             |
+| `ssr-hydration`              | SSR + hydration without server data loading                                          |
+| `subscription-ref`           | Local state, derived streams, coordinating multiple refs                             |
+| `suspense`                   | Suspense boundaries for streaming SSR and client coordination                        |
+| `type-augmentation`          | Typed custom elements on `h` via the `CustomElements` interface                      |