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

package/src/missing-id-error.ts

@@ -0,0 +1,68 @@
+// Builds the error thrown when a create*() call (createLoader / createHandle)
+// reaches runtime without an injected $$id. The exposeInternalIds Vite transform
+// injects $$id only for an EXPORTED const declaration, so a non-exported const,
+// an `export let/var`, or an inline create*() call gets none. Previously this
+// failed with a terse message and no source location; this helper adds the
+// offending call site (best-effort, from the stack) and actionable guidance.
+//
+// The "<Kind> is missing $$id" prefix is preserved so existing tests and any
+// log scrapers keep matching. Dev-only: the call sites guard on
+// process.env.NODE_ENV === "development", so production builds fold the branch
+// away and tree-shake this module out.
+
+// create*() implementation files to skip when locating the user's call site.
+const SELF_FILES = new Set([
+  "missing-id-error",
+  "loader",
+  "loader.rsc",
+  "handle",
+]);
+
+/**
+ * Best-effort "path:line:column" of the user's create*() call, parsed from the
+ * current stack. Skips @rangojs/router internals and node_modules. Returns
+ * undefined if nothing usable is found (stack parsing is inherently fragile).
+ */
+function findUserCallSite(): string | undefined {
+  try {
+    const stack = new Error().stack;
+    if (!stack) return undefined;
+    for (const frame of stack.split("\n").slice(1)) {
+      const m = frame.match(
+        /(?:\(|@|\s)(?:file:\/\/)?((?:\/|[A-Za-z]:[\\/])[^()\s]+?\.(?:ts|tsx|js|jsx|mts|cts)):(\d+):(\d+)\)?/,
+      );
+      if (!m) continue;
+      const path = m[1];
+      if (path.includes("node_modules") || path.includes("@rangojs/router")) {
+        continue;
+      }
+      const base = path
+        .split(/[\\/]/)
+        .pop()!
+        .replace(/\.(?:ts|tsx|js|jsx|mts|cts)$/, "");
+      if (SELF_FILES.has(base)) continue;
+      return `${path}:${m[2]}:${m[3]}`;
+    }
+  } catch {
+    // best-effort only
+  }
+  return undefined;
+}
+
+export function missingInjectedIdError(
+  kind: "Loader" | "Handle",
+  fnName: "createLoader" | "createHandle",
+): Error {
+  const site = findUserCallSite();
+  const at = site ? ` (created at ${site})` : "";
+  return new Error(
+    `[rango] ${kind} is missing $$id${at}.\n` +
+      `The @rangojs/router:expose-internal-ids Vite transform injects ${fnName}()'s ` +
+      `stable $$id from an EXPORTED const declaration only:\n` +
+      `  export const X = ${fnName}(...)\n` +
+      `  const X = ${fnName}(...); export { X }\n` +
+      `A non-exported const, an \`export let/var\`, or an inline ${fnName}(...) ` +
+      `call gets no $$id — export it as \`export const\`. (A matching ` +
+      `"Unsupported ${fnName} shape" warning names the exact file:line.)`,
+  );
+}

package/src/reverse.ts

@@ -231,47 +231,50 @@ export type LocalReverseParams<TPattern extends string> =
   };
 
 /**
- * Type-safe local reverse function with dot-prefixed names only.
+ * Type-safe local reverse function.
  *
  * Returned by `useReverse(routes)` on the client. The route map is the
  * exposure boundary (a generated `routes` from a `urls()` module) and the
- * scope is implicit from that import — there is no global namespace, so
- * names must be dot-prefixed to mirror `ctx.reverse(".name")`.
+ * scope is implicit from that import. Names may be written with or without a
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
+ * there is no separate global namespace here, so it carries no meaning.
  *
  * @example
  * ```typescript
  * const reverse = useReverse(blogRoutes);
- * reverse(".index");                         // ✓ no params
- * reverse(".post", { postId: "hello" });     // ✓ with params
- * reverse(".search", {}, { q: "hi" });       // ✓ with search schema
- * reverse(".typo");                          // ✗ compile error
+ * reverse("index");                          // ✓ no params (dot optional)
+ * reverse(".index");                         // ✓ identical to the above
+ * reverse("post", { postId: "hello" });      // ✓ with params
+ * reverse("search", {}, { q: "hi" });        // ✓ with search schema
+ * reverse("typo");                           // ✗ compile error
  * ```
  */
 export type LocalReverseFunction<TLocalRoutes> = {
   /**
-   * Dot-prefixed local route without params
+   * Route without params (leading dot optional)
    */
   <TName extends keyof TLocalRoutes & string>(
     name: IsEmptyObject<
       ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
     > extends true
-      ? `.${TName}`
+      ? TName | `.${TName}`
       : never,
   ): string;
 
   /**
-   * Dot-prefixed local route with params
+   * Route with params (leading dot optional)
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: `.${TName}`,
+    name: TName | `.${TName}`,
     params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
   ): string;
 
   /**
-   * Dot-prefixed local route with params and search
+   * Route with params and search (leading dot optional)
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: `.${TName}`,
+    name: TName | `.${TName}`,
     params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
     search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
   ): string;

package/src/route-definition/dsl-helpers.ts

@@ -866,8 +866,11 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
 };
 
 /**
- * Transition helper - attaches a ViewTransition config to the current entry
- * or wraps a group of routes in a transparent layout with ViewTransition
+ * Transition helper - opts the entry (or a wrapped group of routes) into
+ * transition-driven navigation by attaching a TransitionConfig. This drives the
+ * commit through startTransition (content hold on all React versions) and, on
+ * experimental React, places a `<ViewTransition>` boundary unless
+ * `viewTransition: false`. See skills/view-transitions for the matrix.
  */
 const transition = (
   configOrChildren?: TransitionConfig | (() => UseItems<AllUseItems>),

package/src/route-definition/helpers-types.ts

@@ -449,19 +449,30 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
     ): CacheItem;
   };
   /**
-   * Attach a ViewTransition boundary to the current segment or a group of routes,
-   * and opt the route into same-route stale-while-revalidate navigation.
-   *
-   * Two effects, both opt-in via this helper:
-   * - Same-route navigation (same route, different params, e.g. /product/1 ->
-   *   /product/2) reconciles the route subtree instead of remounting it, so the
-   *   previous content is held while the new loader resolves rather than flashing
-   *   the route's loading() skeleton. This works on ALL React versions (it is
-   *   plain startTransition + Suspense; see segment-system.tsx inTransitionScope).
-   * - On React experimental, the segment content is additionally wrapped in
-   *   `<ViewTransition>`, so the held same-route swap animates (update/share
-   *   morph) and cross-route swaps animate exit/enter. The animation layer is a
-   *   no-op on stable React; the content-hold is not.
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * `transition()` does two independent things, and you choose how far to go:
+   * 1. startTransition (ALL React versions): the navigation commit is driven
+   *    through React's startTransition, so a same-route nav (same route,
+   *    different params, e.g. /product/1 -> /product/2) holds the previous
+   *    content while the new loader resolves instead of flashing the route's
+   *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
+   *    also the precondition for any view-transition animation.
+   * 2. <ViewTransition> (experimental React only): the segment content is also
+   *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
+   *    Layered on by default; pass { viewTransition: false } to keep #1 without
+   *    the router boundary (and place your own <ViewTransition> instead).
+   *
+   * A view transition cannot fire without a startTransition, so the meaningful
+   * choices are (see skills/view-transitions for the full matrix):
+   * - no transition()                         -> neither (remount + skeleton)
+   * - transition({ viewTransition: false })   -> startTransition only (hold)
+   * - transition({}) / transition({ enter… })  -> startTransition + ViewTransition
+   *
+   * Precedence: a bare transition({}) inherits createRouter({ viewTransition })
+   * (default "auto"); an explicit per-route `viewTransition` always wins. So
+   * transition({}) is startTransition + ViewTransition under the default and
+   * startTransition only when the router sets viewTransition: false.
    *
    * ```typescript
    * // Attach to a single route
@@ -475,13 +486,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   path("/about", AboutPage),
    * ])
    *
-   * // Direction-aware transitions
-   * transition({
-   *   enter: { "navigation": "slide-right", "navigation-back": "slide-left" },
-   *   exit: { "navigation": "slide-left", "navigation-back": "slide-right" },
-   * })
+   * // Hold content + drive view transitions, but place no router boundary:
+   * path("/product/:id", ProductPage, { name: "product" }, () => [
+   *   transition({ viewTransition: false }),
+   * ])
    * ```
-   * @param config - ViewTransition configuration (enter, exit, update, share, default, name)
+   * @param config - ViewTransition configuration (enter, exit, update, share,
+   *   default, name) plus `viewTransition: "auto" | false` to toggle the router
+   *   boundary (createRouter({ viewTransition }) sets the app-wide default)
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {

package/src/router/router-options.ts

@@ -357,6 +357,30 @@ export interface RangoOptions<TEnv = any> {
    */
   theme?: import("../theme/types.js").ThemeConfig | true;
 
+  /**
+   * Default for whether the router wraps `transition()` segments in its own
+   * React `<ViewTransition>` boundary (experimental React only).
+   *
+   * - "auto" (default): every route/layout that opts in via `transition()`
+   *   gets a router-owned cross-fade.
+   * - false: the router never places its own boundary. Routes that use
+   *   `transition()` still drive navigation through startTransition (so loaders
+   *   hold instead of flashing a skeleton) and still let consumer-placed
+   *   `<ViewTransition>` elements animate — the router just contributes no
+   *   cross-fade of its own. This is the "router triggers, you place the
+   *   transitions" model.
+   *
+   * A per-segment `transition({ viewTransition })` overrides this default.
+   *
+   * @example
+   * ```typescript
+   * // App-wide: drive + hold, but never auto-wrap. Place <ViewTransition>
+   * // yourself in components where you want a morph.
+   * const router = createRouter<AppEnv>({ viewTransition: false });
+   * ```
+   */
+  viewTransition?: "auto" | false;
+
   /**
    * URL patterns to register with the router.
    *

package/src/router/segment-resolution/fresh.ts

@@ -28,6 +28,7 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
@@ -224,7 +225,10 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       belongsToRoute: false,
       layoutName: entry.id,
@@ -359,7 +363,10 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component: component ?? null,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       belongsToRoute: true,
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
@@ -443,7 +450,10 @@ export async function resolveOrphanLayout<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+    ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
@@ -565,7 +575,10 @@ export async function resolveParallelEntry<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
       belongsToRoute,

package/src/router/segment-resolution/revalidation.ts

@@ -39,6 +39,7 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
@@ -593,7 +594,10 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
       _handlerRan: handlerRan,
@@ -803,7 +807,10 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     index: 0,
     component: resolvedComponent,
     loading: entry.loading === false ? null : entry.loading,
-    transition: entry.transition,
+    transition: applyViewTransitionDefault(
+      entry.transition,
+      deps.viewTransitionDefault,
+    ),
     params,
     belongsToRoute,
     ...(entry.type === "layout" || entry.type === "cache"
@@ -1137,7 +1144,10 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+    ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
@@ -1294,7 +1304,10 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
       _handlerRan: handlerRan,

package/src/router/segment-resolution/view-transition-default.ts

@@ -0,0 +1,36 @@
+/**
+ * View-transition boundary default resolution.
+ *
+ * Kept in its own module (rather than helpers.ts) because several resolution
+ * tests mock helpers.ts with an explicit export list; a shared util here is
+ * never mocked, so the fresh and revalidation paths always get the real
+ * implementation.
+ */
+
+import type { EntryData } from "../../server/context";
+
+/**
+ * Resolve the effective `viewTransition` for a segment's transition config.
+ *
+ * The per-segment value (set via the transition() DSL) always wins. When it is
+ * unset, the router-level createRouter({ viewTransition }) default is stamped
+ * in so the render gate reads the boundary decision off the segment — server
+ * and client, via the serialized segment — without the router option being
+ * threaded to the client. Only `false` is ever stamped; an unset (or "auto")
+ * value is left untouched because it already means "wrap" at the gate, which
+ * also avoids needless object allocation and payload growth. Used by both the
+ * fresh and revalidation resolution paths.
+ */
+export function applyViewTransitionDefault(
+  transition: EntryData["transition"],
+  viewTransitionDefault: "auto" | false | undefined,
+): EntryData["transition"] {
+  if (!transition) return transition;
+  if (
+    transition.viewTransition === undefined &&
+    viewTransitionDefault === false
+  ) {
+    return { ...transition, viewTransition: false };
+  }
+  return transition;
+}

package/src/router/types.ts

@@ -98,6 +98,14 @@ export interface SegmentResolutionDeps<TEnv = any> {
   ) => ReactNode | NotFoundBoundaryHandler | null;
   notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+  /**
+   * Router-level default for the per-segment `transition({ viewTransition })`
+   * flag, from createRouter({ viewTransition }). Resolved into each segment's
+   * transition config during resolution (only `false` is stamped) so the render
+   * gate reads the boundary decision off the segment on both server and client.
+   * Undefined is treated as "auto" (wrap).
+   */
+  viewTransitionDefault?: "auto" | false;
 }
 
 /**

package/src/router.ts

@@ -155,6 +155,7 @@ export function createRouter<TEnv = any>(
     timeouts: timeoutsOption,
     onTimeout,
     originCheck: originCheckOption,
+    viewTransition: viewTransitionOption = "auto",
   } = options;
 
   // Normalize basename: ensure leading slash, strip trailing slash.
@@ -534,6 +535,7 @@ export function createRouter<TEnv = any>(
     findNearestNotFoundBoundary,
     notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies

package/src/segment-system.tsx

@@ -99,8 +99,11 @@ function createViewTransitionBoundary(
   transition: NonNullable<ResolvedSegment["transition"]>,
   children: ReactNode,
 ): ReactNode {
+  // `viewTransition` is a router-specific flag (boundary opt-out), not a React
+  // <ViewTransition> prop — strip it so it never reaches React.
+  const { viewTransition: _viewTransition, ...vtProps } = transition;
   return createElement(ReactViewTransition, {
-    ...transition,
+    ...vtProps,
     children,
   });
 }
@@ -319,12 +322,25 @@ export async function renderSegments(
     // 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.).
+    //
+    // `transition.viewTransition === false` opts out of the router-owned
+    // boundary only. Driving (the startTransition wrap in browser/partial-update.ts
+    // and the param-agnostic key/hold below) keys off transition *presence*, not
+    // this flag, so a boundary-less transition still holds content and lets
+    // consumer-placed <ViewTransition> elements animate. The global
+    // createRouter({ viewTransition }) default is resolved into this field
+    // during segment resolution (only `false` is stamped; unset/"auto" is left
+    // as-is and means "wrap"), so this gate needs no router-option threading.
     let outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
 
     const transition = node.segment.transition;
 
-    if (ReactViewTransition && transition) {
+    if (
+      ReactViewTransition &&
+      transition &&
+      transition.viewTransition !== false
+    ) {
       if (node.segment.type === "layout") {
         outletContent = wrapDefaultOutletContent(outletContent, transition);
       } else {

package/src/types/segments.ts

@@ -10,7 +10,10 @@ export type ViewTransitionClass = Record<string, string> | string;
 
 /**
  * Configuration for React's <ViewTransition> component.
- * Maps directly to ViewTransitionProps (minus children/ref/callbacks).
+ *
+ * The phase fields (enter/exit/update/share/default/name) map directly to
+ * ViewTransitionProps (minus children/ref/callbacks). The `viewTransition`
+ * field is router-specific and is stripped before the config reaches React.
  */
 export interface TransitionConfig {
   enter?: ViewTransitionClass;
@@ -19,6 +22,20 @@ export interface TransitionConfig {
   share?: ViewTransitionClass;
   default?: ViewTransitionClass;
   name?: string;
+  /**
+   * Whether the router wraps this segment's content in its own
+   * <ViewTransition> boundary.
+   *
+   * - "auto" (default): the router places the boundary, producing the
+   *   router-owned cross-fade described by the phase fields above.
+   * - false: the router places no boundary. The navigation commit is still
+   *   driven through startTransition (so loaders hold instead of flashing a
+   *   skeleton, and consumer-placed <ViewTransition> elements still animate),
+   *   but the router contributes no cross-fade of its own.
+   *
+   * When unset, inherits the createRouter({ viewTransition }) default.
+   */
+  viewTransition?: "auto" | false;
 }
 
 /**

package/src/urls/path-helper-types.ts

@@ -350,7 +350,15 @@ export type PathHelpers<TEnv> = {
   };
 
   /**
-   * Attach a ViewTransition boundary to the current segment or a group of routes
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * Two independent layers: (1) startTransition, on all React versions, holds
+   * the previous content across a same-route nav (no skeleton flash) and is the
+   * precondition for any view transition; (2) on experimental React, an
+   * additional `<ViewTransition>` boundary cross-fades/morphs the swap. Pass
+   * `{ viewTransition: false }` to keep #1 without the router boundary. A view
+   * transition cannot fire without a startTransition. See
+   * skills/view-transitions for the startTransition x ViewTransition matrix.
    */
   transition: {
     (): TransitionItem;

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");
 }