@weftui/core 0.27.1 → 0.29.0

package/docs/reference/dom.md

@@ -2,82 +2,219 @@
 title: "@weftui/dom"
 order: 2
 section: reference
-description: Full API surface for @weftui/dom — the client renderer (mount, hydrate) and the server renderer (renderToString and streaming variants).
+description: Full API surface for @weftui/dom, covering the WeftApp client runtime (make, mount, hydrate, errors, dispose), the server renderer (renderToString and streaming variants), and the Props.merge/Props.cx prop-bag composition utilities.
 ---
 
 # @weftui/dom API Reference
 
-The DOM renderer for Weft. It has two entry points — `@weftui/dom/client` for the
-browser and `@weftui/dom/server` for Node — plus a package root that re-exports the
-renderer error types. See the [Server-Side Rendering guide](https://weftui.dev/docs/how-to/render-on-the-server)
+The DOM renderer for Weft. It has two entry points: `@weftui/dom/client` for the
+browser and `@weftui/dom/server` for Node. A package root re-exports the renderer
+error types. See the [Server-Side Rendering guide](https://weftui.dev/docs/how-to/render-on-the-server)
 for a narrative walkthrough.
 
 ## `@weftui/dom/client`
 
-### `mount`
+`WeftApp` is the client entry point's app namespace (`export * as WeftApp from
+"./weft-app"`). One `WeftApp` value is one lazily-built `ManagedRuntime` (the app
+layer) + one root `Scope` + one unhandled-error hub.
+
+Each `WeftApp.mount` / `WeftApp.hydrate` call creates a child **root scope** under
+the app scope. Layer-built services are shared **by reference** across every root
+mounted from the same app (layer memoization). This is what makes cross-island
+reactive state work (see [examples/shared-state-islands](https://github.com/stefvw93/weft/tree/main/examples/shared-state-islands)).
+
+The barrel also re-exports `MountError`, `HydrateError`, `RootHandle`,
+`UnhandledError`, and the `WeftApp` interface's type as `WeftAppType` (renamed on
+export to avoid colliding with the `WeftApp` namespace import).
+
+### `WeftApp.make`
+
+```ts
+const make: {
+  (): WeftApp<never, never>;
+  <R, E>(
+    layer: Layer.Layer<R, E, never>,
+    options?: { readonly memoMap?: Layer.MemoMap },
+  ): WeftApp<R, E>;
+};
+```
+
+Creates a `WeftApp` from an app layer. `make` is synchronous and side-effect-free
+with respect to the layer: the layer builds **lazily** on the first `mount` /
+`hydrate` (or the first direct `app.runtime` run), per `ManagedRuntime.make`
+semantics.
+
+A layer whose construction has an observable side effect shows that effect only
+after the first mount, never at `make` time. `options.memoMap` shares layer
+memoization across multiple `WeftApp` instances.
+
+There is deliberately no `makeScoped`. To bind an app's lifetime to a scope,
+compose it yourself:
+
+```ts
+const acquireApp = Effect.acquireRelease(
+  Effect.sync(() => WeftApp.make(AppLive)),
+  (app) => WeftApp.dispose(app),
+);
+```
+
+### `WeftApp.mount`
+
+```ts
+const mount: <R, E>(
+  app: WeftApp<R, E>,
+  node: Renderable,
+  root: HTMLElement,
+) => Effect.Effect<RootHandle, E | MountError>;
+```
+
+Mounts `node` into `root` as a new root of `app`. The returned effect is
+self-contained: its requirement channel is `never`, so it runs with a bare
+`Effect.runPromise`. Services come exclusively from the app layer; an
+`Effect.provide` wrapped around this call does not reach components.
+
+Clears `root`'s existing children, renders, appends the result. Completes after
+initial render; streams keep running in the background, owned by the root's scope
+(a child of the app scope).
+
+The app layer builds lazily here on first mount; its error channel `E` surfaces at
+that point. On render failure the root scope is closed before the error propagates;
+the app runtime and other roots are untouched. Mounting on a disposed app fails
+rather than hanging.
+
+### `WeftApp.hydrate`
+
+```ts
+function hydrate<A extends Renderable, R = never, E = never>(
+  app: WeftApp<R, E>,
+  node: A,
+  root: HTMLElement,
+): [AssertNoServerOnly<CoreNode.Context<A>>] extends [CoreNode.Context<A>]
+  ? Effect.Effect<RootHandle, E | HydrateError>
+  : ServerOnlyLeak;
+```
+
+Continues, on the client, the DOM produced on the server by
+`renderToStringHydratable` / `renderToStreamHydratable`, as a new root of `app`.
+Unlike `mount`, does **not** clear `root`: it walks the node tree in lockstep with
+the existing server DOM, adopting nodes in place. Error channel is `E |
+HydrateError` (adds `HydrationMismatchError` on top of everything `mount` can fail
+with).
+
+Preserves the compile-time `AssertNoServerOnly` → `ServerOnlyLeak` guard. A
+server-only requirement left in `node`'s context degrades the return type to the
+`ServerOnlyLeak` sentinel (compile error at the call site), not a runtime failure.
+Hydration mechanics (the readiness barrier, stream-id seeding) are otherwise
+unchanged from `mount`.
+
+### `WeftApp.errors`
+
+```ts
+const errors: <R, E>(app: WeftApp<R, E>) => Stream.Stream<UnhandledError>;
+```
+
+The app's unhandled-error stream. While at least one subscriber exists, the default
+`Effect.logError` fallback is suppressed and every `UnhandledError` is delivered to
+all subscribers. With zero subscribers, each unhandled error runs the default log
+(annotated with `weft.region`) instead.
+
+There is no replay: a subscriber sees only errors published after it subscribed.
+Multiple concurrent subscribers each receive every subsequent error. When the last
+subscriber unsubscribes, the default log resumes.
+
+### `WeftApp.dispose`
+
+```ts
+const dispose: <R, E>(app: WeftApp<R, E>) => Effect.Effect<void>;
+```
+
+Disposes the app, in order:
+
+- closes every root scope (in mount order),
+- releases the runtime's layers (`runtime.disposeEffect`),
+- shuts the error hub down.
+
+Idempotent: teardown effects run once. Subsequent `mount` / `hydrate` calls fail.
+
+### `WeftApp<R, E>` (`WeftAppType`)
 
 ```ts
-mount(node: Renderable, target: Element): Effect<MountHandle, RenderError, R>
+interface WeftApp<in R = never, out E = never> {
+  readonly [TypeId]: typeof TypeId;
+  readonly runtime: ManagedRuntime.ManagedRuntime<R, E>;
+}
 ```
 
-Renders a Weft `node` into `target` for a fresh (non-SSR) page, building real DOM
-and starting every reactive stream. Returns a `MountHandle` whose scope owns the
-mounted tree; closing it tears the tree down. Use `mount` for purely client-rendered
-apps; use `hydrate` when the markup already exists from SSR.
+Re-exported from the barrel as `WeftAppType`. `runtime` is the app's
+`ManagedRuntime`, for running app-level effects against the shared layer outside
+any root. Examples: `app.runtime.runFork(trackPageviews)` (see
+`website/src/entry-client.ts`) and `app.runtime.runPromise(Router.push("/about"))`.
 
-### `hydrate`
+### `RootHandle`
 
 ```ts
-hydrate(node: Renderable, target: Element): Effect<MountHandle, HydrationMismatchError | RenderError, R>
+interface RootHandle {
+  readonly element: HTMLElement;
+  unmount(): Effect.Effect<void>;
+}
 ```
 
-Adopts server-rendered DOM **in place** inside `target` and resumes reactivity
-without re-creating elements. The `node` must produce a tree structurally identical
-to what the server rendered; a divergence fails with `HydrationMismatchError`. This
-is the flash-free path: no second render, the existing nodes simply become live.
+Returned by `mount` / `hydrate`. `element` is the DOM element the root was mounted
+into. `unmount()` closes **this root's scope only**: it interrupts its stream
+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.
 
-### `mountScoped`
+### `UnhandledError`
 
 ```ts
-mountScoped(app: Renderable, root: HTMLElement): Effect<MountHandle, UnsupportedNodeTypeError | StreamSubscriptionError | RenderError, Scope.Scope>
+interface UnhandledError {
+  readonly cause: Cause.Cause<unknown>;
+  readonly region: string;
+  readonly root: RootHandle;
+}
 ```
 
-Scope-aware `mount`: identical behavior, but requires an ambient `Scope.Scope` in
-`R` and registers `unmount` as a finalizer on it, so the mount lives until that
-scope closes rather than only until the mount effect resolves. Provide any scoped
-layer **outside** a long-lived scoped region so it outlives initial render — see
-[Provide Services](https://weftui.dev/docs/how-to/provide-services) for the composition and
-[Layer lifetime at the mount](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount)
-for why.
+An error that escaped every user-level handler and reached the app's
+unhandled-error hub, published on `WeftApp.errors(app)`. `region` identifies where
+in the render tree the error escaped. Sources (one entry per failing occurrence):
+
+- a rendered stream subscription failing or dying with **no enclosing `Boundary`**
+  (region e.g. `"attribute:class"`, `"child:stream-3"`),
+- an error escaping the **outermost** `Boundary` recovery (region
+  `"boundary:outermost"`),
+- an event-handler effect **failing or dying** (region `"event:onClick"`), reported
+  in development and production alike (there is no `NODE_ENV`-gated swallow).
+
+Interrupt-only causes are never published. Errors handled by a nested `Boundary`
+never reach the hub.
 
-### `hydrateScoped`
+### `MountError`
 
 ```ts
-hydrateScoped(app: Renderable, root: HTMLElement): Effect<MountHandle, UnsupportedNodeTypeError | StreamSubscriptionError | RenderError | HydrationMismatchError, Scope.Scope>
+type MountError = UnsupportedNodeTypeError | StreamSubscriptionError | RenderError;
 ```
 
-Scope-aware `hydrate` — same relationship as `mountScoped` to `mount`, with
-`hydrate`'s error union (`HydrationMismatchError` added) and the same client-only
-compile-time guard: a server-only requirement left in `app`'s `R` degrades the
-return type to `ServerOnlyLeak` via `AssertNoServerOnly`.
+Errors `mount` can fail with, beyond the app layer's own error channel `E`.
 
-### `MountHandle`
+### `HydrateError`
 
-The handle returned by `mount`, `hydrate`, `mountScoped`, and `hydrateScoped`. Its
-`unmount()` interrupts every subscription and event handler and disposes the
-mount's `ManagedRuntime`; it does **not** remove the mounted DOM nodes from `root`.
-`unmount` is idempotent — safe to call more than once, including once
-automatically and once explicitly.
+```ts
+type HydrateError = MountError | HydrationMismatchError;
+```
+
+Everything `MountError` covers, plus `HydrationMismatchError` when the server DOM
+and the node tree diverge.
+
+### `TypeId`
 
-The runtime backing the handle lives until `unmount` runs, not until the
-`mount`/`hydrate` effect resolves — that effect completes right after initial
-render, while streams and handlers keep running in the background. If `mount` or
-`hydrate` runs inside a region that supplies an ambient `Scope.Scope` (e.g. under
-`Effect.scoped`), `unmount` is auto-registered on that scope as a finalizer, so the
-mount tears down when the scope closes; with no ambient scope, behavior is
-unchanged and `unmount` must be called explicitly. `mountScoped`/`hydrateScoped`
-register the same finalizer explicitly, so the typed variant does not silently
-depend on this auto-registration.
+```ts
+const TypeId: unique symbol; // Symbol.for("@weftui/dom/WeftApp")
+```
+
+The unique brand for `WeftApp` values. Internal identity marker; rarely referenced
+directly.
 
 ## `@weftui/dom/server`
 
@@ -115,28 +252,228 @@ hydration markers. These back streaming SSR and suspense.
 renderToHydratableShell(node: Renderable): Effect<HydratableShell, Error, R>
 ```
 
-Produces a `HydratableShell` — the document scaffold around the app — for servers
+Produces a `HydratableShell` (the document scaffold around the app) for servers
 that assemble the response shell separately from the streamed body.
 
 ### Suspense failure handling
 
-`SuspenseFailureHandlerTag` is the service tag for a `SuspenseFailureHandler`, which
-maps a failed suspense boundary to a `SuspenseFailureSubstitute` (fallback markup)
-during streaming SSR.
+`SuspenseFailureHandlerTag` is the service tag for a `SuspenseFailureHandler`. The
+handler maps a failed suspense boundary to a `SuspenseFailureSubstitute` (fallback
+markup) during streaming SSR.
 
 ## Package root (`@weftui/dom`)
 
 Re-exports the renderer error types:
 
-- `HydrationMismatchError` — the client tree did not match the server markup.
-- `UnsupportedNodeTypeError` — a node type the renderer cannot handle was encountered.
-- `RenderError` — a general rendering failure.
-- `StreamSubscriptionError` — a reactive stream backing the tree failed to subscribe.
+- `HydrationMismatchError`: the client tree did not match the server markup.
+- `UnsupportedNodeTypeError`: a node type the renderer cannot handle was encountered.
+- `RenderError`: a general rendering failure.
+- `StreamSubscriptionError`: a reactive stream backing the tree failed to subscribe.
+
+Also re-exports the `Props` namespace, below.
+
+## `Props`
+
+`export * as Props from "@weftui/dom"`. Two functions for reconciling DOM prop
+bags: `merge` combines multiple bags into one, `cx` builds a class string.
+Both are pure and synchronous; neither subscribes anything. A reactive result
+is a `Stream` description, subscribed later by the renderer in the element's
+scope.
+
+### `Props.merge`
+
+```ts
+function merge<const Bags extends ReadonlyArray<DomProps>>(...bags: Bags): Merged<Bags>;
+```
+
+`DomProps` is `object`. `merge` is variadic and left-to-right: `merge()` is
+`{}`, `merge(a)` is observationally `a`, and `merge(a, b, c)` folds pairwise
+(`merge(merge(a, b), c)`). `{}` is the identity on either side.
+
+The fold is associative per key, with one exception: `style` is not
+associative when a non-object form (a string, or a whole-object stream) takes
+part. See the `style` rule below.
+
+Keys present on only one side pass through unchanged, by reference. For a key
+present on both sides, the merged value depends on the key:
+
+| Key                                                                         | Rule                                                         | Result                                                             |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `on*` (event handler, per the renderer's `on` + lowercase-third-char check) | chained: both handler bodies run, left then right            | new handler function                                               |
+| `class`                                                                     | concatenated                                                 | `string` if both sides are static, else a derived `Stream<string>` |
+| `style`                                                                     | object sides merge per property; any other form is last-wins | plain object, or the right side as-is                              |
+| `ref`                                                                       | fanned out                                                   | readonly array of `SubscriptionRef`s                               |
+| anything else                                                               | last-wins                                                    | the right side's value, as-is                                      |
+
+**Handlers.** Both handler bodies run synchronously when the merged handler
+is invoked, left then right, before either side's returned `Effect` is
+awaited. This is what makes `event.preventDefault()` written in either body
+observable to the other: two separate DOM listeners would both run during
+dispatch, so neither can wait on the other's `Effect` to decide whether the
+default action should still happen.
+
+Only the returned Effects are sequenced: left first, then right. Both always
+run regardless of whether the other fails. A plain void-returning handler is
+lifted to `Effect.void` (or a died `Effect` if it throws). The merged
+handler's error channel is the union `E_left | E_right`; if both sides fail,
+both causes are aggregated into one, not deduplicated (two equal-looking
+failures are still two failures).
+
+`null` or `undefined` on either side means "not provided": the other side
+passes through unchanged, whatever shape it has, including a reactive
+`Stream`/`Effect`-of-handler value (not chained, since only two plain
+functions are chained; see [Accepted limitations](#accepted-limitations)
+below). `false` on the **right** means "explicitly disabled" and wins, since
+the renderer reads `false` as "no handler." That is how a caller switches a
+behavior's handler off. A `false` on the left simply loses to the right side,
+like any other last-wins value.
+This is the only place `merge` treats a nullish value specially. The generic
+rule below explains why every other key does not.
+
+**`class`.** Two static strings concatenate with a single space, no dedupe:
+`merge({ class: "a" }, { class: "b" }).class === "a b"`. If either side is
+reactive (`Stream`, `Effect`, or `Subscribable`), the result is a derived
+`Stream<string>` combining the latest value from each side, space-joined. A
+static side contributes immediately; the first emission waits only on the
+reactive side(s) (await-first). A reactive side that ends without ever
+emitting fails the derived stream with `NoPropValue`, which joins the merged
+`E` channel. When both sides contribute nothing (absent, `undefined`, or
+empty), the result is `""`, matching `cx` and clsx: it is not normalized to
+`undefined`.
+
+The `class` rule for two present sides is exactly `cx(left, right)`; `cx` is
+that same engine exposed directly (see below).
+
+**`style`.** Two per-property objects (`style: { color: "red" }`) merge by
+key union, right side winning per key; each surviving value, static or
+`Source`, passes through by reference. Any other shape on either side (a
+`string`, or a whole-object stream) is last-wins: the right side replaces the
+left entirely. This is the one case where merge is not associative, since
+last-wins discards a side instead of combining it, so grouping the fold
+differently changes the result. Upgrading whole-object-stream style merging
+to a real per-key merge is additive future work, not a breaking change.
+
+**`ref`.** Both sides concatenate into one readonly array, flattening any
+side that is already an array, so associativity holds:
+`merge({ ref: [a, b] }, { ref: c }).ref` is `[a, b, c]`. Nullish sides are
+dropped, so an optional ref forwarded as `undefined` never enters the array.
+Each ref keeps the normal per-ref contract: set once to `Some(element)` when
+the element mounts. The renderer's `ref` prop accepts a `SubscriptionRef` or
+a `readonly SubscriptionRef[]` directly, so `h.div({ ref: [a, b] })` fans out
+without `merge` too.
+
+**Everything else (generic keys).** Plain last-wins, matching object spread:
+the right side's value wins as-is, including an explicit `undefined`. There
+is no nullish guard on this arm (unlike the handler rule): a guard was tried
+and reverted, because it made the runtime return the left value while the
+type still said the right value was present, silently dropping the left
+side's `E`/`R` channels from the merged type.
+
+#### Type-layer contract
+
+`Merged<Bags>`'s **value** types stay coarse (Source-shaped, not narrowed to
+exactly what the runtime returns); its `E`/`R` **channels** stay precise,
+because `PropsE`/`PropsR` (the machinery that feeds a merged bag's channels
+into `h.*`'s resulting `Node<E, R>`) match `P[K]` against an exact `Stream`
+or function shape. A looser value type would fail that match and silently
+drop the channel.
+
+Consequences worth knowing:
+
+- A shared key's merged value type is **required**, even when the key is
+  optional on both input bags and absent from one side at runtime. Typing it
+  optional would fail the `PropsE`/`PropsR` match and drop the channel for
+  the common case: a behavior primitive's bag with optional props.
+- A handler cell types as callable whenever _either_ side can carry a
+  handler, even if that side is `null` at runtime. Narrowing this would
+  require unioning the nullish outcome back in, which fails the same match.
+- The `ref`-array cell types as `SubscriptionRef<Option<any>>`, not narrowed
+  to a specific element type. `SubscriptionRef` is invariant in its value
+  type, so a precise union would reject the headline case: fanning a
+  behavior's `SubscriptionRef<Option<HTMLElement>>` out alongside a caller's
+  `SubscriptionRef<Option<HTMLInputElement>>`. A mistyped ref inside a
+  fan-out array is therefore not caught at compile time; the set-once
+  contract keeps reads sound regardless.
+- A bag typed with core's `HTMLAttributes`/`DOMAttributes` gets `unknown`
+  handler channels, because those types declare handlers as returning
+  `void | Effect<void, unknown, unknown>`. A behavior primitive that
+  declares precise handler signatures keeps precise channels through the
+  merge.
+
+#### Accepted limitations
+
+- Reactive handler _values_ (a `Stream`/`Effect` of a handler function, the
+  form core's `EventHandler` union allows) are not chained: any non-function
+  handler side falls back to last-wins, consistent with the whole-object
+  style rule. Their `E`/`R` channels are still collected in the merged type.
+- An inline handler written directly inside a `merge` call gets no
+  contextual type for its event parameter, because `DomProps` is `object`
+  and `merge` cannot know which element it will end up on. Write
+  `onclick: (ev: MouseEvent) => …` with an explicit annotation, or give the
+  bag its own type.
+
+### `Props.cx`
+
+```ts
+function cx<const Inputs extends ReadonlyArray<CxInput>>(...inputs: Inputs): CxResult<Inputs>;
+
+type CxInput =
+  | string
+  | false
+  | null
+  | undefined
+  | Stream.Stream<string, any, any>
+  | Effect.Effect<string, any, any>
+  | Subscribable.Subscribable<string, any, any>
+  | CxRecord
+  | ReadonlyArray<CxInput>;
+
+interface CxRecord {
+  readonly [className: string]:
+    | boolean
+    | Stream.Stream<boolean, any, any>
+    | Effect.Effect<boolean, any, any>
+    | Subscribable.Subscribable<boolean, any, any>;
+}
+```
+
+A reactive class-name builder, clsx-compatible plus reactive conditions. Each
+input is one of:
+
+- a **string**: kept as a literal class name segment;
+- a **falsy value** (`false`, `null`, `undefined`, `""`): skipped;
+- a **nested array** of `CxInput`: flattened recursively;
+- a **record** (`{ className: condition }`): each key is included when its
+  condition is truthy;
+- a **reactive value** in place of a string (a `Source<string>`), or as a
+  record condition (a `Source<boolean>`).
+
+`cx()` is `""`. All-static inputs join into a plain `string`, space-separated,
+no dedupe, no empty segments. Any reactive input (a reactive value, or a
+reactive condition in a record) derives a `Stream<string>` that recomputes
+the full class string on any emission, combining the latest value from every
+reactive input.
+
+A reactive value that resolves to `""` contributes nothing to that emission.
+A reactive input that ends without ever emitting fails the stream with
+`NoPropValue`, which joins the result's `E` channel along with every
+reactive input's own `E`/`R`.
+
+Only a plain record (an object literal, not a class instance, `Date`, or
+boxed value like `SubscriptionRef`) is read as a condition map; anything else
+is ignored rather than risking a foreign field name leaking in as a class
+name.
+
+`merge`'s `class` rule for two present sides is observationally
+`cx(left, right)`: one engine behind both names.
 
 ## See also
 
-- [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server) — a narrative walkthrough of the server/client split
-- [Provide Services](https://weftui.dev/docs/how-to/provide-services) — recipes for value layers, `mountScoped`, and `ManagedRuntime`
-- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — hydrate-in-place and why there is no virtual DOM
-- [Services and Context](https://weftui.dev/docs/explanation/services-and-context#layer-lifetime-at-the-mount) — why scoped layers need the mount to outlive initial render
+- [Compose Behavior and Markup](https://weftui.dev/docs/how-to/compose-behavior-and-markup): using `Props.merge`/`Props.cx` to combine a behavior's props with the caller's
+- [Style Reactively](https://weftui.dev/docs/how-to/style-reactively): the `style` prop's reactive forms
+- [Use Element Refs](https://weftui.dev/docs/how-to/use-element-refs): the `ref` prop and its fan-out form
+- [Render on the Server](https://weftui.dev/docs/how-to/render-on-the-server): a narrative walkthrough of the server/client split
+- [Provide Services](https://weftui.dev/docs/how-to/provide-services): recipes for app layers, scoped layers, and binding an app's lifetime to an external scope
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model): hydrate-in-place and why there is no virtual DOM
+- [Services and Context](https://weftui.dev/docs/explanation/services-and-context): how services flow from the app layer to every root
 - [`@weftui/core` reference](https://weftui.dev/docs/reference/core) · [`@weftui/router` reference](https://weftui.dev/docs/reference/router)