@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/context-var.ts

@@ -0,0 +1,156 @@
+/**
+ * Typed context variables for ctx.set() / ctx.get().
+ *
+ * createVar<T>() produces a typed token that handlers set and layouts/middleware
+ * read. The token carries a unique Symbol used as the property key on the
+ * per-request variables object — no build-time processing, no IDs.
+ *
+ * @example
+ * ```ts
+ * import { createVar } from "@rangojs/router";
+ *
+ * interface PaginationData { current: number; total: number }
+ * export const Pagination = createVar<PaginationData>();
+ *
+ * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * export const User = createVar<UserData>({ cache: false });
+ *
+ * // handler
+ * ctx.set(Pagination, { current: 1, total: 4 });
+ *
+ * // layout
+ * const pg = ctx.get(Pagination); // PaginationData | undefined
+ * ```
+ */
+
+export interface ContextVar<T> {
+  readonly __brand: "context-var";
+  readonly key: symbol;
+  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  readonly cache: boolean;
+  /** Phantom field to carry the type parameter. Never set at runtime. */
+  readonly __type?: T;
+}
+
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Setting or getting this var inside a cache() boundary or "use cache"
+   * function will throw. Use for inherently request-specific data (user
+   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
+/**
+ * Create a typed context variable token.
+ *
+ * The returned object is used with ctx.set(token, value) and ctx.get(token)
+ * for compile-time-checked data flow between handlers, layouts, and middleware.
+ */
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
+}
+
+/**
+ * Type guard: is the value a ContextVar token?
+ */
+export function isContextVar(value: unknown): value is ContextVar<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "context-var"
+  );
+}
+
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+) as any;
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
+/**
+ * Read a variable from the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export function contextGet(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): any {
+  if (typeof keyOrVar === "string") return variables[keyOrVar];
+  return variables[keyOrVar.key];
+}
+
+/** Keys that must never be used as string variable names */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
+/**
+ * Write a variable to the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export function contextSet(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+  value: any,
+  options?: ContextSetOptions,
+): void {
+  if (typeof keyOrVar === "string") {
+    if (FORBIDDEN_KEYS.has(keyOrVar)) {
+      throw new Error(
+        `ctx.set(): "${keyOrVar}" is a reserved key and cannot be used as a variable name.`,
+      );
+    }
+    variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
+  } else {
+    variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
+  }
+}

package/src/debug.ts

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -34,7 +34,7 @@ export interface SerializedManifest {
  * Serialize a manifest Map into a JSON-friendly structure
  */
 export function serializeManifest(
-  manifest: Map<string, EntryData>
+  manifest: Map<string, EntryData>,
 ): SerializedManifest {
   const routes: Record<string, SerializedEntry> = {};
   const layouts: Record<string, SerializedEntry> = {};
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 
@@ -92,7 +92,7 @@ export function serializeManifest(
  */
 export function compareManifests(
   oldManifest: SerializedManifest,
-  newManifest: SerializedManifest
+  newManifest: SerializedManifest,
 ): {
   addedRoutes: string[];
   removedRoutes: string[];
@@ -113,10 +113,20 @@ export function compareManifests(
 } {
   const addedRoutes: string[] = [];
   const removedRoutes: string[] = [];
-  const changedRoutes: Array<{ key: string; field: string; old: any; new: any }> = [];
+  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 }> = [];
+  const changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }> = [];
 
   // Compare routes
   const oldRouteKeys = new Set(Object.keys(oldManifest.routes));
@@ -191,7 +201,7 @@ export function compareManifests(
  * Format manifest diff as a human-readable string
  */
 export function formatManifestDiff(
-  diff: ReturnType<typeof compareManifests>
+  diff: ReturnType<typeof compareManifests>,
 ): string {
   const lines: string[] = [];
 
@@ -208,7 +218,7 @@ export function formatManifestDiff(
   if (diff.changedRoutes.length > 0) {
     lines.push("Changed routes:");
     diff.changedRoutes.forEach((c) =>
-      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
     );
   }
 
@@ -225,7 +235,7 @@ export function formatManifestDiff(
   if (diff.changedLayouts.length > 0) {
     lines.push("Changed layouts:");
     diff.changedLayouts.forEach((c) =>
-      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
     );
   }
 

package/src/errors.ts

@@ -22,6 +22,7 @@ export class RouteNotFoundError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, RouteNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -45,6 +46,7 @@ export class DataNotFoundError extends Error {
 
   constructor(message: string = "Not found", options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, DataNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -74,6 +76,7 @@ export class MiddlewareError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, MiddlewareError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -87,6 +90,7 @@ export class HandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, HandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -100,6 +104,7 @@ export class BuildError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, BuildError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -133,9 +138,10 @@ export class NetworkError extends Error {
     options?: ErrorOptions & {
       url?: string;
       operation?: "action" | "navigation" | "revalidation";
-    }
+    },
   ) {
     super(message);
+    Object.setPrototypeOf(this, NetworkError.prototype);
     this.cause = options?.cause;
     this.url = options?.url;
     this.operation = options?.operation;
@@ -194,12 +200,17 @@ export class RouterError extends Error {
   status: number;
   cause?: unknown;
 
-  constructor(code: string, message: string, options?: {
-    status?: number;
-    type?: string;
-    cause?: unknown;
-  }) {
+  constructor(
+    code: string,
+    message: string,
+    options?: {
+      status?: number;
+      type?: string;
+      cause?: unknown;
+    },
+  ) {
     super(message);
+    Object.setPrototypeOf(this, RouterError.prototype);
     this.code = code;
     this.status = options?.status ?? 500;
     this.type = options?.type;
@@ -207,6 +218,59 @@ export class RouterError extends Error {
   }
 }
 
+/**
+ * Thrown inside a Prerender or Static handler at build time to signal
+ * "skip this entry, log it, and continue with the rest."
+ *
+ * When thrown, the entry is excluded from the pre-render manifest
+ * but the build continues normally. Regular throws (non-Skip)
+ * stop all further pre-rendering and fail the build.
+ *
+ * @example
+ * ```typescript
+ * export const BlogPost = Prerender(
+ *   async () => allPosts.map(p => ({ slug: p.slug })),
+ *   async (ctx) => {
+ *     const post = await getPost(ctx.params.slug);
+ *     if (post.draft) throw new Skip(`"${ctx.params.slug}" is a draft`);
+ *     return <PostPage post={post} />;
+ *   },
+ * );
+ * ```
+ */
+export class Skip extends Error {
+  name = "Skip" as const;
+  cause?: unknown;
+
+  constructor(message: string = "Entry skipped", options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, Skip.prototype);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Type guard to check if a thrown value is a Skip signal.
+ */
+export function isSkip(value: unknown): value is Skip {
+  return value instanceof Skip;
+}
+
+/**
+ * Thrown by the partial updater when the server responds with a redirect payload
+ * that carries location state. Caught by navigate() to re-navigate to the
+ * redirect target with the server-set state merged into history.pushState.
+ *
+ * Not an Error subclass -- this is a control flow signal, not a failure.
+ */
+export class ServerRedirect {
+  readonly name = "ServerRedirect";
+  constructor(
+    public readonly url: string,
+    public readonly state: Record<string, unknown> | undefined,
+  ) {}
+}
+
 /**
  * Thrown when route handler returns invalid type
  */
@@ -216,6 +280,7 @@ export class InvalidHandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, InvalidHandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -262,7 +327,12 @@ export function sanitizeError(error: unknown): Response {
     return error;
   }
 
-  const isDev = (import.meta as any).env?.DEV ?? true;
+  // Vite replaces import.meta.env.DEV at compile time. The fallback covers
+  // non-Vite environments (plain Node, test runners without Vite transforms).
+  // SECURITY: fail closed — default to production when the environment is ambiguous.
+  const isDev =
+    (import.meta as any).env?.DEV ??
+    globalThis.process?.env?.NODE_ENV === "development";
 
   if (isDev) {
     // Development: Send full error details for debugging

package/src/handle.ts

@@ -29,7 +29,6 @@ export interface Handle<TData, TAccumulated = TData[]> {
    * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
    */
   readonly $$id: string;
-
 }
 
 /**
@@ -48,14 +47,16 @@ const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
  * 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 {
+export function getCollectFn(
+  id: string,
+): ((segments: unknown[][]) => unknown) | undefined {
   return collectRegistry.get(id);
 }
 
 /**
  * Create a handle definition for accumulating data across route segments.
  *
- * The $$id is auto-generated by the Vite exposeHandleId plugin based on
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
  * file path and export name. No manual naming required.
  *
  * @param collect - Optional collect function (default: flatten into array)
@@ -90,25 +91,29 @@ export function getCollectFn(id: string): ((segments: unknown[][]) => unknown) |
  */
 export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
-  __injectedId?: string
+  __injectedId?: string,
 ): Handle<TData, TAccumulated> {
   const handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV !== "production") {
-    console.warn(
+  if (!handleId && process.env.NODE_ENV === "development") {
+    throw new Error(
       "[rsc-router] Handle is missing $$id. " +
-        "Make sure the exposeHandleId Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)"
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the handle is exported with: export const MyHandle = createHandle(...)",
     );
   }
 
-  const collectFn = collect ??
+  const collectFn =
+    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).
   if (handleId) {
-    collectRegistry.set(handleId, collectFn as (segments: unknown[][]) => unknown);
+    collectRegistry.set(
+      handleId,
+      collectFn as (segments: unknown[][]) => unknown,
+    );
   }
 
   return {
@@ -128,3 +133,43 @@ export function isHandle(value: unknown): value is Handle<unknown, unknown> {
     (value as { __brand: unknown }).__brand === "handle"
   );
 }
+
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export function collectHandleData<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  data: Record<string, Record<string, unknown[]>>,
+  segmentOrder: string[],
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id);
+  if (!collectFn && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+        `Falling back to flat array. Ensure the handle module is imported so ` +
+        `createHandle() runs and registers the collect function.`,
+    );
+  }
+  const collect = (collectFn ??
+    (defaultCollect as unknown as (segments: unknown[][]) => unknown)) as (
+    segments: TData[][],
+  ) => TAccumulated;
+
+  const segmentData = data[handle.$$id];
+  if (!segmentData) return collect([]);
+
+  const segmentArrays: TData[][] = [];
+  for (const segmentId of segmentOrder) {
+    const entries = segmentData[segmentId];
+    if (entries && entries.length > 0) {
+      segmentArrays.push(entries as TData[]);
+    }
+  }
+  return collect(segmentArrays);
+}

package/src/handles/MetaTags.tsx

@@ -28,8 +28,9 @@ import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
 import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
-import { getSSRThemeConfig } from "../theme/theme-context.js";
+import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
+import { useNonce } from "../browser/react/nonce-context.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -40,30 +41,53 @@ function hasTitle(d: MetaDescriptorBase): d is { title: string } {
   return "title" in d && typeof (d as { title?: unknown }).title === "string";
 }
 
-function hasNameContent(d: MetaDescriptorBase): d is { name: string; content: string } {
-  return "name" in d && "content" in d &&
+function hasNameContent(
+  d: MetaDescriptorBase,
+): d is { name: string; content: string } {
+  return (
+    "name" in d &&
+    "content" in d &&
     typeof (d as { name?: unknown }).name === "string" &&
-    typeof (d as { content?: unknown }).content === "string";
+    typeof (d as { content?: unknown }).content === "string"
+  );
 }
 
-function hasPropertyContent(d: MetaDescriptorBase): d is { property: string; content: string } {
-  return "property" in d && "content" in d &&
+function hasPropertyContent(
+  d: MetaDescriptorBase,
+): d is { property: string; content: string } {
+  return (
+    "property" in d &&
+    "content" in d &&
     typeof (d as { property?: unknown }).property === "string" &&
-    typeof (d as { content?: unknown }).content === "string";
+    typeof (d as { content?: unknown }).content === "string"
+  );
 }
 
-function hasHttpEquivContent(d: MetaDescriptorBase): d is { httpEquiv: string; content: string } {
-  return "httpEquiv" in d && "content" in d &&
+function hasHttpEquivContent(
+  d: MetaDescriptorBase,
+): d is { httpEquiv: string; content: string } {
+  return (
+    "httpEquiv" in d &&
+    "content" in d &&
     typeof (d as { httpEquiv?: unknown }).httpEquiv === "string" &&
-    typeof (d as { content?: unknown }).content === "string";
+    typeof (d as { content?: unknown }).content === "string"
+  );
 }
 
-function hasScriptLdJson(d: MetaDescriptorBase): d is { "script:ld+json": object } {
+function hasScriptLdJson(
+  d: MetaDescriptorBase,
+): d is { "script:ld+json": object } {
   return "script:ld+json" in d;
 }
 
-function hasTagName(d: MetaDescriptorBase): d is { tagName: "meta" | "link"; [name: string]: string } {
-  return "tagName" in d && ((d as { tagName?: unknown }).tagName === "meta" || (d as { tagName?: unknown }).tagName === "link");
+function hasTagName(
+  d: MetaDescriptorBase,
+): d is { tagName: "meta" | "link"; [name: string]: string } {
+  return (
+    "tagName" in d &&
+    ((d as { tagName?: unknown }).tagName === "meta" ||
+      (d as { tagName?: unknown }).tagName === "link")
+  );
 }
 
 /**
@@ -78,7 +102,7 @@ function isPromise(value: unknown): value is Promise<unknown> {
  */
 function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
-  index: number
+  index: number,
 ): React.ReactNode {
   // charset
   if (hasCharSet(descriptor)) {
@@ -139,21 +163,42 @@ function renderMetaDescriptor(
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
-      return <link key={`link-${index}`} {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)} />;
+      return (
+        <link
+          key={`link-${index}`}
+          {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)}
+        />
+      );
     }
     if (tagName === "meta") {
-      return <meta key={`meta-${index}`} {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+      return (
+        <meta
+          key={`meta-${index}`}
+          {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)}
+        />
+      );
     }
   }
 
   // Fallback: treat as meta attributes
-  return <meta key={`meta-fallback-${index}`} {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+  return (
+    <meta
+      key={`meta-fallback-${index}`}
+      {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)}
+    />
+  );
 }
 
 /**
  * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
  */
-function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>; index: number }): React.ReactNode {
+function AsyncMetaTag({
+  promise,
+  index,
+}: {
+  promise: Promise<MetaDescriptorBase>;
+  index: number;
+}): React.ReactNode {
   const resolved = use(promise);
   return renderMetaDescriptor(resolved, index);
 }
@@ -172,19 +217,27 @@ function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>
  */
 export function MetaTags(): React.ReactNode {
   const descriptors = useHandle(Meta) as MetaDescriptor[];
-  const themeConfig = getSSRThemeConfig();
+  const themeConfig = useThemeContext()?.config ?? null;
+  const nonce = useNonce();
 
   return (
     <>
       {/* Theme script must be first to prevent FOUC */}
       {themeConfig && (
         <script
+          nonce={nonce}
           dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
         />
       )}
       {descriptors.map((descriptor, index) => {
         if (isPromise(descriptor)) {
-          return <AsyncMetaTag key={`async-${index}`} promise={descriptor} index={index} />;
+          return (
+            <AsyncMetaTag
+              key={`async-${index}`}
+              promise={descriptor}
+              index={index}
+            />
+          );
         }
         return renderMetaDescriptor(descriptor, index);
       })}