@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.124

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

@@ -4,6 +4,8 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { enterActionFence, exitActionFence } from "./action-fence.js";
+import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -156,12 +158,40 @@ export function createServerActionBridge(
 
     // Start action in event controller - handles lifecycle tracking
     const handle = eventController.startAction(id, args);
+    // Whether the action's response carried the keepClientCache() directive.
+    // Set when the response arrives; gates the deferred invalidation below.
+    let keepCache = false;
+    // Single deferred invalidation + fence release, run exactly ONCE however the
+    // action terminates (normal, redirect, error, abort, intercept, concurrent).
+    // This replaces main's eager clear at action start: every directive-free
+    // action invalidates once; keepClientCache() suppresses only the automatic
+    // invalidation, so a concurrent directive-free action still invalidates via
+    // its own latch. Latched so the finally AND the early SPA-redirect returns
+    // (whose Flight stream never settles) can both call it safely.
+    let actionFinalized = false;
+    // skipInvalidation: the version-mismatch reload terminal released nothing
+    // server-side, so it releases the fence without invalidating.
+    const finalizeAction = (skipInvalidation = false): void => {
+      if (actionFinalized) return;
+      actionFinalized = true;
+      // finally so a throw in invalidation cannot leak the fence (latch is set).
+      try {
+        if (!keepCache && !skipInvalidation) {
+          store.markCacheAsStaleAndBroadcast();
+        }
+      } finally {
+        exitActionFence();
+      }
+    };
     try {
       const segmentState = store.getSegmentState();
 
-      // Mark cache as stale immediately when action starts
-      // This ensures SWR pattern kicks in if user navigates away during action
-      store.markCacheAsStaleAndBroadcast();
+      // Raise the action fence (replaces the old eager clear). Nothing is wiped,
+      // rotated, or broadcast yet: navigations during the flight fetch fresh
+      // (no-store) and popstate is treated as SWR, but the decision to
+      // invalidate is deferred to the response so a no-op action (keepClientCache)
+      // can leave the caches and the jar untouched.
+      enterActionFence();
 
       // Create temporary references for serialization
       const temporaryReferences = deps.createTemporaryReferenceSet();
@@ -237,11 +267,22 @@ export function createServerActionBridge(
         // abortAllActions() doesn't disrupt the in-progress Flight stream.
         handle.signal.removeEventListener("abort", onHandleAbort);
 
+        // Did the action call keepClientCache()? If so the deferred invalidation
+        // below is suppressed for THIS action (a concurrent directive-free
+        // action still invalidates via its own response).
+        keepCache = response.headers.get(KEEP_CACHE_HEADER) === "1";
+
         // Check for version mismatch - server wants us to reload
         const reloadResult = handleReloadHeader(response, {
           onBlocked: resolveStreamComplete,
-          onReload: (url) =>
-            log("version mismatch on action, reloading", { reloadUrl: url }),
+          onReload: (url) => {
+            log("version mismatch on action, reloading", { reloadUrl: url });
+            // Never-settling terminal (navigates away), so the finally never
+            // runs: release the fence here. skipInvalidation — the mismatch
+            // short-circuits the action server-side, so nothing mutated and a
+            // broadcast would only risk hard-reloading a sibling mid-task.
+            finalizeAction(true);
+          },
         });
         if (reloadResult) return reloadResult;
 
@@ -253,6 +294,10 @@ export function createServerActionBridge(
         if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
           log("action simple redirect", { url: redirect.url });
           handle.complete(undefined);
+          // This path returns a never-settling promise, so the finally never
+          // runs: invalidate + release the fence here (the mutation committed
+          // and we're navigating away). Latched, so the finally is a no-op.
+          finalizeAction();
           await dispatchRedirect(redirect.url);
           return new Promise<Response>(() => {});
         }
@@ -277,6 +322,9 @@ export function createServerActionBridge(
           log("action router id mismatch, reloading to re-sync");
           handle.complete(undefined);
           resolveStreamComplete();
+          // Never-settling return: release the fence before the reload (the
+          // reload resets module state anyway, but stay balanced). Latched.
+          finalizeAction();
           window.location.reload();
           return new Promise<Response>(() => {});
         }
@@ -542,8 +590,9 @@ export function createServerActionBridge(
           handle.clearConsolidation();
 
           if (scenario.historyKeyChanged) {
-            if (!scenario.onInterceptRoute) {
-              store.markCacheAsStaleAndBroadcast();
+            // Invalidation is deferred to finalizeAction(); here we only trigger
+            // the revalidation refetch of the new route (suppressed on keep).
+            if (!scenario.onInterceptRoute && !keepCache) {
               refetchRoute().catch((error) => {
                 if (isBackgroundSuppressible(error)) return;
                 console.error(
@@ -555,11 +604,14 @@ export function createServerActionBridge(
             break;
           }
 
-          // Same history key but different pathname - safe to refetch current route
-          store.markCacheAsStaleAndBroadcast();
-          await refetchRoute({
-            interceptSourceUrl: store.getInterceptSourceUrl(),
-          });
+          // Same history key but different pathname - safe to refetch current
+          // route. Invalidation is deferred to finalizeAction(); here we only
+          // trigger the revalidation refetch (suppressed on keep).
+          if (!keepCache) {
+            await refetchRoute({
+              interceptSourceUrl: store.getInterceptSourceUrl(),
+            });
+          }
           break;
         }
 
@@ -567,8 +619,11 @@ export function createServerActionBridge(
           console.warn(
             `[Browser] Missing segments after action (HMR detected), refetching...`,
           );
+          // Repair (not revalidation), so ungated on keepCache: a keep action
+          // resolving last must discharge a directive-free sibling's repair.
+          // See the keep row in docs/design/rango-state-cookie.md (the all-keep
+          // edge, and the benign re-mark-stale-after-refetch end-state delta).
           await refetchRoute({ interceptSourceUrl });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -585,11 +640,11 @@ export function createServerActionBridge(
           // Clear consolidation tracking before fetch
           handle.clearConsolidation();
 
+          // Ungated on keepCache, same as hmr-missing above (see the keep row).
           await refetchRoute({
             segments: segmentsToSend,
             interceptSourceUrl,
           });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -653,7 +708,9 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
-          store.markCacheAsStaleAndBroadcast();
+          // Invalidation deferred to finalizeAction() (runs after this caches
+          // the fresh segments), suppressed when the action called
+          // keepClientCache().
           break;
         }
       }
@@ -661,6 +718,11 @@ export function createServerActionBridge(
       handle.complete(returnData);
       return returnData;
     } finally {
+      // The single deferred invalidation + fence release for this action. Runs
+      // for every terminal that settles (normal, navigated-away, error, abort,
+      // intercept, concurrent); the SPA-redirect paths above already ran it.
+      // Latched, so it fires exactly once.
+      finalizeAction();
       handle[Symbol.dispose]();
     }
   }

package/src/browser/types.ts

@@ -71,6 +71,12 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its cache duration.
    */
   prefetchCacheTTL?: number;
+  /**
+   * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
+   * reads it verbatim and binds the rango state cookie to it; composition
+   * happens only server-side.
+   */
+  stateCookieName?: string;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.
@@ -433,9 +439,9 @@ export interface NavigationStore {
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
+  markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
-  broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
   setCrossTabRefreshCallback(callback: () => void): void;

package/src/cache/cf/cf-cache-store.ts

@@ -40,6 +40,10 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import { VERSION } from "@rangojs/router:version";
+import {
+  isPerClientSignalHeader,
+  stripPerClientSignals,
+} from "../../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -1611,6 +1615,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     headers.delete(CACHE_STATUS_HEADER);
     headers.delete(CACHE_TAGS_HEADER);
     headers.delete(CACHE_TAGGED_AT_HEADER);
+    // Finding #3 (read side): strip per-client signals a pre-fix or
+    // pinned-version L1 entry may carry. See the read-side note in the design doc.
+    stripPerClientSignals(headers);
     return new Response(response.body, {
       status: response.status,
       statusText: response.statusText,
@@ -1651,6 +1658,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // replaced with a long max-age so the CF Cache API holds the entry across
       // the SWR window; getResponse restores the original before serving.
       const headers = new Headers(response.headers);
+      // Finding #3: never persist a per-client signal in the shared L1 entry
+      // (the platform's Set-Cookie rejection is unverified and ignores the
+      // directive anyway). See stripPerClientSignals.
+      stripPerClientSignals(headers);
       const originalCacheControl = response.headers.get("Cache-Control");
       if (originalCacheControl !== null) {
         headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
@@ -1688,8 +1699,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // L2: persist to KV (KV requires expirationTtl >= 60s)
       if (this.kv && this.waitUntil && totalTtl >= 60) {
         const kvKey = this.toKVKey(`doc:${key}`);
+        // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
-        response.headers.forEach((v, k) => headersArray.push([k, v]));
+        response.headers.forEach((v, k) => {
+          if (isPerClientSignalHeader(k)) return;
+          headersArray.push([k, v]);
+        });
         // Read body as ArrayBuffer and encode to base64 to preserve binary payloads
         const bodyBuf = kvBody
           ? await new Response(kvBody).arrayBuffer()
@@ -2848,6 +2863,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // so evict it and miss rather than re-failing every read until TTL.
       let response: Response;
       try {
+        // Finding #3 (read side): strip per-client signals a stale envelope may
+        // carry. Inside the try so a malformed `hd` evicts (not throws through);
+        // mutates `hd` in place so promoteResponseToL1 re-seeds from it too.
+        envelope.hd = envelope.hd.filter(
+          ([name]) => !isPerClientSignalHeader(name),
+        );
         const bodyBuffer = base64ToBuffer(envelope.b);
         const headers = new Headers(envelope.hd);
         response = new Response(bodyBuffer, {

package/src/cache/document-cache.ts

@@ -12,6 +12,7 @@
  */
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
+import { hasPerClientSignal } from "../browser/cookie-name.js";
 import {
   getRequestContext,
   type RequestContext,
@@ -121,6 +122,16 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
     return null;
   }
 
+  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
+  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
+  // loader set) would be replayed to every client on a hit — pinning them to
+  // one value and even rolling a rotated client back to a prior one. The
+  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
+  // would suppress invalidation for every replayed client. Refuse both.
+  if (hasPerClientSignal(response.headers)) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }

package/src/cache/memory-segment-store.ts

@@ -14,6 +14,7 @@ import type {
   CacheItemOptions,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import { isPerClientSignalHeader } from "../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -292,8 +293,13 @@ export class MemorySegmentCacheStore<
       // failure must degrade to a no-op (entry simply not cached), never throw
       // up and fail the request.
       const body = await response.clone().arrayBuffer();
+      // Defense-in-depth (Finding #3): never persist a per-client signal into a
+      // shared store. The document-cache chokepoint already refuses these, but
+      // putResponse is public and reachable directly (e.g. tag-revalidation
+      // re-puts), so strip them here too.
       const headers: [string, string][] = [];
       response.headers.forEach((value, name) => {
+        if (isPerClientSignalHeader(name)) return;
         headers.push([name, value]);
       });
 

package/src/client.rsc.tsx

@@ -50,7 +50,7 @@ export { href } from "./href-client.js";
 // Mount context re-exports (useMount is client-only, but MountContext can be referenced)
 export { MountContext } from "./browser/react/mount-context.js";
 
-// Note: useNavigation, useAction, useClientCache are NOT re-exported here
+// Note: useNavigation and useAction are NOT re-exported here
 // because they use client-side state and should only be used in client components
 
 // Handle API - for accumulating data across route segments

package/src/client.tsx

@@ -358,12 +358,6 @@ export {
   type SegmentsState,
 } from "./browser/react/use-segments.js";
 
-// Client cache controls hook
-export {
-  useClientCache,
-  type ClientCacheControls,
-} from "./browser/react/use-client-cache.js";
-
 // Provider
 export {
   NavigationProvider,

package/src/component-utils.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ComponentType } from "react";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 /**
  * Symbol used by React to mark client component references.
@@ -48,11 +49,21 @@ export function isClientComponent(
  *
  * @param component - The component to check
  * @param name - Name to use in error message (e.g., "document")
+ * @param opts.allowServerInTest - When true AND running under a test runner
+ *   (`isUnderTestRunner()`), relax ONLY the "use client" requirement: a server
+ *   component is accepted. The plugin's "use client" transform does not run in a
+ *   bare unit test, so a real exported `document` (almost every app sets one) has
+ *   no client marker and would otherwise throw at `createRouter`, blocking
+ *   `dispatch`/`assertGeneratedRoutesMatch` against the real router. The document
+ *   reference is irrelevant to those (no Flight render). The "not a JSX element"
+ *   guard still fires, and a real dev/build still throws (mirrors the runtime
+ *   fallback-id gating in handle.ts/loader.ts).
  * @throws Error if the component is not a client component
  */
 export function assertClientComponent(
   component: ComponentType<unknown> | unknown,
   name: string,
+  opts?: { allowServerInTest?: boolean },
 ): asserts component is ComponentType<unknown> {
   if (typeof component !== "function") {
     throw new Error(
@@ -62,6 +73,14 @@ export function assertClientComponent(
     );
   }
 
+  // Under a test runner the "use client" transform did not run, so a real
+  // server-rendered `document` has no client marker; accept it (the reference is
+  // never serialized in dispatch/route-map checks). Outside a test runner this
+  // still throws — the build-time safety net is preserved.
+  if (opts?.allowServerInTest && isUnderTestRunner()) {
+    return;
+  }
+
   if (!isClientComponent(component)) {
     throw new Error(
       `${name} must be a client component with "use client" directive at the top of the file. ` +

package/src/handle.ts

@@ -1,4 +1,5 @@
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 /**
  * Handle definition for accumulating data across route segments.
@@ -45,6 +46,11 @@ function defaultCollect<T>(segments: T[][]): T[] {
 // Used by useHandle() to recover collect when handle is deserialized from RSC prop.
 const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
 
+// Monotonic counter for runtime fallback ids (see createHandle). Module-scoped
+// and deterministic, so each createHandle() call gets a stable, unique id within
+// the process. Only used when no build id was injected (a bare unit test).
+let runtimeHandleIdCounter = 0;
+
 /**
  * Look up a collect function from the registry by handle $$id.
  * Returns undefined if not registered (falls back to defaultCollect in useHandle).
@@ -95,10 +101,26 @@ export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
-  const handleId = __injectedId ?? "";
+  let handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Handle", "createHandle");
+  // No build-injected id. Under a test runner: fall back to a synthetic id so the
+  // collect registers below and the handle is exercisable in tests (useHandle,
+  // collectHandle, renderRoute's `handles` run the REAL collect). Otherwise (dev
+  // or a real build) it means an UNSUPPORTED handler shape the plugin skipped —
+  // fail loud. The rich, stack-parsing diagnostic stays behind the NODE_ENV check
+  // so a production build folds it away and tree-shakes missing-id-error.ts out,
+  // shipping the small throw instead. isUnderTestRunner() is runtime-safe.
+  if (!handleId) {
+    if (isUnderTestRunner()) {
+      handleId = `__rango_runtime_handle_${runtimeHandleIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Handle", "createHandle");
+    } else {
+      throw new Error(
+        "[rango] Handle is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createHandle(...)`.",
+      );
+    }
   }
 
   const collectFn =
@@ -107,12 +129,10 @@ export function createHandle<TData, TAccumulated = TData[]>(
 
   // Register collect in module-level registry so useHandle() can recover it
   // when the handle is deserialized from RSC props (toJSON strips collect).
-  if (handleId) {
-    collectRegistry.set(
-      handleId,
-      collectFn as (segments: unknown[][]) => unknown,
-    );
-  }
+  collectRegistry.set(
+    handleId,
+    collectFn as (segments: unknown[][]) => unknown,
+  );
 
   return {
     __brand: "handle" as const,

package/src/host/testing.ts

@@ -4,7 +4,7 @@
  * Helper functions for testing host routing.
  */
 
-import { matchPattern } from "./pattern-matcher.js";
+import { matchPattern, parseRequest } from "./pattern-matcher.js";
 
 export interface CreateTestRequestOptions {
   host: string;
@@ -52,28 +52,57 @@ export function createTestRequest(options: CreateTestRequestOptions): Request {
   });
 }
 
+// Try each pattern (a single pattern or any in an array) against the already
+// parsed host + path. Shared by testPattern and matchesHost so the
+// normalize-and-loop lives once.
+function matchPatterns(
+  pattern: string | string[],
+  hostname: string,
+  pathname: string,
+  parts: string[],
+): boolean {
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+  return patterns.some((p) => matchPattern(p, hostname, pathname, parts));
+}
+
 /**
- * Test if a pattern matches a hostname
+ * Test if a pattern matches a hostname (and, for path-based patterns, a pathname).
+ *
+ * `pathname` defaults to `"/"`, so a host-only pattern works with two args. Pass
+ * the third arg to test a path-based pattern (`**.workers.dev/admin`,
+ * `localhost/shop`) — without it those patterns can never match.
  *
  * @example
  * ```ts
- * expect(testPattern('admin.*', 'admin.example.com')).toBe(true);
- * expect(testPattern(['*', 'www.*'], 'example.com')).toBe(true);
+ * expect(testPattern("admin.*", "admin.example.com")).toBe(true);
+ * expect(testPattern(["*", "www.*"], "example.com")).toBe(true);
+ * expect(testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin")).toBe(true);
  * ```
  */
 export function testPattern(
   pattern: string | string[],
   hostname: string,
+  pathname: string = "/",
 ): boolean {
-  const patterns = Array.isArray(pattern) ? pattern : [pattern];
-  const parts = hostname.split(".");
-  const pathname = "/";
-
-  for (const p of patterns) {
-    if (matchPattern(p, hostname, pathname, parts)) {
-      return true;
-    }
-  }
+  return matchPatterns(pattern, hostname, pathname, hostname.split("."));
+}
 
-  return false;
+/**
+ * Test if a pattern matches a `Request` — the hostname AND pathname are taken
+ * from the request URL (via the same `parseRequest` the host router uses), so a
+ * path-based pattern is tested against a real request without splitting the URL
+ * by hand.
+ *
+ * @example
+ * ```ts
+ * const req = new Request("https://foo.workers.dev/admin");
+ * expect(matchesHost("**.workers.dev/admin", req)).toBe(true);
+ * ```
+ */
+export function matchesHost(
+  pattern: string | string[],
+  request: Request,
+): boolean {
+  const { hostname, pathname, parts } = parseRequest(request);
+  return matchPatterns(pattern, hostname, pathname, parts);
 }

package/src/index.rsc.ts

@@ -184,6 +184,8 @@ export const getRequestContext: <
 export {
   cookies,
   headers,
+  invalidateClientCache,
+  keepClientCache,
   type CookieStore,
   type Cookie,
   type ReadonlyHeaders,
@@ -235,7 +237,26 @@ export {
 export { createConsoleSink } from "./router/telemetry.js";
 export { createOTelSink } from "./router/telemetry-otel.js";
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/index.ts

@@ -217,6 +217,17 @@ export function headers(): never {
   throw serverOnlyStubError("headers");
 }
 
+/**
+ * Client implementation of `invalidateClientCache()`. Unlike the server-only
+ * stubs above this is a REAL function under the `default` condition (it marks
+ * the client's caches stale); the `react-server` condition (index.rsc.ts)
+ * selects the server implementation that writes a rotated `Set-Cookie`.
+ */
+export {
+  invalidateClientCache,
+  keepClientCache,
+} from "./browser/invalidate-client-cache.js";
+
 /**
  * Error-throwing stub for server-only `createReverse` function.
  */
@@ -327,7 +338,26 @@ export {
 // who need the values in non-RSC contexts can import from
 // `@rangojs/router/server`.
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/loader.rsc.ts

@@ -22,9 +22,14 @@ import {
   getFetchableLoader,
 } from "./server/fetchable-loader-store.js";
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 export { getFetchableLoader };
 
+// Counter for runtime-fallback loader ids assigned only in a bare unit test
+// (no Vite plugin to inject one). Process-stable; never reached in a real build.
+let runtimeLoaderIdCounter = 0;
+
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
@@ -51,10 +56,26 @@ export function createLoader<T>(
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   // The $$id will be set on the returned object by Vite plugin
   // For fetchable loaders, __injectedId is also passed as a parameter
-  const loaderId = __injectedId || "";
+  let loaderId = __injectedId || "";
 
-  if (!loaderId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Loader", "createLoader");
+  // No build-injected id. Under a test runner: fall back to a synthetic id so the
+  // fn registers below and the loader is exercisable via runLoader(loaderHandle)
+  // (it recovers the fn from the registry by $$id). Otherwise (dev or a real
+  // build) it means an UNSUPPORTED shape (e.g. a namespace import
+  // `rango.createLoader(...)`) the plugin skipped — fail loud. The rich
+  // diagnostic stays behind the NODE_ENV check so production folds it away and
+  // ships the small throw. isUnderTestRunner() is runtime-safe. Mirrors createHandle.
+  if (!loaderId) {
+    if (isUnderTestRunner()) {
+      loaderId = `__rango_runtime_loader_${runtimeLoaderIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Loader", "createLoader");
+    } else {
+      throw new Error(
+        "[rango] Loader is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createLoader(...)`.",
+      );
+    }
   }
 
   // If not fetchable, store fn in registry (for SSR ctx.use() resolution)