@weftui/router 0.27.1 → 0.29.0

package/README.md

@@ -1,6 +1,6 @@
 # @weftui/router
 
-> Universal nested router for [Weft](https://weftui.dev) — one route tree, rendered on the server and the client, with type-safe params and `href`s.
+> Universal nested router for [Weft](https://weftui.dev): one route tree, rendered on the server and the client, with type-safe params and `href`s.
 
 Maps a URL to a nested page tree that renders identically on the server (`@weftui/router/server`) and the client (`@weftui/router/client`). Route params and query are decoded through [Effect Schema](https://effect.website/docs/schema/introduction/), `href` builds type-safe URLs that round-trip with the matcher, layouts persist across navigations, and `Router.lazy` code-splits a branch while keeping its descriptor eager.
 
@@ -26,7 +26,7 @@ Weft tracks Effect 4's beta line. This release is built and tested against `effe
 | `Router.params` / `Router.query` | Read the live match (snapshot); `…Stream` variants for reactive query-in-place updates. |
 | `Router.navigating`              | Reactive `Idle`/`Navigating` signal for pending UI during deferred-commit navigation.   |
 | `href(ref, args)`                | Builds a type-safe URL for a leaf route reference.                                      |
-| `RouterApp` / `RouterOutlet`     | The universal router root node — render on both server and client.                      |
+| `RouterApp` / `RouterOutlet`     | The universal router root node: render on both server and client.                       |
 | `RouterLive` (client)            | History-backed `Router` layer; also provides the `AppRpcClientTag` seam.                |
 | `RouterServer` (server)          | `RouterServer.render` / `RouterServer.toWebHandler` for SSR dispatch.                   |
 
@@ -54,7 +54,7 @@ href(userRoute, { path: { id: 42 } }); // "/users/42"
 - Full docs: **https://weftui.dev**
 - `@weftui/router` API reference: **https://weftui.dev/docs/reference/router**
 - Routing guide: **https://weftui.dev/docs/how-to/add-routing**
-- Bundled with this package: see the [`./docs`](./docs) directory in `node_modules/@weftui/router/docs` — the complete tutorial, how-to, explanation, and reference tree ships on disk for offline and agent use.
+- Bundled with this package: see the [`./docs`](./docs) directory in `node_modules/@weftui/router/docs`. The complete tutorial, how-to, explanation, and reference tree ships on disk for offline and agent use.
 
 ## License
 

package/dist/client/index.d.ts

@@ -1,18 +1,17 @@
-import { S as Router, b as NavState, i as RouterDef, m as RouteNode, u as Fields, x as NavigateOptions } from "../compile-BJFIgBbE.js";
-import { n as outletNode, r as HrefArgs, t as RouterApp } from "../outlet-eoUQ-W0k.js";
+import { S as Router, b as NavState, i as RouterDef, m as RouteNode, u as Fields, x as NavigateOptions } from "../compile-Bb7AknG_.js";
+import { n as outletNode, r as HrefArgs, t as RouterApp } from "../outlet-2AnUWKQD.js";
 import { Effect, Layer, Scope } from "effect";
 import { AppRpcClientTag } from "@weftui/core";
 import { RpcGroup } from "effect/unstable/rpc";
-
 //#region src/client/router-live.d.ts
 /**
  * The residual app services a caller must still provide through the {@link RouterLiveOptions.context}
- * seam — a def's aggregate `R` minus the services `RouterLive` already threads
+ * seam: a def's aggregate `R` minus the services `RouterLive` already threads
  * (`Router`, `Router.Outlet`, `AppRpcClientTag`). The client mirror of
  * `RouterServer.AppServices`; resolves to `never` for an app with no app-wide service.
  */
 type AppServices<R> = Exclude<R, Router | Router.Outlet | AppRpcClientTag>;
-/** True only for the exact `any` type — a loosely-typed `RouterDef<any, any>`. */
+/** True only for the exact `any` type (a loosely-typed `RouterDef<any, any>`). */
 type IsAny<T> = 0 extends 1 & T ? true : false;
 /**
  * Conditionally shapes the `context` field: **required** when the def has statically
@@ -38,13 +37,14 @@ interface RouterLiveOptions {
   /**
    * The app's `Boundary.rpc` foundation: the merged `RpcGroup` contract (shared
    * with the server handler Layer). Backs the {@link AppRpcClientTag} seam so a
-   * hydrated boundary refetch — and a client-first SPA mount — resolve over the
-   * network rpc client. Optional: omit when the app has no `Boundary.rpc` — then
+   * hydrated boundary refetch (and a client-first SPA mount) resolve over the
+   * network rpc client. Optional: omit when the app has no `Boundary.rpc`. Then
    * no network rpc client is built and a stray `Boundary.rpc` fails with a
    * descriptive error.
    */
   readonly rpc?: {
-    /** The app's merged `RpcGroup` (pure Schema contract). */readonly group: RpcGroup.RpcGroup<any>;
+    /** The app's merged `RpcGroup` (pure Schema contract). */
+    readonly group: RpcGroup.RpcGroup<any>;
   };
 }
 /**
@@ -57,11 +57,11 @@ interface RouterLiveOptions {
  * It additionally derives a real {@link RouterHttpApiClient} from `def.httpApi`
  * (over `FetchHttpClient`, `baseUrl` default same-origin) and exposes it on the
  * `Router` service for network work. SPA URL→leaf resolution stays local via the
- * shared {@link match}er — both sides read the one `def.httpApi` definition.
+ * shared {@link match}er: both sides read the one `def.httpApi` definition.
  *
- * Alongside `Router` it provides the core {@link AppRpcClientTag} seam — a
+ * Alongside `Router` it provides the core {@link AppRpcClientTag} seam: a
  * **network** flat rpc client (`RpcClient.make` over `layerProtocolHttp` →
- * `POST /_eui/rpc`) — so `@weftui/dom` can resolve a `Boundary.rpc` (hydrated
+ * `POST /_eui/rpc`), so `@weftui/dom` can resolve a `Boundary.rpc` (hydrated
  * refetch and client-first mount) without depending on this package or
  * `effect/unstable/rpc`.
  */
@@ -74,8 +74,8 @@ declare function RouterLive<R>(def: RouterDef<any, R>, options?: RouterLiveOptio
  * the href resolves to a route (L1). Modified clicks, non-left buttons,
  * `target=_blank`, `download`, external origins, same-document (hash-only or
  * identical-URL) navigations, and non-matching hrefs fall through to the
- * browser's native handling — the interceptor leaves `preventDefault` untouched
- * in those cases (L2). The listener is removed on scope teardown (L3).
+ * browser's native handling. In those cases the interceptor leaves
+ * `preventDefault` untouched (L2). The listener is removed on scope teardown (L3).
  *
  * @param def - The router definition, used to decide whether an href matches a route.
  * @param navigate - The router's `navigate`, run via the captured runtime on a match.
@@ -88,10 +88,10 @@ declare function installLinkInterceptor(def: RouterDef, navigate: (to: string) =
  * type-safe {@link href} builder. They mirror the History API the client `Router`
  * layer (`RouterLive`) is backed by:
  *
- * - {@link navigate} — go to a leaf route reference with typed `{ path, query }`.
- * - {@link push} / {@link replace} — go to a raw `path + search` string.
- * - {@link back} / {@link forward} — step through History (`history.go`).
- * - {@link setQuery} / {@link patchQuery} — change the current route's query in
+ * - {@link navigate}: go to a leaf route reference with typed `{ path, query }`.
+ * - {@link push} / {@link replace}: go to a raw `path + search` string.
+ * - {@link back} / {@link forward}: step through History (`history.go`).
+ * - {@link setQuery} / {@link patchQuery}: change the current route's query in
  *   place, re-encoding through the matched leaf's `querySchema`.
  *
  * All but `back`/`forward` require the `Router` service (run them within the layer
@@ -99,10 +99,10 @@ declare function installLinkInterceptor(def: RouterDef, navigate: (to: string) =
  */
 /**
  * Navigates to a leaf route `ref` with typed `path`/`query` args, building the URL
- * via {@link href} (so it round-trips with `match`) and pushing — or, with
- * `options.replace`, replacing — the History entry. `path` is required when the
- * route has path params; `query` is optional when every query field is optional
- * (same requiredness rules as `href`).
+ * via {@link href} (so it round-trips with `match`) and pushing the History entry,
+ * or replacing it with `options.replace`. `path` is required when the route has
+ * path params; `query` is optional when every query field is optional (same
+ * requiredness rules as `href`).
  *
  * @example
  * ```ts

package/dist/client/index.js

@@ -1,5 +1,5 @@
-import { a as Router, i as setResolvedCommit, n as outletNode, o as getPreload, r as preRunLeaf, t as RouterApp } from "../outlet-C9N4a4_F.js";
-import { r as match, t as href } from "../href-uvJ6b7zz.js";
+import { a as Router, i as setResolvedCommit, n as outletNode, o as getPreload, r as preRunLeaf, t as RouterApp } from "../outlet-BgJmsO_g.js";
+import { r as match, t as href } from "../href-3swSSbn_.js";
 import { HttpApiClient } from "effect/unstable/httpapi";
 import { Context, Effect, Exit, Fiber, Layer, Option, Schema, Scope, Stream, SubscriptionRef } from "effect";
 import { AppRpcClientTag, Subscribable } from "@weftui/core";
@@ -11,8 +11,8 @@ import { FetchHttpClient } from "effect/unstable/http";
 * the href resolves to a route (L1). Modified clicks, non-left buttons,
 * `target=_blank`, `download`, external origins, same-document (hash-only or
 * identical-URL) navigations, and non-matching hrefs fall through to the
-* browser's native handling — the interceptor leaves `preventDefault` untouched
-* in those cases (L2). The listener is removed on scope teardown (L3).
+* browser's native handling. In those cases the interceptor leaves
+* `preventDefault` untouched (L2). The listener is removed on scope teardown (L3).
 *
 * @param def - The router definition, used to decide whether an href matches a route.
 * @param navigate - The router's `navigate`, run via the captured runtime on a match.
@@ -68,11 +68,11 @@ function normalizeTo(to) {
 * It additionally derives a real {@link RouterHttpApiClient} from `def.httpApi`
 * (over `FetchHttpClient`, `baseUrl` default same-origin) and exposes it on the
 * `Router` service for network work. SPA URL→leaf resolution stays local via the
-* shared {@link match}er — both sides read the one `def.httpApi` definition.
+* shared {@link match}er: both sides read the one `def.httpApi` definition.
 *
-* Alongside `Router` it provides the core {@link AppRpcClientTag} seam — a
+* Alongside `Router` it provides the core {@link AppRpcClientTag} seam: a
 * **network** flat rpc client (`RpcClient.make` over `layerProtocolHttp` →
-* `POST /_eui/rpc`) — so `@weftui/dom` can resolve a `Boundary.rpc` (hydrated
+* `POST /_eui/rpc`), so `@weftui/dom` can resolve a `Boundary.rpc` (hydrated
 * refetch and client-first mount) without depending on this package or
 * `effect/unstable/rpc`.
 */
@@ -187,10 +187,10 @@ function RouterLive(def, options = {}) {
 * type-safe {@link href} builder. They mirror the History API the client `Router`
 * layer (`RouterLive`) is backed by:
 *
-* - {@link navigate} — go to a leaf route reference with typed `{ path, query }`.
-* - {@link push} / {@link replace} — go to a raw `path + search` string.
-* - {@link back} / {@link forward} — step through History (`history.go`).
-* - {@link setQuery} / {@link patchQuery} — change the current route's query in
+* - {@link navigate}: go to a leaf route reference with typed `{ path, query }`.
+* - {@link push} / {@link replace}: go to a raw `path + search` string.
+* - {@link back} / {@link forward}: step through History (`history.go`).
+* - {@link setQuery} / {@link patchQuery}: change the current route's query in
 *   place, re-encoding through the matched leaf's `querySchema`.
 *
 * All but `back`/`forward` require the `Router` service (run them within the layer
@@ -198,10 +198,10 @@ function RouterLive(def, options = {}) {
 */
 /**
 * Navigates to a leaf route `ref` with typed `path`/`query` args, building the URL
-* via {@link href} (so it round-trips with `match`) and pushing — or, with
-* `options.replace`, replacing — the History entry. `path` is required when the
-* route has path params; `query` is optional when every query field is optional
-* (same requiredness rules as `href`).
+* via {@link href} (so it round-trips with `match`) and pushing the History entry,
+* or replacing it with `options.replace`. `path` is required when the route has
+* path params; `query` is optional when every query field is optional (same
+* requiredness rules as `href`).
 *
 * @example
 * ```ts

package/dist/{compile-BJFIgBbE.d.ts → compile-Bb7AknG_.d.ts}

@@ -1,10 +1,10 @@
 import { HttpApi, HttpApiClient } from "effect/unstable/httpapi";
 import { Context, Effect, Option, Schema } from "effect";
 import { Component, Node, Subscribable } from "@weftui/core";
-
 //#region src/errors.d.ts
 declare const RouterNotFound_base: Schema.Class<RouterNotFound, Schema.TaggedStruct<"RouterNotFound", {
-  /** The path that could not be resolved, when known. */readonly path: Schema.optional<Schema.String>;
+  /** The path that could not be resolved, when known. */
+  readonly path: Schema.optional<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Tagged error raised by {@link notFound} and caught by the router's internal
@@ -28,12 +28,14 @@ declare const notFound: (path?: string) => Effect.Effect<never, RouterNotFound>;
 /** Type guard recognising a {@link RouterNotFound} value regardless of its prototype. */
 declare const isRouterNotFound: (u: unknown) => u is RouterNotFound;
 declare const RouterParamsError_base: Schema.Class<RouterParamsError, Schema.TaggedStruct<"RouterParamsError", {
-  /** Which side of the match failed validation. */readonly source: Schema.Literals<readonly ["path", "query"]>; /** The requested field names, for diagnostics. */
+  /** Which side of the match failed validation. */
+  readonly source: Schema.Literals<readonly ["path", "query"]>;
+  /** The requested field names, for diagnostics. */
   readonly keys: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Tagged error raised by `Router.params` / `Router.query` when the live match does
- * not satisfy the requested fields — either no route is matched, or a requested
+ * not satisfy the requested fields: either no route is matched, or a requested
  * key is missing / fails its schema's `Type`-side validation. `source` records
  * whether the failure was on the path params or the query, and `keys` lists the
  * requested field names for diagnostics.
@@ -52,7 +54,8 @@ type RouteMatch = {
   readonly _tag: "Matched";
   readonly leaf: CompiledLeaf;
   readonly path: Record<string, unknown>;
-  readonly query: Record<string, unknown>; /** Normalized request URL (path + search), used by the outlet as a dedupe key. */
+  readonly query: Record<string, unknown>;
+  /** Normalized request URL (path + search), used by the outlet as a dedupe key. */
   readonly url: string;
 } | {
   readonly _tag: "NotFound";
@@ -73,19 +76,16 @@ interface MatcherEntry {
 }
 /**
  * Precompiles a {@link RouterDef} into ordered matcher entries (memoized per
- * `RouterDef`). The patterns and path/query schemas are read from the authoritative
- * `def.httpApi` `"pages"` endpoints — the single source of truth the server dispatch
- * also reads — and each entry's render metadata leaf is resolved from `def.compiled`
+ * `RouterDef`). Patterns and path/query schemas are read from the authoritative
+ * `def.httpApi` `"pages"` endpoints (the single source of truth the server dispatch
+ * also reads), and each entry's render metadata leaf is resolved from `def.compiled`
  * by endpoint id. Matching stays local (SPA URL→leaf); see the refactor plan's
  * _Feasibility constraint_.
  *
  * Entries are sorted most-specific first (fewer params, then longer pattern) so a
- * static segment wins over a param segment at the same position (M6).
- *
- * Note: the specificity order is a global heuristic (param count, then length).
- * It resolves the common "static beats param at the same position" case, but two
- * patterns with the same param count and length (e.g. `/a/:b/c` vs `/a/x/:d`)
- * fall back to endpoint order.
+ * static segment wins over a param segment at the same position (M6). That order is
+ * a global heuristic, so two patterns with the same param count and length (e.g.
+ * `/a/:b/c` vs `/a/x/:d`) fall back to endpoint order.
  */
 declare function compileMatchers(def: RouterDef): readonly MatcherEntry[];
 /**
@@ -98,7 +98,7 @@ declare function match(def: RouterDef, url: string): RouteMatch;
 //#endregion
 //#region src/router-service.d.ts
 /**
- * The universal router service. Provided per render — by `RouterLive` on the
+ * The universal router service. Provided per render: by `RouterLive` on the
  * client (History-API backed) and by a fixed per-request implementation on the
  * server. Layouts and pages read it anywhere via `yield* Router`.
  *
@@ -106,12 +106,12 @@ declare function match(def: RouterDef, url: string): RouteMatch;
  * {@link Router.layout}, and {@link Router.router} build the route tree (mirroring
  * `Component.gen` / `Boundary.catchTag` / `h.div`), and {@link Router.Outlet} /
  * {@link Router.params} / {@link Router.query} deliver the outlet and the live
- * match's params/query by dependency injection. The roles merge by declaration —
+ * match's params/query by dependency injection. The roles merge by declaration:
  * `yield* Router` reads the service; `Router.route(…)` authors a tree.
  */
 /**
  * The platform `HttpApiClient` derived from a router's `HttpApi` spine. Typed
- * opaquely (`Client<any, …>`) because the spine is `HttpApi.Top` — its
+ * opaquely (`Client<any, …>`) because the spine is `HttpApi.Top`: its
  * group/endpoint shapes are assembled in a runtime loop by `buildHttpApi`, so a
  * precise client type is not recoverable. Present (`Option.some`) on the client
  * (`RouterLive`), absent (`Option.none`) on the server, which is itself the origin.
@@ -142,7 +142,8 @@ interface NavigateOptions {
   readonly replace?: boolean;
 }
 declare const Router_base: Context.ServiceClass<Router, "@weftui/router/Router", {
-  /** The current match as a hot `Subscribable`; drives the outlet. */readonly currentMatch: Subscribable.Subscribable<RouteMatch>;
+  /** The current match as a hot `Subscribable`; drives the outlet. */
+  readonly currentMatch: Subscribable.Subscribable<RouteMatch>;
   /**
    * Navigates to `to` (a path, optionally with a query). On the client this
    * pushes History state and re-renders the affected outlet; on the server it
@@ -152,8 +153,8 @@ declare const Router_base: Context.ServiceClass<Router, "@weftui/router/Router",
   /**
    * The derived {@link RouterHttpApiClient} for network work (route prefetch,
    * foundation for future loaders/data). `Option.some` on the client,
-   * `Option.none` on the server. SPA URL→leaf resolution does **not** use this —
-   * it stays local via the shared matcher (see the refactor _Feasibility constraint_).
+   * `Option.none` on the server. SPA URL→leaf resolution does **not** use this.
+   * It stays local via the shared matcher (see the refactor _Feasibility constraint_).
    */
   readonly httpApiClient: Option.Option<RouterHttpApiClient>;
   /**
@@ -174,17 +175,17 @@ declare const OutletTag_base: Context.ServiceClass<OutletTag, "@weftui/router/Ou
  * reads it with `yield* Router.Outlet`.
  *
  * Typed **opaque** as `Node<never, never>` so splicing `[outlet]` adds nothing to
- * a layout's local channels — the subtree's real channels are aggregated
+ * a layout's local channels: the subtree's real channels are aggregated
  * structurally by {@link makeLayout} / {@link makeRouter}, never inferred across
  * this DI boundary. Re-exported on the namespace as `Router.Outlet`.
  */
 declare class OutletTag extends OutletTag_base {}
 /**
  * Reads the live match's **path params** for the requested `fields`. Snapshot
- * semantics — reads `yield* Router` then `currentMatch.get` — and returns the
+ * semantics (reads `yield* Router`, then `currentMatch.get`), returning the
  * already-decoded values **directly**: the matcher decoded them against the leaf's
- * full path schema, so no re-validation is needed (the cast is sound — the picked
- * subset is the `Type` side of `fields`). Fails with a {@link RouterParamsError}
+ * full path schema, so no re-validation is needed. The cast is sound because the
+ * picked subset is the `Type` side of `fields`. Fails with a {@link RouterParamsError}
  * (`source: "path"`) only when no route is matched. Re-exported as `Router.params`.
  */
 declare function readParams<F extends Fields>(fields: F): Effect.Effect<FieldsType<F>, RouterParamsError, Router>;
@@ -248,7 +249,7 @@ type FieldsType<F extends Fields> = Schema.Struct.Type<F>;
  * The router passes `{ path, query }` into the leaf slot at render time (the
  * {@link makeRoute} props-form overload), so a page can read them directly as props
  * instead of via the `Router.params` / `Router.query` dependency-injection
- * accessors. Layouts and deeper nodes — which can't take handler args — keep DI.
+ * accessors. Layouts and deeper nodes keep DI, since they can't take handler args.
  */
 interface RouteHandlerProps<Path extends Fields = {}, Query extends Fields = {}> {
   /** The live match's decoded path params (`Type` side of the route's `path`). */
@@ -260,26 +261,26 @@ interface RouteHandlerProps<Path extends Fields = {}, Query extends Fields = {}>
  * The shape of a route/layout `component` slot: a callable producing a {@link Node},
  * invoked by the router at render time. It accepts both a plain zero-arg thunk
  * (`() => h.div(…)`) and a {@link Component} produced by `Component.make` /
- * `Component.gen` (a generic `(props, children?) => Node`). The `props: any` arm —
- * rather than `()` — is what keeps a required-props `Component<…>` structurally
+ * `Component.gen` (a generic `(props, children?) => Node`). The `props: any` arm,
+ * rather than `()`, is what keeps a required-props `Component<…>` structurally
  * assignable; the router calls the slot with no arguments.
  */
 type ComponentSlot<N extends Node<any, any> = Node<any, any>> = (props: any) => N;
 /**
  * The {@link Node} a {@link ComponentSlot} produces when the router invokes it with no
- * props/children — used to recover the slot's `E`/`R` channels for the route tree.
+ * props/children. Used to recover the slot's `E`/`R` channels for the route tree.
  *
  * A plain zero-arg thunk is matched first (`() => infer N`): a required-props
  * `Component` is *not* assignable to `() => unknown`, so it falls through to the
  * `Component` arm, where the internal `E`/`R` type parameters are read directly. This
- * two-step form is deliberate — `ReturnType<S>` collapses a generic `Component`'s
+ * two-step form is deliberate: `ReturnType<S>` collapses a generic `Component`'s
  * channels to `unknown` (they depend on the erased `GenP`/`GenC`), whereas extracting
  * the `Component<…, E, R>` parameters preserves them. Caller prop/children channels are
  * never relevant here because the router supplies neither.
  */
 type SlotNode<S> = S extends (() => infer N) ? N : S extends Component.Component<any, any, infer E, infer R> ? Node<E, R> : never;
 /**
- * A leaf page in the route tree. Its `component` *is* its handler — a
+ * A leaf page in the route tree. Its `component` *is* its handler: a
  * {@link ComponentSlot} (a `Component.gen` / `Component.make` component, or a plain
  * `() => Node` thunk) that the router invokes at render time and that reads the live
  * match's params via `Router.params` / `Router.query`. `Path`/`Query` drive matching
@@ -300,7 +301,7 @@ interface RouteNode<Path extends Fields = {}, Query extends Fields = {}, E = nev
 }
 /**
  * A layout wrapping an outlet (the next level down) in the route tree. A layout is
- * **purely UI nesting** — it owns **no path or segment**; all path structure lives
+ * **purely UI nesting**: it owns **no path or segment**; all path structure lives
  * on routes. Its `component` is a {@link ComponentSlot} that splices the injected
  * outlet via `yield* Router.Outlet`; the router invokes it per render and discharges
  * that `Outlet` requirement. A layout that needs a param reads it via `Router.params`.
@@ -315,7 +316,7 @@ interface LayoutNode<E = never, R = never> {
   /**
    * Phantom marker for this layout subtree's aggregate error channel (see
    * {@link TreeE}). Covariant (stores `E` directly) so a fully-discharged layout
-   * (`LayoutNode<never, never>` — its `Outlet` provided, no subtree errors) stays
+   * (`LayoutNode<never, never>`, its `Outlet` provided and no subtree errors) stays
    * assignable to the `LayoutNode<any, any>` arm of {@link TreeNode}.
    */
   readonly _E?: E;
@@ -333,26 +334,17 @@ type SubtreeE<C extends readonly TreeNode[]> = TreeE<C[number]>;
 /** Aggregate requirement channel over a children tuple (distributes over `C[number]`). */
 type SubtreeR<C extends readonly TreeNode[]> = TreeR<C[number]>;
 /**
- * Declares a leaf page. The `component` *is* the route handler — a thunk the
+ * Declares a leaf page. The `component` *is* the route handler: a thunk the
  * router invokes at render time; its error / requirement channels propagate up the
  * tree. Two authoring forms are accepted:
  *
- * - **Handler-arg props** — the slot declares `(props: {@link RouteHandlerProps})`
+ * - **Handler-arg props**: the slot declares `(props: {@link RouteHandlerProps})`
  *   and the router passes the live match's decoded `{ path, query }` in directly
  *   (first overload; `path`/`query` are inferred from the route's `path`/`query`
- *   fields). A plain zero-arg thunk works too — it just ignores the props.
- * - **Dependency injection** — a `Component.make` / `Component.gen` component that
+ *   fields). A plain zero-arg thunk works too. It just ignores the props.
+ * - **Dependency injection**: a `Component.make` / `Component.gen` component that
  *   reads the live match via `Router.params` / `Router.query` (second overload).
  *
- * @example Handler-arg props (decoded `{ path, query }`)
- * ```ts
- * Router.route("users/:id", {
- *   path: { id: Schema.NumberFromString },
- *   query: { tab: Schema.optional(Schema.String) },
- *   component: ({ path, query }) => h.div({}, `User ${path.id} (${query.tab ?? "info"})`),
- * });
- * ```
- *
  * @example Dependency injection (`Router.params` / a `Component`)
  * ```ts
  * Router.route("about", { component: Component.make(() => h.h1({}, "About")) });
@@ -400,24 +392,16 @@ declare function makeLayout<C extends readonly TreeNode[], S extends ComponentSl
 }, children: C): LayoutNode<Node.Error<SlotNode<S>> | SubtreeE<C>, Exclude<Node.Context<SlotNode<S>>, Router.Outlet> | SubtreeR<C>>;
 /**
  * Wraps a dynamic-import `load` as a lazy {@link ComponentSlot}: the route's descriptor
- * (`segment`, `path`/`query`) stays eager and matchable, while the component — the render
- * body and its module's deps — is split into the chunk `load` resolves. The router invokes
+ * (`segment`, `path`/`query`) stays eager and matchable, while the component (the render
+ * body and its module's deps) is split into the chunk `load` resolves. The router invokes
  * the returned slot at render time; it awaits `load` then renders the resolved component,
  * adopting the server DOM in place on hydration (flash-free) and fetching the chunk on
  * client navigation. Exposed as {@link Router.lazy}. See `lazy-component.specs.md`.
  *
  * The resolved value is a component slot (`Component.gen` / `Component.make`, or a
- * `() => Node` thunk) — the shape `component:` already accepts — so its `E`/`R` channels
+ * `() => Node` thunk), the shape `component:` already accepts, so its `E`/`R` channels
  * are recovered via {@link SlotNode} and propagate up the tree exactly as an eager
  * component's do.
- *
- * @example
- * ```ts
- * Router.route("docs/:category/:slug", {
- *   path: { category: Schema.String, slug: Schema.String },
- *   component: Router.lazy(() => import("./doc-page").then((m) => m.DocPage)),
- * });
- * ```
  */
 declare function lazyComponent<S extends ComponentSlot>(load: () => Promise<S>): () => Node<Node.Error<SlotNode<S>>, Node.Context<SlotNode<S>>>;
 //#endregion
@@ -426,7 +410,7 @@ declare function lazyComponent<S extends ComponentSlot>(load: () => Promise<S>):
  * A compiled layout level: its component slot plus the dedupe `patternPrefix` used
  * by the client outlet to key the level. A layout owns no path of its own, so the
  * prefix is derived as the **longest common path-segment prefix of every leaf in
- * the layout's subtree** — it changes (and the level re-renders) exactly when a
+ * the layout's subtree**: it changes (and the level re-renders) exactly when a
  * param shared by all those leaves changes, and persists otherwise.
  */
 interface CompiledLayout {
@@ -452,7 +436,7 @@ interface CompiledLeaf {
   /**
    * Path-param schema. Its **encoded** side is typed string-encodeable
    * (`Record<string, string | undefined>`) so it satisfies platform's
-   * `HttpApiEndpoint` `params` constraint without an `as any` cast — param schemas
+   * `HttpApiEndpoint` `params` constraint without an `as any` cast: param schemas
    * round-trip strings, so the `Schema.Struct` value is asserted to this shape.
    */
   readonly pathSchema: Schema.Codec<Record<string, unknown>, Readonly<Record<string, string | undefined>>>;
@@ -516,9 +500,9 @@ declare const leafRegistry: WeakMap<RouteNode<any, any, any, any>, CompiledLeaf>
  * Pass 1 walks the tree: only **routes** contribute path parts (layouts own no
  * path), so each leaf's `parts` come solely from the route segments on its branch,
  * and its ancestor `LayoutNode`s are recorded in order. Pass 2 derives one shared
- * {@link CompiledLayout} per distinct layout node — its `patternPrefix` is the
- * longest common path prefix of that layout's subtree leaves — then assembles each
- * leaf's `layoutChain` (root → parent) and merged path schema.
+ * {@link CompiledLayout} per distinct layout node, whose `patternPrefix` is the
+ * longest common path prefix of that layout's subtree leaves. It then assembles
+ * each leaf's `layoutChain` (root → parent) and merged path schema.
  */
 declare function compile(def: {
   root: TreeNode;
@@ -526,7 +510,7 @@ declare function compile(def: {
 }): Compiled;
 /**
  * Builds the authoritative `HttpApi` for a compiled tree (S4): a single `"pages"`
- * group whose endpoints are GET endpoints — one per leaf — at each leaf's full path
+ * group holding one GET endpoint per leaf, at each leaf's full path
  * pattern, carrying `params: pathSchema`, `query: querySchema`, a
  * `Schema.String` (text/HTML) success, and a `RouterNotFound → 404` error. The tree
  * (not `HttpApi`) is the authoring surface; this is the single source of truth the

package/dist/{href-uvJ6b7zz.js → href-3swSSbn_.js}

@@ -1,4 +1,4 @@
-import { l as leafRegistry } from "./outlet-C9N4a4_F.js";
+import { l as leafRegistry } from "./outlet-BgJmsO_g.js";
 import { Result, Schema } from "effect";
 //#region src/matcher.ts
 /** Escapes a literal path segment for inclusion in a `RegExp`. */
@@ -28,19 +28,16 @@ const emptySchema = Schema.Struct({});
 const matchersCache = /* @__PURE__ */ new WeakMap();
 /**
 * Precompiles a {@link RouterDef} into ordered matcher entries (memoized per
-* `RouterDef`). The patterns and path/query schemas are read from the authoritative
-* `def.httpApi` `"pages"` endpoints — the single source of truth the server dispatch
-* also reads — and each entry's render metadata leaf is resolved from `def.compiled`
+* `RouterDef`). Patterns and path/query schemas are read from the authoritative
+* `def.httpApi` `"pages"` endpoints (the single source of truth the server dispatch
+* also reads), and each entry's render metadata leaf is resolved from `def.compiled`
 * by endpoint id. Matching stays local (SPA URL→leaf); see the refactor plan's
 * _Feasibility constraint_.
 *
 * Entries are sorted most-specific first (fewer params, then longer pattern) so a
-* static segment wins over a param segment at the same position (M6).
-*
-* Note: the specificity order is a global heuristic (param count, then length).
-* It resolves the common "static beats param at the same position" case, but two
-* patterns with the same param count and length (e.g. `/a/:b/c` vs `/a/x/:d`)
-* fall back to endpoint order.
+* static segment wins over a param segment at the same position (M6). That order is
+* a global heuristic, so two patterns with the same param count and length (e.g.
+* `/a/:b/c` vs `/a/x/:d`) fall back to endpoint order.
 */
 function compileMatchers(def) {
 	const cached = matchersCache.get(def);

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { A as notFound, C as RouterHttpApiClient, D as RouterNotFound, E as match, O as RouterParamsError, S as Router, T as compileMatchers, _ as TreeE, a as RouterOptions, b as NavState, c as leafRegistry, d as FieldsType, f as LayoutNode, g as SubtreeR, h as SubtreeE, i as RouterDef, k as isRouterNotFound, l as ComponentSlot, m as RouteNode, n as CompiledLayout, o as buildHttpApi, p as RouteHandlerProps, r as CompiledLeaf, s as compile, t as Compiled, u as Fields, v as TreeNode, w as RouteMatch, x as NavigateOptions, y as TreeR } from "./compile-BJFIgBbE.js";
-import { i as href, n as outletNode, r as HrefArgs, t as RouterApp } from "./outlet-eoUQ-W0k.js";
+import { A as notFound, C as RouterHttpApiClient, D as RouterNotFound, E as match, O as RouterParamsError, S as Router, T as compileMatchers, _ as TreeE, a as RouterOptions, b as NavState, c as leafRegistry, d as FieldsType, f as LayoutNode, g as SubtreeR, h as SubtreeE, i as RouterDef, k as isRouterNotFound, l as ComponentSlot, m as RouteNode, n as CompiledLayout, o as buildHttpApi, p as RouteHandlerProps, r as CompiledLeaf, s as compile, t as Compiled, u as Fields, v as TreeNode, w as RouteMatch, x as NavigateOptions, y as TreeR } from "./compile-Bb7AknG_.js";
+import { i as href, n as outletNode, r as HrefArgs, t as RouterApp } from "./outlet-2AnUWKQD.js";
 export { type Compiled, type CompiledLayout, type CompiledLeaf, type ComponentSlot, type Fields, type FieldsType, type HrefArgs, type LayoutNode, type NavState, type NavigateOptions, type RouteHandlerProps, type RouteMatch, type RouteNode, Router, RouterApp, type RouterDef, type RouterHttpApiClient, RouterNotFound, type RouterOptions, RouterParamsError, type SubtreeE, type SubtreeR, type TreeE, type TreeNode, type TreeR, buildHttpApi, compile, compileMatchers, href, isRouterNotFound, leafRegistry, match, notFound, outletNode };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as Router, c as compile, d as RouterParamsError, f as isRouterNotFound, l as leafRegistry, n as outletNode, p as notFound, s as buildHttpApi, t as RouterApp, u as RouterNotFound } from "./outlet-C9N4a4_F.js";
-import { n as compileMatchers, r as match, t as href } from "./href-uvJ6b7zz.js";
+import { a as Router, c as compile, d as RouterParamsError, f as isRouterNotFound, l as leafRegistry, n as outletNode, p as notFound, s as buildHttpApi, t as RouterApp, u as RouterNotFound } from "./outlet-BgJmsO_g.js";
+import { n as compileMatchers, r as match, t as href } from "./href-3swSSbn_.js";
 export { Router, RouterApp, RouterNotFound, RouterParamsError, buildHttpApi, compile, compileMatchers, href, isRouterNotFound, leafRegistry, match, notFound, outletNode };

package/dist/{outlet-eoUQ-W0k.d.ts → outlet-2AnUWKQD.d.ts}

@@ -1,6 +1,5 @@
-import { D as RouterNotFound, S as Router, d as FieldsType, i as RouterDef, m as RouteNode, u as Fields } from "./compile-BJFIgBbE.js";
+import { D as RouterNotFound, S as Router, d as FieldsType, i as RouterDef, m as RouteNode, u as Fields } from "./compile-Bb7AknG_.js";
 import { Node } from "@weftui/core";
-
 //#region src/href.d.ts
 /**
  * The `href` argument object for a leaf with path fields `Path` and query fields