@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/use-loader.tsx

@@ -1,9 +1,71 @@
 "use client";
 
-import { useCallback, useContext, useEffect, useRef, useState } from "react";
+import {
+  isValidElement,
+  startTransition,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
+/**
+ * Extract a specific loader's data from a content ReactNode.
+ *
+ * When a route registers loaders via loader(), the resolved data lives in
+ * the route's OutletProvider (rendered as <Outlet /> content). Parallel
+ * slots are siblings of <Outlet />, so they can't find it by walking
+ * the parent context chain. This helper traverses wrapper elements
+ * (MountContextProvider, ViewTransition, etc.) to reach the OutletProvider
+ * and extract the loader data directly.
+ */
+const NOT_FOUND = Symbol("not-found");
+
+function extractContentLoaderData(
+  node: ReactNode,
+  loaderId: string,
+): unknown | typeof NOT_FOUND {
+  if (!isValidElement(node)) return NOT_FOUND;
+  const props = node.props as Record<string, any> | undefined;
+  if (!props) return NOT_FOUND;
+
+  // Direct OutletProvider with loaderData
+  if (props.loaderData && loaderId in props.loaderData) {
+    return props.loaderData[loaderId];
+  }
+
+  // LoaderBoundary: loaderIds + loaderDataPromise (already resolved array).
+  // When the segment has loading(), loaderData is resolved inside
+  // LoaderBoundary via use(). If the promise was pre-awaited (forceAwait
+  // or isAction), the prop is a raw array we can index into.
+  if (
+    props.loaderIds &&
+    Array.isArray(props.loaderIds) &&
+    props.loaderDataPromise &&
+    !(props.loaderDataPromise instanceof Promise)
+  ) {
+    const idx = (props.loaderIds as string[]).indexOf(loaderId);
+    if (idx !== -1) {
+      const data = (props.loaderDataPromise as any[])[idx];
+      // loaderDataPromise entries may be { ok, data } result objects
+      if (data && typeof data === "object" && "ok" in data) {
+        return data.ok ? data.data : NOT_FOUND;
+      }
+      return data;
+    }
+  }
+
+  // Traverse into wrapper elements (MountContextProvider, ViewTransition,
+  // Suspense wrappers, etc.)
+  if (props.children) return extractContentLoaderData(props.children, loaderId);
+  return NOT_FOUND;
+}
+
 /**
  * Payload returned by loader RSC requests
  */
@@ -13,12 +75,9 @@ interface LoaderRscPayload<T = unknown> {
 }
 
 /**
- * Load function type with form action support
+ * Load function type for fetching loader data from the client
  */
-export type LoadFunction<T> = ((options?: LoadOptions) => Promise<T>) & {
-  /** Form action for progressive enhancement - can be passed to form action prop */
-  action: (formData: FormData) => Promise<void>;
-};
+export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
 /**
  * Result type for useLoader hook (strict - data is required)
@@ -69,28 +128,37 @@ export interface UseLoaderOptions {
  */
 function useLoaderInternal<T>(
   loader: LoaderDefinition<T>,
-  options?: UseLoaderOptions
+  options?: UseLoaderOptions,
 ): UseFetchLoaderResult<T> {
   const context = useContext(OutletContext);
 
   // Get data from context (SSR/navigation)
-  const getContextData = useCallback((): T | undefined => {
+  const contextData = useMemo((): T | undefined => {
     let current: OutletContextValue | null | undefined = context;
     while (current) {
       if (current.loaderData && loader.$$id in current.loaderData) {
         return current.loaderData[loader.$$id] as T;
       }
+      // Check content element — the route's OutletProvider is rendered as
+      // <Outlet /> content (a child), so its loaderData isn't in the parent
+      // chain. Parallel slots need to reach into it to find route-level loaders.
+      const contentData = extractContentLoaderData(
+        current.content,
+        loader.$$id,
+      );
+      if (contentData !== NOT_FOUND) {
+        return contentData as T;
+      }
       current = current.parent;
     }
     return undefined;
   }, [context, loader.$$id]);
 
-  const contextData = getContextData();
-
   // Local state for fetched data (from load() calls)
   const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
+  const requestIdRef = useRef(0);
 
   // Track context data changes to reset fetched data on navigation
   const prevContextDataRef = useRef(contextData);
@@ -108,13 +176,25 @@ function useLoaderInternal<T>(
 
   const throwOnError = options?.throwOnError ?? true;
 
-  // Load function for fetching data
+  // Refs for values used inside load() that should NOT cause callback identity
+  // churn. loader.$$id can change if a reusable component receives a different
+  // loader without remounting; data changes on every navigation. Refs keep the
+  // callback stable while always reading the latest values.
+  const loaderIdRef = useRef(loader.$$id);
+  loaderIdRef.current = loader.$$id;
+  const dataRef = useRef(data);
+  dataRef.current = data;
+
+  // Load function for fetching data via the ?_rsc_loader endpoint.
+  // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
+      const requestId = ++requestIdRef.current;
+      const loaderId = loaderIdRef.current;
       // Verify the loader has $$id
-      if (!loader.$$id) {
+      if (!loaderId) {
         throw new Error(
-          `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`
+          `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`,
         );
       }
 
@@ -122,8 +202,8 @@ function useLoaderInternal<T>(
       setError(null);
 
       try {
-        const url = new URL(window.location.pathname, window.location.origin);
-        url.searchParams.set("_rsc_loader", loader.$$id);
+        const url = new URL(window.location.href);
+        url.searchParams.set("_rsc_loader", loaderId);
 
         const method = loadOptions?.method ?? "GET";
         const isBodyMethod = method !== "GET";
@@ -131,29 +211,58 @@ function useLoaderInternal<T>(
         let fetchOptions: RequestInit;
 
         if (isBodyMethod) {
-          // POST/PUT/PATCH/DELETE - send params and body as JSON
-          const bodyPayload: { params?: Record<string, string>; body?: unknown } = {};
-          if (loadOptions?.params && Object.keys(loadOptions.params).length > 0) {
-            bodyPayload.params = loadOptions.params;
+          const bodyValue =
+            "body" in (loadOptions ?? {})
+              ? (loadOptions as any).body
+              : undefined;
+          const hasParams =
+            loadOptions?.params && Object.keys(loadOptions.params).length > 0;
+
+          if (bodyValue instanceof FormData) {
+            // FormData body — send as multipart/form-data (preserves File objects).
+            // Params are appended as a JSON string in a special field.
+            if (hasParams) {
+              bodyValue.set(
+                "_rsc_loader_params",
+                JSON.stringify(loadOptions!.params),
+              );
+            }
+            fetchOptions = {
+              method,
+              headers: { Accept: "text/x-component" },
+              body: bodyValue,
+            };
+          } else {
+            // JSON body — send params and body as JSON
+            const bodyPayload: {
+              params?: Record<string, string>;
+              body?: unknown;
+            } = {};
+            if (hasParams) {
+              bodyPayload.params = loadOptions!.params;
+            }
+            if (bodyValue !== undefined) {
+              bodyPayload.body = bodyValue;
+            }
+
+            fetchOptions = {
+              method,
+              headers: {
+                Accept: "text/x-component",
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify(bodyPayload),
+            };
           }
-          if ("body" in (loadOptions ?? {}) && (loadOptions as any).body !== undefined) {
-            bodyPayload.body = (loadOptions as any).body;
-          }
-
-          fetchOptions = {
-            method,
-            headers: {
-              Accept: "text/x-component",
-              "Content-Type": "application/json",
-            },
-            body: JSON.stringify(bodyPayload),
-          };
         } else {
           // GET - send params in query string
-          if (loadOptions?.params && Object.keys(loadOptions.params).length > 0) {
+          if (
+            loadOptions?.params &&
+            Object.keys(loadOptions.params).length > 0
+          ) {
             url.searchParams.set(
               "_rsc_loader_params",
-              JSON.stringify(loadOptions.params)
+              JSON.stringify(loadOptions.params),
             );
           }
 
@@ -175,61 +284,32 @@ function useLoaderInternal<T>(
         }
 
         const result = payload.loaderResult;
-        setFetchedData(result);
+        if (requestId === requestIdRef.current) {
+          startTransition(() => {
+            setFetchedData(result);
+          });
+        }
         return result;
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
-        setError(err);
-        if (throwOnError) {
-          throw err;
+        if (requestId === requestIdRef.current) {
+          setError(err);
         }
-        // When throwOnError is false, return the current data (previous successful
-        // value or undefined). Caller should check error state for error handling.
-        return data as T;
-      } finally {
-        setIsLoading(false);
-      }
-    },
-    [throwOnError]
-  );
-
-  // Form action for progressive enhancement
-  // This wrapper is for useFetchLoader's load.action - it manages state internally
-  // and doesn't use React's useActionState. For true PE, use loader.action directly
-  // with useActionState.
-  const action = useCallback(
-    async (formData: FormData): Promise<void> => {
-      if (!loader.action) {
-        throw new Error(
-          `Loader "${loader.$$id}" does not have an action. ` +
-            `Make sure the loader is created with fetchable: true.`
-        );
-      }
-
-      setIsLoading(true);
-      setError(null);
-
-      try {
-        // Pass null as prevState - this wrapper manages state internally
-        const result = await loader.action(null, formData);
-        setFetchedData(result);
-      } catch (e) {
-        const err = e instanceof Error ? e : new Error(String(e));
-        setError(err);
         if (throwOnError) {
           throw err;
         }
+        // When throwOnError is false, return the latest data snapshot (previous
+        // successful value or undefined). Caller should check error state.
+        return dataRef.current as T;
       } finally {
-        setIsLoading(false);
+        if (requestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
       }
     },
-    [throwOnError]
+    [throwOnError],
   );
 
-  // Attach action to load function
-  const loadWithAction = load as LoadFunction<T>;
-  loadWithAction.action = action;
-
   // Throw during render if there's an error and throwOnError is true
   // This allows ErrorBoundaries to catch async errors from load()
   if (error && throwOnError) {
@@ -240,8 +320,8 @@ function useLoaderInternal<T>(
     data,
     isLoading,
     error,
-    load: loadWithAction,
-    refetch: loadWithAction,
+    load,
+    refetch: load,
   };
 }
 
@@ -276,7 +356,7 @@ function useLoaderInternal<T>(
  */
 export function useLoader<T>(
   loader: LoaderDefinition<T>,
-  options?: UseLoaderOptions
+  options?: UseLoaderOptions,
 ): UseLoaderResult<T> {
   const result = useLoaderInternal(loader, options);
 
@@ -285,7 +365,7 @@ export function useLoader<T>(
     throw new Error(
       `useLoader: Loader "${loader.$$id}" data not found in context. ` +
         `Make sure the loader is registered on the route with loader(). ` +
-        `If you need on-demand fetching, use useFetchLoader() instead.`
+        `If you need on-demand fetching, use useFetchLoader() instead.`,
     );
   }
 
@@ -340,7 +420,7 @@ export function useLoader<T>(
  */
 export function useFetchLoader<T>(
   loader: LoaderDefinition<T>,
-  options?: UseLoaderOptions
+  options?: UseLoaderOptions,
 ): UseFetchLoaderResult<T> {
   return useLoaderInternal(loader, options);
 }

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 = "";
+    },
+  };
+}