@rangojs/router 0.0.0-experimental.8bcfea43 → 0.0.0-experimental.8c0b0f1d

package/src/router/trie-matching.ts

@@ -15,7 +15,9 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
+  /** Optional param names declared on the route. Absent params are omitted
+   * from `params` (read as `undefined`), matching the
+   * `ExtractParams<"/:locale?/...">` type. */
   optionalParams?: string[];
   /** Ancestry shortCodes for layout pruning */
   ancestry: string[];
@@ -203,14 +205,11 @@ function validateAndBuild(
     }
   }
 
-  // Fill in empty strings for optional params that weren't matched
-  if (leaf.op) {
-    for (const name of leaf.op) {
-      if (!(name in params)) {
-        params[name] = "";
-      }
-    }
-  }
+  // Optional params that weren't matched are left absent from `params` so
+  // `ctx.params.locale` reads as `undefined`, matching the
+  // `ExtractParams<"/:locale?/...">` type (`{ locale?: string }`). Both
+  // internal consumers — the constraint check above and `reverse()` —
+  // already treat missing/undefined as the absent form.
 
   // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;

package/src/rsc/progressive-enhancement.ts

@@ -248,6 +248,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         segments: match.segments,
         matched: match.matched,
         diff: match.diff,
+        resolvedIds: match.resolvedIds,
         params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
@@ -354,6 +355,7 @@ async function renderPeErrorBoundary<TEnv>(
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
+      resolvedIds: errorResult.resolvedIds,
       params: errorResult.params,
       isPartial: false,
       isError: true,

package/src/rsc/rsc-rendering.ts

@@ -59,6 +59,7 @@ export async function handleRscRendering<TEnv>(
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
+          resolvedIds: match.resolvedIds,
           params: match.params,
           isPartial: false,
           rootLayout: ctx.router.rootLayout,
@@ -81,6 +82,7 @@ export async function handleRscRendering<TEnv>(
           segments: result.segments,
           matched: result.matched,
           diff: result.diff,
+          resolvedIds: result.resolvedIds,
           params: result.params,
           isPartial: true,
           slots: result.slots,
@@ -144,6 +146,7 @@ export async function handleRscRendering<TEnv>(
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
+          resolvedIds: match.resolvedIds,
           params: match.params,
           isPartial: false,
           rootLayout: ctx.router.rootLayout,

package/src/rsc/server-action.ts

@@ -213,6 +213,7 @@ export async function executeServerAction<TEnv>(
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          resolvedIds: errorResult.resolvedIds,
           params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
@@ -324,6 +325,7 @@ export async function revalidateAfterAction<TEnv>(
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      resolvedIds: matchResult.resolvedIds,
       params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),

package/src/rsc/types.ts

@@ -26,6 +26,12 @@ export interface RscPayload {
     isError?: boolean;
     matched?: string[];
     diff?: string[];
+    /**
+     * All segment ids re-resolved on the server, including null-component
+     * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+     * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+     */
+    resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;

package/src/segment-system.tsx

@@ -131,6 +131,47 @@ export interface RenderSegmentsOptions {
   rootLayout?: ComponentType<RootLayoutProps>;
 }
 
+function createViewTransitionBoundary(
+  transition: NonNullable<ResolvedSegment["transition"]>,
+  children: ReactNode,
+): ReactNode {
+  return createElement(ReactViewTransition, {
+    ...transition,
+    children,
+  });
+}
+
+function wrapDefaultOutletContent(
+  content: ReactNode,
+  transition: NonNullable<ResolvedSegment["transition"]>,
+): ReactNode {
+  if (!React.isValidElement(content)) {
+    return createViewTransitionBoundary(transition, content);
+  }
+
+  const props = content.props as any;
+
+  if (content.type === MountContextProvider) {
+    return React.cloneElement(content, {
+      children: wrapDefaultOutletContent(props.children, transition),
+    } as any);
+  }
+
+  if (content.type === OutletProvider && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      content: wrapDefaultOutletContent(props.content, transition),
+    } as any);
+  }
+
+  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      outletContent: wrapDefaultOutletContent(props.outletContent, transition),
+    } as any);
+  }
+
+  return createViewTransitionBoundary(transition, content);
+}
+
 /**
  * Render segments into a React tree with proper layout nesting
  *
@@ -273,17 +314,27 @@ export async function renderSegments(
     // in transitions without adding custom animation classes. Named element-level
     // <ViewTransition> components inside (with name/share props) morph independently
     // from the parent's default cross-fade.
-    if (ReactViewTransition && node.segment.transition) {
-      nodeContent = createElement(ReactViewTransition, {
-        ...node.segment.transition,
-        children: nodeContent,
-      });
-    }
-
-    // Common props for OutletProvider
-    const outletContent: ReactNode =
+    //
+    // For layouts, wrap the outlet content (what `<Outlet />` renders) rather
+    // than the layout component itself. Parallel slots like `<ParallelOutlet
+    // name="@modal" />` read from a separate context channel and end up as
+    // siblings of the VT in the rendered tree, so modal mounts don't trigger a
+    // subtree update on the layout-level VT — which would otherwise make
+    // React's commit walker fire `document.startViewTransition` and apply
+    // view-transition-names to the underlying main subtree (cover/title/etc.).
+    let outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
 
+    const transition = node.segment.transition;
+
+    if (ReactViewTransition && transition) {
+      if (node.segment.type === "layout") {
+        outletContent = wrapDefaultOutletContent(outletContent, transition);
+      } else {
+        nodeContent = createViewTransitionBoundary(transition, nodeContent);
+      }
+    }
+
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
     const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);

package/src/ssr/index.tsx

@@ -162,9 +162,13 @@ function createSsrEventController(opts: {
 }): EventController {
   const location = new URL(opts.pathname, "http://localhost");
   let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
   const handleState = {
     data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    ),
   };
   const state: DerivedNavigationState = {
     state: "idle",

package/src/types/handler-context.ts

@@ -471,13 +471,16 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * **Return Types:**
  * - `boolean` - Hard decision: immediately returns this value (short-circuits)
  * - `{ defaultShouldRevalidate: boolean }` - Soft decision: updates suggestion for next revalidator
+ * - `void` / `null` / `undefined` - Defer to the current suggestion (no opinion); the
+ *   loop continues to the next revalidator without changing the running default
  *
  * **Execution Flow:**
  * 1. Start with built-in `defaultShouldRevalidate` (true if params changed)
  * 2. Execute global revalidators first, then route-specific
  * 3. Hard decision (boolean): stop immediately and use that value
  * 4. Soft decision (object): update suggestion and continue to next revalidator
- * 5. If all return soft decisions: use the final suggestion
+ * 5. Defer (`void` / `null` / `undefined`): leave suggestion unchanged and continue
+ * 6. If no hard decision was returned: use the final running suggestion
  *
  * @param args.currentParams - Previous route params (generic by default, can be narrowed)
  * @param args.currentUrl - Previous URL
@@ -489,7 +492,8 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.formData - Form data from action (future support)
  * @param args.formMethod - HTTP method from action (future support)
  *
- * @returns Hard decision (boolean) or soft suggestion (object)
+ * @returns Hard decision (boolean), soft suggestion (object), or defer
+ *   (`void` / `null` / `undefined`) to keep the running suggestion as-is.
  *
  * @example
  * ```typescript
@@ -514,8 +518,9 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * a segment (layout, route, parallel slot, or loader) should be re-rendered.
  *
  * Return `true` to re-render, `false` to skip (keep client's current version),
- * or `{ defaultShouldRevalidate: boolean }` to override the default for
- * downstream segments.
+ * `{ defaultShouldRevalidate: boolean }` to update the running suggestion for
+ * downstream revalidators, or nothing (`void` / `null` / `undefined`) to defer
+ * to the current suggestion without changing it.
  *
  * @example
  * ```ts
@@ -615,7 +620,7 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * action that may have mutated backend state.
    */
   stale?: boolean;
-}) => boolean | { defaultShouldRevalidate: boolean };
+}) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported
 

package/src/types/segments.ts

@@ -62,6 +62,14 @@ export interface ResolvedSegment {
   notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
   // Mount path from include() scope, used for MountContext.Provider wrapping
   mountPath?: string;
+  /**
+   * @internal Server-side marker: true when the segment's handler actually ran
+   * this request (not skipped via the revalidate cache path). Used by
+   * match-result.ts to populate `MatchResult.resolvedIds` for client-side
+   * handle-bucket cleanup. Stripped from the wire payload before serialization
+   * — never reaches the client.
+   */
+  _handlerRan?: boolean;
 }
 
 /**
@@ -116,6 +124,15 @@ export interface MatchResult {
   segments: ResolvedSegment[];
   matched: string[];
   diff: string[];
+  /**
+   * Every segment id whose handler actually ran on the server this request,
+   * including ones with `component === null` that get filtered out of
+   * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
+   * cleanup pass — a slot that re-resolves and pushes nothing must clear
+   * its previous handle bucket, but `diff` doesn't carry it because the
+   * segment payload doesn't either. A superset of `diff`.
+   */
+  resolvedIds: string[];
   /**
    * Merged route params from all matched segments
    * Available for use by the handler after route matching

package/src/vite/debug.ts

@@ -2,20 +2,41 @@
  * Debug logging for the Rango Vite plugin.
  *
  * Thin wrapper over the `debug` package (the same one Vite uses for its
- * own `vite:*` namespaces). Enable via `DEBUG=rango:*` or `vite --debug rango`.
+ * own `vite:*` namespaces). Enable with either:
  *
- * Returns `undefined` when the namespace is not enabled, so call sites can
- * guard expensive diagnostics with a simple truthiness check:
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
  *
- *     const debug = createRangoDebugger("rango:routes");
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger(NS.routes);
  *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
  *
- * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces
- * (sets DEBUG=rango:* for the current process if nothing is already set).
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
  */
 
 import debugFactory from "debug";
 
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export const NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+} as const;
+
 // Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
 // console.logs in this plugin. Map it to `rango:*` so those call sites can
 // be migrated to the `debug` pipeline without breaking existing setups.
@@ -29,14 +50,19 @@ if (process.env.INTERNAL_RANGO_DEBUG) {
 export type Debugger = (formatter: string, ...args: unknown[]) => void;
 
 export function createRangoDebugger(namespace: string): Debugger | undefined {
-  const instance = debugFactory(namespace);
-  return instance.enabled ? (instance as unknown as Debugger) : undefined;
+  const primary = debugFactory(namespace);
+  // Shadow namespace so `vite --debug rango:*` (which expands to
+  // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary as Debugger;
+  if (shadow.enabled) return shadow as Debugger;
+  return undefined;
 }
 
 /**
- * Measure a sync or async block and log its duration via `debug`. No-ops
- * (still runs `fn`) when the namespace is disabled, so production cost is a
- * single `.enabled` check per call.
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
  *
  *     await timed(debug, "discover routers", () => discoverRouters(state));
  */
@@ -53,3 +79,106 @@ export async function timed<T>(
     debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
   }
 }
+
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export function timedSync<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T,
+): T {
+  if (!debug) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+  record(file: string, ms: number): void;
+  /**
+   * Convenience: time a sync or async block and record it. Propagates
+   * throws; records regardless of outcome. Returns the function's result.
+   */
+  time<T>(file: string, fn: () => T): T;
+  time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+  flush(): void;
+}
+
+export function createCounter(
+  debug: Debugger | undefined,
+  label: string,
+): Counter | undefined {
+  if (!debug) return undefined;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file: string, ms: number): void => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time<T>(file: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const start = performance.now();
+      let out: T | Promise<T>;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof (out as any).then === "function") {
+        return (out as Promise<T>).finally(() =>
+          record(file, performance.now() - start),
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush(): void {
+      if (n === 0) return;
+      debug(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile,
+      );
+      // Reset so buildEnd firing once per environment (Vite 6+ multi-env)
+      // gives one log line per env rather than silently dropping later data.
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    },
+  };
+}

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

@@ -20,6 +20,9 @@ import {
   expandPrerenderRoutes,
   renderStaticHandlers,
 } from "./prerender-collection.js";
+import { createRangoDebugger, timed, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.discovery);
 
 /**
  * Import the user's entry via RSC runner, generate manifests for each
@@ -38,10 +41,16 @@ export async function discoverRouters(
   // 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).
-  await rscEnv.runner.import(state.resolvedEntryPath);
+  await timed(debug, "inner: import entry", () =>
+    rscEnv.runner.import(state.resolvedEntryPath),
+  );
 
   // Import the router package to access the registry
-  const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+  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) {
@@ -100,9 +109,15 @@ export async function discoverRouters(
   }
 
   // Import build utilities for manifest generation
-  const buildMod = await rscEnv.runner.import("@rangojs/router/build");
+  const buildMod = await timed(
+    debug,
+    "inner: import @rangojs/router/build",
+    () => rscEnv.runner.import("@rangojs/router/build"),
+  );
   const generateManifestFull = buildMod.generateManifestFull;
 
+  debug?.("inner: found %d router(s) in registry", registry.size);
+
   const nestedRouterConflict = findNestedRouterConflict(
     [...registry.values()]
       .map((router) => router.__sourceFile)
@@ -130,6 +145,7 @@ export async function discoverRouters(
   // Collect all manifests for trie building (avoid re-running generateManifest)
   const allManifests: Array<{ id: string; manifest: any }> = [];
 
+  const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
       continue;
@@ -234,8 +250,15 @@ export async function discoverRouters(
     }
   }
 
+  debug?.(
+    "inner: generated manifests for %d router(s) (%sms)",
+    allManifests.length,
+    (performance.now() - manifestGenStart).toFixed(1),
+  );
+
   // Build route trie from merged manifest + ancestry
   let newMergedRouteTrie: any = null;
+  const trieStart = debug ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
     const buildRouteTrie = buildMod.buildRouteTrie;
     if (buildRouteTrie && mergedRouteAncestry) {
@@ -329,6 +352,11 @@ export async function discoverRouters(
     }
   }
 
+  debug?.(
+    "inner: trie build done (%sms)",
+    (performance.now() - trieStart).toFixed(1),
+  );
+
   // Commit all local state to the shared discovery state atomically.
   // This ensures a failed re-discovery (e.g. from a transient module
   // evaluation error) preserves the last known-good state.