@weftui/dom 0.27.0 → 0.28.0

package/docs/explanation/rendering-model.md

@@ -46,9 +46,9 @@ This also fixes the update _shape_. Because the structure is fixed, an update is
 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
 

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

@@ -15,37 +15,33 @@ When a component does `yield* ThemeService`, `ThemeService` enters that node's r
 
 ```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 with `Layer.scoped`, backed by an `acquireRelease` — 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.
-
-`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:
+Under the old `mount`/`hydrate` model this was a real footgun. Each call created its own implicit `ManagedRuntime`, and that runtime's effect resolved right after the tree's **initial render** — not when the app stopped running — while 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**. 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.
 
-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.
+`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`, and 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`, with no `mountScoped`, no `Effect.never`, and no manual `ManagedRuntime` composition to reach for. See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for the recipes — including `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` — 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.
 
 So the router exposes an explicit **`context` seam** — a `Layer` threaded to the document shell and every route, layout, and leaf:
 
@@ -77,7 +73,7 @@ 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.
 
@@ -85,7 +81,7 @@ class Db extends ServerTag("Db")<Db, { query: (sql: string) => Effect.Effect<Row
 
 - [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`
+- [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)

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

@@ -177,21 +177,21 @@ Router.route("users/:id", {
 
 ## Client setup
 
-On the client, provide the `Router` via `RouterLive(def)` and render `RouterApp(def)`. `RouterLive` is a **scoped layer** — it owns the `popstate` listener and the same-origin link-click interceptor — so it must outlive the mount. Provide it through a long-lived `ManagedRuntime` rather than `Effect.provide` at the node level:
+On the client, provide the `Router` via `RouterLive(def)` and render `RouterApp(def)`. `RouterLive` is a **scoped layer** — it owns the `popstate` listener and the same-origin link-click interceptor — so it must outlive the mount. Give it to `WeftApp.make`: the app runtime owns it for the app's lifetime, built lazily on first hydrate and released only at `WeftApp.dispose`. Do not wrap `Effect.provide` around the mount/hydrate call — services come exclusively from the app layer.
 
 ```typescript
 // entry-client.ts
-import { hydrate } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { RouterApp, RouterLive } from "@weftui/router/client";
-import { ManagedRuntime } from "effect";
+import { Effect } from "effect";
 import { App } from "./app";
 
 const root = document.getElementById("root")!;
-const runtime = ManagedRuntime.make(RouterLive(App));
-void runtime.runPromise(hydrate(RouterApp(App), root));
+const app = WeftApp.make(RouterLive(App));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 ```
 
-For a client-only app (no SSR), swap `hydrate` for `mount` — everything else is identical.
+For a client-only app (no SSR), swap `WeftApp.hydrate` for `WeftApp.mount` — everything else is identical.
 
 ### Link interception
 
@@ -280,7 +280,7 @@ export const handler = RouterServer.toWebHandler(App, { document: documentShell
 
 ### `effect/unstable/httpapi` is the spine
 
-The tree is the authoring surface, but `effect/unstable/httpapi`'s `HttpApi` is the **single source of truth** for paths and schemas. Sealing the tree with `Router.router(...)` builds it once (`buildHttpApi`) and stamps it onto `def.httpApi`: a single `"pages"` group with one GET endpoint per leaf at its full path pattern, carrying `setPath(pathSchema)`, `setUrlParams(querySchema)`, and a `RouterNotFound → 404` error. Both sides read that one definition, so they always agree:
+The tree is the authoring surface, but `effect/unstable/httpapi`'s `HttpApi` is the **single source of truth** for paths and schemas. Sealing the tree with `Router.router(...)` builds it once (`buildHttpApi`) and stamps it onto `def.httpApi`: a single `"pages"` group with one GET endpoint per leaf at its full path pattern, carrying `params: pathSchema`, `query: querySchema`, and a `RouterNotFound → 404` error. Both sides read that one definition, so they always agree:
 
 - **Server** — `RouterServer` dispatches through `HttpApiBuilder` (platform owns request→leaf matching, path/query decode, and the 404 status).
 - **Client** — `RouterLive` derives a real `HttpApiClient` from the same `def.httpApi` (exposed as `Router.httpApiClient`) for network work. SPA URL→leaf resolution stays **local** (there is no public client-side "match this URL against my `HttpApi`" utility in platform), fed from the same endpoint definitions so it never drifts from the server.

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

@@ -56,7 +56,7 @@ The return type here is `Effect.Effect<Node, never, never>` — itself a valid `
 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 and is torn down automatically when the
-component unmounts (or when the whole tree unmounts via the `MountHandle`). The renderer
+component unmounts (or when its root unmounts via `RootHandle.unmount()`). 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.
 
@@ -235,12 +235,14 @@ const UserAvatar = Component.gen(function* (props: { userId: string }) {
 const avatar = UserAvatar({ userId: "123" });
 ```
 
-Provide the service at the mount boundary:
+Give the service to the app layer:
 
 ```typescript
-void Effect.runPromise(
-  mount(App(), document.getElementById("root")!).pipe(Effect.provide(UserServiceLive)),
-);
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+
+const app = WeftApp.make(UserServiceLive);
+void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
 ## Returning fragments

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

@@ -88,11 +88,13 @@ export const render = (url: string) =>
 
 ```typescript
 // entry-client.ts — network client posting to /_eui/rpc
+import { WeftApp } from "@weftui/dom/client";
 import { RouterApp, RouterLive } from "@weftui/router/client";
+import { Effect } from "effect";
 import { StockRpcs } from "./data/inventory";
 
-const runtime = ManagedRuntime.make(RouterLive(App, { rpc: { group: StockRpcs } }));
-void runtime.runPromise(hydrate(RouterApp(App), root));
+const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 ```
 
 - **Server** ([`RouterServer`](https://weftui.dev/docs/reference/router#routerserver)) mounts the handler Layer at `POST /_eui/rpc` (so a client refetch re-runs it on the server) **and** exposes an in-process client over the same handlers for SSR resolution — never a network hop.

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

@@ -2,123 +2,101 @@
 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.
+description: Provide plain and scoped Layers to a WeftApp — app layers for the common case, scoped layers that just work, memoMap sharing, and binding an app's lifetime to a scope.
 ---
 
 # Provide Services
 
-**Goal:** provide a `Layer` to the mounted app so its components can read services with `yield* Service`.
+**Goal:** provide a `Layer` to a `WeftApp` 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 — app layers
 
-## 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.
+Pass the layer to `WeftApp.make`. This is the common case and needs nothing else — the layer builds lazily on first mount, and every component, event handler, and stream subscription in every root mounted from `app` can read it.
 
 ```typescript
-import { mount } from "@weftui/dom/client";
-import { Effect, pipe } from "effect";
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
 import { App } from "./app";
 import { ThemeServiceLive } from "./theme-service";
 
 const root = document.getElementById("root")!;
 
-const program = pipe(mount(App(), root), Effect.provide(ThemeServiceLive));
-
-Effect.runPromise(program);
+const app = WeftApp.make(ThemeServiceLive);
+void Effect.runPromise(WeftApp.mount(app, App(), root));
 ```
 
-## Recipe 2 — scoped layers with `mountScoped`
+## Recipe 2 — scoped layers just work
+
+A **scoped** layer — `Layer.effect` backed by `acquireRelease`, or anything else that owns a subscription, listener, or registry — needs nothing different from Recipe 1. The app owns one lazy `ManagedRuntime`: the layer builds on first mount and releases only at `WeftApp.dispose(app)`, not when any individual mount's render effect resolves. There is no `mountScoped`, no `Effect.never`, no manual scope threading.
 
-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.
+`AtomRegistry.layer` (from `effect/unstable/reactivity`) is a real scoped layer — its atom subscriptions are fibers forked for the app's whole lifetime:
 
 ```typescript
-import { mountScoped } from "@weftui/dom/client";
-import { Deferred, Effect, Fiber, pipe } from "effect";
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { AtomRegistry } from "effect/unstable/reactivity";
 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));
+const app = WeftApp.make(AtomRegistry.layer);
+void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
-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:
+`RouterLive` (from `@weftui/router/client`) is another — it owns the `popstate` listener and the same-origin link-click interceptor for as long as the app runs:
 
 ```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));
+const app = WeftApp.make(RouterLive(App, { rpc: { group: StockRpcs } }));
+void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
 ```
 
-`hydrateScoped` is the SSR counterpart — same composition, swap `mountScoped` for `hydrateScoped`.
+Both examples are runnable in full at [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) and [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr).
 
-## Recipe 3 — `ManagedRuntime` with plain `mount`
+## Recipe 3 — sharing layer memoization with `memoMap`
 
-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.
+`WeftApp.make(layer, { memoMap })` accepts an explicit `Layer.MemoMap`, so multiple `WeftApp` instances can share layer construction — for example, building one app per test case while reusing an expensive shared dependency's memoized build across them:
 
 ```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);
+import { WeftApp } from "@weftui/dom/client";
+import { Layer } from "effect";
 
-await runtime.runPromise(mount(App(), root));
+const memoMap = Layer.makeMemoMap();
 
-// later:
-// await runtime.dispose();
+const appA = WeftApp.make(SharedLive, { memoMap });
+const appB = WeftApp.make(SharedLive, { memoMap });
 ```
 
-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.
+Most apps have exactly one `WeftApp` and never need this option.
 
-## Anti-patterns
+## Recipe 4 — binding an app's lifetime to a scope
 
-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.
+There is deliberately no `makeScoped`. To tie an app's disposal to a `Scope` you already manage — a framework integration or a test harness that owns one — compose it yourself with `Effect.acquireRelease`:
 
 ```typescript
-// ❌ plain mount: the layer releases the instant runPromise settles
-Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
+import { Effect } from "effect";
+import { WeftApp } from "@weftui/dom/client";
+import { AppLive } from "./app-live";
+
+const acquireApp = Effect.acquireRelease(
+  Effect.sync(() => WeftApp.make(AppLive)),
+  (app) => WeftApp.dispose(app),
+);
 ```
 
+`acquireApp` yields a `WeftApp` and registers `WeftApp.dispose` as a finalizer on whatever scope the surrounding effect runs in — closing that scope tears the app down the same way `WeftApp.dispose` normally would (roots, then layers, then the error hub).
+
+## Anti-pattern: `Effect.provide` around the mount call
+
 ```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));
+// ❌ does nothing useful: WeftApp.mount's R is always `never`, and services
+// come exclusively from the app layer — a wrapped Effect.provide never
+// reaches components, handlers, or stream subscriptions
+Effect.runPromise(pipe(WeftApp.mount(app, App(), root), Effect.provide(SomeLayer)));
 ```
 
-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.
+`WeftApp.mount`/`WeftApp.hydrate` return an effect whose requirement channel is always `never` — there is no `R` left for `Effect.provide` to discharge. Any service a component needs must be in the layer passed to `WeftApp.make`.
 
 ## 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 (`AtomRegistry.layer` from `effect/unstable/reactivity`) mounted with this composition
+- [Services and Context](https://weftui.dev/docs/explanation/services-and-context) — how `R` accumulates and discharges at `WeftApp.make`, and why scoped layers no longer need special handling
+- [`WeftApp` reference](https://weftui.dev/docs/reference/dom) — full signatures for `make`, `mount`, `hydrate`, `dispose`
+- [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) — a real scoped layer (`AtomRegistry.layer`)
+- [examples/shared-state-islands](https://github.com/stefvw93/weft/tree/main/examples/shared-state-islands) — one app layer shared by reference across multiple mounted roots

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

@@ -12,7 +12,7 @@ Weft renders on the server and **hydrates** on the client: the server produces H
 ## 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.
+- **Client** — `@weftui/dom/client`'s `WeftApp.hydrate` walks the server DOM, adopts it, wires up reactivity and event handlers, and resumes from the inline data. It does **not** re-render from scratch.
 
 ```typescript
 // server entry
@@ -25,12 +25,13 @@ export const render = (): Promise<string> => Effect.runPromise(renderToStringHyd
 
 ```typescript
 // client entry
-import { hydrate } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect } from "effect";
 import { App } from "./app";
 
 const root = document.getElementById("root")!;
-void Effect.runPromise(hydrate(App(), root));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.hydrate(app, 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.

package/docs/index.md

@@ -10,7 +10,7 @@ The docs follow the [Diátaxis](https://diataxis.fr) model. Pick your entry poin
 
 **[→ 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`
+1. [Your First App](https://weftui.dev/docs/tutorial/01-your-first-app) — `h` and `WeftApp`
 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
@@ -31,7 +31,7 @@ New to the model itself? Read [The Rendering Model](https://weftui.dev/docs/expl
 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/dom`** — the renderer: `./client` (`WeftApp.mount`/`WeftApp.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).