@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/defer.ts

@@ -0,0 +1,196 @@
+/**
+ * Deferred handle values — "decide synchronously, resolve late".
+ *
+ * A handle is pushed from code that holds `ctx` (a route/layout handler), so the
+ * decision to push lands before the handles stream seals. But the value often
+ * isn't known there — it may come from a deep async component far from the
+ * handler. `ctx.use(Handle).defer()` reserves the handle's slot now (synchronous,
+ * so ordering and the pre-seal timing hold) and returns a resolver with the SAME
+ * signature as the push: you call it later, anywhere in the render, with the same
+ * value you would have passed to the push.
+ *
+ *   const breadcrumb = ctx.use(Breadcrumbs);   // (item) => void  &  .defer()
+ *   const resolve = breadcrumb.defer({ timeoutMs: 5000, else: null });
+ *   // deep async component, far from ctx:
+ *   resolve({ label, href, content });          // identical call, just deferred
+ *
+ * Under the hood the reserved slot is a Promise the renderer `use()`s; RSC Flight
+ * streams it as a late row, so a deferred-aware consumer reading the handle
+ * (`useHandle`) sees that entry as a `Promise` until it resolves (see
+ * {@link DeferredHandleEntry}). The hazard that guards against bugs: a deferred
+ * slot whose resolver is never called would keep the Flight stream — and the HTTP
+ * response — open forever. So a deferred auto-resolves to `else` after `timeoutMs`
+ * (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is never called,
+ * degrading gracefully (and warning in dev) instead of hanging the request.
+ */
+
+/** Default auto-resolve window. Long enough for genuine deep async work, short
+ *  enough that a forgotten resolve does not hang the response indefinitely. */
+export const DEFAULT_DEFER_TIMEOUT_MS = 10_000;
+
+/** Options for `ctx.use(Handle).defer()`. */
+export interface DeferOptions<TData> {
+  /**
+   * Auto-resolve to `else` after this many ms if the resolver is never called,
+   * so a forgotten resolve cannot hold the Flight stream — and thus the HTTP
+   * response — open. Defaults to {@link DEFAULT_DEFER_TIMEOUT_MS}. `0` or
+   * `Infinity` disable the timeout intentionally (not recommended on a request
+   * path). Any other non-finite or negative value is treated as a mistake and
+   * falls back to the default rather than silently disabling the safety net.
+   * Named `timeoutMs` to match the router's `*Ms` duration convention.
+   */
+  timeoutMs?: number;
+  /**
+   * Value the slot resolves to if the timeout fires before the resolver is
+   * called. Defaults to `undefined` (the deferred item is skipped/empty). For
+   * renderable handle content, `null` is the usual graceful fallback, so the
+   * type admits `null` even when `TData` does not.
+   */
+  else?: TData | null;
+}
+
+/**
+ * The call signature shared by a handle push and the resolver returned by
+ * `.defer()`: a concrete value, a `Promise` of the value (Flight streams it as a
+ * late row), or a thunk returning a `Promise` (called immediately).
+ */
+export type HandlePushFn<TData> = (
+  data: TData | Promise<TData> | (() => Promise<TData>),
+) => void;
+
+/**
+ * The push function returned by `ctx.use(Handle)`. Call it to push a value now,
+ * or call `.defer()` to reserve the slot now and resolve the value later (e.g.
+ * from a deep async component) with a timeout safety net.
+ */
+export type HandlePush<TData> = HandlePushFn<TData> & {
+  /**
+   * Reserve this handle's slot synchronously and return a resolver that is
+   * push-equal: it takes the same argument shapes as the push (value, Promise, or
+   * thunk) and behaves identically. Two things the resolver adds over a direct
+   * push: a timeout (if the resolver is never called, the slot auto-resolves to
+   * `options.else` after `options.timeoutMs`; calling the resolver cancels it),
+   * and — on the action/revalidation path only — a thunk it runs does NOT
+   * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
+   * because a deferred resolver fires after the handler phase has closed.
+   *
+   * The reserved slot appears in the accumulated handle data as a pending
+   * `Promise` until it resolves (see {@link DeferredHandleEntry}); a
+   * deferred-aware consumer narrows thenable entries (`use()`/`await` + null
+   * check) before dereferencing.
+   */
+  defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
+};
+
+/**
+ * A handle entry a deferred-aware consumer may read from `useHandle`: either a
+ * resolved value, or a pending `Promise` that resolves to the value, to `else`,
+ * or (when no `else` was given) `undefined` on timeout. Reading code should treat
+ * thenable entries as such and narrow before dereferencing.
+ */
+export type DeferredHandleEntry<TData> =
+  | TData
+  | Promise<TData | null | undefined>;
+
+// Internal: a timeout-bounded { promise, resolve }. Not part of the public API
+// (the public surface is `ctx.use(Handle).defer()`); exported for `withDefer`
+// and unit tests only. Resolves to `T`, the `else` fallback, or `undefined`.
+export function createDeferred<T>(options?: {
+  timeoutMs?: number;
+  fallback?: T | null;
+}): {
+  promise: Promise<T | null | undefined>;
+  resolve: (value: T | null | undefined) => void;
+} {
+  let resolveInner!: (value: T | null | undefined) => void;
+  let settled = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const promise = new Promise<T | null | undefined>((resolve) => {
+    resolveInner = resolve;
+  });
+
+  const finish = (value: T | null | undefined): void => {
+    if (settled) return;
+    settled = true;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    resolveInner(value);
+  };
+
+  // 0 and Infinity are documented intentional disables. Any other non-finite or
+  // negative value (NaN, -1, a bad parsed config/env) is a mistake — fall back to
+  // the default rather than SILENTLY disabling the safety net, which would let a
+  // forgotten resolve hang the Flight stream and the response forever.
+  const requested = options?.timeoutMs ?? DEFAULT_DEFER_TIMEOUT_MS;
+  let ms: number;
+  if (requested === 0 || requested === Infinity) {
+    ms = requested;
+  } else if (Number.isFinite(requested) && requested > 0) {
+    ms = requested;
+  } else {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        `[rango] defer(): invalid timeout ${String(requested)}; using the ` +
+          `${DEFAULT_DEFER_TIMEOUT_MS}ms default so the safety net stays on. ` +
+          `Use 0 or Infinity to disable the timeout intentionally.`,
+      );
+    }
+    ms = DEFAULT_DEFER_TIMEOUT_MS;
+  }
+
+  if (ms > 0 && ms !== Infinity) {
+    timer = setTimeout(() => {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[rango] A deferred handle value was not resolved within ${ms}ms; ` +
+            `resolving to the fallback so the response can flush. Call the ` +
+            `resolver from the component that produces the value, or raise timeoutMs.`,
+        );
+      }
+      finish(options?.fallback);
+    }, ms);
+    // Don't let a pending timer alone keep a Node process alive (no-op on workerd).
+    (timer as { unref?: () => void }).unref?.();
+  }
+
+  return { promise, resolve: finish };
+}
+
+/**
+ * Attach `.defer()` to a handle push function. The deferred slot is reserved by
+ * pushing the deferred promise through the same push (so ordering, sealing, and
+ * Flight streaming all reuse the existing path); the returned resolver settles it.
+ */
+export function withDefer<TData>(push: HandlePushFn<TData>): HandlePush<TData> {
+  const handlePush = push as HandlePush<TData>;
+  // Safe to mutate push in place: each ctx.use(Handle) call (request-context.ts,
+  // loader-resolution.ts) builds a fresh closure, so .defer never leaks across
+  // handles or requests.
+  handlePush.defer = (options) => {
+    const deferred = createDeferred<TData>({
+      timeoutMs: options?.timeoutMs,
+      fallback: options?.else,
+    });
+    // Reserve the slot now by pushing the pending promise (the renderer use()s it).
+    push(deferred.promise as Promise<TData>);
+    // The resolver is push-equal: a thunk is invoked immediately (as push does)
+    // and a Promise is adopted by the reserved slot. Calling it settles the slot
+    // and cancels the timeout — the timeout only fires if it is never called.
+    const resolveSlot = deferred.resolve as (
+      value: TData | Promise<TData>,
+    ) => void;
+    return (data) => {
+      // The thunk runs without re-entering the push-callback scope a direct push
+      // thunk gets on the action/revalidation path (loader-resolution.ts): a
+      // deferred resolver fires from a deep component after the handler phase has
+      // closed, so there is no live deadlock-guard window to exempt.
+      resolveSlot(
+        typeof data === "function" ? (data as () => Promise<TData>)() : data,
+      );
+    };
+  };
+  return handlePush;
+}

package/src/deps/ssr.ts

@@ -1,2 +1 @@
-// Re-export @vitejs/plugin-rsc/ssr for internal use by virtual entries
 export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";

package/src/handle.ts

@@ -46,15 +46,10 @@ function defaultCollect<T>(segments: T[][]): T[] {
 // Used by useHandle() to recover collect when handle is deserialized from RSC prop.
 const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
 
-// Monotonic counter for runtime fallback ids (see createHandle). Module-scoped
-// and deterministic, so each createHandle() call gets a stable, unique id within
-// the process. Only used when no build id was injected (a bare unit test).
+// Monotonic counter for runtime fallback ids (see createHandle). Only used
+// when no build id was injected (a bare unit test).
 let runtimeHandleIdCounter = 0;
 
-/**
- * Look up a collect function from the registry by handle $$id.
- * Returns undefined if not registered (falls back to defaultCollect in useHandle).
- */
 export function getCollectFn(
   id: string,
 ): ((segments: unknown[][]) => unknown) | undefined {
@@ -127,8 +122,6 @@ export function createHandle<TData, TAccumulated = TData[]>(
     collect ??
     (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
 
-  // Register collect in module-level registry so useHandle() can recover it
-  // when the handle is deserialized from RSC props (toJSON strips collect).
   collectRegistry.set(
     handleId,
     collectFn as (segments: unknown[][]) => unknown,
@@ -140,9 +133,6 @@ export function createHandle<TData, TAccumulated = TData[]>(
   };
 }
 
-/**
- * Type guard to check if a value is a Handle.
- */
 export function isHandle(value: unknown): value is Handle<unknown, unknown> {
   return (
     typeof value === "object" &&

package/src/handles/MetaTags.tsx

@@ -97,24 +97,18 @@ function isPromise(value: unknown): value is Promise<unknown> {
   return value !== null && typeof value === "object" && "then" in value;
 }
 
-/**
- * Render a single meta descriptor as a React element.
- */
 function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
-  // charset
   if (hasCharSet(descriptor)) {
     return <meta key="charSet" charSet={descriptor.charSet} />;
   }
 
-  // title
   if (hasTitle(descriptor)) {
     return <title key="title">{descriptor.title}</title>;
   }
 
-  // name + content (description, viewport, etc.)
   if (hasNameContent(descriptor)) {
     return (
       <meta
@@ -125,7 +119,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // property + content (Open Graph, etc.)
   if (hasPropertyContent(descriptor)) {
     return (
       <meta
@@ -136,7 +129,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // http-equiv + content
   if (hasHttpEquivContent(descriptor)) {
     return (
       <meta
@@ -147,7 +139,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // JSON-LD structured data
   if (hasScriptLdJson(descriptor)) {
     const json = JSON.stringify(descriptor["script:ld+json"]);
     return (
@@ -159,7 +150,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // Custom tagName (meta or link with arbitrary attributes)
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
@@ -180,7 +170,6 @@ function renderMetaDescriptor(
     }
   }
 
-  // Fallback: treat as meta attributes
   return (
     <meta
       key={`meta-fallback-${index}`}
@@ -189,9 +178,6 @@ function renderMetaDescriptor(
   );
 }
 
-/**
- * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
- */
 function AsyncMetaTag({
   promise,
   index,

package/src/handles/breadcrumbs.ts

@@ -39,18 +39,29 @@ export interface BreadcrumbItem {
 /**
  * Collect function for Breadcrumbs handle.
  * Flattens segments in parent-to-child order with deduplication by href
- * (last item for each href wins).
+ * (last item for each href wins). Deferred slots (`ctx.use(Breadcrumbs).defer()`)
+ * arrive as pending Promise entries with no href yet; they are passed through by
+ * identity and excluded from the href dedup so concurrent deferred crumbs do not
+ * all collapse under a single `undefined` href.
  */
 function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
   const all = segments.flat();
-  const seen = new Map<string, number>();
 
+  const isResolvedItem = (item: unknown): item is BreadcrumbItem =>
+    item != null &&
+    typeof item === "object" &&
+    typeof (item as { then?: unknown }).then !== "function" &&
+    typeof (item as { href?: unknown }).href === "string";
+
+  const seen = new Map<string, number>();
   for (let i = 0; i < all.length; i++) {
-    seen.set(all[i].href, i);
+    if (isResolvedItem(all[i])) seen.set(all[i].href, i);
   }
 
-  // Return items in order, keeping only the last occurrence per href
-  return all.filter((item, index) => seen.get(item.href) === index);
+  // Deferred items bypass dedup (excluded via !isResolvedItem check).
+  return all.filter(
+    (item, index) => !isResolvedItem(item) || seen.get(item.href) === index,
+  );
 }
 
 /**

package/src/handles/meta.ts

@@ -35,9 +35,6 @@ import type {
   UnsetDescriptor,
 } from "../router/types.js";
 
-/**
- * Type guard for unset descriptor
- */
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -49,9 +46,6 @@ function isUnsetDescriptor(
   );
 }
 
-/**
- * Type guard for title descriptor (any form)
- */
 function isTitleDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
@@ -62,9 +56,6 @@ function isTitleDescriptor(
   );
 }
 
-/**
- * Type guard for title template descriptor
- */
 function isTitleTemplate(
   title: TitleDescriptor,
 ): title is { template: string; default: string } {
@@ -76,21 +67,13 @@ function isTitleTemplate(
   );
 }
 
-/**
- * Type guard for absolute title descriptor
- */
 function isAbsoluteTitle(
   title: TitleDescriptor,
 ): title is { absolute: string } {
   return typeof title === "object" && title !== null && "absolute" in title;
 }
 
-/**
- * Get a unique key for a meta descriptor for deduplication.
- * Returns undefined for descriptors that shouldn't be deduplicated.
- */
 function getMetaKey(descriptor: MetaDescriptor): string | undefined {
-  // Skip unset descriptors - they are processed separately
   if (isUnsetDescriptor(descriptor)) {
     return undefined;
   }
@@ -110,13 +93,10 @@ function getMetaKey(descriptor: MetaDescriptor): string | undefined {
     return `httpEquiv:${descriptor.httpEquiv}`;
   }
   if ("script:ld+json" in descriptor) {
-    // JSON-LD scripts can have multiple, don't dedupe by default
     return undefined;
   }
   if ("tagName" in descriptor) {
-    // For link tags, dedupe by rel if present
     if (descriptor.tagName === "link" && "rel" in descriptor) {
-      // Some link rels should be unique (canonical), others not (stylesheet)
       const uniqueRels = ["canonical", "icon", "apple-touch-icon"];
       if (uniqueRels.includes(descriptor.rel as string)) {
         return `link:${descriptor.rel}`;
@@ -136,9 +116,6 @@ const defaultMetaDescriptors: MetaDescriptor[] = [
   { name: "viewport", content: "width=device-width, initial-scale=1" },
 ];
 
-/**
- * Helper to add or replace a descriptor in the result array
- */
 function addOrReplace(
   result: MetaDescriptor[],
   keyToIndex: Map<string, number>,
@@ -155,9 +132,6 @@ function addOrReplace(
   }
 }
 
-/**
- * Helper to update indices after removing an element
- */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
   removedIndex: number,
@@ -169,17 +143,11 @@ function updateIndicesAfterRemoval(
   }
 }
 
-/**
- * Collect function for Meta handle.
- * Includes default meta descriptors, then deduplicates by key with later routes overriding earlier ones.
- * Supports title templates, absolute titles, and unset descriptors.
- */
 function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
   const result: MetaDescriptor[] = [];
   const keyToIndex = new Map<string, number>();
   let titleTemplate: string | undefined;
 
-  // Add defaults first so they can be overridden
   for (const descriptor of defaultMetaDescriptors) {
     const key = getMetaKey(descriptor);
     if (key !== undefined) {
@@ -190,7 +158,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Handle unset descriptors
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -202,14 +169,11 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle title descriptors with template/absolute support
       if (isTitleDescriptor(descriptor)) {
         const titleValue = descriptor.title;
 
         if (isTitleTemplate(titleValue)) {
-          // Store template for subsequent title descriptors in child segments
           titleTemplate = titleValue.template;
-          // Set the default title
           addOrReplace(
             result,
             keyToIndex,
@@ -220,7 +184,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         }
 
         if (isAbsoluteTitle(titleValue)) {
-          // Absolute title bypasses any template
           addOrReplace(
             result,
             keyToIndex,
@@ -230,7 +193,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           continue;
         }
 
-        // String title - apply template if one exists
         const finalTitle = titleTemplate
           ? titleTemplate.replace("%s", titleValue as string)
           : titleValue;
@@ -243,7 +205,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle all other descriptors
       const key = getMetaKey(descriptor);
       addOrReplace(result, keyToIndex, descriptor, key);
     }

package/src/host/cookie-handler.ts

@@ -1,9 +1,3 @@
-/**
- * Cookie Override Handler
- *
- * Manages cookie-based host override for development environments.
- */
-
 import type { HostOverrideConfig } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import { matchPattern, parseRequest } from "./pattern-matcher.js";
@@ -13,9 +7,6 @@ import {
   HostValidationError,
 } from "./errors.js";
 
-/**
- * Parse cookies from request
- */
 export function parseCookies(request: Request): Record<string, string> {
   const cookieHeader = request.headers.get("cookie");
   if (!cookieHeader) {
@@ -40,24 +31,15 @@ export function parseCookies(request: Request): Record<string, string> {
   return cookies;
 }
 
-/**
- * Get cookie value from request
- */
 export function getCookie(request: Request, name: string): string | undefined {
   const cookies = parseCookies(request);
   return cookies[name];
 }
 
-/**
- * Create Set-Cookie header to delete a cookie
- */
 export function createDeleteCookieHeader(name: string): string {
   return `${name}=; Max-Age=0; Path=/; Secure; HttpOnly`;
 }
 
-/**
- * Create error response with cookie deletion
- */
 export function createCookieErrorResponse(
   cookieName: string,
   message: string,
@@ -77,9 +59,6 @@ export function createCookieErrorResponse(
   );
 }
 
-/**
- * Check if current host is allowed to use override
- */
 export function isHostAllowed(
   request: Request,
   allowedHosts: string[],
@@ -95,12 +74,6 @@ export function isHostAllowed(
   return false;
 }
 
-/**
- * Handle cookie override logic
- *
- * Returns overridden hostname if valid, original hostname if no override.
- * Throws errors for invalid overrides.
- */
 export function handleCookieOverride(
   request: Request,
   config: HostOverrideConfig | undefined,
@@ -115,46 +88,37 @@ export function handleCookieOverride(
   const cookieValue = getCookie(request, cookieName);
   const { hostname: originalHostname } = parseRequest(request);
 
-  // No cookie - return original hostname
   if (!cookieValue) {
     return originalHostname;
   }
 
-  // Check if current host is allowed
   const allowed = isHostAllowed(request, allowedHosts);
 
-  // If not allowed, throw error
   if (!allowed) {
     throw new HostOverrideNotAllowedError(originalHostname, cookieName, {
       cause: { cookieValue, currentHost: originalHostname },
     });
   }
 
-  // If allowed and has custom validation, run it
   if (validate) {
     try {
       const validatedHostname = validate(request, cookieValue, input);
       return validatedHostname;
     } catch (error) {
-      // Wrap in HostValidationError
       const message = error instanceof Error ? error.message : String(error);
       throw new HostValidationError(message, error);
     }
   }
 
-  // Default validation - verify it's a valid hostname using URL constructor
   try {
-    // Try to construct a URL with the hostname to validate it
     const testUrl = new URL(`https://${cookieValue}`);
 
-    // Ensure the hostname matches what we provided (URL constructor normalizes it)
     if (testUrl.hostname !== cookieValue) {
       throw new InvalidHostnameError(cookieValue, {
         cause: { original: cookieValue, normalized: testUrl.hostname },
       });
     }
   } catch (error) {
-    // If URL constructor failed, throw InvalidHostnameError with cause
     if (error instanceof InvalidHostnameError) {
       throw error;
     }

package/src/host/errors.ts

@@ -4,16 +4,10 @@
  * All host router errors extend HostRouterError for easy instance checking.
  */
 
-/**
- * Error options with cause
- */
 interface ErrorOptions {
   cause?: unknown;
 }
 
-/**
- * Base error class for all host router errors
- */
 export class HostRouterError extends Error {
   cause?: unknown;
 
@@ -27,9 +21,6 @@ export class HostRouterError extends Error {
   }
 }
 
-/**
- * Error thrown when pattern validation fails
- */
 export class InvalidPatternError extends HostRouterError {
   constructor(pattern: string, reason: string, options?: ErrorOptions) {
     super(`Invalid pattern "${pattern}": ${reason}`, options);
@@ -38,9 +29,6 @@ export class InvalidPatternError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when cookie override is not allowed
- */
 export class HostOverrideNotAllowedError extends HostRouterError {
   constructor(currentHost: string, cookieName: string, options?: ErrorOptions) {
     super(
@@ -52,9 +40,6 @@ export class HostOverrideNotAllowedError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when cookie hostname is invalid
- */
 export class InvalidHostnameError extends HostRouterError {
   constructor(hostname: string, options?: ErrorOptions) {
     super(`Invalid hostname format: "${hostname}"`, options);
@@ -63,9 +48,6 @@ export class InvalidHostnameError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when custom validation fails
- */
 export class HostValidationError extends HostRouterError {
   constructor(message: string, cause?: unknown) {
     super(message, { cause });
@@ -74,9 +56,6 @@ export class HostValidationError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when no route matches
- */
 export class NoRouteMatchError extends HostRouterError {
   constructor(hostname: string, pathname: string, options?: ErrorOptions) {
     super(`No route matched for ${hostname}${pathname}`, options);
@@ -85,9 +64,6 @@ export class NoRouteMatchError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when handler type is invalid
- */
 export class InvalidHandlerError extends HostRouterError {
   constructor(handler: unknown, options?: ErrorOptions) {
     super(`Invalid handler type: ${typeof handler}`, options);

package/src/host/index.ts

@@ -20,6 +20,12 @@
  *   }
  * };
  * ```
+ *
+ * The host surface (`Handler`, `Middleware`, `match`, `HostOverrideConfig.validate`)
+ * types `input` as `RouterRequestInput<any>` by design: a host router fans out to
+ * heterogeneous sub-apps with differing env/vars shapes, so there is no single
+ * `TEnv`/`TVars` to thread through. `input.env`/`input.vars` are therefore `any`
+ * here; the typed env shape lives on each sub-app's `createRouter<TEnv>()`.
  */
 
 // Core router