@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/loader.ts

@@ -1,9 +1,14 @@
 /**
- * rsc-router/loader (client version)
+ * @rangojs/router/loader (client version)
  *
  * Client-only stub for createLoader. Returns a minimal loader definition
- * that can be passed to hooks like useLoader. The actual loader function
- * is not included - it only exists on the server.
+ * ({ __brand, $$id }) that can be passed to hooks like useLoader.
+ * The actual loader function is not included -- it only exists on the server.
+ *
+ * For export-only loader files, the Vite plugin replaces the entire file with
+ * object literals (bypassing this function). Those stubs only contain
+ * { __brand, $$id }.
+ * This function only runs when loaders are in mixed files (not export-only).
  *
  * The $$id is injected by the Vite exposeInternalIds plugin.
  */
@@ -13,35 +18,48 @@ import type {
   LoaderDefinition,
   LoaderFn,
 } from "./types.js";
+import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 2: Fetchable with `true` (no middleware)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true
+  fetchable: true,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 3: Fetchable with middleware options
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  options: FetchableLoaderOptions
+  options: FetchableLoaderOptions,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
-// Implementation - client stub that just returns the loader definition
-// The $$id parameter is injected by Vite plugin, not user-provided
+// Implementation - client stub ($$id injected by Vite plugin, not user-provided)
 export function createLoader<T>(
   _fn: LoaderFn<T, Record<string, string | undefined>, any>,
   _fetchable?: true | FetchableLoaderOptions,
-  __injectedId?: string
+  __injectedId?: string,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
-  // Client only needs the $$id for identification
-  // The actual loader function is only used on the server
+  const loaderId = __injectedId || "";
+
+  // Under test runner, no id needed (loaderId stays ""; loader.rsc.ts provides fallback).
+  // Otherwise, missing id means unsupported shape — fail loud to avoid wrong key.
+  if (!loaderId && !isUnderTestRunner()) {
+    if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Loader", "createLoader");
+    }
+    throw new Error(
+      "[rango] Loader is missing $$id — the build plugin did not inject one. " +
+        "Export it as `export const X = createLoader(...)`.",
+    );
+  }
+
   return {
     __brand: "loader",
-    $$id: __injectedId || "",
+    $$id: loaderId,
   };
 }

package/src/missing-id-error.ts

@@ -0,0 +1,68 @@
+// Builds the error thrown when a create*() call (createLoader / createHandle)
+// reaches runtime without an injected $$id. The exposeInternalIds Vite transform
+// injects $$id only for an EXPORTED const declaration, so a non-exported const,
+// an `export let/var`, or an inline create*() call gets none. Previously this
+// failed with a terse message and no source location; this helper adds the
+// offending call site (best-effort, from the stack) and actionable guidance.
+//
+// The "<Kind> is missing $$id" prefix is preserved so existing tests and any
+// log scrapers keep matching. Dev-only: the call sites guard on
+// process.env.NODE_ENV === "development", so production builds fold the branch
+// away and tree-shake this module out.
+
+// create*() implementation files to skip when locating the user's call site.
+const SELF_FILES = new Set([
+  "missing-id-error",
+  "loader",
+  "loader.rsc",
+  "handle",
+]);
+
+/**
+ * Best-effort "path:line:column" of the user's create*() call, parsed from the
+ * current stack. Skips @rangojs/router internals and node_modules. Returns
+ * undefined if nothing usable is found (stack parsing is inherently fragile).
+ */
+function findUserCallSite(): string | undefined {
+  try {
+    const stack = new Error().stack;
+    if (!stack) return undefined;
+    for (const frame of stack.split("\n").slice(1)) {
+      const m = frame.match(
+        /(?:\(|@|\s)(?:file:\/\/)?((?:\/|[A-Za-z]:[\\/])[^()\s]+?\.(?:ts|tsx|js|jsx|mts|cts)):(\d+):(\d+)\)?/,
+      );
+      if (!m) continue;
+      const path = m[1];
+      if (path.includes("node_modules") || path.includes("@rangojs/router")) {
+        continue;
+      }
+      const base = path
+        .split(/[\\/]/)
+        .pop()!
+        .replace(/\.(?:ts|tsx|js|jsx|mts|cts)$/, "");
+      if (SELF_FILES.has(base)) continue;
+      return `${path}:${m[2]}:${m[3]}`;
+    }
+  } catch {
+    // best-effort only
+  }
+  return undefined;
+}
+
+export function missingInjectedIdError(
+  kind: "Loader" | "Handle",
+  fnName: "createLoader" | "createHandle",
+): Error {
+  const site = findUserCallSite();
+  const at = site ? ` (created at ${site})` : "";
+  return new Error(
+    `[rango] ${kind} is missing $$id${at}.\n` +
+      `The @rangojs/router:expose-internal-ids Vite transform injects ${fnName}()'s ` +
+      `stable $$id from an EXPORTED const declaration only:\n` +
+      `  export const X = ${fnName}(...)\n` +
+      `  const X = ${fnName}(...); export { X }\n` +
+      `A non-exported const, an \`export let/var\`, or an inline ${fnName}(...) ` +
+      `call gets no $$id — export it as \`export const\`. (A matching ` +
+      `"Unsupported ${fnName} shape" warning names the exact file:line.)`,
+  );
+}

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {

package/src/outlet-provider.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import { useContext, useMemo, type ReactNode } from "react";
+import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Outlet content provider — stores parent context for useLoader chain walking.
+ */
+export function OutletProvider({
+  content,
+  parallel,
+  segment,
+  loaderData,
+  children,
+}: {
+  content: ReactNode;
+  parallel?: ResolvedSegment[];
+  segment?: ResolvedSegment;
+  loaderData?: Record<string, any>;
+  children: ReactNode;
+}): ReactNode {
+  // Get parent context to enable walking up the chain for loader lookups
+  const parentContext = useContext(OutletContext);
+
+  const value = useMemo(
+    () => ({
+      content,
+      parallel,
+      segment,
+      loaderData,
+      parent: parentContext,
+      loading: segment?.loading,
+    }),
+    [content, parallel, segment, loaderData, parentContext],
+  );
+
+  return (
+    <OutletContext.Provider value={value}>{children}</OutletContext.Provider>
+  );
+}

package/src/prerender/param-hash.ts

@@ -1,30 +1,32 @@
 /**
  * Deterministic param hashing for prerender storage keys.
- *
- * Used at build time (child process) to generate filenames and at
- * runtime (worker) to look up pre-rendered data. Both environments
- * must produce identical hashes for the same params.
- *
- * Uses a simple DJB2-based hash that works in all JS environments
- * (Node.js, Cloudflare Workers, browsers) without crypto imports.
+ * Used at build time and runtime; both must produce identical hashes.
+ * DJB2-based; works in all JS environments without crypto imports.
  */
 
-/**
- * Compute a deterministic hash string from route params.
- * For static routes (no params), returns "_".
- */
+import { encodeKV } from "../encode-kv.js";
+
+// For static routes (no params), returns "_".
 export function hashParams(params: Record<string, string>): string {
   const entries = Object.entries(params);
   if (entries.length === 0) return "_";
 
-  const sorted = entries.sort(([a], [b]) => a.localeCompare(b));
-  const str = sorted.map(([k, v]) => `${k}=${v}`).join("&");
-  return djb2Hex(str);
+  // Byte-order sort + encodeURIComponent join (see encodeKV); output is
+  // byte-identical to the prior inline implementation, so build-time and
+  // runtime hashes stay stable.
+  return djb2Hex(encodeKV(entries, { sort: true }));
 }
 
 /**
  * DJB2 hash returning an 8-char hex string.
  * Deterministic across all JS runtimes.
+ *
+ * 32-bit output: per-route collision probability hits ~50% near ~77k distinct
+ * param sets (birthday bound). The production store keys solely on
+ * routeName/paramHash and does not verify the canonical param string, so a
+ * collision serves the surviving entry for both param sets. Benign for typical
+ * catalogs; revisit (wider hash or stored-param verification) before
+ * pre-rendering hundreds of thousands of pages per route.
  */
 function djb2Hex(str: string): string {
   let hash = 5381;

package/src/prerender/store.ts

@@ -1,28 +1,59 @@
 /**
- * Prerender Store
- *
- * Reads pre-rendered segment data from the worker bundle at build time.
- * The data is stored as globalThis.__PRERENDER_MANIFEST, a map of
- * "<routeName>/<paramHash>" to dynamic import functions that resolve
- * individual prerender entry modules.
+ * Prerender Store — reads pre-rendered segment data from the worker bundle.
+ * Manifest module (injected via globalThis.__loadPrerenderManifestModule)
+ * contains key-to-specifier map and loadPrerenderAsset for import() resolution.
  */
 
-import type { SerializedSegmentData, SegmentHandleData } from "../cache/types.js";
+import type { SerializedSegmentData } from "../cache/types.js";
 
 export interface PrerenderEntry {
   segments: SerializedSegmentData[];
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle map (see handle-snapshot.ts encodeHandles); "" when the
+   *  route pushed no handles. Encoded so Promise/ReactNode handle values survive
+   *  the JSON-serialized build artifact / dev wire, identical to the runtime cache. */
+  handles: string;
 }
 
 export interface PrerenderStore {
-  get(routeName: string, paramHash: string, meta?: { pathname: string }):
-    PrerenderEntry | null | Promise<PrerenderEntry | null>;
+  get(
+    routeName: string,
+    paramHash: string,
+    meta?: { pathname: string; isPassthroughRoute?: boolean },
+  ): PrerenderEntry | null | Promise<PrerenderEntry | null>;
+}
+
+export interface StaticEntry {
+  encoded: string;
+  /** RSC-encoded single-segment handle data (see encodeHandleValue); "" when the
+   *  Static handler pushed no handles. */
+  handles: string;
+}
+
+export interface StaticStore {
+  get(handlerId: string): Promise<StaticEntry | null>;
+}
+
+interface PrerenderManifestModule {
+  default: Record<string, string>;
+  loadPrerenderAsset: (
+    specifier: string,
+  ) => Promise<{ default: PrerenderEntry }>;
 }
 
 declare global {
-  // Injected by closeBundle post-processing: map of key -> () => import("./assets/__pr-*.js")
+  // Injected by closeBundle post-processing: lazy loader for the prerender
+  // manifest module. The module exports a key→specifier map and a
+  // loadPrerenderAsset function that anchors import() relative to the manifest.
   // eslint-disable-next-line no-var
-  var __PRERENDER_MANIFEST: Record<string, () => Promise<{ default: PrerenderEntry }>> | undefined;
+  var __loadPrerenderManifestModule:
+    | (() => Promise<PrerenderManifestModule>)
+    | undefined;
+  // Injected by closeBundle post-processing: map of handlerId -> () => import("./assets/__st-*.js")
+  // Asset default export is either a string (no handles) or { encoded, handles } object.
+  // eslint-disable-next-line no-var
+  var __STATIC_MANIFEST:
+    | Record<string, () => Promise<{ default: string | StaticEntry }>>
+    | undefined;
   // Injected by virtual module in dev mode for on-demand prerender
   // eslint-disable-next-line no-var
   var __PRERENDER_DEV_URL: string | undefined;
@@ -35,9 +66,12 @@ declare global {
  */
 export function createDevPrerenderStore(devUrl: string): PrerenderStore {
   return {
-    async get(_routeName, _paramHash, meta) {
+    async get(routeName, paramHash, meta) {
       if (!meta?.pathname) return null;
-      const url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}`;
+      const isIntercept = paramHash.endsWith("/i");
+      let url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}&routeName=${encodeURIComponent(routeName)}`;
+      if (isIntercept) url += "&intercept=1";
+      if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
         const res = await fetch(url);
         if (!res.ok) return null;
@@ -52,17 +86,35 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
 /**
  * Create a prerender store.
  * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
- * Production: backed by globalThis.__PRERENDER_MANIFEST injected at build time.
+ * Production: backed by globalThis.__loadPrerenderManifestModule which lazily
+ * loads the manifest module on first access.
  * Returns null if no prerender data is available.
  */
 export function createPrerenderStore(): PrerenderStore | null {
   if (globalThis.__PRERENDER_DEV_URL) {
     return createDevPrerenderStore(globalThis.__PRERENDER_DEV_URL);
   }
-  const manifest = globalThis.__PRERENDER_MANIFEST;
-  if (!manifest || Object.keys(manifest).length === 0) return null;
+  if (!globalThis.__loadPrerenderManifestModule) return null;
 
   const cache = new Map<string, Promise<PrerenderEntry | null>>();
+  let manifestModulePromise: Promise<PrerenderManifestModule> | null = null;
+
+  function loadManifestModule(): Promise<PrerenderManifestModule> {
+    if (!manifestModulePromise) {
+      // Do not cache a failed manifest-module load: clear the memoized promise
+      // on rejection so the next get() retries, and let the error propagate
+      // (consistent with the per-asset load policy below) instead of caching a
+      // null for the isolate lifetime, which would silently degrade every
+      // prerendered route to a miss after one transient failure.
+      manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
+        (err) => {
+          manifestModulePromise = null;
+          throw err;
+        },
+      );
+    }
+    return manifestModulePromise;
+  }
 
   return {
     get(routeName: string, paramHash: string): Promise<PrerenderEntry | null> {
@@ -70,11 +122,59 @@ export function createPrerenderStore(): PrerenderStore | null {
       const cached = cache.get(key);
       if (cached) return cached;
 
-      const loader = manifest[key];
-      if (!loader) return Promise.resolve(null);
+      const promise = loadManifestModule().then((mod) => {
+        const specifier = mod.default[key];
+        if (!specifier) return null;
+        // Let asset load errors propagate — a missing/corrupted artifact
+        // for a key that exists in the manifest is a build/deploy error
+        // and should surface as a 500, not be silently swallowed as null
+        // (which the handler stub would misreport as a 404).
+        return mod.loadPrerenderAsset(specifier).then((asset) => asset.default);
+      });
+      // Only memoize once the manifest module resolved: a manifest-load
+      // rejection must not poison the per-key cache, or the retry above is moot.
+      cache.set(
+        key,
+        promise.catch((err) => {
+          cache.delete(key);
+          throw err;
+        }),
+      );
+      return promise;
+    },
+  };
+}
+
+/**
+ * Create a static segment store.
+ * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.
+ * Returns null if no static data is available (dev mode or no Static handlers).
+ */
+export function createStaticStore(): StaticStore | null {
+  const manifest = globalThis.__STATIC_MANIFEST;
+  if (!manifest || Object.keys(manifest).length === 0) return null;
+
+  const cache = new Map<string, Promise<StaticEntry | null>>();
+
+  return {
+    get(handlerId: string): Promise<StaticEntry | null> {
+      const cached = cache.get(handlerId);
+      if (cached) return cached;
+
+      const importFn = manifest[handlerId];
+      if (!importFn) return Promise.resolve(null);
 
-      const promise = loader().then((mod) => mod.default).catch(() => null);
-      cache.set(key, promise);
+      const promise = importFn()
+        .then((mod) => {
+          const val = mod.default;
+          // Normalize: string-only (no handles) or { encoded, handles }
+          if (typeof val === "string") {
+            return { encoded: val, handles: "" } as StaticEntry;
+          }
+          return val as StaticEntry;
+        })
+        .catch(() => null);
+      cache.set(handlerId, promise);
       return promise;
     },
   };