@weftui/core 0.27.1 → 0.29.0

package/docs/explanation/combinator-api.md

@@ -7,7 +7,9 @@ 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. JSX collapses every component's return type to an opaque `JSX.Element`, erasing both channels; the combinator API exists specifically to keep them intact.
+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.
+
+JSX collapses every component's return type to an opaque `JSX.Element`, erasing both channels. The combinator API exists specifically to keep them intact.
 
 ## Nodes are Effects
 
@@ -23,13 +25,13 @@ Nodes are first-class Effects. Everything in the Effect ecosystem works on them
 import { h } from "@weftui/core";
 import { Effect } from "effect";
 
-// yield* in Effect.gen — R propagates into the generator's context
+// yield* in Effect.gen: R propagates into the generator's context
 const node = yield * h.div({ class: "container" }, "Hello");
 
-// pipe — chain Effect operators directly
+// pipe: chain Effect operators directly
 const provided = pipe(h.div(userStream), Effect.provide(UserServiceLive));
 
-// Effect.flatMap — sequence node creation with async logic
+// Effect.flatMap: sequence node creation with async logic
 const card = pipe(
   fetchCard(id),
   Effect.flatMap((data) => h.div({ class: "card" }, data.title)),
@@ -78,7 +80,7 @@ Reactive prop values (any `Stream`, `Effect`, or `Subscribable`) contribute thei
 ```typescript
 declare const colorStream: Stream.Stream<string, never, ThemeService>;
 
-// Node<never, ThemeService> — R comes from the stream prop
+// Node<never, ThemeService>: R comes from the stream prop
 const box = h.div({ style: { color: colorStream } }, "Hello");
 ```
 
@@ -130,7 +132,7 @@ 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 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.
 
 Without `Component`, a plain function's return type is fixed at definition time and does not reflect the caller's reactive prop types.
 
@@ -149,16 +151,16 @@ Boundary.suspend({ fallback: h.div({ class: "spinner" }, "Loading...") }, [
 ]);
 ```
 
-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.
+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.
 
-`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`.
+`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 also
 
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why a `Node` is an `Effect` and how the tree renders
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — the `Source` vocabulary that reactive props and children accept
-- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense) — the boundary combinators as tree nodes
-- [Author Components](https://weftui.dev/docs/how-to/author-components) — `Component.gen` / `Component.make` in practice
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): why a `Node` is an `Effect` and how the tree renders
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the `Source` vocabulary that reactive props and children accept
+- [Boundaries and Suspense](https://weftui.dev/docs/explanation/boundaries-and-suspense): the boundary combinators as tree nodes
+- [Author Components](https://weftui.dev/docs/how-to/author-components): `Component.gen` / `Component.make` in practice
 - [`@weftui/core` reference](https://weftui.dev/docs/reference/core)

package/docs/explanation/reactive-primitives.md

@@ -7,14 +7,14 @@ description: The Source<A, E, R> vocabulary; Stream, Effect, and Subscribable as
 
 # Reactive Primitives
 
-The unified `Source` vocabulary is what lets static values, Effects, Streams, and Subscribables be used interchangeably wherever reactivity is supported — props, children, and style values all accept the same type.
+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 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"
+- 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:
 
@@ -24,7 +24,7 @@ type Source<A, E, R> = A | Effect.Effect<A, E, R> | Stream.Stream<A, E, R> | Sub
 
 ## Static values
 
-Static props behave exactly as you'd expect — set once and never updated:
+Static props are set once and never updated:
 
 ```typescript
 h.div({ class: "container", id: "root" }, "Hello");
@@ -45,17 +45,17 @@ The `E` and `R` channels of the Effect flow into the node's own channels.
 
 ## Stream props and children
 
-Streams are the primary reactive primitive. Each emission replaces the previous value in the DOM — no diffing, direct DOM update:
+Streams are the primary reactive primitive. Each emission replaces the previous value in the DOM (no diffing, direct DOM update):
 
 ```typescript
 import { SubscriptionRef, Stream } from "effect";
 
 const count = yield * SubscriptionRef.make(0);
 
-// SubscriptionRef.changes(count) is a Stream<number> — each new value updates the text node
+// SubscriptionRef.changes(count) is a Stream<number>: each new value updates the text node
 h.span([SubscriptionRef.changes(count)]);
 
-// Stream as a prop — each emission sets the attribute
+// Stream as a prop: each emission sets the attribute
 const isDisabled = Stream.map(SubscriptionRef.changes(count), (n) => n >= 10);
 h.button({ disabled: isDisabled }, "Submit");
 ```
@@ -119,7 +119,7 @@ h.div({ style: styleObjectStream });
 
 // Combine a whole-object stream with a static property.
 // A whole-object stream replaces every property on each emit, so fold the
-// static value into each emitted object with Stream.map — you cannot spread the
+// static value into each emitted object with Stream.map. You cannot spread the
 // Stream itself into a style object (that copies the Stream's internals, not
 // its emitted style keys).
 h.div({
@@ -147,18 +147,18 @@ When a `Stream` prop ends before emitting, the renderer raises a `NoPropValue` t
 // Handle at the mount boundary if needed. `Effect.catchTag` matches the error
 // by its string tag, so no `NoPropValue` import is required here.
 pipe(
-  mount(App(), root),
+  WeftApp.mount(app, App(), root),
   Effect.catchTag("NoPropValue", (e) =>
     Effect.logWarning(`Prop stream ended before emitting: ${e.key}`),
   ),
 );
 ```
 
-In practice you only encounter `NoPropValue` if you use a finite `Stream` as a prop and it ends before emitting — e.g., `Stream.empty` or `Stream.take(0, stream)`. Most usage with `SubscriptionRef.changes` or infinite streams never raises it.
+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.
 
 ## See also
 
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — streams as the weft woven through a static tree
-- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how reactive props and children contribute `E`/`R`
-- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively) and [Render Keyed Lists](https://weftui.dev/docs/how-to/render-keyed-lists) — reactive props and collections in practice
-- [`Source` reference](https://weftui.dev/docs/reference/core#source-namespace) — the `Source` type and `Source.toSubscribable`
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): streams as the weft woven through a static tree
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): how reactive props and children contribute `E`/`R`
+- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively) and [Render Keyed Lists](https://weftui.dev/docs/how-to/render-keyed-lists): reactive props and collections in practice
+- [`Source` reference](https://weftui.dev/docs/reference/core#source-namespace): the `Source` type and `Source.toSubscribable`

package/docs/explanation/rendering-model.md

@@ -2,12 +2,12 @@
 title: The Rendering Model
 order: 1
 section: explanation
-description: Why Weft has no virtual DOM — nodes are Effects, streams are the live thread woven through a static tree, and hydration adopts server DOM in place.
+description: Why Weft has no virtual DOM. Nodes are Effects, streams are the live thread woven through a static tree, and hydration adopts server DOM in place.
 ---
 
 # The Rendering Model
 
-Weft renders UI by **weaving streams through a static tree**. There is no virtual DOM, no diff, no reconciler comparing two trees each frame. This page explains the model that makes that work — and why it falls out of one definition.
+Weft renders UI by **weaving streams through a static tree**. There is no virtual DOM, no diff, no reconciler comparing two trees each frame.
 
 ## Nodes are Effects
 
@@ -17,38 +17,40 @@ The whole library rests on a single equation:
 type Node<E = never, R = never> = Effect.Effect<ElementDescriptor, E, R>;
 ```
 
-Every element in a Weft tree **is an Effect**. `h.div(...)`, a component's return value, a boundary — each is an `Effect` that, when run, produces an element descriptor. Two consequences follow immediately, and they shape everything else:
+Every element in a Weft tree **is an Effect**. `h.div(...)`, a component's return value, a boundary: each is an `Effect` that, when run, produces an element descriptor. Two consequences follow:
 
-1. **The error (`E`) and requirement (`R`) channels accumulate through the tree.** A child that reads a service, or a prop backed by a failible stream, contributes its `R` and `E` to its parent, which contributes to _its_ parent, up to the mount boundary. The type of your app node is the exact union of everything it needs and everything it can fail with — visible to the type checker, satisfiable exactly once, at `mount`/`hydrate`. See [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) for how the accumulation works mechanically.
-2. **Every Effect combinator applies to a node directly.** `Effect.provide`, `Effect.flatMap`, `Effect.gen`, `Effect.catch` — none of them are special-cased for UI. A node is an ordinary Effect, so the entire Effect ecosystem composes with your view for free.
+1. **The error (`E`) and requirement (`R`) channels accumulate through the tree.** A child that reads a service, or a prop backed by a failible stream, contributes its `R` and `E` to its parent. That parent contributes to _its_ parent, up to the mount boundary. The type of your app node is the exact union of everything it needs and everything it can fail with. It is visible to the type checker, satisfiable exactly once, at `mount`/`hydrate`. See [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) for how the accumulation works mechanically.
+2. **Every Effect combinator applies to a node directly.** `Effect.provide`, `Effect.flatMap`, `Effect.gen`, `Effect.catch`: none of them are special-cased for UI. A node is an ordinary Effect, so the entire Effect ecosystem composes with your view for free.
 
-JSX collapses every component to an opaque `JSX.Element`, erasing both channels. Weft keeps them, and that is the point of the whole design. (There is [no JSX](https://weftui.dev/docs/explanation/combinator-api) here — components are plain functions you _call_.)
+JSX collapses every component to an opaque `JSX.Element`, erasing both channels. Weft keeps them, and that is the point of the whole design. (There is [no JSX](https://weftui.dev/docs/explanation/combinator-api) here; components are plain functions you _call_.)
 
 ## Warp and weft
 
 The name is the metaphor. On a loom, the **warp** is the set of fixed threads held under tension; the **weft** is the live thread drawn back and forth across them to form the cloth.
 
-- Your **component tree is the warp** — the structure, fixed for the lifetime of a mounted region.
-- **Streams are the weft** — the live values drawn across that structure. A `Stream`, `Effect`, or `Subscribable` used as a prop value or child is a thread woven through a specific point in the tree.
+- Your **component tree is the warp**: the structure, fixed for the lifetime of a mounted region.
+- **Streams are the weft**: the live values drawn across that structure. A `Stream`, `Effect`, or `Subscribable` used as a prop value or child is a thread woven through a specific point in the tree.
 
-When a stream emits, only the DOM at _that_ point updates. Nothing above it re-runs; no sibling is touched; there is no tree to diff because the structure never changed — only a value threaded through one hole in it did. This is why Weft needs no virtual DOM: **the reactivity is local by construction.** The vocabulary of stream-shaped values (and how their channels flow) is [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives).
+When a stream emits, only the DOM at _that_ point updates. Nothing above it re-runs; no sibling is touched. There is no tree to diff because the structure never changed; only a value threaded through one hole in it did. This is why Weft needs no virtual DOM: **the reactivity is local by construction.** The vocabulary of stream-shaped values (and how their channels flow) is [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives).
 
-> **Note.** "Only that point updates" is the default, not a manual optimization. You do not memoize regions or declare dependencies — a value is reactive exactly where you thread a stream, and static everywhere else.
+> **Note.** "Only that point updates" is the default, not a manual optimization. You do not memoize regions or declare dependencies. A value is reactive exactly where you thread a stream, and static everywhere else.
 
 ## 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. The renderer subscribes to each woven stream and patches its target in place on every emission — reusing the existing DOM node, patching text and attributes rather than recreating elements (identity, focus, and typed input survive an update).
+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.
 
-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)) that reconciles by key rather than by structural diff.
+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.
+
+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.
 
 ## One tree, two sides, hydrate in place
 
 The same component tree renders on the server and the client:
 
 - On the **server**, the tree renders to an HTML string (or a streaming response) via `@weftui/dom/server`. The _hydratable_ renderers additionally emit the inline data each reactive region needs to resume.
-- On the **client**, `hydrate()` walks that server-rendered DOM and **adopts it in place** — it wires up reactivity and event handlers on the existing nodes rather than re-rendering. The first client production matches the adopted DOM exactly, so nothing is mutated and there is no flash.
+- On the **client**, `WeftApp.hydrate` walks that server-rendered DOM and **adopts it in place**: it wires up reactivity and event handlers on the existing nodes rather than re-rendering. The first client production matches the adopted DOM exactly, so nothing is mutated and there is no flash.
 
-Because the same `Node<E, R>` describes both passes, there is nothing to keep in sync: the server output and the client's first render are the _same tree_ run in two environments. Services flow from the mount (or the router's render-time context) through the tree to wherever a component reads them, on both sides. The mechanics of the two-sided render live in [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server); the service flow is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
+Because the same `Node<E, R>` describes both passes, there is nothing to keep in sync. The server output and the client's first render are the _same tree_ run in two environments. Services flow from the app layer (or the router's render-time context) through the tree to wherever a component reads them, on both sides. The mechanics of the two-sided render live in [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server); the service flow is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
 
 ## Why this matters
 
@@ -59,7 +61,7 @@ Because the same `Node<E, R>` describes both passes, there is nothing to keep in
 
 ## See also
 
-- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how `E`/`R` accumulate; why `Node` is an `Effect`; `h` and components
-- [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`
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): how `E`/`R` accumulate; why `Node` is an `Effect`; `h` and components
+- [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`

package/docs/explanation/services-and-context.md

@@ -2,52 +2,58 @@
 title: Services and Context
 order: 5
 section: explanation
-description: How Effect services reach components — the requirement channel, discharging R at the mount, the router's render-time context seam, and ServerTag server-only brands.
+description: "How Effect services reach components: the requirement channel, discharging R at the mount, the router's render-time context seam, and ServerTag server-only brands."
 ---
 
 # Services and Context
 
-Weft has no separate dependency-injection system. It uses Effect's — a component that needs a service reads it with `yield* Service`, and because [a node is an Effect](https://weftui.dev/docs/explanation/rendering-model), that requirement rides the node's `R` channel up the tree to a single point where you provide it. This page explains how a service travels from where you provide it to where a component reads it, and the two seams that make that work across the server/client boundary.
+Weft has no separate dependency-injection system. It uses Effect's. A component that needs a service reads it with `yield* Service`. Because [a node is an Effect](https://weftui.dev/docs/explanation/rendering-model), that requirement rides the node's `R` channel up the tree to a single point where you provide it.
+
+This page explains how a service travels from provider to reader, and the two seams that make that work across the server/client boundary.
 
 ## R accumulates, then discharges once
 
-When a component does `yield* ThemeService`, `ThemeService` enters that node's requirement channel. It accumulates through every parent — a boundary, a layout, the app node — until the whole tree's `R` is the union of everything any component needs. You satisfy it in **one** place, at the edge:
+When a component does `yield* ThemeService`, `ThemeService` enters that node's requirement channel. It accumulates through every parent: a boundary, a layout, the app node. The whole tree's `R` becomes the union of everything any component needs. You satisfy it in **one** place, at the edge:
 
 ```typescript
 import { Effect } from "effect";
-import { mount } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 
-const handle = pipe(
-  mount(App(), document.getElementById("root")!),
-  Effect.provide(ThemeServiceLive),
-);
+const app = WeftApp.make(ThemeServiceLive);
+const handle = WeftApp.mount(app, App(), document.getElementById("root")!);
 ```
 
-Provide too little and it is a compile error at the mount call — the type of `App()` names exactly which service is missing. This is the same discipline as any Effect program: `R` is a promise the type checker holds you to, discharged at the program's boundary, not sprinkled through the tree.
+Provide too little and it is a compile error at `WeftApp.make`: the type of `App()` names exactly which service is missing. This is the same discipline as any Effect program. `R` is a promise the type checker holds you to, discharged at the program's boundary, not sprinkled through the tree.
 
-Services flow **down** from that provide point to every reader, including across reactive boundaries: a stream woven into a prop carries its own `R`, and a handler that reads a service resolves it from the same context. There is no prop-drilling and no context-provider component — the requirement channel _is_ the wiring.
+Services flow **down** from the app's layer to every reader, including across reactive boundaries. A stream woven into a prop carries its own `R`, and a handler that reads a service resolves it from the same context. There is no prop-drilling and no context-provider component: the requirement channel _is_ the wiring.
 
-## Layer lifetime at the mount
+## Layer lifetime and the app runtime
 
-The `ThemeServiceLive` example above works because `mount`'s effect and the service's lifetime coincide by accident: `ThemeServiceLive` is a plain value layer with nothing to release, so it makes no difference whether it is "alive" for one tick or the whole session. That accident stops holding the moment the layer is **scoped** — built from an `acquireRelease`-backed `Layer.effect` — because `mount`'s effect resolves right after the tree's **initial render**, not when the app stops running. Streams, event handlers, and forked work all keep running on the mount's runtime long after that Effect has settled.
+Under the old `mount`/`hydrate` model this was a real footgun. Each call created its own implicit `ManagedRuntime`. That runtime's effect resolved right after the tree's **initial render**, not when the app stopped running. Streams, event handlers, and forked work kept running on it long after.
 
-`Effect.provide(scopedLayer)` is `acquireUseRelease` sugar: acquire, run the wrapped effect, then release **when that effect completes**. Wrap it directly around `mount`, and the release runs at mount-resolve — while the mounted tree is still reading from the now-disposed service:
+`Effect.provide(scopedLayer)` is `acquireUseRelease` sugar: acquire, run the wrapped effect, then release **when that effect completes**. Wrapped directly around `mount`, the release ran at mount-resolve, while the mounted tree was still reading from the now-disposed service:
 
 ```typescript
-// ❌ the layer's finalizers run the instant runPromise settles, while the
-// mounted tree keeps running — every subscription now reads a disposed service
+// ❌ (old API) the layer's finalizers ran the instant runPromise settled, while the
+// mounted tree kept running: every subscription then read a disposed service
 Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
 ```
 
-This is exactly what happened with the atom registry layer (`AtomRegistry.layer`, from `effect/unstable/reactivity`) in the [`effect-atom` example](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) (issue #122): every atom-driven region rendered empty, with no error, because the registry the streams read from had already been disposed.
+This is exactly what happened with the atom registry layer (`AtomRegistry.layer`, from `effect/unstable/reactivity`) in the [`effect-atom` example](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) (issue #122). Every atom-driven region rendered empty, with no error, because the registry the streams read from had already been disposed.
+
+`WeftApp` closes this gap structurally instead of by convention. An app owns exactly **one** lazy `ManagedRuntime`. `WeftApp.make(layer)` builds the layer on the first `mount`/`hydrate`. It releases only at `WeftApp.dispose(app)`, never when any individual mount's render effect resolves.
+
+A scoped layer (`AtomRegistry.layer`, `RouterLive`) therefore just works passed straight to `WeftApp.make`. There is no `mountScoped`, no `Effect.never`, and no manual `ManagedRuntime` composition to reach for.
 
-The fix is to give the scoped layer a lifetime that matches the app, not the initial render: provide it **outside** a scoped region that stays open for as long as the app should run, and mount inside that region with `mountScoped` (which ties `unmount` to the region's scope instead of to the resolution of the mount effect). An `Effect.never` (or `Deferred.await` on a shutdown signal) keeps the region — and therefore the layer — alive until something explicitly closes it. See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for the recipe, including the `ManagedRuntime` alternative when a scoped region isn't a good fit.
+See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for the recipes. They cover `memoMap` sharing across apps and the `Effect.acquireRelease(make, dispose)` pattern for binding an app's own lifetime to an external scope. There is deliberately no `makeScoped`.
 
 ## The router's render-time context seam
 
-A plain `mount`/`hydrate` discharges `R` at the call site. But under `@weftui/router`, the tree does not render in the context of the effect that called `render` — each request dispatches through platform's HTTP layer in its own managed context, and the reactive outlet drains in the top render context, not in any intermediate node's. Providing a service _ambiently_ around the render would be lost before it reached a route component.
+A plain `WeftApp.mount`/`WeftApp.hydrate` discharges `R` once, at `WeftApp.make`. But under `@weftui/router`, the tree does not render in the context of the effect that called `render`.
 
-So the router exposes an explicit **`context` seam** — a `Layer` threaded to the document shell and every route, layout, and leaf:
+Each request dispatches through platform's HTTP layer in its own managed context. The reactive outlet drains in the top render context, not in any intermediate node's. Providing a service _ambiently_ around the render would be lost before it reached a route component.
+
+So the router exposes an explicit **`context` seam**, a `Layer` threaded to the document shell and every route, layout, and leaf:
 
 ```typescript
 class Greeting extends Context.Service<Greeting, { text: string }>()("Greeting") {}
@@ -55,17 +61,21 @@ class Greeting extends Context.Service<Greeting, { text: string }>()("Greeting")
 // server entry
 RouterServer.render(App, { document, url, context: Layer.succeed(Greeting, { text: "hi" }) });
 
-// client entry — same seam, so the hydrated tree reads the same services
+// client entry: same seam, so the hydrated tree reads the same services
 RouterLive(App, { context: DocsLive });
 ```
 
-The seam is **symmetric** (same shape on both sides) and **type-tracked**: the def's aggregate residual `R` is discharged here, so a missing provide is a compile error rather than a runtime 500. The residual is `AppServices<R>` — the def's `R` minus what the router itself threads (`Router`, `Router.Outlet`, `AppRpcClientTag`). An app with no app-services needs no `context`; a loosely-typed `RouterDef<any, any>` may omit it. This is how the website provides its `Docs` service to every page — see [Add Routing](https://weftui.dev/docs/how-to/add-routing).
+The seam is **symmetric** (same shape on both sides) and **type-tracked**. The def's aggregate residual `R` is discharged here, so a missing provide is a compile error rather than a runtime 500. The residual is `AppServices<R>`: the def's `R` minus what the router itself threads (`Router`, `Router.Outlet`, `AppRpcClientTag`). An app with no app-services needs no `context`; a loosely-typed `RouterDef<any, any>` may omit it.
+
+This is how the website provides its `Docs` service to every page. See [Add Routing](https://weftui.dev/docs/how-to/add-routing).
 
 ## Server-only services: `ServerTag`
 
-Some services must _never_ run in the browser — a database handle, a private credential, an rpc handler's backing store. Declare those with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) instead of `Context.Service`. It behaves exactly like `Context.Service`, but its identifier carries a **server-only brand**.
+Some services must _never_ run in the browser: a database handle, a private credential, an rpc handler's backing store. Declare those with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) instead of `Context.Service`. It behaves exactly like `Context.Service`, but its identifier carries a **server-only brand**.
+
+The brand's job is to turn a leak into a **compile error at the `hydrate` call site**. A `Boundary.rpc` handler legitimately reads server-only services on the server, but they must not survive into client code. Since `render` only ever touches the _decoded result_ (never the service), a correctly-written boundary keeps its output `R` free of the brand.
 
-The brand's job is to turn a leak into a **compile error at the `hydrate` call site**. A `Boundary.rpc` handler legitimately reads server-only services on the server, but they must not survive into client code: since `render` only ever touches the _decoded result_ (never the service), a correctly-written boundary keeps its output `R` free of the brand. If a branded tag ever leaks into `render` and reaches the client requirement channel, `hydrate`'s `AssertNoServerOnly` resolves `R` to a compile-error sentinel — you learn at build time, not from a runtime defect.
+If a branded tag leaks into `render` and reaches the client requirement channel, `hydrate`'s `AssertNoServerOnly` resolves `R` to a compile-error sentinel. You learn at build time, not from a runtime defect.
 
 ```typescript
 import { ServerTag } from "@weftui/core";
@@ -77,15 +87,15 @@ class Db extends ServerTag("Db")<Db, { query: (sql: string) => Effect.Effect<Row
 ## The whole picture
 
 - A component reads a service with `yield* Service`; the requirement enters `R`.
-- `R` accumulates through the tree and is discharged **once** — at `mount`/`hydrate`, or through the router's `context` seam.
+- `R` accumulates through the tree and is discharged **once**: at `WeftApp.make`, or through the router's `context` seam.
 - The same services flow to the same components on the server and the client, because it is the same tree.
 - `ServerTag` brands the services that must stay server-side, enforced at the `hydrate` boundary.
 
 ## See also
 
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why services flow through the tree at all
-- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how `R` accumulates from children and reactive props
-- [Provide Services](https://weftui.dev/docs/how-to/provide-services) — recipes for value layers, scoped layers with `mountScoped`, and `ManagedRuntime`
-- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — providing app services through the router `context` seam
-- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc) — where `ServerTag` and the rpc handler Layer meet
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): why services flow through the tree at all
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): how `R` accumulates from children and reactive props
+- [Provide Services](https://weftui.dev/docs/how-to/provide-services): recipes for app layers, scoped layers, and binding an app's lifetime to an external scope
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing): providing app services through the router `context` seam
+- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc): where `ServerTag` and the rpc handler Layer meet
 - [`ServerTag` API reference](https://weftui.dev/docs/reference/core#servertag)