@weftui/router 0.26.1 → 0.26.3

package/docs/explanation/services-and-context.md

@@ -0,0 +1,91 @@
+---
+title: Services and Context
+order: 5
+section: explanation
+description: How Effect services reach components — the requirement channel, discharging R at the mount, the router's render-time context seam, and ServerTag server-only brands.
+---
+
+# Services and Context
+
+Weft has no separate dependency-injection system. It uses Effect's — a component that needs a service reads it with `yield* Service`, and because [a node is an Effect](https://weftui.dev/docs/explanation/rendering-model), that requirement rides the node's `R` channel up the tree to a single point where you provide it. This page explains how a service travels from where you provide it to where a component reads it, and the two seams that make that work across the server/client boundary.
+
+## R accumulates, then discharges once
+
+When a component does `yield* ThemeService`, `ThemeService` enters that node's requirement channel. It accumulates through every parent — a boundary, a layout, the app node — until the whole tree's `R` is the union of everything any component needs. You satisfy it in **one** place, at the edge:
+
+```typescript
+import { Effect } from "effect";
+import { mount } from "@weftui/dom/client";
+
+const handle = pipe(
+  mount(App(), document.getElementById("root")!),
+  Effect.provide(ThemeServiceLive),
+);
+```
+
+Provide too little and it is a compile error at the mount call — the type of `App()` names exactly which service is missing. This is the same discipline as any Effect program: `R` is a promise the type checker holds you to, discharged at the program's boundary, not sprinkled through the tree.
+
+Services flow **down** from that provide point to every reader, including across reactive boundaries: a stream woven into a prop carries its own `R`, and a handler that reads a service resolves it from the same context. There is no prop-drilling and no context-provider component — the requirement channel _is_ the wiring.
+
+## Layer lifetime at the mount
+
+The `ThemeServiceLive` example above works because `mount`'s effect and the service's lifetime coincide by accident: `ThemeServiceLive` is a plain value layer with nothing to release, so it makes no difference whether it is "alive" for one tick or the whole session. That accident stops holding the moment the layer is **scoped** — built with `Layer.scoped`, backed by an `acquireRelease` — because `mount`'s effect resolves right after the tree's **initial render**, not when the app stops running. Streams, event handlers, and forked work all keep running on the mount's runtime long after that Effect has settled.
+
+`Effect.provide(scopedLayer)` is `acquireUseRelease` sugar: acquire, run the wrapped effect, then release **when that effect completes**. Wrap it directly around `mount`, and the release runs at mount-resolve — while the mounted tree is still reading from the now-disposed service:
+
+```typescript
+// ❌ the layer's finalizers run the instant runPromise settles, while the
+// mounted tree keeps running — every subscription now reads a disposed service
+Effect.runPromise(mount(App(), root).pipe(Effect.provide(SomeScopedLayer)));
+```
+
+This is exactly what happened with effect-atom's `Registry.layer` in the [`effect-atom` example](https://github.com/stefvw93/weft/tree/main/examples/effect-atom) (issue #122): every atom-driven region rendered empty, with no error, because the registry the streams read from had already been disposed.
+
+The fix is to give the scoped layer a lifetime that matches the app, not the initial render: provide it **outside** a scoped region that stays open for as long as the app should run, and mount inside that region with `mountScoped` (which ties `unmount` to the region's scope instead of to the resolution of the mount effect). An `Effect.never` (or `Deferred.await` on a shutdown signal) keeps the region — and therefore the layer — alive until something explicitly closes it. See [Provide Services](https://weftui.dev/docs/how-to/provide-services) for the recipe, including the `ManagedRuntime` alternative when a scoped region isn't a good fit.
+
+## The router's render-time context seam
+
+A plain `mount`/`hydrate` discharges `R` at the call site. But under `@weftui/router`, the tree does not render in the context of the effect that called `render` — each request dispatches through platform's HTTP layer in its own managed context, and the reactive outlet drains in the top render context, not in any intermediate node's. Providing a service _ambiently_ around the render would be lost before it reached a route component.
+
+So the router exposes an explicit **`context` seam** — a `Layer` threaded to the document shell and every route, layout, and leaf:
+
+```typescript
+class Greeting extends Context.Tag("Greeting")<Greeting, { text: string }>() {}
+
+// server entry
+RouterServer.render(App, { document, url, context: Layer.succeed(Greeting, { text: "hi" }) });
+
+// client entry — same seam, so the hydrated tree reads the same services
+RouterLive(App, { context: DocsLive });
+```
+
+The seam is **symmetric** (same shape on both sides) and **type-tracked**: the def's aggregate residual `R` is discharged here, so a missing provide is a compile error rather than a runtime 500. The residual is `AppServices<R>` — the def's `R` minus what the router itself threads (`Router`, `Router.Outlet`, `AppRpcClientTag`). An app with no app-services needs no `context`; a loosely-typed `RouterDef<any, any>` may omit it. This is how the website provides its `Docs` service to every page — see [Add Routing](https://weftui.dev/docs/how-to/add-routing).
+
+## Server-only services: `ServerTag`
+
+Some services must _never_ run in the browser — a database handle, a private credential, an rpc handler's backing store. Declare those with [`ServerTag`](https://weftui.dev/docs/reference/core#servertag) instead of `Context.Tag`. It behaves exactly like `Context.Tag`, but its identifier carries a **server-only brand**.
+
+The brand's job is to turn a leak into a **compile error at the `hydrate` call site**. A `Boundary.rpc` handler legitimately reads server-only services on the server, but they must not survive into client code: since `render` only ever touches the _decoded result_ (never the service), a correctly-written boundary keeps its output `R` free of the brand. If a branded tag ever leaks into `render` and reaches the client requirement channel, `hydrate`'s `AssertNoServerOnly` resolves `R` to a compile-error sentinel — you learn at build time, not from a runtime defect.
+
+```typescript
+import { ServerTag } from "@weftui/core";
+
+// Only ever provided on the server; a leak into client code fails to compile.
+class Db extends ServerTag("Db")<Db, { query: (sql: string) => Effect.Effect<Row[]> }>() {}
+```
+
+## The whole picture
+
+- A component reads a service with `yield* Service`; the requirement enters `R`.
+- `R` accumulates through the tree and is discharged **once** — at `mount`/`hydrate`, or through the router's `context` seam.
+- The same services flow to the same components on the server and the client, because it is the same tree.
+- `ServerTag` brands the services that must stay server-side, enforced at the `hydrate` boundary.
+
+## See also
+
+- [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why services flow through the tree at all
+- [The Combinator API](https://weftui.dev/docs/explanation/combinator-api) — how `R` accumulates from children and reactive props
+- [Provide Services](https://weftui.dev/docs/how-to/provide-services) — recipes for value layers, scoped layers with `mountScoped`, and `ManagedRuntime`
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — providing app services through the router `context` seam
+- [Load Data with RPC](https://weftui.dev/docs/how-to/load-data-with-rpc) — where `ServerTag` and the rpc handler Layer meet
+- [`ServerTag` API reference](https://weftui.dev/docs/reference/core#servertag)

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

@@ -0,0 +1,306 @@
+---
+title: Routing
+order: 4
+section: how-to
+description: "@weftui/router — universal nested routing, Router.route / Router.layout / Router.router, type-safe href, layouts, and programmatic navigation."
+---
+
+# Routing
+
+`@weftui/router` is a universal (server + client) nested router for Weft. It maps a URL to a rendered `Node` tree on both sides:
+
+- **Server** — matches an incoming request path, renders the matched nested page to hydratable HTML, and responds with `text/html` (HTTP 404 for not-found).
+- **Client** — matches `window.location`, swaps pages reactively via the History API, and keeps unchanged ancestor layouts mounted across navigations.
+
+The package mirrors `@weftui/dom`: a shared (universal) root, a `./client` entry, and a `./server` entry.
+
+```bash
+npm install @weftui/router
+```
+
+## The mental model
+
+A route's **component is its handler** — a page is a component that renders, and its `component` slot is invoked at render time on whichever side the request arrives. Server-resolved data stays with [`Boundary.rpc`](https://weftui.dev/docs/how-to/load-data-with-rpc); client-side async stays with `Boundary.suspend`.
+
+You author an **explicit nested route tree** with three namespaced combinators — mirroring the `h.div` / `Component.gen` / `Boundary.catchTag` surface — and seal it once:
+
+| Combinator                                            | Builds                                                            |
+| ----------------------------------------------------- | ----------------------------------------------------------------- |
+| `Router.route(segment, { path?, query?, component })` | A leaf page.                                                      |
+| `Router.layout({ component }, children)`              | A layout that wraps an outlet (purely UI nesting — owns no path). |
+| `Router.router(root, { notFound })`                   | Seals the tree into a `RouterDef`.                                |
+
+The tree is the source of truth. The same sealed `RouterDef` drives both server and client.
+
+## Authoring routes
+
+Every `component` slot is a **`ComponentSlot`** — a callable producing a `Node`, passed **uncalled**. Use [`Component.make` / `Component.gen`](https://weftui.dev/docs/how-to/author-components) (or a plain `() => Node` thunk). The router invokes it at render time, which is what lets `href(…)` resolve after the tree is compiled.
+
+```typescript
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { Schema } from "effect";
+
+const About = Router.route("about", {
+  component: Component.make(() => h.h1("About")),
+});
+
+const User = Router.route("users/:id", {
+  path: { id: Schema.NumberFromString },
+  component: Component.gen(function* () {
+    const { id } = yield* Router.params({ id: Schema.NumberFromString });
+    return yield* h.div(`User ${id}`);
+  }),
+});
+```
+
+- **`segment`** is relative to the parent and may contain `:name` path-param placeholders (e.g. `"users/:id"`). A leading/trailing `/` is tolerated. Each leaf carries its full relative path (e.g. `"users/:id/settings"`).
+- **`path` / `query`** are `Schema.Struct.Fields` (a record of `name → Schema`), declared **only on routes**. The compiler covers every `:name` placeholder in `pathSchema`, defaulting to `Schema.String` when a placeholder has no declared field. Query fields are optional by default.
+
+> Authoring components with `Component.make` / `Component.gen` keeps every slot fully typed: the router never sees a `Node<any, any>`, and each component's `E`/`R` channels aggregate up through `Router.layout` / `Router.router` into the sealed `RouterDef`.
+
+## Reading the match: handler-arg props vs. injection
+
+A leaf page reads the current match's decoded `path` / `query` in **either** of two forms.
+
+### Handler-arg props (leaf pages)
+
+The router passes the decoded `{ path, query }` straight into a leaf `component` as props (typed `RouteHandlerProps<Path, Query>`, inferred from the route's `path` / `query` fields). No `Router` access, no validation step — just read the props:
+
+```typescript
+const idParam = { id: Schema.NumberFromString };
+const sortQuery = { sort: Schema.optional(Schema.String) };
+
+Router.route("users/:id/posts", {
+  path: idParam,
+  query: sortQuery,
+  // `path.id` is already a number; `query.sort` is `string | undefined`.
+  component: ({ path, query }) =>
+    h.section([h.h2(`Posts for user ${path.id}`), h.p(`sort: ${query.sort ?? "none"}`)]),
+});
+```
+
+This is the most direct form for a leaf. A plain zero-arg thunk works too — it just ignores the props.
+
+### Dependency injection (layouts and deep nodes)
+
+A **layout** sits above the leaf and so can't take handler args; it reads the match by **dependency injection** instead. `Router.params(fields)` / `Router.query(fields)` are readable from **any** component:
+
+```typescript
+// A /users/:id layout (above the leaf) reads `:id` by injection.
+const UserShell = Component.gen(function* () {
+  const { id } = yield* Router.params(idParam);
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ class: "user" }, [h.h1(`User ${id}`), outlet]);
+});
+```
+
+`Router.params(fields)` / `Router.query(fields)` read the live match and pick the requested `fields` keys (already decoded by the matcher, so no re-validation). They return the typed values, or fail with a tagged [`RouterParamsError`](#errors) (carrying `source: "path" | "query"` and the requested `keys`) when no route matches. That error bubbles into the app node's aggregate `E`, so a user may recover it with `Boundary.catchTag("RouterParamsError", …)`.
+
+> **Reactive accessors.** `Router.paramsStream(fields)` / `Router.queryStream(fields)` are the reactive counterparts — each resolves a `Subscribable` derived from `currentMatch.changes`, so a component can render `[(yield* Router.queryStream(sortQuery)).changes]` and update **in place** even when the same leaf stays mounted (the query-only case `Router.query` would miss). See [Programmatic navigation](#programmatic-navigation).
+
+## Layouts and the outlet
+
+A **layout** wraps the next level down — the **outlet** — which is also delivered by injection. A layout reads it with `yield* Router.Outlet` and places it like any `h`-style child:
+
+```typescript
+const UserShell = Component.gen(function* () {
+  const { id } = yield* Router.params(idParam);
+  const outlet = yield* Router.Outlet;
+  return yield* h.div({ class: "user" }, [h.h1(`User ${id}`), outlet]);
+});
+
+Router.layout({ component: UserShell }, [settingsRoute, postsRoute]);
+```
+
+`Router.Outlet` is typed **opaque** (`Node<never, never>`), so splicing it adds nothing to the layout's own channels — the subtree's real `E`/`R` are aggregated structurally by `Router.layout`. The router discharges the `Outlet` requirement at render time, so it never appears in a layout's (or the sealed app's) aggregate requirement channel.
+
+A layout owns **no `segment` or `path`** — all path structure lives on routes. A layout that needs a param simply reads it via `Router.params`.
+
+### Layout persistence
+
+Each nesting level renders as a reactive stream child keyed by `(pattern + the param values that level depends on)` and `dedupe`d. An unchanged ancestor layout therefore **stays mounted** across a navigation that only changes a deeper level: its DOM identity and any local state (a `SubscriptionRef`, a scroll position) survive while only the inner outlet swaps.
+
+## Sealing the tree
+
+`Router.router(root, { notFound })` compiles the tree eagerly (stamping leaf references so `href` works) and captures the app-level not-found page:
+
+```typescript
+export const App = Router.router(
+  Router.layout({ component: Shell }, [
+    homeRoute,
+    Router.layout({ component: UserShell }, [settingsRoute, postsRoute]),
+  ]),
+  { notFound: () => h.section({ id: "page" }, [h.h2("404 — page not found")]) },
+);
+```
+
+`App` is a `RouterDef` whose phantom `E`/`R` carry the aggregate channels of the whole tree (plus the not-found page) — keep `app.ts` side-effect-free (no `mount`/`hydrate`) so both entries can import it.
+
+## Type-safe links with `href`
+
+`href(leafRef, args)` builds a URL from a leaf route reference (the value returned by `Router.route`). Path params are **required** in the argument type and query is optional when every query field is optional:
+
+```typescript
+import { href } from "@weftui/router";
+
+const Home = Component.make(() =>
+  h.nav([
+    h.a({ href: href(settingsRoute, { path: { id: 1 } }) }, "User 1 settings"),
+    h.a({ href: href(postsRoute, { path: { id: 2 }, query: { sort: "new" } }) }, "User 2 posts"),
+  ]),
+);
+```
+
+Path params encode into the pattern (`/users/:id` + `{ id: 42 }` ⇒ `/users/42`); query values encode through the query schema into a key-sorted search string. `href` round-trips with the matcher. The leaf must belong to a tree sealed with `Router.router()` (which is why deferring the `component` body via `Component.make` matters — `href` runs at render time, after compile).
+
+## Not-found
+
+`notFound(path?)` short-circuits the current render with a `RouterNotFound` failure. Callable from any page or layout; the nearest enclosing not-found boundary renders the configured `notFound` page in its place, and the server responds with HTTP 404:
+
+```typescript
+import { notFound, Router } from "@weftui/router";
+
+Router.route("users/:id", {
+  path: idParam,
+  component: Component.gen(function* () {
+    const { id } = yield* Router.params(idParam);
+    if (id < 0) return yield* notFound();
+    return yield* h.div(`User ${id}`);
+  }),
+});
+```
+
+`RouterNotFound` is exported, so a `Boundary.catchTag("RouterNotFound", …)` placed inside a subtree overrides the app-level fallback for that subtree (the router's internal boundary is outermost, so a nearer user boundary wins).
+
+## Client setup
+
+On the client, provide the `Router` via `RouterLive(def)` and render `RouterApp(def)`. `RouterLive` is a **scoped layer** — it owns the `popstate` listener and the same-origin link-click interceptor — so it must outlive the mount. Provide it through a long-lived `ManagedRuntime` rather than `Effect.provide` at the node level:
+
+```typescript
+// entry-client.ts
+import { hydrate } from "@weftui/dom/client";
+import { RouterApp, RouterLive } from "@weftui/router/client";
+import { ManagedRuntime } from "effect";
+import { App } from "./app";
+
+const root = document.getElementById("root")!;
+const runtime = ManagedRuntime.make(RouterLive(App));
+void runtime.runPromise(hydrate(RouterApp(App), root));
+```
+
+For a client-only app (no SSR), swap `hydrate` for `mount` — everything else is identical.
+
+### Link interception
+
+A plain `h.a({ href })` to a same-origin, route-matching URL performs SPA navigation when clicked — no full page load. The interceptor leaves the browser's native behaviour untouched for modified clicks (ctrl/meta/shift/alt or non-left button), `target=_blank`, `download`, external origins, same-document (hash-only) navigations, and hrefs that don't resolve to a route. You don't wire anything up: `RouterLive` installs the delegated listener for the layer's lifetime and removes it on teardown.
+
+## Programmatic navigation
+
+For navigation that isn't a link click, `@weftui/router/client` exposes typed helpers. They run as `Effect`s within the `RouterLive` layer (except `back` / `forward`, which only touch `window.history`):
+
+```typescript
+import {
+  back,
+  forward,
+  navigate,
+  patchQuery,
+  push,
+  replace,
+  setQuery,
+} from "@weftui/router/client";
+
+// Typed: build the URL from a leaf ref + decoded args (same rules as `href`).
+yield * navigate(postsRoute, { path: { id: 42 }, query: { sort: "new" } });
+yield * navigate(settingsRoute, { path: { id: 42 } }, { replace: true });
+
+// Raw path + search string.
+yield * push("/users/1/posts?sort=new");
+yield * replace("/users/1/settings");
+
+// History stepping (popstate resyncs the router).
+yield * back();
+yield * forward();
+
+// Change only the current route's query, re-encoded through its query schema.
+// The path is kept, so the leaf stays mounted and `queryStream` readers update.
+yield * setQuery({ sort: "old" }); // replaces the query
+yield * patchQuery({ sort: "old" }); // merges into the current query
+```
+
+- **`navigate(ref, args)`** builds the URL via [`href`](#type-safe-links-with-href) (so it round-trips with the matcher) and pushes — or, with `{ replace: true }`, replaces — the History entry. `args` follows the same requiredness rules as `href`.
+- **`setQuery` / `patchQuery`** keep the path, so the active leaf is never remounted — pair them with `Router.queryStream` for in-place reactive updates. They are a no-op when no route is matched.
+
+### Scroll position on navigation
+
+A client navigation whose **path** changes resets the window scroll to the top at commit — matching what a full page load would do, which a raw History `pushState`/`replaceState` otherwise doesn't. This applies uniformly to `Router.navigate`, clicking a link the [interceptor](#link-interception) handles, and the `push` / `replace` helpers.
+
+- **Query-only navigations preserve scroll.** `setQuery` / `patchQuery` (and any navigation that keeps the same path) don't reset — the leaf stays mounted, so there's nothing to scroll away from.
+- **Back/forward is untouched.** The router never resets scroll on `popstate`; the browser's native `history.scrollRestoration: "auto"` restores the offset the entry had when the user left it.
+- **Hash navigation (`#section`) is unaffected** — it's browser-native, and the link interceptor already lets same-document/hash-only clicks fall through.
+
+There's no opt-out; the behavior is hardwired.
+
+## Server setup
+
+On the server, `RouterServer` matches a request URL, builds a fixed-match `Router`, renders `RouterApp` to hydratable HTML inside a **document shell**, and reports a status (404 when no route matches or a page raises `RouterNotFound`).
+
+The document shell is itself a `ComponentSlot` that splices the app via `yield* Router.Outlet` — exactly like a layout receives its outlet:
+
+```typescript
+// entry-server.ts
+import { Component, h } from "@weftui/core";
+import { Router } from "@weftui/router";
+import { RouterServer } from "@weftui/router/server";
+import { Effect } from "effect";
+import { App } from "./app";
+
+const documentShell = Component.gen(function* () {
+  const app = yield* Router.Outlet;
+  return yield* h.html({ lang: "en" }, [
+    h.head([h.meta({ charset: "utf-8" }), h.title("My app")]),
+    h.body([
+      h.div({ id: "root" }, [app]),
+      h.script({ type: "module", src: "/src/entry-client.ts" }),
+    ]),
+  ]);
+});
+
+// { html, status } — `<!DOCTYPE html>` is prepended for you.
+export const render = (url: string) =>
+  Effect.runPromise(RouterServer.render(App, { document: documentShell, url }));
+
+// Or a Web fetch-style handler, ready to bridge into Vite or any Web server.
+export const handler = RouterServer.toWebHandler(App, { document: documentShell });
+```
+
+`render` provides both `Router.Outlet` (the app, per request) and `Router` (so the shell may read params), and renders through `renderToStringHydratable` so the client can `hydrate` in place.
+
+### `@effect/platform` is the spine
+
+The tree is the authoring surface, but `@effect/platform`'s `HttpApi` is the **single source of truth** for paths and schemas. Sealing the tree with `Router.router(...)` builds it once (`buildHttpApi`) and stamps it onto `def.httpApi`: a single `"pages"` group with one GET endpoint per leaf at its full path pattern, carrying `setPath(pathSchema)`, `setUrlParams(querySchema)`, and a `RouterNotFound → 404` error. Both sides read that one definition, so they always agree:
+
+- **Server** — `RouterServer` dispatches through `HttpApiBuilder` (platform owns request→leaf matching, path/query decode, and the 404 status).
+- **Client** — `RouterLive` derives a real `HttpApiClient` from the same `def.httpApi` (exposed as `Router.httpApiClient`) for network work. SPA URL→leaf resolution stays **local** (there is no public client-side "match this URL against my `HttpApi`" utility in platform), fed from the same endpoint definitions so it never drifts from the server.
+
+## Errors
+
+| Error               | Raised by                                                             | Recover with                                                                |
+| ------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `RouterNotFound`    | `notFound()`, or no route matched                                     | `Boundary.catchTag("RouterNotFound", …)` (or the app-level `notFound` page) |
+| `RouterParamsError` | `Router.params` / `Router.query` on a missing/invalid key or no match | `Boundary.catchTag("RouterParamsError", …)`                                 |
+
+Both are modeled as `Schema.TaggedError`, so they encode/decode across the wire the same way `Boundary.rpc` replays typed failures.
+
+## `Boundary.rpc` interplay
+
+Initial SSR navigation works end to end: the server resolves the rpc and inlines its payload, and the client replays it during `hydrate`. **Client-side** navigation into a page containing a `Boundary.rpc` has no SSR payload, so the boundary performs a **client-first mount** — it renders the boundary's `fallback`, forks the rpc call over `POST /_eui/rpc`, and swaps in the result. `@weftui/router` provides the `AppRpcClientTag` seam on both sides (network client on the client, in-process on the server), so the same rpc backs SSR-replay, refetch, and client-first mount. See the [rpc data boundaries guide](https://weftui.dev/docs/how-to/load-data-with-rpc).
+
+## See also
+
+- [`@weftui/router` API reference](https://weftui.dev/docs/reference/router)
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — a runnable SSR + hydration app with nested layouts, persistent layout state, type-safe `href`s, handler-arg props, and programmatic navigation over the `@effect/platform` spine
+- [Component Authoring](https://weftui.dev/docs/how-to/author-components) — `Component.make` / `Component.gen`, the idiomatic way to write route components
+- [Server-Side Rendering](https://weftui.dev/docs/how-to/render-on-the-server) — `renderToStringHydratable`, `hydrate`, and `Boundary.rpc`
+- [RPC Data Boundaries](https://weftui.dev/docs/how-to/load-data-with-rpc) — `Boundary.rpc`, the `Resource` handle, and the four lifecycles
+- [`packages/router/router.specs.md`](https://github.com/stefvw93/weft/blob/main/packages/router/router.specs.md) — the full specification

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

@@ -0,0 +1,264 @@
+---
+title: Component Authoring
+order: 1
+section: how-to
+description: Plain functions vs. Component.gen / Component.make, instance scope, fragments, render-prop children, and service requirements.
+---
+
+# 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.
+
+## Plain functions
+
+The simplest component is just a function:
+
+```typescript
+import { h } from "@weftui/core";
+
+function Greeting({ name }: { name: string }) {
+  return h.p(`Hello, ${name}!`);
+}
+
+// Call it like a function
+Greeting({ name: "World" });
+```
+
+Use a plain function 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
+
+## 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:
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, SubscriptionRef } from "effect";
+
+const Counter = () =>
+  Effect.gen(function* () {
+    const count = yield* SubscriptionRef.make(0);
+
+    return yield* h.div([
+      h.span([count.changes]),
+      h.button({ onclick: () => SubscriptionRef.update(count, (n) => n + 1) }, "+"),
+    ]);
+  });
+```
+
+The return type here is `Effect.Effect<Node, never, never>` — itself a valid `Node`, so it composes naturally with other tree-building calls. As soon as such a component is reused or takes props, prefer wrapping the same generator in [`Component.gen`](#componentgen--componentmake-for-reusable-components) (below) so the caller's reactive prop and children channels flow into its node type.
+
+## Component scope and background effects
+
+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 and is torn down automatically when the
+component unmounts (or when the whole tree unmounts via the `MountHandle`). 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.fork`.
+
+`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.fork` 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(
+      inputRef.changes,
+      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.fork,     // ❌ 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.
+
+```typescript
+import { Component, h, Source } from "@weftui/core";
+
+interface CardProps {
+  title: Source.Source<string>;
+  body?: Source.Source<string>;
+}
+
+const Card = Component.make((props: CardProps) =>
+  h.div({ class: "card" }, [
+    h.h3({ class: "card-title" }, [props.title]),
+    props.body ? h.p({ class: "card-body" }, [props.body]) : null,
+  ]),
+);
+```
+
+`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>` — so 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
+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.
+
+### 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.
+- 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:
+
+```typescript
+const ItemList = Component.make(
+  (props: { items: readonly string[] }, renderItem: (item: string) => readonly Renderable[]) =>
+    h.ul(props.items.flatMap(renderItem)),
+);
+
+ItemList({ items: ["a", "b"] }, (item) => [h.li(item)]);
+```
+
+## Props typing
+
+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>` — so the caller can pass a plain value or any reactive shape interchangeably, and you write it once:
+
+```typescript
+import { Source } from "@weftui/core";
+
+interface ButtonProps {
+  label: Source.Source<string>; // static or reactive text
+  disabled?: Source.Source<boolean>; // static or reactive boolean
+  onclick?: () => void | Effect.Effect<void>; // plain or Effect-returning handler
+}
+```
+
+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
+
+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), which turns any `Source<A>` into an await-first, hot `Subscribable<A>`:
+
+```typescript
+import { Component, h, Source } from "@weftui/core";
+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(label.changes, (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, and 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.
+
+## Composing components
+
+Call component functions directly inside a children array:
+
+```typescript
+import { h } from "@weftui/core";
+
+function App() {
+  return h.div({ class: "app" }, [
+    Header({ title: "My App" }),
+    h.main([Sidebar(), h.article([Content({ id: 1 })])]),
+    Footer(),
+  ]);
+}
+```
+
+Children arrays accumulate `E`/`R` from all their members. The parent node's type reflects the union of all children's channels.
+
+## Components that require services
+
+If a component's render function uses a service via `yield*`, that service appears in the component's `CompR` parameter:
+
+```typescript
+import { Component, h } from "@weftui/core";
+
+const UserAvatar = Component.gen(function* (props: { userId: string }) {
+  const userService = yield* UserService;
+  const user = yield* userService.getUser(props.userId);
+  return yield* h.img({ src: user.avatarUrl, alt: user.name });
+});
+
+// Node<never, UserService> — regardless of what the caller passes
+const avatar = UserAvatar({ userId: "123" });
+```
+
+Provide the service at the mount boundary:
+
+```typescript
+void Effect.runPromise(
+  mount(App(), document.getElementById("root")!).pipe(Effect.provide(UserServiceLive)),
+);
+```
+
+## Returning fragments
+
+When a component needs to return multiple sibling elements without a wrapper, use `h.fragment`:
+
+```typescript
+import { h } from "@weftui/core";
+
+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.
+
+## 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
+- [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