@rangojs/router 0.0.0-experimental.112 → 0.0.0-experimental.114

package/src/use-loader.tsx

@@ -187,17 +187,20 @@ export interface UseLoaderOptions {
    */
   key?: string;
   /**
-   * Cross-loader refresh group. Tag reads of DIFFERENT loaders with the same
-   * `refreshGroup` name, then call `useRefreshLoaders(name)()` to refresh the
-   * whole group at once. Each member is refreshed with a plain GET against the
-   * current route URL — no params, no body, no mutation methods — because a
-   * group spans heterogeneous loaders with different param/return shapes.
+   * Cross-loader refresh group tag(s). Tag reads of DIFFERENT loaders with a
+   * shared name, then call `useRefreshLoaders()(name)` to refresh the whole group
+   * at once. Pass an array to tag one read into several groups — it is refreshed
+   * when ANY of its groups is refreshed, so a coarse tag can cover the whole set
+   * while a finer tag targets a subset. Each member is refreshed with a plain GET
+   * against the current route URL — no params, no body, no mutation methods —
+   * because a group spans heterogeneous loaders with different param/return
+   * shapes.
    *
    * For parameterized sharing of a SINGLE loader, use `key` instead; group
    * members should be registered or non-parameterized-keyed reads (a plain-GET
    * group refresh would drop any per-call params).
    */
-  refreshGroup?: string;
+  refreshGroup?: string | string[];
 }
 
 /**
@@ -254,29 +257,42 @@ function useLoaderInternal<T>(
   // only hooks with the same `key` refresh together. Default (no key) keeps the
   // historical behavior: one bucket per loader id.
   const key = options?.key;
-  const refreshGroup = options?.refreshGroup;
+  // Normalize the refresh-group tag(s) to a stable, deduped, sorted list. The
+  // joined `groupKey` string is the subscribe effect's dependency, so passing an
+  // inline array literal (`refreshGroup={["a", "b"]}`) does not force a
+  // resubscribe on every render. An empty list means "no groups" — identical to
+  // omitting the option (`hasGroups` stays false, no private bucket is created).
+  const refreshGroupOption = options?.refreshGroup;
+  const groupKey =
+    refreshGroupOption === undefined
+      ? ""
+      : JSON.stringify(
+          typeof refreshGroupOption === "string"
+            ? [refreshGroupOption]
+            : [...new Set(refreshGroupOption)].sort(),
+        );
+  const groupList = useMemo<string[]>(
+    () => (groupKey === "" ? [] : (JSON.parse(groupKey) as string[])),
+    [groupKey],
+  );
+  const hasGroups = groupList.length > 0;
   // A grouped reader with no explicit key gets a private per-hook bucket so a
   // cross-loader group refresh cannot leak into the bare `loader.$$id` bucket
   // shared by unrelated unkeyed readers. Sharing within a group is opt-in via
   // an explicit `key`.
   const privateBucketIdRef = useRef<string | null>(null);
-  if (
-    refreshGroup !== undefined &&
-    key === undefined &&
-    privateBucketIdRef.current === null
-  ) {
+  if (hasGroups && key === undefined && privateBucketIdRef.current === null) {
     privateBucketIdRef.current = `__rg${privateGroupBucketSeq++}`;
   }
   const effectiveKey =
-    key ??
-    (refreshGroup !== undefined ? privateBucketIdRef.current! : undefined);
+    key ?? (hasGroups ? privateBucketIdRef.current! : undefined);
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
   // Plain-GET refresh thunk registered with the store for cross-loader group
   // refresh (useRefreshLoaders). Always shares into this hook's bucket, never
   // touches lastSharedRequestIdRef (so a group refresh never render-throws —
-  // errors surface via `error` and reject the refreshGroup() promise instead),
+  // errors surface via `error` and reject the refreshGroups() promise instead),
   // and sends no params/body. Stable across navigations (depends only on
   // loaderId + bucketKey), so the store keeps one current thunk per bucket.
   const groupRefetch = useCallback(async (): Promise<void> => {
@@ -340,16 +356,17 @@ function useLoaderInternal<T>(
       {
         loaderId,
         ephemeral: !hasContextData,
-        group: refreshGroup,
-        refetch: refreshGroup !== undefined ? groupRefetch : undefined,
+        group: hasGroups ? groupList : undefined,
+        refetch: hasGroups ? groupRefetch : undefined,
       },
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
     // sharedSnapshot is captured for the one-shot init sync; we don't want
     // to re-subscribe on every snapshot change. bucketKey, hasContextData,
-    // refreshGroup, and groupRefetch are the only inputs that require a fresh
-    // subscription (groupRefetch is stable per bucketKey).
-  }, [bucketKey, hasContextData, refreshGroup, groupRefetch]);
+    // groupKey, and groupRefetch are the only inputs that require a fresh
+    // subscription (groupList is memoized on groupKey; groupRefetch is stable
+    // per bucketKey).
+  }, [bucketKey, hasContextData, groupKey, groupRefetch]);
 
   // Local state holds the result of:
   //   - parameterized / mutation `load()` calls (load({ params }), POST,
@@ -360,9 +377,13 @@ function useLoaderInternal<T>(
   //     prevents two unrelated components from accidentally sharing data
   //     through the global store just because they reference the same
   //     loader id.
-  const [localFetchedData, setLocalFetchedData] = useState<T | undefined>(
-    undefined,
-  );
+  // `has` distinguishes a committed local result (including `null`/`undefined`)
+  // from "no local load yet", so a load() that resolves to a falsy value is not
+  // discarded in favor of the shared snapshot or the seeded context.
+  const [localFetchedData, setLocalFetchedData] = useState<{
+    has: boolean;
+    value: T | undefined;
+  }>({ has: false, value: undefined });
   const [localIsLoading, setLocalIsLoading] = useState(false);
   const [localError, setLocalError] = useState<Error | null>(null);
 
@@ -385,7 +406,7 @@ function useLoaderInternal<T>(
   const prevContextDataRef = useRef(contextData);
   useEffect(() => {
     if (prevContextDataRef.current !== contextData) {
-      setLocalFetchedData(undefined);
+      setLocalFetchedData({ has: false, value: undefined });
       setLocalIsLoading(false);
       setLocalError(null);
       lastSharedRequestIdRef.current = null;
@@ -396,10 +417,14 @@ function useLoaderInternal<T>(
     }
   }, [contextData, loaderId]);
 
-  // Read priority: a parameterized load() result overrides the shared
-  // snapshot; the shared snapshot overrides the server-seeded context.
-  const data =
-    localFetchedData ?? (sharedSnapshot.value as T | undefined) ?? contextData;
+  // Read priority: a committed parameterized load() result overrides the shared
+  // snapshot; a committed shared snapshot overrides the server-seeded context.
+  // `has`/`hasValue` gate each level so a committed falsy value is not skipped.
+  const data = localFetchedData.has
+    ? localFetchedData.value
+    : sharedSnapshot.hasValue
+      ? (sharedSnapshot.value as T | undefined)
+      : contextData;
   const isLoading = localIsLoading || sharedSnapshot.isLoading;
   const error = localError ?? sharedSnapshot.error;
 
@@ -553,7 +578,7 @@ function useLoaderInternal<T>(
           // if a newer load() was issued from this hook before this one
           // resolved, drop the stale result.
           startTransition(() => {
-            setLocalFetchedData(result);
+            setLocalFetchedData({ has: true, value: result });
             setLocalIsLoading(false);
           });
         }
@@ -712,14 +737,21 @@ export function useFetchLoader<T>(
 }
 
 /**
- * Refresh every loader tagged with a shared `refreshGroup` name.
+ * Get a stable function that refreshes loaders by cross-loader group tag.
  *
- * Returns a stable async function that refreshes all currently-mounted reads
- * in the group with a plain GET against the current route URL. This is the
- * cross-loader counterpart to the single-loader `key`: use it to refresh a set
- * of DIFFERENT loaders together (e.g. profile + orders after an account
- * switch). Members are tagged via `useLoader(Loader, { refreshGroup })` /
- * `useFetchLoader(Loader, { refreshGroup })`.
+ * The returned `refresh(groups)` takes one group name or an array of names and
+ * re-runs every currently-mounted read tagged with ANY of them, with a plain GET
+ * against the current route URL. This is the cross-loader counterpart to the
+ * single-loader `key`: use it to refresh a set of DIFFERENT loaders together
+ * (e.g. profile + orders after an account switch). Members are tagged via
+ * `useLoader(Loader, { refreshGroup })` / `useFetchLoader(Loader, { refreshGroup })`,
+ * where `refreshGroup` is one name or several.
+ *
+ * Passing the group(s) to the returned function rather than to the hook lets a
+ * single `useRefreshLoaders()` instance refresh different groups depending on
+ * context, and lets one call refresh several groups at once — their members are
+ * unioned and deduped, so a loader tagged into two of the named groups is fetched
+ * exactly once.
  *
  * Group refresh never render-throws: a failing member surfaces its error via
  * that read's `error` state, and the returned promise rejects with an
@@ -736,15 +768,30 @@ export function useFetchLoader<T>(
  *   return <span>{data.name}</span>;
  * }
  * function Orders() {
- *   const { data } = useLoader(OrdersLoader, { key: userId, refreshGroup: "account" });
+ *   // Tagged into two groups: refreshed by "account" (the whole set) or "orders".
+ *   const { data } = useLoader(OrdersLoader, {
+ *     key: userId,
+ *     refreshGroup: ["account", "orders"],
+ *   });
  *   return <span>{data.count} orders</span>;
  * }
- * function RefreshButton() {
- *   const refreshAccount = useRefreshLoaders("account");
- *   return <button onClick={() => refreshAccount()}>Refresh</button>;
+ * function RefreshButtons() {
+ *   const refresh = useRefreshLoaders();
+ *   return (
+ *     <>
+ *       <button onClick={() => refresh("account")}>Refresh account</button>
+ *       <button onClick={() => refresh("orders")}>Refresh orders</button>
+ *       <button onClick={() => refresh(["account", "orders"])}>Refresh both</button>
+ *     </>
+ *   );
  * }
  * ```
  */
-export function useRefreshLoaders(group: string): () => Promise<void> {
-  return useCallback(() => loaderStore.refreshGroup(group), [group]);
+export function useRefreshLoaders(): (
+  groups: string | string[],
+) => Promise<void> {
+  return useCallback(
+    (groups: string | string[]) => loaderStore.refreshGroups(groups),
+    [],
+  );
 }

package/src/vite/plugins/expose-ids/export-analysis.ts

@@ -6,6 +6,7 @@ import {
   buildExportMap,
   escapeRegExp,
 } from "../expose-id-utils.js";
+import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
 import type { CreateExportBinding } from "./types.js";
 
 /**
@@ -59,19 +60,57 @@ export function isExportOnlyFile(
   return true;
 }
 
-// NOTE: This regex may over-count when the fn name appears inside strings or
-// comments, but it's only used for the warning heuristic (totalCalls >
-// supportedBindings) and the inline-extraction pre-check, so over-counting
-// triggers a harmless extra AST parse rather than affecting correctness.
+function createCallPattern(fnNames: string[]): RegExp {
+  return new RegExp(
+    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
+    "g",
+  );
+}
+
+// Counts real create*() call sites, ignoring occurrences inside comments and
+// string literals. Used by the unsupported-shape warning heuristic and the
+// inline-extraction pre-check.
 export function countCreateCallsForNames(
   code: string,
   fnNames: string[],
 ): number {
-  const pattern = new RegExp(
-    `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
-    "g",
-  );
-  return (code.match(pattern) || []).length;
+  return codeMatchIndices(code, createCallPattern(fnNames)).length;
+}
+
+/** Convert a 0-based byte offset to a 1-based { line, column }. */
+export function offsetToLineColumn(
+  code: string,
+  index: number,
+): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(index, code.length);
+  for (let i = 0; i < end; i++) {
+    if (code[i] === "\n") {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: index - lineStart + 1 };
+}
+
+/**
+ * Locate every real create*() call site (comment/string-free) that is NOT one
+ * of the supported, id-injectable export bindings, returning each as a 1-based
+ * { line, column }. The empty result means every call is in a supported shape.
+ * Both binding-collection paths anchor `callExprStart` at the start of the
+ * create* identifier — exactly where this pattern matches — so the set
+ * difference is exact.
+ */
+export function findUnsupportedCreateCallSites(
+  code: string,
+  fnNames: string[],
+  supportedBindings: CreateExportBinding[],
+): Array<{ line: number; column: number }> {
+  const supported = new Set(supportedBindings.map((b) => b.callExprStart));
+  return codeMatchIndices(code, createCallPattern(fnNames))
+    .filter((index) => !supported.has(index))
+    .map((index) => offsetToLineColumn(code, index));
 }
 
 export function getImportedFnNames(
@@ -306,9 +345,25 @@ export function collectCreateExportBindings(
 export function buildUnsupportedShapeWarning(
   filePath: string,
   fnName: string,
+  sites: Array<{ line: number; column: number }> = [],
 ): string {
-  return [
-    `[rango] Unsupported ${fnName} shape in "${filePath}".`,
+  const lines = [`[rango] Unsupported ${fnName} shape in "${filePath}".`];
+
+  // Point at the exact call(s) so the location is clickable in the terminal/IDE
+  // (file:line:column) instead of leaving the user to scan the whole file.
+  if (sites.length === 1) {
+    const s = sites[0];
+    lines.push(
+      `The ${fnName}(...) call at ${filePath}:${s.line}:${s.column} has no stable $$id injected — it is not in a supported shape.`,
+    );
+  } else if (sites.length > 1) {
+    lines.push(
+      `These ${fnName}(...) calls have no stable $$id injected — they are not in a supported shape:`,
+    );
+    for (const s of sites) lines.push(`  - ${filePath}:${s.line}:${s.column}`);
+  }
+
+  lines.push(
     `Supported shapes are:`,
     `  - export const X = ${fnName}(...)`,
     `  - const X = ${fnName}(...); export { X }`,
@@ -316,5 +371,6 @@ export function buildUnsupportedShapeWarning(
     `Potentially unsupported forms include:`,
     `  - export let/var X = ${fnName}(...)`,
     `  - inline ${fnName}(...) calls`,
-  ].join("\n");
+  );
+  return lines.join("\n");
 }

package/src/vite/plugins/expose-internal-ids.ts

@@ -28,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  findUnsupportedCreateCallSites,
   isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
@@ -370,14 +371,21 @@ ${lazyImports.join(",\n")}
           if (!hasCode) continue;
 
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          // Locate the real (comment/string-free) create* calls not covered by
+          // a supported, id-injectable export shape. Empty means every call is
+          // fine — in particular, a create*() token in a comment or string no
+          // longer trips a spurious warning.
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames),
+          );
+          if (sites.length === 0) continue;
 
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
 
         // --- Loader: track for manifest (RSC env only) ---

package/src/vite/plugins/use-cache-transform.ts

@@ -30,6 +30,13 @@ const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 // and should not be wrapped (children can't be cache-keyed).
 const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
+/**
+ * Grammar for a valid function-level directive: `use cache` optionally followed
+ * by `: <profile-name>`. The single source of truth for both the transform and
+ * the near-miss validator below.
+ */
+export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
+
 export function useCacheTransform(): Plugin {
   let projectRoot = "";
   let isBuild = false;
@@ -116,9 +123,9 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         );
 
-        // Always check for near-miss directives, even when valid directives
-        // exist. A file may contain both valid and invalid "use cache" directives
-        // in different functions — the invalid ones should still warn.
+        // Check for near-miss directives on the function-level path. The
+        // file-level branch above returns earlier (it wraps every export
+        // regardless), so this runs only when there is no file-level directive.
         warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
         if (functionResult) return functionResult;
@@ -219,7 +226,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (
         value: string,
         name: string,
@@ -273,11 +280,6 @@ function findFileLevelDirective(
   return null;
 }
 
-/**
- * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
- */
-const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
-
 /**
  * Regex for near-miss: starts with "use cache:" but has invalid tokens.
  */
@@ -307,7 +309,7 @@ function warnOnNearMissDirectives(
       if (
         value.startsWith("use cache") &&
         NEAR_MISS_RE.test(value) &&
-        !VALID_DIRECTIVE_RE.test(value)
+        !USE_CACHE_DIRECTIVE_RE.test(value)
       ) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(

package/src/vite/router-discovery.ts

@@ -17,6 +17,7 @@ import {
   findNestedRouterConflict,
   findRouterFiles,
 } from "../build/generate-route-types.js";
+import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -1184,8 +1185,19 @@ export function createRouterDiscoveryPlugin(
               trimmed.startsWith('"use client"') ||
               trimmed.startsWith("'use client'");
             if (!inRecoveryMode && isUseClient) return;
-            const hasUrls = source.includes("urls(");
-            const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            // Cheap raw pre-check first; only when a candidate token is present
+            // do we confirm it occurs in real code (not a comment/string) via a
+            // single allocation-free code-region scan. Most saved files contain
+            // neither token and skip the scan entirely. This avoids a comment or
+            // string mention spuriously marking a file relevant and triggering an
+            // unnecessary re-discovery on save.
+            let hasUrls = source.includes("urls(");
+            let hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            if (hasUrls) hasUrls = firstCodeMatchIndex(source, /urls\(/g) >= 0;
+            if (hasCreateRouter) {
+              hasCreateRouter =
+                firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
+            }
             if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
             if (inRecoveryMode) {
               debugDiscovery?.(