@weftui/core 0.30.0 → 0.31.1

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

@@ -7,11 +7,11 @@ description: Plain functions vs. Component.gen / Component.make, instance scope,
 
 # Component Authoring
 
-Weft components are plain TypeScript functions that return a `Node<E, R>`. This guide covers the two ways to define them and when to choose each.
+**Goal:** write a Weft component, a plain function returning a `Node<E, R>`, and pick the right authoring style for its complexity.
 
 ## Plain functions
 
-The simplest component is just a function:
+Static props, no internal state: write and call a plain function.
 
 ```typescript
 import { h } from "@weftui/core";
@@ -20,19 +20,18 @@ function Greeting({ name }: { name: string }) {
   return h.p(`Hello, ${name}!`);
 }
 
-// Call it like a function
-Greeting({ name: "World" });
+Greeting({ name: "World" }); // called directly, no JSX, no deferred descriptor
 ```
 
-Use a plain function when:
+Reach for this when:
 
-- Props are all static (strings, numbers, plain functions)
-- The component has no internal state
-- You don't need the caller's reactive prop types to propagate
+- Props are all static (strings, numbers, plain functions).
+- The component has no internal state.
+- You don't need the caller's reactive prop types to propagate into the return type.
 
 ## Components with internal state
 
-When a component needs reactive state, use `Effect.gen` to set it up before building the tree. The component function still runs once. The setup happens at mount time:
+Set up reactive state with `Effect.gen` before building the tree. The component function still runs once; the setup happens at mount time:
 
 ```typescript
 import { h } from "@weftui/core";
@@ -49,68 +48,16 @@ const Counter = () =>
   });
 ```
 
-The return type here is `Effect.Effect<Node, never, never>`, itself a valid `Node`, so it composes naturally with other tree-building calls.
+`Effect.Effect<Node, never, never>` is itself a valid `Node`, so it composes with any other tree-building call.
 
-As soon as such a component is reused or takes props, wrap the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below). That way the caller's reactive prop and children channels flow into its node type.
+Once a component like this is reused or takes props, wrap the same generator in `Component.gen` (below) so the caller's reactive prop and children channels flow into its node type.
 
-## Component scope and background effects
+## `Component.gen` / `Component.make`
 
-Every component instance is rendered under its own **instance scope**, a child of the
-mount scope created fresh for that instance. Anything bound to the instance scope lives
-exactly as long as the component is mounted. It is torn down automatically when the
-component unmounts (or when its root unmounts via `RootHandle.unmount()`).
+Both build a component whose returned `Node`'s `E`/`R` include the caller's reactive prop and children channels, not just the body's own:
 
-The renderer provides this scope as the ambient `Scope.Scope` while it evaluates the
-component body, so it is already in context when you need it.
-
-This matters the moment a component starts **background work**: a subscription, an
-observer of a `ref`, a polling timer, anything you `fork`. The rule:
-
-> Fork background work with **`Effect.forkScoped`**, never a bare `Effect.forkChild`.
-
-`Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for
-the component's lifetime and is interrupted on unmount. A bare `Effect.forkChild` instead
-attaches the fiber to the component-body fiber, the one that runs your `Effect.gen` to
-produce the tree. That fiber completes the instant the gen returns its node, so the
-forked work is cancelled almost immediately.
-
-Concretely, an observer that runs an effect when a `ref`'s element mounts:
-
-```typescript
-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, // ✅ tied to the instance scope: survives until unmount
-      // Effect.forkChild, // ❌ tied to the body fiber: interrupted when the gen returns
-    );
-
-    return yield* h.input({ ref: inputRef, type: "text" });
-  });
-```
-
-You do not manage the scope yourself: you do not create it, close it, or pass it
-around. `forkScoped` reads it from context, and unmount closes it for you. If you ever
-fork outside a component body (rare), you must supply a `Scope.Scope` yourself. The
-type system will tell you, because `forkScoped` carries a `Scope.Scope` requirement.
-
-See `examples/element-ref` for the auto-focus, measure, and canvas recipes built on
-this pattern.
-
-## `Component.gen` / `Component.make` for reusable components
-
-When you want the caller's reactive prop types to flow into the returned node's type, use one of the `Component` factories. Both have the same call semantics; pick the body style that fits:
-
-- **`Component.make`**: body is a plain function returning any `Effect` (typically a `Node`). Use for one-liners and pipe compositions.
-- **`Component.gen`**: body is a generator. Use when you need `yield*` to set up local state or pull from services.
+- **`Component.make`**: body is a plain function returning any `Effect`. Use for one-liners and pipe compositions.
+- **`Component.gen`**: body is a generator. Use when you need `yield*` for local state or services.
 
 ```typescript
 import { Component, h, Source } from "@weftui/core";
@@ -128,40 +75,28 @@ const Card = Component.make((props: CardProps) =>
 );
 ```
 
-`Source.Source<string>` is Weft's caller-facing prop vocabulary: a single type covering a static `string`, a `Stream<string>`, an `Effect<string>`, or a `Subscribable<string>`. You don't hand-write `string | Stream.Stream<string> | …` on every prop.
-
-Passing a `Source` straight to `h` (as above) is all you need when the value is just spliced into the tree. The renderer normalizes it.
-
-Now the caller's stream types are visible in the returned node:
-
 ```typescript
 declare const titleStream: Stream.Stream<string, never, I18nService>;
 
-// Node<never, I18nService>: I18nService requirement flows out
+// Node<never, I18nService>: I18nService flows out from the prop the caller passed
 const card = Card({ title: titleStream });
 ```
 
-Without a `Component` factory, a plain function's return type is fixed at definition time and won't reflect the caller's reactive prop types.
+Without a `Component` factory, a plain function's return type is fixed at definition time and can't reflect what the caller actually passes.
 
-### Body `E`/`R` inference
-
-You don't declare the body's `E`/`R` channels explicitly. They're inferred from the returned (or yielded) effect:
-
-- The body's `E`/`R` come from whatever effects appear inside.
-- The caller's reactive prop channels and reactive children channels are unioned on top at the call site.
+- The body's `E`/`R` come from whatever effects it yields or returns.
+- Caller prop channels and children channels are unioned on top at the call site.
 - Static prop values (`string`, `number`, plain functions) contribute `never`.
 
 ### Children: array or function
 
-Both factories accept an optional second `children` argument, typed as:
-
 ```typescript
 type Component.Children<Input = never> =
   | readonly Renderable[]
   | ((input: Input) => readonly Renderable[]);
 ```
 
-The function form is the render-prop / slot pattern. The component invokes the function with whatever input it chooses, and the returned array's `E`/`R` propagate out:
+The function form is the render-prop / slot pattern. The component calls it with whatever `input` it chooses, and the returned array's `E`/`R` propagate out:
 
 ```typescript
 const ItemList = Component.make(
@@ -172,9 +107,9 @@ const ItemList = Component.make(
 ItemList({ items: ["a", "b"] }, (item) => [h.li(item)]);
 ```
 
-## Props typing
+## Props typing with `Source`
 
-For a prop that accepts both static and reactive values, type it as [`Source.Source<T>`](https://weftui.dev/docs/reference/core#source-namespace) rather than hand-writing the union. `Source.Source<T>` **is** that union: `T | Stream<T> | Effect<T> | Subscribable<T>`. The caller can pass a plain value or any reactive shape interchangeably, and you write it once:
+Type a prop that accepts both static and reactive values as `Source.Source<T>` instead of hand-writing the union:
 
 ```typescript
 import { Source } from "@weftui/core";
@@ -186,11 +121,9 @@ interface ButtonProps {
 }
 ```
 
-When a caller passes a plain string, the component's node type has `never` for that prop's channels. When they pass a `Stream.Stream<string, never, SomeService>`, `SomeService` appears in the `R` channel. The extraction is exactly `Source.Success` / `Source.Error` / `Source.Context`.
-
-### Reading a `Source` in the body
+`Source.Source<T>` **is** the union `T | Stream<T> | Effect<T> | Subscribable<T>`. A plain string contributes `never` to the node's channels; a `Stream<string, never, SomeService>` contributes `SomeService` to `R`. The extraction is `Source.Success` / `Source.Error` / `Source.Context`.
 
-Splicing a `Source` straight into `h` (`[props.label]`) is enough when you only place it in the tree. When the body needs to **read or derive** from the value (combine two props, feed a stream operator, drive logic), normalize it first with [`Source.toSubscribable`](https://weftui.dev/docs/reference/core#sourcetosubscribablesource-key). It turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
+Splicing a `Source` straight into `h` (`[props.label]`) is enough when the body only places it in the tree. Reach for `Source.toSubscribable` when the body needs to **read or derive** from it:
 
 ```typescript
 import { Component, h, Source, Subscribable } from "@weftui/core";
@@ -198,19 +131,48 @@ import { Stream } from "effect";
 
 const LoudLabel = Component.gen(function* (props: { label: Source.Source<string> }) {
   const label = yield* Source.toSubscribable(props.label); // Subscribable<string>
-  // Now derive from it like any Subscribable: static, Effect, and Stream inputs all work.
   return yield* h.strong([Stream.map(Subscribable.changes(label), (text) => text.toUpperCase())]);
 });
 ```
 
-`toSubscribable` is scoped:
-
-- A `Stream` prop is pumped by a fiber that terminates with the component's instance scope.
-- An `Effect` prop is memoized.
-- An existing `Subscribable` is threaded through by reference.
+- An existing `Subscribable` prop is threaded through by reference, no new fiber.
+- A `Stream` prop is pumped by a fiber scoped to the component's instance scope.
+- An `Effect` prop is memoized, so it runs at most once.
 - A static value emits once.
 
-It is the same normalization the renderer applies to props internally. Reach for it whenever you need the value as a `Subscribable` instead of leaving it opaque.
+## Instance scope and background effects
+
+Every component instance renders under its own **instance scope**, a child of the mount scope created fresh per instance. It closes on unmount (or when its root unmounts via `RootHandle.unmount()`). The renderer supplies it as the ambient `Scope.Scope` while your body runs, so it's already in context.
+
+Fork background work (a subscription, a ref observer, a polling timer) with **`Effect.forkScoped`**, never a bare `Effect.forkChild`:
+
+```typescript
+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, // ✅ tied to the instance scope: survives until unmount
+      // Effect.forkChild, // ❌ tied to the body fiber: interrupted when the gen returns
+    );
+
+    return yield* h.input({ ref: inputRef, type: "text" });
+  });
+```
+
+- `Effect.forkScoped` attaches the fiber to the instance scope, so it keeps running for the component's lifetime and is interrupted on unmount.
+- `Effect.forkChild` attaches to the component-body fiber instead, the one that runs your generator to produce the tree. That fiber completes the instant the body returns its node, so a bare fork is cancelled almost immediately.
+
+You never create, close, or pass the scope yourself: `forkScoped` reads it from context, and unmount closes it for you. Forking outside a component body (rare) requires supplying a `Scope.Scope`, and `forkScoped`'s own `Scope.Scope` requirement makes the type system tell you.
+
+See [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs) for the auto-focus, measure, and canvas recipes built on this pattern.
 
 ## Composing components
 
@@ -228,11 +190,11 @@ function App() {
 }
 ```
 
-Children arrays accumulate `E`/`R` from all their members. The parent node's type reflects the union of all children's channels.
+Children arrays accumulate `E`/`R` from all their members; the parent node's type reflects the union.
 
 ## Components that require services
 
-If a component's render function uses a service via `yield*`, that service appears in the component's `CompR` parameter:
+A service read via `yield*` inside the body appears in the component's `R` channel, regardless of what the caller passes:
 
 ```typescript
 import { Component, h } from "@weftui/core";
@@ -243,11 +205,11 @@ const UserAvatar = Component.gen(function* (props: { userId: string }) {
   return yield* h.img({ src: user.avatarUrl, alt: user.name });
 });
 
-// Node<never, UserService>: regardless of what the caller passes
+// Node<never, UserService>
 const avatar = UserAvatar({ userId: "123" });
 ```
 
-Give the service to the app layer:
+Give the service to the app layer, not to the mount call:
 
 ```typescript
 import { WeftApp } from "@weftui/dom/client";
@@ -257,9 +219,11 @@ const app = WeftApp.make(UserServiceLive);
 void Effect.runPromise(WeftApp.mount(app, App(), document.getElementById("root")!));
 ```
 
+See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for scoped layers, `memoMap` sharing, and why wrapping `Effect.provide` around the mount call doesn't work.
+
 ## Returning fragments
 
-When a component needs to return multiple sibling elements without a wrapper, use `h.fragment`:
+Return multiple sibling elements without a wrapper using `h.fragment`:
 
 ```typescript
 import { h } from "@weftui/core";
@@ -268,11 +232,13 @@ const TableCells = ({ row }: { row: Row }) =>
   h.fragment([h.td(row.name), h.td(row.value), h.td(row.status)]);
 ```
 
-`h.fragment` returns a `Node<E, R>` that accumulates channels from all its children.
+`h.fragment` returns a `Node<E, R>` that accumulates channels from all its children, same as any other `h.*` call.
 
 ## See also
 
 - [The Combinator API](https://weftui.dev/docs/explanation/combinator-api): `h`, `h.fragment`, and how `E`/`R` accumulate
 - [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives): the `Source` vocabulary props accept
+- [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs): `ref` props and scoped mount observers
+- [Provide Services](https://weftui.dev/docs/how-to/provide-services): app layers, scoped layers, and `memoMap`
 - [Add Routing](https://weftui.dev/docs/how-to/add-routing): route components are `Component` slots
 - [`@weftui/core` reference](https://weftui.dev/docs/reference/core): `Component`, `Source`, and the full surface

package/docs/how-to/compose-behavior-and-markup.md

@@ -7,29 +7,26 @@ description: "Use Props.merge to combine a behavior prop bag with your own marku
 
 # Compose Behavior and Markup
 
-**Goal:** share behavior (aria wiring, handlers, refs, reactive state) without
-giving up ownership of the element it applies to.
+`Props.merge` combines a behavior's prop bag (aria wiring, handlers, refs, reactive state) with markup you own, without either side losing what it contributed.
 
 ## The problem
 
-Behavior and markup usually want different owners. A dropdown's keyboard
-handling, `aria-expanded` wiring and anchor ref are worth writing once. The
-button itself is yours: your classes, your text, your extra handlers.
+Object spread can't combine two prop bags safely:
 
-Object spread cannot combine them. `{ ...behavior, ...mine }` silently drops the
-behavior's `onclick` when you supply your own, and drops its `ref` when you
-supply yours. Nothing warns you.
+```ts
+const merged = { ...behavior, ...mine };
+// mine.onclick replaces behavior.onclick entirely, and mine.ref replaces
+// behavior.ref entirely. Nothing warns you.
+```
 
-`Props.merge` reconciles both bags instead.
+`Props.merge` reconciles the collision per key instead of silently dropping a side.
 
 ## Behavior as a prop bag
 
-A behavior primitive is a plain Effect that yields a prop bag. There is no
-component wrapper and no hook rules, so you can `yield*` it anywhere and hold
-the result.
+A behavior primitive is a plain Effect that yields a prop bag. There's no component wrapper and no hook rules, so you `yield*` it anywhere and hold the result:
 
 ```ts
-import { Effect, Option, SubscriptionRef } from "effect";
+import { Effect, Option, Stream, SubscriptionRef } from "effect";
 
 const makeDisclosure = () =>
   Effect.gen(function* () {
@@ -38,7 +35,11 @@ const makeDisclosure = () =>
 
     const trigger = {
       ref: anchor,
-      "aria-expanded": SubscriptionRef.changes(isOpen),
+      // A boolean value renders as presence-only (`setAttribute(name, "")`),
+      // which is wrong for `aria-*`. Map to the literal string instead.
+      "aria-expanded": Stream.map(SubscriptionRef.changes(isOpen), (open) =>
+        open ? ("true" as const) : ("false" as const),
+      ),
       onclick: () => SubscriptionRef.update(isOpen, (open) => !open),
     };
 
@@ -46,13 +47,11 @@ const makeDisclosure = () =>
   });
 ```
 
-`makeDisclosure` returns a plain object, not a `DomProps`-typed value. `merge`
-accepts it as-is: it dispatches on each key's name, not on the bag's declared
-type.
+`makeDisclosure` returns a plain object, not a `DomProps`-typed value. `merge` accepts it as-is: it dispatches on each key's name, not on the bag's declared type.
 
-## Merge it onto your element
+## Merge onto your element
 
-You write the element. The bag merges onto it.
+You write the element; the bag merges onto it:
 
 ```ts
 import { h } from "@weftui/core";
@@ -74,24 +73,32 @@ const Panel = () =>
   });
 ```
 
-Three rules earn their keep in that one call:
+- **Handlers chain.** The disclosure toggles, then `trackClick` runs; a failure in one never blocks the other.
+- **Refs fan out.** `anchor` and `measure` both receive the element; spread would have kept only one.
+- **`class` takes a reactive condition.** `btn--open` follows `isOpen` through `Props.cx`.
+
+Type an inline handler's event explicitly (`(ev: MouseEvent)` above). `merge` doesn't know which element the bag will land on, so it can't infer it.
+
+## Per-key rules
+
+| Key           | Rule                                                                                         |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| `on*`         | Chained left to right. Both bodies run; failures from both sides are aggregated.             |
+| `class`       | Concatenated. All-static stays a `string`; either side reactive makes it a `Stream<string>`. |
+| `style`       | Two per-property objects merge per key, right wins. Any other shape is last-wins.            |
+| `ref`         | Fan out: concatenates into an array, and every ref receives the element.                     |
+| anything else | Last-wins.                                                                                   |
 
-1. **Handlers chain.** The disclosure toggles, then `trackClick` runs. Both
-   always run, and a failure in one does not prevent the other. A broken
-   analytics call cannot block the toggle.
-2. **Refs fan out.** `anchor` and `measure` both receive the element. Spread
-   would have kept only one, silently.
-3. **`cx` takes a reactive condition.** `btn--open` follows `isOpen`, and only
-   the class attribute updates.
+```ts
+Props.merge({ style: { color: "red" } }, { style: { fontWeight: "bold" } });
+// => { style: { color: "red", fontWeight: "bold" } }
+```
 
-Type an inline handler's event explicitly, as `(ev: MouseEvent)` above. `merge`
-does not know which element the bag will land on, so it cannot infer it.
+A key present on only one side passes through untouched.
 
-## Typed errors flow through
+## Typed errors and services flow through
 
-A handler that fails with a tagged error, or needs a service, keeps both
-channels through the merge. They surface on the component's `Node<E, R>`, so the
-app must provide the service and can catch the error at a boundary.
+A handler that fails with a tagged error, or needs a service, keeps both channels through the merge. They surface on the component's `Node<E, R>`, so the app must provide the service and can catch the error at a boundary:
 
 ```ts
 declare const rowBehavior: object;
@@ -109,35 +116,115 @@ h.button(Props.merge(rowBehavior, { onclick: () => deleteItem }), "Delete");
 
 ## Two gotchas that differ from spread
 
-- **`false` on a handler is an explicit opt-out and wins.** `null` and
-  `undefined` mean "not provided", so the other side survives instead.
-- **Every other key is genuinely last-wins.** Forwarding an omitted optional
-  prop (`{ id: props.id }`) still overwrites a default with `undefined`, the
-  same as `{ ...base, ...override }` would. Guard at the call site if that
-  matters.
+- **`false` on a handler is an explicit opt-out and wins.** `null`/`undefined` mean "not provided", so the other side survives instead:
+
+  ```ts
+  Props.merge({ onclick: () => track() }, { onclick: false }); // handler is off
+  ```
+
+- **Every other key is genuinely last-wins.** Forwarding an omitted optional prop (`{ id: props.id }`) still overwrites a default with `undefined`, the same as `{ ...base, ...override }` would. Guard at the call site if that matters.
+
+The [reference](https://weftui.dev/docs/reference/dom#propsmerge) has the full per-key rule table, including the `style` and reactive-class cases above.
 
-The [reference](https://weftui.dev/docs/reference/dom#propsmerge) has the full per-key rule
-table, including the `style` and reactive-class cases this guide doesn't
-cover.
+## Complete example
+
+A disclosure behavior merged onto a caller-owned button, with a click counter and a ref the behavior doesn't know about. This is the whole file set, copy/paste runnable in a `vite` + `@weftui/core`/`@weftui/dom` 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>Compose behavior and markup demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+```typescript
+// src/app.ts
+/**
+ * Disclosure behavior (open state, anchor ref, toggle handler) merged onto a
+ * button the caller owns: its own class, its own click counter, its own ref.
+ * Side-effect-free (no mount call), so `main.ts` and any test can import
+ * `App` directly.
+ */
+import { h } from "@weftui/core";
+import { Props } from "@weftui/dom";
+import { Effect, Option, Stream, SubscriptionRef } from "effect";
+
+const makeDisclosure = () =>
+  Effect.gen(function* () {
+    const isOpen = yield* SubscriptionRef.make(false);
+    const anchor = yield* SubscriptionRef.make(Option.none<HTMLElement>());
+
+    const trigger = {
+      ref: anchor,
+      "aria-expanded": Stream.map(SubscriptionRef.changes(isOpen), (open) =>
+        open ? ("true" as const) : ("false" as const),
+      ),
+      onclick: () => SubscriptionRef.update(isOpen, (open) => !open),
+    };
+
+    return { isOpen, trigger };
+  });
+
+export const App = () =>
+  Effect.gen(function* () {
+    const disclosure = yield* makeDisclosure();
+    const measure = yield* SubscriptionRef.make(Option.none<HTMLElement>());
+    const clicks = yield* SubscriptionRef.make(0);
+
+    return yield* h.div({ id: "app" }, [
+      h.button(
+        Props.merge(disclosure.trigger, {
+          class: Props.cx("btn", { "btn--open": SubscriptionRef.changes(disclosure.isOpen) }),
+          onclick: () => SubscriptionRef.update(clicks, (n) => n + 1),
+          ref: measure,
+        }),
+        "Details",
+      ),
+      h.p([
+        "clicked ",
+        Stream.map(SubscriptionRef.changes(clicks), String),
+        " times · ref fan-out: ",
+        Stream.map(SubscriptionRef.changes(measure), (captured) =>
+          Option.isSome(captured) ? "captured" : "pending",
+        ),
+      ]),
+    ]);
+  });
+```
+
+```typescript
+// src/main.ts
+/**
+ * Browser entry: mounts the demo into #root.
+ */
+import { WeftApp } from "@weftui/dom/client";
+import { Effect } from "effect";
+import { App } from "./app";
+
+const root = document.getElementById("root")!;
+
+const app = WeftApp.make();
+void Effect.runPromise(WeftApp.mount(app, App(), root));
+```
 
 ## When to use
 
-Reach for `Props.merge` when two parties contribute props to one element: a
-shared behavior and a caller, or a base variant and a caller's override. For
-a single bag you already control, write the object directly. Merge earns its
-cost only when a key could collide.
+Reach for `Props.merge` when two parties contribute props to one element: a shared behavior and a caller, or a base variant and a caller's override. For a single bag you already control, write the object directly. Merge only earns its cost when a key could collide.
 
-`Props.merge` is pure: calling it has no side effects and subscribes
-nothing. A merged `class` that turns out reactive is a `Stream` description.
-The renderer subscribes it once the element mounts, the same as any other
-reactive prop.
+`Props.merge` is pure: calling it has no side effects and subscribes nothing. A merged `class` that turns out reactive is a `Stream` description, not a live subscription. The renderer subscribes it once the element mounts, the same as any other reactive prop.
 
 ## See also
 
-- [Headless Menu example](https://github.com/stefvw93/weft/tree/main/examples/headless-menu): a full behavior
-  primitive (`Menu.trigger`/`popup`/`item`) merged onto consumer-owned markup,
-  with handler chaining, ref fan-out, and a service requirement flowing
-  through the merge into `Node<E, R>`.
+- [Headless Menu example](https://github.com/stefvw93/weft/tree/main/examples/headless-menu): a full behavior primitive (`Menu.trigger`/`popup`/`item`) merged onto consumer-owned markup, with handler chaining, ref fan-out, and a service requirement flowing through the merge into `Node<E, R>`.
 - [`@weftui/dom` reference](https://weftui.dev/docs/reference/dom): the full per-key rules and `cx` grammar
 - [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs): the single-ref contract that fan-out builds on
 - [Style Reactively](https://weftui.dev/docs/how-to/style-reactively): per-property style streams and `cx`