@rangojs/router 0.22.1 → 0.23.0

package/src/segment-system.tsx

@@ -9,6 +9,8 @@ import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
+import { isRenderableLoading } from "./types/boundaries.js";
+import { isPlaceholder } from "./types/segments.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
@@ -23,6 +25,7 @@ import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import { getBoundaryContent } from "./segment-boundary-content.js";
+import { asStream } from "./browser/defer.js";
 import {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
@@ -61,15 +64,6 @@ function segDebugLog(msg: string, details?: Record<string, unknown>): void {
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
-// A loading skeleton is renderable only when it is a real ReactNode value.
-// `false` is treated as "not renderable" here. This is the three-term gate;
-// the distinct two-term gate at the LoaderBoundary site deliberately treats
-// `false` as "create a boundary without a RouteContentWrapper"
-// (tree-structure.md), so it must NOT use this helper.
-function isRenderableLoading(loading: ReactNode): boolean {
-  return loading !== undefined && loading !== null && loading !== false;
-}
-
 // Exported for unit testing the no-parallel fast path (D6); internal otherwise.
 export function restoreParallelLoaderMarkers(
   segments: ResolvedSegment[],
@@ -264,32 +258,61 @@ function wrapDefaultOutletContent(
  * reader sits above every boundary, so the throw is a Fizz shell error (500).
  * `settledFallback` is that node; the caller plants it and, for a redirect,
  * replaces the whole page (an ancestor reading the loader would still throw).
+ *
+ * `settle` is the forceAwait/action lane of a loader set that holds a
+ * deferred loader (`prefetch: false`, see hasDeferred): every other loader is
+ * settled like a flagged one, so the commit stays whole for them, and the
+ * deferred one keeps its hole for the read site to suspend on. A settled
+ * error with no boundary is left to the read site there, where the aggregate
+ * lane it replaces would have thrown it.
  */
-async function buildLoaderStreams(loaders: ResolvedSegment[]): Promise<{
+async function buildLoaderStreams(
+  loaders: ResolvedSegment[],
+  settle?: boolean,
+): Promise<{
   streams: Record<string, unknown>;
   awaitedIds: string[] | undefined;
   settledFallback: ReactNode | undefined;
 }> {
   const streams: Record<string, unknown> = {};
   let awaitedIds: string[] | undefined;
-  let awaitedValues: unknown[] | undefined;
+  let settledIds: string[] | undefined;
+  let settledValues: unknown[] | undefined;
   for (const l of loaders) {
-    if (l.awaitBeforeFlush) {
+    if (l.awaitBeforeFlush || (settle && !isPlaceholder(l))) {
       const value = await l.loaderData;
       streams[l.loaderId!] = value;
-      (awaitedIds ??= []).push(l.loaderId!);
-      (awaitedValues ??= []).push(value);
+      if (l.awaitBeforeFlush) (awaitedIds ??= []).push(l.loaderId!);
+      (settledIds ??= []).push(l.loaderId!);
+      (settledValues ??= []).push(value);
     } else {
       streams[l.loaderId!] = l.loaderData;
     }
   }
-  const settledFallback = awaitedIds
-    ? (decodeLoaderResults(awaitedValues!, awaitedIds).errorFallback ??
-      undefined)
-    : undefined;
+  let settledFallback: ReactNode | undefined;
+  if (settledIds) {
+    try {
+      settledFallback =
+        decodeLoaderResults(settledValues!, settledIds).errorFallback ??
+        undefined;
+    } catch (error) {
+      if (!settle) throw error;
+    }
+  }
   return { streams, awaitedIds, settledFallback };
 }
 
+/**
+ * A loader set that holds a deferred loader (`prefetch: false`): its
+ * `loaderData` is a hole (browser/defer.ts) the browser resolves when the
+ * fill request lands (browser/partial-update.ts fillHoles), so no lane may
+ * await the set as a whole. The
+ * tree build would wait for a request that is only sent once it returns.
+ */
+function hasDeferred(loaders: ResolvedSegment[]): boolean {
+  return loaders.some(isPlaceholder);
+}
+
 function isLoaderRedirectNode(node: ReactNode): boolean {
   return isValidElement(node) && node.type === LoaderRedirect;
 }
@@ -354,6 +377,11 @@ export async function renderSegments(
     rootLayout: RootLayout,
     transitionGatedOff,
   } = options || {};
+  // forceAwait and action lanes settle loader data before the commit, except
+  // a set that holds a deferred loader (hasDeferred).
+  const settleLoaders = !!(forceAwait || isAction);
+  const settleAll = (loaders: ResolvedSegment[]): boolean =>
+    settleLoaders && !hasDeferred(loaders);
 
   const segDebug = INTERNAL_RANGO_DEBUG;
   const segDebugStart = segDebug ? performance.now() : 0;
@@ -484,6 +512,8 @@ export async function renderSegments(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
     );
 
+    // A deferred unit's component is a hole (browser/defer.ts), never a
+    // Promise: the awaits below pass it through.
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
       const componentAwaitStart = segDebug ? performance.now() : 0;
@@ -540,7 +570,11 @@ export async function renderSegments(
           componentTypeof: typeof c,
         });
       }
-      nodeContent = registerLazyRef(resolvedComponent);
+      // A hole here is read by React itself (browser/defer.ts asStream).
+      const streamed = asStream(resolvedComponent) as ReactNode;
+      nodeContent = isPlaceholder(node.segment)
+        ? streamed
+        : registerLazyRef(streamed);
     }
 
     // Wrap with <ViewTransition> if transition config exists (React 19.3+ / experimental).
@@ -614,7 +648,7 @@ export async function renderSegments(
       // for content-suspending routes (segment-loader-promise.ts).
       let boundaryLoaderStreams: Record<string, unknown> | undefined;
       let boundaryAwaitedLoaderIds: string[] | undefined;
-      if (forceAwait || isAction) {
+      if (settleAll(loaderEntries)) {
         const awaitStart = segDebug ? performance.now() : 0;
         boundaryLoaderData =
           loaderDataPromise instanceof Promise
@@ -632,7 +666,7 @@ export async function renderSegments(
           streams: boundaryLoaderStreams,
           awaitedIds: boundaryAwaitedLoaderIds,
           settledFallback,
-        } = await buildLoaderStreams(loaderEntries));
+        } = await buildLoaderStreams(loaderEntries, settleLoaders));
         if (settledFallback !== undefined) {
           if (isLoaderRedirectNode(settledFallback)) {
             content = settledFallback;
@@ -698,7 +732,7 @@ export async function renderSegments(
       let errorFallback: ReactNode = null;
       let loaderStreams: Record<string, unknown> | undefined;
       let awaitedLoaderIds: string[] | undefined;
-      if (forceAwait || isAction) {
+      if (settleAll(layoutLoaders)) {
         const layoutAwaitStart = segDebug ? performance.now() : 0;
         const resolvedData = await buildLoaderPromise(layoutLoaders);
         if (segDebug) {
@@ -726,7 +760,7 @@ export async function renderSegments(
           streams: loaderStreams,
           awaitedIds: awaitedLoaderIds,
           settledFallback,
-        } = await buildLoaderStreams(layoutLoaders));
+        } = await buildLoaderStreams(layoutLoaders, settleLoaders));
         if (settledFallback !== undefined) {
           if (isLoaderRedirectNode(settledFallback)) {
             content = settledFallback;
@@ -780,9 +814,9 @@ export async function renderSegments(
           // loader paid the pre-flush await, settle the aggregate so
           // LoaderResolver decodes the array without a Flight-chunk use().
           const settleParallelAggregate =
-            forceAwait ||
-            isAction ||
-            ownedLoaders.every((l) => l.awaitBeforeFlush === true);
+            (settleLoaders ||
+              ownedLoaders.every((l) => l.awaitBeforeFlush === true)) &&
+            !hasDeferred(ownedLoaders);
           if (settleParallelAggregate) {
             const parallelAwaitStart = segDebug ? performance.now() : 0;
             p.loaderDataPromise =

package/src/server/context.ts

@@ -117,6 +117,13 @@ export type EntryPropDatas = {
  */
 export type EntryPropRender = {
   loading?: ReactNode | false;
+  /**
+   * loading(fallback, { prefetch: false }) with a renderable fallback: a
+   * prefetch defers what the fallback covers while the entry's segment is
+   * new to the client (router/segment-resolution/prefetch-deferral.ts). Set
+   * on both DSL evaluations, whatever `ssr` did to `loading`.
+   */
+  loadingPrefetch?: false;
   transition?: TransitionConfig;
 };
 
@@ -150,6 +157,12 @@ export type LoaderEntry = {
    * navigation evaluation never has it.
    */
   bake?: true;
+  /**
+   * loader(Def, { prefetch: false }): a prefetch defers this registration
+   * while its segment is new to the client
+   * (router/segment-resolution/prefetch-deferral.ts).
+   */
+  prefetch?: false;
 };
 
 /**
@@ -867,9 +880,14 @@ export function track(label: string, depth?: number): () => void {
  * nested RangoContext.run() calls in Vite's module runner.
  */
 const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
-const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
-  globalThis as any
-)[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+interface LoaderScope {
+  active: true;
+  /** $$id of the DSL loader this scope resolves (runInsideLoaderScope). */
+  loaderId?: string;
+}
+const loaderScopeALS: AsyncLocalStorage<LoaderScope> = ((globalThis as any)[
+  LOADER_SCOPE_KEY
+] ??= new AsyncLocalStorage<LoaderScope>());
 
 // Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
 // of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
@@ -1429,8 +1447,24 @@ export function assertCachedHeaderWriteAllowed(
  * are bypassed because loaders are always fresh (never cached) and
  * their side effects (setCookie, header, etc.) are safe.
  */
-export function runInsideLoaderScope<T>(fn: () => T): T {
-  return loaderScopeALS.run({ active: true }, fn);
+export function runInsideLoaderScope<T>(fn: () => T, loaderId?: string): T {
+  return loaderScopeALS.run({ active: true, loaderId }, fn);
+}
+
+/**
+ * The loader whose run a handle push here belongs to, for the browser's
+ * merge of a partial response (handles/pushed-by.ts): the DSL loader
+ * this scope resolves, else the outermost loader body around the push (a
+ * loader a handler reads with ctx.use). Undefined for a handler's own push.
+ */
+export function getHandlePushOwner(): string | undefined {
+  const dsl = loaderScopeALS.getStore()?.loaderId;
+  if (dsl !== undefined) return dsl;
+  let outermost: string | undefined;
+  for (let s = loaderBodyScopeALS.getStore(); s; s = s.parent) {
+    if (s.loaderId !== undefined) outermost = s.loaderId;
+  }
+  return outermost;
 }
 
 /**

package/src/server/handle-store.ts

@@ -1,5 +1,10 @@
-import { findEnclosingLoaderBody, isInsideLoaderScope } from "./context.js";
+import {
+  findEnclosingLoaderBody,
+  getHandlePushOwner,
+  isInsideLoaderScope,
+} from "./context.js";
 import { holdsThenable } from "../router/segment-resolution/mask-nested.js";
+import { pushedByKey } from "../handles/pushed-by.js";
 
 /**
  * Handle data structure: handleName -> segmentId -> entries[]
@@ -75,6 +80,12 @@ interface SlotTag {
   restoredOf?: string;
   /** A restored slot a dropped settled push of its loader stood in for. */
   matched?: true;
+  /**
+   * The loader whose run made the push, for the browser (pushed-by.ts): the
+   * DSL loader or loader body it is made in (getHandlePushOwner), else the
+   * loader a copy stands for. Unset for a handler's push.
+   */
+  by?: string;
 }
 
 // Shared by every plain DSL-loader push; tags are never mutated in place.
@@ -111,6 +122,24 @@ function cloneHandleData(data: HandleData): HandleData {
   return clone;
 }
 
+// SlotTag.by of each value, index-aligned; undefined when no value has one.
+function pushedByOf(
+  values: unknown[],
+  tags: (SlotTag | undefined)[] | undefined,
+  keep?: (i: number) => boolean,
+): (string | null)[] | undefined {
+  if (!tags) return undefined;
+  const by: (string | null)[] = [];
+  let any = false;
+  for (let i = 0; i < values.length; i++) {
+    if (keep && !keep(i)) continue;
+    const run = tags[i]?.by ?? null;
+    if (run !== null) any = true;
+    by.push(run);
+  }
+  return any ? by : undefined;
+}
+
 /**
  * HandleStore tracks pending handler promises and stores handle data.
  *
@@ -297,7 +326,8 @@ export interface HandleStore {
    * nav/action payloads, whose consumer applies each yield progressively) or
    * "settled" (the document lane, whose consumers drain to completion in
    * blocking positions and must not wait on loader bodies).
-   * Each yield contains the full accumulated state (not just the delta).
+   * Each yield contains the full accumulated state (not just the delta),
+   * with the pushedBy records of its buckets (handles/pushed-by.ts).
    * Safe for concurrent consumers (per-consumer version cursor).
    * The "settled" lane of a frozen store (freezeDocumentSnapshot) yields the
    * frozen state once, at once, and ends. That yield is the store's own
@@ -331,6 +361,17 @@ export interface HandleStore {
     excludeLoaderPushes?: boolean,
   ): Record<string, unknown[]>;
 
+  /**
+   * The loader whose run pushed each value in getDataForSegment(segmentId,
+   * excludeLoaderPushes), index-aligned per handle (null: the handler's).
+   * Handles without such a value are omitted; undefined when none has one.
+   * The browser's pushedBy record (handles/pushed-by.ts).
+   */
+  getPushedBy(
+    segmentId: string,
+    excludeLoaderPushes?: boolean,
+  ): Record<string, (string | null)[]> | undefined;
+
   /**
    * The push `owner` of each value in getDataForSegment(segmentId, true),
    * index-aligned per handle (null: no owner). Handles without an owned
@@ -379,6 +420,14 @@ export function createHandleStore(): HandleStore {
   // (not value identity) so primitive values are covered too.
   // replaySegmentData installs fresh arrays, so restored values are untagged.
   const slotTags = new WeakMap<unknown[], (SlotTag | undefined)[]>();
+  // Frozen tags of plain pushes made by a run (SlotTag.by), one per loader.
+  const pushedBySlots = new Map<string, SlotTag>();
+  const pushedBySlot = (loader: true | undefined, by: string): SlotTag => {
+    const key = loader ? `L${by}` : `H${by}`;
+    let tag = pushedBySlots.get(key);
+    if (!tag) pushedBySlots.set(key, (tag = Object.freeze({ loader, by })));
+    return tag;
+  };
   // Copies standing in for a loader that has not pushed live yet: loaderId ->
   // the arrays holding them. Kept apart by kind: only a placeholder gives way
   // to a run that ends without a push, or to a cached unit's delivery.
@@ -602,6 +651,25 @@ export function createHandleStore(): HandleStore {
     }
   }
 
+  // What a stream yields: a copy of the data, with each bucket's pushedBy
+  // record (pushed-by.ts) for the browser's merge.
+  function snapshot(): HandleData {
+    const out: HandleData = {};
+    for (const handleName in data) {
+      const buckets: Record<string, unknown[]> = {};
+      let pushedBy: Record<string, (string | null)[]> | undefined;
+      for (const segmentId in data[handleName]) {
+        const values = data[handleName][segmentId];
+        buckets[segmentId] = [...values];
+        const by = pushedByOf(values, slotTags.get(values));
+        if (by) (pushedBy ??= {})[segmentId] = by;
+      }
+      out[handleName] = buckets;
+      if (pushedBy) out[pushedByKey(handleName)] = pushedBy;
+    }
+    return out;
+  }
+
   // Settlement barriers: `settled` (handler lane) resolves when sealed AND
   // handler inflight === 0. `fullySettled` additionally waits for the
   // auxiliary (loader) lane. seal() signals "no more track() calls"; each
@@ -812,6 +880,12 @@ export function createHandleStore(): HandleStore {
         at = restoredInsertIndex(values, restoredBy);
         if (replayOf === undefined) liveOf = restoredBy;
       }
+      const by =
+        getHandlePushOwner() ??
+        replayOf ??
+        restoredOf ??
+        placeholderOf ??
+        owner;
       insertSlot(
         values,
         at,
@@ -829,10 +903,13 @@ export function createHandleStore(): HandleStore {
               liveOf,
               under,
               owner,
+              by,
             }
-          : loader
-            ? LOADER_SLOT
-            : undefined,
+          : by !== undefined
+            ? pushedBySlot(loader, by)
+            : loader
+              ? LOADER_SLOT
+              : undefined,
       );
       if (replayOf !== undefined) {
         addPending(pendingReplays, replayOf, values);
@@ -958,7 +1035,7 @@ export function createHandleStore(): HandleStore {
         if (this.onError) this.onError(error);
         else console.error(error);
       }
-      documentSnapshot = { version, data: cloneHandleData(data) };
+      documentSnapshot = { version, data: snapshot() };
     },
 
     async *stream(
@@ -1005,7 +1082,7 @@ export function createHandleStore(): HandleStore {
       while (true) {
         if (version > seen && Object.keys(data).length > 0) {
           seen = version;
-          yield cloneHandleData(data);
+          yield snapshot();
         }
         if (done) break;
         await waitForEmission(seen, () => done);
@@ -1043,7 +1120,7 @@ export function createHandleStore(): HandleStore {
       while (true) {
         if (version > seen) {
           seen = version;
-          yield cloneHandleData(data);
+          yield snapshot();
         }
         if (done) break;
         await waitForEmission(seen, () => done);
@@ -1069,6 +1146,25 @@ export function createHandleStore(): HandleStore {
       return result;
     },
 
+    getPushedBy(
+      segmentId: string,
+      excludeLoaderPushes?: boolean,
+    ): Record<string, (string | null)[]> | undefined {
+      let result: Record<string, (string | null)[]> | undefined;
+      for (const handleName in data) {
+        const values = data[handleName][segmentId];
+        if (!values) continue;
+        const tags = slotTags.get(values);
+        const by = pushedByOf(
+          values,
+          tags,
+          excludeLoaderPushes ? (i) => !tags?.[i]?.loader : undefined,
+        );
+        if (by) (result ??= {})[handleName] = by;
+      }
+      return result;
+    },
+
     getRecordOwners(
       segmentId: string,
     ): Record<string, (string | null)[]> | undefined {

package/src/server/request-context.ts

@@ -78,6 +78,7 @@ import {
   readGuardedTheme,
 } from "./cookie-store.js";
 import { requestHeaders } from "./request-headers.js";
+import { requestKind } from "../router/segment-resolution/prefetch-deferral.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -713,6 +714,21 @@ export interface RequestContext<
    */
   _payloadVisitorTheme?: boolean;
 
+  /**
+   * @internal Set by the partial render when its payload carries deferred
+   * units (`prefetch: false`): what one page's prefetch left for the fill.
+   * The document cache does not store that response, whatever Cache-Control
+   * it ends up with (docs/design/prefetch-false.md, R7).
+   */
+  _payloadDeferred?: boolean;
+
+  /**
+   * @internal What the request says it is: a `<Link>` prefetch or a fill
+   * (`prefetch: false`), read once at creation
+   * (segment-resolution/prefetch-deferral.ts requestKind).
+   */
+  _requestKind?: "prefetch" | "fill";
+
   /**
    * Attach location state entries to the current response.
    *
@@ -1012,6 +1028,8 @@ export type PublicRequestContext<
   | "_readTheme"
   | "_documentCacheRender"
   | "_payloadVisitorTheme"
+  | "_payloadDeferred"
+  | "_requestKind"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
@@ -1445,12 +1463,14 @@ export function createRequestContext<TEnv>(
   };
 
   const cleanUrl = stripInternalParams(url);
+  const originalUrl = new URL(request.url);
 
   const ctx: RequestContext<TEnv> = {
     env,
     request,
     url: cleanUrl,
-    originalUrl: new URL(request.url),
+    originalUrl,
+    _requestKind: requestKind(request, originalUrl),
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
     _variables: variables,

package/src/server.ts

@@ -58,3 +58,7 @@ export {
   setClientUrlProjection,
   type ClientUrlProjection,
 } from "./client-urls/server-projection.js";
+
+// Hoisted clientUrls() revalidate() predicates: the generated
+// `<file>?rango-revalidate` modules register them in the RSC realm.
+export { registerClientUrlRevalidators } from "./client-urls/revalidate-registry.js";

package/src/testing/action-form.ts

@@ -12,8 +12,7 @@
  * Post the result with `serveShellRequest(router, url, { form })`.
  */
 
-import * as RSDServer from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
-import { registerServerModule } from "./internal/server-modules.js";
+import { registerTestAction } from "./internal/test-action.js";
 
 /** Options for {@link createActionForm}. */
 export interface CreateActionFormOptions {
@@ -41,15 +40,7 @@ export function createActionForm(
   options: CreateActionFormOptions,
 ): FormData {
   const { id, useActionState = true, fields = {} } = options;
-  const [moduleId, name] = id.split("#");
-  if (!moduleId || !name) {
-    throw new Error(
-      `createActionForm: id must be "<module id>#<export name>", received ${JSON.stringify(id)}`,
-    );
-  }
-  registerServerModule(moduleId, {
-    [name]: RSDServer.registerServerReference(action, moduleId, name),
-  });
+  registerTestAction(action, id, "createActionForm");
 
   const form = new FormData();
   if (useActionState) {

package/src/testing/e2e/page-helpers.ts

@@ -3,6 +3,7 @@
 // returned from `createPageHelpers(expect)`; the rest are standalone.
 
 import type { ConsoleMessage, Expect, Locator, Page } from "@playwright/test";
+import { PREFETCH_HEADER } from "../../prefetch-markers.js";
 
 // ============================================================================
 //  Standalone helpers (need only a page/locator)
@@ -170,7 +171,8 @@ export async function measureTime<T>(
 export function isPrefetchRequest(req: {
   headers: () => Record<string, string>;
 }): boolean {
-  return !!req.headers()["x-rango-prefetch"];
+  // Playwright lowercases header names.
+  return !!req.headers()[PREFETCH_HEADER.toLowerCase()];
 }
 
 // Module-level matcher + handler so blockPrefetch/unblockPrefetch share

package/src/testing/flight.entry.ts

@@ -64,6 +64,7 @@ export {
   resetShellTestState,
 } from "./serve-shell-request.js";
 export type {
+  ServeShellRequestAction,
   ServeShellRequestOptions,
   ServeShellRequestResult,
   ShellRequestHandles,

package/src/testing/index.ts

@@ -26,7 +26,7 @@
  *   condition and would throw if pulled into this barrel.
  *
  * Layers:
- * - Unit:        runMiddleware, runLoader, runClientRevalidate
+ * - Unit:        runMiddleware, runLoader, runRevalidate, runTransitionWhen
  * - Integration: dispatch (request -> Response)
  * - Cross-cut:   assertCacheStatus, assertShellStatus, assertGeneratedRoutesMatch
  * - Component:   see @rangojs/router/testing/dom (renderRoute)
@@ -55,8 +55,11 @@ export type {
   RunTransitionWhenResult,
 } from "./run-transition-when.js";
 
-export { runClientRevalidate } from "./run-client-revalidate.js";
-export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
+export { runRevalidate } from "./run-revalidate.js";
+export type {
+  RunRevalidateAction,
+  RunRevalidateOptions,
+} from "./run-revalidate.js";
 
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";

package/src/testing/internal/action-id.ts

@@ -1,5 +1,20 @@
 import { resolveActionRefId } from "../../router/is-action.js";
 
+/** An imported server action, as a testing primitive's `action` option takes it. */
+export type ImportedAction = (...args: never[]) => unknown;
+
+/**
+ * Normalizes a testing primitive's `action` option: a bare imported action or
+ * actionId string becomes `{ ref }`; the object form passes through.
+ */
+export function normalizeTestAction<
+  T extends { ref?: ImportedAction | string },
+>(action: ImportedAction | string | T | undefined): T | undefined {
+  return typeof action === "function" || typeof action === "string"
+    ? ({ ref: action } as T)
+    : action;
+}
+
 /**
  * The id a testing primitive's `action` option names: a single imported
  * server action (its `$id ?? $$id`, as the action boundary derives it) or a
@@ -7,7 +22,7 @@ import { resolveActionRefId } from "../../router/is-action.js";
  * primitive.
  */
 export function resolveTestActionId(
-  action: ((...args: never[]) => unknown) | string | undefined,
+  action: ImportedAction | string | undefined,
   primitive: string,
 ): string | undefined {
   if (action === undefined) return undefined;