@rangojs/router 0.0.0-experimental.66 → 0.0.0-experimental.66cdebe3

package/src/use-loader.tsx

@@ -2,6 +2,7 @@
 
 import {
   isValidElement,
+  startTransition,
   useCallback,
   useContext,
   useEffect,
@@ -284,7 +285,9 @@ function useLoaderInternal<T>(
 
         const result = payload.loaderResult;
         if (requestId === requestIdRef.current) {
-          setFetchedData(result);
+          startTransition(() => {
+            setFetchedData(result);
+          });
         }
         return result;
       } catch (e) {

package/src/vite/debug.ts

@@ -0,0 +1,184 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * 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.
+ *
+ * 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.
+// Uses debug.enable() rather than mutating process.env because the `debug`
+// package already snapshotted DEBUG when it was imported above.
+if (process.env.INTERNAL_RANGO_DEBUG) {
+  const existing = debugFactory.disable();
+  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+}
+
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+
+export function createRangoDebugger(namespace: string): 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 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));
+ */
+export async function timed<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  if (!debug) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    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.

package/src/vite/discovery/gate-state.ts

@@ -0,0 +1,171 @@
+import type { Debugger } from "../debug.js";
+
+/**
+ * Manifest-readiness gate + rediscovery scheduler.
+ *
+ * Owns the four pieces of state that cooperate to keep
+ * `s.discoveryDone` (the promise the manifest virtual module's `load()`
+ * hook awaits) consistent across HMR fan-out:
+ *
+ *   - **gatePending**: a Promise has been issued and not yet resolved.
+ *     Workerd's manifest virtual module load() is blocked on it.
+ *   - **inProgress**: a refresh's work callback is currently executing.
+ *   - **queued**: a refresh was attempted while one was already in
+ *     flight; the active run consumes this in its `finally` and
+ *     recurses.
+ *   - **pendingEvents**: a route-file event has been received (gate
+ *     already reset) but the corresponding refresh's work hasn't started
+ *     yet — i.e. the debounce hasn't fired. Set in `noteRouteEvent`,
+ *     cleared at the start of each refresh cycle. Refresh's finally MUST
+ *     hold the gate if this is true even when `queued` is false,
+ *     otherwise an event whose debounce fires AFTER the active refresh
+ *     completes (the "tail-race" window) would observe a resolved gate.
+ *
+ * The HMR-event flow (cloudflare-stress repro):
+ *
+ *   t=0    Touch 1  → noteRouteEvent  → pendingEvents=true, beginGate
+ *                                      (gate1 pending)
+ *          → debounce 100ms
+ *   t=100  runRefreshCycle(work)      → clear pendingEvents, work starts
+ *   t=750  Touch 2  → noteRouteEvent  → pendingEvents=true (no-op gate)
+ *                                      → debounce fires at t=850
+ *   t=800  refresh A's finally        → queued=false, pendingEvents=true
+ *                                      → HOLD gate (don't resolve)
+ *   t=850  runRefreshCycle (debounce) → clear pendingEvents, work starts
+ *   t=1500 refresh B's finally        → queued=false, pendingEvents=false
+ *                                      → resolveGate (gate1 resolves)
+ *
+ * @internal Exported only for unit tests.
+ */
+export interface DiscoveryGate {
+  /**
+   * Reset the gate to a fresh pending Promise via `s.discoveryDone`.
+   * No-op when a gate is already pending — file watchers can fire
+   * multiple events for one save, and replacing the resolver would
+   * orphan the original promise (workerd's manifest load() would hang).
+   */
+  beginGate(): void;
+  /**
+   * Resolve the current pending gate. No-op when no gate is pending.
+   * Called at the tail of the last refresh cycle in a burst.
+   */
+  resolveGate(): void;
+  /**
+   * Record that a route-file event has arrived. Sets `pendingEvents`
+   * and begins the gate. Idempotent for both flags.
+   */
+  noteRouteEvent(): void;
+  /**
+   * Run one refresh cycle, managing queue + pending state around it.
+   * If a cycle is already in flight, sets `queued=true` and returns.
+   * Otherwise clears `pendingEvents`, runs `work`, and in `finally`:
+   *
+   *   - queued        → recurse, gate stays pending
+   *   - pendingEvents → hold gate (next debounced cycle resolves)
+   *   - neither       → resolveGate
+   */
+  runRefreshCycle(work: () => Promise<void>): Promise<void>;
+  /** Snapshot of internal state. Test-only. */
+  readonly state: () => Readonly<{
+    gatePending: boolean;
+    inProgress: boolean;
+    queued: boolean;
+    pendingEvents: boolean;
+  }>;
+}
+
+/** State container the gate writes `discoveryDone` into. */
+export interface GateOwner {
+  discoveryDone: Promise<void> | null | undefined;
+}
+
+export function createDiscoveryGate(
+  s: GateOwner,
+  debug?: Debugger,
+): DiscoveryGate {
+  let gatePending = false;
+  let gateResolver: () => void = () => {};
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+
+  const beginGate = (): void => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise<void>((resolve) => {
+      gateResolver = resolve;
+    });
+    gatePending = true;
+  };
+
+  const resolveGate = (): void => {
+    if (!gatePending) return;
+    // Defer resolution while a refresh cycle is in flight or queued, or
+    // while an unprocessed route-file event is pending its debounce.
+    // Without this guard, cold-start's `discover().then(resolveGate)`
+    // could fire while an HMR-triggered runRefreshCycle is mid-flight,
+    // prematurely unblocking workerd's manifest load() against the
+    // stale cold-start gen. The active cycle's `finally` calls
+    // resolveGate again at the tail and finishes the resolution then.
+    if (inProgress || queued || pendingEvents) {
+      debug?.(
+        "hmr: resolveGate deferred — work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents,
+      );
+      return;
+    }
+    gatePending = false;
+    debug?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+
+  const noteRouteEvent = (): void => {
+    pendingEvents = true;
+    beginGate();
+  };
+
+  const runRefreshCycle = async (work: () => Promise<void>): Promise<void> => {
+    if (inProgress) {
+      queued = true;
+      debug?.("hmr: rediscovery in flight — queued for a follow-up cycle");
+      return;
+    }
+    // Snapshot the current pendingEvents into "we're about to process";
+    // events arriving from now on re-set it.
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err: unknown) => {
+          debug?.(
+            "hmr: queued cycle rejected — releasing gate (%s)",
+            err instanceof Error ? err.message : String(err),
+          );
+          // Belt-and-suspenders: even if the queued cycle's own try/catch
+          // missed something, ensure workerd doesn't hang.
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug?.(
+          "hmr: holding gate for pending events (debounce not yet fired)",
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents }),
+  };
+}