@rangojs/router 0.10.1 → 0.12.0

package/src/ssr/index.tsx

@@ -154,10 +154,20 @@ export interface SSRDependencies<TEnv = unknown> {
   ) => TransformStream<Uint8Array, Uint8Array>;
 
   /**
-   * Function to load bootstrap script content
-   * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+   * Function to load bootstrap script content.
+   * Required unless `getClientEntryUrl` is provided with `headScripts: "preinit"`.
+   * Custom SSR entries typically: `() => import.meta.viteRsc.loadBootstrapScriptContent("index")`
+   * (deprecated in `@vitejs/plugin-rsc` 0.5.33 in favor of `getClientEntryUrl`).
    */
-  loadBootstrapScriptContent: () => Promise<string>;
+  loadBootstrapScriptContent?: () => Promise<string>;
+
+  /**
+   * Client entry URL from `@vitejs/plugin-rsc/ssr` `getClientEntryUrl()`.
+   * Preferred when `headScripts` is `"preinit"`: Fizz receives `bootstrapModules`
+   * without the deprecated `loadBootstrapScriptContent` round-trip. Custom SSR
+   * entries can omit this and keep the inline bootstrap path.
+   */
+  getClientEntryUrl?: () => string;
 
   /**
    * Document script strategy; the generated virtual SSR entry threads the
@@ -438,36 +448,105 @@ interface ShellResumeOptions {
 const BOOTSTRAP_IMPORT_ONLY_RE =
   /^\s*import\(\s*(["'])([^"'\\]+)\1\s*\)\s*;?\s*$/;
 
+const MISSING_BOOTSTRAP_MSG =
+  "[ssr] Missing bootstrap dependency: provide loadBootstrapScriptContent(), " +
+  'or getClientEntryUrl with headScripts: "preinit".';
+
 /**
- * Prefer bootstrapModules over the inline import() bootstrap. When the content
- * is exactly `import("<entry-url>")`, hand Fizz the URL instead: React then
- * emits a `<link rel="modulepreload" fetchpriority="low">` hint in the head
- * plus the executing `<script type="module" src async>` at end of shell — the
- * entry fetch starts with the first flushed bytes instead of when the parser
- * reaches an opaque inline script that only reveals the URL once executed.
- * Fizz stamps the request nonce on both tags (the inline form needed that
- * too), and under PPR both land in the stored prelude; on resume React has
- * already cleared the bootstrap fields from the postponed state, so nothing
- * re-emits.
+ * Construction-time guard for {@link resolveBootstrap}: a handler whose deps
+ * can never produce a bootstrap must fail at startup, not 500 per request.
+ * getClientEntryUrl only counts under an explicit `headScripts: "preinit"` —
+ * any other headScripts keeps the inline path, so its presence alone is a
+ * misconfiguration worth flagging rather than silently ignoring.
  */
-function resolveBootstrapOptions(
-  content: string,
-  headScripts: SSRDependencies["headScripts"],
-): Pick<
+function assertBootstrapDeps(deps: SSRDependencies): void {
+  const preinit = deps.headScripts === "preinit";
+  if (deps.getClientEntryUrl && !preinit) {
+    console.warn(
+      '[ssr] getClientEntryUrl is ignored without headScripts: "preinit"; ' +
+        "the inline loadBootstrapScriptContent path is used instead.",
+    );
+  }
+  if (
+    !(preinit && deps.getClientEntryUrl) &&
+    !deps.loadBootstrapScriptContent
+  ) {
+    throw new Error(MISSING_BOOTSTRAP_MSG);
+  }
+}
+
+type BootstrapOptions = Pick<
   RenderToReadableStreamOptions,
   "bootstrapScriptContent" | "bootstrapModules"
-> {
-  // Explicit opt-in only: undefined (a custom SSR entry that predates the
-  // option, which also never installed the preinit hook) keeps the inline
-  // bootstrap byte-for-byte — converting by default would break CSPs that
-  // allowlist the known inline import() via a script hash.
-  if (headScripts !== "preinit") {
-    return { bootstrapScriptContent: content };
+>;
+
+/**
+ * Resolve Fizz's bootstrap options from the deps.
+ *
+ * Prefer bootstrapModules over the inline import() bootstrap: with
+ * `headScripts: "preinit"`, getClientEntryUrl() (sync — nothing to race)
+ * short-circuits to bootstrapModules, and inline content that is exactly
+ * `import("<entry-url>")` converts to the URL. React then emits a
+ * `<link rel="modulepreload" fetchpriority="low">` hint in the head plus the
+ * executing `<script type="module" src async>` at end of shell — the entry
+ * fetch starts with the first flushed bytes instead of when the parser reaches
+ * an opaque inline script that only reveals the URL once executed. Fizz stamps
+ * the request nonce on both tags, and under PPR both land in the stored
+ * prelude; on resume React has already cleared the bootstrap fields from the
+ * postponed state, so nothing re-emits. The conversion is an explicit opt-in:
+ * undefined headScripts (a custom SSR entry that predates the option, which
+ * also never installed the preinit hook) keeps the inline bootstrap
+ * byte-for-byte — converting by default would break CSPs that allowlist the
+ * known inline import() via a script hash.
+ *
+ * With `deadline` (shell capture), the inline load races it: a load that never
+ * resolves within the deadline is the same bounded no-shell degrade as a shell
+ * that never goes quiet — resolves `null`, the caller's degrade sentinel
+ * (disjoint from the load's string). A load that REJECTS is a genuine error
+ * and still propagates. The no-op catch keeps a late rejection off the
+ * unhandledRejection path when the deadline already won; a rejection that
+ * lands first still propagates out.
+ */
+async function resolveBootstrap(
+  deps: SSRDependencies,
+): Promise<BootstrapOptions>;
+async function resolveBootstrap(
+  deps: SSRDependencies,
+  deadline: Promise<void>,
+): Promise<BootstrapOptions | null>;
+async function resolveBootstrap(
+  deps: SSRDependencies,
+  deadline?: Promise<void>,
+): Promise<BootstrapOptions | null> {
+  const preinit = deps.headScripts === "preinit";
+  if (preinit) {
+    // Truthy on purpose, and the ONLY predicate on the URL: an empty string is
+    // an unusable entry URL and falls through to the inline path.
+    const url = deps.getClientEntryUrl?.();
+    if (url) {
+      return { bootstrapModules: [url] };
+    }
+  }
+  if (!deps.loadBootstrapScriptContent) {
+    throw new Error(MISSING_BOOTSTRAP_MSG);
+  }
+  let content: string;
+  if (deadline) {
+    const load = deps.loadBootstrapScriptContent();
+    load.catch(() => {});
+    const raced = await Promise.race([load, deadline.then(() => null)]);
+    if (raced === null) return null;
+    content = raced;
+  } else {
+    content = await deps.loadBootstrapScriptContent();
+  }
+  if (preinit) {
+    const match = BOOTSTRAP_IMPORT_ONLY_RE.exec(content);
+    return match
+      ? { bootstrapModules: [match[2]!] }
+      : { bootstrapScriptContent: content };
   }
-  const match = BOOTSTRAP_IMPORT_ONLY_RE.exec(content);
-  return match
-    ? { bootstrapModules: [match[2]!] }
-    : { bootstrapScriptContent: content };
+  return { bootstrapScriptContent: content };
 }
 
 /**
@@ -476,7 +555,10 @@ function resolveBootstrapOptions(
  * @example
  * ```tsx
  * import { createSSRHandler } from "@rangojs/router/ssr";
- * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+ * import {
+ *   createFromReadableStream,
+ *   getClientEntryUrl,
+ * } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
  * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
@@ -484,6 +566,17 @@ function resolveBootstrapOptions(
  *   createFromReadableStream,
  *   renderToReadableStream,
  *   injectRSCPayload,
+ *   getClientEntryUrl,
+ *   headScripts: "preinit", // getClientEntryUrl is only used under "preinit"
+ * });
+ * ```
+ *
+ * Custom SSR entries that still use the deprecated bootstrap helper:
+ * ```tsx
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
  *   loadBootstrapScriptContent: () =>
  *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
  * });
@@ -494,9 +587,9 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     createFromReadableStream,
     renderToReadableStream,
     injectRSCPayload,
-    loadBootstrapScriptContent,
     onError,
   } = deps;
+  assertBootstrapDeps(deps);
 
   /**
    * Render RSC stream to HTML stream
@@ -541,8 +634,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         origin,
       });
 
-      // Get bootstrap script content
-      const bootstrapScriptContent = await loadBootstrapScriptContent();
+      const bootstrap = await resolveBootstrap(deps);
 
       // ssr:false auto-raise (see SSRDependencies.progressiveChunkSize).
       // Awaiting the payload here is latency-neutral: fizz cannot emit even
@@ -563,7 +655,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // isolate-global, the nonce per request).
       const htmlStream = await runWithPreinitNonce(nonce, () =>
         renderToReadableStream(<SsrRoot />, {
-          ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+          ...bootstrap,
           formState,
           nonce,
           ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
@@ -600,8 +692,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
 export function createShellCaptureHandler<TEnv = unknown>(
   deps: SSRDependencies<TEnv>,
 ) {
-  const { createFromReadableStream, loadBootstrapScriptContent, prerender } =
-    deps;
+  const { createFromReadableStream, prerender } = deps;
   const onError = deps.onError;
 
   if (!prerender) {
@@ -610,6 +701,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
         "PPR shell capture requires the prerender export; wire it in the SSR virtual entry.",
     );
   }
+  assertBootstrapDeps(deps);
 
   /**
    * Prerender the shell and return the stored artifacts, or null when the
@@ -659,21 +751,10 @@ export function createShellCaptureHandler<TEnv = unknown>(
         origin: opts.origin,
       });
 
-      // Bootstrap load raced against the deadline. A load that never resolves
-      // within maxWaitMs is the same bounded no-shell degrade as a shell that
-      // never goes quiet: return null, do not hang. A load that REJECTS is a
-      // genuine error and still propagates (it is not the deadline). `null` is
-      // the deadline sentinel — disjoint from the load's `Promise<string>`, so
-      // the race narrows to `string | null` with no wrapper. The no-op catch
-      // keeps a late rejection off the unhandledRejection path when the deadline
-      // already won; a rejection that lands first still propagates out.
-      const load = loadBootstrapScriptContent();
-      load.catch(() => {});
-      const bootstrapScriptContent = await Promise.race([
-        load,
-        deadline.promise.then(() => null),
-      ]);
-      if (bootstrapScriptContent === null) {
+      // Bootstrap resolution raced against the deadline (see resolveBootstrap):
+      // null means the deadline won — the bounded no-shell degrade.
+      const bootstrap = await resolveBootstrap(deps, deadline.promise);
+      if (bootstrap === null) {
         return null;
       }
 
@@ -689,7 +770,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       const abortReason = { rangoShellCaptureAbort: true };
       const prerenderPromise = prerender(<SsrRoot />, {
         signal: controller.signal,
-        ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+        ...bootstrap,
         // Explicit option only — the ssr:false auto-raise is live-SSR scoped
         // (RangoBaseOptions.progressiveChunkSize documents the contract); the
         // capture handler starts prerender without deserializing the payload,

package/src/testing/flight.ts

@@ -7,14 +7,15 @@
  * the same react-server-dom serializer the router uses at runtime. It runs in
  * plain node (no Vite, no browser), but ONLY under the `react-server` export
  * condition. The serializer is the VENDORED build shipped with
- * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc` entry top-level
- * imports Vite virtual modules and is not usable outside a Vite build.
+ * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc/server` entry
+ * top-level imports Vite virtual modules and is not usable outside a Vite
+ * build.
  *
  * Run the example/tests for this module via the dedicated rsc vitest project
  * (vitest.rsc.config.ts), which forces `--conditions=react-server` on the
  * worker. The main vitest project must NOT use that condition (it would flip
  * React to the no-hooks server build and break the ~50 tests that mock
- * @vitejs/plugin-rsc/rsc).
+ * @vitejs/plugin-rsc/rsc/server).
  *
  * Scope / limitations (v1):
  * - Server-only / leaf trees. A tree containing a CLIENT component emits an

package/src/testing/index.ts

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

package/src/testing/run-client-revalidate.ts

@@ -0,0 +1,108 @@
+/**
+ * runClientRevalidate — unit-test clientUrls() revalidate() predicates.
+ *
+ * Builds the same {@link ClientRevalidateArgs} the browser collector passes
+ * and evaluates the predicate(s) through the SAME chain evaluator production
+ * uses (client-urls/revalidate-chain.ts) — locked default, boolean
+ * short-circuit, soft-verdict threading, and fail-open are the production
+ * code paths, not a re-implementation. Pass an array to test a chain.
+ *
+ * Synchronous: client revalidate functions must be sync.
+ */
+
+import { makeIsAction, resolveActionRefId } from "../router/is-action.js";
+import {
+  lockedClientDefault,
+  runClientRevalidateChain,
+} from "../client-urls/revalidate-chain.js";
+import { toURL } from "./to-url.js";
+import type {
+  ClientRevalidateArgs,
+  ClientRevalidateFn,
+} from "../client-urls/types.js";
+
+const DEFAULT_URL = "http://localhost/";
+
+function resolveActionId(
+  action: ((...args: never[]) => unknown) | string | undefined,
+): string | undefined {
+  if (action === undefined) return undefined;
+  if (typeof action === "string") return action;
+  const id = resolveActionRefId(action);
+  if (id === undefined) {
+    throw new Error(
+      "runClientRevalidate: `action` must be a single imported server action " +
+        "(carrying its build-injected id) or an actionId string. The passed " +
+        "function has no $id/$$id — outside a built app, pass the id string " +
+        'your predicate should match (e.g. "src/actions/cart.ts#addToCart").',
+    );
+  }
+  return id;
+}
+
+/**
+ * Options for {@link runClientRevalidate}. Defaults model a same-URL
+ * navigation with no action (locked default `false`).
+ */
+export interface RunClientRevalidateOptions {
+  currentUrl?: string | URL;
+  nextUrl?: string | URL;
+  currentParams?: Record<string, string>;
+  nextParams?: Record<string, string>;
+  stale?: boolean;
+  /**
+   * The triggering action: a single imported reference (id resolved via
+   * `$id ?? $$id`; throws if the function carries neither) or a raw actionId
+   * string. A namespace/object is rejected — it cannot identify the ONE
+   * action that triggered the request. Omit for a plain navigation.
+   */
+  action?: ((...args: never[]) => unknown) | string;
+  /**
+   * Model an action-triggered refetch GET: predicates see `isAction()` as
+   * true, but the locked default stays the navigation default, matching how
+   * the server evaluates that request (no actionContext). Defaults to
+   * treating a provided `action` as the action POST itself.
+   */
+  actionRequest?: boolean;
+}
+
+/**
+ * Run one clientUrls `revalidate()` predicate — or a chain, in declaration
+ * order — against production-built args. Returns the final boolean decision
+ * (locked default if every predicate defers or throws).
+ */
+export function runClientRevalidate(
+  fn: ClientRevalidateFn | readonly ClientRevalidateFn[],
+  opts: RunClientRevalidateOptions = {},
+): boolean {
+  const currentUrl = toURL(opts.currentUrl, new URL(DEFAULT_URL));
+  const nextUrl = toURL(opts.nextUrl, currentUrl);
+  const currentParams = opts.currentParams ?? {};
+  const nextParams = opts.nextParams ?? currentParams;
+  const inAction = opts.action !== undefined;
+  const actionId = resolveActionId(opts.action);
+  const defaultShouldRevalidate = lockedClientDefault({
+    actionRequest: opts.actionRequest ?? inAction,
+    currentParams,
+    nextParams,
+    currentUrl,
+    nextUrl,
+  });
+
+  const baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate"> = {
+    currentUrl,
+    nextUrl,
+    currentParams,
+    nextParams,
+    stale: opts.stale ?? false,
+    isAction: makeIsAction(actionId, inAction),
+    ...(actionId !== undefined ? { actionId } : {}),
+  };
+
+  return runClientRevalidateChain(
+    Array.isArray(fn) ? fn : [fn],
+    baseArgs,
+    defaultShouldRevalidate,
+    "runClientRevalidate predicate",
+  );
+}

package/src/testing/run-transition-when.ts

@@ -35,9 +35,7 @@ import type { OnErrorCallback } from "../types/error-types.js";
 import type { EntryData } from "../server/context.js";
 import { evaluatePprTransitionWhen } from "../router/transition-when.js";
 import { invokeOnError } from "../router/error-handling.js";
-
-const toURL = (v: string | URL, base: URL): URL =>
-  typeof v === "string" ? new URL(v, base.origin) : v;
+import { toURL } from "./to-url.js";
 
 /**
  * Options for runTransitionWhen. All navigation/action fields are optional and

package/src/testing/to-url.ts

@@ -0,0 +1,5 @@
+/** Shared string|URL coercion for the testing primitives. */
+export function toURL(value: string | URL | undefined, fallback: URL): URL {
+  if (value === undefined) return fallback;
+  return typeof value === "string" ? new URL(value, fallback.origin) : value;
+}

package/src/testing/vitest-stubs/plugin-rsc.ts

@@ -1,8 +1,9 @@
-// Stub for `@vitejs/plugin-rsc/rsc`, shipped so consumers do not have to write a
-// per-file `vi.mock(...)`. Importing a router internal transitively pulls this
-// module, whose real top-level body imports Vite virtuals that do not resolve in
-// plain node. The unit/integration primitives (dispatch/runLoader/runMiddleware)
-// never render RSC, so empty fns suffice.
+// Stub for `@vitejs/plugin-rsc/rsc` and the split `/rsc/server`, `/rsc/client`
+// entries, shipped so consumers do not have to write a per-file `vi.mock(...)`.
+// Importing a router internal transitively pulls this module, whose real
+// top-level body imports Vite virtuals that do not resolve in plain node. The
+// unit/integration primitives (dispatch/runLoader/runMiddleware) never render
+// RSC, so empty fns suffice.
 export const createFromReadableStream = (): never => {
   throw new Error("plugin-rsc stub: createFromReadableStream not available");
 };
@@ -14,3 +15,10 @@ export const decodeReply = (): undefined => undefined;
 export const decodeAction = (): undefined => undefined;
 export const decodeFormState = (): undefined => undefined;
 export const createTemporaryReferenceSet = (): Record<string, never> => ({});
+export const encodeReply = (): never => {
+  throw new Error("plugin-rsc stub: encodeReply not available");
+};
+export const createClientTemporaryReferenceSet = (): Record<
+  string,
+  never
+> => ({});

package/src/testing/vitest.ts

@@ -18,7 +18,8 @@
  *   `@rangojs/router` specifier to its react-server entry (real impls) while
  *   leaving React as the client build — which is exactly what this helper does.
  * - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
- *   (whose real body imports unresolvable Vite virtuals) are stubbed.
+ *   plus `/rsc/server`, `/rsc/client` (whose real body imports unresolvable
+ *   Vite virtuals) are stubbed.
  * - Cloudflare apps additionally import the `cloudflare:workers` /
  *   `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
  *
@@ -126,7 +127,7 @@ export function rangoTestAliases(
       replacement: here("src/testing/vitest-stubs/version.ts"),
     },
     {
-      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
     },
   ];

package/src/types/handler-context.ts

@@ -541,8 +541,10 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
 /**
  * A reference to a server action, used by `isAction()` in a revalidate predicate.
  *
- * Either a directly imported action (`import { addToCart }`) or a namespace
- * import of an action module (`import * as CartActions`). Matching resolves the
+ * Either a directly imported action (`import { addToCart }`), a namespace
+ * import of an action module (`import * as CartActions`), an object
+ * literal of actions (`{ addToCart, removeFromCart }`), or a grouped
+ * namespace (`{ Cart: CartActions, Order: OrderActions }`). Matching resolves the
  * action's build-injected id (`path#export`) — the same identity the router uses
  * for `actionId` — so a renamed or moved action breaks at compile time instead
  * of silently failing to match.
@@ -551,6 +553,9 @@ export type ActionRef =
   | ((...args: never[]) => unknown)
   | Record<string, unknown>;
 
+/** The `isAction()` matcher passed to server and client `revalidate()` predicates. */
+export type IsActionFn = (...actions: ActionRef[]) => boolean;
+
 /**
  * Revalidation function called during client-side navigation to decide whether
  * a segment (layout, route, parallel slot, or loader) should be re-rendered.
@@ -643,8 +648,10 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
   /**
    * Typed, rename-safe action matching. Returns `true` when the action that
    * triggered this revalidation is one of the given references — or, for a
-   * namespace import (`import * as CartActions`), any export of that module —
-   * and `false` otherwise (including plain navigation with no action).
+   * namespace import (`import * as CartActions`), object literal
+   * (`{ addToCart, removeFromCart }`), or grouped namespaces
+   * (`{ Cart: CartActions }`), any of those exports — and `false`
+   * otherwise (including plain navigation with no action).
    *
    * Called with NO arguments it answers "is this request an action at all?":
    * `true` for any action, `false` on plain navigation. Use the bare form when
@@ -668,9 +675,10 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
    * revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
    * revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any in the module
+   * revalidate((ctx) => ctx.isAction({ addToCart, removeFromCart }) || undefined); // object form
    * ```
    */
-  isAction: (...actions: ActionRef[]) => boolean;
+  isAction: IsActionFn;
   /** URL where the action was executed (the page the user was on when they triggered the action). */
   actionUrl?: URL;
   /** Return value from the action execution. Can be used to conditionally revalidate based on the action's outcome. */

package/src/types/index.ts

@@ -38,6 +38,7 @@ export type {
   RevalidateParams,
   ShouldRevalidateFn,
   ActionRef,
+  IsActionFn,
   RouteKeys,
   ExtractRouteParams,
   HandlersForRouteMap,

package/src/vite/plugins/expose-action-id.ts

@@ -92,6 +92,27 @@ function isUseServerModule(filePath: string): boolean {
   }
 }
 
+/**
+ * Per-reference own `bind` injected next to `$$id`. React's client.browser
+ * build carries no server-reference metadata across `.bind()` (the
+ * edge/node/server builds install an own `bind` on each reference that
+ * does), so `isAction(boundStub)` would silently miss in the browser only.
+ * Installing the same per-reference own `bind` here — scoped to the stubs
+ * this plugin already wraps, guarded to never override an existing own
+ * `bind` — closes that without mutating the global Function.prototype
+ * (which would re-wrap once per Vite environment/HMR pass and break
+ * native-function detection for co-loaded code). The helper re-installs
+ * itself on the bound result so chained binds keep the metadata too.
+ */
+export const ACTION_BIND_HELPER_NAME: string = "__rangoActionBind";
+export const ACTION_BIND_HELPER_SOURCE: string = `var ${ACTION_BIND_HELPER_NAME} = function () {
+  var bound = Function.prototype.bind.apply(this, arguments);
+  if (typeof this.$id === "string") bound.$id = this.$id;
+  if (typeof this.$$id === "string") bound.$$id = this.$$id;
+  bound.bind = ${ACTION_BIND_HELPER_NAME};
+  return bound;
+};`;
+
 function applyServerReferenceWrapping(
   code: string,
   s: MagicString,
@@ -126,10 +147,17 @@ function applyServerReferenceWrapping(
       }
     }
 
-    const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; return fn; })(${fnCall}(${idArg}${rest}))`;
+    const replacement =
+      `(function(fn) { fn.$$id = ${finalIdArg}; ` +
+      `if (!Object.prototype.hasOwnProperty.call(fn, "bind")) fn.bind = ${ACTION_BIND_HELPER_NAME}; ` +
+      `return fn; })(${fnCall}(${idArg}${rest}))`;
     s.overwrite(start, end, replacement);
   }
 
+  if (hasChanges) {
+    s.prepend(`${ACTION_BIND_HELPER_SOURCE}\n`);
+  }
+
   return hasChanges;
 }