@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/errors.ts

@@ -1,5 +1,5 @@
 /**
- * Custom error classes for RSC Router
+ * Custom error classes for Rango
  *
  * All errors include:
  * - Descriptive names for easy identification
@@ -27,6 +27,17 @@ export class RouteNotFoundError extends Error {
   }
 }
 
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails.
+export function isRouteNotFoundError(
+  error: unknown,
+): error is RouteNotFoundError {
+  return (
+    error instanceof RouteNotFoundError ||
+    (error instanceof Error && error.name === "RouteNotFoundError")
+  );
+}
+
 /**
  * Thrown when data is not found (e.g., product with ID doesn't exist)
  * Use this in handlers/loaders to trigger the nearest notFoundBoundary
@@ -109,6 +120,24 @@ export class BuildError extends Error {
   }
 }
 
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export class DslContextError extends Error {
+  name = "DslContextError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, DslContextError.prototype);
+    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.
@@ -196,7 +225,6 @@ export function isNetworkError(error: unknown): boolean {
 export class RouterError extends Error {
   name = "RouterError" as const;
   code: string;
-  type?: string;
   status: number;
   cause?: unknown;
 
@@ -205,7 +233,6 @@ export class RouterError extends Error {
     message: string,
     options?: {
       status?: number;
-      type?: string;
       cause?: unknown;
     },
   ) {
@@ -213,7 +240,6 @@ export class RouterError extends Error {
     Object.setPrototypeOf(this, RouterError.prototype);
     this.code = code;
     this.status = options?.status ?? 500;
-    this.type = options?.type;
     this.cause = options?.cause;
   }
 }

package/src/escape-script.ts

@@ -0,0 +1,52 @@
+/**
+ * Escape a JSON (or JSON-derived) string for safe embedding inside an HTML
+ * <script> element via dangerouslySetInnerHTML. Without this a value containing
+ * "</script>" closes the tag early — the rest of the page leaks as raw HTML, and
+ * in an executable script the trailing content runs. Escaping "<" defeats the
+ * early close; ">" and "&" are escaped for completeness so the serialized payload
+ * can never form HTML syntax. The result is still valid JSON and a valid JS
+ * string literal (\uXXXX escapes are legal in both) and re-parses identically.
+ *
+ * Used by every site that interpolates JSON.stringify(...) into inline <script>
+ * content: the JSON-LD meta descriptors (handles/MetaTags) and the FOUC theme
+ * init script (theme/theme-script).
+ */
+export function escapeJsonForScript(json: string): string {
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+}
+
+/**
+ * Escape an inline <script> body so it cannot terminate or corrupt the document.
+ * Two sequences are rewritten, each via a JS escape that is valid in string,
+ * template, regex (including the `u`/`v` flags), and JSON contexts — so the body
+ * still parses identically as code AND as JSON (application/json, ld+json):
+ * - "</script" -> "<\/script": stops a literal close tag inside the body from
+ *   ending the element early. `\/` is a valid JSON escape and a valid regex escape.
+ * - "<!--": the "!" (U+0021) is emitted as a unicode escape (see the replacement
+ *   string below), so the literal "<!--" token never reaches the HTML parser. A
+ *   literal "<!--" puts the parser into the "script data escaped" state and a
+ *   following "<script" into "script data DOUBLE escaped", where the real
+ *   "</script>" no longer closes the element — `var x = "<!--<script>"` would
+ *   swallow the rest of the document. The unicode-escape form decodes back to "!"
+ *   in string/template/JSON/regex contexts, unlike "\!" (invalid JSON, invalid
+ *   /u-regex escape).
+ * Real operators such as `a < b` and `a && b` are untouched (unlike
+ * escapeJsonForScript, which \u-escapes every "<", "&", ">").
+ *
+ * GUARANTEE / LIMITATION: value-preserving for the contexts where these sequences
+ * legitimately appear — string/template literals, regexes (incl. `u`/`v`), and
+ * JSON. It is NOT source-text-preserving (e.g. String.raw`</script>` sees the
+ * extra backslash), and it cannot rewrite "</script"/"<!--" that appear as bare
+ * code (a legacy `<!--` line comment, or `</script` outside any literal) — neither
+ * occurs in valid script payloads. Not a general sanitizer for arbitrary UNTRUSTED
+ * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
+ * inlining it as code.
+ *
+ * Used by the Script handle's <Scripts> renderer for inline `children`.
+ */
+export function escapeScriptBody(js: string): string {
+  return js.replace(/<!--/g, "<\\u0021--").replace(/<\/(script)/gi, "<\\/$1");
+}

package/src/handle.ts

@@ -1,3 +1,6 @@
+import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
+
 /**
  * Handle definition for accumulating data across route segments.
  *
@@ -7,8 +10,11 @@
  *
  * @example
  * ```ts
- * // Define a handle (name auto-generated from file + export)
- * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Define a handle (name auto-generated from file + export).
+ * // Default collect is the identity: one array per segment that pushed.
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat(), // opt into a single flat list
+ * );
  *
  * // Use in handler
  * const push = ctx.use(Breadcrumbs);
@@ -18,7 +24,7 @@
  * const crumbs = useHandle(Breadcrumbs);
  * ```
  */
-export interface Handle<TData, TAccumulated = TData[]> {
+export interface Handle<TData, TAccumulated = TData[][]> {
   /**
    * Brand to distinguish handles from loaders in ctx.use()
    */
@@ -32,10 +38,13 @@ export interface Handle<TData, TAccumulated = TData[]> {
 }
 
 /**
- * Default collect function that flattens segment arrays into a single array.
+ * Default collect: pass the per-segment data through as-is — one array per segment
+ * that pushed, in segment order. Lossless, so a consumer can tell which/how-many
+ * segments contributed. Callers that want a single flat list opt in with
+ * `createHandle((segments) => segments.flat())`.
  */
-function defaultCollect<T>(segments: T[][]): T[] {
-  return segments.flat();
+function defaultCollect<T>(segments: T[][]): T[][] {
+  return segments;
 }
 
 // Module-level registry mapping $$id to collect functions.
@@ -43,10 +52,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>();
 
-/**
- * Look up a collect function from the registry by handle $$id.
- * Returns undefined if not registered (falls back to defaultCollect in useHandle).
- */
+// Monotonic counter for runtime fallback ids (see createHandle). Only used
+// when no build id was injected (a bare unit test).
+let runtimeHandleIdCounter = 0;
+
 export function getCollectFn(
   id: string,
 ): ((segments: unknown[][]) => unknown) | undefined {
@@ -59,13 +68,22 @@ export function getCollectFn(
  * 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)
+ * @param collect - Optional collect function. Default: pass the per-segment data
+ *   through as-is (one array per segment that pushed, in segment order). Lossless,
+ *   so a consumer can tell which/how-many segments contributed. Opt into a single
+ *   flat list with `(segments) => segments.flat()`.
  * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
  *
  * @example
  * ```ts
- * // Default: flatten into array
- * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Default: per-segment grouping, as-is
+ * export const Pushed = createHandle<string>();
+ * // Result type: string[][]  (e.g. [["a"], ["b", "c"]])
+ *
+ * // Opt into a single flat list
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat()
+ * );
  * // Result type: BreadcrumbItem[]
  *
  * // Custom: last value wins
@@ -80,8 +98,9 @@ export function getCollectFn(
  * );
  * // Result type: MetaTags
  *
- * // Custom: dedupe by href
- * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ * // Custom: dedupe by href (TAccumulated must be given — a custom collect that
+ * // returns a flat array no longer matches the default TData[][])
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
  *   (segments) => {
  *     const all = segments.flat();
  *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
@@ -89,32 +108,40 @@ export function getCollectFn(
  * );
  * ```
  */
-export function createHandle<TData, TAccumulated = TData[]>(
+export function createHandle<TData, TAccumulated = TData[][]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
-  const handleId = __injectedId ?? "";
+  let handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rsc-router] Handle is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)",
-    );
+  // No build-injected id. Under a test runner: fall back to a synthetic id so the
+  // collect registers below and the handle is exercisable in tests (useHandle,
+  // collectHandle, renderRoute's `handles` run the REAL collect). Otherwise (dev
+  // or a real build) it means an UNSUPPORTED handler shape the plugin skipped —
+  // fail loud. The rich, stack-parsing diagnostic stays behind the NODE_ENV check
+  // so a production build folds it away and tree-shakes missing-id-error.ts out,
+  // shipping the small throw instead. isUnderTestRunner() is runtime-safe.
+  if (!handleId) {
+    if (isUnderTestRunner()) {
+      handleId = `__rango_runtime_handle_${runtimeHandleIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Handle", "createHandle");
+    } else {
+      throw new Error(
+        "[rango] Handle is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createHandle(...)`.",
+      );
+    }
   }
 
   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 {
     __brand: "handle" as const,
@@ -122,9 +149,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" &&
@@ -133,3 +157,49 @@ 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 {
+  // Fall back to the default (identity, pass-through) collect when none is
+  // registered — e.g. the handle's module was not imported so createHandle() never
+  // ran. This is harmless for a handle that wanted the default, but a handle with a
+  // CUSTOM collect that failed to register silently gets the wrong shape (identity
+  // TData[][]) cast as its declared TAccumulated. The runtime can't tell the two
+  // apart (a Handle only carries $$id), so warn in dev (folded out of production).
+  const collectFn = getCollectFn(handle.$$id);
+  if (!collectFn && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[rango] Handle "${handle.$$id}" has no registered collect — falling back ` +
+        `to the identity (per-segment data as-is). If this handle declares a ` +
+        `CUSTOM collect, import its module so createHandle() runs where it is read.`,
+    );
+  }
+  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

@@ -3,11 +3,16 @@
 /**
  * Component to render collected meta descriptors in the document head.
  *
- * Supports both sync and async meta descriptors. Async descriptors
- * (Promise<MetaDescriptorBase>) are resolved using React's use() hook.
+ * Deferred (Promise) meta descriptors are resolved before MetaTags renders
+ * (server-side on the full render, client-side before apply on navigation), so
+ * it only ever receives resolved descriptors and never suspends.
  *
  * When theme is enabled in the router config, MetaTags also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
+ * This makes MetaTags the sole FOUC-script injector for apps that render it;
+ * the standalone `<ThemeScript />` is only needed when MetaTags is not used.
+ * Rendering both is safe (the inline script guards listener registration) but
+ * redundant.
  *
  * @example
  * ```tsx
@@ -24,13 +29,13 @@
  * ```
  */
 
-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 type { MetaDescriptorBase } from "../router/types.js";
 import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
 import { useNonce } from "../browser/react/nonce-context.js";
+import { escapeJsonForScript } from "../escape-script.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -90,31 +95,18 @@ function hasTagName(
   );
 }
 
-/**
- * Check if a value is a Promise.
- */
-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(
+export 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 +117,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // property + content (Open Graph, etc.)
   if (hasPropertyContent(descriptor)) {
     return (
       <meta
@@ -136,7 +127,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // http-equiv + content
   if (hasHttpEquivContent(descriptor)) {
     return (
       <meta
@@ -147,9 +137,10 @@ function renderMetaDescriptor(
     );
   }
 
-  // JSON-LD structured data
   if (hasScriptLdJson(descriptor)) {
-    const json = JSON.stringify(descriptor["script:ld+json"]);
+    const json = escapeJsonForScript(
+      JSON.stringify(descriptor["script:ld+json"]),
+    );
     return (
       <script
         key={`ld-json-${index}`}
@@ -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,20 +178,6 @@ function renderMetaDescriptor(
   );
 }
 
-/**
- * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
- */
-function AsyncMetaTag({
-  promise,
-  index,
-}: {
-  promise: Promise<MetaDescriptorBase>;
-  index: number;
-}): React.ReactNode {
-  const resolved = use(promise);
-  return renderMetaDescriptor(resolved, index);
-}
-
 /**
  * Renders all collected meta descriptors from route handlers.
  *
@@ -212,11 +187,16 @@ function AsyncMetaTag({
  * When theme is enabled in router config, also renders the theme initialization
  * script to prevent FOUC (flash of unstyled content).
  *
- * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
- * React's use() hook. RSC streaming handles the Promise resolution.
+ * Deferred (Promise) meta descriptors are resolved BEFORE MetaTags renders —
+ * server-side on the full/SSR render, client-side before apply on navigation
+ * (resolve-by-default) — so MetaTags only ever receives resolved descriptors and
+ * never suspends.
  */
 export function MetaTags(): React.ReactNode {
-  const descriptors = useHandle(Meta) as MetaDescriptor[];
+  // Deferred descriptors are resolved BEFORE collect runs (resolve-by-default),
+  // and collectMeta strips unset markers, so the collected output is always
+  // resolved base descriptors (never a Promise).
+  const descriptors = useHandle(Meta) as MetaDescriptorBase[];
   const themeConfig = useThemeContext()?.config ?? null;
   const nonce = useNonce();
 
@@ -229,18 +209,9 @@ export function MetaTags(): React.ReactNode {
           dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
         />
       )}
-      {descriptors.map((descriptor, index) => {
-        if (isPromise(descriptor)) {
-          return (
-            <AsyncMetaTag
-              key={`async-${index}`}
-              promise={descriptor}
-              index={index}
-            />
-          );
-        }
-        return renderMetaDescriptor(descriptor, index);
-      })}
+      {descriptors.map((descriptor, index) =>
+        renderMetaDescriptor(descriptor, index),
+      )}
     </>
   );
 }