@weftui/router 0.21.0 → 0.23.0

package/dist/outlet-CXgDkheJ.js

@@ -0,0 +1,467 @@
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "@effect/platform";
+import { Context, Effect, Schema, Stream, Subscribable, pipe } from "effect";
+import { Boundary, h } from "@weftui/core";
+//#region src/errors.ts
+/**
+* Tagged error raised by {@link notFound} and caught by the router's internal
+* not-found boundary. Exported so a user can place their own
+* `Boundary.catchTag("RouterNotFound", …)` to override the fallback for a subtree
+* (the router's internal boundary is outermost, so a nearer user boundary wins).
+*
+* Modeled as a `Schema.TaggedError` so it can be encoded/decoded across the wire
+* the same way `Boundary.rpc` replays typed failures.
+*/
+var RouterNotFound = class extends Schema.TaggedError()("RouterNotFound", { 
+/** The path that could not be resolved, when known. */
+path: Schema.optional(Schema.String) }) {};
+/**
+* Short-circuits the current page render with a {@link RouterNotFound} failure,
+* Next.js-style. Callable from any page or layout `component`; the nearest
+* enclosing not-found boundary (the router's internal one by default) renders the
+* configured `notFound` page in its place. The server responds with HTTP 404.
+*
+* @param path - Optional path to attach for diagnostics.
+*/
+const notFound = (path) => Effect.fail(new RouterNotFound({ path }));
+/** Type guard recognising a {@link RouterNotFound} value regardless of its prototype. */
+const isRouterNotFound = (u) => typeof u === "object" && u !== null && "_tag" in u && u._tag === "RouterNotFound";
+/**
+* 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
+* 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.
+*
+* It bubbles up through the route tree's aggregate error channel, so a user may
+* place a `Boundary.catchTag("RouterParamsError", …)` to recover within a subtree.
+*
+* Modeled as a `Schema.TaggedError` so it can be encoded/decoded across the wire
+* the same way `RouterNotFound` and `Boundary.rpc` replay typed failures.
+*/
+var RouterParamsError = class extends Schema.TaggedError()("RouterParamsError", {
+	/** Which side of the match failed validation. */
+	source: Schema.Literal("path", "query"),
+	/** The requested field names, for diagnostics. */
+	keys: Schema.Array(Schema.String)
+}) {};
+//#endregion
+//#region src/compile.ts
+/**
+* Maps each authored {@link RouteNode} to its {@link CompiledLeaf}. Populated by
+* {@link compile} (via {@link router}) and read by `href` so a leaf reference can
+* resolve its full pattern and schemas.
+*/
+const leafRegistry = /* @__PURE__ */ new WeakMap();
+/** Splits a segment string into its non-empty path parts. */
+function splitSegment(segment) {
+	return segment.split("/").filter((s) => s.length > 0);
+}
+/** Joins cumulative path parts into a normalized pattern (`/`-prefixed, no trailing `/`). */
+function toPattern(parts) {
+	return parts.length === 0 ? "/" : `/${parts.join("/")}`;
+}
+/** Extracts `:name` placeholder names from cumulative path parts, in order. */
+function extractParams(parts) {
+	return parts.filter((p) => p.startsWith(":")).map((p) => p.slice(1));
+}
+/** Derives a stable, identifier-safe id from a full path pattern. */
+function patternToId(pattern, index) {
+	const base = pattern.replace(/:/g, "").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	return base.length === 0 ? `root_${index}` : `${base}_${index}`;
+}
+/** The longest leading run of path parts shared by every entry in `partsList`. */
+function longestCommonSegmentPrefix(partsList) {
+	const first = partsList[0];
+	if (first === void 0) return [];
+	const prefix = [];
+	for (let i = 0; i < first.length; i++) {
+		const part = first[i];
+		if (part === void 0) break;
+		let common = true;
+		for (let j = 1; j < partsList.length; j++) if (partsList[j]?.[i] !== part) {
+			common = false;
+			break;
+		}
+		if (!common) break;
+		prefix.push(part);
+	}
+	return prefix;
+}
+/**
+* Compiles a route tree into a flat list of {@link CompiledLeaf}s (C1–C6).
+*
+* 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.
+*/
+function compile(def) {
+	const leafWorks = [];
+	const walk = (node, parentParts, parentPathFields, ancestors) => {
+		if (node._tag === "Layout") {
+			for (const child of node.children) walk(child, parentParts, parentPathFields, [...ancestors, node]);
+			return;
+		}
+		leafWorks.push({
+			node,
+			parts: [...parentParts, ...splitSegment(node.segment)],
+			pathFields: {
+				...parentPathFields,
+				...node.path
+			},
+			query: node.query,
+			ancestors
+		});
+	};
+	walk(def.root, [], {}, []);
+	const layoutLeafParts = /* @__PURE__ */ new Map();
+	for (const work of leafWorks) for (const ancestor of work.ancestors) {
+		const list = layoutLeafParts.get(ancestor) ?? [];
+		list.push(work.parts);
+		layoutLeafParts.set(ancestor, list);
+	}
+	const compiledLayouts = /* @__PURE__ */ new Map();
+	for (const [node, partsList] of layoutLeafParts) {
+		const lcp = longestCommonSegmentPrefix(partsList);
+		compiledLayouts.set(node, {
+			patternPrefix: toPattern(lcp),
+			paramNames: extractParams(lcp),
+			component: node.component
+		});
+	}
+	const leaves = [];
+	for (const work of leafWorks) {
+		const fullPathPattern = toPattern(work.parts);
+		const paramNames = extractParams(work.parts);
+		const pathFields = {};
+		for (const name of paramNames) pathFields[name] = work.pathFields[name] ?? Schema.String;
+		const leaf = {
+			id: patternToId(fullPathPattern, leaves.length),
+			fullPathPattern,
+			paramNames,
+			pathSchema: Schema.Struct(pathFields),
+			querySchema: Schema.Struct(work.query),
+			component: work.node.component,
+			layoutChain: work.ancestors.map((a) => compiledLayouts.get(a))
+		};
+		leaves.push(leaf);
+		leafRegistry.set(work.node, leaf);
+	}
+	return {
+		leaves,
+		notFound: def.notFound
+	};
+}
+/**
+* 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
+* pattern, carrying `setPath(pathSchema)`, `setUrlParams(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
+* server dispatch (`HttpApiBuilder`) and the client matcher / derived `HttpApiClient`
+* read from, so both sides agree on paths and schemas.
+*
+* Each leaf's `pathSchema`/`querySchema` are typed string-encodeable (see
+* {@link CompiledLeaf}), so `setPath`/`setUrlParams` need no `as any` casts.
+*
+* `Boundary.rpc` data no longer rides this spine: it resolves through the app's
+* merged `RpcGroup` over the ambient `AppRpcClient` (`POST /_eui/rpc`), wired
+* explicitly into `RouterServer`/`RouterLive`. The matcher reads only `"pages"`.
+*/
+function buildHttpApi(leaves) {
+	const group = leaves.reduce((g, leaf) => g.add(HttpApiEndpoint.get(leaf.id, leaf.fullPathPattern).setPath(leaf.pathSchema).setUrlParams(leaf.querySchema).addSuccess(Schema.String).addError(RouterNotFound, { status: 404 })), HttpApiGroup.make("pages"));
+	return HttpApi.make("router").add(group);
+}
+/**
+* Seals a route tree into a {@link RouterDef}, compiling it eagerly (so leaf
+* references are stamped for `href`), building its authoritative {@link buildHttpApi}
+* spine, and capturing the app-level not-found page. The tree's aggregate channels
+* (plus the not-found page's) are carried on the returned `RouterDef`'s phantom
+* `E`/`R` params.
+*/
+function makeRouter(root, options) {
+	const compiled = compile({
+		root,
+		notFound: options.notFound
+	});
+	return {
+		root,
+		notFound: options.notFound,
+		compiled,
+		httpApi: buildHttpApi(compiled.leaves)
+	};
+}
+//#endregion
+//#region src/route-tree.ts
+function makeRoute(segment, config) {
+	return {
+		_tag: "Route",
+		segment,
+		path: config.path ?? {},
+		query: config.query ?? {},
+		component: config.component
+	};
+}
+/**
+* Declares a layout. `component` is a {@link ComponentSlot} that splices the next
+* level down via `yield* Router.Outlet` (place it in the returned tree). The
+* router invokes it per render and provides that outlet, so `Router.Outlet` is
+* **excluded** from the layout's aggregate requirement channel; the subtree's
+* real channels are unioned in.
+*
+* @example
+* ```ts
+* Router.layout(
+*   {
+*     component: Component.gen(function* () {
+*       const outlet = yield* Router.Outlet;
+*       return yield* h.div({ class: "shell" }, [Header(), outlet]);
+*     }),
+*   },
+*   [Router.route("", { component: Home })],
+* );
+* ```
+*/
+function makeLayout(config, children) {
+	return {
+		_tag: "Layout",
+		component: config.component,
+		children
+	};
+}
+/**
+* Brand key marking a {@link ComponentSlot} as **preloadable** — a lazy slot
+* ({@link lazyComponent}) carries a `preload()` under this key. Internal to
+* `@weftui/router` (read by the client `navigate` to resolve a matched branch's
+* chunks before commit; see `pending-navigation.specs.md`); not public API.
+*
+* Declared `unique symbol` so it is usable as a computed interface key.
+*/
+const PreloadSlot = Symbol.for("@weftui/router/preload");
+/**
+* Reads the {@link PreloadSlot | preload} capability off a slot, or `undefined` for an
+* eager slot. Lets `navigate` await a matched branch's lazy chunks without knowing
+* which slots are lazy.
+*/
+function getPreload(slot) {
+	return slot[PreloadSlot];
+}
+/**
+* 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
+* 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
+* 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)),
+* });
+* ```
+*/
+function lazyComponent(load) {
+	let cached;
+	let resolved;
+	const preload = () => (cached ??= load()).then((component) => {
+		resolved = component;
+		return component;
+	});
+	const slot = () => resolved !== void 0 ? resolved({}) : Effect.gen(function* () {
+		return yield* (yield* Effect.promise(() => cached ??= load()))({});
+	});
+	return Object.assign(slot, { [PreloadSlot]: preload });
+}
+//#endregion
+//#region src/router-service.ts
+var Router = class extends Context.Tag("@weftui/router/Router")() {};
+/**
+* The injected outlet: the node a layout (or the server document shell) splices
+* to place the next level down. Provided per render by the router
+* (`Effect.provideService(layout.component({}), OutletTag, innerNode)`); a layout
+* 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
+* structurally by {@link makeLayout} / {@link makeRouter}, never inferred across
+* this DI boundary. Re-exported on the namespace as `Router.Outlet`.
+*/
+var OutletTag = class extends Context.Tag("@weftui/router/Outlet")() {};
+/** Picks the requested `fields` keys out of a decoded match record. */
+function pick(fields, record) {
+	const subset = {};
+	for (const key of Object.keys(fields)) subset[key] = record[key];
+	return subset;
+}
+/**
+* Reads the live match's **path params** for the requested `fields`. Snapshot
+* semantics — reads `yield* Router` then `currentMatch.get` — and returns 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}
+* (`source: "path"`) only when no route is matched. Re-exported as `Router.params`.
+*/
+function readParams(fields) {
+	return Effect.gen(function* () {
+		const match = yield* (yield* Router).currentMatch.get;
+		if (match._tag === "NotFound") return yield* Effect.fail(new RouterParamsError({
+			source: "path",
+			keys: Object.keys(fields)
+		}));
+		return pick(fields, match.path);
+	});
+}
+/**
+* Reads the live match's **query** for the requested `fields`. Same snapshot +
+* direct-read semantics as {@link readParams}, failing with a
+* {@link RouterParamsError} (`source: "query"`) only on a no-match. Re-exported as
+* `Router.query`.
+*/
+function readQuery(fields) {
+	return Effect.gen(function* () {
+		const match = yield* (yield* Router).currentMatch.get;
+		if (match._tag === "NotFound") return yield* Effect.fail(new RouterParamsError({
+			source: "query",
+			keys: Object.keys(fields)
+		}));
+		return pick(fields, match.query);
+	});
+}
+/**
+* Builds a reactive {@link Subscribable} of the picked `fields` from a `currentMatch`
+* Subscribable, reading the `path` or `query` side. Unlike {@link readParams} /
+* {@link readQuery} (snapshot accessors that fail on `NotFound`), the reactive form
+* is **resilient**: a `NotFound` match yields the empty subset (each field
+* `undefined`) rather than failing, so the stream stays live across navigations.
+*/
+function selectStream(currentMatch, fields, source) {
+	const select = (m) => pick(fields, m._tag === "Matched" ? m[source] : {});
+	return Subscribable.make({
+		get: Effect.map(currentMatch.get, select),
+		changes: Stream.map(currentMatch.changes, select)
+	});
+}
+/**
+* Reactive counterpart to {@link readParams}: a {@link Subscribable} of the live
+* match's **path params** for `fields`, derived from `currentMatch.changes`. It
+* re-emits on every navigation and stays live across `NotFound` (yielding the empty
+* subset), so a component can render `[(yield* Router.paramsStream(fields)).changes]`
+* and update in place even when the outlet keeps the same leaf mounted. Re-exported
+* as `Router.paramsStream`.
+*/
+function subscribeParams(fields) {
+	return Effect.map(Router, (router) => selectStream(router.currentMatch, fields, "path"));
+}
+/**
+* Reactive counterpart to {@link readQuery}: a {@link Subscribable} of the live
+* match's **query** for `fields`. Especially useful for query-only changes
+* (`setQuery` / `patchQuery`), which keep the same leaf mounted: a snapshot
+* `Router.query` would not update, but this stream does. Re-exported as
+* `Router.queryStream`.
+*/
+function subscribeQuery(fields) {
+	return Effect.map(Router, (router) => selectStream(router.currentMatch, fields, "query"));
+}
+/**
+* Reactive {@link Subscribable} of the client {@link NavState}. A component reads
+* `[(yield* Router.navigatingStream).changes]` to render pending UI during a
+* deferred-commit navigation (`pending-navigation.specs.md`). Re-exported as
+* `Router.navigatingStream`.
+*/
+const subscribeNavigating = Effect.map(Router, (router) => router.navigating);
+(function(_Router) {
+	_Router.route = makeRoute;
+	_Router.layout = makeLayout;
+	_Router.lazy = lazyComponent;
+	_Router.router = makeRouter;
+	_Router.Outlet = OutletTag;
+	_Router.params = readParams;
+	_Router.query = readQuery;
+	_Router.paramsStream = subscribeParams;
+	_Router.queryStream = subscribeQuery;
+	_Router.navigatingStream = subscribeNavigating;
+})(Router || (Router = {}));
+//#endregion
+//#region src/outlet.ts
+/** Substitutes `:name` placeholders in a pattern with encoded param values. */
+function substitute(pattern, params) {
+	return pattern.replace(/:([A-Za-z0-9_]+)/g, (_m, name) => encodeURIComponent(String(params[name])));
+}
+/** A dedupe key reused when this level is unchanged across a navigation (O2). */
+function keyOf(index, match) {
+	if (match._tag === "NotFound") return "\0notfound";
+	const chain = match.leaf.layoutChain;
+	if (index >= chain.length) return `leaf:${match.url}`;
+	const layout = chain[index];
+	return layout === void 0 ? `layout:${index}` : substitute(layout.patternPrefix, match.path);
+}
+/** Builds the `Renderable` for one nesting level of a match. */
+function renderLevel(def, router, index, match) {
+	if (match._tag === "NotFound") return def.compiled.notFound();
+	const chain = match.leaf.layoutChain;
+	const leafProps = {
+		path: match.path,
+		query: match.query
+	};
+	if (index >= chain.length) return match.leaf.component(leafProps);
+	const layout = chain[index];
+	if (layout === void 0) return match.leaf.component(leafProps);
+	const outlet = h.fragment([levelStream(def, router, index + 1)]);
+	return Effect.provideService(layout.component({}), Router.Outlet, outlet);
+}
+/**
+* The reactive stream for one nesting level: re-emits only when this level's
+* dedupe key changes, so unchanged ancestor layouts stay mounted while a deeper
+* level swaps (O2/O3). The DOM renderer treats the returned `Stream` as a
+* reactive child region.
+*/
+function levelStream(def, router, index) {
+	return pipe(router.currentMatch.changes, Stream.map((match) => [keyOf(index, match), match]), Stream.changesWith((a, b) => a[0] === b[0]), Stream.map(([, match]) => renderLevel(def, router, index, match)));
+}
+/**
+* The bare nested-outlet node for a router definition: a fragment whose single
+* reactive child is the level-0 stream. Used directly by the server renderer so
+* a `RouterNotFound` raised by a page escapes to the server's 404 handler.
+*/
+function outletNode(def) {
+	const stream = Stream.unwrap(Effect.map(Router, (router) => levelStream(def, router, 0)));
+	return h.fragment([stream]);
+}
+/**
+* The universal router root node. Wraps {@link outletNode} in the router's
+* internal not-found boundary so a `RouterNotFound` raised by a page renders the
+* configured `notFound` page in place (also covering client-side navigation). A
+* user `Boundary.catchTag("RouterNotFound", …)` placed inside a page is nearer and
+* therefore wins for that subtree.
+*
+* Server and client render the **same** `RouterApp` tree so hydration aligns. The
+* server no longer needs a status side-channel: it dispatches through
+* `HttpApiBuilder`, so a page-raised `RouterNotFound` (and a no-match) surface their
+* 404 through the platform request pipeline rather than a render-time callback.
+*
+* `RouterLive` is a scoped layer (it owns the popstate listener + link click
+* interceptor) and must outlive the mount, so provide it via a long-lived
+* `ManagedRuntime` rather than `Effect.provide` at the node level:
+*
+* ```ts
+* const runtime = ManagedRuntime.make(RouterLive(def));
+* runtime.runPromise(hydrate(RouterApp(def), root));
+* ```
+*/
+function RouterApp(def) {
+	return Boundary.catchTag({
+		tag: "RouterNotFound",
+		fallback: () => def.compiled.notFound()
+	}, [outletNode(def)]);
+}
+//#endregion
+export { buildHttpApi as a, RouterNotFound as c, notFound as d, getPreload as i, RouterParamsError as l, outletNode as n, compile as o, Router as r, leafRegistry as s, RouterApp as t, isRouterNotFound as u };

package/dist/{outlet-BBEjKu3z.d.ts → outlet-DbqTgkXa.d.ts}

@@ -1,4 +1,4 @@
-import { E as RouterNotFound, d as FieldsType, i as RouterDef, m as RouteNode, u as Fields, x as Router } from "./compile-C0JShTTR.js";
+import { D as RouterNotFound, S as Router, d as FieldsType, i as RouterDef, m as RouteNode, u as Fields } from "./compile-HOyeyWRy.js";
 import { Node } from "@weftui/core";
 
 //#region src/href.d.ts

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
-import { i as RouterDef, l as ComponentSlot } from "../compile-C0JShTTR.js";
+import { S as Router, i as RouterDef, l as ComponentSlot } from "../compile-HOyeyWRy.js";
 import { Effect, Layer } from "effect";
+import { AppRpcClientTag } from "@weftui/core";
 import { RpcGroup } from "@effect/rpc";
 
 //#region src/server/router-server.d.ts
@@ -19,7 +20,7 @@ declare namespace RouterServer {
    * registry) — `toWebHandler` serves it at `POST /_eui/rpc`, and an in-process
    * client over the same handlers resolves SSR boundaries in-process.
    */
-  interface RpcOptions {
+  export interface RpcOptions {
     /** The app's merged `RpcGroup` (pure Schema contract; shared with the client). */
     readonly group: RpcGroup.RpcGroup<any>;
     /** The server-only handler Layer (`group.toLayer(...)` ⊕ its dependencies). */
@@ -33,8 +34,16 @@ declare namespace RouterServer {
    * params), so the document may use either. Mirrors the route/layout `component` slot,
    * so it accepts both a plain thunk and a `Component.make` / `Component.gen` component.
    * `<!DOCTYPE html>` is prepended at serialize time.
+   *
+   * `context` is the render-time provide seam (spec:
+   * `ambient-context-propagation.specs.md`): an app-wide `Layer` provided to the
+   * document shell **and** every route/layout leaf. It is required exactly when the
+   * def carries residual app services ({@link AppServices} — its aggregate `R` minus
+   * the `Router` / `Router.Outlet` / `AppRpcClientTag` the router already threads) and
+   * disallowed otherwise, so a missing provide is a compile error and `rpc`-only /
+   * no-service apps stay unchanged (surfaced via {@link ContextOption} at each entry).
    */
-  interface Options {
+  export interface Options {
     /** The document shell slot; reads the app to splice via `yield* Router.Outlet`. */
     readonly document: ComponentSlot;
     /**
@@ -45,8 +54,33 @@ declare namespace RouterServer {
      */
     readonly rpc?: RpcOptions;
   }
+  /**
+   * The residual app services a caller must still provide through the {@link Options.context}
+   * seam: a def's aggregate requirement `R` **minus** the services the router already
+   * threads in per render — `Router` and `Router.Outlet` (provided by the outlet /
+   * document plumbing) and `AppRpcClientTag` (provided from the `rpc` option). When this
+   * resolves to `never` the app has no app-wide service to inject and `context` is disallowed.
+   */
+  export type AppServices<R> = Exclude<R, Router | Router.Outlet | AppRpcClientTag>;
+  /** 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 at each entry point: **required** (a
+   * `Layer` supplying every residual {@link AppServices}) when the def has statically
+   * known app-wide services, **absent** when it has none, and **optional** for a
+   * loosely-typed `RouterDef<any, any>` (residual services can't be tracked, so the
+   * seam is not forced). This makes a missing provide a compile error for a precisely
+   * typed def (AC2) while keeping no-service / loosely-typed apps unchanged (AC3).
+   */
+  export type ContextOption<R> = [AppServices<R>] extends [never] ? {
+    readonly context?: undefined;
+  } : IsAny<AppServices<R>> extends true ? {
+    readonly context?: Layer.Layer<any, never, never>;
+  } : {
+    readonly context: Layer.Layer<AppServices<R>, never, never>;
+  };
   /** The result of {@link render}. */
-  interface Rendered {
+  export interface Rendered {
     readonly html: string;
     readonly status: number;
   }
@@ -56,16 +90,16 @@ declare namespace RouterServer {
    * with `<!DOCTYPE html>` prepended and the status sourced from the platform
    * pipeline (200, or 404 for a no-match / page-raised `RouterNotFound`).
    */
-  function render(def: RouterDef, options: Options & {
+  export function render<R>(def: RouterDef<any, R>, options: Options & {
     readonly url: string;
-  }): Effect.Effect<Rendered, Error>;
+  } & ContextOption<R>): Effect.Effect<Rendered, Error>;
   /**
    * The platform web `fetch`-style handler `(Request) => Promise<Response>` that
    * dispatches through `HttpApiBuilder` and renders the matched route to
    * `text/html`. Suitable for bridging into a dev server (e.g. Vite) or any
    * Web-platform server.
    */
-  function toWebHandler(def: RouterDef, options: Options): (request: Request) => Promise<Response>;
+  export function toWebHandler<R>(def: RouterDef<any, R>, options: Options & ContextOption<R>): (request: Request) => Promise<Response>;
   /**
    * Streaming variant of {@link toWebHandler} (spec: "Streaming SSR" in
    * `router.specs.md`, SW1 … SW7). Same `Options`, memoized separately. Per
@@ -78,7 +112,8 @@ declare namespace RouterServer {
    * `RouterNotFound` stay real 404s; `POST /_eui/rpc` delegation is unchanged.
    * `render` and `toWebHandler` remain fully buffered.
    */
-  function toStreamingWebHandler(def: RouterDef, options: Options): (request: Request) => Promise<Response>;
+  export function toStreamingWebHandler<R>(def: RouterDef<any, R>, options: Options & ContextOption<R>): (request: Request) => Promise<Response>;
+  export {};
 }
 //#endregion
 export { RouterServer };