@rangojs/router 0.5.2 → 0.6.0

package/src/vite/discovery/client-urls-projection.ts

@@ -0,0 +1,322 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePath, parseAst } from "vite";
+import {
+  serializeClientUrlPatterns,
+  type ClientUrlProjection,
+} from "../../client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "../../client-urls/types.js";
+import {
+  computeProductionHash,
+  hashRefKey,
+} from "../plugins/client-ref-hashing.js";
+import { hasUseClientDirective } from "../utils/directive-prologue.js";
+import { createRangoDebugger, NS } from "../debug.js";
+import { findTsFiles } from "../../build/route-types/scan-filter.js";
+import type { DiscoveryState } from "./state.js";
+
+const debug = createRangoDebugger(NS.discovery);
+
+interface ClientUrlSsrEnvironment {
+  readonly runner?: {
+    import(id: string): Promise<Record<string, unknown>>;
+  };
+}
+
+interface ClientUrlProjectionServerModule {
+  clearClientUrlProjections(): void;
+  setClientUrlProjection(
+    referenceId: string,
+    projection: ClientUrlProjection,
+  ): void;
+}
+
+function hasDefaultExport(code: string): boolean {
+  let program: { body?: any[] };
+  try {
+    program = parseAst(code, { lang: "tsx" }) as { body?: any[] };
+  } catch {
+    return false;
+  }
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExportDefaultDeclaration") return true;
+    if (node?.type !== "ExportNamedDeclaration") continue;
+    for (const specifier of node.specifiers ?? []) {
+      const exportedName =
+        specifier?.exported?.name ?? specifier?.exported?.value;
+      if (exportedName === "default") return true;
+    }
+  }
+  return false;
+}
+
+function normalizeSource(state: DiscoveryState, id: string): string {
+  const cleanId = id.split("?", 1)[0];
+  const absoluteId = isAbsolute(cleanId)
+    ? cleanId
+    : resolve(state.projectRoot, cleanId);
+  return normalizePath(absoluteId);
+}
+
+function referenceId(referenceKey: string): string {
+  return `${referenceKey}#default`;
+}
+
+function withoutReferenceQuery(reference: string): string {
+  const exportIndex = reference.lastIndexOf("#");
+  const moduleId =
+    exportIndex === -1 ? reference : reference.slice(0, exportIndex);
+  const exportName = exportIndex === -1 ? "" : reference.slice(exportIndex);
+  const queryIndex = moduleId.indexOf("?");
+  return `${queryIndex === -1 ? moduleId : moduleId.slice(0, queryIndex)}${exportName}`;
+}
+
+export function recordClientUrlsModule(
+  state: DiscoveryState,
+  code: string,
+  id: string,
+): void {
+  if (
+    !code.includes("clientUrls(") ||
+    !hasUseClientDirective(code) ||
+    !hasDefaultExport(code)
+  ) {
+    return;
+  }
+
+  const source = normalizeSource(state, id);
+  const projectRoot = normalizePath(resolve(state.projectRoot));
+  const relativeId = normalizePath(relative(projectRoot, source));
+  const outsideProject =
+    relativeId === ".." ||
+    relativeId.startsWith("../") ||
+    isAbsolute(relativeId);
+  const devReferenceKey = outsideProject ? `/@fs${source}` : `/${relativeId}`;
+
+  const sourceByReferenceId = (state.clientUrlSourceByReferenceId ??=
+    new Map());
+  sourceByReferenceId.set(referenceId(devReferenceKey), source);
+
+  const productionReferenceKeys = new Set([
+    hashRefKey(relativeId),
+    computeProductionHash(projectRoot, devReferenceKey),
+  ]);
+  for (const productionReferenceKey of productionReferenceKeys) {
+    sourceByReferenceId.set(referenceId(productionReferenceKey), source);
+  }
+}
+
+export function resolveClientUrlsSource(
+  state: DiscoveryState,
+  referenceId: string,
+): string | undefined {
+  return state.clientUrlSourceByReferenceId?.get(
+    withoutReferenceQuery(referenceId),
+  );
+}
+
+/**
+ * Deterministic filesystem discovery of clientUrls modules. Transform-based
+ * recording only sees modules that some environment actually loads — a
+ * clientUrls module not yet reachable from any transformed graph at discovery
+ * time (cold ordering, a mount added before its first import is served) would
+ * never be recorded and its include would fail with empty projections. Walking
+ * the project source (the same walk static route-type generation performs)
+ * makes recording independent of module-graph timing. The transform hooks
+ * still record too — they refresh dev HMR edits between scans.
+ */
+export function scanForClientUrlModules(state: DiscoveryState): void {
+  if (!state.projectRoot) return;
+  for (const filePath of findTsFiles(state.projectRoot, state.scanFilter)) {
+    let code: string;
+    try {
+      code = readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    recordClientUrlsModule(state, code, filePath);
+  }
+}
+
+function projectionError(
+  referenceId: string,
+  source: string | undefined,
+  message: string,
+  cause?: unknown,
+): Error {
+  const sourceDescription = source ? ` from source "${source}"` : "";
+  const errorMessage = `Cannot discover client URL projection for reference "${referenceId}"${sourceDescription}: ${message}`;
+  return cause === undefined
+    ? new Error(errorMessage)
+    : new Error(errorMessage, { cause });
+}
+
+/**
+ * Lenient pre-entry projection refresh. Re-serializes every RECORDED clientUrls
+ * module before the discovery pass imports the entry, so routers re-created by
+ * that import materialize against the CURRENT module contents.
+ *
+ * Scar: node-preset HMR served stale client-urls routes after a route-shape
+ * edit — the clientUrls module is an HMR-accepted client boundary in the rsc
+ * graph, and the strict registry-driven pass below only runs AFTER the entry
+ * import, so `.routes(reference)` materialized the previous pass's projection.
+ *
+ * Errors are deliberately swallowed per source (a module mid-edit keeps its
+ * last-known projection); the strict discoverClientUrlProjections() pass still
+ * surfaces real failures afterwards. No-ops on cold start (nothing recorded
+ * yet) and when the SSR runner is unavailable.
+ */
+export async function refreshRecordedClientUrlProjections(
+  state: DiscoveryState,
+  ssrEnv: ClientUrlSsrEnvironment | undefined,
+  serverMod: ClientUrlProjectionServerModule,
+): Promise<void> {
+  const sourceByReferenceId = state.clientUrlSourceByReferenceId;
+  if (
+    !sourceByReferenceId?.size ||
+    typeof ssrEnv?.runner?.import !== "function"
+  ) {
+    return;
+  }
+
+  const referenceIdsBySource = new Map<string, string[]>();
+  for (const [refId, source] of sourceByReferenceId) {
+    const ids = referenceIdsBySource.get(source);
+    if (ids) {
+      ids.push(refId);
+    } else {
+      referenceIdsBySource.set(source, [refId]);
+    }
+  }
+
+  for (const [source, referenceIds] of referenceIdsBySource) {
+    let definition: unknown;
+    try {
+      definition = (await ssrEnv.runner.import(source)).default;
+    } catch {
+      continue;
+    }
+    if (
+      (typeof definition !== "object" && typeof definition !== "function") ||
+      definition === null ||
+      (definition as { __brand?: unknown }).__brand !== "client-urls"
+    ) {
+      continue;
+    }
+    const projection = serializeClientUrlPatterns(
+      definition as ClientUrlPatterns,
+    );
+    debug?.(
+      "pre-entry refresh %s -> [%s]",
+      source,
+      projection.routes.map((route) => route.pattern).join(", "),
+    );
+    for (const referenceId of referenceIds) {
+      serverMod.setClientUrlProjection(referenceId, projection);
+      // The eager routes-manifest virtual module REPLAYS this state map
+      // (clearClientUrlProjections + set) whenever it re-evaluates — and the
+      // watcher's gen-file write invalidates it right before the entry import,
+      // so a stale map here would clobber the registry install above before
+      // the router materializes its mount. Keep both in sync.
+      state.clientUrlProjectionMap?.set(referenceId, projection);
+    }
+  }
+}
+
+/**
+ * Strict projection discovery over every RECORDED clientUrls module. Recorded
+ * modules — not router references — are the source of truth: include() mounts
+ * materialize lazily from the projection registry, so there is no router-level
+ * reference list to consult. Serializes every source before atomically
+ * installing the new projections (a failure preserves last-known state).
+ *
+ * A recorded source whose file no longer exists is dropped silently
+ * (recordClientUrlsModule never un-records, so deletions must self-heal here).
+ * A present-but-broken module is a hard error: it is part of the app graph.
+ */
+export async function discoverClientUrlProjections(
+  state: DiscoveryState,
+  ssrEnv: ClientUrlSsrEnvironment | undefined,
+  serverMod: ClientUrlProjectionServerModule,
+): Promise<void> {
+  scanForClientUrlModules(state);
+  const sourceByReferenceId = state.clientUrlSourceByReferenceId;
+  if (!sourceByReferenceId?.size) {
+    serverMod.clearClientUrlProjections();
+    state.clientUrlProjectionMap = new Map();
+    return;
+  }
+
+  const referenceIdsBySource = new Map<string, string[]>();
+  for (const [referenceId, source] of sourceByReferenceId) {
+    const ids = referenceIdsBySource.get(source);
+    if (ids) {
+      ids.push(referenceId);
+    } else {
+      referenceIdsBySource.set(source, [referenceId]);
+    }
+  }
+
+  if (typeof ssrEnv?.runner?.import !== "function") {
+    const [source, ids] = referenceIdsBySource.entries().next().value as [
+      string,
+      string[],
+    ];
+    throw projectionError(
+      ids[0],
+      source,
+      "the SSR module runner is unavailable",
+    );
+  }
+
+  const nextProjections = new Map<string, ClientUrlProjection>();
+  const removedSources: string[] = [];
+  for (const [source, referenceIds] of referenceIdsBySource) {
+    let module: Record<string, unknown>;
+    try {
+      module = await ssrEnv.runner.import(source);
+    } catch (cause) {
+      if (!existsSync(source)) {
+        removedSources.push(source);
+        continue;
+      }
+      throw projectionError(
+        referenceIds[0],
+        source,
+        "failed to import the source module",
+        cause,
+      );
+    }
+    const definition = module.default;
+    if (
+      (typeof definition !== "object" && typeof definition !== "function") ||
+      definition === null ||
+      (definition as { __brand?: unknown }).__brand !== "client-urls"
+    ) {
+      throw projectionError(
+        referenceIds[0],
+        source,
+        'the module default export must be created by clientUrls() and have __brand === "client-urls"',
+      );
+    }
+    const projection = serializeClientUrlPatterns(
+      definition as ClientUrlPatterns,
+    );
+    for (const referenceId of referenceIds) {
+      nextProjections.set(referenceId, projection);
+    }
+  }
+
+  for (const source of removedSources) {
+    for (const [referenceId, recorded] of sourceByReferenceId) {
+      if (recorded === source) sourceByReferenceId.delete(referenceId);
+    }
+  }
+
+  serverMod.clearClientUrlProjections();
+  for (const [id, projection] of nextProjections) {
+    serverMod.setClientUrlProjection(id, projection);
+  }
+  state.clientUrlProjectionMap = nextProjections;
+}

package/src/vite/discovery/discover-routers.ts

@@ -21,6 +21,7 @@ import {
 // RangoContext from the runner realm) — see the runner.import below.
 import { buildPerRouterTrie } from "../../build/route-trie.js";
 import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
+import { mergeFullManifests } from "../../build/merge-full-manifests.js";
 import { flattenLeafEntries } from "../utils/manifest-utils.js";
 import type { DiscoveryState, PrecomputedEntry } from "./state.js";
 import {
@@ -34,6 +35,10 @@ import {
 } from "./discovery-errors.js";
 import { createRangoDebugger, timed, NS } from "../debug.js";
 import { computeProductionHash } from "../plugins/client-ref-hashing.js";
+import {
+  discoverClientUrlProjections,
+  refreshRecordedClientUrlProjections,
+} from "./client-urls-projection.js";
 
 const debug = createRangoDebugger(NS.discovery);
 
@@ -48,9 +53,25 @@ const debug = createRangoDebugger(NS.discovery);
 export async function discoverRouters(
   state: DiscoveryState,
   rscEnv: any,
+  ssrEnv?: any,
 ): Promise<any> {
   if (!state.resolvedEntryPath) return;
 
+  // Import the router package FIRST (leaf module, no side effects on user
+  // code) so recorded clientUrls projections can be refreshed BEFORE the entry
+  // import: routers re-created by that import call `.routes(reference)` at
+  // module scope and materialize whatever projection is installed at that
+  // moment. On HMR re-discovery that must be the CURRENT module contents, not
+  // the previous pass's snapshot (see refreshRecordedClientUrlProjections).
+  const serverMod = await timed(
+    debug,
+    "inner: import @rangojs/router/server",
+    () => rscEnv.runner.import("@rangojs/router/server"),
+  );
+  await timed(debug, "inner: refresh recorded client URL projections", () =>
+    refreshRecordedClientUrlProjections(state, ssrEnv, serverMod),
+  );
+
   // Import the entry file via RSC environment.
   // For node preset: this is the router file (createRouter() registers in RouterRegistry).
   // For cloudflare preset: this is the worker entry (which imports the router).
@@ -58,12 +79,6 @@ export async function discoverRouters(
     rscEnv.runner.import(state.resolvedEntryPath),
   );
 
-  // Import the router package to access the registry
-  const serverMod = await timed(
-    debug,
-    "inner: import @rangojs/router/server",
-    () => rscEnv.runner.import("@rangojs/router/server"),
-  );
   let registry: Map<string, any> = serverMod.RouterRegistry;
 
   if (!registry || registry.size === 0) {
@@ -114,6 +129,10 @@ export async function discoverRouters(
     }
   }
 
+  await timed(debug, "inner: discover client URL projections", () =>
+    discoverClientUrlProjections(state, ssrEnv, serverMod),
+  );
+
   // generateManifestFull must run in the RSC runner realm: it invokes the
   // user's urlpatterns.handler() via RangoContext, consuming router instances
   // from the runner. The trie/fallback-ref builders are pure transforms over
@@ -176,20 +195,27 @@ export async function discoverRouters(
 
   const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
-    if (!router.urlpatterns || !generateManifestFull) {
+    if (!generateManifestFull) {
       continue;
     }
 
-    const manifest = await generateManifestFull(
-      router.urlpatterns,
-      routerMountIndex,
-      {
-        routerId: id,
-        ...(router.__basename ? { urlPrefix: router.__basename } : {}),
-        ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
-      },
-    );
-    routerMountIndex++;
+    const mounts =
+      router.__urlpatternMounts ??
+      (router.urlpatterns ? [{ patterns: router.urlpatterns }] : []);
+    if (mounts.length === 0) continue;
+
+    const mountManifests = [];
+    for (const mount of mounts) {
+      mountManifests.push(
+        await generateManifestFull(mount.patterns, routerMountIndex, {
+          routerId: id,
+          ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+          ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+        }),
+      );
+      routerMountIndex++;
+    }
+    const manifest = mergeFullManifests(mountManifests);
     allManifests.push({ id, manifest });
 
     // Router-level "use client" boundary defaults -> app-fallback (the

package/src/vite/discovery/state.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ScanFilter } from "../../build/generate-route-types.js";
+import type { ClientUrlProjection } from "../../client-urls/server-projection.js";
 
 export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 
@@ -79,6 +80,11 @@ export interface ShellPrerenderCandidate {
     | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number };
 }
 
+export interface ClientUrlDiscoveryState {
+  clientUrlSourceByReferenceId: Map<string, string>;
+  clientUrlProjectionMap: Map<string, ClientUrlProjection>;
+}
+
 export interface DiscoveryState {
   resolvedEntryPath: string | undefined;
   projectRoot: string;
@@ -109,6 +115,8 @@ export interface DiscoveryState {
   perRouterTrieMap: Map<string, any>;
   perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
   perRouterManifestDataMap: Map<string, Record<string, string>>;
+  clientUrlSourceByReferenceId?: Map<string, string>;
+  clientUrlProjectionMap?: Map<string, ClientUrlProjection>;
 
   prerenderManifestEntries: Record<string, string> | null;
   staticManifestEntries: Record<string, string> | null;
@@ -164,7 +172,7 @@ export interface DiscoveryState {
 export function createDiscoveryState(
   entryPath: string | undefined,
   opts: PluginOptions | undefined,
-): DiscoveryState {
+): DiscoveryState & ClientUrlDiscoveryState {
   return {
     resolvedEntryPath: entryPath,
     projectRoot: "",
@@ -182,6 +190,8 @@ export function createDiscoveryState(
     perRouterTrieMap: new Map(),
     perRouterPrecomputedMap: new Map(),
     perRouterManifestDataMap: new Map(),
+    clientUrlSourceByReferenceId: new Map(),
+    clientUrlProjectionMap: new Map(),
 
     prerenderManifestEntries: null,
     staticManifestEntries: null,

package/src/vite/discovery/virtual-module-codegen.ts

@@ -44,6 +44,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
   const hasManifest =
     state.mergedRouteManifest &&
     Object.keys(state.mergedRouteManifest).length > 0;
+  const hasClientUrlModules = Boolean(state.clientUrlSourceByReferenceId?.size);
 
   if (hasManifest) {
     // Build gen file import statements for each router with a sourceFile.
@@ -83,6 +84,9 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       "setRouterManifest",
       ...(state.isBuildMode ? ["registerRouterManifestLoader"] : []),
       "clearAllRouterData",
+      ...(hasClientUrlModules
+        ? ["clearClientUrlProjections", "setClientUrlProjection"]
+        : []),
     ];
     const lines = [
       `import { ${serverImports.join(", ")} } from "@rangojs/router/server";`,
@@ -95,6 +99,16 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       `clearAllRouterData();`,
     ];
 
+    if (hasClientUrlModules) {
+      lines.push(`clearClientUrlProjections();`);
+      for (const [referenceId, projection] of state.clientUrlProjectionMap ??
+        []) {
+        lines.push(
+          `setClientUrlProjection(${JSON.stringify(referenceId)}, ${jsonParseExpression(projection)});`,
+        );
+      }
+    }
+
     if (varIdx > 0) {
       lines.push(
         `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
@@ -169,6 +183,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
   }
 
   const lines: string[] = [];
+  if (hasClientUrlModules) {
+    lines.push(
+      `import { clearClientUrlProjections } from "@rangojs/router/server";`,
+      `clearClientUrlProjections();`,
+    );
+  }
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||

package/src/vite/plugins/virtual-entries.ts

@@ -154,14 +154,23 @@ import {
   decodeAction,
   decodeFormState,
 } from "@rangojs/router/internal/deps/rsc";
-import { router } from "${routerPath}";
-import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
-import { VERSION } from "@rangojs/router:version";
 
 // Startup bootstrap imports (routes + loader manifests). See
 // RSC_ENTRY_BOOTSTRAP_IMPORTS — the same list the custom-entry injector uses.
+//
+// ORDER IS LOAD-BEARING: the bootstrap imports MUST precede the router import.
+// The routes-manifest module installs client URL projections
+// (setClientUrlProjection), and createRouter().routes(clientUrlsReference)
+// consults them at router-module evaluation. Router-first would silently push
+// every clientUrls() app onto the deferred-subscription path and change mount
+// registration order with no error. The custom-entry injector keeps the same
+// guarantee by PREPENDING this list at file top (version-injector.ts).
 ${bootstrapImports}
 
+import { router } from "${routerPath}";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
+import { VERSION } from "@rangojs/router:version";
+
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
 // re-evaluate before router.tsx finishes, leaving the import undefined.