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

package/src/cache/tag-invalidation.ts

@@ -0,0 +1,230 @@
+/**
+ * Cache Tag Invalidation API
+ *
+ * Two on-demand invalidation verbs, mirroring the distinction popularized by
+ * Next.js so consumers can pick the right consistency model:
+ *
+ * - updateTag(...tags): read-your-own-writes. Awaitable - resolves only after
+ *   in-process invalidation across every configured store completes. Use in a
+ *   Server Action and `await` it before the action re-renders, so the action's
+ *   own response reflects the mutation.
+ *
+ * - revalidateTag(...tags): fire-and-forget via waitUntil - the response is not
+ *   blocked. Use in Route Handlers / webhooks. NOTE: both verbs hard-purge; the
+ *   only difference is awaitability. revalidateTag does NOT serve stale content -
+ *   the next read after the invalidation lands is a hard miss that re-renders.
+ *   (The name mirrors Next.js, where it is SWR; here it is background-purge.)
+ *
+ * Both fan out across the app-level store (ctx._cacheStore) and every explicit
+ * per-scope store from cache({ store }) registered for this handler
+ * (ctx._explicitTaggedStores), calling the store-level invalidateTags()
+ * primitive for each tag. A single configured store (the common case) owns its
+ * own tag index and distributed invalidation - there is no separate
+ * tag-invalidation store.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import { reportingAsync } from "./cache-error.js";
+import { normalizeTags } from "./cache-tag.js";
+import type { SegmentCacheStore } from "./types.js";
+
+/**
+ * Collect every store that may hold entries tagged for this request's handler:
+ * the app-level store plus all explicit per-scope stores (deduplicated). Splits
+ * them into tag-capable (implement invalidateTags()) and not, so callers can
+ * warn about configured stores whose tagged entries will NOT be invalidated.
+ *
+ * `hasContext` reports whether an ALS request context existed at all. Without one
+ * (e.g. a queue consumer or cron job calling updateTag/revalidateTag) no stores
+ * are reachable, and the empty-capable case is a missing-context problem, not a
+ * store-config problem - callers branch on this to warn about the right cause.
+ */
+function collectStores(): {
+  capable: SegmentCacheStore[];
+  incapable: number;
+  hasContext: boolean;
+} {
+  const ctx = _getRequestContext();
+  const stores = new Set<SegmentCacheStore>();
+  if (ctx?._cacheStore) stores.add(ctx._cacheStore);
+  if (ctx?._explicitTaggedStores) {
+    for (const store of ctx._explicitTaggedStores) stores.add(store);
+  }
+  const capable: SegmentCacheStore[] = [];
+  let incapable = 0;
+  for (const store of stores) {
+    if (typeof store.invalidateTags === "function") capable.push(store);
+    else incapable++;
+  }
+  return { capable, incapable, hasContext: ctx != null };
+}
+
+/**
+ * Production-visible warning. A misconfigured store silently dropping
+ * invalidations is a data-correctness footgun, so this surfaces in every
+ * environment (not dev-only).
+ */
+function warnNoTagStore(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] No tag-capable cache store is configured; tags ` +
+      `[${tags.join(", ")}] were not invalidated. The configured store must ` +
+      `implement invalidateTags() (the built-in MemorySegmentCacheStore and ` +
+      `CFCacheStore do).`,
+  );
+}
+
+/**
+ * Production-visible warning for the no-request-context case. Distinct from
+ * warnNoTagStore: the stores are not unreachable because they are misconfigured,
+ * but because there is no ALS request context to reach them through (e.g. a queue
+ * consumer or scheduled job). Naming the real cause keeps consumers from chasing
+ * a store-config red herring.
+ */
+function warnNoRequestContext(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] Called outside a request context (e.g. from a queue consumer or ` +
+      `scheduled job); no cache stores are reachable and tags ` +
+      `[${tags.join(", ")}] were not invalidated. Invoke it within a request ` +
+      `(Server Action or route handler).`,
+  );
+}
+
+/**
+ * Production-visible warning for mixed-store configs: at least one configured
+ * store does not support tag invalidation, so its tagged entries (if any) are
+ * left stale even though other stores were invalidated.
+ */
+function warnPartialTagStore(fn: string, incapable: number): void {
+  console.warn(
+    `[${fn}] ${incapable} configured cache store(s) do not implement ` +
+      `invalidateTags(); their tagged entries were NOT invalidated. Use a ` +
+      `tag-capable store (e.g. MemorySegmentCacheStore / CFCacheStore) for any ` +
+      `cache({ store }) boundary whose entries you invalidate by tag.`,
+  );
+}
+
+async function invalidateAcross(
+  stores: SegmentCacheStore[],
+  tags: string[],
+): Promise<void> {
+  // One invalidateTags(tags) call per store: the store receives the whole tag
+  // batch so it can do a single CDN purge request rather than one per tag.
+  //
+  // allSettled, not all: a store's invalidateTags() can reject (e.g. CFCacheStore
+  // surfaces a failed durable KV marker write). With Promise.all, the first
+  // rejection would short-circuit and the other stores' outcomes would go
+  // unobserved. Attempt every store, then surface a combined error so an awaited
+  // updateTag() still rejects (read-your-own-writes honesty) without masking the
+  // stores that did succeed.
+  const results = await Promise.allSettled(
+    stores.map((store) => store.invalidateTags!(tags)),
+  );
+  const errors = results
+    .filter((r): r is PromiseRejectedResult => r.status === "rejected")
+    .map((r) => r.reason);
+  if (errors.length > 0) {
+    const err = new Error(
+      `[tag invalidation] ${errors.length}/${stores.length} store(s) failed to ` +
+        `invalidate tags [${tags.join(", ")}]; their entries may still serve ` +
+        `stale data. Retry the invalidation.`,
+    );
+    (err as Error & { cause?: unknown }).cause = errors[0];
+    throw err;
+  }
+}
+
+/**
+ * Immediately expire every cache entry tagged with any of `tags`, resolving
+ * once in-process invalidation across all configured stores completes.
+ *
+ * Read-your-own-writes: because the returned promise resolves before you return
+ * from a Server Action, awaiting it guarantees the action's own re-render (and
+ * any subsequent read) sees fresh data.
+ *
+ * @example
+ * ```typescript
+ * async function updateProduct(formData: FormData) {
+ *   "use server";
+ *   await db.updateProduct(formData);
+ *   await updateTag("products");   // next render is fresh
+ * }
+ * ```
+ */
+export async function updateTag(...tags: string[]): Promise<void> {
+  const valid = normalizeTags(tags);
+  if (valid.length === 0) return;
+
+  const { capable, incapable, hasContext } = collectStores();
+  if (capable.length === 0) {
+    if (hasContext) warnNoTagStore("updateTag", valid);
+    else warnNoRequestContext("updateTag", valid);
+    return;
+  }
+  if (incapable > 0) warnPartialTagStore("updateTag", incapable);
+
+  await invalidateAcross(capable, valid);
+}
+
+/**
+ * Invalidate every cache entry tagged with any of `tags` in the background,
+ * without blocking the current response (fire-and-forget via waitUntil).
+ *
+ * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
+ * next read after the invalidation lands is a miss that re-renders fresh. The
+ * only difference from updateTag() is awaitability - revalidateTag() defers the
+ * purge off the response path and is not awaited.
+ *
+ * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
+ * Action, use updateTag() instead so the action's own response is fresh.
+ *
+ * Fire-and-forget: because this returns void and runs in the background, a
+ * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to
+ * the caller. It IS reported - logged loudly and routed through the router's
+ * `onError` callback (phase `cache`, `metadata.category === "cache-invalidate"`)
+ * via reportingAsync - so the failure is observable in telemetry even though it
+ * cannot be awaited. If you need the invalidation to be CONFIRMED (and to retry
+ * on failure), use `await updateTag()` instead, which rejects when a store's
+ * durable write fails.
+ *
+ * @example
+ * ```typescript
+ * // route handler invoked by an external webhook
+ * export async function POST() {
+ *   "use server";
+ *   revalidateTag("products");
+ *   return new Response("ok");
+ * }
+ * ```
+ */
+export function revalidateTag(...tags: string[]): void {
+  const valid = normalizeTags(tags);
+  if (valid.length === 0) return;
+
+  const { capable, incapable, hasContext } = collectStores();
+  if (capable.length === 0) {
+    if (hasContext) warnNoTagStore("revalidateTag", valid);
+    else warnNoRequestContext("revalidateTag", valid);
+    return;
+  }
+  if (incapable > 0) warnPartialTagStore("revalidateTag", incapable);
+
+  const ctx = _getRequestContext();
+  // reportingAsync never rejects: it catches a failed durable write and routes
+  // it through reportCacheError (loud log + onError). This is the only place a
+  // revalidateTag failure can be observed, since it is not awaitable. Pass ctx
+  // explicitly - the run executes in a detached waitUntil where the ALS context
+  // is gone, so onError fires only if we hand it the captured context.
+  const run = () =>
+    reportingAsync(
+      () => invalidateAcross(capable, valid),
+      "cache-invalidate",
+      "[revalidateTag] background invalidation",
+      ctx,
+    );
+  if (ctx?.waitUntil) {
+    ctx.waitUntil(run);
+  } else {
+    // No request context (e.g. called outside ALS): best-effort background run.
+    void run();
+  }
+}

package/src/cache/types.ts

@@ -136,12 +136,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param response - Response to cache (will be cloned)
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation
    */
   putResponse?(
     key: string,
     response: Response,
     ttl: number,
     swr?: number,
+    tags?: string[],
   ): Promise<void>;
 
   // ============================================================================
@@ -167,6 +169,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
     value: string,
     options?: CacheItemOptions,
   ): Promise<void>;
+
+  // ============================================================================
+  // Tag-based Invalidation (optional)
+  // ============================================================================
+
+  /**
+   * Invalidate every cache entry (segment, response, item) tagged with any of
+   * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
+   * APIs delegate to. Receives ALL of one invalidation call's tags at once so
+   * stores can batch their work (e.g. a single CDN purge request rather than
+   * one per tag). Stores that do not support tags simply omit this method.
+   * @param tags - The cache tags to invalidate
+   */
+  invalidateTags?(tags: string[]): Promise<void>;
 }
 
 /**
@@ -181,6 +197,13 @@ export interface CacheItemResult {
   handles?: string;
   /** Whether the entry is stale and should be revalidated */
   shouldRevalidate: boolean;
+  /**
+   * The entry's cache tags (including runtime cacheTag() tags), surfaced on read
+   * so a "use cache" HIT can still contribute its tags to the request-scoped tag
+   * set used by document-level caching. On a hit the cached function is not
+   * re-run, so its runtime tags are only available here, not from re-execution.
+   */
+  tags?: string[];
 }
 
 /**
@@ -235,6 +258,10 @@ export interface CachedEntryData {
   handles: string;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
+  /** Cache tags for invalidation */
+  tags?: string[];
+  /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+  taggedAt?: number;
 }
 
 // ============================================================================

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,11 +184,20 @@ export const getRequestContext: <
 export {
   cookies,
   headers,
+  invalidateClientCache,
+  keepClientCache,
   type CookieStore,
   type Cookie,
   type ReadonlyHeaders,
 } from "./server/cookie-store.js";
 
+// Cache tag APIs (server-only)
+// cacheTag: tag the current "use cache" entry at runtime.
+// updateTag: read-your-own-writes invalidation (awaitable, for Server Actions).
+// revalidateTag: background hard-purge invalidation (not awaited, for route handlers / webhooks).
+export { cacheTag } from "./cache/cache-tag.js";
+export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
+
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
@@ -228,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.
  */
@@ -237,6 +248,18 @@ export function middleware(): never {
 export function revalidate(): never {
   throw serverOnlyStubError("revalidate");
 }
+// Cache tag APIs are server-only (real implementations in index.rsc.ts). These
+// stubs keep the named-export shape identical under the default/non-react-server
+// condition so SSR/client/default bundles that encounter the import link cleanly.
+export function cacheTag(): never {
+  throw serverOnlyStubError("cacheTag");
+}
+export function updateTag(): never {
+  throw serverOnlyStubError("updateTag");
+}
+export function revalidateTag(): never {
+  throw serverOnlyStubError("revalidateTag");
+}
 export function loader(): never {
   throw serverOnlyStubError("loader");
 }
@@ -315,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)