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

package/skills/use-cache/SKILL.md

@@ -68,7 +68,10 @@ createRouter({
 
 - `"use cache"` (no name) resolves to `default`.
 - `"use cache: short"` resolves to the `short` profile.
-- Unknown profile names throw at build/boot time.
+- Unknown profile names throw at runtime, on the first invocation of the cached
+  function (the Vite transform does not validate names at build/boot). The error
+  is actionable -- it names the missing profile and shows the `createRouter({
+cacheProfiles: { ... } })` entry to add.
 
 ## Cache Key
 
@@ -77,18 +80,33 @@ use-cache:{functionId}:{serializedArgs}
 ```
 
 - `functionId` -- stable ID from Vite transform (module path + export name).
-- `serializedArgs` -- non-tainted arguments serialized via RSC `encodeReply()`.
+- `serializedArgs` -- key-generating arguments serialized via RSC `encodeReply()`.
+
+When there are no key-generating arguments, the key has no trailing colon -- it is
+just `use-cache:{functionId}`.
 
 Different functions always produce different cache keys, even for the same route.
 This is important for intercepted routes -- the path handler and intercept handler
 each have their own `functionId` and therefore their own cache entries.
 
+### Route context is folded into the key
+
+The tainted `ctx` object is excluded from arg serialization (see below), but
+route-identifying fields read off it are extracted into `serializedArgs`:
+`url.host`, route name (`_routeName`), `pathname`, `params`, response type
+(`_responseType`), and the user-facing sorted search params (internal `_rsc*`/`__`
+params excluded). The same cached function called with `ctx` on different routes,
+param combinations, hosts, response types, or query variants therefore produces
+distinct cache entries -- not one shared entry.
+
 ## Tainted Arguments (ctx, env, req)
 
 Request-scoped objects are branded with `Symbol.for('rango:nocache')` at creation.
 When detected:
 
 1. **Excluded from cache key** -- request-scoped, not meaningful for keying.
+   (The route-identifying fields read off `ctx` are still folded in -- see
+   "Route context is folded into the key" above.)
 2. **Handle data captured on miss** -- side effects via `ctx.use(Handle)` are recorded.
 3. **Handle data replayed on hit** -- restored into the current request's HandleStore.
 
@@ -122,12 +140,16 @@ const data = await getCachedData(locale); // locale is now in the cache key
 These ctx methods **throw** inside a `"use cache"` function because their effects
 are lost on cache hit (the function body is skipped):
 
-- `ctx.set()` / `ctx.get()` for passing values to children
+- `ctx.set()` for passing values to children
 - `ctx.header()`
 - `ctx.setTheme()`
 - `ctx.setLocationState()`
 - `ctx.onResponse()`
 
+`ctx.get()` is **not** exec-guarded inside `"use cache"` -- it is a read, so it is
+safe. (It only throws when reading a non-cacheable variable inside the separate
+route-level `cache()` DSL boundary.)
+
 The error message recommends two alternatives:
 
 1. Extract the data fetch into a separate cached function and call ctx methods outside it.
@@ -304,8 +326,15 @@ export async function getProducts() {
 ## Backing Store
 
 Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
-One store, one configuration, one invalidation API. Tag-based invalidation
-(`revalidateTag`) works across all mechanisms.
+One store, one configuration.
+
+Cache entries (and `cacheProfiles`) accept an optional `tags` field, but the
+built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) do not yet index or
+invalidate by tag -- tags are passed through to the store and otherwise ignored.
+Tag-based invalidation (`revalidateTag`) is a forward-looking API that requires a
+custom store with secondary indices. Today entries expire by TTL/SWR. The separate
+`revalidate()` export is the client-update axis (which segments re-render on a
+navigation or action), not a cache bust.
 
 ## Interaction with Other Caching
 

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/location-state-shared.ts

@@ -3,6 +3,8 @@
  * No "use client" directive so it can be imported from RSC
  */
 
+import type { ReactElement } from "react";
+
 /**
  * Internal entry representing a state value with its unique key.
  * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
@@ -22,6 +24,88 @@ export interface LocationStateOptions {
   flash?: boolean;
 }
 
+type LocationStateUnsafeFn = (...args: never[]) => unknown;
+
+// Broadest constructor signature (`abstract` covers both abstract and concrete
+// classes). A class passed as state has a `new` signature, not a call signature,
+// so it slips past LocationStateUnsafeFn; at runtime the lazy-getter path
+// (`typeof value === "function"`) then mistakes it for a getter and throws.
+type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
+
+// `unknown` cannot be verified serializable, so it is rejected (callers must
+// supply a concrete type). `any` deliberately defeats type checking and is NOT
+// guardable — it is assignable to the branded error too, so the check always
+// passes; it remains an explicit escape hatch.
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsUnknown<T> =
+  IsAny<T> extends true ? false : unknown extends T ? true : false;
+
+/**
+ * Branded error surfaced when a value that cannot live in location state is
+ * used. Location state is written into `history.state`, which uses the
+ * structured clone algorithm; React elements, functions, and symbols throw a
+ * `DataCloneError` at runtime. Carries a human-readable reason so the compile
+ * error explains the fix.
+ */
+export type LocationStateUnsafe<Reason extends string> = {
+  readonly __rango_location_state_unsafe: Reason;
+};
+
+/**
+ * Maps `T` to itself when it is safe to store in location state, or to a branded
+ * {@link LocationStateUnsafe} error for the disallowed parts: `unknown`, React
+ * elements (RSC/JSX content), functions, class constructors, and symbols.
+ * Recurses through arrays, `Map`, `Set`, and plain objects; structured-clone
+ * built-ins (`Date`, `RegExp`, typed arrays, `Blob`, `File`, `FormData`) pass
+ * through. Consumed by {@link ValidateLocationState}, which is intersected into a
+ * definition's value parameter so posting RSC content is a COMPILE error, not a
+ * runtime `DataCloneError`. (`any` is unguardable and remains an escape hatch.)
+ */
+export type LocationStateSafe<T> =
+  IsUnknown<T> extends true
+    ? LocationStateUnsafe<"location state needs an explicit, concrete type; `unknown` cannot be verified as serializable">
+    : T extends LocationStateUnsafeFn
+      ? LocationStateUnsafe<"functions cannot be stored in location state">
+      : T extends LocationStateUnsafeCtor
+        ? LocationStateUnsafe<"class constructors cannot be stored in location state">
+        : T extends symbol
+          ? LocationStateUnsafe<"symbols cannot be stored in location state">
+          : T extends ReactElement
+            ? LocationStateUnsafe<"React/RSC content cannot be stored in location state; store plain data and render it on arrival">
+            : T extends string | number | boolean | bigint | null | undefined
+              ? T
+              : T extends
+                    | Date
+                    | RegExp
+                    | ArrayBuffer
+                    | ArrayBufferView
+                    | Blob
+                    | File
+                    | FormData
+                ? T
+                : T extends ReadonlyMap<infer K, infer V>
+                  ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>>
+                  : T extends ReadonlySet<infer V>
+                    ? ReadonlySet<LocationStateSafe<V>>
+                    : T extends readonly unknown[]
+                      ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                      : T extends object
+                        ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                        : T;
+
+/**
+ * `unknown` (a no-op) when `T` is safe to store in location state, otherwise a
+ * branded {@link LocationStateUnsafe} object. Intersected into the value
+ * parameter of a definition's call and `write()` so POSTING RSC content (or any
+ * non-serializable value) is a compile error whose text carries the reason —
+ * without a `TState extends ...` self-constraint, which TypeScript rejects as
+ * circular (TS2313). For safe `T`, `value & unknown` collapses back to `value`,
+ * so valid usage is unchanged.
+ */
+export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>]
+  ? unknown
+  : LocationStateUnsafe<"location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival">;
+
 /**
  * Type-safe location state definition
  *
@@ -59,7 +143,7 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
    *
    * Client-only: throws when called on the server (no history available).
    */
-  write(value: TState): void;
+  write(value: TState & ValidateLocationState<TState>): void;
   /**
    * Statically remove this definition's slot from the current history entry,
    * leaving any other keys on history.state untouched. Idempotent: removing
@@ -118,7 +202,10 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  */
 export function createLocationState<TState>(
   options?: LocationStateOptions,
-): LocationStateDefinition<[TState | (() => TState)], TState> {
+): LocationStateDefinition<
+  [(TState | (() => TState)) & ValidateLocationState<TState>],
+  TState
+> {
   const flash = options?.flash ?? false;
   let _key: string | undefined;
 
@@ -209,7 +296,10 @@ export function createLocationState<TState>(
     enumerable: true,
   });
 
-  return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
+  return fn as unknown as LocationStateDefinition<
+    [(TState | (() => TState)) & ValidateLocationState<TState>],
+    TState
+  >;
 }
 
 /**

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/per-module-writer.ts

@@ -97,7 +97,10 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    // Match .ts/.tsx/.js/.jsx (same as router-processing.ts / router-transform.ts).
+    // Without the jsx? branch a .jsx/.js source produced genPath === filePath,
+    // overwriting the source file instead of writing a sibling .gen.ts.
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
 
     // When a urls() variable was found but static resolution yields zero
     // routes, write an empty placeholder so generated imports stay

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/cache/cache-scope.ts

@@ -187,6 +187,32 @@ export class CacheScope {
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
 
+  /**
+   * Evaluate the cache `condition` predicate. Returns false (skip the cache
+   * operation) when the predicate returns false or throws; returns true when
+   * there is no condition or no request context to evaluate it against.
+   */
+  private conditionAllows(op: "read" | "write"): boolean {
+    if (this.config === false || !this.config.condition) return true;
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return true;
+    try {
+      if (!this.config.condition(requestCtx)) {
+        debugCacheLog(
+          `[CacheScope] condition returned false, skipping cache ${op}`,
+        );
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error(
+        `[CacheScope] condition function threw, skipping cache ${op}:`,
+        error,
+      );
+      return false;
+    }
+  }
+
   /**
    * Lookup cached segments for a route (single cache entry per request).
    * Returns { segments, shouldRevalidate } or null if cache miss.
@@ -204,27 +230,7 @@ export class CacheScope {
     shouldRevalidate: boolean;
   } | null> {
     if (!this.enabled) return null;
-
-    // Evaluate condition — skip cache read when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const requestCtx = getRequestContext();
-      if (requestCtx) {
-        try {
-          if (!this.config.condition(requestCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache read`,
-            );
-            return null;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache read:`,
-            error,
-          );
-          return null;
-        }
-      }
-    }
+    if (!this.conditionAllows("read")) return null;
 
     const store = this.getStore();
     if (!store) return null;
@@ -284,27 +290,7 @@ export class CacheScope {
     isIntercept?: boolean,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
-
-    // Evaluate condition — skip cache write when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const conditionCtx = getRequestContext();
-      if (conditionCtx) {
-        try {
-          if (!this.config.condition(conditionCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache write`,
-            );
-            return;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache write:`,
-            error,
-          );
-          return;
-        }
-      }
-    }
+    if (!this.conditionAllows("write")) return;
 
     const store = this.getStore();
     if (!store) return;