@weftui/router 0.27.0 → 0.28.0

package/README.md

@@ -9,9 +9,11 @@ Three entry points mirror `@weftui/dom`: `@weftui/router` (authoring + universal
 ## Installation
 
 ```bash
-npm install @weftui/core @weftui/dom @weftui/router effect
+npm install @weftui/core @weftui/dom @weftui/router effect@beta
 ```
 
+Weft tracks Effect 4's beta line. This release is built and tested against `effect@4.0.0-beta.98`; the peer range accepts newer 4.0 betas, which may contain upstream breaking changes.
+
 `effect` is a peer dependency; `@weftui/core` and `@weftui/dom` provide the tree and renderer.
 
 ## Key exports

package/dist/client/index.d.ts

@@ -1,9 +1,8 @@
-import { S as Router, b as NavState, i as RouterDef, m as RouteNode, u as Fields, x as NavigateOptions } from "../compile-DWdMZiMt.js";
-import { n as outletNode, r as HrefArgs, t as RouterApp } from "../outlet-BiFb5gdK.js";
+import { S as Router, b as NavState, i as RouterDef, m as RouteNode, u as Fields, x as NavigateOptions } from "../compile-DySac7KN.js";
+import { n as outletNode, r as HrefArgs, t as RouterApp } from "../outlet-saKduDFz.js";
 import { Effect, Layer, Scope } from "effect";
 import { AppRpcClientTag } from "@weftui/core";
 import { RpcGroup } from "effect/unstable/rpc";
-
 //#region src/client/router-live.d.ts
 /**
  * The residual app services a caller must still provide through the {@link RouterLiveOptions.context}
@@ -44,7 +43,8 @@ interface RouterLiveOptions {
    * descriptive error.
    */
   readonly rpc?: {
-    /** The app's merged `RpcGroup` (pure Schema contract). */readonly group: RpcGroup.RpcGroup<any>;
+    /** The app's merged `RpcGroup` (pure Schema contract). */
+    readonly group: RpcGroup.RpcGroup<any>;
   };
 }
 /**

package/dist/client/index.js

@@ -1,5 +1,5 @@
-import { a as Router, i as setResolvedCommit, n as outletNode, o as getPreload, r as preRunLeaf, t as RouterApp } from "../outlet-ty5ZYKBW.js";
-import { r as match, t as href } from "../href-DD8PoCGO.js";
+import { a as Router, i as setResolvedCommit, n as outletNode, o as getPreload, r as preRunLeaf, t as RouterApp } from "../outlet-C9N4a4_F.js";
+import { r as match, t as href } from "../href-uvJ6b7zz.js";
 import { HttpApiClient } from "effect/unstable/httpapi";
 import { Context, Effect, Exit, Fiber, Layer, Option, Schema, Scope, Stream, SubscriptionRef } from "effect";
 import { AppRpcClientTag, Subscribable } from "@weftui/core";

package/dist/{compile-DWdMZiMt.d.ts → compile-DySac7KN.d.ts}

@@ -1,10 +1,10 @@
 import { HttpApi, HttpApiClient } from "effect/unstable/httpapi";
 import { Context, Effect, Option, Schema } from "effect";
 import { Component, Node, Subscribable } from "@weftui/core";
-
 //#region src/errors.d.ts
 declare const RouterNotFound_base: Schema.Class<RouterNotFound, Schema.TaggedStruct<"RouterNotFound", {
-  /** The path that could not be resolved, when known. */readonly path: Schema.optional<Schema.String>;
+  /** The path that could not be resolved, when known. */
+  readonly path: Schema.optional<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Tagged error raised by {@link notFound} and caught by the router's internal
@@ -28,7 +28,9 @@ declare const notFound: (path?: string) => Effect.Effect<never, RouterNotFound>;
 /** Type guard recognising a {@link RouterNotFound} value regardless of its prototype. */
 declare const isRouterNotFound: (u: unknown) => u is RouterNotFound;
 declare const RouterParamsError_base: Schema.Class<RouterParamsError, Schema.TaggedStruct<"RouterParamsError", {
-  /** Which side of the match failed validation. */readonly source: Schema.Literals<readonly ["path", "query"]>; /** The requested field names, for diagnostics. */
+  /** Which side of the match failed validation. */
+  readonly source: Schema.Literals<readonly ["path", "query"]>;
+  /** The requested field names, for diagnostics. */
   readonly keys: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -52,7 +54,8 @@ type RouteMatch = {
   readonly _tag: "Matched";
   readonly leaf: CompiledLeaf;
   readonly path: Record<string, unknown>;
-  readonly query: Record<string, unknown>; /** Normalized request URL (path + search), used by the outlet as a dedupe key. */
+  readonly query: Record<string, unknown>;
+  /** Normalized request URL (path + search), used by the outlet as a dedupe key. */
   readonly url: string;
 } | {
   readonly _tag: "NotFound";
@@ -66,9 +69,9 @@ interface MatcherEntry {
   readonly leaf: CompiledLeaf;
   readonly regex: RegExp;
   readonly paramNames: readonly string[];
-  /** Path-param schema, read from the endpoint's `setPath` slot. */
+  /** Path-param schema, read from the endpoint's `params` slot. */
   readonly pathSchema: ParamSchema;
-  /** Query schema, read from the endpoint's `setUrlParams` slot. */
+  /** Query schema, read from the endpoint's `query` slot. */
   readonly querySchema: ParamSchema;
 }
 /**
@@ -111,7 +114,7 @@ declare function match(def: RouterDef, url: string): RouteMatch;
  */
 /**
  * The platform `HttpApiClient` derived from a router's `HttpApi` spine. Typed
- * opaquely (`Client<any, …>`) because the spine is `HttpApi.Any` — its
+ * opaquely (`Client<any, …>`) because the spine is `HttpApi.Top` — its
  * group/endpoint shapes are assembled in a runtime loop by `buildHttpApi`, so a
  * precise client type is not recoverable. Present (`Option.some`) on the client
  * (`RouterLive`), absent (`Option.none`) on the server, which is itself the origin.
@@ -142,7 +145,8 @@ interface NavigateOptions {
   readonly replace?: boolean;
 }
 declare const Router_base: Context.ServiceClass<Router, "@weftui/router/Router", {
-  /** The current match as a hot `Subscribable`; drives the outlet. */readonly currentMatch: Subscribable.Subscribable<RouteMatch>;
+  /** The current match as a hot `Subscribable`; drives the outlet. */
+  readonly currentMatch: Subscribable.Subscribable<RouteMatch>;
   /**
    * Navigates to `to` (a path, optionally with a query). On the client this
    * pushes History state and re-renders the affected outlet; on the server it
@@ -452,14 +456,14 @@ interface CompiledLeaf {
   /**
    * Path-param schema. Its **encoded** side is typed string-encodeable
    * (`Record<string, string | undefined>`) so it satisfies platform's
-   * `HttpApiEndpoint.setPath` constraint without an `as any` cast — param schemas
+   * `HttpApiEndpoint` `params` constraint without an `as any` cast — param schemas
    * round-trip strings, so the `Schema.Struct` value is asserted to this shape.
    */
   readonly pathSchema: Schema.Codec<Record<string, unknown>, Readonly<Record<string, string | undefined>>>;
   /**
    * Query schema. Its **encoded** side is typed string-encodeable
    * (`Record<string, string | ReadonlyArray<string> | undefined>`) so it satisfies
-   * platform's `HttpApiEndpoint.setUrlParams` constraint without a cast.
+   * platform's `HttpApiEndpoint` `query` constraint without a cast.
    */
   readonly querySchema: Schema.Codec<Record<string, unknown>, Readonly<Record<string, string | ReadonlyArray<string> | undefined>>>;
   /** The page's component slot; invoked per render, reads params via `Router.params` / `Router.query`. */
@@ -489,7 +493,7 @@ interface RouterDef<E = any, R = any> {
    * nesting/render metadata platform's flat API can't represent. Built by
    * {@link buildHttpApi} during {@link makeRouter}.
    */
-  readonly httpApi: HttpApi.Any;
+  readonly httpApi: HttpApi.Top;
   /**
    * Phantom marker for the tree's aggregate error channel. Covariant (stores `E`
    * directly) so a fully-static `RouterDef<never, never>` stays assignable to the
@@ -527,20 +531,20 @@ declare function compile(def: {
 /**
  * Builds the authoritative `HttpApi` for a compiled tree (S4): a single `"pages"`
  * group whose endpoints are GET endpoints — one per leaf — at each leaf's full path
- * pattern, carrying `setPath(pathSchema)`, `setUrlParams(querySchema)`, a
+ * pattern, carrying `params: pathSchema`, `query: querySchema`, a
  * `Schema.String` (text/HTML) success, and a `RouterNotFound → 404` error. The tree
  * (not `HttpApi`) is the authoring surface; this is the single source of truth the
  * server dispatch (`HttpApiBuilder`) and the client matcher / derived `HttpApiClient`
  * read from, so both sides agree on paths and schemas.
  *
  * Each leaf's `pathSchema`/`querySchema` are typed string-encodeable (see
- * {@link CompiledLeaf}), so `setPath`/`setUrlParams` need no `as any` casts.
+ * {@link CompiledLeaf}), so the `params`/`query` options need no `as any` casts.
  *
  * `Boundary.rpc` data no longer rides this spine: it resolves through the app's
  * merged `RpcGroup` over the ambient `AppRpcClient` (`POST /_eui/rpc`), wired
  * explicitly into `RouterServer`/`RouterLive`. The matcher reads only `"pages"`.
  */
-declare function buildHttpApi(leaves: readonly CompiledLeaf[]): HttpApi.Any;
+declare function buildHttpApi(leaves: readonly CompiledLeaf[]): HttpApi.Top;
 /**
  * Seals a route tree into a {@link RouterDef}, compiling it eagerly (so leaf
  * references are stamped for `href`), building its authoritative {@link buildHttpApi}

package/dist/{href-DD8PoCGO.js → href-uvJ6b7zz.js}

@@ -1,4 +1,4 @@
-import { l as leafRegistry } from "./outlet-ty5ZYKBW.js";
+import { l as leafRegistry } from "./outlet-C9N4a4_F.js";
 import { Result, Schema } from "effect";
 //#region src/matcher.ts
 /** Escapes a literal path segment for inclusion in a `RegExp`. */
@@ -50,7 +50,7 @@ function compileMatchers(def) {
 	const endpoints = def.httpApi.groups["pages"]?.endpoints ?? {};
 	const entries = [];
 	for (const endpoint of Object.values(endpoints)) {
-		const leaf = leafById.get(endpoint.name);
+		const leaf = leafById.get(endpoint.identifier);
 		if (leaf === void 0) continue;
 		entries.push({
 			leaf,

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { A as notFound, C as RouterHttpApiClient, D as RouterNotFound, E as match, O as RouterParamsError, S as Router, T as compileMatchers, _ as TreeE, a as RouterOptions, b as NavState, c as leafRegistry, d as FieldsType, f as LayoutNode, g as SubtreeR, h as SubtreeE, i as RouterDef, k as isRouterNotFound, l as ComponentSlot, m as RouteNode, n as CompiledLayout, o as buildHttpApi, p as RouteHandlerProps, r as CompiledLeaf, s as compile, t as Compiled, u as Fields, v as TreeNode, w as RouteMatch, x as NavigateOptions, y as TreeR } from "./compile-DWdMZiMt.js";
-import { i as href, n as outletNode, r as HrefArgs, t as RouterApp } from "./outlet-BiFb5gdK.js";
+import { A as notFound, C as RouterHttpApiClient, D as RouterNotFound, E as match, O as RouterParamsError, S as Router, T as compileMatchers, _ as TreeE, a as RouterOptions, b as NavState, c as leafRegistry, d as FieldsType, f as LayoutNode, g as SubtreeR, h as SubtreeE, i as RouterDef, k as isRouterNotFound, l as ComponentSlot, m as RouteNode, n as CompiledLayout, o as buildHttpApi, p as RouteHandlerProps, r as CompiledLeaf, s as compile, t as Compiled, u as Fields, v as TreeNode, w as RouteMatch, x as NavigateOptions, y as TreeR } from "./compile-DySac7KN.js";
+import { i as href, n as outletNode, r as HrefArgs, t as RouterApp } from "./outlet-saKduDFz.js";
 export { type Compiled, type CompiledLayout, type CompiledLeaf, type ComponentSlot, type Fields, type FieldsType, type HrefArgs, type LayoutNode, type NavState, type NavigateOptions, type RouteHandlerProps, type RouteMatch, type RouteNode, Router, RouterApp, type RouterDef, type RouterHttpApiClient, RouterNotFound, type RouterOptions, RouterParamsError, type SubtreeE, type SubtreeR, type TreeE, type TreeNode, type TreeR, buildHttpApi, compile, compileMatchers, href, isRouterNotFound, leafRegistry, match, notFound, outletNode };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as Router, c as compile, d as RouterParamsError, f as isRouterNotFound, l as leafRegistry, n as outletNode, p as notFound, s as buildHttpApi, t as RouterApp, u as RouterNotFound } from "./outlet-ty5ZYKBW.js";
-import { n as compileMatchers, r as match, t as href } from "./href-DD8PoCGO.js";
+import { a as Router, c as compile, d as RouterParamsError, f as isRouterNotFound, l as leafRegistry, n as outletNode, p as notFound, s as buildHttpApi, t as RouterApp, u as RouterNotFound } from "./outlet-C9N4a4_F.js";
+import { n as compileMatchers, r as match, t as href } from "./href-uvJ6b7zz.js";
 export { Router, RouterApp, RouterNotFound, RouterParamsError, buildHttpApi, compile, compileMatchers, href, isRouterNotFound, leafRegistry, match, notFound, outletNode };

package/dist/{outlet-ty5ZYKBW.js → outlet-C9N4a4_F.js}

@@ -157,14 +157,14 @@ function compile(def) {
 /**
 * Builds the authoritative `HttpApi` for a compiled tree (S4): a single `"pages"`
 * group whose endpoints are GET endpoints — one per leaf — at each leaf's full path
-* pattern, carrying `setPath(pathSchema)`, `setUrlParams(querySchema)`, a
+* pattern, carrying `params: pathSchema`, `query: querySchema`, a
 * `Schema.String` (text/HTML) success, and a `RouterNotFound → 404` error. The tree
 * (not `HttpApi`) is the authoring surface; this is the single source of truth the
 * server dispatch (`HttpApiBuilder`) and the client matcher / derived `HttpApiClient`
 * read from, so both sides agree on paths and schemas.
 *
 * Each leaf's `pathSchema`/`querySchema` are typed string-encodeable (see
-* {@link CompiledLeaf}), so `setPath`/`setUrlParams` need no `as any` casts.
+* {@link CompiledLeaf}), so the `params`/`query` options need no `as any` casts.
 *
 * `Boundary.rpc` data no longer rides this spine: it resolves through the app's
 * merged `RpcGroup` over the ambient `AppRpcClient` (`POST /_eui/rpc`), wired

package/dist/{outlet-BiFb5gdK.d.ts → outlet-saKduDFz.d.ts}

@@ -1,6 +1,5 @@
-import { D as RouterNotFound, S as Router, d as FieldsType, i as RouterDef, m as RouteNode, u as Fields } from "./compile-DWdMZiMt.js";
+import { D as RouterNotFound, S as Router, d as FieldsType, i as RouterDef, m as RouteNode, u as Fields } from "./compile-DySac7KN.js";
 import { Node } from "@weftui/core";
-
 //#region src/href.d.ts
 /**
  * The `href` argument object for a leaf with path fields `Path` and query fields

package/dist/server/index.d.ts

@@ -1,8 +1,7 @@
-import { S as Router, i as RouterDef, l as ComponentSlot } from "../compile-DWdMZiMt.js";
+import { S as Router, i as RouterDef, l as ComponentSlot } from "../compile-DySac7KN.js";
 import { Effect, Layer } from "effect";
 import { AppRpcClientTag } from "@weftui/core";
 import { RpcGroup } from "effect/unstable/rpc";
-
 //#region src/server/router-server.d.ts
 /**
  * Server-side rendering for a {@link RouterDef}. Dispatch runs through the

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { a as Router, f as isRouterNotFound, n as outletNode, u as RouterNotFound } from "../outlet-ty5ZYKBW.js";
+import { a as Router, f as isRouterNotFound, n as outletNode, u as RouterNotFound } from "../outlet-C9N4a4_F.js";
 import { HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Cause, Effect, Exit, Layer, Option, Schema, Scope, Stream } from "effect";
 import { AppRpcClientTag, Subscribable } from "@weftui/core";

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

@@ -38,9 +38,9 @@ The channel algebra is the whole reason they exist: `catchTag("Foo", …)` remov
 
 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, and it can still fail later: a `Stream` backing a `Boundary.rpc` resource might raise `RouterNotFound` after a client-side navigation, for instance. If a `BoundaryContext` encloses the region, the failure routes to it exactly as above, and the boundary's fallback swaps in.
 
-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 the subscription fiber's failure exit is left **unobserved**. The Effect runtime itself then reports it — `"Fiber terminated with an unhandled error"` — because Weft raises that fiber's `FiberRef.unhandledErrorLogLevel` from the ambient default (`Debug`) to `LogLevel.Error` and annotates the log with `weft.region`, identifying 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. Interruption — the ordinary case of unmount tearing down the region's scope — is never reported; only genuine failures are.
+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. When that exit is a failure whose cause is not interruption-only, Weft reports it explicitly via `Effect.logError(exit.cause)`, 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.
 
-This is deliberate: rather than a Weft-specific error-reporting config, visibility is controlled by the same knobs any Effect program uses — `Logger.withMinimumLogLevel` to filter it, `Effect.withUnhandledErrorLogLevel` to change how loudly (or quietly) unhandled fiber exits are reported elsewhere in your program. 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.
+This is deliberate: rather than leaving the failure to whatever the Effect runtime would otherwise do with an unobserved fiber exit, Weft observes and logs it itself, so visibility is 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. 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.
 
 ## Suspense boundaries
 

package/docs/explanation/reactive-primitives.md

@@ -147,7 +147,7 @@ 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}`),
   ),

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).
 

package/docs/reference/dom.md

@@ -2,7 +2,7 @@
 title: "@weftui/dom"
 order: 2
 section: reference
-description: Full API surface for @weftui/dom — the client renderer (mount, hydrate) and the server renderer (renderToString and streaming variants).
+description: Full API surface for @weftui/dom — the WeftApp client runtime (make, mount, hydrate, errors, dispose) and the server renderer (renderToString and streaming variants).
 ---
 
 # @weftui/dom API Reference
@@ -14,70 +14,191 @@ for a narrative walkthrough.
 
 ## `@weftui/dom/client`
 
-### `mount`
+`WeftApp` is the client entry point's app namespace (`export * as WeftApp from
+"./weft-app"`). One `WeftApp` value is one lazily-built `ManagedRuntime` (the app
+layer) + one root `Scope` + one unhandled-error hub. Each `WeftApp.mount` /
+`WeftApp.hydrate` call creates a child **root scope** under the app scope;
+layer-built services are shared **by reference** across every root mounted from the
+same app (layer memoization), which is what makes cross-island reactive state work
+(see [examples/shared-state-islands](https://github.com/stefvw93/weft/tree/main/examples/shared-state-islands)). The
+barrel also re-exports `MountError`, `HydrateError`, `RootHandle`, `UnhandledError`,
+and the `WeftApp` interface's type as `WeftAppType` (renamed on export to avoid
+colliding with the `WeftApp` namespace import).
+
+### `WeftApp.make`
+
+```ts
+const make: {
+  (): WeftApp<never, never>;
+  <R, E>(
+    layer: Layer.Layer<R, E, never>,
+    options?: { readonly memoMap?: Layer.MemoMap },
+  ): WeftApp<R, E>;
+};
+```
+
+Creates a `WeftApp` from an app layer. Synchronous and side-effect-free with
+respect to the layer: the layer builds **lazily** on the first `mount` / `hydrate`
+(or the first direct `app.runtime` run) — `ManagedRuntime.make` semantics. A layer
+whose construction has an observable side effect shows that effect only after the
+first mount, never at `make` time. `options.memoMap` shares layer memoization
+across multiple `WeftApp` instances.
+
+There is deliberately no `makeScoped`. To bind an app's lifetime to a scope,
+compose it yourself:
+
+```ts
+const acquireApp = Effect.acquireRelease(
+  Effect.sync(() => WeftApp.make(AppLive)),
+  (app) => WeftApp.dispose(app),
+);
+```
+
+### `WeftApp.mount`
+
+```ts
+const mount: <R, E>(
+  app: WeftApp<R, E>,
+  node: Renderable,
+  root: HTMLElement,
+) => Effect.Effect<RootHandle, E | MountError>;
+```
+
+Mounts `node` into `root` as a new root of `app`. Self-contained — the returned
+effect's requirement channel is `never`, so it runs with a bare `Effect.runPromise`;
+services come exclusively from the app layer, and an `Effect.provide` wrapped around
+this call does not reach components. Clears `root`'s existing children, renders,
+appends the result. Completes after initial render; streams keep running in the
+background, owned by the root's scope (a child of the app scope). The app layer
+builds lazily here on first mount; its error channel `E` surfaces at that point. On
+render failure the root scope is closed before the error propagates; the app
+runtime and other roots are untouched. Mounting on a disposed app fails — it does
+not hang.
+
+### `WeftApp.hydrate`
+
+```ts
+function hydrate<A extends Renderable, R = never, E = never>(
+  app: WeftApp<R, E>,
+  node: A,
+  root: HTMLElement,
+): [AssertNoServerOnly<CoreNode.Context<A>>] extends [CoreNode.Context<A>]
+  ? Effect.Effect<RootHandle, E | HydrateError>
+  : ServerOnlyLeak;
+```
+
+Continues, on the client, the DOM produced on the server by
+`renderToStringHydratable` / `renderToStreamHydratable`, as a new root of `app`.
+Unlike `mount`, does **not** clear `root`: it walks the node tree in lockstep with
+the existing server DOM, adopting nodes in place. Error channel is `E |
+HydrateError` (adds `HydrationMismatchError` on top of everything `mount` can fail
+with). Preserves the compile-time `AssertNoServerOnly` → `ServerOnlyLeak` guard: a
+server-only requirement left in `node`'s context degrades the return type to the
+`ServerOnlyLeak` sentinel (compile error at the call site) instead of a runtime
+failure. Hydration mechanics — the readiness barrier, stream-id seeding — are
+otherwise unchanged from `mount`.
+
+### `WeftApp.errors`
 
 ```ts
-mount(node: Renderable, target: Element): Effect<MountHandle, RenderError, R>
+const errors: <R, E>(app: WeftApp<R, E>) => Stream.Stream<UnhandledError>;
 ```
 
-Renders a Weft `node` into `target` for a fresh (non-SSR) page, building real DOM
-and starting every reactive stream. Returns a `MountHandle` whose scope owns the
-mounted tree; closing it tears the tree down. Use `mount` for purely client-rendered
-apps; use `hydrate` when the markup already exists from SSR.
+The app's unhandled-error stream. While at least one subscriber exists, the default
+`Effect.logError` fallback is suppressed and every `UnhandledError` is delivered to
+all subscribers. With zero subscribers, each unhandled error runs the default log
+(annotated with `weft.region`) instead. No replay — a subscriber sees only errors
+published after it subscribed; multiple concurrent subscribers each receive every
+subsequent error. When the last subscriber unsubscribes, the default log resumes.
 
-### `hydrate`
+### `WeftApp.dispose`
 
 ```ts
-hydrate(node: Renderable, target: Element): Effect<MountHandle, HydrationMismatchError | RenderError, R>
+const dispose: <R, E>(app: WeftApp<R, E>) => Effect.Effect<void>;
 ```
 
-Adopts server-rendered DOM **in place** inside `target` and resumes reactivity
-without re-creating elements. The `node` must produce a tree structurally identical
-to what the server rendered; a divergence fails with `HydrationMismatchError`. This
-is the flash-free path: no second render, the existing nodes simply become live.
+Disposes the app: closes every root scope (in mount order), then releases the
+runtime's layers (`runtime.disposeEffect`), then shuts the error hub down.
+Idempotent — teardown effects run once. Subsequent `mount` / `hydrate` calls fail.
 
-### `mountScoped`
+### `WeftApp<R, E>` (`WeftAppType`)
 
 ```ts
-mountScoped(app: Renderable, root: HTMLElement): Effect<MountHandle, UnsupportedNodeTypeError | StreamSubscriptionError | RenderError, Scope.Scope>
+interface WeftApp<in R = never, out E = never> {
+  readonly [TypeId]: typeof TypeId;
+  readonly runtime: ManagedRuntime.ManagedRuntime<R, E>;
+}
 ```
 
-Scope-aware `mount`: identical behavior, but requires an ambient `Scope.Scope` in
-`R` and registers `unmount` as a finalizer on it, so the mount lives until that
-scope closes rather than only until the mount effect resolves. Provide any scoped
-layer **outside** a long-lived scoped region so it outlives initial render — see
-[Provide Services](https://weftui.dev/docs/how-to/provide-services) for the composition and
-[Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount)
-for why.
+Re-exported from the barrel as `WeftAppType`. `runtime` is the app's
+`ManagedRuntime`, for running app-level effects against the shared layer outside any
+root — e.g. `app.runtime.runFork(trackPageviews)` (see
+`website/src/entry-client.ts`) or `app.runtime.runPromise(Router.push("/about"))`.
 
-### `hydrateScoped`
+### `RootHandle`
 
 ```ts
-hydrateScoped(app: Renderable, root: HTMLElement): Effect<MountHandle, UnsupportedNodeTypeError | StreamSubscriptionError | RenderError | HydrationMismatchError, Scope.Scope>
+interface RootHandle {
+  readonly element: HTMLElement;
+  unmount(): Effect.Effect<void>;
+}
 ```
 
-Scope-aware `hydrate` — same relationship as `mountScoped` to `mount`, with
-`hydrate`'s error union (`HydrationMismatchError` added) and the same client-only
-compile-time guard: a server-only requirement left in `app`'s `R` degrades the
-return type to `ServerOnlyLeak` via `AssertNoServerOnly`.
+Returned by `mount` / `hydrate`. `element` is the DOM element the root was mounted
+into. `unmount()` closes **this root's scope only**: it interrupts its stream
+subscriptions and any scoped work forked from its event handlers. It does **not**
+dispose the app runtime, touch other roots, or remove the rendered DOM nodes from
+`element`. Idempotent — teardown side effects fire once.
 
-### `MountHandle`
+### `UnhandledError`
 
-The handle returned by `mount`, `hydrate`, `mountScoped`, and `hydrateScoped`. Its
-`unmount()` interrupts every subscription and event handler and disposes the
-mount's `ManagedRuntime`; it does **not** remove the mounted DOM nodes from `root`.
-`unmount` is idempotent — safe to call more than once, including once
-automatically and once explicitly.
+```ts
+interface UnhandledError {
+  readonly cause: Cause.Cause<unknown>;
+  readonly region: string;
+  readonly root: RootHandle;
+}
+```
+
+An error that escaped every user-level handler and reached the app's
+unhandled-error hub, published on `WeftApp.errors(app)`. `region` identifies where
+in the render tree the error escaped. Sources (one entry per failing occurrence):
+
+- a rendered stream subscription failing or dying with **no enclosing `Boundary`**
+  (region e.g. `"attribute:class"`, `"child:stream-3"`),
+- an error escaping the **outermost** `Boundary` recovery (region
+  `"boundary:outermost"`),
+- an event-handler effect **failing or dying** (region `"event:onClick"`) — reported
+  in development and production alike; there is no `NODE_ENV`-gated swallow.
+
+Interrupt-only causes are never published. Errors handled by a nested `Boundary`
+never reach the hub.
+
+### `MountError`
+
+```ts
+type MountError = UnsupportedNodeTypeError | StreamSubscriptionError | RenderError;
+```
+
+Errors `mount` can fail with, beyond the app layer's own error channel `E`.
+
+### `HydrateError`
+
+```ts
+type HydrateError = MountError | HydrationMismatchError;
+```
+
+Everything `MountError` covers, plus `HydrationMismatchError` when the server DOM
+and the node tree diverge.
+
+### `TypeId`
+
+```ts
+const TypeId: unique symbol; // Symbol.for("@weftui/dom/WeftApp")
+```
 
-The runtime backing the handle lives until `unmount` runs, not until the
-`mount`/`hydrate` effect resolves — that effect completes right after initial
-render, while streams and handlers keep running in the background. If `mount` or
-`hydrate` runs inside a region that supplies an ambient `Scope.Scope` (e.g. under
-`Effect.scoped`), `unmount` is auto-registered on that scope as a finalizer, so the
-mount tears down when the scope closes; with no ambient scope, behavior is
-unchanged and `unmount` must be called explicitly. `mountScoped`/`hydrateScoped`
-register the same finalizer explicitly, so the typed variant does not silently
-depend on this auto-registration.
+The unique brand for `WeftApp` values. Internal identity marker; rarely referenced
+directly.
 
 ## `@weftui/dom/server`
 
@@ -136,7 +257,7 @@ Re-exports the renderer error types:
 ## See also
 
 - [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server) — a narrative walkthrough of the server/client split
-- [Provide Services](https://weftui.dev/docs/how-to/provide-services) — recipes for value layers, `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
 - [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — hydrate-in-place and why there is no virtual DOM
-- [Services and Context](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) — why scoped layers need the mount to outlive initial render
+- [Services and Context](https://weftui.dev/docs/explanation/services-and-context) — how services flow from the app layer to every root
 - [`@weftui/core` reference](https://weftui.dev/docs/reference/core) · [`@weftui/router` reference](https://weftui.dev/docs/reference/router)

package/docs/reference/router.md

@@ -203,7 +203,7 @@ RouterApp<E, R>(def: RouterDef<E, R>): Node<Exclude<E, RouterNotFound>, R | Rout
 
 The universal router root node — render this on both server and client. Wraps the nested outlet in the router's internal not-found boundary, so a `RouterNotFound` raised by a page renders the configured `notFound` page in place. Server dispatch runs through `HttpApiBuilder`: a page-raised `RouterNotFound` and a no-match surface their 404 through the platform request pipeline.
 
-`RouterApp` requires `Router` in its environment — provide it via `RouterLive` (client) or `RouterServer` (server), not `Effect.provide` at the node level (that would release the scoped layer immediately).
+`RouterApp` requires `Router` in its environment — provide it via `RouterLive` (client) or `RouterServer` (server), not `Effect.provide` at the node level — services under `WeftApp` come exclusively from the app's layer, not ambient `Effect.provide`.
 
 ### `outletNode` (a.k.a. `RouterOutlet`)
 
@@ -224,11 +224,11 @@ RouterLive(
 ): Layer.Layer<Router | AppRpcClientTag>;
 ```
 
-The client `Router` layer, backed by the History API. Seeds a `SubscriptionRef` from `window.location`, listens for `popstate`, installs the same-origin link-click interceptor, and derives the `HttpApiClient` exposed as `Router.httpApiClient` (over `FetchHttpClient`; `baseUrl` defaults to same-origin). Alongside `Router` it also provides the core [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam — a **network** flat rpc client over the app's merged `RpcGroup` (`RpcClient.make` → `POST /_eui/rpc`) — so `@weftui/dom` can resolve a [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) (hydrated refetch and client-first SPA mount) without depending on this package or `effect/unstable/rpc`. Pass the same merged `group` the server wires into [`RouterServer`](#routerserver). **Scoped** — it must outlive the mount, so provide it through a `ManagedRuntime`:
+The client `Router` layer, backed by the History API. Seeds a `SubscriptionRef` from `window.location`, listens for `popstate`, installs the same-origin link-click interceptor, and derives the `HttpApiClient` exposed as `Router.httpApiClient` (over `FetchHttpClient`; `baseUrl` defaults to same-origin). Alongside `Router` it also provides the core [`AppRpcClientTag`](https://weftui.dev/docs/reference/core#apprpcclienttag) seam — a **network** flat rpc client over the app's merged `RpcGroup` (`RpcClient.make` → `POST /_eui/rpc`) — so `@weftui/dom` can resolve a [`Boundary.rpc`](https://weftui.dev/docs/reference/core#boundaryrpc) (hydrated refetch and client-first SPA mount) without depending on this package or `effect/unstable/rpc`. Pass the same merged `group` the server wires into [`RouterServer`](#routerserver). **Scoped** — it must outlive the mount; give it to `WeftApp.make` and the app runtime owns its lifetime (built lazily on first mount, released at `WeftApp.dispose`):
 
 ```typescript
-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));
 ```
 
 ### Programmatic navigation
@@ -323,7 +323,7 @@ These power the runtime and are exported for tooling/tests; most apps never touc
 | Export                      | Description                                                                                                                                                                    |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `compile(def)`              | Walks a tree into flat `CompiledLeaf`s with merged path/query schemas and layout chains.                                                                                       |
-| `buildHttpApi(leaves)`      | Builds the authoritative `HttpApi` (one `"pages"` group, a GET endpoint per leaf with `setPath`/`setUrlParams` + 404). Called by `Router.router`; the result is `def.httpApi`. |
+| `buildHttpApi(leaves)`      | Builds the authoritative `HttpApi` (one `"pages"` group, a GET endpoint per leaf with `params`/`query` schemas + 404). Called by `Router.router`; the result is `def.httpApi`. |
 | `leafRegistry`              | `WeakMap<RouteNode, CompiledLeaf>` read by `href` to resolve a leaf's pattern/schemas.                                                                                         |
 | `match(compiled, url)`      | Resolves a URL to a `RouteMatch` (`Matched` with decoded `path`/`query`, or `NotFound`).                                                                                       |
 | `compileMatchers(compiled)` | Precompiles per-leaf regex matchers.                                                                                                                                           |

package/docs/tutorial/01-your-first-app.md

@@ -14,9 +14,11 @@ We assume you know [Effect](https://effect.website/docs/getting-started/introduc
 ## Install
 
 ```bash
-npm install @weftui/core @weftui/dom effect
+npm install @weftui/core @weftui/dom effect@beta
 ```
 
+Weft tracks Effect 4's beta line. This release is built and tested against `effect@4.0.0-beta.98`; the peer range accepts newer 4.0 betas, which may contain upstream breaking changes.
+
 `@weftui/core` gives you the element builders and combinators; `@weftui/dom` renders them (its `./client` entry mounts in the browser). `effect` is the peer everything is built on.
 
 ## Build a component
@@ -25,14 +27,15 @@ A **component is a plain function you call** — there is no JSX and no `<Compon
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect } from "effect";
 
 function App() {
   return h.div({ class: "app" }, [h.h1("Hello, Weft"), h.p("A minimal app.")]);
 }
 
-void Effect.runPromise(mount(App(), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
 The `h` namespace is the entry point: every property (`h.div`, `h.h1`, `h.button`, …) is a builder for that HTML tag. A builder takes optional props and children, and returns a `Node`.
@@ -40,7 +43,7 @@ The `h` namespace is the entry point: every property (`h.div`, `h.h1`, `h.button
 ## What just happened
 
 - `App()` returns a **`Node<never, never>`** — the two type parameters are the error channel (`E`) and the requirement channel (`R`), both `never` here because this component neither fails nor needs a service. As your app grows, those channels accumulate what it can fail with and what it depends on. That is the whole point of Weft's types — see [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model).
-- `mount(node, target)` renders the node into `target`, building real DOM and starting any reactive streams. It returns an `Effect<MountHandle>`; run it with your Effect runtime (`Effect.runPromise` is fine for a script).
+- `WeftApp.make()` creates a Weft app — synchronously, with no layer to build yet. `WeftApp.mount(app, node, target)` renders the node into `target`, building real DOM and starting any reactive streams. It returns `Effect<RootHandle, …>` with `R = never`, so a bare `Effect.runPromise` runs it — no `Effect.provide` needed. You will give `WeftApp.make` a `Layer` once components need services — see [Services and Async](https://weftui.dev/docs/tutorial/03-services-and-async).
 - The component function runs **once**. Nothing here re-runs on a timer or a state change — because there is no state yet. That comes next.
 
 ## Next

package/docs/tutorial/02-reactivity.md

@@ -15,7 +15,7 @@ Use Effect's `SubscriptionRef` for component-local state. `SubscriptionRef.chang
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect, SubscriptionRef } from "effect";
 
 const Counter = () =>
@@ -29,7 +29,8 @@ const Counter = () =>
     ]);
   });
 
-void Effect.runPromise(mount(Counter(), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, Counter(), document.getElementById("root")!));
 ```
 
 `Effect.gen` lets you `yield*` the `SubscriptionRef` to set up state **before** building the tree. Because a `Node` is an `Effect`, the component body is an ordinary generator — no hooks, no dependency arrays.

package/docs/tutorial/03-services-and-async.md

@@ -11,12 +11,12 @@ description: Give handlers access to services from the environment, and render a
 
 ## Handlers that use services
 
-An event handler can **return an Effect**, and that Effect runs in the component's environment — so it can read any service you provide at the mount boundary:
+An event handler can **return an Effect**, and that Effect runs in the app's environment — so it can read any service the app's layer provides:
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
-import { Context, Effect, Layer, pipe } from "effect";
+import { WeftApp } from "@weftui/dom/client";
+import { Context, Effect, Layer } from "effect";
 
 class Logger extends Context.Service<Logger, { log: (message: string) => Effect.Effect<void> }>()(
   "Logger",
@@ -38,13 +38,12 @@ const LogButton = () =>
     "Log",
   );
 
-// Provide the layer at mount — every handler in the tree can now read Logger.
-void Effect.runPromise(
-  pipe(mount(LogButton(), document.getElementById("root")!), Effect.provide(LoggerLive)),
-);
+// Give the app the layer — every handler in every root can now read Logger.
+const app = WeftApp.make(LoggerLive);
+void Effect.runPromise(WeftApp.mount(app, LogButton(), document.getElementById("root")!));
 ```
 
-`Logger` entered the tree's requirement channel the moment `LogButton` read it, and you discharged it **once**, at `mount`, with `Effect.provide`. Provide too little and it is a compile error at the mount call. This is Weft's entire dependency-injection story — it is just Effect's. The deeper treatment is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
+`Logger` entered the tree's requirement channel the moment `LogButton` read it, and you discharged it **once**, by passing `LoggerLive` to `WeftApp.make`. Provide too little and it is a compile error — the type of `app` (and so of `WeftApp.mount(app, LogButton(), …)`) names exactly which service is missing. Services come exclusively from the app's layer: an `Effect.provide` wrapped around the `mount` call does **not** reach components or handlers. This is Weft's entire dependency-injection story — it is just Effect's. The deeper treatment is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
 
 ## Async loading states
 
@@ -52,7 +51,7 @@ A component can return a **`Stream<Node>`** to show different content over time.
 
 ```typescript
 import { h } from "@weftui/core";
-import { mount } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect, Stream } from "effect";
 
 const AsyncGreeting = ({ name }: { name: string }) =>
@@ -66,7 +65,10 @@ const AsyncGreeting = ({ name }: { name: string }) =>
     ),
   );
 
-void Effect.runPromise(mount(AsyncGreeting({ name: "World" }), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(
+  WeftApp.mount(app, AsyncGreeting({ name: "World" }), document.getElementById("root")!),
+);
 ```
 
 The stream emits the loading node first, then the resolved node — the renderer swaps the DOM in place on the second emission. This is the raw mechanism; for coordinating _several_ async regions with a single fallback, reach for [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense), which you will meet in the next step.

package/docs/tutorial/04-errors-and-server.md

@@ -42,11 +42,12 @@ export const render = () => Effect.runPromise(renderToStringHydratable(App()));
 
 ```typescript
 // client entry
-import { hydrate } from "@weftui/dom/client";
+import { WeftApp } from "@weftui/dom/client";
 import { Effect } from "effect";
 import { App } from "./app";
 
-void Effect.runPromise(hydrate(App(), document.getElementById("root")!));
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.hydrate(app, App(), document.getElementById("root")!));
 ```
 
 The same side-effect-free `App` is imported by both entries. For server-resolved data that replays into the client without a second request, `Boundary.rpc` extends this model — resolve an rpc on the server, serialize its result into the HTML, replay it on hydrate, then keep the region live for refetch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weftui/router",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Universal nested router for Weft — one route tree, server and client, with type-safe params and href",
   "keywords": [
     "effect",
@@ -44,20 +44,21 @@
     "access": "public"
   },
   "dependencies": {
-    "@weftui/core": "0.27.0",
-    "@weftui/dom": "0.27.0"
+    "@weftui/core": "0.28.0",
+    "@weftui/dom": "0.28.0"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.3",
-    "@types/node": "^25.9.2",
-    "effect": "4.0.0-beta.93",
+    "@types/node": "^26.1.1",
+    "effect": "4.0.0-beta.98",
     "jsdom": "^29.1.1",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2",
-    "vite-plus": "0.2.2"
+    "tstyche": "^7.2.2",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.5",
+    "vite-plus": "0.2.5"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.93"
+    "effect": ">=4.0.0-beta.98 <4.0.0"
   }
 }