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

package/skills/react-compiler/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: react-compiler
+description: Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.
+argument-hint:
+---
+
+# React Compiler
+
+React Compiler is **opt-in** in Rango. The plugin pipeline is fully compatible —
+you just add one more plugin. The catch on a current Rango stack (Vite 8 +
+`@vitejs/plugin-react` v6) is that **v6 dropped its internal Babel for oxc**, so
+the way the React docs and most blog posts show it — `react({ babel: { plugins:
+[...] } })` — silently does nothing. The compiler has to be its own top-level
+plugin.
+
+## The shape (read first)
+
+- The compiler is a **Babel** plugin, run via
+  [`@rolldown/plugin-babel`](https://www.npmjs.com/package/@rolldown/plugin-babel)
+  with `reactCompilerPreset()` from `@vitejs/plugin-react`.
+- **Ordering is load-bearing:** put `babel(...)` **after `react()`** and
+  **before the plugin that supplies `@vitejs/plugin-rsc`**. In a default Rango
+  app that plugin is `rango()` itself; in a Cloudflare app it is
+  `@cloudflare/vite-plugin`.
+- **It is client-only.** `reactCompilerPreset()` gates itself to the client
+  environment. Server/RSC components are not compiled, and that is the upstream
+  example's behavior — not a Rango limitation. See
+  [What gets compiled](#what-gets-compiled-client-only).
+- **Rango's build-time prerender is unaffected.** You do not need to do anything
+  special. See [Prerender](#interaction-with-build-time-prerender).
+
+## Step 1: Install
+
+```bash
+pnpm add -D @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
+# TypeScript users also want the Babel core types:
+pnpm add -D @types/babel__core
+```
+
+React 19 ships `react/compiler-runtime` in-tree, so there is **no** extra runtime
+to install and **no** `target` option to set. Only pass `target: '17' | '18'` to
+`reactCompilerPreset()` if you are on an older React.
+
+## Step 2: Wire it in
+
+### Default (non-Cloudflare) app
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    babel({ presets: [reactCompilerPreset()] }),
+    rango(), // supplies @vitejs/plugin-rsc
+  ],
+});
+```
+
+### Cloudflare app
+
+```ts
+// vite.config.ts
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+import { defineConfig } from "vite";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    babel({ presets: [reactCompilerPreset()] }),
+    rango({ preset: "cloudflare" }),
+    cloudflare({
+      /* ... */
+    }), // supplies @vitejs/plugin-rsc
+  ],
+});
+```
+
+## What gets compiled (client-only)
+
+`reactCompilerPreset()` carries
+`rolldown.applyToEnvironmentHook: (env) => env.config.consumer === "client"`, so
+even though the babel plugin is top-level, the transform runs **only in the
+`client` environment**:
+
+| Environment | `consumer` | Compiled? |
+| ----------- | ---------- | --------- |
+| client      | `client`   | Yes       |
+| ssr         | `server`   | No        |
+| rsc         | `server`   | No        |
+
+This matches the upstream `@vitejs/plugin-rsc` example. If you genuinely need to
+compile **server** components, you would have to invoke
+`babel-plugin-react-compiler` yourself without the preset's
+`applyToEnvironmentHook` — that is outside what the example does and is not
+covered here.
+
+## Options
+
+`reactCompilerPreset()` forwards to `babel-plugin-react-compiler`:
+
+| Option                          | Effect                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `compilationMode: 'annotation'` | Compile only components marked with the `"use memo"` directive, not every eligible one |
+| `target: '17' \| '18'`          | Emit `react-compiler-runtime` calls for React < 19. Omit on React 19+.                 |
+
+## Interaction with build-time prerender
+
+Nothing to configure. Rango's discovery/prerender step runs a throwaway temp Vite
+server (`createTempRscServer`) that forwards only your **resolution** plugins
+(`resolveId` / `load`). A pure transform plugin like `@rolldown/plugin-babel` is
+intentionally **not** forwarded — and that is correct: the temp runner only
+produces **data** (serialized Flight payloads + the route manifest), not shipped
+code, and React Compiler is a memoization-only transform that does not change
+rendered output. Your shipped client bundle still gets compiled, because the
+babel plugin lives in your app's top-level plugin array alongside `react()`.
+
+## Step 3: Verify the compiler actually ran
+
+A compiled module imports the cache allocator from `react/compiler-runtime` and
+calls `_c(n)`. Those two appear in **every** compiled module, so they are the
+reliable per-module signal in dev:
+
+```bash
+pnpm dev
+# fetch any client component module straight from Vite and look for the markers:
+curl -s "http://localhost:5173/src/components/SomeClientComponent.tsx" \
+  | grep -E "compiler-runtime|_c\("
+```
+
+For a production build, grep the built client bundle for the compiler's
+input-independent cache check, which has a **zero baseline** without the compiler:
+
+```bash
+pnpm build
+grep -r "Symbol.for(\"react.memo_cache_sentinel\")" dist/client/assets/ | head
+```
+
+Note the **comparison** form `$[i] === Symbol.for("react.memo_cache_sentinel")`
+is only emitted for components with input-independent JSX, so it is reliable over
+the **whole** client bundle, not necessarily in one chosen module. (React core
+also defines that symbol once with a single `=` assignment, so count comparisons,
+not the bare string.) Run the same grep over `dist/rsc` / `dist/ssr` and you
+should find **none** — that is the client-only contract.
+
+## Troubleshooting
+
+| Symptom                                                               | Cause / fix                                                                                                                                 |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Nothing is compiled; no `compiler-runtime` import anywhere            | You used `react({ babel: { plugins: [...] } })`. plugin-react v6 has no internal Babel — add `@rolldown/plugin-babel` as its own plugin.    |
+| Client compiled, but server/RSC components are not                    | Expected. `reactCompilerPreset()` is client-only (see the table). Not a bug.                                                                |
+| `Cannot find module 'babel-plugin-react-compiler'` (or `@babel/core`) | Install the peer deps from Step 1; they are not bundled by `reactCompilerPreset()`.                                                         |
+| Build pulls in `react-compiler-runtime`                               | You set `target: '17'`/`'18'` on React 19. Drop `target` — React 19 ships `react/compiler-runtime` in-tree.                                 |
+| Output looks compiled but a component misbehaves                      | The component likely breaks the Rules of React. Fix the component, or scope the compiler with `compilationMode: 'annotation'` while you do. |
+
+## Reference
+
+A worked, tested wiring (dev + production e2e markers, incl. the client-only
+contract) lives in the `@rangojs/router` repo: `docs/react-compiler.md` and the
+`react-compiler.test.ts` files under `e2e/e2e-basic`, `tests/cloudflare-basic`,
+and `tests/vite-rsc-demo`.

package/skills/view-transitions/SKILL.md

@@ -6,11 +6,33 @@ argument-hint: [layout|route|parallel|intercept]
 
 # View Transitions
 
-Rango wires React's experimental `<ViewTransition>` into the segment tree via the `transition()` helper. Each segment can declare its own transition config; rango wraps it at the right tree position so navigations morph the right pieces and modals do not.
+`transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
-> Requires React experimental (the build that exports `<ViewTransition>` and `addTransitionType`). With stable React, `transition()` is a no-op — your routes still render, just without view-transition wrappers.
+1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions.
+2. **`<ViewTransition>` (the animation, layered on top).** On experimental React, rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs experimental React; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
-## What `transition()` does
+> The `<ViewTransition>` layer requires React experimental (the build that exports `<ViewTransition>` / `addTransitionType`). On stable React that layer is a no-op — but the `startTransition` driving (content hold) still applies.
+
+## Purpose: `startTransition` vs `<ViewTransition>`
+
+These are two **independent** mechanisms. `startTransition` controls _fallbacks_ (hold the old content vs. flash the Suspense skeleton) and is what lets a view transition fire at all; the `<ViewTransition>` boundary is the _visual cross-fade_.
+
+|                            | `startTransition` **OFF**                                                      | `startTransition` **ON**                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| **`<ViewTransition>` OFF** | plain nav — remount on param change, skeleton flash, no animation              | **hold** content (no skeleton flash); a consumer-placed `<ViewTransition>` still morphs; no router cross-fade |
+| **`<ViewTransition>` ON**  | **impossible** — React never activates `<ViewTransition>` outside a Transition | hold + router cross-fade                                                                                      |
+
+The bottom-left cell is the key constraint: a view transition cannot exist without a `startTransition`. So once you reach for `transition()`, the only real choice is _startTransition_ vs _startTransition + ViewTransition_:
+
+| What you want                          | Config                                              | Effect                                                                                                 |
+| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| nothing (default nav)                  | no `transition()`                                   | remount + skeleton on param change                                                                     |
+| `startTransition` only                 | `transition({ viewTransition: false })`             | hold content; place your own `<ViewTransition>` where you want it                                      |
+| `startTransition` + `<ViewTransition>` | `transition({})` / `transition({ enter, exit, … })` | hold + router cross-fade (experimental React; on stable it degrades to the `startTransition`-only row) |
+
+`createRouter({ viewTransition: "auto" \| false })` sets the app-wide default for the third row; a per-segment `viewTransition` wins. See [Opting out of the router boundary](#opting-out-of-the-router-boundary-place-your-own-viewtransition) for the full opt-out story.
+
+## What `transition()` does (wrap location)
 
 `transition(config)` attaches a [`TransitionConfig`](#transitionconfig) to the surrounding entry. Where the wrap actually lands in the rendered React tree depends on the segment type:
 
@@ -186,12 +208,72 @@ interface TransitionConfig {
   share?: string | Record<string, string>;
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
+  viewTransition?: "auto" | false; // boundary opt-out (see below)
 }
 ```
 
 - `default` is the catch-all if a phase-specific prop is unset.
 - The object form keys are React transition types tagged by rango: `"navigation"` (forward navigations), `"navigation-back"` (popstate cache restores), and `"action"` (partial-update action/refetch paths only — see the caveat in "Direction-aware transitions").
 - `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
+- `viewTransition` toggles whether rango places its own `<ViewTransition>` boundary. `"auto"` (default) wraps as described above; `false` opts out — see the next section.
+
+## Opting out of the router boundary (place your own `<ViewTransition>`)
+
+By default a `transition()` segment gets a rango-placed `<ViewTransition>` boundary — a cross-fade of the whole outlet/route. If you'd rather animate specific elements yourself (place `<ViewTransition name="...">` in your components), set `viewTransition: false`. The router then contributes **no boundary of its own** but still:
+
+- drives the navigation commit through `startTransition` (so React runs `document.startViewTransition`, and your own `<ViewTransition>` elements animate on navigation — driving is what they need, not a router boundary), and
+- holds same-route content (stale-while-revalidate; no skeleton flash).
+
+```tsx
+// Router drives the transition + holds content, but places NO cross-fade.
+// Only your <ViewTransition name="hero"> morphs.
+urls(({ path, transition }) => [
+  path("/product/:id", ProductPage, { name: "product" }, () => [
+    transition({ viewTransition: false }),
+  ]),
+]);
+
+// ProductPage renders the boundary itself, exactly where it's wanted:
+function ProductPage() {
+  return (
+    <ViewTransition name="hero">
+      <img src={cover} />
+    </ViewTransition>
+  );
+}
+```
+
+This is the rango analogue of the "router triggers, you place the names" model used by React Router / TanStack: rango guarantees navigations run inside a React transition; you own the boundaries.
+
+**App-wide default.** Flip the default for every `transition()` segment at the router level. A per-segment `viewTransition` still overrides it.
+
+```ts
+const router = createRouter<AppEnv>({ viewTransition: false });
+// Now `transition({})` drives + holds but places no boundary anywhere.
+// Re-enable a router boundary on one route with transition({ viewTransition: "auto" }).
+```
+
+**Precedence (per-route vs router default).** A bare `transition({})` has no per-route `viewTransition`, so it inherits the router default (`"auto"` unless `createRouter({ viewTransition: false })`). An explicit per-route value always wins. The `viewTransition` flag only toggles the boundary — `startTransition` driving and content-hold are on in every row below (they key off `transition()` presence, not this flag):
+
+| per-route (`transition(...)`)            | router (`createRouter`) | resolved boundary        | result      |
+| ---------------------------------------- | ----------------------- | ------------------------ | ----------- |
+| `transition({})` (unset)                 | `"auto"` (default)      | wrap                     | **ST + VT** |
+| `transition({})` (unset)                 | `false`                 | no wrap                  | **ST only** |
+| `transition({ viewTransition: "auto" })` | `"auto"`                | wrap                     | ST + VT     |
+| `transition({ viewTransition: "auto" })` | `false`                 | wrap (per-route wins)    | **ST + VT** |
+| `transition({ viewTransition: false })`  | `"auto"`                | no wrap (per-route wins) | **ST only** |
+| `transition({ viewTransition: false })`  | `false`                 | no wrap                  | ST only     |
+
+On stable React the "VT" column is always a no-op (there is no `<ViewTransition>`), so every row collapses to its `startTransition`-only behavior there.
+
+| Config                                               | Router boundary  | startTransition driving (no skeleton flash) | Your own `<ViewTransition name>`   |
+| ---------------------------------------------------- | ---------------- | ------------------------------------------- | ---------------------------------- |
+| no `transition()`                                    | —                | no                                          | does not fire on nav               |
+| `transition({})` / `{ viewTransition: "auto" }`      | yes (cross-fade) | yes                                         | fires, under the router cross-fade |
+| `transition({ viewTransition: false })`              | none             | yes                                         | fires alone                        |
+| global `viewTransition: false`, route `transition()` | none             | yes                                         | fires alone                        |
+
+> On **stable** React there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
 ## Recommendations
 

package/src/browser/react/use-reverse.ts

@@ -34,11 +34,18 @@ function joinMount(mount: string, pattern: string): string {
 /**
  * Mount-aware reverse function for a locally-imported `routes` map.
  *
- * Resolves dot-prefixed route names against the passed `routes` (typically
- * a generated `routes` from a `urls()` module's `.gen.ts`), prefixes the
- * result with the surrounding `include()` mount path, and substitutes
- * params — auto-filling from the current matched route's params and
- * letting explicit params override.
+ * The `routes` map you pass IS the scope: `reverse("name")` looks the name up
+ * in that map (verbatim), prefixes the result with the surrounding `include()`
+ * mount path via `useMount()`, and substitutes params — auto-filling from the
+ * current matched route's params, with explicit params overriding. A module's
+ * components can therefore reverse their own routes without knowing where the
+ * module is mounted: include it under any prefix and the URLs resolve correctly.
+ *
+ * The leading dot is optional and cosmetic: `reverse("post")` and
+ * `reverse(".post")` resolve identically. The dot exists only as a readability
+ * convention and for parity with `ctx.reverse(".name")` on the server; here the
+ * passed map is the scope, so there is no separate global namespace to
+ * disambiguate and the dot carries no meaning.
  *
  * @example
  * ```tsx
@@ -50,8 +57,8 @@ function joinMount(mount: string, pattern: string): string {
  *   const reverse = useReverse(blogRoutes);
  *   return (
  *     <>
- *       <Link to={reverse(".index")}>Blog</Link>
- *       <Link to={reverse(".post", { postId: "hello" })}>Post</Link>
+ *       <Link to={reverse("index")}>Blog</Link>
+ *       <Link to={reverse("post", { postId: "hello" })}>Post</Link>
  *     </>
  *   );
  * }
@@ -69,14 +76,14 @@ export function useReverse<const TRoutes extends LocalRouteMap>(
       explicitParams?: Record<string, string | undefined>,
       search?: Record<string, unknown>,
     ): string => {
-      if (!name.startsWith(".")) {
-        throw new Error(`Local route names must start with ".": "${name}"`);
-      }
-      const lookupName = name.slice(1);
+      // The leading dot is optional. The passed map IS the scope, so a dot to
+      // signal "local" is unnecessary — "detail" and ".detail" resolve the same.
+      // A dot is accepted (and stripped) for readability / ctx.reverse parity.
+      const lookupName = name.startsWith(".") ? name.slice(1) : name;
       const entry = (routes as LocalRouteMap)[lookupName];
       const pattern = getPattern(entry);
       if (pattern === undefined) {
-        throw new Error(`Unknown local route: "${name}"`);
+        throw new Error(`Unknown route: "${name}"`);
       }
 
       const joined = joinMount(mount, pattern);

package/src/build/route-types/router-processing.ts

@@ -15,6 +15,7 @@ import {
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
+import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
@@ -38,6 +39,8 @@ function countPublicRouteEntries(source: string): number {
 }
 
 const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+// Global variant for the code-region scan (firstCodeMatchIndex sets lastIndex).
+const ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 
 function isRoutableSourceFile(name: string): boolean {
   return (
@@ -90,7 +93,17 @@ function findRouterFilesRecursive(
 
     try {
       const source = readFileSync(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      // Fast path: most files contain no `createRouter(` at all, so the cheap
+      // raw regex short-circuits before the code-region scan. Only a file that
+      // mentions the token (real call OR a comment/string mention) is rescanned
+      // over code regions — allocation-free, never building a stripped copy —
+      // so a mention inside a comment or string is not mistaken for a real
+      // router file (which previously triggered a spurious "Multiple routers
+      // found" error).
+      if (
+        ROUTER_CALL_PATTERN.test(source) &&
+        firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0
+      ) {
         routerFilesInDir.push(fullPath);
       }
     } catch {

package/src/build/route-types/source-scan.ts

@@ -0,0 +1,118 @@
+// Allocation-light, linear-time source scanning for the build-time scanners.
+//
+// The router-file scanner, the HMR relevance check, and the unsupported-shape
+// warning all need to know whether a token like `createRouter(` / `createLoader(`
+// appears in REAL code versus inside a comment or string literal. Rather than
+// build a full comment/string-stripped copy of the source (which on a large
+// file allocates an O(n) string plus, naively, a per-char array), these helpers
+// run the regex over the whole source ONCE (the engine sweeps left-to-right,
+// O(n)) and classify each match's offset with a forward, O(1)-memory cursor that
+// advances monotonically across the source.
+//
+// Time: O(n) — one native regex sweep plus one forward classification pass.
+// Memory: O(1) for the boolean check; O(#matches) for the index list. No
+// stripped copy and no per-char array are ever materialized.
+//
+// Pragmatic scanner, not a full tokenizer: regex literals are not special-cased
+// (a target token inside one is implausible) and template interpolations are
+// treated as opaque string content. One intentional consequence: a token whose
+// match would only complete by treating an interleaved comment as whitespace
+// (e.g. `createRouter /* x */ (`) is not detected — real calls never interleave
+// a comment between the callee and its arguments.
+
+// JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
+function isLineTerminator(ch: string): boolean {
+  const c = ch.charCodeAt(0);
+  // LF, CR, LS (U+2028), PS (U+2029)
+  return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
+}
+
+/**
+ * Build a classifier that answers "is offset `q` in code (not a comment or
+ * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
+ * so a full left-to-right sequence of queries costs O(n) total with O(1) memory.
+ */
+function makeCodeClassifier(code: string): (q: number) => boolean {
+  const n = code.length;
+  let i = 0; // forward cursor: everything before `i` is already classified
+  let skipStart = -1; // last detected comment/string region (cache)
+  let skipEnd = -1;
+
+  return (q: number): boolean => {
+    if (q >= skipStart && q < skipEnd) return false; // q in the cached region
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        // Comment/string region [i, end). `q >= i` here (loop condition).
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true; // reached q in code mode
+  };
+}
+
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export function firstCodeMatchIndex(code: string, pattern: RegExp): number {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export function codeMatchIndices(code: string, pattern: RegExp): number[] {
+  const inCode = makeCodeClassifier(code);
+  const indices: number[] = [];
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}

package/src/handle.ts

@@ -1,3 +1,5 @@
+import { missingInjectedIdError } from "./missing-id-error.js";
+
 /**
  * Handle definition for accumulating data across route segments.
  *
@@ -96,11 +98,7 @@ export function createHandle<TData, TAccumulated = TData[]>(
   const handleId = __injectedId ?? "";
 
   if (!handleId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rango] Handle is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)",
-    );
+    throw missingInjectedIdError("Handle", "createHandle");
   }
 
   const collectFn =

package/src/loader.rsc.ts

@@ -21,6 +21,7 @@ import {
   registerFetchableLoader,
   getFetchableLoader,
 } from "./server/fetchable-loader-store.js";
+import { missingInjectedIdError } from "./missing-id-error.js";
 
 export { getFetchableLoader };
 
@@ -53,11 +54,7 @@ export function createLoader<T>(
   const loaderId = __injectedId || "";
 
   if (!loaderId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rango] Loader is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the loader is exported with: export const MyLoader = createLoader(...)",
-    );
+    throw missingInjectedIdError("Loader", "createLoader");
   }
 
   // If not fetchable, store fn in registry (for SSR ctx.use() resolution)

package/src/loader.ts

@@ -18,6 +18,7 @@ import type {
   LoaderDefinition,
   LoaderFn,
 } from "./types.js";
+import { missingInjectedIdError } from "./missing-id-error.js";
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
@@ -46,11 +47,7 @@ export function createLoader<T>(
   const loaderId = __injectedId || "";
 
   if (!loaderId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rango] Loader is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the loader is exported with: export const MyLoader = createLoader(...)",
-    );
+    throw missingInjectedIdError("Loader", "createLoader");
   }
 
   return {

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.)`,
+  );
+}