@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.150

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/build-shell-capture.ts

@@ -0,0 +1,253 @@
+/**
+ * Producer B: build-time PPR shell capture for Prerender+ppr routes (#699).
+ *
+ * Runs in the RSC realm of the build's temp server, AFTER all bundles are
+ * written (the prelude embeds built client asset URLs — bootstrap module,
+ * chunk preloads — that only exist post-client-build). The capture core is
+ * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
+ * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
+ * quiesce, tags union, putShell barrier). The differences are only the base
+ * context (a synthetic build request created via createRequestContext over the
+ * build env — no ambient identity, so the identity guard is trivially
+ * satisfied) and the sink (an entry collector instead of a runtime store).
+ *
+ * The capture's match() re-enters withCacheLookup, HITs the in-realm prerender
+ * store seeded from the just-collected Flight payloads, and REPLAYS the
+ * build-time segments — no handler execution, exactly the runtime composition
+ * path (#697). Live-lane loaders mask into holes; bake-lane loaders execute
+ * under the build context and refuse the capture if they reject or read
+ * identity, the same eligibility rules as at runtime.
+ */
+
+import type { ShellCacheEntry } from "../cache/types.js";
+import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
+import {
+  createRequestContext,
+  runWithRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import {
+  deriveShellCaptureContext,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+  type ShellCaptureDescriptor,
+} from "../rsc/shell-capture.js";
+import { buildFullPayload } from "../rsc/full-payload.js";
+import type { RscPayload, SSRModule } from "../rsc/types.js";
+import type { HandlerContext } from "../rsc/handler-context.js";
+import { renderToReadableStream } from "../deps/rsc.js";
+import {
+  resolvePprConfig,
+  type ResolvedPprConfig,
+} from "../rsc/shell-serve.js";
+
+/**
+ * Normalize a collected truthy `ppr` path option into the SAME concrete
+ * policy the runtime serve path derives — through resolvePprConfig itself,
+ * over a synthetic route entry — so the build-stamped ttl default can never
+ * drift from the serve-side one.
+ */
+export function resolveBuildPprConfig(
+  ppr:
+    | true
+    | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number },
+): ResolvedPprConfig {
+  const resolved = resolvePprConfig({ type: "route", ppr } as any);
+  // resolvePprConfig returns null only for undefined/false ppr; the collector
+  // filtered those out. Guard for the type only.
+  if (!resolved) throw new Error("[rango] unreachable: ppr option was falsy");
+  return resolved;
+}
+
+export interface BuildShellCaptureOptions {
+  /** The router instance (from RouterRegistry in the same realm). */
+  router: any;
+  /** Concrete URL path to capture (e.g. "/pp/alpha"). */
+  urlPath: string;
+  /**
+   * The candidate's trie route key. The capture's match() must land on THIS
+   * route: the phase sweeps every registered router, and a router that does
+   * not own the URL matches something else (its catch-all, a 404 shape) —
+   * that capture must not be baked.
+   */
+  routeName: string;
+  /** Shell store key to stamp into the descriptor (host-free at build). */
+  key: string;
+  ttl?: number;
+  swr?: number;
+  /** The route's static ppr.tags (the capture unions render-recorded tags). */
+  tags?: string[];
+  /**
+   * The route's resolved snapshot size cap (ResolvedPprConfig.maxSnapshotBytes)
+   * — build captures apply the same over-cap skip as runtime captures, so a
+   * raised per-route cap behaves identically across both producers.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * The route's `ppr.captureTimeout` (ms) — producer B honors the same settle
+   * budget as the runtime capture. Build has no waitUntil lifetime bound, so
+   * the option is the only ceiling here.
+   */
+  captureTimeout?: number;
+  /** Build-time env bindings (rango plugin buildEnv), if configured. */
+  buildEnv?: unknown;
+  /**
+   * The MAIN build's version (the version plugin's value folded into the
+   * shipped worker) — NOT the temp server's own version-plugin value. The
+   * serve-side isValidShellHit gate compares entry.buildVersion against the
+   * running worker's ctx.version; stamping the temp server's would make every
+   * build entry an eternal MISS.
+   */
+  buildVersion: string;
+  /**
+   * The SSR half, composed by the plugin from the temp server's SSR
+   * environment runner (react-dom/static prerender + Flight client), with the
+   * bootstrap script content overridden to the BUILT client entry URL.
+   */
+  captureShellHTML: NonNullable<SSRModule["captureShellHTML"]>;
+  /** Verbose per-attempt breadcrumbs (build log). */
+  debug?: boolean;
+}
+
+export interface BuildShellCaptureResult {
+  outcome:
+    | "stored"
+    | "no-shell"
+    | "redirect"
+    | "refused"
+    /** The router swept does not own this URL — try the next one. */
+    | "route-mismatch";
+  /** Present iff outcome === "stored". */
+  entry?: ShellCacheEntry;
+  /** The putShell-barrier tag union (static ppr.tags + render-recorded). */
+  tags?: string[];
+  /** On route-mismatch: what this router's match actually landed on. */
+  matchedRouteName?: string;
+}
+
+/**
+ * Capture the PPR shell for one prerendered URL at build time. Retries once
+ * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
+ * transform graph, mirroring producer A's cold-start retry — same delay).
+ */
+export async function captureShellForBuild(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const first = await attemptBuildCapture(opts);
+  if (first.outcome !== "no-shell") return first;
+  if (opts.debug) {
+    console.log(
+      `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
+    );
+  }
+  await delay(SHELL_CAPTURE_RETRY_DELAY_MS);
+  return attemptBuildCapture(opts);
+}
+
+/** One attempt: fresh base context, fresh derivation, fresh render. */
+async function attemptBuildCapture(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const router = opts.router;
+  const url = new URL(opts.urlPath, "http://build.invalid");
+  const request = new Request(url, { method: "GET" });
+
+  // Synthetic build request context: same factory the runtime handler uses,
+  // so the capture's ALS surface (cookie machinery, variables, waitUntil,
+  // theme resolution) is production-shaped. No cookie header → theme resolves
+  // to the app default, exactly like a first anonymous visitor's capture.
+  const baseCtx = createRequestContext({
+    env: (opts.buildEnv ?? {}) as any,
+    request,
+    url,
+    variables: {},
+    // Fresh empty store per attempt: cache()/"use cache" reads MISS, execute,
+    // and are recorded into the snapshot by the derivation's RecordingShell
+    // wrapper — the entry pins its own generation, nothing preexisting leaks.
+    cacheStore: new MemorySegmentCacheStore(),
+    themeConfig: router.themeConfig ?? null,
+    stateCookieName: router.resolvedStateCookieName,
+    version: opts.buildVersion,
+  });
+
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+    ttl: opts.ttl,
+    swr: opts.swr,
+  });
+
+  // Entry collector: captureAndStoreShell's sink. putShell never fails here,
+  // so a "stored" outcome always carries the entry.
+  let collected: { entry: ShellCacheEntry; tags?: string[] } | null = null;
+  const collector = {
+    putShell: async (
+      _key: string,
+      entry: ShellCacheEntry,
+      _ttl?: number,
+      _swr?: number,
+      tags?: string[],
+    ): Promise<void> => {
+      collected = { entry, tags };
+    },
+  };
+
+  const descriptor: ShellCaptureDescriptor = {
+    key: opts.key,
+    buildVersion: opts.buildVersion,
+    ttl: opts.ttl,
+    swr: opts.swr,
+    tags: opts.tags,
+    captureTimeout: opts.captureTimeout,
+    store: collector as any,
+    debug: opts.debug,
+    maxSnapshotBytes: opts.maxSnapshotBytes,
+  };
+
+  let mismatchedRouteName: string | undefined;
+  const outcome = await runWithRequestContext(derivedCtx, async () => {
+    const match = await router.match(request, { env: opts.buildEnv ?? {} });
+    if (match.routeName !== opts.routeName) {
+      mismatchedRouteName = match.routeName;
+      return "route-mismatch" as const;
+    }
+    if (match.redirect) return "redirect" as const;
+
+    setRequestContextParams(match.params, match.routeName);
+
+    const payload = buildFullPayload(
+      match,
+      // buildFullPayload reads only ctx.router.* and ctx.version.
+      { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        if (opts.debug) {
+          console.warn(
+            `[rango] shell capture render error for ${opts.urlPath}:`,
+            error,
+          );
+        }
+      },
+    });
+
+    return captureAndStoreShell(
+      { captureShellHTML: opts.captureShellHTML } as SSRModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+    );
+  });
+
+  if (outcome === "stored" && collected !== null) {
+    const hit: { entry: ShellCacheEntry; tags?: string[] } = collected;
+    return { outcome, entry: hit.entry, tags: hit.tags };
+  }
+  if (outcome === "route-mismatch") {
+    return { outcome, matchedRouteName: mismatchedRouteName };
+  }
+  return { outcome };
+}

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/shell-manifest-key.ts

@@ -0,0 +1,20 @@
+/**
+ * Build shell manifest key, shared by the producer (the build's shell
+ * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
+ * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
+ * cannot drift. Dependency-free: the producer runs node-side in the plugin,
+ * the consumer in the RSC runtime.
+ *
+ * PATHNAME-ONLY by design. Host-free because the build knows no request
+ * host. Router-free because the router id ($$id) is a hash of
+ * filePath:lineNumber of the TRANSFORMED source, which differs between the
+ * discovery temp server's dev-style transform chain and the main build's —
+ * a temp-realm router id can never be looked up by the shipped worker. The
+ * producer instead detects pathname collisions across routers at build time
+ * and declines both entries (loudly), keeping the key unambiguous. This is
+ * a manifest namespace, never a store keyspace: the runtime shell key
+ * (host + pathname + search + ":shell") stays untouched.
+ */
+export function buildShellManifestKey(pathname: string): string {
+  return pathname;
+}