@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}

package/src/vite/plugins/cloudflare-protocol-stub.ts

@@ -0,0 +1,214 @@
+import type { Plugin } from "vite";
+
+const VIRTUAL_PREFIX = "virtual:rango-cloudflare-stub-";
+const NULL_PREFIX = "\0" + VIRTUAL_PREFIX;
+const CF_PREFIX = "cloudflare:";
+
+/**
+ * `globalThis` key the `cloudflare:workers` stub reads to populate its
+ * `env` export. Router discovery sets this to the resolved `buildEnv`
+ * proxy (from `wrangler.getPlatformProxy()` when `buildEnv: "auto"` is
+ * configured, or a user-supplied object otherwise) before importing the
+ * worker entry, and clears it after discovery disposes the proxy. When
+ * unset, the stub's `env` falls back to `{}`.
+ *
+ * Using `globalThis` is the only cross-module bridge that works here:
+ * the stub's `load` hook returns source text, not a live closure, but
+ * the stub module is evaluated in the same Node process as the
+ * discovery plugin — so reading a global at module-evaluation time
+ * reaches whatever the plugin assigned there. A symbol key would be
+ * cleaner in-process but awkward to name from the stub source.
+ *
+ * @internal
+ */
+export const BUILD_ENV_GLOBAL_KEY = "__rango_build_env__";
+
+const SOURCE_EXT_RE = /\.[mc]?[jt]sx?$/;
+
+const IMPORT_NODE_TYPES = new Set([
+  "ImportDeclaration",
+  "ImportExpression",
+  "ExportNamedDeclaration",
+  "ExportAllDeclaration",
+]);
+
+// Keep in sync with `STUBS` in cloudflare-protocol-loader-hook.mjs —
+// both paths (Vite transform and Node loader) need to hand out the same
+// classes. Unknown `cloudflare:*` modules fall back to an empty default
+// export so third-party packages (e.g. the Cloudflare Agents SDK) can
+// pull them into the graph without crashing discovery. Discovery only
+// evaluates module top-level code — no handlers run — so missing named
+// exports only fail if something does `class X extends Missing {}` at
+// module scope, which is rare outside the already-stubbed classes.
+const STUBS: Record<string, string> = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = globalThis[${JSON.stringify(BUILD_ENV_GLOBAL_KEY)}] ?? {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively (empty
+// default export) rather than throwing. We prioritize dependency-graph
+// resilience over strict validation of user imports because third-party
+// packages can pull `cloudflare:*` modules we haven't curated, and
+// discovery should not fail just because those modules appear in the graph.
+// Tradeoff: unsupported user-authored `cloudflare:*` imports may fail later
+// with a generic JS/module error instead of a tailored rango-branded hint.
+// The test below pins this behavior so dependency compatibility is not
+// regressed accidentally.
+const FALLBACK_STUB = `export default {};\n`;
+
+interface AstNode {
+  type: string;
+  start?: number;
+  end?: number;
+  source?: AstNode | null;
+  value?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Stubs `cloudflare:*` imports for the discovery-time Node Vite server.
+ *
+ * Discovery only evaluates user module top-level code — it never invokes
+ * DurableObject / WorkerEntrypoint / Workflow handlers — so empty base
+ * classes are enough for `class X extends DurableObject {}` declarations
+ * to load in Node, where `cloudflare:*` is otherwise unresolvable.
+ *
+ * Interception point: a transform hook parses source with Rollup's
+ * plugin-context parser (`this.parse`) and rewrites only real import
+ * specifier spans (`import ... from "cloudflare:xxx"`,
+ * `import("cloudflare:xxx")`, `export ... from "cloudflare:xxx"`) to a
+ * plain virtual module name (`virtual:rango-cloudflare-stub-xxx`).
+ * This must be done in transform because Vite's module runner routes
+ * URL-scheme specifiers straight to Node's native ESM loader without
+ * consulting plugin `resolveId` hooks. Using the AST (instead of a
+ * text regex or a permissive lexer) guarantees that strings,
+ * comments, and template literals that merely contain import-like
+ * text are never mutated — the walker only looks at the four import
+ * node types.
+ *
+ * The transform runs on user source AND on compiled node_modules
+ * output: real-world CF packages (e.g. the Cloudflare Agents SDK)
+ * ship compiled JS that contains `import ... from "cloudflare:email"`
+ * and similar, so excluding node_modules would leave those imports
+ * unrewritten. Cost is small because the early exit (`code.includes`)
+ * skips files with no cloudflare: mention.
+ *
+ * The plugin intentionally runs at Vite's default ordering (no
+ * `enforce: "pre"`) so TS/JSX has already been compiled to plain JS
+ * by the time `this.parse` runs — acorn doesn't understand
+ * non-standard syntax.
+ *
+ * `cloudflare:workers`, `cloudflare:email`, `cloudflare:sockets`, and
+ * `cloudflare:workflows` each get curated stubs with the well-known
+ * symbols that appear in top-level `extends` positions. Any other
+ * `cloudflare:*` specifier falls back to an empty default export —
+ * discovery never executes the handlers, so an empty module is safe
+ * for anything the graph pulls in transitively.
+ *
+ * Only registered in the discovery temp server, not the user's runtime
+ * config.
+ * @internal
+ */
+export function createCloudflareProtocolStubPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:cloudflare-protocol-stub",
+    transform(code, id) {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!SOURCE_EXT_RE.test(cleanId)) return null;
+      if (!code.includes(CF_PREFIX)) return null;
+
+      let ast: AstNode;
+      try {
+        ast = this.parse(code, { lang: "tsx" }) as unknown as AstNode;
+      } catch {
+        // Malformed source — let a downstream plugin surface the parse error.
+        return null;
+      }
+
+      const hits: Array<{ start: number; end: number; value: string }> = [];
+      walk(ast, (node) => {
+        if (!IMPORT_NODE_TYPES.has(node.type)) return;
+        const source = node.source;
+        if (!source || source.type !== "Literal") return;
+        if (typeof source.value !== "string") return;
+        if (!source.value.startsWith(CF_PREFIX)) return;
+        if (typeof source.start !== "number" || typeof source.end !== "number")
+          return;
+        hits.push({
+          start: source.start,
+          end: source.end,
+          value: source.value,
+        });
+      });
+
+      if (hits.length === 0) return null;
+
+      // Rewrite from last to first so earlier offsets stay valid. `start`/
+      // `end` span the full literal including quotes, so we re-emit the
+      // same quote character around the new specifier.
+      hits.sort((a, b) => b.start - a.start);
+      let out = code;
+      for (const hit of hits) {
+        const submodule = hit.value.slice(CF_PREFIX.length);
+        const quote = code[hit.start] === "'" ? "'" : '"';
+        out =
+          out.slice(0, hit.start) +
+          quote +
+          VIRTUAL_PREFIX +
+          submodule +
+          quote +
+          out.slice(hit.end);
+      }
+      return { code: out, map: null };
+    },
+    resolveId(id) {
+      if (id.startsWith(VIRTUAL_PREFIX)) {
+        return "\0" + id;
+      }
+      return null;
+    },
+    load(id) {
+      if (!id.startsWith(NULL_PREFIX)) return null;
+      const submodule = id.slice(NULL_PREFIX.length);
+      const specifier = CF_PREFIX + submodule;
+      return STUBS[specifier] ?? FALLBACK_STUB;
+    },
+  };
+}
+
+function walk(node: unknown, visit: (n: AstNode) => void): void {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+    return;
+  }
+  const n = node as AstNode;
+  if (typeof n.type !== "string") return;
+  visit(n);
+  for (const key in n) {
+    if (key === "loc" || key === "start" || key === "end" || key === "range") {
+      continue;
+    }
+    walk(n[key], visit);
+  }
+}

package/src/vite/plugins/expose-action-id.ts

@@ -3,6 +3,9 @@ import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
 import { normalizePath } from "./expose-id-utils.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 /**
  * Type for the RSC plugin's manager API
@@ -39,7 +42,7 @@ function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
     );
     if (plugin) {
       console.warn(
-        `[rsc-router:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
+        `[rango:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
           `Consider updating the name lookup if the plugin was renamed.`,
       );
     }
@@ -254,6 +257,8 @@ export function exposeActionId(): Plugin {
   let isBuild = false;
   let hashToFileMap: Map<string, string> | undefined;
   let rscPluginApi: RscPluginApi | undefined;
+  const counterTransform = createCounter(debug, "expose-action-id transform");
+  const counterRender = createCounter(debug, "expose-action-id renderChunk");
 
   return {
     name: "@rangojs/router:expose-action-id",
@@ -268,6 +273,11 @@ export function exposeActionId(): Plugin {
       rscPluginApi = getRscPluginApi(config);
     },
 
+    buildEnd() {
+      counterTransform?.flush();
+      counterRender?.flush();
+    },
+
     buildStart() {
       // Verify RSC plugin is present at build start (after all config hooks have run)
       // This allows rsc-router:rsc-integration to dynamically add the RSC plugin
@@ -277,7 +287,7 @@ export function exposeActionId(): Plugin {
 
       if (!rscPluginApi) {
         throw new Error(
-          "[rsc-router] Could not find @vitejs/plugin-rsc. " +
+          "[rango] Could not find @vitejs/plugin-rsc. " +
             "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
@@ -324,40 +334,54 @@ export function exposeActionId(): Plugin {
         return;
       }
 
-      // Dev mode: no hash-to-file mapping needed (IDs are already file paths)
-      return transformServerReferences(code, id);
+      const start = counterTransform ? performance.now() : 0;
+      try {
+        // Dev mode: no hash-to-file mapping needed (IDs are already file paths)
+        return transformServerReferences(code, id);
+      } finally {
+        counterTransform?.record(id, performance.now() - start);
+      }
     },
 
     // Build mode: renderChunk runs after all transforms and bundling complete
     renderChunk(code, chunk) {
-      // Only RSC bundle should get file paths for revalidation matching
-      // SSR bundle must NOT use file paths because client components run there
-      // and need to match the client bundle during hydration (otherwise: error #418)
-      const isRscEnv = this.environment?.name === "rsc";
-
-      // Only use file path mapping for RSC environment
-      const effectiveMap = isRscEnv ? hashToFileMap : undefined;
-
-      // For RSC bundles, both createServerReference and registerServerReference
-      // may need transforming. Use a single MagicString for correct sourcemaps.
-      if (isRscEnv && hashToFileMap) {
-        const s = new MagicString(code);
-        const changed1 = applyServerReferenceWrapping(code, s, effectiveMap);
-        const changed2 = applyRegisterReferenceWrapping(code, s, hashToFileMap);
-        if (changed1 || changed2) {
-          return {
-            code: s.toString(),
-            map: s.generateMap({
-              source: chunk.fileName,
-              includeContent: true,
-            }),
-          };
+      const start = counterRender ? performance.now() : 0;
+      try {
+        // Only RSC bundle should get file paths for revalidation matching
+        // SSR bundle must NOT use file paths because client components run there
+        // and need to match the client bundle during hydration (otherwise: error #418)
+        const isRscEnv = this.environment?.name === "rsc";
+
+        // Only use file path mapping for RSC environment
+        const effectiveMap = isRscEnv ? hashToFileMap : undefined;
+
+        // For RSC bundles, both createServerReference and registerServerReference
+        // may need transforming. Use a single MagicString for correct sourcemaps.
+        if (isRscEnv && hashToFileMap) {
+          const s = new MagicString(code);
+          const changed1 = applyServerReferenceWrapping(code, s, effectiveMap);
+          const changed2 = applyRegisterReferenceWrapping(
+            code,
+            s,
+            hashToFileMap,
+          );
+          if (changed1 || changed2) {
+            return {
+              code: s.toString(),
+              map: s.generateMap({
+                source: chunk.fileName,
+                includeContent: true,
+              }),
+            };
+          }
+          return null;
         }
-        return null;
-      }
 
-      // Non-RSC environments: only transform createServerReference calls
-      return transformServerReferences(code, chunk.fileName, effectiveMap);
+        // Non-RSC environments: only transform createServerReference calls
+        return transformServerReferences(code, chunk.fileName, effectiveMap);
+      } finally {
+        counterRender?.record(chunk.fileName, performance.now() - start);
+      }
     },
   };
 }

package/src/vite/plugins/expose-id-utils.ts

@@ -32,18 +32,22 @@ export function makeStubId(
 }
 
 /**
- * Generate an 8-char hex hash for an inline static handler call site.
- * Uses file path and line number (plus optional index for same-line collisions).
+ * Generate an 8-char hex hash for an inline handler call site.
+ *
+ * Keyed on the source-order INDEX of the call (the Nth inline `fnName(...)` in
+ * the file), NOT its line number. Line numbers shift between the prerender
+ * build context and the production build context (preceding transforms differ,
+ * e.g. plugin-react boilerplate), which would desync the prerender manifest key
+ * from the runtime handler id and break prerender/static freezing. The
+ * source-order index is invariant to line shifts; `fnName` keeps Static and
+ * Prerender inline ids from colliding at the same index.
  */
 export function hashInlineId(
   filePath: string,
-  lineNumber: number,
-  index?: number,
+  fnName: string,
+  index: number,
 ): string {
-  const input =
-    index !== undefined && index > 0
-      ? `${filePath}:${lineNumber}:${index}`
-      : `${filePath}:${lineNumber}`;
+  const input = `${filePath}:${fnName}:${index}`;
   return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
 }
 

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(
@@ -119,6 +158,28 @@ export function getCalledIdentifierFromCall(callExpr: any): string | null {
   return null;
 }
 
+/**
+ * plugin-react's dev Fast Refresh wraps exports whose function body uses
+ * hook-like calls in a signature-registration call. A loader/handle that calls
+ * `ctx.use(...)` trips this heuristic, so `export const X = createLoader(...)`
+ * becomes `export const X = _s(createLoader(...), "<sig>", true)` — the create*
+ * call is the first argument of an unrelated wrapper call. Unwrap a single such
+ * layer so ID injection still targets the inner create* call. The `$$id`
+ * assignment is appended after the whole statement (against the export local),
+ * which is unaffected by the wrapper since `_s(x)` returns `x`.
+ */
+function unwrapSignatureWrappedCall(init: any, fnNameSet: Set<string>): any {
+  if (init?.type !== "CallExpression") return init;
+  const directId = getCalledIdentifierFromCall(init);
+  if (directId && fnNameSet.has(directId)) return init;
+  const firstArg = init.arguments?.[0];
+  if (firstArg?.type === "CallExpression") {
+    const innerId = getCalledIdentifierFromCall(firstArg);
+    if (innerId && fnNameSet.has(innerId)) return firstArg;
+  }
+  return init;
+}
+
 export function collectCreateExportBindingsFallback(
   code: string,
   fnNames: string[],
@@ -196,7 +257,7 @@ export function collectCreateExportBindings(
 ): CreateExportBinding[] {
   if (!program) {
     try {
-      program = parseAst(code, { jsx: true });
+      program = parseAst(code, { lang: "tsx" });
     } catch {
       return collectCreateExportBindingsFallback(code, fnNames);
     }
@@ -212,10 +273,13 @@ export function collectCreateExportBindings(
     }
 
     for (const decl of varDecl.declarations ?? []) {
-      const calledIdentifier = getCalledIdentifierFromCall(decl?.init);
+      // Unwrap a Fast Refresh signature wrapper (`_s(createLoader(...), ...)`)
+      // so injection targets the inner create* call. Falls back to decl.init.
+      const callExpr = unwrapSignatureWrappedCall(decl?.init, fnNameSet);
+      const calledIdentifier = getCalledIdentifierFromCall(callExpr);
       if (
         decl?.id?.type !== "Identifier" ||
-        decl?.init?.type !== "CallExpression" ||
+        callExpr?.type !== "CallExpression" ||
         !calledIdentifier ||
         !fnNameSet.has(calledIdentifier)
       ) {
@@ -226,9 +290,8 @@ export function collectCreateExportBindings(
       const exportNames = exportMap.get(localName) ?? [];
       if (exportNames.length === 0) continue;
 
-      const callStart = decl.init.start as number;
-      const callEnd = decl.init.end as number;
-      const calleeEnd = decl.init.callee.end as number;
+      const callEnd = callExpr.end as number;
+      const calleeEnd = callExpr.callee.end as number;
 
       let openParenPos = -1;
       for (let i = calleeEnd; i < callEnd; i++) {
@@ -245,10 +308,10 @@ export function collectCreateExportBindings(
       bindings.push({
         localName,
         exportNames,
-        callExprStart: decl.init.start as number,
+        callExprStart: callExpr.start as number,
         callOpenParenPos: openParenPos,
         callCloseParenPos: closeParenPos,
-        argCount: decl.init.arguments?.length ?? 0,
+        argCount: callExpr.arguments?.length ?? 0,
         statementEnd,
       });
     }
@@ -282,9 +345,25 @@ export function collectCreateExportBindings(
 export function buildUnsupportedShapeWarning(
   filePath: string,
   fnName: string,
+  sites: Array<{ line: number; column: number }> = [],
 ): string {
-  return [
-    `[rsc-router] 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 }`,
@@ -292,5 +371,6 @@ export function buildUnsupportedShapeWarning(
     `Potentially unsupported forms include:`,
     `  - export let/var X = ${fnName}(...)`,
     `  - inline ${fnName}(...) calls`,
-  ].join("\n");
+  );
+  return lines.join("\n");
 }