@weftui/core 0.26.2 → 0.27.0

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

@@ -18,21 +18,21 @@ A component's `E` channel accumulates up the tree. A **failure boundary** is whe
 ```typescript
 import { Boundary, h } from "@weftui/core";
 
-Boundary.catchAll({ fallback: (e) => h.div({ class: "error" }, `Failed: ${e.message}`) }, [
+Boundary.catch({ fallback: (e) => h.div({ class: "error" }, `Failed: ${e.message}`) }, [
   RiskyWidget(),
 ]);
 ```
 
 There are six failure-catch variants, mirroring Effect's own error operators so the mental model transfers directly:
 
-| Variant                  | Catches                                    |
-| ------------------------ | ------------------------------------------ |
-| `catchAll`               | every failure in `E`                       |
-| `catchAllCause`          | the full `Cause` (defects included)        |
-| `catchTag` / `catchTags` | one / several tagged errors by `_tag`      |
-| `catchSome` / `catchIf`  | a selected subset, by `Option` / predicate |
+| Variant                   | Catches                                    |
+| ------------------------- | ------------------------------------------ |
+| `catch`                   | every failure in `E`                       |
+| `catchCause`              | the full `Cause` (defects included)        |
+| `catchTag` / `catchTags`  | one / several tagged errors by `_tag`      |
+| `catchFilter` / `catchIf` | a selected subset, by `Filter` / predicate |
 
-The channel algebra is the whole reason they exist: `catchTag("Foo", …)` removes `Foo` from the children's `E` and adds whatever the fallback needs — so the type of the boundary node reflects exactly which failures are still live and which were handled. An unhandled failure re-raises to the **nearest enclosing** boundary; if none catches it at **mount time**, mounting fails. Boundaries nest, so an inner `catchTag` can handle a specific case while an outer `catchAll` sweeps the rest.
+The channel algebra is the whole reason they exist: `catchTag("Foo", …)` removes `Foo` from the children's `E` and adds whatever the fallback needs — so the type of the boundary node reflects exactly which failures are still live and which were handled. An unhandled failure re-raises to the **nearest enclosing** boundary; if none catches it at **mount time**, mounting fails. Boundaries nest, so an inner `catchTag` can handle a specific case while an outer `catch` sweeps the rest.
 
 ### Post-mount failures with no enclosing boundary
 

package/docs/explanation/reactive-primitives.md

@@ -52,11 +52,11 @@ import { SubscriptionRef, Stream } from "effect";
 
 const count = yield * SubscriptionRef.make(0);
 
-// count.changes is a Stream<number> — each new value updates the text node
-h.span([count.changes]);
+// SubscriptionRef.changes(count) is a Stream<number> — each new value updates the text node
+h.span([SubscriptionRef.changes(count)]);
 
 // Stream as a prop — each emission sets the attribute
-const isDisabled = Stream.map(count.changes, (n) => n >= 10);
+const isDisabled = Stream.map(SubscriptionRef.changes(count), (n) => n >= 10);
 h.button({ disabled: isDisabled }, "Submit");
 ```
 
@@ -65,22 +65,22 @@ Streams can also supply entire child arrays. Each emission replaces the previous
 ```typescript
 const todos = yield * SubscriptionRef.make<string[]>([]);
 
-h.ul([Stream.map(todos.changes, (list) => list.map((item) => h.li(item)))]);
+h.ul([Stream.map(SubscriptionRef.changes(todos), (list) => list.map((item) => h.li(item)))]);
 ```
 
 ## Derived streams
 
-Because `.changes` is a plain `Stream`, the full Stream API applies:
+Because `SubscriptionRef.changes(ref)` returns a plain `Stream`, the full Stream API applies:
 
 ```typescript
 const count = yield * SubscriptionRef.make(0);
 
-const doubled = Stream.map(count.changes, (n) => n * 2);
-const formatted = Stream.map(count.changes, (n) => `Count: ${n}`);
-const isHigh = Stream.map(count.changes, (n) => n > 10);
+const doubled = Stream.map(SubscriptionRef.changes(count), (n) => n * 2);
+const formatted = Stream.map(SubscriptionRef.changes(count), (n) => `Count: ${n}`);
+const isHigh = Stream.map(SubscriptionRef.changes(count), (n) => n > 10);
 
 h.div([
-  h.p([count.changes]),
+  h.p([SubscriptionRef.changes(count)]),
   h.p([doubled]),
   h.p([formatted]),
   h.p({ style: { color: Stream.map(isHigh, (b) => (b ? "red" : "black")) } }, "Status"),
@@ -93,8 +93,10 @@ Multiple refs can be combined with `Stream.zipLatestWith`, `Stream.merge`, or ot
 const firstName = yield * SubscriptionRef.make("");
 const lastName = yield * SubscriptionRef.make("");
 
-const fullName = Stream.zipLatestWith(firstName.changes, lastName.changes, (first, last) =>
-  `${first} ${last}`.trim(),
+const fullName = Stream.zipLatestWith(
+  SubscriptionRef.changes(firstName),
+  SubscriptionRef.changes(lastName),
+  (first, last) => `${first} ${last}`.trim(),
 );
 ```
 

package/docs/explanation/rendering-model.md

@@ -20,7 +20,7 @@ type Node<E = never, R = never> = Effect.Effect<ElementDescriptor, E, R>;
 Every element in a Weft tree **is an Effect**. `h.div(...)`, a component's return value, a boundary — each is an `Effect` that, when run, produces an element descriptor. Two consequences follow immediately, and they shape everything else:
 
 1. **The error (`E`) and requirement (`R`) channels accumulate through the tree.** A child that reads a service, or a prop backed by a failible stream, contributes its `R` and `E` to its parent, which contributes to _its_ parent, up to the mount boundary. The type of your app node is the exact union of everything it needs and everything it can fail with — visible to the type checker, satisfiable exactly once, at `mount`/`hydrate`. See [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) for how the accumulation works mechanically.
-2. **Every Effect combinator applies to a node directly.** `Effect.provide`, `Effect.flatMap`, `Effect.gen`, `Effect.catchAll` — none of them are special-cased for UI. A node is an ordinary Effect, so the entire Effect ecosystem composes with your view for free.
+2. **Every Effect combinator applies to a node directly.** `Effect.provide`, `Effect.flatMap`, `Effect.gen`, `Effect.catch` — none of them are special-cased for UI. A node is an ordinary Effect, so the entire Effect ecosystem composes with your view for free.
 
 JSX collapses every component to an opaque `JSX.Element`, erasing both channels. Weft keeps them, and that is the point of the whole design. (There is [no JSX](https://weftui.dev/docs/explanation/combinator-api) here — components are plain functions you _call_.)
 

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

@@ -39,7 +39,7 @@ The `ThemeServiceLive` example above works because `mount`'s effect and the serv
 Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
 ```
 
-This is exactly what happened with effect-atom's `Registry.layer` in the [`effect-atom` example](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) (issue #122): every atom-driven region rendered empty, with no error, because the registry the streams read from had already been disposed.
+This is exactly what happened with the atom registry layer (`AtomRegistry.layer`, from `effect/unstable/reactivity`) in the [`effect-atom` example](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) (issue #122): every atom-driven region rendered empty, with no error, because the registry the streams read from had already been disposed.
 
 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.
 
@@ -50,7 +50,7 @@ A plain `mount`/`hydrate` discharges `R` at the call site. But under `@weftui/ro
 So the router exposes an explicit **`context` seam** — a `Layer` threaded to the document shell and every route, layout, and leaf:
 
 ```typescript
-class Greeting extends Context.Tag("Greeting")<Greeting, { text: string }>() {}
+class Greeting extends Context.Service<Greeting, { text: string }>()("Greeting") {}
 
 // server entry
 RouterServer.render(App, { document, url, context: Layer.succeed(Greeting, { text: "hi" }) });
@@ -63,7 +63,7 @@ The seam is **symmetric** (same shape on both sides) and **type-tracked**: the d
 
 ## Server-only services: `ServerTag`
 
-Some services must _never_ run in the browser — a database handle, a private credential, an rpc handler's backing store. Declare those with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) instead of `Context.Tag`. It behaves exactly like `Context.Tag`, but its identifier carries a **server-only brand**.
+Some services must _never_ run in the browser — a database handle, a private credential, an rpc handler's backing store. Declare those with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) instead of `Context.Service`. It behaves exactly like `Context.Service`, but its identifier carries a **server-only brand**.
 
 The brand's job is to turn a leak into a **compile error at the `hydrate` call site**. A `Boundary.rpc` handler legitimately reads server-only services on the server, but they must not survive into client code: since `render` only ever touches the _decoded result_ (never the service), a correctly-written boundary keeps its output `R` free of the brand. If a branded tag ever leaks into `render` and reaches the client requirement channel, `hydrate`'s `AssertNoServerOnly` resolves `R` to a compile-error sentinel — you learn at build time, not from a runtime defect.
 

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

@@ -165,7 +165,7 @@ Router.route("users/:id", {
   path: idParam,
   component: Component.gen(function* () {
     const { id } = yield* Router.params(idParam);
-    if (id < 0) return yield* notFound();
+    if (!Number.isFinite(id) || id < 0) return yield* notFound();
     return yield* h.div(`User ${id}`);
   }),
 });
@@ -173,6 +173,8 @@ Router.route("users/:id", {
 
 `RouterNotFound` is exported, so a `Boundary.catchTag("RouterNotFound", …)` placed inside a subtree overrides the app-level fallback for that subtree (the router's internal boundary is outermost, so a nearer user boundary wins).
 
+> **`Schema.NumberFromString` gotcha.** Decoding no longer fails on a non-numeric segment — `/users/abc` decodes `id` to `NaN` instead of missing the route. A leaf that guards a numeric param must check `Number.isFinite(id)` itself (as above); relying on the schema alone to 404 non-numeric input no longer works.
+
 ## 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:
@@ -231,6 +233,16 @@ yield * patchQuery({ sort: "old" }); // merges into the current query
 - **`navigate(ref, args)`** builds the URL via [`href`](#type-safe-links-with-href) (so it round-trips with the matcher) and pushes — or, with `{ replace: true }`, replaces — the History entry. `args` follows the same requiredness rules as `href`.
 - **`setQuery` / `patchQuery`** keep the path, so the active leaf is never remounted — pair them with `Router.queryStream` for in-place reactive updates. They are a no-op when no route is matched.
 
+### Scroll position on navigation
+
+A client navigation whose **path** changes resets the window scroll to the top at commit — matching what a full page load would do, which a raw History `pushState`/`replaceState` otherwise doesn't. This applies uniformly to `Router.navigate`, clicking a link the [interceptor](#link-interception) handles, and the `push` / `replace` helpers.
+
+- **Query-only navigations preserve scroll.** `setQuery` / `patchQuery` (and any navigation that keeps the same path) don't reset — the leaf stays mounted, so there's nothing to scroll away from.
+- **Back/forward is untouched.** The router never resets scroll on `popstate`; the browser's native `history.scrollRestoration: "auto"` restores the offset the entry had when the user left it.
+- **Hash navigation (`#section`) is unaffected** — it's browser-native, and the link interceptor already lets same-document/hash-only clicks fall through.
+
+There's no opt-out; the behavior is hardwired.
+
 ## Server setup
 
 On the server, `RouterServer` matches a request URL, builds a fixed-match `Router`, renders `RouterApp` to hydratable HTML inside a **document shell**, and reports a status (404 when no route matches or a page raises `RouterNotFound`).
@@ -266,9 +278,9 @@ export const handler = RouterServer.toWebHandler(App, { document: documentShell
 
 `render` provides both `Router.Outlet` (the app, per request) and `Router` (so the shell may read params), and renders through `renderToStringHydratable` so the client can `hydrate` in place.
 
-### `@effect/platform` is the spine
+### `effect/unstable/httpapi` is the spine
 
-The tree is the authoring surface, but `@effect/platform`'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 `setPath(pathSchema)`, `setUrlParams(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.
@@ -280,7 +292,7 @@ The tree is the authoring surface, but `@effect/platform`'s `HttpApi` is the **s
 | `RouterNotFound`    | `notFound()`, or no route matched                                     | `Boundary.catchTag("RouterNotFound", …)` (or the app-level `notFound` page) |
 | `RouterParamsError` | `Router.params` / `Router.query` on a missing/invalid key or no match | `Boundary.catchTag("RouterParamsError", …)`                                 |
 
-Both are modeled as `Schema.TaggedError`, so they encode/decode across the wire the same way `Boundary.rpc` replays typed failures.
+Both are modeled as `Schema.TaggedErrorClass`, so they encode/decode across the wire the same way `Boundary.rpc` replays typed failures.
 
 ## `Boundary.rpc` interplay
 
@@ -289,7 +301,7 @@ Initial SSR navigation works end to end: the server resolves the rpc and inlines
 ## See also
 
 - [`@weftui/router` API reference](https://weftui.dev/docs/reference/router)
-- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable SSR + hydration app with nested layouts, persistent layout state, type-safe `href`s, handler-arg props, and programmatic navigation over the `@effect/platform` spine
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable SSR + hydration app with nested layouts, persistent layout state, type-safe `href`s, handler-arg props, and programmatic navigation over the `effect/unstable/httpapi` spine
 - [Component Authoring](https://weftui.dev/docs/how-to/author-components) — `Component.make` / `Component.gen`, the idiomatic way to write route components
 - [Server-Side Rendering](https://weftui.dev/docs/how-to/render-on-the-server) — `renderToStringHydratable`, `hydrate`, and `Boundary.rpc`
 - [RPC Data Boundaries](https://weftui.dev/docs/how-to/load-data-with-rpc) — `Boundary.rpc`, the `Resource` handle, and the four lifecycles

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

@@ -43,7 +43,7 @@ const Counter = () =>
     const count = yield* SubscriptionRef.make(0);
 
     return yield* h.div([
-      h.span([count.changes]),
+      h.span([SubscriptionRef.changes(count)]),
       h.button({ onclick: () => SubscriptionRef.update(count, (n) => n + 1) }, "+"),
     ]);
   });
@@ -63,10 +63,10 @@ so it is already in context when you need it.
 This matters the moment a component starts **background work** — a subscription, an
 observer of a `ref`, a polling timer, anything you `fork`. The rule:
 
-> Fork background work with **`Effect.forkScoped`**, never a bare `Effect.fork`.
+> Fork background work with **`Effect.forkScoped`**, never a bare `Effect.forkChild`.
 
 `Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for
-the component's lifetime and is interrupted on unmount. A bare `Effect.fork` instead
+the component's lifetime and is interrupted on unmount. A bare `Effect.forkChild` instead
 attaches the fiber to the component-body fiber — the one that runs your `Effect.gen` to
 produce the tree. That fiber completes the instant the gen returns its node, so the
 forked work is cancelled almost immediately.
@@ -82,12 +82,12 @@ const AutoFocusInput = () =>
     const inputRef = yield* SubscriptionRef.make<Option.Option<HTMLInputElement>>(Option.none());
 
     yield* pipe(
-      inputRef.changes,
+      SubscriptionRef.changes(inputRef),
       Stream.filter(Option.isSome),
       Stream.take(1),
       Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
       Effect.forkScoped, // ✅ tied to the instance scope — survives until unmount
-      // Effect.fork,     // ❌ tied to the body fiber — interrupted when the gen returns
+      // Effect.forkChild, // ❌ tied to the body fiber — interrupted when the gen returns
     );
 
     return yield* h.input({ ref: inputRef, type: "text" });

package/docs/how-to/handle-forms.md

@@ -9,15 +9,15 @@ description: Build a controlled form with SubscriptionRef field state, reactive
 
 **Goal:** a controlled form whose inputs drive `SubscriptionRef` state, whose errors update reactively as the user types, and whose submit runs an Effect.
 
-Each field is a `SubscriptionRef`. Bind it with `oninput`, derive validation from its `.changes` stream, and return an `Effect` from `onsubmit` (after `preventDefault`).
+Each field is a `SubscriptionRef`. Bind it with `oninput`, derive validation from its `SubscriptionRef.changes(ref)` stream, and return an `Effect` from `onsubmit` (after `preventDefault`).
 
 ```typescript
 import { h } from "@weftui/core";
-import { Effect, Either, Schema, Stream, SubscriptionRef } from "effect";
+import { Effect, Result, Schema, Stream, SubscriptionRef } from "effect";
 
 const Email = Schema.String.pipe(
-  Schema.filter((s) => s.includes("@"), { message: () => "Must contain @" }),
-  Schema.filter((s) => s.includes("."), { message: () => "Must contain a domain" }),
+  Schema.check(Schema.makeFilter((s) => (s.includes("@") ? undefined : "Must contain @"))),
+  Schema.check(Schema.makeFilter((s) => (s.includes(".") ? undefined : "Must contain a domain"))),
 );
 
 const LoginForm = () =>
@@ -26,11 +26,11 @@ const LoginForm = () =>
     const status = yield* SubscriptionRef.make<string | null>(null);
 
     // Validation is a stream derived from the field — it re-runs as the user types.
-    const error = Stream.map(email.changes, (value) => {
+    const error = Stream.map(SubscriptionRef.changes(email), (value) => {
       if (value.length === 0) return null; // don't nag an empty field
-      return Either.match(Schema.decodeUnknownEither(Email)(value), {
-        onLeft: (e) => e.message.split(":").pop()?.trim() ?? "Invalid",
-        onRight: () => null,
+      return Result.match(Schema.decodeUnknownResult(Email)(value), {
+        onFailure: (e) => e.message.split(":").pop()?.trim() ?? "Invalid",
+        onSuccess: () => null,
       });
     });
 
@@ -52,7 +52,7 @@ const LoginForm = () =>
         }),
         Stream.map(error, (err) => (err ? h.span({ class: "error-text" }, err) : null)),
         h.button({ type: "submit" }, "Login"),
-        h.div([Stream.map(status.changes, (s) => (s ? h.span(s) : null))]),
+        h.div([Stream.map(SubscriptionRef.changes(status), (s) => (s ? h.span(s) : null))]),
       ],
     );
   });
@@ -61,7 +61,7 @@ const LoginForm = () =>
 ## How it works
 
 - **Field state** is a `SubscriptionRef.make("")`; `oninput` writes the current value with `SubscriptionRef.set`. Because the input is driven by the ref, it is a controlled input.
-- **Validation is reactive**, not on-blur or on-submit only: `Stream.map(email.changes, …)` produces an error string (or `null`) on every keystroke. Use [`Schema`](https://effect.website/docs/schema/introduction) to decode — `Schema.decodeUnknownEither(schema)(value)` returns an `Either`, and `Either.match` turns it into UI. A node or `null` in a child slot renders the error or nothing.
+- **Validation is reactive**, not on-blur or on-submit only: `Stream.map(SubscriptionRef.changes(email), …)` produces an error string (or `null`) on every keystroke. Use [`Schema`](https://effect.website/docs/schema/introduction) to decode — `Schema.decodeUnknownResult(schema)(value)` returns a `Result`, and `Result.match` turns it into UI. A node or `null` in a child slot renders the error or nothing.
 - **Submit returns an Effect.** `onsubmit` calls `e.preventDefault()` and then **returns** an `Effect` (it is not `yield*`-ed inline) — the renderer runs it in a detached fiber, so it can `SubscriptionRef.set`, `Effect.sleep`, read fields with `SubscriptionRef.get`, or call a service.
 
 ## Variations

package/docs/how-to/load-async-data.md

@@ -2,14 +2,14 @@
 title: Load Async Data
 order: 9
 section: how-to
-description: Show a loading state then resolved content with Stream.concat, and turn a failed fetch into a fallback node with Effect.catchAll — all client-side.
+description: Show a loading state then resolved content with Stream.concat, and turn a failed fetch into a fallback node with Effect.catch — all client-side.
 ---
 
 # Load Async Data
 
 **Goal:** render a loading placeholder, then the fetched content, and a fallback if the fetch fails — for data that loads **on the client**.
 
-Return a `Stream<Node>` that emits the loading node first and the resolved node second, sequenced with `Stream.concat`. Handle failure inside the effect with `Effect.catchAll`, which maps the error to a fallback node.
+Return a `Stream<Node>` that emits the loading node first and the resolved node second, sequenced with `Stream.concat`. Handle failure inside the effect with `Effect.catch`, which maps the error to a fallback node.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -34,7 +34,7 @@ const UserCard = ({ id }: { id: number }) =>
     Stream.fromEffect(
       fetchUser(id).pipe(
         Effect.flatMap((user) => h.div({ class: "user-card" }, [h.h3(user.name), h.p(user.email)])),
-        Effect.catchAll((error) => h.div({ class: "error" }, `Error: ${error.message}`)),
+        Effect.catch((error) => h.div({ class: "error" }, `Error: ${error.message}`)),
       ),
     ),
   );
@@ -44,7 +44,7 @@ const UserCard = ({ id }: { id: number }) =>
 
 - **`Stream.concat`** sequences two streams: `Stream.make(loadingNode)` emits once immediately, then `Stream.fromEffect(effect)` emits the resolved node when the effect completes. The renderer swaps the DOM in place on the second emission.
 - **`Effect.flatMap((data) => h.div(...))`** builds the content node from the data — `h.*` returns a `Node`, which is an `Effect`, so it composes directly in the pipeline.
-- **`Effect.catchAll((error) => node)`** converts the error channel into a fallback node, so the stream always yields something renderable. The failure never escapes to the mount.
+- **`Effect.catch((error) => node)`** converts the error channel into a fallback node, so the stream always yields something renderable. The failure never escapes to the mount.
 - **Parallel loading is automatic:** place several async components as siblings and their fetches run concurrently — no orchestration needed.
 
 ## When to reach for a boundary instead

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

@@ -39,7 +39,7 @@ The rpc **contract** (pure Schema) is shared with the client. The rpc **handler*
 
 ```typescript
 // data/inventory.ts
-import { Rpc, RpcGroup } from "@effect/rpc";
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
 import { Context, Effect, Layer, Schema } from "effect";
 
 // --- Contract (shareable with the client) ---
@@ -53,10 +53,10 @@ export const GetStock = Rpc.make("GetStock", { payload: StockKey, success: Stock
 export const StockRpcs = RpcGroup.make(GetStock);
 
 // --- Handler (server-only; the client never imports this) ---
-class Inventory extends Context.Tag("Inventory")<
+class Inventory extends Context.Service<
   Inventory,
   { readonly stockFor: (id: number) => Effect.Effect<typeof Stock.Type> }
->() {}
+>()("Inventory") {}
 
 const InventoryLive = Layer.succeed(Inventory, {
   stockFor: (id) => Effect.succeed({ units: 7 + (id % 5) }),
@@ -68,7 +68,7 @@ export const StockLive = StockRpcs.toLayer({
 }).pipe(Layer.provide(InventoryLive));
 ```
 
-Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Tag`) when they might be referenced from universal code: the brand makes a leak into `render` a compile error at the `hydrate` call site rather than a runtime surprise.
+Declare server-only services with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) (not `Context.Service`) when they might be referenced from universal code: the brand makes a leak into `render` a compile error at the `hydrate` call site rather than a runtime surprise.
 
 ## Wiring the router
 
@@ -157,7 +157,7 @@ Boundary.catchTag({ tag: "OutOfStock", fallback: (e) => h.p({ class: "error" },
 ]);
 ```
 
-A transport **defect** (no `Cause.failureOption`), or an rpc with no `error` schema, is **not** replayed; it propagates — a server-side fallback and a client mismatch.
+A transport **defect** (no `Cause.findErrorOption`), or an rpc with no `error` schema, is **not** replayed; it propagates — a server-side fallback and a client mismatch.
 
 ## When to use
 

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

@@ -121,4 +121,4 @@ In both cases the tell is the same: nothing in the composition keeps a scope ope
 - [Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) — why the mount effect resolving early matters for scoped layers
 - [Services and Context](https://weftui.dev/docs/explanation/services-and-context) — how `R` accumulates and discharges at the mount
 - [`mountScoped` / `hydrateScoped` reference](https://weftui.dev/docs/reference/dom#mountscoped) — signatures and error unions
-- [examples/effect-atom](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) — a real scoped layer (`Registry.layer`) mounted with this composition
+- [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

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

@@ -9,7 +9,7 @@ description: Capture a DOM element with the ref prop into a SubscriptionRef<Opti
 
 **Goal:** get a handle to a real DOM element — to focus it, measure it, or call an imperative browser API on it.
 
-Declare a `SubscriptionRef<Option<HTMLElement>>`, attach it with the `ref` prop, and either **react** to the element appearing (a scoped observer on `.changes`) or **read** it later inside a handler.
+Declare a `SubscriptionRef<Option<HTMLElement>>`, attach it with the `ref` prop, and either **react** to the element appearing (a scoped observer on `SubscriptionRef.changes(ref)`) or **read** it later inside a handler.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -21,7 +21,7 @@ const AutoFocusInput = () =>
 
     // Observe the element becoming available, once, and focus it.
     yield* pipe(
-      inputRef.changes,
+      SubscriptionRef.changes(inputRef),
       Stream.filter(Option.isSome),
       Stream.take(1),
       Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
@@ -35,8 +35,8 @@ const AutoFocusInput = () =>
 ## How it works
 
 - **The `ref` prop** takes a `SubscriptionRef<Option<T>>`. The renderer sets it to `Option.some(element)` **once**, when the element is created — so the ref is an `Option`: `None` until mount, `Some(el)` after.
-- **React to mount** by observing `ref.changes`: `Stream.filter(Option.isSome)` waits for the element, `Stream.take(1)` takes just the first appearance, and `Stream.runForEach` does the imperative work. This is the equivalent of a mount effect.
-- **Use `Effect.forkScoped`, not `Effect.fork`.** `forkScoped` ties the observer fiber to the component's **instance scope** (the ambient `Scope` the renderer provides), so it lives as long as the component is mounted. A bare `Effect.fork` binds to the transient component-body fiber and is interrupted the instant the generator returns — the observer would never fire.
+- **React to mount** by observing `SubscriptionRef.changes(ref)`: `Stream.filter(Option.isSome)` waits for the element, `Stream.take(1)` takes just the first appearance, and `Stream.runForEach` does the imperative work. This is the equivalent of a mount effect.
+- **Use `Effect.forkScoped`, not `Effect.forkChild`.** `forkScoped` ties the observer fiber to the component's **instance scope** (the ambient `Scope` the renderer provides), so it lives as long as the component is mounted. A bare `Effect.forkChild` binds to the transient component-body fiber and is interrupted the instant the generator returns — the observer would never fire.
 
 ## Read a ref imperatively
 
@@ -58,6 +58,6 @@ const scroll = () =>
 
 ## See also
 
-- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `SubscriptionRef` and `.changes`
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `SubscriptionRef` and `SubscriptionRef.changes`
 - [Author Components](https://weftui.dev/docs/how-to/author-components) — instance scope and `Effect.forkScoped`
 - [examples/element-ref](https://github.com/stefvw93/weft/tree/main/examples/element-ref) — auto-focus, element measurement, and imperative scroll via refs

package/docs/reference/core.md

@@ -144,7 +144,7 @@ Boundary.suspend(
 
 #### `Boundary.rpc`
 
-A universal server/client render boundary backed by one `Rpc` from the app's merged `RpcGroup` ([`@effect/rpc`](https://github.com/Effect-TS/effect/tree/main/packages/rpc)). The rpc **`_tag`** is the boundary's stable identity and its **payload schema** the typed input; the handler lives in the server-only rpc Layer (`group.toLayer(...)`), which the client never imports — tree-shaking does the client/server split structurally. Unlike the catch variants it takes a `render` function — not a children array — and that `render` receives a reactive [`Resource`](#resourcea), not a bare value.
+A universal server/client render boundary backed by one `Rpc` from the app's merged `RpcGroup` ([`effect/unstable/rpc`](https://github.com/Effect-TS/effect)). The rpc **`_tag`** is the boundary's stable identity and its **payload schema** the typed input; the handler lives in the server-only rpc Layer (`group.toLayer(...)`), which the client never imports — tree-shaking does the client/server split structurally. Unlike the catch variants it takes a `render` function — not a children array — and that `render` receives a reactive [`Resource`](#resourcea), not a bare value.
 
 ```typescript
 Boundary.rpc<R extends Rpc.Any, C extends Node<any, any>>(
@@ -201,22 +201,21 @@ The descriptor `type` every `Boundary.rpc` carries (`{ type: SERVER_BOUNDARY, pr
 interface AppRpcClient {
   readonly call: (tag: string, payload: unknown) => Effect.Effect<unknown, unknown>;
 }
-class AppRpcClientTag extends Context.Tag("@weftui/core/AppRpcClient")<
-  AppRpcClientTag,
-  AppRpcClient
->() {}
+class AppRpcClientTag extends Context.Service<AppRpcClientTag, AppRpcClient>()(
+  "@weftui/core/AppRpcClient",
+) {}
 ```
 
-The ambient, package-neutral seam the renderer resolves a `Boundary.rpc` through — a **flat, untyped** caller `(tag, payload) => Effect<success>`. It lets `@weftui/dom` resolve a boundary without importing `@effect/rpc` or `@weftui/router`. `@weftui/router` provides it: a **network** `RpcClient` (POST `/_eui/rpc`) in the browser, an **in-process** client over the handler Layer on the server. `call` returns the already-decoded success; the renderer owns `successSchema`/`errorSchema` decoding of the inline SSR payload only. Both `AppRpcClientTag` and the `AppRpcClient` type are re-exported from `@weftui/core`. Absent in a router-less mount, where a `Boundary.rpc` resolves to a descriptive "needs router/rpc" error (not a defect).
+The ambient, package-neutral seam the renderer resolves a `Boundary.rpc` through — a **flat, untyped** caller `(tag, payload) => Effect<success>`. It lets `@weftui/dom` resolve a boundary without importing `effect/unstable/rpc` or `@weftui/router`. `@weftui/router` provides it: a **network** `RpcClient` (POST `/_eui/rpc`) in the browser, an **in-process** client over the handler Layer on the server. `call` returns the already-decoded success; the renderer owns `successSchema`/`errorSchema` decoding of the inline SSR payload only. Both `AppRpcClientTag` and the `AppRpcClient` type are re-exported from `@weftui/core`. Absent in a router-less mount, where a `Boundary.rpc` resolves to a descriptive "needs router/rpc" error (not a defect).
 
 See the [rpc data boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc) and [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr).
 
-#### `Boundary.catchAll`
+#### `Boundary.catch`
 
-Catches all typed failures (`Cause.fail`). Defects (`Cause.die`) are not caught and re-raise.
+Catches all typed failures (`Cause.fail`). Defects (`Cause.die`) are not caught and re-raise. Mirrors Effect 4's `Effect.catch` (renamed from `catchAll` in v3).
 
 ```typescript
-Boundary.catchAll<C, FE, FR>(
+Boundary.catch<C, FE, FR>(
   props: { fallback: (e: ChildrenE<C>) => Node<FE, FR> },
   children: C,
 ): Node<FE, ChildrenR<C> | FR>
@@ -224,12 +223,12 @@ Boundary.catchAll<C, FE, FR>(
 
 The children's `E` is fully consumed. The output `E` is only the fallback's own error channel.
 
-#### `Boundary.catchAllCause`
+#### `Boundary.catchCause`
 
-Catches every `Cause` including defects and interruptions.
+Catches every `Cause` including defects and interruptions. Mirrors Effect 4's `Effect.catchCause` (renamed from `catchAllCause` in v3).
 
 ```typescript
-Boundary.catchAllCause<C, FE, FR>(
+Boundary.catchCause<C, FE, FR>(
   props: { fallback: (cause: Cause.Cause<ChildrenE<C>>) => Node<FE, FR> },
   children: C,
 ): Node<FE, ChildrenR<C> | FR>
@@ -266,18 +265,30 @@ Boundary.catchTags<C, Handlers>(
 ): Node<UnhandledE | HandlersE, ChildrenR<C> | HandlersR>
 ```
 
-#### `Boundary.catchSome`
+#### `Boundary.catchFilter`
 
-The fallback returns `Option<Node>`. `Option.none()` re-raises the error; `Option.some(node)` catches it.
+Conditionally catches using a `Filter`, run on each typed failure: a `Result.succeed` (pass) recovers via `fallback`, receiving the possibly-narrowed pass value; a `Result.fail` re-raises the error (its `Fail` channel `X` is preserved in the output `E`, since the boundary may not handle any given error). Takes the `Filter` and `fallback` as **positional** arguments — no wrapping props object. Mirrors Effect 4's `Effect.catchFilter` (renamed from `catchSome`, which took an `Option`-returning function in v3).
 
 ```typescript
-Boundary.catchSome<C, FE, FR>(
-  props: { fallback: (e: ChildrenE<C>) => Option.Option<Node<FE, FR>> },
+Boundary.catchFilter<C, EB, X, FE, FR>(
+  filter: Filter.Filter<ChildrenE<C>, EB, X>,
+  fallback: (matched: EB) => Node<FE, FR>,
   children: C,
-): Node<ChildrenE<C> | FE, ChildrenR<C> | FR>
+): Node<X | FE, ChildrenR<C> | FR>
+```
+
+```typescript
+import { Boundary } from "@weftui/core";
+import { Filter, Result } from "effect";
+
+Boundary.catchFilter(
+  Filter.make((e: AppError) => (e._tag === "Net" ? Result.succeed(e) : Result.fail(e))),
+  (matched) => h.div({}, matched.message),
+  [Widget()],
+);
 ```
 
-The children's `E` is preserved in the output because the boundary may or may not handle any given error.
+The children's `E` is narrowed to the filter's `Fail` channel `X` in the output, because the boundary may or may not handle any given error.
 
 #### `Boundary.catchIf`
 
@@ -301,7 +312,7 @@ Inner boundaries shadow outer ones for their subtree — the innermost boundary
 
 ```typescript
 // Inner catches FooError; BarError propagates to outer
-Boundary.catchAll({ fallback: (e) => h.div(`Outer: ${e.message}`) }, [
+Boundary.catch({ fallback: (e) => h.div(`Outer: ${e.message}`) }, [
   Boundary.catchTag({ tag: "Foo", fallback: (e) => h.span(`Foo: ${e.msg}`) }, [
     ChildWithFooOrBarError(),
   ]),
@@ -312,7 +323,7 @@ Boundary.catchAll({ fallback: (e) => h.div(`Outer: ${e.message}`) }, [
 
 ## ServerTag
 
-A `Context.Tag` whose identifier is branded server-only. Use it exactly like `Context.Tag` for services that must only ever be provided on the server — e.g. a database handle read inside an rpc handler Layer. The brand also guards [`Boundary.rpc`](#boundaryrpc): a server-only tag accidentally referenced in `render` stays in the requirement channel, where `hydrate`'s `AssertNoServerOnly` rejects it at compile time.
+A `Context.Service` key whose identifier is branded server-only. Use it exactly like `Context.Service` for services that must only ever be provided on the server — e.g. a database handle read inside an rpc handler Layer. The brand also guards [`Boundary.rpc`](#boundaryrpc): a server-only tag accidentally referenced in `render` stays in the requirement channel, where `hydrate`'s `AssertNoServerOnly` rejects it at compile time.
 
 ```typescript
 import { ServerTag } from "@weftui/core";

package/docs/reference/router.md

@@ -19,7 +19,7 @@ Three entry points mirror `@weftui/dom`:
 
 ## `Router`
 
-`Router` is both an Effect `Context.Tag` and the authoring namespace; the two roles merge by declaration. `yield* Router` reads the per-render service; `Router.route(…)` authors a tree.
+`Router` is both an Effect `Context.Service` key and the authoring namespace; the two roles merge by declaration. `yield* Router` reads the per-render service; `Router.route(…)` authors a tree.
 
 The service value carries:
 
@@ -96,7 +96,7 @@ See the [Split Routes Lazily](https://weftui.dev/docs/how-to/split-routes-lazily
 
 ### `Router.Outlet`
 
-A `Context.Tag` whose value is the node to splice for the next level down. A layout (or the server document shell) reads it with `const outlet = yield* Router.Outlet`. Typed **opaque** as `Node<never, never>`, and discharged by the router at render time, so it never appears in a reader's aggregate requirement channel.
+A `Context.Service` key whose value is the node to splice for the next level down. A layout (or the server document shell) reads it with `const outlet = yield* Router.Outlet`. Typed **opaque** as `Node<never, never>`, and discharged by the router at render time, so it never appears in a reader's aggregate requirement channel.
 
 ### `Router.params` / `Router.query`
 
@@ -224,7 +224,7 @@ 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/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, so provide it through a `ManagedRuntime`:
 
 ```typescript
 const runtime = ManagedRuntime.make(RouterLive(App, { rpc: { group: StockRpcs } }));
@@ -258,6 +258,10 @@ yield * push("/users/1/posts?sort=new");
 yield * patchQuery({ sort: "old" }); // keeps the current path + other query fields
 ```
 
+### Scroll reset
+
+Every client-committed navigation whose path differs from the previously committed path — `navigate`, `push`, `replace`, and the link interceptor — resets `window.scrollTo(0, 0)` synchronously at commit. Query-only navigations (`setQuery` / `patchQuery`, or any push/replace to the same path) preserve scroll. `popstate` (`back` / `forward`) never resets; the browser's own `history.scrollRestoration: "auto"` restores the prior offset for those entries. Server rendering is unaffected. Not configurable — there is no `NavigateOptions` field to opt out.
+
 ### `installLinkInterceptor`
 
 ```typescript
@@ -290,11 +294,11 @@ Dispatch runs through the `def.httpApi` spine via `HttpApiBuilder`: platform own
 
 ### `RouterNotFound`
 
-`Schema.TaggedError` with an optional `path: string`. Raised by [`notFound`](#notfound) or when no route matches. Caught by the router's internal not-found boundary; export it to place your own `Boundary.catchTag("RouterNotFound", …)` (a nearer user boundary wins).
+`Schema.TaggedErrorClass` with an optional `path: string`. Raised by [`notFound`](#notfound) or when no route matches. Caught by the router's internal not-found boundary; export it to place your own `Boundary.catchTag("RouterNotFound", …)` (a nearer user boundary wins).
 
 ### `RouterParamsError`
 
-`Schema.TaggedError` with `source: "path" | "query"` and `keys: readonly string[]`. Raised by `Router.params` / `Router.query` when the live match doesn't satisfy the requested fields. Bubbles into the tree's aggregate error channel.
+`Schema.TaggedErrorClass` with `source: "path" | "query"` and `keys: readonly string[]`. Raised by `Router.params` / `Router.query` when the live match doesn't satisfy the requested fields. Bubbles into the tree's aggregate error channel.
 
 ### `notFound`