npm - @weftui/core - Versions diffs - 0.30.0 → 0.31.0 - Mend

@weftui/core 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/dist/{index-CX9uEejU.d.ts → index-B-dPfhKZ.d.ts} +13 -0
package/dist/index.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/types/index.d.ts +1 -1
package/docs/explanation/boundaries-and-suspense.md +36 -6
package/docs/explanation/combinator-api.md +17 -11
package/docs/explanation/reactive-primitives.md +40 -13
package/docs/explanation/rendering-model.md +14 -2
package/docs/how-to/add-routing.md +2 -8
package/docs/how-to/author-components.md +69 -103
package/docs/how-to/compose-behavior-and-markup.md +141 -54
package/docs/how-to/handle-forms.md +142 -15
package/docs/how-to/load-async-data.md +110 -6
package/docs/how-to/load-data-with-rpc.md +167 -14
package/docs/how-to/provide-services.md +84 -1
package/docs/how-to/render-keyed-lists.md +116 -10
package/docs/how-to/render-on-the-server.md +111 -13
package/docs/how-to/show-navigation-progress.md +118 -12
package/docs/how-to/split-routes-lazily.md +106 -3
package/docs/how-to/style-reactively.md +141 -13
package/docs/how-to/use-element-refs.md +126 -8
package/docs/reference/core.md +20 -0
package/docs/reference/dom.md +43 -0
package/docs/tutorial/01-your-first-app.md +43 -13
package/docs/tutorial/02-reactivity.md +29 -30
package/docs/tutorial/03-services-and-async.md +89 -38
package/docs/tutorial/04-errors-and-server.md +41 -25
package/package.json +1 -1

package/docs/how-to/split-routes-lazily.md CHANGED Viewed

@@ -9,7 +9,7 @@ description: Code-split a route's component into its own chunk with Router.lazy,
 **Goal:** keep a heavy page's render code (and its dependencies) out of the initial bundle, loading it only when its route is actually rendered.
-Wrap the route's `component` in [`Router.lazy`](https://weftui.dev/docs/reference/router#routerlazy). The route **descriptor** (its segment and param schemas) stays eager, so the matcher, `href`, and the server's dispatch API still see it statically. Only the component body is split into its own chunk.
+Wrap the route's `component` in [`Router.lazy`](https://weftui.dev/docs/reference/router#routerlazy):
 ```typescript
 import { Router } from "@weftui/router";
@@ -21,7 +21,7 @@ Router.route("docs/:category/:slug", {
 });
 ```
-The chunk loads on the server during render and on the client on navigation. Only the **matched branch's** chunks are ever fetched.
+The route's **descriptor** (segment, `path`/`query` schemas) stays eager, so the matcher, `href`, and the server's dispatch API still see it statically. Only the component body is split into its own chunk, fetched on the server during render and on the client on navigation. Only the **matched branch's** chunks are ever loaded.
 `E`/`R` are preserved: a lazy route has the exact same channels as the same component declared eagerly. An unmet service requirement is still a compile error at `Router.router(...)`.
@@ -48,14 +48,117 @@ A descriptor file that still `import`s the impl statically gains nothing: the bu
 - **Flash-free hydration.** On a directly-loaded lazy route, the client re-invokes the same slot, awaits the chunk, and adopts the server DOM in place. The first production matches, so nothing is mutated.
 - **Blank-free navigation.** Client navigation is **deferred-commit**: the router resolves the target branch's chunk **and the matched leaf's own component effect** _before_ committing the URL. The previous page stays mounted through the fetch and any data the leaf awaits, and the swap is a single tick. See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for the `Router.navigating` signal this exposes.
-- **Synchronous revisits.** `Router.lazy` memoizes its load per slot, so a second visit to a loaded route commits immediately.
+- **Synchronous revisits.** `Router.lazy` memoizes its load per slot. The first render triggers the `import()`; every later render (including a revisit after navigating away) reuses the resolved module.
+```typescript
+// One slot, created once. Its loader Promise resolves on first render and is
+// reused on every later render, including back-navigation to this route.
+const page = Router.lazy(() => import("./doc-page").then((m) => m.DocPage));
+Router.route("docs/intro", { component: page });
+```
 ## Edge cases
 - **Lazy layouts.** A `Router.layout({ component: Router.lazy(...) })` splits too. Each lazy node in the matched branch is awaited; nodes outside it never load.
+  ```typescript
+  Router.layout(
+    { component: Router.lazy(() => import("./admin-shell").then((m) => m.AdminShell)) },
+    [settingsRoute, usersRoute],
+  );
+  ```
 - **Chunk-load failure is a defect.** If the `import()` rejects (offline, or a stale client requesting a chunk a new deploy removed), it dies as a defect and surfaces through normal defect handling. It never hangs or silently 404s. The rejection is memoized, so the route keeps failing until a reload (the deploy-skew case).
 - **Not a lazy _subtree_.** Only the component is lazy. You cannot defer a whole `RouteNode` behind an `import()`; the matcher needs every leaf's segment and param schema before anything loads.
+## Complete example
+A client-only app with two routes: `Home` (eager) and `Lazy` (split into its own chunk). This is the whole file set, copy/paste runnable in a `vite` + `@weftui/router` project.
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Weft lazy routing demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+```typescript
+// src/lazy-page.ts
+/**
+ * The lazily-loaded page body. Kept in its own module so the dynamic
+ * `import()` in `app.ts` is a real code-split point, not just a wrapper
+ * around a statically-imported value.
+ */
+import { Component, h } from "@weftui/core";
+export const LazyPage = Component.make(() =>
+  h.section({ id: "page" }, [h.h2("Lazy page"), h.p("Loaded on demand.")]),
+);
+```
+```typescript
+// src/app.ts
+/**
+ * Client-only lazy-routing demo: a Home route declared eagerly, and a Lazy
+ * route whose component is code-split via `Router.lazy`. Side-effect-free (no
+ * mount call), so `main.ts` and any test can import `App` directly.
+ */
+import { Component, h } from "@weftui/core";
+import { href, Router } from "@weftui/router";
+const homeRoute = Router.route("", {
+  component: Component.make(() => h.section({ id: "page" }, [h.h2("Home")])),
+});
+const lazyRoute = Router.route("lazy", {
+  component: Router.lazy(() => import("./lazy-page").then((m) => m.LazyPage)),
+});
+const Shell = Component.gen(function* () {
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ id: "app" }, [
+    h.nav([h.a({ href: href(homeRoute) }, "Home"), " · ", h.a({ href: href(lazyRoute) }, "Lazy")]),
+    h.main([outlet]),
+  ]);
+});
+export const App = Router.router(Router.layout({ component: Shell }, [homeRoute, lazyRoute]), {
+  notFound: () => h.section({ id: "page" }, [h.h2("404: page not found")]),
+});
+```
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the lazy-routing demo into `#root`. No server render
+ * to hydrate, so this uses `WeftApp.mount`, not `hydrate`.
+ */
+import { WeftApp } from "@weftui/dom/client";
+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 app = WeftApp.make(RouterLive(App));
+void Effect.runPromise(WeftApp.mount(app, RouterApp(App), root));
+```
+Load `/`, open the network panel, then click "Lazy": `lazy-page`'s chunk fetches only on that click, not on initial load. Click "Home" then "Lazy" again and no second fetch fires: the slot's memo serves the resolved component.
 ## See also
 - [`Router.lazy` API reference](https://weftui.dev/docs/reference/router#routerlazy)

package/docs/how-to/style-reactively.md CHANGED Viewed

@@ -7,9 +7,9 @@ description: Drive inline styles from streams (a single property, or a whole sty
 # Style Reactively
-**Goal:** animate or react to state in an element's inline style without re-rendering. Drive a single CSS property, or a whole style object, from a stream.
+**Goal:** animate or react to state in an element's inline style without re-rendering.
-The `style` prop accepts the [`Source`](https://weftui.dev/docs/explanation/reactive-primitives) vocabulary at any level. A property value can be a stream, and you can spread a stream of style objects. CSS `transition` composes naturally, because the renderer mutates the existing node in place.
+The `style` prop accepts the [`Source`](https://weftui.dev/docs/explanation/reactive-primitives) vocabulary at either level: a single property's value, or the whole object. CSS `transition` composes naturally, because a stream emission patches the existing DOM node in place.
 ```typescript
 import { h } from "@weftui/core";
@@ -34,27 +34,155 @@ const AnimatedHue = () => {
 };
 ```
-## Three modes
+## Per-property streams
-1. **A single property as a stream.** As above: one key's value is a `Stream`, the others are static strings. Each stream property is subscribed independently.
-2. **A static object.** An ordinary `style: { backgroundColor: "#667eea" }` with no streams; nothing updates.
-3. **A whole style object as a stream.** Spread a stream that emits complete style objects, merged with static props:
+Give one or more keys a `Stream` value and leave the rest as plain strings. Each reactive key subscribes independently, so two properties can animate off unrelated sources on the same element:
 ```typescript
-const pulse = Stream.make(1, 0.5).pipe(
-  Stream.schedule(Schedule.spaced("800 millis")),
-  Stream.forever,
+const size = Stream.iterate(100, (s) => (s >= 150 ? 100 : s + 10)).pipe(
+  Stream.schedule(Schedule.spaced("200 millis")),
 );
-h.div({ style: { ...pulse, transition: "opacity 0.4s ease-in-out" } }, "Pulse");
+h.div({
+  style: {
+    width: Stream.map(size, (s) => `${s}px`),
+    height: Stream.map(size, (s) => `${s}px`),
+    transition: "width 0.2s, height 0.2s",
+  },
+});
+```
+A key without a stream stays static: an ordinary `style: { backgroundColor: "#667eea" }` never updates.
+## Whole-object streams
+Give `style` itself a `Stream` that emits complete style objects. Each emission replaces every property on the element, so it's the right shape for changes that move several properties together:
+```typescript
+const theme = Stream.make(
+  { backgroundColor: "#667eea", transform: "scale(1)" },
+  { backgroundColor: "#764ba2", transform: "scale(1.1)" },
+).pipe(Stream.schedule(Schedule.spaced("1 second")), Stream.forever);
+h.div({
+  // fold the static `transition` into every emitted object: the renderer
+  // clears and resets all style properties on each emission, so a sibling
+  // key can't survive alongside it. Spreading `theme` into a style object
+  // literal doesn't work either, since that copies the Stream's own fields,
+  // not the values it emits.
+  style: Stream.map(theme, (s) => ({ ...s, transition: "all 0.3s ease" })),
+});
+```
+## Reactive classes
+`Props.cx` (from `@weftui/dom`) builds a class string from static names and `{ className: condition }` records, where a condition may be a stream:
+```typescript
+import { h } from "@weftui/core";
+import { Props } from "@weftui/dom";
+h.div({ class: Props.cx("demo-box", { "demo-box--active": isActiveStream }) });
 ```
+See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup) for merging `class` across two prop bags.
 ## Notes
 - **Property names are camelCase** (`backgroundColor`, `boxShadow`), the same keys as the DOM `style` object.
-- **CSS transitions just work.** A stream emission patches the DOM node directly (no re-render), so the browser applies the `transition` as it would for any style mutation.
-- **Pace with `Schedule`.** The idiom for time-based style animation: `Stream.iterate`/`Stream.make` paced by `Stream.schedule(Schedule.spaced(…))` and looped with `Stream.forever`. Combine with any Effect timing you like.
-- **Classes have a reactive builder too.** `Props.cx` builds a class string from strings, falsy values, nested arrays, and `{ className: condition }` records, where a condition may be a stream. Merging two bags that both carry `class` concatenates them. See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup).
+- **CSS transitions just work.** A stream emission patches the DOM node directly (no re-render), so the browser applies `transition` as it would for any style mutation.
+- **Pace with `Schedule`.** `Stream.iterate`/`Stream.make`, paced by `Stream.schedule(Schedule.spaced(…))` and looped with `Stream.forever`, is the idiom for time-based style animation:
+```typescript
+Stream.iterate(0, (n) => n + 1).pipe(
+  Stream.schedule(Schedule.spaced("100 millis")),
+  Stream.forever,
+);
+```
+Combine with any Effect timing you like.
+## Complete example
+A page with one per-property demo (hue cycling) and one whole-object demo (theme switch), mounted into an empty `#root`. This is the whole file set, copy/paste runnable in a `vite` + `@weftui/core` project.
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Weft reactive styles demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+```typescript
+// src/app.ts
+/**
+ * Reactive styles demo: a per-property hue cycle and a whole-object theme
+ * switch. Side-effect-free (no mount call), so `main.ts` and any test can
+ * import `App` directly.
+ */
+import { h } from "@weftui/core";
+import { Schedule, Stream } from "effect";
+const AnimatedHue = () => {
+  const hue = Stream.iterate(0, (h) => (h + 2) % 360).pipe(
+    Stream.schedule(Schedule.spaced("50 millis")),
+  );
+  return h.div(
+    {
+      style: {
+        backgroundColor: Stream.map(hue, (h) => `hsl(${h}, 70%, 60%)`),
+        transition: "background-color 0.05s",
+        padding: "1rem",
+      },
+    },
+    "Hue",
+  );
+};
+const ThemeSwitch = () => {
+  const theme = Stream.make(
+    { backgroundColor: "#667eea", transform: "scale(1)" },
+    { backgroundColor: "#764ba2", transform: "scale(1.1)" },
+  ).pipe(Stream.schedule(Schedule.spaced("1 second")), Stream.forever);
+  return h.div(
+    {
+      style: Stream.map(theme, (s) => ({ ...s, transition: "all 0.3s ease", padding: "1rem" })),
+    },
+    "Theme",
+  );
+};
+export const App = () => h.div([AnimatedHue(), ThemeSwitch()]);
+```
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the reactive styles demo into `#root`.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("#root not found");
+}
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
 ## See also

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

@@ -32,15 +32,34 @@ const AutoFocusInput = () =>
   });
 ```
-## How it works
+## The `ref` prop
-- **The `ref` prop** takes a `SubscriptionRef<Option<T>>`. The renderer sets it to `Option.some(element)` **once**, when the element is created. The ref is therefore an `Option`: `None` until mount, `Some(el)` after.
-- **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). 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, so the observer would never fire.
+`ref` accepts a `SubscriptionRef<Option<T>>`, and nothing else: a plain `Ref` doesn't match the prop's type, and the renderer only recognizes a `SubscriptionRef`. The renderer sets it to `Option.some(element)` **once**, when the element is created:
+```typescript
+ref?:
+	| SubscriptionRef.SubscriptionRef<Option.Option<T>>
+	| ReadonlyArray<SubscriptionRef.SubscriptionRef<Option.Option<any>>>;
+```
+The ref is an `Option` because of this timing: `None` until mount, `Some(el)` after. It stays `Some` after unmount too; nothing clears it.
+## Fork the observer with `Effect.forkScoped`
+`Stream.filter(Option.isSome)` waits for the element, `Stream.take(1)` takes just its first appearance, and `Stream.runForEach` runs the imperative work once. Fork that pipeline with `Effect.forkScoped`, never `Effect.forkChild`:
+```typescript
+declare const observer: Effect.Effect<void>; // the filter/take/runForEach pipeline
+yield * Effect.forkScoped(observer); // ties the fiber to the component's instance scope
+yield * Effect.forkChild(observer); // wrong: dies the instant the component body returns
+```
+`forkScoped` ties the fiber to the component's **instance scope**, the ambient `Scope` the renderer provides per component. It lives as long as the component is mounted. `forkChild` binds to the transient component-body fiber instead, which is interrupted the instant the generator returns, so the observer would never fire.
 ## Read a ref imperatively
-When you only need the element later (e.g. in a click handler), skip the observer and read the ref on demand:
+When you only need the element later (e.g. in a click handler), skip the observer and read the ref on demand with `SubscriptionRef.get`:
 ```typescript
 const scroll = () =>
@@ -50,11 +69,110 @@ const scroll = () =>
   });
 ```
+## Share a ref across behaviors
+`ref` also accepts a `ReadonlyArray` of refs: every entry receives the element (fan-out). This is the single-ref contract that fan-out builds on, so a shared behavior's ref and your own can coexist on the same element:
+```typescript
+h.div({ ref: [measureRef, focusRef] });
+```
+`Props.merge` produces this array automatically when both prop bags being merged carry a `ref`, concatenating rather than overwriting. See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup) for the full merge rules.
+## Complete example
+An auto-focusing input and a measured box, mounted with no other services. The whole file set:
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Weft element ref demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+```typescript
+// src/app.ts
+/**
+ * Element ref demo: an auto-focusing input and a box that reports its own
+ * measured size after mount. Side-effect-free (no mount call), so `main.ts`
+ * and any test can import `App` directly.
+ */
+import { h } from "@weftui/core";
+import { Effect, Option, pipe, Stream, SubscriptionRef } from "effect";
+const AutoFocusInput = () =>
+  Effect.gen(function* () {
+    const inputRef = yield* SubscriptionRef.make<Option.Option<HTMLInputElement>>(Option.none());
+    yield* pipe(
+      SubscriptionRef.changes(inputRef),
+      Stream.filter(Option.isSome),
+      Stream.take(1),
+      Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
+      Effect.forkScoped,
+    );
+    return yield* h.input({ ref: inputRef, type: "text", placeholder: "I'm focused!" });
+  });
+const MeasuredBox = () =>
+  Effect.gen(function* () {
+    const boxRef = yield* SubscriptionRef.make<Option.Option<HTMLDivElement>>(Option.none());
+    const size = yield* SubscriptionRef.make("measuring...");
+    yield* pipe(
+      SubscriptionRef.changes(boxRef),
+      Stream.filter(Option.isSome),
+      Stream.take(1),
+      Stream.runForEach((el) =>
+        Effect.gen(function* () {
+          const rect = el.value.getBoundingClientRect();
+          yield* SubscriptionRef.set(size, `${rect.width}x${rect.height}`);
+        }),
+      ),
+      Effect.forkScoped,
+    );
+    return yield* h.div([
+      h.div({ ref: boxRef, style: { width: "200px", height: "80px", border: "1px solid" } }),
+      h.p(["size: ", SubscriptionRef.changes(size)]),
+    ]);
+  });
+export const App = () => h.div([AutoFocusInput(), MeasuredBox()]);
+```
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the demo into `#root`. No app layer is needed here,
+ * so `WeftApp.make()` takes no arguments.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("#root not found");
+}
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
 ## Notes
-- A plain `Ref` suffices if you **only** read the element imperatively; use `SubscriptionRef` when you need to **react** to it becoming available.
-- Refs are set once at element creation and are not cleared on unmount.
-- **Several refs can share one element.** `ref` also accepts an array, and every entry receives the element: `h.div({ ref: [measure, focus] })`. `Props.merge` produces such an array when both bags carry a `ref`, so a shared behavior's ref and your own can coexist. See [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup).
+- A component with local state, like the two above, is written as a plain `Effect.gen` function; see [Component Authoring](https://weftui.dev/docs/how-to/author-components#components-with-internal-state).
 - Coming from React: `SubscriptionRef.make<Option<T>>(Option.none())` ↔ `useRef<T>(null)`; the `Stream.filter(Option.isSome)` observer ↔ a `useEffect` mount guard.
 ## See also

package/docs/reference/core.md CHANGED Viewed

@@ -421,6 +421,26 @@ type Source.Source<A, E, R> = A | Effect.Effect<A, E, R> | Stream.Stream<A, E, R
 Any prop or child that supports reactivity accepts a `Source.Source`. Static values, Effects, Streams, and Subscribables are all valid.
+#### `Source.changes(source)`
+Returns the change stream of any `Source`, without normalizing through
+`Subscribable` first:
+```typescript
+Source.changes<A, E, R>(source: Source.Source<A, E, R>): Stream.Stream<A, E, R>
+```
+Variant mapping:
+- **`Subscribable`** → its `changes` stream, by reference
+- **`Stream`** → returned as-is (identity, no wrap)
+- **`Effect`** → `Stream.fromEffect(source)`, emitting the resolved value once
+- **Static value** → `Stream.make(value)`, emitting once
+Unlike `Source.toSubscribable`, this allocates no `SubscriptionRef`, latch, or
+pump fiber. Use it where only the change stream is needed, e.g. list
+reconciliation reading a `Source<Iterable<A>>` directly.
 #### `Source.toSubscribable(source, key?)`
 Normalizes any `Source.Source` into a hot `Subscribable<A, E | NoPropValue, R>` scoped to the enclosing `Scope`:

package/docs/reference/dom.md CHANGED Viewed

@@ -156,6 +156,8 @@ any root. Examples: `app.runtime.runFork(trackPageviews)` (see
 interface RootHandle {
   readonly element: HTMLElement;
   unmount(): Effect.Effect<void>;
+  readonly awaitCommit: Effect.Effect<number>;
+  readonly commitGeneration: Effect.Effect<number>;
 }
 ```
@@ -166,6 +168,47 @@ 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.
+#### `RootHandle.awaitCommit`
+```ts
+readonly awaitCommit: Effect.Effect<number>;
+```
+Resolves when everything dirty at the time you run this effect has committed to
+the DOM or been discarded, yielding the commit generation.
+- **Immediate when idle.** If nothing is dirty, it resolves right away with the
+  current generation; there is no forced tick.
+- **Quiescence-scoped, not future-scoped.** It covers only writes already
+  delivered to the Loom at call time, not values a descendant pump writes
+  later. Stream delivery from a `set` to its region's cell is itself
+  asynchronous, so give the pump a beat (or check the DOM, or compare
+  `commitGeneration`) before treating one `awaitCommit` as covering that
+  specific write.
+- **Resolves across `WeftApp.dispose`.** Interrupting the app's flush fiber
+  resolves every outstanding barrier; no caller hangs across app disposal.
+- **App-scoped, not root-scoped.** One Loom is shared by every root of a
+  `WeftApp`. With multiple mounted roots, `awaitCommit` may also wait on a
+  sibling root's pending commits (a documented superset of "this root's
+  commits"). Per-root filtering is not implemented.
+```ts
+yield * SubscriptionRef.set(count, 1);
+yield * Effect.sleep("10 millis"); // let the emission reach the region's cell
+yield * handle.awaitCommit; // everything delivered so far is now in the DOM
+```
+#### `RootHandle.commitGeneration`
+```ts
+readonly commitGeneration: Effect.Effect<number>;
+```
+The app's current commit generation: a monotonic counter, shared across every
+root of the `WeftApp`, incremented once per flush pass that committed at least
+one cell. Reading it does not wait for anything in flight; pair it with
+`awaitCommit` to observe a specific commit rather than just the latest count.
 ### `UnhandledError`
 ```ts

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

@@ -9,6 +9,8 @@ description: "Install Weft, build a component with the h namespace, and mount it
 We assume you know [Effect](https://effect.website/docs/getting-started/introduction) fundamentals. Weft is Effect for the UI, so we will not re-explain `Effect.gen`, services, or streams from scratch.
+Across this tutorial you build one app: a counter. This step renders its static shell.
 ## Install
 ```bash
@@ -17,33 +19,61 @@ 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
+## Build and mount it
-A **component is a plain function you call**. There is no JSX and no `<Component/>` deferral. It returns a `Node`, which is just an `Effect` that produces a DOM node:
+A **component is a plain function you call**. There is no JSX and no `<Component/>` deferral. `App()` returns a `Node`, and the `h` namespace builds one: every property (`h.div`, `h.h1`, `h.button`, …) is a builder for that HTML tag, taking optional props and children.
 ```typescript
+// src/app.ts
 import { h } from "@weftui/core";
+export function App() {
+  return h.div({ class: "app" }, [
+    h.h1("Weft Counter"),
+    h.p({ class: "count" }, "Count: 0"),
+    h.div({ class: "controls" }, [
+      h.button({ type: "button" }, "−"),
+      h.button({ type: "button" }, "+"),
+    ]),
+  ]);
+}
+```
+```typescript
+// src/main.ts
 import { WeftApp } from "@weftui/dom/client";
 import { Effect } from "effect";
+import { App } from "./app";
-function App() {
-  return h.div({ class: "app" }, [h.h1("Hello, Weft"), h.p("A minimal app.")]);
-}
+const root = document.getElementById("root")!;
 const app = WeftApp.make();
-void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Weft counter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
 ```
-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`.
+Run it with `vite` (or any dev server that serves ES modules) and you get a heading, a static count, and two inert buttons. The buttons don't do anything yet: that's next.
 ## 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).
-- `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 with 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.
+- `App()` returns a **`Node<never, never>`**, an `Effect` that resolves to an element descriptor, not a DOM node yet. `E` and `R` are `never` 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: see [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model).
+- `WeftApp.make()` creates a Weft app synchronously, with no layer to build yet. `WeftApp.mount(app, node, root)` renders `node` into `root`, building real DOM. It returns `Effect<RootHandle, …>` with `R = never`, so a bare `Effect.runPromise` runs it. You'll give `WeftApp.make` a `Layer` once components need services: see [Services and Async](https://weftui.dev/docs/tutorial/03-services-and-async).
+- `App` runs **once**. Nothing re-invokes it, because there's no state yet.
 ## Next
-- [Reactivity →](https://weftui.dev/docs/tutorial/02-reactivity): make the UI change over time with `SubscriptionRef` and streams
+- [Reactivity →](https://weftui.dev/docs/tutorial/02-reactivity): wire up the counter with `SubscriptionRef` and streams