@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f681f24a

package/src/browser/debug-channel.ts

@@ -0,0 +1,93 @@
+/**
+ * Client-side debug channel for React Performance Tracks.
+ *
+ * Creates a bidirectional channel that communicates with the server-side
+ * debug channel via Vite's HMR WebSocket. Used with createFromFetch()
+ * so Chrome DevTools can display Server Components in the Performance tab.
+ *
+ * Dev-only — gated behind import.meta.hot.
+ */
+
+export const DEBUG_ID_HEADER = "X-RSC-Debug-Id";
+const DEBUG_S2C_EVENT = "rango:perf-s2c";
+const DEBUG_C2S_EVENT = "rango:perf-c2s";
+
+type DebugPayload =
+  | { i: string; b: string } // chunk (base64)
+  | { i: string; d: true }; // done
+
+const bytesToBase64 = (bytes: Uint8Array) => {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+};
+
+const base64ToBytes = (base64: string) =>
+  Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+
+/**
+ * Create a client-side debug channel for the given debugId.
+ * The channel communicates with the server via Vite's HMR WebSocket.
+ */
+export function createClientDebugChannel(debugId: string): {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+} | null {
+  const hot = (import.meta as any).hot;
+  if (!hot) return null;
+
+  let closed = false;
+  let onServerData: ((payload: DebugPayload) => void) | undefined;
+
+  const cleanup = (notify?: boolean) => {
+    if (closed) return;
+    closed = true;
+    if (onServerData) {
+      hot.off(DEBUG_S2C_EVENT, onServerData);
+    }
+    if (notify) {
+      hot.send(DEBUG_C2S_EVENT, { i: debugId, d: true } satisfies DebugPayload);
+    }
+  };
+
+  // Readable: receives server-to-client debug data via HMR WS
+  const readable = new ReadableStream<Uint8Array>({
+    start(controller) {
+      onServerData = (payload: DebugPayload) => {
+        if (closed || payload.i !== debugId) return;
+        if ("b" in payload) {
+          controller.enqueue(base64ToBytes(payload.b));
+        }
+        if ("d" in payload) {
+          cleanup();
+          controller.close();
+        }
+      };
+      hot.on(DEBUG_S2C_EVENT, onServerData);
+    },
+    cancel() {
+      cleanup(true);
+    },
+  });
+
+  // Writable: sends client-to-server commands via HMR WS
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      if (closed) throw new TypeError("Channel is closed");
+      hot.send(DEBUG_C2S_EVENT, {
+        i: debugId,
+        b: bytesToBase64(chunk),
+      } satisfies DebugPayload);
+    },
+    close() {
+      cleanup(true);
+    },
+    abort() {
+      cleanup(true);
+    },
+  });
+
+  return { readable, writable };
+}

package/src/browser/navigation-client.ts

@@ -12,6 +12,8 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
+import { findSourceMapURL } from "../deps/browser.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -107,6 +109,14 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
+      // Dev-only: create debug channel for React Performance Tracks
+      const debugId = (import.meta as any).hot
+        ? crypto.randomUUID()
+        : undefined;
+      const debugChannel = debugId
+        ? createClientDebugChannel(debugId)
+        : undefined;
+
       /** Start a fresh navigation fetch (no cache / inflight hit). */
       const doFreshFetch = (): Promise<Response> => {
         if (tx) {
@@ -124,6 +134,7 @@ export function createNavigationClient(
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,
             }),
             ...(hmr && { "X-RSC-HMR": "1" }),
+            ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
           },
           signal,
         }).then((response) => {
@@ -220,7 +231,12 @@ export function createNavigationClient(
 
       try {
         // Deserialize RSC payload
-        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+        const payload = await deps.createFromFetch<RscPayload>(
+          responsePromise,
+          {
+            ...(debugChannel && { debugChannel, findSourceMapURL }),
+          },
+        );
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,

package/src/browser/partial-update.ts

@@ -259,6 +259,17 @@ export function createPartialUpdater(
             existingSegments,
           );
 
+          // Fix: tx.commit() cached the source page's handleData because
+          // eventController hasn't been updated yet. Overwrite with the
+          // correct cached handleData to prevent cache corruption on
+          // subsequent navigations to this same URL.
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
+
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
           // Remove `handles` from metadata to prevent NavigationProvider from

package/src/browser/prefetch/queue.ts

@@ -5,21 +5,19 @@
  * Hover prefetches bypass this queue — they fire directly for immediate response
  * to user intent.
  *
- * Draining is deferred to the next animation frame so prefetch network activity
- * never blocks paint. This applies to both the initial batch and subsequent
- * batches — every drain cycle yields to the browser first.
+ * Draining waits for an idle main-thread moment and for viewport images to
+ * finish loading, so prefetch fetch() calls never compete with critical
+ * resources for the browser's connection pool.
  *
  * When a navigation starts, queued prefetches are cancelled but executing ones
  * are left running. Navigation can reuse their in-flight responses via the
  * prefetch cache's inflight promise map, avoiding duplicate requests.
  */
 
-const MAX_CONCURRENT = 2;
+import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
 
-const deferToNextPaint: (fn: () => void) => void =
-  typeof requestAnimationFrame === "function"
-    ? requestAnimationFrame
-    : (fn) => setTimeout(fn, 0);
+const MAX_CONCURRENT = 2;
+const IMAGE_WAIT_TIMEOUT = 2000;
 
 let active = 0;
 const queue: Array<{
@@ -28,8 +26,9 @@ const queue: Array<{
 }> = [];
 const queued = new Set<string>();
 const executing = new Set<string>();
-let abortController: AbortController | null = null;
+const abortControllers = new Map<string, AbortController>();
 let drainScheduled = false;
+let drainGeneration = 0;
 
 function startExecution(
   key: string,
@@ -37,8 +36,10 @@ function startExecution(
 ): void {
   active++;
   executing.add(key);
-  abortController ??= new AbortController();
-  execute(abortController.signal).finally(() => {
+  const ac = new AbortController();
+  abortControllers.set(key, ac);
+  execute(ac.signal).finally(() => {
+    abortControllers.delete(key);
     // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
     // Without this guard, cancelled tasks' .finally() would underflow active
     // below zero, breaking the MAX_CONCURRENT guarantee.
@@ -50,18 +51,32 @@ function startExecution(
 }
 
 /**
- * Schedule a drain on the next animation frame.
- * Coalesces multiple drain requests into a single rAF callback so
- * batch completion doesn't schedule redundant frames.
+ * Schedule a drain after the browser is idle and viewport images are loaded.
+ * Coalesces multiple drain requests into a single deferred callback so
+ * batch completion doesn't schedule redundant waits.
+ *
+ * The two-step wait ensures prefetch fetch() calls don't compete with
+ * images for the browser's connection pool:
+ * 1. waitForIdle — yield until the main thread has a quiet moment
+ * 2. waitForViewportImages OR 2s timeout — yield until visible images
+ *    finish loading, but don't let slow/broken images block indefinitely
  */
 function scheduleDrain(): void {
   if (drainScheduled) return;
   if (active >= MAX_CONCURRENT || queue.length === 0) return;
   drainScheduled = true;
-  deferToNextPaint(() => {
-    drainScheduled = false;
-    drain();
-  });
+  const gen = drainGeneration;
+  waitForIdle()
+    .then(() =>
+      Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
+    )
+    .then(() => {
+      drainScheduled = false;
+      // Stale drain: a cancel/abort happened while we were waiting.
+      // A fresh scheduleDrain will be called by whatever enqueues next.
+      if (gen !== drainGeneration) return;
+      if (queue.length > 0) drain();
+    });
 }
 
 function drain(): void {
@@ -74,9 +89,10 @@ function drain(): void {
 
 /**
  * Enqueue a prefetch for concurrency-limited execution.
- * Execution is always deferred to the next animation frame to avoid
- * blocking paint, even when below the concurrency limit.
- * Deduplicates by key — items already queued or executing are skipped.
+ * Execution is deferred until the browser is idle and viewport images
+ * have finished loading, so prefetches never compete with critical
+ * resources. Deduplicates by key — items already queued or executing
+ * are skipped.
  *
  * The executor receives an AbortSignal that is aborted when
  * cancelAllPrefetches() is called (e.g. on navigation start).
@@ -93,19 +109,32 @@ export function enqueuePrefetch(
 }
 
 /**
- * Cancel queued prefetches. Executing prefetches are left running so
- * navigation can reuse their in-flight responses (checked via
- * consumeInflightPrefetch in the prefetch cache). With MAX_CONCURRENT=2
- * and priority: "low", in-flight prefetches don't meaningfully compete
- * with navigation fetches under HTTP/2 multiplexing.
+ * Cancel queued prefetches and abort in-flight ones that don't match
+ * the current navigation target. If `keepUrl` is provided, the
+ * executing prefetch whose key contains that URL is kept alive so
+ * navigation can reuse its response via consumeInflightPrefetch.
  *
  * Called when a navigation starts via the NavigationProvider's
  * event controller subscription.
  */
-export function cancelAllPrefetches(): void {
+export function cancelAllPrefetches(keepUrl?: string | null): void {
   queue.length = 0;
   queued.clear();
   drainScheduled = false;
+  drainGeneration++;
+
+  // Abort in-flight prefetches that aren't for the navigation target.
+  // Keys use format "sourceHref\0targetPathname+search" — match the
+  // target portion (after \0) against keepUrl.
+  for (const [key, ac] of abortControllers) {
+    const target = key.split("\0")[1];
+    if (keepUrl && target && keepUrl.startsWith(target)) continue;
+    ac.abort();
+    abortControllers.delete(key);
+    if (executing.delete(key)) {
+      active--;
+    }
+  }
 }
 
 /**
@@ -114,8 +143,10 @@ export function cancelAllPrefetches(): void {
  * in-flight responses would be stale.
  */
 export function abortAllPrefetches(): void {
-  abortController?.abort();
-  abortController = null;
+  for (const ac of abortControllers.values()) {
+    ac.abort();
+  }
+  abortControllers.clear();
 
   queue.length = 0;
   queued.clear();
@@ -125,4 +156,5 @@ export function abortAllPrefetches(): void {
   executing.clear();
   active = 0;
   drainScheduled = false;
+  drainGeneration++;
 }

package/src/browser/prefetch/resource-ready.ts

@@ -0,0 +1,77 @@
+/**
+ * Resource Readiness
+ *
+ * Utilities to defer speculative prefetches until critical resources
+ * (viewport images) have finished loading. Prevents prefetch fetch()
+ * calls from competing with images for the browser's connection pool.
+ */
+
+/**
+ * Resolve when all in-viewport images have finished loading.
+ * Returns immediately if no images are pending.
+ *
+ * Only checks images that exist at call time — does not observe
+ * dynamically added images. For SPA navigations where new images
+ * appear after render, call this after the navigation settles.
+ */
+export function waitForViewportImages(): Promise<void> {
+  if (typeof document === "undefined") return Promise.resolve();
+
+  const pending = Array.from(document.querySelectorAll("img")).filter((img) => {
+    if (img.complete) return false;
+    const rect = img.getBoundingClientRect();
+    return (
+      rect.bottom > 0 &&
+      rect.right > 0 &&
+      rect.top < window.innerHeight &&
+      rect.left < window.innerWidth
+    );
+  });
+
+  if (pending.length === 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    const settled = new Set<HTMLImageElement>();
+
+    const settle = (img: HTMLImageElement) => {
+      if (settled.has(img)) return;
+      settled.add(img);
+      if (settled.size >= pending.length) resolve();
+    };
+
+    for (const img of pending) {
+      img.addEventListener("load", () => settle(img), { once: true });
+      img.addEventListener("error", () => settle(img), { once: true });
+      // Re-check: image may have completed between the initial filter
+      // and listener attachment. settle() is idempotent per image, so
+      // a queued load event firing afterward is harmless.
+      if (img.complete) settle(img);
+    }
+  });
+}
+
+/**
+ * Resolve after the given number of milliseconds.
+ */
+export function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Resolve when the browser has an idle main-thread moment.
+ * Uses requestIdleCallback where available, falls back to setTimeout.
+ *
+ * This is a scheduling hint, not an asset-loaded detector — combine
+ * with waitForViewportImages() for full resource readiness.
+ */
+export function waitForIdle(timeout = 200): Promise<void> {
+  if (typeof window !== "undefined" && "requestIdleCallback" in window) {
+    return new Promise((resolve) => {
+      window.requestIdleCallback(() => resolve(), { timeout });
+    });
+  }
+
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}

package/src/browser/react/NavigationProvider.tsx

@@ -289,15 +289,17 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
-  // Cancel speculative prefetches when navigation starts.
-  // Viewport/render prefetches should not compete with navigation fetches.
+  // Cancel non-matching prefetches when navigation starts.
+  // Frees connections so the navigation fetch isn't competing with
+  // speculative prefetches. The prefetch matching the navigation target
+  // is kept alive so it can be reused via consumeInflightPrefetch.
   useEffect(() => {
     let wasIdle = true;
     const unsub = eventController.subscribe(() => {
       const state = eventController.getState();
       const isIdle = state.state === "idle" && !state.isStreaming;
       if (wasIdle && !isIdle) {
-        cancelAllPrefetches();
+        cancelAllPrefetches(state.pendingUrl);
       }
       wasIdle = isIdle;
     });

package/src/browser/server-action-bridge.ts

@@ -4,6 +4,8 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
+import { findSourceMapURL } from "../deps/browser.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -199,6 +201,14 @@ export function createServerActionBridge(
       const onHandleAbort = () => fetchAbort.abort();
       handle.signal.addEventListener("abort", onHandleAbort, { once: true });
 
+      // Dev-only: create debug channel for React Performance Tracks
+      const debugId = (import.meta as any).hot
+        ? crypto.randomUUID()
+        : undefined;
+      const debugChannel = debugId
+        ? createClientDebugChannel(debugId)
+        : undefined;
+
       // Send action request with stream tracking
       const responsePromise = fetch(url, {
         method: "POST",
@@ -210,6 +220,7 @@ export function createServerActionBridge(
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
           }),
+          ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
         },
         body: encodedBody,
         signal: fetchAbort.signal,
@@ -272,6 +283,7 @@ export function createServerActionBridge(
       try {
         payload = await deps.createFromFetch<RscPayload>(responsePromise, {
           temporaryReferences,
+          ...(debugChannel && { debugChannel, findSourceMapURL }),
         });
       } catch (error) {
         // Clean up streaming token on error (may be null if fetch failed before .then() ran)

package/src/browser/types.ts

@@ -341,7 +341,14 @@ export type ReadonlyURLSearchParams = Omit<
 export interface RscBrowserDependencies {
   createFromFetch: <T>(
     response: Promise<Response>,
-    options?: { temporaryReferences?: any },
+    options?: {
+      temporaryReferences?: any;
+      debugChannel?: { readable?: ReadableStream; writable?: WritableStream };
+      findSourceMapURL?: (
+        filename: string,
+        environmentName: string,
+      ) => string | null;
+    },
   ) => Promise<T>;
   createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
   encodeReply: (

package/src/cache/cache-runtime.ts

@@ -214,11 +214,21 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted args and RequestContext so request-scoped
-          // reads (cookies, headers) and side effects (ctx.set, etc.)
-          // throw inside background revalidation, same as the miss path.
-          // Uses ref-counted stamp/unstamp so overlapping executions
-          // sharing the same ctx don't clear each other's guards.
+          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
+          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
+          // which is sufficient for correctness.
+          //
+          // We intentionally skip stamping requestCtx here because:
+          // 1. runBackground starts the async task synchronously (before the
+          //    first await), so stampCacheExec would pollute the shared
+          //    requestCtx while the foreground pipeline is still running.
+          //    This causes assertNotInsideCacheExec to fire when cache-store
+          //    later calls requestCtx.onResponse().
+          // 2. requestCtx methods are closure-bound to the original ctx, so
+          //    neither Object.create() nor a proxy can isolate the stamp.
+          // 3. The foreground miss path already stamps requestCtx and catches
+          //    cookies()/headers() misuse on first execution. The background
+          //    re-runs the same function with the same request.
           const bgTaintedArgs: unknown[] = [];
           for (const arg of args) {
             if (isTainted(arg)) {
@@ -226,9 +236,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               bgTaintedArgs.push(arg);
             }
           }
-          if (requestCtx) {
-            stampCacheExec(requestCtx as object);
-          }
 
           try {
             const freshResult = await fn.apply(this, args);
@@ -249,9 +256,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
             }
-            if (requestCtx) {
-              unstampCacheExec(requestCtx as object);
-            }
             // Restore original handle store
             if (originalHandleStore && requestCtx) {
               requestCtx._handleStore = originalHandleStore;

package/src/cache/cache-scope.ts

@@ -328,22 +328,59 @@ export class CacheScope {
     // Check if this is a partial request (navigation) vs document request
     const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
 
+    if (INTERNAL_RANGO_DEBUG) {
+      debugCacheLog(
+        `[CacheScope] cacheRoute: scheduling waitUntil for ${key} (${nonLoaderSegments.length} segments, isPartial=${isPartial})`,
+      );
+    }
+
     requestCtx.waitUntil(async () => {
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(
+          `[CacheScope] waitUntil: awaiting handleStore.settled for ${key}`,
+        );
+      }
+
       await handleStore.settled;
 
-      // For document requests: only cache if ALL segments have components (complete render)
-      // For partial requests: null components are expected (client already has them)
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(`[CacheScope] waitUntil: handleStore settled for ${key}`);
+      }
+
+      // For document requests: only cache if layout segments have components
+      // (complete render). Parallel and route segments may legitimately have
+      // null components — UI-less @meta parallels return null, and void route
+      // handlers produce null when the UI lives in parallel slots/layouts.
+      // Partial requests always allow null components (client already has them).
       if (!isPartial) {
-        const hasAllComponents = nonLoaderSegments.every(
-          (s) => s.component !== null,
+        const hasIncompleteLayouts = nonLoaderSegments.some(
+          (s) => s.component === null && s.type === "layout",
         );
-        if (!hasAllComponents) return;
+        if (hasIncompleteLayouts) {
+          const nullSegments = nonLoaderSegments
+            .filter((s) => s.component === null && s.type === "layout")
+            .map((s) => s.id);
+          const error = new Error(
+            `[CacheScope] Cache write skipped: layout segments have null components ` +
+              `(${nullSegments.join(", ")}). This indicates an incomplete render — ` +
+              `layout handlers must return JSX for document requests to be cacheable.`,
+          );
+          error.name = "CacheScopeInvariantError";
+          console.error(error.message);
+          return;
+        }
       }
 
       // Collect handle data for non-loader segments only
       const handles = captureHandles(nonLoaderSegments, handleStore);
 
       try {
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(
+            `[CacheScope] waitUntil: serializing ${nonLoaderSegments.length} segments for ${key}`,
+          );
+        }
+
         // Serialize non-loader segments only
         const serializedSegments = await serializeSegments(nonLoaderSegments);
 
@@ -353,6 +390,10 @@ export class CacheScope {
           expiresAt: Date.now() + ttl * 1000,
         };
 
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
+        }
+
         await store.set(key, data, ttl, swr);
 
         if (INTERNAL_RANGO_DEBUG) {

package/src/cache/taint.ts

@@ -81,6 +81,61 @@ export function assertNotInsideCacheExec(
   }
 }
 
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
+  "rango:inside-cache-scope",
+) as any;
+
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export function stampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
+}
+
+/**
+ * Remove cache() scope mark.
+ */
+export function unstampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_SCOPE];
+  } else {
+    (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export function assertNotInsideCacheScope(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+        `On cache hit the handler is skipped, so this side effect would be lost. ` +
+        `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+    );
+  }
+}
+
 /**
  * Brand symbol for functions wrapped by registerCachedFunction().
  * Used at runtime to detect when a "use cache" function is misused