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

@rangojs/router 0.0.0-experimental.2

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 (155) hide show

package/CLAUDE.md +7 -0
package/README.md +19 -0
package/dist/vite/index.js +1298 -0
package/package.json +140 -0
package/skills/caching/SKILL.md +319 -0
package/skills/document-cache/SKILL.md +152 -0
package/skills/hooks/SKILL.md +359 -0
package/skills/intercept/SKILL.md +292 -0
package/skills/layout/SKILL.md +216 -0
package/skills/loader/SKILL.md +365 -0
package/skills/middleware/SKILL.md +442 -0
package/skills/parallel/SKILL.md +255 -0
package/skills/route/SKILL.md +141 -0
package/skills/router-setup/SKILL.md +403 -0
package/skills/theme/SKILL.md +54 -0
package/skills/typesafety/SKILL.md +352 -0
package/src/__mocks__/version.ts +6 -0
package/src/__tests__/component-utils.test.ts +76 -0
package/src/__tests__/route-definition.test.ts +63 -0
package/src/__tests__/urls.test.tsx +436 -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 +893 -0
package/src/browser/navigation-client.ts +162 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +559 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +275 -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/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +178 -0
package/src/browser/react/use-href.tsx +208 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-navigation.ts +150 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +164 -0
package/src/browser/rsc-router.tsx +353 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/server-action-bridge.ts +747 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +464 -0
package/src/cache/__tests__/document-cache.test.ts +522 -0
package/src/cache/__tests__/memory-segment-store.test.ts +487 -0
package/src/cache/__tests__/memory-store.test.ts +484 -0
package/src/cache/cache-scope.ts +565 -0
package/src/cache/cf/__tests__/cf-cache-store.test.ts +428 -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 +387 -0
package/src/client.rsc.tsx +88 -0
package/src/client.tsx +621 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +23 -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 +259 -0
package/src/handle.ts +120 -0
package/src/handles/MetaTags.tsx +193 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/href-client.ts +128 -0
package/src/href-context.ts +33 -0
package/src/href.ts +177 -0
package/src/index.rsc.ts +79 -0
package/src/index.ts +87 -0
package/src/loader.rsc.ts +204 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +198 -0
package/src/route-definition.ts +1371 -0
package/src/route-map-builder.ts +146 -0
package/src/route-types.ts +198 -0
package/src/route-utils.ts +89 -0
package/src/router/__tests__/match-context.test.ts +104 -0
package/src/router/__tests__/match-pipelines.test.ts +537 -0
package/src/router/__tests__/match-result.test.ts +566 -0
package/src/router/__tests__/on-error.test.ts +935 -0
package/src/router/__tests__/pattern-matching.test.ts +577 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +158 -0
package/src/router/loader-resolution.ts +326 -0
package/src/router/manifest.ts +138 -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 +261 -0
package/src/router/match-middleware/cache-store.ts +266 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +268 -0
package/src/router/match-middleware/segment-resolution.ts +174 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +214 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.test.ts +1355 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +272 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +299 -0
package/src/router/types.ts +96 -0
package/src/router.ts +3876 -0
package/src/rsc/__tests__/helpers.test.ts +175 -0
package/src/rsc/handler.ts +1060 -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 +237 -0
package/src/segment-system.tsx +456 -0
package/src/server/__tests__/request-context.test.ts +171 -0
package/src/server/context.ts +417 -0
package/src/server/handle-store.ts +230 -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 +146 -0
package/src/ssr/__tests__/ssr-handler.test.tsx +188 -0
package/src/ssr/index.tsx +234 -0
package/src/theme/ThemeProvider.tsx +291 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/__tests__/theme.test.ts +120 -0
package/src/theme/constants.ts +55 -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 +1561 -0
package/src/urls.ts +726 -0
package/src/use-loader.tsx +346 -0
package/src/vite/__tests__/expose-loader-id.test.ts +117 -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 +357 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/index.ts +787 -0
package/src/vite/package-resolution.ts +125 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +109 -0

package/src/component-utils.ts ADDED Viewed

@@ -0,0 +1,76 @@
+/**
+ * Component utilities for RSC
+ *
+ * Helpers for working with React Server Components and client components.
+ */
+import type { ComponentType } from "react";
+/**
+ * Symbol used by React to mark client component references.
+ * When a file has "use client" directive, the bundler transforms the exports
+ * to include this symbol on $$typeof.
+ */
+const CLIENT_REFERENCE = Symbol.for("react.client.reference");
+/**
+ * Check if a component is a client component (has "use client" directive).
+ *
+ * Client components are marked by the bundler with:
+ * - $$typeof: Symbol.for("react.client.reference")
+ * - $$id: string (module identifier)
+ *
+ * @param component - The component to check
+ * @returns true if the component has client reference marker
+ *
+ * @example
+ * ```typescript
+ * import { MyComponent } from "./my-component"; // has "use client"
+ *
+ * if (!isClientComponent(MyComponent)) {
+ *   throw new Error("MyComponent must be a client component");
+ * }
+ * ```
+ */
+export function isClientComponent(
+  component: ComponentType<unknown> | unknown
+): boolean {
+  if (typeof component !== "function") {
+    return false;
+  }
+  const withMeta = component as { $$typeof?: symbol };
+  return withMeta.$$typeof === CLIENT_REFERENCE;
+}
+/**
+ * Assert that a component is a client component.
+ * Throws a descriptive error if not.
+ *
+ * @param component - The component to check
+ * @param name - Name to use in error message (e.g., "document")
+ * @throws Error if the component is not a client component
+ */
+export function assertClientComponent(
+  component: ComponentType<unknown> | unknown,
+  name: string
+): asserts component is ComponentType<unknown> {
+  if (typeof component !== "function") {
+    throw new Error(
+      `${name} must be a client component function with "use client" directive. ` +
+        `Make sure to pass the component itself, not a JSX element: ` +
+        `${name}: My${capitalize(name)} (correct) vs ${name}: <My${capitalize(name)} /> (incorrect)`
+    );
+  }
+  if (!isClientComponent(component)) {
+    throw new Error(
+      `${name} must be a client component with "use client" directive at the top of the file. ` +
+        `Server components cannot be used as the ${name} because their function reference ` +
+        `cannot be serialized in the RSC payload. Add "use client" to your ${name} file.`
+    );
+  }
+}
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

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 createRSCRouter.
+ * 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/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,259 @@
+/**
+ * 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;
+}
+/**
+ * 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",
+    },
+  });
+}

package/src/handle.ts ADDED Viewed

@@ -0,0 +1,120 @@
+/**
+ * Handle definition for accumulating data across route segments.
+ *
+ * Handles allow server-side route handlers to pass accumulated data to client
+ * components. Unlike loaders (which fetch data for specific routes), handles
+ * accumulate data across all matched route segments.
+ *
+ * @example
+ * ```ts
+ * // Define a handle (name auto-generated from file + export)
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ *
+ * // Use in handler
+ * const push = ctx.use(Breadcrumbs);
+ * push({ label: "Home", href: "/" });
+ *
+ * // Consume on client
+ * const crumbs = useHandle(Breadcrumbs);
+ * ```
+ */
+export interface Handle<TData, TAccumulated = TData[]> {
+  /**
+   * Brand to distinguish handles from loaders in ctx.use()
+   */
+  readonly __brand: "handle";
+  /**
+   * Auto-generated unique ID for this handle (used as key in storage)
+   * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
+   */
+  readonly $$id: string;
+  /**
+   * Collect function to transform segment data into final value.
+   * Receives array of arrays - each inner array contains values pushed
+   * by one segment, ordered parent-to-child.
+   *
+   * @param segments - Array of segment data arrays, e.g. [[a, b], [c], [d, e]]
+   * @returns The accumulated value
+   */
+  readonly collect: (segments: TData[][]) => TAccumulated;
+}
+/**
+ * Default collect function that flattens segment arrays into a single array.
+ */
+function defaultCollect<T>(segments: T[][]): T[] {
+  return segments.flat();
+}
+/**
+ * Create a handle definition for accumulating data across route segments.
+ *
+ * The $$id is auto-generated by the Vite exposeHandleId plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * @param collect - Optional collect function (default: flatten into array)
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: flatten into array
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Result type: BreadcrumbItem[]
+ *
+ * // Custom: last value wins
+ * export const PageTitle = createHandle<string, string>(
+ *   (segments) => segments.flat().at(-1) ?? "Default Title"
+ * );
+ * // Result type: string
+ *
+ * // Custom: object merge
+ * export const Meta = createHandle<Partial<MetaTags>, MetaTags>(
+ *   (segments) => Object.assign({ robots: "index,follow" }, ...segments.flat())
+ * );
+ * // Result type: MetaTags
+ *
+ * // Custom: dedupe by href
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ *   (segments) => {
+ *     const all = segments.flat();
+ *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
+ *   }
+ * );
+ * ```
+ */
+export function createHandle<TData, TAccumulated = TData[]>(
+  collect?: (segments: TData[][]) => TAccumulated,
+  __injectedId?: string
+): Handle<TData, TAccumulated> {
+  const handleId = __injectedId ?? "";
+  if (!handleId && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rsc-router] Handle is missing $$id. " +
+        "Make sure the exposeHandleId Vite plugin is enabled and " +
+        "the handle is exported with: export const MyHandle = createHandle(...)"
+    );
+  }
+  return {
+    __brand: "handle" as const,
+    $$id: handleId,
+    collect:
+      collect ??
+      (defaultCollect as unknown as (segments: TData[][]) => TAccumulated),
+  };
+}
+/**
+ * Type guard to check if a value is a Handle.
+ */
+export function isHandle(value: unknown): value is Handle<unknown, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "handle"
+  );
+}