npm - @rangojs/router - Versions diffs - 0.0.0-experimental.10 - Mend

@rangojs/router 0.0.0-experimental.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (172) hide show

package/CLAUDE.md +43 -0
package/README.md +19 -0
package/dist/bin/rango.js +227 -0
package/dist/vite/index.js +3039 -0
package/package.json +171 -0
package/skills/caching/SKILL.md +191 -0
package/skills/debug-manifest/SKILL.md +108 -0
package/skills/document-cache/SKILL.md +180 -0
package/skills/fonts/SKILL.md +165 -0
package/skills/hooks/SKILL.md +442 -0
package/skills/intercept/SKILL.md +190 -0
package/skills/layout/SKILL.md +213 -0
package/skills/links/SKILL.md +180 -0
package/skills/loader/SKILL.md +246 -0
package/skills/middleware/SKILL.md +202 -0
package/skills/mime-routes/SKILL.md +124 -0
package/skills/parallel/SKILL.md +228 -0
package/skills/prerender/SKILL.md +283 -0
package/skills/rango/SKILL.md +54 -0
package/skills/response-routes/SKILL.md +358 -0
package/skills/route/SKILL.md +173 -0
package/skills/router-setup/SKILL.md +346 -0
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +78 -0
package/skills/typesafety/SKILL.md +394 -0
package/src/__internal.ts +175 -0
package/src/bin/rango.ts +24 -0
package/src/browser/event-controller.ts +876 -0
package/src/browser/index.ts +18 -0
package/src/browser/link-interceptor.ts +121 -0
package/src/browser/lru-cache.ts +69 -0
package/src/browser/merge-segment-loaders.ts +126 -0
package/src/browser/navigation-bridge.ts +913 -0
package/src/browser/navigation-client.ts +165 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +600 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +346 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +53 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +120 -0
package/src/browser/react/location-state.ts +62 -0
package/src/browser/react/mount-context.ts +32 -0
package/src/browser/react/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +203 -0
package/src/browser/react/use-href.tsx +40 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +140 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +164 -0
package/src/browser/rsc-router.tsx +352 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/segment-structure-assert.ts +67 -0
package/src/browser/server-action-bridge.ts +762 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +478 -0
package/src/build/generate-manifest.ts +377 -0
package/src/build/generate-route-types.ts +828 -0
package/src/build/index.ts +36 -0
package/src/build/route-trie.ts +239 -0
package/src/cache/cache-scope.ts +563 -0
package/src/cache/cf/cf-cache-store.ts +428 -0
package/src/cache/cf/index.ts +19 -0
package/src/cache/document-cache.ts +340 -0
package/src/cache/index.ts +58 -0
package/src/cache/memory-segment-store.ts +150 -0
package/src/cache/memory-store.ts +253 -0
package/src/cache/types.ts +392 -0
package/src/client.rsc.tsx +83 -0
package/src/client.tsx +643 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +23 -0
package/src/debug.ts +233 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +295 -0
package/src/handle.ts +130 -0
package/src/handles/MetaTags.tsx +193 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/host/cookie-handler.ts +159 -0
package/src/host/errors.ts +97 -0
package/src/host/index.ts +56 -0
package/src/host/pattern-matcher.ts +214 -0
package/src/host/router.ts +330 -0
package/src/host/testing.ts +79 -0
package/src/host/types.ts +138 -0
package/src/host/utils.ts +25 -0
package/src/href-client.ts +202 -0
package/src/href-context.ts +33 -0
package/src/index.rsc.ts +121 -0
package/src/index.ts +165 -0
package/src/loader.rsc.ts +207 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/prerender/param-hash.ts +35 -0
package/src/prerender/store.ts +40 -0
package/src/prerender.ts +156 -0
package/src/reverse.ts +267 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +193 -0
package/src/route-definition.ts +1431 -0
package/src/route-map-builder.ts +242 -0
package/src/route-types.ts +220 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +158 -0
package/src/router/intercept-resolution.ts +387 -0
package/src/router/loader-resolution.ts +327 -0
package/src/router/manifest.ts +216 -0
package/src/router/match-api.ts +621 -0
package/src/router/match-context.ts +264 -0
package/src/router/match-middleware/background-revalidation.ts +236 -0
package/src/router/match-middleware/cache-lookup.ts +382 -0
package/src/router/match-middleware/cache-store.ts +276 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +281 -0
package/src/router/match-middleware/segment-resolution.ts +184 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +213 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.ts +791 -0
package/src/router/pattern-matching.ts +407 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +301 -0
package/src/router/segment-resolution.ts +1315 -0
package/src/router/trie-matching.ts +172 -0
package/src/router/types.ts +163 -0
package/src/router.gen.ts +6 -0
package/src/router.ts +2423 -0
package/src/rsc/handler.ts +1443 -0
package/src/rsc/helpers.ts +64 -0
package/src/rsc/index.ts +56 -0
package/src/rsc/nonce.ts +18 -0
package/src/rsc/types.ts +236 -0
package/src/segment-system.tsx +442 -0
package/src/server/context.ts +466 -0
package/src/server/handle-store.ts +229 -0
package/src/server/loader-registry.ts +174 -0
package/src/server/request-context.ts +554 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +171 -0
package/src/ssr/index.tsx +296 -0
package/src/theme/ThemeProvider.tsx +291 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/constants.ts +59 -0
package/src/theme/index.ts +58 -0
package/src/theme/theme-context.ts +70 -0
package/src/theme/theme-script.ts +152 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types.ts +1757 -0
package/src/urls.gen.ts +8 -0
package/src/urls.ts +1282 -0
package/src/use-loader.tsx +346 -0
package/src/vite/expose-action-id.ts +344 -0
package/src/vite/expose-handle-id.ts +209 -0
package/src/vite/expose-loader-id.ts +426 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/expose-prerender-handler-id.ts +429 -0
package/src/vite/index.ts +2068 -0
package/src/vite/package-resolution.ts +125 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +114 -0

package/src/components/DefaultDocument.tsx ADDED Viewed

@@ -0,0 +1,23 @@
+"use client";
+import type { ReactNode, ReactElement } from "react";
+import { MetaTags } from "../handles/MetaTags.js";
+/**
+ * Default document component that provides a basic HTML structure.
+ * Used when no custom document is provided to createRouter.
+ * Includes MetaTags for automatic charset, viewport, and route meta support.
+ *
+ * Uses suppressHydrationWarning on <html> because the theme script
+ * may modify class/style attributes before React hydrates.
+ */
+export function DefaultDocument({ children }: { children: ReactNode }): ReactElement {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/src/debug.ts ADDED Viewed

@@ -0,0 +1,233 @@
+/**
+ * Debug utilities for manifest inspection and comparison
+ */
+import type { EntryData } from "./server/context";
+/**
+ * Serialized entry for debug output
+ */
+export interface SerializedEntry {
+  id: string;
+  shortCode: string;
+  type: string;
+  parentShortCode: string | null;
+  pattern?: string;
+  hasLoader: boolean;
+  hasMiddleware: boolean;
+  hasErrorBoundary: boolean;
+  parallelCount: number;
+  interceptCount: number;
+}
+/**
+ * Serialized manifest structure
+ */
+export interface SerializedManifest {
+  routes: Record<string, SerializedEntry>;
+  layouts: Record<string, SerializedEntry>;
+  totalRoutes: number;
+  totalLayouts: number;
+}
+/**
+ * Serialize a manifest Map into a JSON-friendly structure
+ */
+export function serializeManifest(
+  manifest: Map<string, EntryData>
+): SerializedManifest {
+  const routes: Record<string, SerializedEntry> = {};
+  const layouts: Record<string, SerializedEntry> = {};
+  // Collect all entries including parents
+  const allEntries = new Map<string, EntryData>();
+  for (const [key, entry] of manifest.entries()) {
+    allEntries.set(key, entry);
+    // Walk up parent chain to collect all layouts
+    let parent = entry.parent;
+    while (parent) {
+      if (!allEntries.has(parent.id)) {
+        allEntries.set(parent.id, parent);
+      }
+      parent = parent.parent;
+    }
+  }
+  for (const [key, entry] of allEntries.entries()) {
+    const serialized: SerializedEntry = {
+      id: entry.id,
+      shortCode: entry.shortCode,
+      type: entry.type,
+      parentShortCode: entry.parent?.shortCode ?? null,
+      hasLoader: entry.loader?.length > 0,
+      hasMiddleware: entry.middleware?.length > 0,
+      hasErrorBoundary: entry.errorBoundary?.length > 0,
+      parallelCount: entry.parallel?.length ?? 0,
+      interceptCount: entry.intercept?.length ?? 0,
+    };
+    if (entry.type === "route" && "pattern" in entry) {
+      serialized.pattern = entry.pattern;
+    }
+    if (entry.type === "route") {
+      routes[key] = serialized;
+    } else if (entry.type === "layout" || entry.type === "cache") {
+      layouts[key] = serialized;
+    }
+  }
+  return {
+    routes,
+    layouts,
+    totalRoutes: Object.keys(routes).length,
+    totalLayouts: Object.keys(layouts).length,
+  };
+}
+/**
+ * Compare two manifests and return differences
+ */
+export function compareManifests(
+  oldManifest: SerializedManifest,
+  newManifest: SerializedManifest
+): {
+  addedRoutes: string[];
+  removedRoutes: string[];
+  changedRoutes: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }>;
+  addedLayouts: string[];
+  removedLayouts: string[];
+  changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }>;
+} {
+  const addedRoutes: string[] = [];
+  const removedRoutes: string[] = [];
+  const changedRoutes: Array<{ key: string; field: string; old: any; new: any }> = [];
+  const addedLayouts: string[] = [];
+  const removedLayouts: string[] = [];
+  const changedLayouts: Array<{ key: string; field: string; old: any; new: any }> = [];
+  // Compare routes
+  const oldRouteKeys = new Set(Object.keys(oldManifest.routes));
+  const newRouteKeys = new Set(Object.keys(newManifest.routes));
+  for (const key of newRouteKeys) {
+    if (!oldRouteKeys.has(key)) {
+      addedRoutes.push(key);
+    }
+  }
+  for (const key of oldRouteKeys) {
+    if (!newRouteKeys.has(key)) {
+      removedRoutes.push(key);
+    } else {
+      // Compare fields
+      const oldEntry = oldManifest.routes[key];
+      const newEntry = newManifest.routes[key];
+      for (const field of Object.keys(oldEntry) as (keyof SerializedEntry)[]) {
+        if (oldEntry[field] !== newEntry[field]) {
+          changedRoutes.push({
+            key,
+            field,
+            old: oldEntry[field],
+            new: newEntry[field],
+          });
+        }
+      }
+    }
+  }
+  // Compare layouts
+  const oldLayoutKeys = new Set(Object.keys(oldManifest.layouts));
+  const newLayoutKeys = new Set(Object.keys(newManifest.layouts));
+  for (const key of newLayoutKeys) {
+    if (!oldLayoutKeys.has(key)) {
+      addedLayouts.push(key);
+    }
+  }
+  for (const key of oldLayoutKeys) {
+    if (!newLayoutKeys.has(key)) {
+      removedLayouts.push(key);
+    } else {
+      const oldEntry = oldManifest.layouts[key];
+      const newEntry = newManifest.layouts[key];
+      for (const field of Object.keys(oldEntry) as (keyof SerializedEntry)[]) {
+        if (oldEntry[field] !== newEntry[field]) {
+          changedLayouts.push({
+            key,
+            field,
+            old: oldEntry[field],
+            new: newEntry[field],
+          });
+        }
+      }
+    }
+  }
+  return {
+    addedRoutes,
+    removedRoutes,
+    changedRoutes,
+    addedLayouts,
+    removedLayouts,
+    changedLayouts,
+  };
+}
+/**
+ * Format manifest diff as a human-readable string
+ */
+export function formatManifestDiff(
+  diff: ReturnType<typeof compareManifests>
+): string {
+  const lines: string[] = [];
+  if (diff.addedRoutes.length > 0) {
+    lines.push("Added routes:");
+    diff.addedRoutes.forEach((r) => lines.push(`  + ${r}`));
+  }
+  if (diff.removedRoutes.length > 0) {
+    lines.push("Removed routes:");
+    diff.removedRoutes.forEach((r) => lines.push(`  - ${r}`));
+  }
+  if (diff.changedRoutes.length > 0) {
+    lines.push("Changed routes:");
+    diff.changedRoutes.forEach((c) =>
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+    );
+  }
+  if (diff.addedLayouts.length > 0) {
+    lines.push("Added layouts:");
+    diff.addedLayouts.forEach((l) => lines.push(`  + ${l}`));
+  }
+  if (diff.removedLayouts.length > 0) {
+    lines.push("Removed layouts:");
+    diff.removedLayouts.forEach((l) => lines.push(`  - ${l}`));
+  }
+  if (diff.changedLayouts.length > 0) {
+    lines.push("Changed layouts:");
+    diff.changedLayouts.forEach((c) =>
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+    );
+  }
+  return lines.length > 0 ? lines.join("\n") : "No differences found";
+}

package/src/default-error-boundary.tsx ADDED Viewed

@@ -0,0 +1,88 @@
+import type { ReactNode } from "react";
+import type { ErrorBoundaryFallbackProps } from "./types.js";
+/**
+ * Default error boundary fallback component
+ *
+ * This is rendered when an error occurs and no custom error boundary
+ * is defined in the route tree. Shows a simple "Internal Server Error"
+ * message with the error details in development.
+ */
+export function DefaultErrorFallback({
+  error,
+}: ErrorBoundaryFallbackProps): ReactNode {
+  const isDev = process.env.NODE_ENV !== "production";
+  return (
+    <div
+      style={{
+        fontFamily: "system-ui, -apple-system, sans-serif",
+        padding: "2rem",
+        maxWidth: "600px",
+        margin: "2rem auto",
+      }}
+    >
+      <h1
+        style={{
+          color: "#dc2626",
+          fontSize: "1.5rem",
+          marginBottom: "1rem",
+        }}
+      >
+        Internal Server Error
+      </h1>
+      <p
+        style={{
+          color: "#374151",
+          marginBottom: "1rem",
+        }}
+      >
+        An unexpected error occurred while processing your request.
+      </p>
+      {isDev && (
+        <div
+          style={{
+            background: "#fef2f2",
+            border: "1px solid #fecaca",
+            borderRadius: "0.5rem",
+            padding: "1rem",
+            marginBottom: "1rem",
+          }}
+        >
+          <p
+            style={{
+              fontWeight: 600,
+              color: "#991b1b",
+              marginBottom: "0.5rem",
+            }}
+          >
+            {error.name}: {error.message}
+          </p>
+          {error.stack && (
+            <pre
+              style={{
+                fontSize: "0.75rem",
+                color: "#6b7280",
+                overflow: "auto",
+                whiteSpace: "pre-wrap",
+                wordBreak: "break-word",
+              }}
+            >
+              {error.stack}
+            </pre>
+          )}
+        </div>
+      )}
+      <a
+        href="/"
+        style={{
+          display: "inline-block",
+          color: "#2563eb",
+          textDecoration: "underline",
+        }}
+      >
+        Go to homepage
+      </a>
+    </div>
+  );
+}

package/src/deps/browser.ts ADDED Viewed

@@ -0,0 +1,8 @@
+// Re-export @vitejs/plugin-rsc/browser for internal use by virtual entries
+export {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+  createTemporaryReferenceSet,
+} from "@vitejs/plugin-rsc/browser";

package/src/deps/html-stream-client.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ // Re-export rsc-html-stream/client for internal use by virtual entries
2	+ export { rscStream } from "rsc-html-stream/client";

package/src/deps/html-stream-server.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ // Re-export rsc-html-stream/server for internal use by virtual entries
2	+ export { injectRSCPayload } from "rsc-html-stream/server";

package/src/deps/rsc.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/// <reference types="@vitejs/plugin-rsc/types" />
+// Re-export @vitejs/plugin-rsc/rsc for internal use by virtual entries
+export {
+  renderToReadableStream,
+  decodeReply,
+  createTemporaryReferenceSet,
+  loadServerAction,
+  decodeAction,
+  decodeFormState,
+} from "@vitejs/plugin-rsc/rsc";

package/src/deps/ssr.ts ADDED Viewed

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

package/src/errors.ts ADDED Viewed

@@ -0,0 +1,295 @@
+/**
+ * Custom error classes for RSC Router
+ *
+ * All errors include:
+ * - Descriptive names for easy identification
+ * - Cause property for structured debugging data
+ */
+/**
+ * Options for error construction
+ */
+interface ErrorOptions {
+  cause?: unknown;
+}
+/**
+ * Thrown when no route matches the requested pathname
+ */
+export class RouteNotFoundError extends Error {
+  name = "RouteNotFoundError" as const;
+  cause?: unknown;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Thrown when data is not found (e.g., product with ID doesn't exist)
+ * Use this in handlers/loaders to trigger the nearest notFoundBoundary
+ *
+ * @example
+ * ```typescript
+ * route("products.detail", async (ctx) => {
+ *   const product = await db.products.get(ctx.params.slug);
+ *   if (!product) throw new DataNotFoundError("Product not found");
+ *   return <ProductDetail product={product} />;
+ * });
+ * ```
+ */
+export class DataNotFoundError extends Error {
+  name = "DataNotFoundError" as const;
+  cause?: unknown;
+  constructor(message: string = "Not found", options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Convenience function to throw a DataNotFoundError
+ * Shorter syntax for common not-found scenarios
+ *
+ * @example
+ * ```typescript
+ * const product = await db.products.get(slug);
+ * if (!product) throw notFound("Product not found");
+ * // or simply:
+ * if (!product) throw notFound();
+ * ```
+ */
+export function notFound(message?: string): never {
+  throw new DataNotFoundError(message);
+}
+/**
+ * Thrown when middleware execution fails
+ */
+export class MiddlewareError extends Error {
+  name = "MiddlewareError" as const;
+  cause?: unknown;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Thrown when a route handler fails
+ */
+export class HandlerError extends Error {
+  name = "HandlerError" as const;
+  cause?: unknown;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Thrown when segment building fails
+ */
+export class BuildError extends Error {
+  name = "BuildError" as const;
+  cause?: unknown;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Thrown when a network request fails (server unreachable, no internet, etc.)
+ * This error triggers the root error boundary with retry capability.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(url);
+ * } catch (error) {
+ *   if (error instanceof TypeError) {
+ *     throw new NetworkError("Unable to connect to server", { cause: error });
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export class NetworkError extends Error {
+  name = "NetworkError" as const;
+  cause?: unknown;
+  /** The URL that failed to fetch */
+  url?: string;
+  /** Whether this was during an action, navigation, or revalidation */
+  operation?: "action" | "navigation" | "revalidation";
+  constructor(
+    message: string = "Network request failed",
+    options?: ErrorOptions & {
+      url?: string;
+      operation?: "action" | "navigation" | "revalidation";
+    }
+  ) {
+    super(message);
+    this.cause = options?.cause;
+    this.url = options?.url;
+    this.operation = options?.operation;
+  }
+}
+/**
+ * Check if an error is a network-level failure (server unreachable, no internet)
+ * These are typically TypeError from fetch when the network request itself fails.
+ */
+export function isNetworkError(error: unknown): boolean {
+  // NetworkError we throw ourselves
+  if (error instanceof NetworkError) {
+    return true;
+  }
+  // TypeError from fetch() when network fails (e.g., "Failed to fetch")
+  if (error instanceof TypeError) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("failed to fetch") ||
+      message.includes("network request failed") ||
+      message.includes("networkerror") ||
+      message.includes("load failed")
+    );
+  }
+  // DOMException with network-related names
+  if (error instanceof DOMException) {
+    return error.name === "NetworkError";
+  }
+  return false;
+}
+/**
+ * Structured error for JSON response routes.
+ * Thrown by handlers to return a typed error envelope with a specific HTTP status.
+ *
+ * Unlike standard Error, RouterError messages are always exposed to the client
+ * (the developer intentionally crafted them for consumers).
+ *
+ * @example
+ * ```typescript
+ * path("/products/:id", (ctx) => {
+ *   const product = products.find(p => p.id === ctx.params.id);
+ *   if (!product) throw new RouterError("NOT_FOUND", "Product not found", { status: 404 });
+ *   return product;
+ * }, { name: "productDetail" })
+ * ```
+ */
+export class RouterError extends Error {
+  name = "RouterError" as const;
+  code: string;
+  type?: string;
+  status: number;
+  cause?: unknown;
+  constructor(code: string, message: string, options?: {
+    status?: number;
+    type?: string;
+    cause?: unknown;
+  }) {
+    super(message);
+    this.code = code;
+    this.status = options?.status ?? 500;
+    this.type = options?.type;
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Thrown when route handler returns invalid type
+ */
+export class InvalidHandlerError extends Error {
+  name = "InvalidHandlerError" as const;
+  cause?: unknown;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+/**
+ * Internal invariant assertion for development-time checks
+ *
+ * @internal
+ * @param condition - Condition that must be true
+ * @param message - Error message to throw if condition is false
+ * @throws {Error} If condition is false
+ *
+ * @example
+ * ```typescript
+ * invariant(user !== null, 'User must be defined');
+ * invariant(node.type === 'layout', `Expected layout, got ${node.type}`);
+ * ```
+ */
+export function invariant(condition: any, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(`Invariant: ${message}`);
+  }
+}
+/**
+ * Sanitize errors for production - prevents leaking sensitive information
+ *
+ * SECURITY CRITICAL:
+ * - In production: NEVER send stack traces, file paths, or internal state
+ * - In development: Show full error details for debugging
+ * - ALWAYS consume error.stack to prevent memory leaks
+ *
+ * @param error - Error to sanitize
+ * @returns Response suitable for sending to client
+ */
+export function sanitizeError(error: unknown): Response {
+  // CRITICAL: Consume stack trace to prevent memory leaks
+  if (error && typeof error === "object" && "stack" in error) {
+    const _ = error.stack; // Force V8 to generate/consume stack trace
+  }
+  // Response objects are safe to return as-is
+  if (error instanceof Response) {
+    return error;
+  }
+  const isDev = (import.meta as any).env?.DEV ?? true;
+  if (isDev) {
+    // Development: Send full error details for debugging
+    const errorDetails = {
+      name: error instanceof Error ? error.name : "Error",
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      cause:
+        error && typeof error === "object" && "cause" in error
+          ? (error as any).cause
+          : undefined,
+    };
+    return new Response(JSON.stringify(errorDetails, null, 2), {
+      status: 500,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  }
+  // Production: Generic error only - NO internal details
+  // SECURITY: Never leak stack traces, file paths, or application state
+  return new Response("Internal Server Error", {
+    status: 500,
+    headers: {
+      "Content-Type": "text/plain",
+    },
+  });
+}