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

@weftui/router 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 (24) hide show

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 +3 -3

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

package/docs/tutorial/02-reactivity.md CHANGED Viewed

@@ -7,54 +7,53 @@ description: Add component-local state with SubscriptionRef and weave its stream
 # Reactivity
-[Previously](https://weftui.dev/docs/tutorial/01-your-first-app) we mounted a static component. Now we make it change over time. This is the defining move in Weft: **weave a stream through the tree, and only that point updates.**
+[Previously](https://weftui.dev/docs/tutorial/01-your-first-app) you mounted a static counter shell. Now wire it up. This is the defining move in Weft: **weave a stream through the tree, and only that point updates.**
-## Local state with `SubscriptionRef`
+## Wire up the counter
-Use Effect's `SubscriptionRef` for component-local state. `SubscriptionRef.changes(ref)` returns a `Stream` that emits the current value and then every update. Pass that stream as a child or prop and the DOM at that spot becomes live:
+Use Effect's `SubscriptionRef` for component-local state. `SubscriptionRef.changes(ref)` returns a `Stream` that emits the current value and then every update. Pass that stream (or a derived stream) as a child and the DOM at that spot becomes live. Replace `src/app.ts`:
 ```typescript
+// src/app.ts
 import { h } from "@weftui/core";
-import { WeftApp } from "@weftui/dom/client";
-import { Effect, SubscriptionRef } from "effect";
+import { Effect, Stream, SubscriptionRef } from "effect";
-const Counter = () =>
+export const App = () =>
   Effect.gen(function* () {
     const count = yield* SubscriptionRef.make(0);
-    return yield* h.div([
-      h.span([SubscriptionRef.changes(count)]),
-      h.button({ onclick: () => SubscriptionRef.update(count, (n) => n + 1) }, "+"),
-      h.button({ onclick: () => SubscriptionRef.update(count, (n) => n - 1) }, "-"),
+    const label = Stream.map(SubscriptionRef.changes(count), (n) => `Count: ${n}`);
+    return yield* h.div({ class: "app" }, [
+      h.h1("Weft Counter"),
+      h.p({ class: "count" }, [label]),
+      h.div({ class: "controls" }, [
+        h.button(
+          { type: "button", onclick: () => SubscriptionRef.update(count, (n) => n - 1) },
+          "−",
+        ),
+        h.button(
+          { type: "button", onclick: () => SubscriptionRef.update(count, (n) => n + 1) },
+          "+",
+        ),
+      ]),
     ]);
   });
-const app = WeftApp.make();
-void Effect.runPromise(WeftApp.mount(app, Counter(), document.getElementById("root")!));
 ```
-`Effect.gen` lets you `yield*` the `SubscriptionRef` to set up state **before** building the tree. Because a `Node` is an `Effect`, the component body is an ordinary generator: no hooks, no dependency arrays.
-## The key idea: the body runs once
-The `Counter` function runs **exactly once**. It creates the ref, builds the tree, and returns. After that, nothing re-invokes it. The only thing that changes the DOM is the `SubscriptionRef.changes(count)` stream woven into the `h.span`.
+`main.ts` and `index.html` don't change. Reload and the buttons work.
-When you click `+`, `SubscriptionRef.update` pushes a new value, the stream emits, and the renderer patches _just that span's text_ in place. No diff, no re-render, no sibling touched.
+## Why this works
-This is what "streams are the weft" means in practice: reactivity is local to exactly where you thread a stream. Everything else is static. The full model is [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model); the vocabulary of stream-shaped values is [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives).
+`App`'s body runs **exactly once**: it creates the ref, builds the tree, and returns. Nothing re-invokes it afterward. The only thing that changes the DOM is the `label` stream woven into `h.p`.
-> **Note.** In `[SubscriptionRef.changes(count)]` the stream is passed as a child array. Static values (`"Hello"`, `5`) work in the same position and simply never change. The rule is uniform: a plain value is static, a stream-shaped value is reactive.
+Click `+` and `SubscriptionRef.update` pushes a new value, `label` emits `"Count: 1"`, and the renderer patches _just that paragraph's text_ in place. No diff, no re-render, no sibling touched.
-## Deriving values
+`label` also shows **deriving values**: because `SubscriptionRef.changes(count)` is a `Stream`, you shape reactive text with ordinary stream operators (`Stream.map` here) instead of a templating syntax. Anywhere you'd compute a derived value, map the stream.
-Because `SubscriptionRef.changes(count)` returns a `Stream`, you shape reactive text with ordinary stream operators:
-```typescript
-h.span([Stream.map(SubscriptionRef.changes(count), (n) => `Count: ${n}`)]);
-```
+> **Note.** A stream-shaped child or prop is reactive; a static value (`"Hello"`, `5`) is not and never changes. `h.h1("Weft Counter")` above is static for exactly that reason. The rule is uniform across the whole tree.
-Anywhere you would compute a derived value, map the stream instead. The derivation stays reactive.
+The full model is [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model); the vocabulary of stream-shaped values is [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives).
 ## Next
-- [Services and Async →](https://weftui.dev/docs/tutorial/03-services-and-async): pull dependencies from the environment and render async loading states
+- [Services and Async →](https://weftui.dev/docs/tutorial/03-services-and-async): read services from a button handler and load data asynchronously

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

@@ -7,15 +7,13 @@ description: Give handlers access to services from the environment, and render a
 # Services and Async
-[So far](https://weftui.dev/docs/tutorial/02-reactivity) our state has been self-contained. Real apps talk to services and wait on async work. Both fall out of the same fact (a `Node` is an `Effect`), so both use plain Effect.
+[So far](https://weftui.dev/docs/tutorial/02-reactivity) the counter's state has been self-contained. Real apps talk to services and wait on async work. Both fall out of the same fact (a `Node` is an `Effect`), so both use plain Effect. This step adds a logging service to the buttons and an async fact panel below the counter.
 ## Handlers that use services
 An event handler can **return an Effect**. That Effect runs in the app's environment, so it can read any service the app's layer provides:
 ```typescript
-import { h } from "@weftui/core";
-import { WeftApp } from "@weftui/dom/client";
 import { Context, Effect, Layer } from "effect";
 class Logger extends Context.Service<Logger, { log: (message: string) => Effect.Effect<void> }>()(
@@ -23,60 +21,113 @@ class Logger extends Context.Service<Logger, { log: (message: string) => Effect.
 ) {}
 const LoggerLive = Layer.succeed(Logger, {
-  log: (message) => Effect.sync(() => console.log(message)),
+  log: (message) => Effect.log(message),
 });
+```
-const LogButton = () =>
-  h.button(
-    {
-      onclick: () =>
-        Effect.gen(function* () {
-          const logger = yield* Logger;
-          yield* logger.log("Button clicked");
-        }),
-    },
-    "Log",
-  );
+Wire it into the counter's `step` handler, so every click logs before updating state:
-// Give the app the layer: every handler in every root can now read Logger.
-const app = WeftApp.make(LoggerLive);
-void Effect.runPromise(WeftApp.mount(app, LogButton(), document.getElementById("root")!));
+```typescript
+const step = (delta: number) =>
+  Effect.gen(function* () {
+    const logger = yield* Logger;
+    yield* SubscriptionRef.update(count, (n) => n + delta);
+    yield* logger.log(`count changed by ${delta}`);
+  });
 ```
-`Logger` entered the tree's requirement channel the moment `LogButton` read it. You discharged it **once**, by passing `LoggerLive` to `WeftApp.make`. Provide too little and it is a compile error. The type of `app` (and so of `WeftApp.mount(app, LogButton(), …)`) names exactly which service is missing.
-Services come exclusively from the app's layer: an `Effect.provide` wrapped around the `mount` call does **not** reach components or handlers. This is Weft's entire dependency-injection story; it is just Effect's. The deeper treatment is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
+`Logger` entered the tree's requirement channel the moment `step` read it. You'll discharge it **once**, by passing `LoggerLive` to `WeftApp.make`. Provide too little and it's a compile error. Services come exclusively from the app's layer: an `Effect.provide` wrapped around the `mount` call does **not** reach components or handlers. This is Weft's entire dependency-injection story; it's just Effect's. The deeper treatment is [Services and Context](https://weftui.dev/docs/explanation/services-and-context).
 ## Async loading states
 A component can return a **`Stream<Node>`** to show different content over time. Sequence a loading placeholder before the resolved content with `Stream.concat`:
 ```typescript
+const fetchFact = (n: number) =>
+  Effect.gen(function* () {
+    yield* Effect.sleep("800 millis");
+    return `${n} is ${n % 2 === 0 ? "even" : "odd"}.`;
+  });
+const NumberFact = ({ n }: { n: number }) =>
+  Stream.concat(
+    Stream.make(h.p({ class: "fact" }, "Loading a fact…")),
+    Stream.fromEffect(Effect.map(fetchFact(n), (fact) => h.p({ class: "fact" }, fact))),
+  );
+```
+The stream emits the loading node first, then the resolved node. The renderer swaps the DOM in place on the second emission. This is the raw mechanism; to coordinate _several_ async regions with one fallback, reach for [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense).
+## Put it together
+Replace `src/app.ts`, adding both pieces as part of the same tree:
+```typescript
+// src/app.ts
 import { h } from "@weftui/core";
-import { WeftApp } from "@weftui/dom/client";
-import { Effect, Stream } from "effect";
+import { Context, Effect, Layer, Stream, SubscriptionRef } from "effect";
+export class Logger extends Context.Service<
+  Logger,
+  { log: (message: string) => Effect.Effect<void> }
+>()("Logger") {}
+export const LoggerLive = Layer.succeed(Logger, {
+  log: (message) => Effect.log(message),
+});
-const AsyncGreeting = ({ name }: { name: string }) =>
+const fetchFact = (n: number) =>
+  Effect.gen(function* () {
+    yield* Effect.sleep("800 millis");
+    return `${n} is ${n % 2 === 0 ? "even" : "odd"}.`;
+  });
+const NumberFact = ({ n }: { n: number }) =>
   Stream.concat(
-    Stream.make(h.span("Loading…")),
-    Stream.fromEffect(
-      Effect.gen(function* () {
-        yield* Effect.sleep("1 second");
-        return yield* h.span(`Hello, ${name}!`);
-      }),
-    ),
+    Stream.make(h.p({ class: "fact" }, "Loading a fact…")),
+    Stream.fromEffect(Effect.map(fetchFact(n), (fact) => h.p({ class: "fact" }, fact))),
   );
-const app = WeftApp.make();
-void Effect.runPromise(
-  WeftApp.mount(app, AsyncGreeting({ name: "World" }), document.getElementById("root")!),
-);
+export const App = () =>
+  Effect.gen(function* () {
+    const count = yield* SubscriptionRef.make(0);
+    const label = Stream.map(SubscriptionRef.changes(count), (n) => `Count: ${n}`);
+    const step = (delta: number) =>
+      Effect.gen(function* () {
+        const logger = yield* Logger;
+        yield* SubscriptionRef.update(count, (n) => n + delta);
+        yield* logger.log(`count changed by ${delta}`);
+      });
+    return yield* h.div({ class: "app" }, [
+      h.h1("Weft Counter"),
+      h.p({ class: "count" }, [label]),
+      h.div({ class: "controls" }, [
+        h.button({ type: "button", onclick: () => step(-1) }, "−"),
+        h.button({ type: "button", onclick: () => step(1) }, "+"),
+      ]),
+      NumberFact({ n: 3 }),
+    ]);
+  });
 ```
-The stream emits the loading node first, then the resolved node. The renderer swaps the DOM in place on the second emission.
+Give the app the layer in `src/main.ts`:
+```typescript
+// src/main.ts
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App, LoggerLive } from "./app";
+const root = document.getElementById("root")!;
+const app = WeftApp.make(LoggerLive);
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
-This is the raw mechanism. To coordinate _several_ async regions with a single fallback, reach for [`Boundary.suspend`](https://weftui.dev/docs/explanation/boundaries-and-suspense), which you will meet in the next step.
+Reload: the fact panel shows "Loading a fact…" then swaps in, and every click logs to the console.
 ## Next
-- [Errors and Server Rendering →](https://weftui.dev/docs/tutorial/04-errors-and-server): catch failures with boundaries and render on the server
+- [Errors and Server Rendering →](https://weftui.dev/docs/tutorial/04-errors-and-server): catch the fact panel's failures with a boundary and render the whole app on the server