@weftui/core 0.30.0 → 0.31.1

package/README.md

@@ -9,10 +9,10 @@ This package is renderer-agnostic. Pair it with [`@weftui/dom`](https://weftui.d
 ## Installation
 
 ```bash
-npm install @weftui/core effect@beta
+npm install @weftui/core effect@rc
 ```
 
-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.
+Weft tracks Effect 4's prerelease line (beta, then rc). This release is built and tested against `effect@4.0.0-rc.112`; the peer range accepts newer 4.0 prereleases, which may contain upstream breaking changes.
 
 `effect` is a peer dependency. To render, add [`@weftui/dom`](https://www.npmjs.com/package/@weftui/dom).
 

package/dist/{index-CX9uEejU.d.ts → index-B-dPfhKZ.d.ts}

@@ -10526,6 +10526,19 @@ declare namespace Source {
   type Error<S> = S extends Stream.Stream<any, infer E, any> ? E : S extends Effect.Effect<any, infer E, any> ? E : S extends Subscribable<any, infer E, any> ? E : never;
   /** Extract the requirement channel `R` from any {@link Source} kind; a static value ⇒ `never`. */
   type Context<S> = S extends Stream.Stream<any, any, infer R> ? R : S extends Effect.Effect<any, any, infer R> ? R : S extends Subscribable<any, any, infer R> ? R : never;
+  /**
+   * The change stream of a `Source<A>`, without the `Subscribable` hop.
+   *
+   * - existing `Subscribable` → its `changes` stream;
+   * - `Stream<A>` → returned as-is (identity, no wrap);
+   * - `Effect<A>` → `Stream.fromEffect` (emits the resolved value once);
+   * - static `A` → `Stream.make(value)` (emits once).
+   *
+   * Unlike {@link toSubscribable} this allocates no ref, latch, or pump fiber,
+   * so consumers that only ever read changes (e.g. list reconciliation) skip
+   * the extra hop entirely.
+   */
+  function changes<A, E = never, R = never>(source: Source.Source<A, E, R>): Stream.Stream<A, E, R>;
   /**
    * Normalize a `Source<A>` into an await-first, hot `Subscribable`.
    *

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { D as Subscribable, E as Source, O as index_d_exports, T as NoPropValue, a as SVGElements, r as Renderable, s as HTMLElements, t as ElementDescriptor } from "./index-CX9uEejU.js";
+import { D as Subscribable, E as Source, O as index_d_exports, T as NoPropValue, a as SVGElements, r as Renderable, s as HTMLElements, t as ElementDescriptor } from "./index-B-dPfhKZ.js";
 import { Cause, Context, Effect, Filter, Option, Stream } from "effect";
 import { Rpc } from "effect/unstable/rpc";
 //#region src/combinator/types.d.ts

package/dist/index.js

@@ -1 +1 @@
-import{t as e}from"./rolldown-runtime-DK3Fl9T5.js";import{Cause as t,Context as n,Data as r,Deferred as i,Effect as a,Filter as o,Option as s,Predicate as c,Result as l,Stream as u,SubscriptionRef as d,identity as f,pipe as p}from"effect";const m=Symbol.for(`@weftui/core/ElementDescriptor`);function h(e){let t=a.succeed(e);return Object.defineProperty(t,m,{value:e,enumerable:!1}),t}function g(e){return a.isEffect(e)&&m in e?e[m]:void 0}var _=e({FAILURE_BOUNDARY:()=>v,SERVER_BOUNDARY:()=>b,SUSPENSE_BOUNDARY:()=>y,catch:()=>S,catchCause:()=>C,catchFilter:()=>E,catchIf:()=>D,catchTag:()=>w,catchTags:()=>T,rpc:()=>k,suspend:()=>O});const v=Symbol.for(`weft/FAILURE_BOUNDARY`),y=Symbol.for(`weft/SUSPENSE_BOUNDARY`),b=Symbol.for(`weft/SERVER_BOUNDARY`);function x(e,t){return h({type:v,props:{match:e,children:t}})}function S(e,n){return x(n=>{let r=t.findErrorOption(n);return s.isSome(r)?e.fallback(r.value):null},n)}function C(e,t){return x(t=>e.fallback(t),t)}function w(e,n){return x(n=>{let r=t.findErrorOption(n);if(s.isNone(r))return null;let i=r.value;return i._tag===e.tag?e.fallback(i):null},n)}function T(e,n){return x(n=>{let r=t.findErrorOption(n);if(s.isNone(r))return null;let i=r.value,a=i._tag;if(a===void 0)return null;let o=e[a];return o?o(i):null},n)}function E(e,n,r){return x(r=>{let i=t.findErrorOption(r);if(s.isNone(i))return null;let a=e(i.value);return l.isSuccess(a)?n(a.success):null},r)}function D(e,n){return x(n=>{let r=t.findErrorOption(n);if(s.isNone(r))return null;let i=r.value;return e.predicate(i)?e.fallback(i):null},n)}function O(e,t){return h({type:y,props:{...e,children:t}})}function k(e,t,n,r){let i=e;return h({type:b,props:{tag:i._tag,payloadSchema:i.payloadSchema,successSchema:i.successSchema,errorSchema:i.errorSchema,payload:t,render:n,fallback:r?.fallback}})}var A=class extends n.Service()(`@weftui/core/AppRpcClient`){};const j=e=>()=>n.Service()(e);function M(e){return typeof e==`object`&&!!e&&u.TypeId in e}function N(e){return M(e)?e:a.isEffect(e)?u.fromEffect(e):u.make(e)}var P=e({TypeId:()=>F,changes:()=>z,get:()=>R,isSubscribable:()=>B,make:()=>L});const F=`~@weftui/core/Subscribable`,I=e=>e,L=e=>({[F]:F,get:e.get,changes:e.changes}),R=e=>I(e).get,z=e=>I(e).changes,B=e=>c.hasProperty(e,F);var V=class extends r.TaggedError(`NoPropValue`){};let H;(function(e){function n(e,n){return B(e)?a.succeed(e):M(e)?a.gen(function*(){let r=yield*d.make(s.none()),c=yield*i.make(),l=yield*i.make(),m=p(u.runForEach(e,e=>p(d.set(r,s.some(e)),a.andThen(i.succeed(c,e)),a.asVoid)),a.ensuring(p(d.get(r),a.flatMap(e=>s.isNone(e)?a.asVoid(i.fail(c,new V({key:n}))):a.void))),a.onError(e=>t.hasInterruptsOnly(e)?a.void:a.asVoid(i.failCause(l,e))));yield*a.forkScoped(m);let h=p(d.get(r),a.flatMap(e=>s.isSome(e)?a.succeed(e.value):i.await(c))),g=p(d.changes(r),u.filterMap(o.fromPredicateOption(f)),u.interruptWhen(i.await(l)));return L({get:h,changes:g})}):a.isEffect(e)?a.gen(function*(){let t=yield*a.cached(e),n=u.fromEffect(t);return L({get:t,changes:n})}):a.succeed(L({get:a.succeed(e),changes:u.make(e)}))}e.toSubscribable=n})(H||={});const U=Symbol(`@weftui/core/fragment`);function W(e){return((t,n)=>{let r={},i;return Array.isArray(t)||typeof t==`string`||typeof t==`number`?i=t:t!==void 0&&(r=t,n!==void 0&&(i=n)),h({type:e,props:i===void 0?r:{...r,children:i}})})}function G(e=new Map){return new Proxy({fragment(e){return h({type:U,props:{children:e}})}},{get(t,n){return n in t?t[n]:e.get(n)??e.set(n,W(n)).get(n)}})}const K=G(new Map),q=Symbol(`@weftui/core/list`);let J;(function(e){function t(e,t){return h({type:q,props:{of:e.of,by:e.by,render:t}})}e.each=t})(J||={});let Y;(function(e){function t(e){return(t,n=[])=>a.gen(function*(){return yield*e(t,n)})}e.gen=t;function n(e){return e}e.make=n})(Y||={});export{A as AppRpcClientTag,_ as Boundary,Y as Component,v as FAILURE_BOUNDARY,U as FRAGMENT,q as LIST,J as List,V as NoPropValue,b as SERVER_BOUNDARY,y as SUSPENSE_BOUNDARY,j as ServerTag,H as Source,P as Subscribable,h as elementNode,g as getElementDescriptor,K as h,M as isStream,N as toStream};
+import{t as e}from"./rolldown-runtime-DK3Fl9T5.js";import{Cause as t,Context as n,Data as r,Deferred as i,Effect as a,Filter as o,Option as s,Predicate as c,Result as l,Stream as u,SubscriptionRef as d,identity as f,pipe as p}from"effect";const m=Symbol.for(`@weftui/core/ElementDescriptor`);function h(e){let t=a.succeed(e);return Object.defineProperty(t,m,{value:e,enumerable:!1}),t}function g(e){return a.isEffect(e)&&m in e?e[m]:void 0}var _=e({FAILURE_BOUNDARY:()=>v,SERVER_BOUNDARY:()=>b,SUSPENSE_BOUNDARY:()=>y,catch:()=>S,catchCause:()=>C,catchFilter:()=>E,catchIf:()=>D,catchTag:()=>w,catchTags:()=>T,rpc:()=>k,suspend:()=>O});const v=Symbol.for(`weft/FAILURE_BOUNDARY`),y=Symbol.for(`weft/SUSPENSE_BOUNDARY`),b=Symbol.for(`weft/SERVER_BOUNDARY`);function x(e,t){return h({type:v,props:{match:e,children:t}})}function S(e,n){return x(n=>{let r=t.findErrorOption(n);return s.isSome(r)?e.fallback(r.value):null},n)}function C(e,t){return x(t=>e.fallback(t),t)}function w(e,n){return x(n=>{let r=t.findErrorOption(n);if(s.isNone(r))return null;let i=r.value;return i._tag===e.tag?e.fallback(i):null},n)}function T(e,n){return x(n=>{let r=t.findErrorOption(n);if(s.isNone(r))return null;let i=r.value,a=i._tag;if(a===void 0)return null;let o=e[a];return o?o(i):null},n)}function E(e,n,r){return x(r=>{let i=t.findErrorOption(r);if(s.isNone(i))return null;let a=e(i.value);return l.isSuccess(a)?n(a.success):null},r)}function D(e,n){return x(n=>{let r=t.findErrorOption(n);if(s.isNone(r))return null;let i=r.value;return e.predicate(i)?e.fallback(i):null},n)}function O(e,t){return h({type:y,props:{...e,children:t}})}function k(e,t,n,r){let i=e;return h({type:b,props:{tag:i._tag,payloadSchema:i.payloadSchema,successSchema:i.successSchema,errorSchema:i.errorSchema,payload:t,render:n,fallback:r?.fallback}})}var A=class extends n.Service()(`@weftui/core/AppRpcClient`){};const j=e=>()=>n.Service()(e);function M(e){return typeof e==`object`&&!!e&&u.TypeId in e}function N(e){return M(e)?e:a.isEffect(e)?u.fromEffect(e):u.make(e)}var P=e({TypeId:()=>F,changes:()=>z,get:()=>R,isSubscribable:()=>B,make:()=>L});const F=`~@weftui/core/Subscribable`,I=e=>e,L=e=>({[F]:F,get:e.get,changes:e.changes}),R=e=>I(e).get,z=e=>I(e).changes,B=e=>c.hasProperty(e,F);var V=class extends r.TaggedError(`NoPropValue`){};let H;(function(e){function n(e){return B(e)?z(e):M(e)?e:a.isEffect(e)?u.fromEffect(e):u.make(e)}e.changes=n;function r(e,n){return B(e)?a.succeed(e):M(e)?a.gen(function*(){let r=yield*d.make(s.none()),c=yield*i.make(),l=yield*i.make(),m=p(u.runForEach(e,e=>p(d.set(r,s.some(e)),a.andThen(i.succeed(c,e)),a.asVoid)),a.ensuring(p(d.get(r),a.flatMap(e=>s.isNone(e)?a.asVoid(i.fail(c,new V({key:n}))):a.void))),a.onError(e=>t.hasInterruptsOnly(e)?a.void:a.asVoid(i.failCause(l,e))));yield*a.forkScoped(m);let h=p(d.get(r),a.flatMap(e=>s.isSome(e)?a.succeed(e.value):i.await(c))),g=p(d.changes(r),u.filterMap(o.fromPredicateOption(f)),u.interruptWhen(i.await(l)));return L({get:h,changes:g})}):a.isEffect(e)?a.gen(function*(){let t=yield*a.cached(e),n=u.fromEffect(t);return L({get:t,changes:n})}):a.succeed(L({get:a.succeed(e),changes:u.make(e)}))}e.toSubscribable=r})(H||={});const U=Symbol(`@weftui/core/fragment`);function W(e){return((t,n)=>{let r={},i;return Array.isArray(t)||typeof t==`string`||typeof t==`number`?i=t:t!==void 0&&(r=t,n!==void 0&&(i=n)),h({type:e,props:i===void 0?r:{...r,children:i}})})}function G(e=new Map){return new Proxy({fragment(e){return h({type:U,props:{children:e}})}},{get(t,n){return n in t?t[n]:e.get(n)??e.set(n,W(n)).get(n)}})}const K=G(new Map),q=Symbol(`@weftui/core/list`);let J;(function(e){function t(e,t){return h({type:q,props:{of:e.of,by:e.by,render:t}})}e.each=t})(J||={});let Y;(function(e){function t(e){return(t,n=[])=>a.gen(function*(){return yield*e(t,n)})}e.gen=t;function n(e){return e}e.make=n})(Y||={});export{A as AppRpcClientTag,_ as Boundary,Y as Component,v as FAILURE_BOUNDARY,U as FRAGMENT,q as LIST,J as List,V as NoPropValue,b as SERVER_BOUNDARY,y as SUSPENSE_BOUNDARY,j as ServerTag,H as Source,P as Subscribable,h as elementNode,g as getElementDescriptor,K as h,M as isStream,N as toStream};

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-import { C as StyleAttributeValue, S as HTMLAttributeSource, _ as HTMLFormMethod, a as SVGElements, b as HTMLReferrerPolicy, c as HTMLRole, d as EventHandlerFn, f as HTMLAutocapitalize, g as HTMLFormEncType, h as HTMLDir, i as SVGAttributes, l as DOMAttributes, m as HTMLCrossorigin, n as ElementType, o as HTMLAttributes, p as HTMLAutocomplete, r as Renderable, s as HTMLElements, t as ElementDescriptor, u as EventHandler, v as HTMLIframeSandbox, w as StyleProperties, x as AriaAttributes, y as HTMLLinkAs } from "../index-CX9uEejU.js";
+import { C as StyleAttributeValue, S as HTMLAttributeSource, _ as HTMLFormMethod, a as SVGElements, b as HTMLReferrerPolicy, c as HTMLRole, d as EventHandlerFn, f as HTMLAutocapitalize, g as HTMLFormEncType, h as HTMLDir, i as SVGAttributes, l as DOMAttributes, m as HTMLCrossorigin, n as ElementType, o as HTMLAttributes, p as HTMLAutocomplete, r as Renderable, s as HTMLElements, t as ElementDescriptor, u as EventHandler, v as HTMLIframeSandbox, w as StyleProperties, x as AriaAttributes, y as HTMLLinkAs } from "../index-B-dPfhKZ.js";
 export { AriaAttributes, DOMAttributes, ElementDescriptor, ElementType, EventHandler, EventHandlerFn, HTMLAttributeSource, HTMLAttributes, HTMLAutocapitalize, HTMLAutocomplete, HTMLCrossorigin, HTMLDir, HTMLElements, HTMLFormEncType, HTMLFormMethod, HTMLIframeSandbox, HTMLLinkAs, HTMLReferrerPolicy, HTMLRole, Renderable, SVGAttributes, SVGElements, StyleAttributeValue, StyleProperties };

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

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

package/docs/explanation/combinator-api.md

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

package/docs/explanation/reactive-primitives.md

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

package/docs/explanation/rendering-model.md

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

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

@@ -329,10 +329,7 @@ import { RouterApp, RouterLive } from "@weftui/router/client";
 import { Effect } from "effect";
 import { App } from "./app";
 
-const root = document.getElementById("root");
-if (root === null) {
-  throw new Error("#root not found");
-}
+const root = document.getElementById("root")!;
 
 const app = WeftApp.make(RouterLive(App));
 void Effect.runPromise(WeftApp.mount(app, RouterApp(App), root));
@@ -485,10 +482,7 @@ import { RouterApp, RouterLive } from "@weftui/router/client";
 import { Effect } from "effect";
 import { App } from "./app";
 
-const root = document.getElementById("root");
-if (root === null) {
-  throw new Error("#root not found");
-}
+const root = document.getElementById("root")!;
 
 const app = WeftApp.make(RouterLive(App));
 void Effect.runPromise(WeftApp.hydrate(app, RouterApp(App), root));
@@ -557,7 +551,7 @@ Option.isSome(httpApiClient); // true under RouterLive, false under RouterServer
 | `RouterNotFound`    | `notFound()`, or no route matched                                     | `Boundary.catchTag(…)` (or the app-level `notFound` page) |
 | `RouterParamsError` | `Router.params` / `Router.query` on a missing/invalid key or no match | `Boundary.catchTag(…)`                                    |
 
-Both are modeled as `Schema.TaggedErrorClass`, so they encode/decode across the wire the same way `Boundary.rpc` replays typed failures.
+Both are modeled as `Schema.TaggedError`, so they encode/decode across the wire the same way `Boundary.rpc` replays typed failures.
 
 Recover locally by wrapping just the subtree that can fail, rather than relying on the app-level `notFound` page for everything: