@weftui/router 0.30.0 → 0.31.0

package/docs/explanation/boundaries-and-suspense.md

@@ -40,15 +40,28 @@ An unhandled failure re-raises to the **nearest enclosing** boundary; if none ca
 
 ### Post-mount failures with no enclosing boundary
 
-The routing above describes what happens while a node is being built. Once mounted, a reactive region (an attribute, child, or list stream, or a hydrated equivalent) keeps running for the lifetime of its scope. It can still fail later: a `Stream` backing a `Boundary.rpc` resource might raise `RouterNotFound` after a client-side navigation. If a `BoundaryContext` encloses the region, the failure routes to it exactly as above, and the boundary's fallback swaps in.
+The routing above describes what happens while a node is being built. Once mounted, a reactive region keeps running for the lifetime of its scope: an attribute, a child, a list stream, or a hydrated equivalent. It can still fail later, e.g. a `Boundary.rpc` resource's refetch stream raising after a client-side navigation.
 
-If no boundary encloses it, there is nothing to swap to. Weft does not synthesize one. The region's DOM keeps its last rendered content, and a watcher fiber (forked into the same scope alongside the subscription itself) observes its exit directly.
+If a boundary encloses the region, the failure routes to it exactly as above and its fallback swaps in. If none does, there is nothing to swap to. Weft does not synthesize one: the region's DOM keeps its last rendered content, and a watcher fiber (forked alongside the subscription itself) observes the exit instead.
 
-When that exit is a failure whose cause is not interruption-only, Weft reports it explicitly via `Effect.logError(exit.cause)`. The log is annotated with `weft.region` to identify the failing region by kind and identity (e.g. `attribute:class`, `child:stream-3`, `list:stream-2`, `hydrate:stream-1 (/products/42)`). This fires for typed failures and defects alike, in both dev and prod, exactly once per failing region, at the `"Error"` level. Interruption (the ordinary case of unmount tearing down the region's scope) is never reported; only genuine failures are.
+An exit whose cause is not interruption-only publishes an `UnhandledError` (`cause`, `region`, `root`) to the app's unhandled-error hub, exposed as `WeftApp.errors(app)`. `region` names the failing spot: `attribute:class`, `child:stream-3`, or `boundary:outermost` for a failure that escapes even the outermost boundary. Subscribe to observe every occurrence yourself:
 
-This is deliberate. Rather than leave the failure to whatever the Effect runtime would do with an unobserved fiber exit, Weft observes and logs it itself. Visibility is therefore controlled by the same knobs any Effect program uses: `References.MinimumLogLevel` (provided via `Effect.provideService`) to filter it, or a custom `Logger` to route it elsewhere.
+```typescript
+import { WeftApp } from "@weftui/dom/client";
+import { Effect, Stream } from "effect";
+
+Effect.runFork(
+  Stream.runForEach(WeftApp.errors(app), (error) =>
+    Effect.log(`unhandled in ${error.region}`, error.cause),
+  ),
+);
+```
 
-A stream that can fail and has no enclosing boundary is a stream whose failures you've chosen not to route into the UI. The log is what tells you that decision has consequences at runtime.
+With zero subscribers, each unhandled error instead runs a default `Effect.logError(cause)` annotated with `weft.region`, exactly once per occurrence, in dev and prod alike. Subscribing suppresses that fallback for as long as at least one subscriber stays attached.
+
+This is deliberate: rather than leave an unobserved fiber exit to the runtime, Weft always surfaces it, either to your subscriber or to the log. Interruption (ordinary unmount teardown) is never published or logged; only genuine failures are.
+
+A stream that can fail with no enclosing boundary is a stream whose failures you've chosen not to route into the UI. `WeftApp.errors` (and the log fallback) is what tells you that decision has consequences at runtime. Full contract: [`WeftApp.errors` / `UnhandledError`](https://weftui.dev/docs/reference/dom#weftapperrors).
 
 ## Suspense boundaries
 
@@ -100,11 +113,28 @@ Its channel behavior is also distinct. The rpc's typed `error` schema joins the
 
 The unifying idea: failure, async pending state, and server data are not three separate subsystems bolted onto the renderer. They are three **boundary nodes** in the one tree, each intercepting a different thing flowing through it. Each has channel behavior you can read off its type.
 
-That is why they nest freely. A `Boundary.catchTag` can wrap a `Boundary.rpc` to catch its typed failure. A `Boundary.suspend` can wrap async siblings that themselves contain rpc boundaries.
+That is why they nest freely. A `Boundary.catchTag` can wrap a `Boundary.rpc` to catch its typed failure, and a `Boundary.suspend` can wrap async siblings that themselves contain rpc boundaries:
+
+```typescript
+import { Boundary, h, Subscribable } from "@weftui/core";
+import { Stream } from "effect";
+
+Boundary.catchTag({ tag: "StockRpcError", fallback: () => h.p("Couldn't load stock.") }, [
+  Boundary.rpc(
+    GetStock,
+    () => ({ id: productId }),
+    (resource) =>
+      h.span([Stream.map(Subscribable.changes(resource.value), (s) => String(s.units))]),
+  ),
+]);
+```
+
+Each layer only sees the channel its own kind produces: `catchTag` narrows `E`, `Boundary.rpc` widens it by the rpc's error schema. Neither cares how the other renders.
 
 ## See also
 
 - [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): why a boundary is just a node in a static tree
 - [`Boundary` API reference](https://weftui.dev/docs/reference/core#boundary-namespace): every variant's signature and channel algebra
+- [`WeftApp.errors` / `UnhandledError`](https://weftui.dev/docs/reference/dom#weftapperrors): the unhandled-error hub for post-mount failures with no enclosing boundary
 - [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc): the full `Boundary.rpc` walkthrough and its four lifecycles
 - [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server): how suspense and rpc boundaries stream and hydrate

package/docs/explanation/combinator-api.md

@@ -7,7 +7,14 @@ description: How h, h.fragment, and Component.gen / Component.make work; why Nod
 
 # The Combinator API
 
-Weft builds UI trees by calling builder functions. Because component return types stay as generic `Effect.Effect<ElementDescriptor, E, R>`, the error channel (`E`) and requirements channel (`R`) propagate through the entire tree: visible to the type checker, satisfiable at the mount boundary.
+Weft builds UI trees by calling builder functions, not by writing markup. There is no JSX runtime and no `h(Component)` overload: a component is a plain function you call, and its result goes straight into the tree.
+
+```typescript
+// No JSX, no deferred element. Header/Main/Footer already ran; these are Nodes.
+const tree = h.div({ class: "app" }, [Header(), Main(), Footer()]);
+```
+
+Because a component's return type stays a concrete `Effect.Effect<ElementDescriptor, E, R>`, its error channel (`E`) and requirement channel (`R`) propagate through the whole tree. Both are visible to the type checker and satisfiable exactly once, at the mount boundary.
 
 JSX collapses every component's return type to an opaque `JSX.Element`, erasing both channels. The combinator API exists specifically to keep them intact.
 
@@ -110,7 +117,7 @@ const TableRow = ({ user }: { user: User }) =>
 
 ## Custom components with `Component.gen` / `Component.make`
 
-Plain functions work fine for simple components, but the `Component` factories provide type-level wiring so the caller's reactive prop types contribute their `E`/`R` to the returned node. Pick `Component.make` for a plain-function body and `Component.gen` for a generator body (when you need `yield*` to set up local state or pull from services).
+Plain functions work fine for simple components. The `Component` factories add type-level wiring: the caller's actual reactive prop types contribute their `E`/`R` to the node returned at that call site, not just the types you wrote in the signature. Pick `Component.make` for a plain-function body, `Component.gen` for a generator body (when you need `yield*` for local state or a service).
 
 ```typescript
 import { Component, h } from "@weftui/core";
@@ -132,30 +139,29 @@ declare const labelStream: Stream.Stream<string, never, I18nService>;
 const btn = Button({ label: labelStream });
 ```
 
-Components also accept an optional `children` argument, either as `readonly Renderable[]` or as a `(input) => readonly Renderable[]` function (render-prop pattern). `E`/`R` from children, including the array returned by a function-children call, accumulate on the resulting node.
+Components also accept an optional `children` argument: either `readonly Renderable[]`, or a `(input) => readonly Renderable[]` function for the render-prop pattern. Either way, the children's `E`/`R` accumulate onto the resulting node, including the array a function-children call returns.
 
-Without `Component`, a plain function's return type is fixed at definition time and does not reflect the caller's reactive prop types.
+A plain function without `Component` has its return type fixed at definition time. It reflects only the prop types you wrote, never a specific caller's reactive prop types.
 
-See [component-authoring.md](https://weftui.dev/docs/how-to/author-components) for a full walkthrough.
+See [Author Components](https://weftui.dev/docs/how-to/author-components) for a full walkthrough.
 
-## Suspense boundaries
+## Boundaries accumulate channels too
 
-`Boundary.suspend` wraps async children and shows a fallback until all of them have emitted their first value:
+`Boundary.suspend`, `Boundary.catch`, and the rest of the `Boundary` namespace are Nodes, not a separate concept. A boundary wraps children and its own type is `Node<ChildrenE, ChildrenR>`, so the same accumulation rules apply:
 
 ```typescript
 import { Boundary, h } from "@weftui/core";
 
+// Node<ChildrenE, ChildrenR>: transparent to E/R, like a plain h.* parent
 Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading...") }, [
   AsyncCard({ id: 1 }),
   AsyncCard({ id: 2 }),
 ]);
 ```
 
-The fallback is replaced atomically: either all children are visible or none are. This prevents partial flicker when multiple async siblings resolve at different times. The boundary's node type is `Node<ChildrenE, ChildrenR>`: the children's `E`/`R` channels accumulate onto it, exactly as they would for a plain `h.*` parent.
-
-On the server, `renderToStreamHydratable` emits the fallback inline and appends patch scripts as children resolve. On the client, `hydrate` sees through `Boundary.suspend` boundaries and adopts the already-resolved DOM directly.
+A boundary changes _when_ and _whether_ its children's output reaches the DOM, not what its type carries. `Boundary.catchTag` is the one exception: it removes the matched tag from `E`, since that's the failure it discharges.
 
-`Boundary.suspend` is one of the boundary combinators. See the [core reference](https://weftui.dev/docs/reference/core#boundarysuspend) for the full `Boundary.*` surface, including the failure-catch variants and `Boundary.rpc`.
+See [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) for what each boundary variant does, and the [core reference](https://weftui.dev/docs/reference/core#boundary-namespace) for the full `Boundary.*` surface.
 
 ## See also
 

package/docs/explanation/reactive-primitives.md

@@ -7,16 +7,14 @@ description: The Source<A, E, R> vocabulary; Stream, Effect, and Subscribable as
 
 # Reactive Primitives
 
-The unified `Source` vocabulary lets static values, Effects, Streams, and Subscribables be used interchangeably. Props, children, and style values all accept the same type.
+Weft accepts a `Source` for any prop value, any child, and any style value: one vocabulary, four kinds, used interchangeably wherever reactivity is supported.
 
-Weft accepts a `Source` for prop values and children. Any of these is valid wherever reactivity is supported:
-
-- A plain static value (`string`, `number`, `boolean`, ...)
-- An `Effect.Effect<A, E, R>`: runs once and resolves to a value
-- A `Stream.Stream<A, E, R>`: each emission replaces the previous value
-- A `Subscribable<A, E, R>`: like a hot stream; already has a "current value"
-
-The `Source<A, E, R>` type captures this union:
+| Kind                                                      | Behavior                                  |
+| --------------------------------------------------------- | ----------------------------------------- |
+| a plain static value (`string`, `number`, `boolean`, ...) | set once, never updates                   |
+| `Effect.Effect<A, E, R>`                                  | runs once, resolves to a value            |
+| `Stream.Stream<A, E, R>`                                  | each emission replaces the previous value |
+| `Subscribable<A, E, R>`                                   | a hot stream: already has a current value |
 
 ```typescript
 type Source<A, E, R> = A | Effect.Effect<A, E, R> | Stream.Stream<A, E, R> | Subscribable<A, E, R>;
@@ -139,13 +137,42 @@ h.div({
 });
 ```
 
+## Latest-value-wins conflation
+
+Every reactive region and prop is drained by one shared commit scheduler, the
+Loom (see [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model#the-loom-one-scheduler-per-app-committing-asynchronously)).
+When a source emits faster than the DOM commits, the Loom conflates the burst:
+it keeps only the newest value per region and skips the intermediate ones.
+
+```typescript
+const ticks = Stream.range(0, 999); // publishes far faster than the DOM commits
+
+h.span([ticks]); // the span settles on 999; 0 through 998 may never render
+```
+
+The final DOM state always reflects the newest value; nothing is lost
+permanently. What is skipped are the values in between, by design: this is
+what keeps a fast-publishing source from piling up unbounded DOM work.
+
+Code that must observe every emission, not just the settled one (an audit
+log, a counter that sums each tick), should consume the stream directly
+instead of relying on what lands in the DOM:
+
+```typescript
+yield * Stream.runForEach(ticks, (n) => Effect.sync(() => total.push(n)));
+```
+
 ## NoPropValue
 
-When a `Stream` prop ends before emitting, the renderer raises a `NoPropValue` tagged error. This carries an optional `key` field identifying which prop triggered it:
+A finite `Stream` prop can end without ever emitting, e.g. `Stream.empty` or `Stream.take(0, stream)`. When it does, the renderer raises a `NoPropValue` tagged error carrying an optional `key` that identifies the prop:
+
+```typescript
+h.span([Stream.empty]); // completes without emitting: raises NoPropValue
+```
+
+`Effect.catchTag` matches by the string tag, so handling it at the mount boundary needs no `NoPropValue` import:
 
 ```typescript
-// Handle at the mount boundary if needed. `Effect.catchTag` matches the error
-// by its string tag, so no `NoPropValue` import is required here.
 pipe(
   WeftApp.mount(app, App(), root),
   Effect.catchTag("NoPropValue", (e) =>
@@ -154,7 +181,7 @@ pipe(
 );
 ```
 
-In practice you only encounter `NoPropValue` when a finite `Stream` prop ends before emitting (e.g., `Stream.empty` or `Stream.take(0, stream)`). Most usage with `SubscriptionRef.changes` or infinite streams never raises it.
+`SubscriptionRef.changes` and other infinite streams always emit before completing, so most usage never raises it.
 
 ## See also
 

package/docs/explanation/rendering-model.md

@@ -37,12 +37,22 @@ When a stream emits, only the DOM at _that_ point updates. Nothing above it re-r
 
 ## Streams drive all updates
 
-There is no `setState`, no render-triggering scheduler, no "re-render this component." A region of the DOM is live **if and only if** a stream is woven into it. To make something update, you thread a stream through it; to keep something static, you pass a plain value.
+There is no `setState`, no "re-render this component," no vdom diff. A region of the DOM is live **if and only if** a stream is woven into it. To make something update, you thread a stream through it; to keep something static, you pass a plain value.
 
-The renderer subscribes to each woven stream and patches its target in place on every emission. It reuses the existing DOM node and patches text and attributes rather than recreating elements, so identity, focus, and typed input survive an update.
+The renderer reuses the existing DOM node and patches text and attributes in place rather than recreating elements, so identity, focus, and typed input survive an update. Updates stay local: a stream woven at one point never touches an untouched sibling or re-runs a parent.
 
 This also fixes the update _shape_. Because the structure is fixed, an update is always "new value into a known hole," never "reconcile these two trees." Even list rendering, where the number of children genuinely varies, is expressed as a keyed region ([`List.each`](https://weftui.dev/docs/how-to/render-keyed-lists)). It reconciles by key rather than by structural diff.
 
+## The Loom: one scheduler per app, committing asynchronously
+
+Every woven stream feeds one shared scheduler per `WeftApp`: the **Loom**. It keeps one latest-value slot per reactive region or prop and commits changes to the DOM in passes.
+
+The name follows the metaphor: individual streams spin as fast as they like, like threads paid out from a bobbin. The loom only ever weaves the newest state of each thread into the fabric, one pass at a time. A region that receives several values before its next commit collapses to the last one: intermediate emissions are conflated, never committed. This bounds DOM work no matter how fast a source publishes.
+
+Commits are asynchronous: they happen on the scheduler's own turn, not synchronously with the write. `RootHandle.awaitCommit` is the acknowledgement. It resolves once everything pending at call time has either committed or been discarded, returning the commit generation. See the [`RootHandle` reference](https://weftui.dev/docs/reference/dom#roothandle) for its exact semantics.
+
+None of this changes what you write. You still thread a `Stream`, `Effect`, or `Subscribable` through a prop or child; the Loom is an implementation detail of how those emissions reach the DOM. Code that must observe every intermediate value, not just the settled one, should consume the stream directly instead of relying on what lands in the DOM (see [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives#latest-value-wins-conflation)).
+
 ## One tree, two sides, hydrate in place
 
 The same component tree renders on the server and the client:
@@ -56,6 +66,7 @@ Because the same `Node<E, R>` describes both passes, there is nothing to keep in
 
 - **No diff cost.** Updates are O(changed value), not O(tree). There is no reconciliation pass to pay for.
 - **Local reasoning.** A stream woven at one point cannot affect another. What is reactive is exactly what you made reactive.
+- **Bounded commit work.** The Loom conflates bursts to one commit per region, so a fast-publishing source cannot outrun the DOM.
 - **Type-honest edges.** The app node's `E`/`R` is the whole app's error and dependency surface, checked at compile time and discharged once at the edge.
 - **Flash-free SSR by construction.** Hydration adopts rather than replaces, because the tree is identical on both sides.
 
@@ -65,3 +76,4 @@ Because the same `Node<E, R>` describes both passes, there is nothing to keep in
 - [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the stream-shaped values you weave through the tree
 - [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense): how failure and async are modeled as nodes in the same tree
 - [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server): the server/client split and `hydrate`
+- [`@weftui/dom` reference](https://weftui.dev/docs/reference/dom#roothandle): `RootHandle.awaitCommit` and `commitGeneration`

package/docs/how-to/add-routing.md

@@ -329,10 +329,7 @@ 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 root = document.getElementById("root")!;
 
 const app = WeftApp.make(RouterLive(App));
 void Effect.runPromise(WeftApp.mount(app, RouterApp(App), root));
@@ -485,10 +482,7 @@ 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 root = document.getElementById("root")!;
 
 const app = WeftApp.make(RouterLive(App));
 void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));

package/docs/how-to/author-components.md

@@ -7,11 +7,11 @@ description: Plain functions vs. Component.gen / Component.make, instance scope,
 
 # Component Authoring
 
-Weft components are plain TypeScript functions that return a `Node<E, R>`. This guide covers the two ways to define them and when to choose each.
+**Goal:** write a Weft component, a plain function returning a `Node<E, R>`, and pick the right authoring style for its complexity.
 
 ## Plain functions
 
-The simplest component is just a function:
+Static props, no internal state: write and call a plain function.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -20,19 +20,18 @@ function Greeting({ name }: { name: string }) {
   return h.p(`Hello, ${name}!`);
 }
 
-// Call it like a function
-Greeting({ name: "World" });
+Greeting({ name: "World" }); // called directly, no JSX, no deferred descriptor
 ```
 
-Use a plain function when:
+Reach for this when:
 
-- Props are all static (strings, numbers, plain functions)
-- The component has no internal state
-- You don't need the caller's reactive prop types to propagate
+- Props are all static (strings, numbers, plain functions).
+- The component has no internal state.
+- You don't need the caller's reactive prop types to propagate into the return type.
 
 ## Components with internal state
 
-When a component needs reactive state, use `Effect.gen` to set it up before building the tree. The component function still runs once. The setup happens at mount time:
+Set up reactive state with `Effect.gen` before building the tree. The component function still runs once; the setup happens at mount time:
 
 ```typescript
 import { h } from "@weftui/core";
@@ -49,68 +48,16 @@ const Counter = () =>
   });
 ```
 
-The return type here is `Effect.Effect<Node, never, never>`, itself a valid `Node`, so it composes naturally with other tree-building calls.
+`Effect.Effect<Node, never, never>` is itself a valid `Node`, so it composes with any other tree-building call.
 
-As soon as such a component is reused or takes props, wrap the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below). That way the caller's reactive prop and children channels flow into its node type.
+Once a component like this is reused or takes props, wrap the same generator in `Component.gen` (below) so the caller's reactive prop and children channels flow into its node type.
 
-## Component scope and background effects
+## `Component.gen` / `Component.make`
 
-Every component instance is rendered under its own **instance scope**, a child of the
-mount scope created fresh for that instance. Anything bound to the instance scope lives
-exactly as long as the component is mounted. It is torn down automatically when the
-component unmounts (or when its root unmounts via `RootHandle.unmount()`).
+Both build a component whose returned `Node`'s `E`/`R` include the caller's reactive prop and children channels, not just the body's own:
 
-The renderer provides this scope as the ambient `Scope.Scope` while it evaluates the
-component body, so it is already in context when you need it.
-
-This matters the moment a component starts **background work**: a subscription, an
-observer of a `ref`, a polling timer, anything you `fork`. The rule:
-
-> Fork background work with **`Effect.forkScoped`**, never a bare `Effect.forkChild`.
-
-`Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for
-the component's lifetime and is interrupted on unmount. A bare `Effect.forkChild` instead
-attaches the fiber to the component-body fiber, the one that runs your `Effect.gen` to
-produce the tree. That fiber completes the instant the gen returns its node, so the
-forked work is cancelled almost immediately.
-
-Concretely, an observer that runs an effect when a `ref`'s element mounts:
-
-```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());
-
-    yield* pipe(
-      SubscriptionRef.changes(inputRef),
-      Stream.filter(Option.isSome),
-      Stream.take(1),
-      Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
-      Effect.forkScoped, // ✅ tied to the instance scope: survives until unmount
-      // Effect.forkChild, // ❌ tied to the body fiber: interrupted when the gen returns
-    );
-
-    return yield* h.input({ ref: inputRef, type: "text" });
-  });
-```
-
-You do not manage the scope yourself: you do not create it, close it, or pass it
-around. `forkScoped` reads it from context, and unmount closes it for you. If you ever
-fork outside a component body (rare), you must supply a `Scope.Scope` yourself. The
-type system will tell you, because `forkScoped` carries a `Scope.Scope` requirement.
-
-See `examples/element-ref` for the auto-focus, measure, and canvas recipes built on
-this pattern.
-
-## `Component.gen` / `Component.make` for reusable components
-
-When you want the caller's reactive prop types to flow into the returned node's type, use one of the `Component` factories. Both have the same call semantics; pick the body style that fits:
-
-- **`Component.make`**: body is a plain function returning any `Effect` (typically a `Node`). Use for one-liners and pipe compositions.
-- **`Component.gen`**: body is a generator. Use when you need `yield*` to set up local state or pull from services.
+- **`Component.make`**: body is a plain function returning any `Effect`. Use for one-liners and pipe compositions.
+- **`Component.gen`**: body is a generator. Use when you need `yield*` for local state or services.
 
 ```typescript
 import { Component, h, Source } from "@weftui/core";
@@ -128,40 +75,28 @@ const Card = Component.make((props: CardProps) =>
 );
 ```
 
-`Source.Source<string>` is Weft's caller-facing prop vocabulary: a single type covering a static `string`, a `Stream<string>`, an `Effect<string>`, or a `Subscribable<string>`. You don't hand-write `string | Stream.Stream<string> | …` on every prop.
-
-Passing a `Source` straight to `h` (as above) is all you need when the value is just spliced into the tree. The renderer normalizes it.
-
-Now the caller's stream types are visible in the returned node:
-
 ```typescript
 declare const titleStream: Stream.Stream<string, never, I18nService>;
 
-// Node<never, I18nService>: I18nService requirement flows out
+// Node<never, I18nService>: I18nService flows out from the prop the caller passed
 const card = Card({ title: titleStream });
 ```
 
-Without a `Component` factory, a plain function's return type is fixed at definition time and won't reflect the caller's reactive prop types.
+Without a `Component` factory, a plain function's return type is fixed at definition time and can't reflect what the caller actually passes.
 
-### Body `E`/`R` inference
-
-You don't declare the body's `E`/`R` channels explicitly. They're inferred from the returned (or yielded) effect:
-
-- The body's `E`/`R` come from whatever effects appear inside.
-- The caller's reactive prop channels and reactive children channels are unioned on top at the call site.
+- The body's `E`/`R` come from whatever effects it yields or returns.
+- Caller prop channels and children channels are unioned on top at the call site.
 - Static prop values (`string`, `number`, plain functions) contribute `never`.
 
 ### Children: array or function
 
-Both factories accept an optional second `children` argument, typed as:
-
 ```typescript
 type Component.Children<Input = never> =
   | readonly Renderable[]
   | ((input: Input) => readonly Renderable[]);
 ```
 
-The function form is the render-prop / slot pattern. The component invokes the function with whatever input it chooses, and the returned array's `E`/`R` propagate out:
+The function form is the render-prop / slot pattern. The component calls it with whatever `input` it chooses, and the returned array's `E`/`R` propagate out:
 
 ```typescript
 const ItemList = Component.make(
@@ -172,9 +107,9 @@ const ItemList = Component.make(
 ItemList({ items: ["a", "b"] }, (item) => [h.li(item)]);
 ```
 
-## Props typing
+## Props typing with `Source`
 
-For a prop that accepts both static and reactive values, type it as [`Source.Source<T>`](https://weftui.dev/docs/reference/core#source-namespace) rather than hand-writing the union. `Source.Source<T>` **is** that union: `T | Stream<T> | Effect<T> | Subscribable<T>`. The caller can pass a plain value or any reactive shape interchangeably, and you write it once:
+Type a prop that accepts both static and reactive values as `Source.Source<T>` instead of hand-writing the union:
 
 ```typescript
 import { Source } from "@weftui/core";
@@ -186,11 +121,9 @@ interface ButtonProps {
 }
 ```
 
-When a caller passes a plain string, the component's node type has `never` for that prop's channels. When they pass a `Stream.Stream<string, never, SomeService>`, `SomeService` appears in the `R` channel. The extraction is exactly `Source.Success` / `Source.Error` / `Source.Context`.
-
-### Reading a `Source` in the body
+`Source.Source<T>` **is** the union `T | Stream<T> | Effect<T> | Subscribable<T>`. A plain string contributes `never` to the node's channels; a `Stream<string, never, SomeService>` contributes `SomeService` to `R`. The extraction is `Source.Success` / `Source.Error` / `Source.Context`.
 
-Splicing a `Source` straight into `h` (`[props.label]`) is enough when you only place it in the tree. When the body needs to **read or derive** from the value (combine two props, feed a stream operator, drive logic), normalize it first with [`Source.toSubscribable`](https://weftui.dev/docs/reference/core#sourcetosubscribablesource-key). It turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
+Splicing a `Source` straight into `h` (`[props.label]`) is enough when the body only places it in the tree. Reach for `Source.toSubscribable` when the body needs to **read or derive** from it:
 
 ```typescript
 import { Component, h, Source, Subscribable } from "@weftui/core";
@@ -198,19 +131,48 @@ import { Stream } from "effect";
 
 const LoudLabel = Component.gen(function* (props: { label: Source.Source<string> }) {
   const label = yield* Source.toSubscribable(props.label); // Subscribable<string>
-  // Now derive from it like any Subscribable: static, Effect, and Stream inputs all work.
   return yield* h.strong([Stream.map(Subscribable.changes(label), (text) => text.toUpperCase())]);
 });
 ```
 
-`toSubscribable` is scoped:
-
-- A `Stream` prop is pumped by a fiber that terminates with the component's instance scope.
-- An `Effect` prop is memoized.
-- An existing `Subscribable` is threaded through by reference.
+- An existing `Subscribable` prop is threaded through by reference, no new fiber.
+- A `Stream` prop is pumped by a fiber scoped to the component's instance scope.
+- An `Effect` prop is memoized, so it runs at most once.
 - A static value emits once.
 
-It is the same normalization the renderer applies to props internally. Reach for it whenever you need the value as a `Subscribable` instead of leaving it opaque.
+## Instance scope and background effects
+
+Every component instance renders under its own **instance scope**, a child of the mount scope created fresh per instance. It closes on unmount (or when its root unmounts via `RootHandle.unmount()`). The renderer supplies it as the ambient `Scope.Scope` while your body runs, so it's already in context.
+
+Fork background work (a subscription, a ref observer, a polling timer) with **`Effect.forkScoped`**, never a bare `Effect.forkChild`:
+
+```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());
+
+    yield* pipe(
+      SubscriptionRef.changes(inputRef),
+      Stream.filter(Option.isSome),
+      Stream.take(1),
+      Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
+      Effect.forkScoped, // ✅ tied to the instance scope: survives until unmount
+      // Effect.forkChild, // ❌ tied to the body fiber: interrupted when the gen returns
+    );
+
+    return yield* h.input({ ref: inputRef, type: "text" });
+  });
+```
+
+- `Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for the component's lifetime and is interrupted on unmount.
+- `Effect.forkChild` attaches to the component-body fiber instead, the one that runs your generator to produce the tree. That fiber completes the instant the body returns its node, so a bare fork is cancelled almost immediately.
+
+You never create, close, or pass the scope yourself: `forkScoped` reads it from context, and unmount closes it for you. Forking outside a component body (rare) requires supplying a `Scope.Scope`, and `forkScoped`'s own `Scope.Scope` requirement makes the type system tell you.
+
+See [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs) for the auto-focus, measure, and canvas recipes built on this pattern.
 
 ## Composing components
 
@@ -228,11 +190,11 @@ function App() {
 }
 ```
 
-Children arrays accumulate `E`/`R` from all their members. The parent node's type reflects the union of all children's channels.
+Children arrays accumulate `E`/`R` from all their members; the parent node's type reflects the union.
 
 ## Components that require services
 
-If a component's render function uses a service via `yield*`, that service appears in the component's `CompR` parameter:
+A service read via `yield*` inside the body appears in the component's `R` channel, regardless of what the caller passes:
 
 ```typescript
 import { Component, h } from "@weftui/core";
@@ -243,11 +205,11 @@ const UserAvatar = Component.gen(function* (props: { userId: string }) {
   return yield* h.img({ src: user.avatarUrl, alt: user.name });
 });
 
-// Node<never, UserService>: regardless of what the caller passes
+// Node<never, UserService>
 const avatar = UserAvatar({ userId: "123" });
 ```
 
-Give the service to the app layer:
+Give the service to the app layer, not to the mount call:
 
 ```typescript
 import { WeftApp } from "@weftui/dom/client";
@@ -257,9 +219,11 @@ const app = WeftApp.make(UserServiceLive);
 void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
+See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for scoped layers, `memoMap` sharing, and why wrapping `Effect.provide` around the mount call doesn't work.
+
 ## Returning fragments
 
-When a component needs to return multiple sibling elements without a wrapper, use `h.fragment`:
+Return multiple sibling elements without a wrapper using `h.fragment`:
 
 ```typescript
 import { h } from "@weftui/core";
@@ -268,11 +232,13 @@ const TableCells = ({ row }: { row: Row }) =>
   h.fragment([h.td(row.name), h.td(row.value), h.td(row.status)]);
 ```
 
-`h.fragment` returns a `Node<E, R>` that accumulates channels from all its children.
+`h.fragment` returns a `Node<E, R>` that accumulates channels from all its children, same as any other `h.*` call.
 
 ## See also
 
 - [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): `h`, `h.fragment`, and how `E`/`R` accumulate
 - [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the `Source` vocabulary props accept
+- [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs): `ref` props and scoped mount observers
+- [Provide Services](https://weftui.dev/docs/how-to/provide-services): app layers, scoped layers, and `memoMap`
 - [Add Routing](https://weftui.dev/docs/how-to/add-routing): route components are `Component` slots
 - [`@weftui/core` reference](https://weftui.dev/docs/reference/core): `Component`, `Source`, and the full surface