@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/ssr/inject-rsc-eager.ts

@@ -0,0 +1,167 @@
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+
+/**
+ * Eager Flight-payload injector for the PPR resume path.
+ *
+ * rsc-html-stream's injectRSCPayload starts forwarding Flight chunks only from
+ * inside its first transform() callback — i.e. AFTER the first HTML chunk flows.
+ * That policy exists for the normal document path (a <script> must not precede
+ * the doctype). On a PPR shell HIT it parks the ENTIRE hydration payload: the
+ * resumed fizz render emits its first chunk only when the first hole's data
+ * resolves (live loaders — measured ~1.5s on SFCC-backed pages), while the
+ * Flight root row is ready within ~30ms of the tail render starting. The client
+ * cannot call hydrateRoot until that root row arrives, so the lazy start held
+ * hydration hostage to the slowest loader for no structural reason: the stored
+ * prelude (a complete document through </body></html>) is already on the wire
+ * before the tail, so every tail byte is foster-parented and a Flight <script>
+ * is valid as the FIRST tail byte.
+ *
+ * This injector starts pumping Flight chunks immediately in start(). Ordering
+ * safety is kept by serializing ALL writes through one promise chain: fizz
+ * chunks buffered within a tick flush as one atomic task (same batching idea as
+ * the stock injector — never inject between two partial HTML chunks), and each
+ * Flight script is its own task, so scripts land only between batches. The
+ * trailer is stripped from passing HTML and re-appended once, after both
+ * streams complete — identical to the stock contract.
+ *
+ * RESUME/DATA-VARIANT ONLY. The normal document path must keep the stock
+ * injector: there the first bytes are the document head, and an eager script
+ * would precede the doctype.
+ */
+
+const encoder = new TextEncoder();
+const TRAILER = "</body></html>";
+
+// Escape closing script tags and HTML comments in JS content (ported from
+// rsc-html-stream/server; escapes the "s" instead of the slash so a regexp
+// literal like `0</script/` stays valid JS).
+function escapeScript(script: string): string {
+  return script.replace(/<!--/g, "<\\!--").replace(/<\/(script)/gi, "</\\$1");
+}
+
+function writeScript(
+  controller: TransformStreamDefaultController<Uint8Array>,
+  jsExpr: string,
+  nonce: string | undefined,
+): void {
+  controller.enqueue(
+    encoder.encode(
+      `<script${nonce ? ` nonce="${nonce}"` : ""}>${escapeScript(
+        `(self.__FLIGHT_DATA||=[]).push(${jsExpr})`,
+      )}</script>`,
+    ),
+  );
+}
+
+export function injectRSCPayloadEager(
+  rscStream: ReadableStream<Uint8Array>,
+  options?: { nonce?: string },
+): TransformStream<Uint8Array, Uint8Array> {
+  const nonce = options?.nonce;
+  const htmlDecoder = new TextDecoder();
+  const t0 = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
+  let loggedFirstFlight = false;
+  let loggedFirstHtml = false;
+
+  // All output goes through this chain: one task per Flight script, one task
+  // per buffered-HTML batch. A script can therefore never split a batch.
+  let queue: Promise<void> = Promise.resolve();
+  const enqueueTask = (fn: () => void): Promise<void> => {
+    queue = queue.then(fn);
+    return queue;
+  };
+
+  let buffered: Uint8Array[] = [];
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  let rscDone: Promise<void> = Promise.resolve();
+
+  function flushBufferedHTML(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): void {
+    if (INTERNAL_RANGO_DEBUG && !loggedFirstHtml && buffered.length > 0) {
+      loggedFirstHtml = true;
+      console.log(
+        `[Server][ppr] eager-inject: first resumed HTML batch +${Math.round(performance.now() - t0)}ms (abs ${Math.round(performance.now())})`,
+      );
+    }
+    for (const chunk of buffered) {
+      let buf = htmlDecoder.decode(chunk, { stream: true });
+      if (buf.endsWith(TRAILER)) buf = buf.slice(0, -TRAILER.length);
+      controller.enqueue(encoder.encode(buf));
+    }
+    const remaining = htmlDecoder.decode();
+    if (remaining.length) {
+      const out = remaining.endsWith(TRAILER)
+        ? remaining.slice(0, -TRAILER.length)
+        : remaining;
+      controller.enqueue(encoder.encode(out));
+    }
+    buffered.length = 0;
+    timeout = null;
+  }
+
+  async function pumpRSC(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): Promise<void> {
+    const rscDecoder = new TextDecoder("utf-8", { fatal: true });
+    const reader = rscStream.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // String when the chunk is valid unicode, base64 round-trip otherwise —
+      // same fallback the stock injector uses.
+      let jsExpr: string;
+      try {
+        jsExpr = JSON.stringify(rscDecoder.decode(value, { stream: true }));
+      } catch {
+        const base64 = JSON.stringify(
+          btoa(String.fromCodePoint(...(value as Uint8Array))),
+        );
+        jsExpr = `Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`;
+      }
+      await enqueueTask(() => {
+        if (INTERNAL_RANGO_DEBUG && !loggedFirstFlight) {
+          loggedFirstFlight = true;
+          console.log(
+            `[Server][ppr] eager-inject: first flight script +${Math.round(performance.now() - t0)}ms (abs ${Math.round(performance.now())})`,
+          );
+        }
+        writeScript(controller, jsExpr, nonce);
+      });
+    }
+    const remaining = rscDecoder.decode();
+    if (remaining.length) {
+      await enqueueTask(() =>
+        writeScript(controller, JSON.stringify(remaining), nonce),
+      );
+    }
+  }
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    start(controller) {
+      // The eager part: pump Flight immediately, before any HTML arrives.
+      rscDone = pumpRSC(controller).catch((err) => {
+        try {
+          controller.error(err);
+        } catch {
+          // Stream already errored/closed; nothing to signal.
+        }
+      });
+    },
+    transform(chunk, controller) {
+      buffered.push(chunk);
+      if (timeout) return;
+      // Batch same-tick fizz chunks so a Flight script cannot land between two
+      // partial HTML chunks of one logical write (stock injector's invariant).
+      timeout = setTimeout(() => {
+        void enqueueTask(() => flushBufferedHTML(controller));
+      }, 0);
+    },
+    async flush(controller) {
+      await rscDone;
+      if (timeout) clearTimeout(timeout);
+      await enqueueTask(() => flushBufferedHTML(controller));
+      controller.enqueue(encoder.encode(TRAILER));
+    },
+  });
+}

package/src/ssr/preinit-client-references.ts

@@ -0,0 +1,106 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { preinitModule } from "react-dom";
+
+/**
+ * JS/CSS asset deps plugin-rsc resolves for a client reference. Structural
+ * mirror of @vitejs/plugin-rsc's ResolvedAssetDeps — deliberately not imported:
+ * @rangojs/router/ssr never imports plugin-rsc directly; every plugin binding
+ * is injected by the virtual SSR entry (see SSRDependencies).
+ */
+export interface ClientReferenceDeps {
+  js: string[];
+  css: string[];
+}
+
+/**
+ * Callback shape of @vitejs/plugin-rsc/ssr's setOnClientReference. Fired
+ * (synchronously, inside the Fizz render) whenever a client reference module
+ * is accessed during SSR — the same moment plugin-rsc issues its own
+ * ReactDOM.preloadModule calls for the reference's chunks.
+ */
+export type OnClientReference = (reference: {
+  id: string;
+  deps: ClientReferenceDeps;
+}) => void;
+
+/** setOnClientReference from @vitejs/plugin-rsc/ssr (injected). */
+export type SetOnClientReference = (
+  callback: OnClientReference | undefined,
+) => void;
+
+/**
+ * Per-request CSP nonce channel for the preinit hook. The hook is installed
+ * once per isolate while the nonce is per request, and Fizz interleaves
+ * concurrent renders at task granularity — a module-scoped variable would race
+ * across requests and stamp request A's scripts with request B's nonce. ALS is
+ * the only channel that survives from the render call into the client-reference
+ * proxy access. A lost context degrades to nonce-less preinit (CSP blocks the
+ * head script; hydration still works through the nonce'd bootstrap), never to a
+ * wrong nonce.
+ */
+const preinitNonceStorage = new AsyncLocalStorage<string | undefined>();
+
+/**
+ * Run a Fizz render (renderToReadableStream / prerender / resume) with the
+ * request's nonce visible to the client-reference preinit hook. Nonce-less
+ * requests (the common non-CSP configuration) skip the ALS frame entirely —
+ * getStore() on an unentered storage already returns undefined, so the hook
+ * reads the same value either way.
+ */
+export function runWithPreinitNonce<T>(
+  nonce: string | undefined,
+  fn: () => T,
+): T {
+  return nonce === undefined ? fn() : preinitNonceStorage.run(nonce, fn);
+}
+
+/**
+ * Upgrade plugin-rsc's client-reference modulepreload hints to executing
+ * scripts: for every JS chunk a client reference needs, emit
+ * `<script type="module" src async>` hoisted into the document head instead of
+ * only `<link rel="modulepreload">`.
+ *
+ * Why: modulepreload fetches + compiles but never executes; the chunks then
+ * execute only when the entry's hydration import walks the graph — after the
+ * whole document has streamed. preinitModule starts execution as soon as each
+ * chunk arrives, overlapping it with body streaming (the pattern Next.js uses
+ * via ReactDOM.preinit for all non-bootstrap chunks). Under PPR the preinits
+ * run during shell capture, so the executing tags live in the stored prelude
+ * and chunk execution starts on the first flushed bytes.
+ *
+ * No duplicate tags: plugin-rsc's preloadModule fires first in the same
+ * synchronous block; Fizz's preinitModuleScript then clears the queued preload
+ * chunks for that URL and adopts its credentials (ReactFizzConfigDOM,
+ * renderState.preloads.moduleScripts). Capture→resume double-emission is
+ * prevented the same way: the `moduleScriptResources[src] = null` markers
+ * serialize inside the postponed state, so the resume pass preinits only
+ * references the shell never saw.
+ *
+ * crossOrigin "" matches plugin-rsc's preloadModule creds so the upgrade path
+ * reuses the same resource instead of forking on credential mismatch.
+ *
+ * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
+ * PR #694 has the Lighthouse/hydration numbers):
+ * - Fetch priority: an executing async module script fetches at Chromium's
+ *   async-script priority, below a bare modulepreload hint; preinitModule
+ *   forwards no fetchPriority (react-dom's public API drops it — only
+ *   `preinit` forwards it). Execution-overlap is bought with hint priority,
+ *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
+ *   dev documents have no head chunk scripts — a client module whose module
+ *   scope assumes body-parsed DOM can break in production only. The
+ *   `rango({ headScripts: "preload" })` escape hatch restores hint-only.
+ * - plugin-rsc's setOnClientReference is a single-slot, last-write-wins
+ *   setter: another registrant in the SSR environment silently replaces this
+ *   hook (or is replaced by it). No composition API exists upstream yet.
+ */
+export function installClientReferencePreinit(
+  setOnClientReference: SetOnClientReference,
+): void {
+  setOnClientReference(({ deps }) => {
+    const nonce = preinitNonceStorage.getStore();
+    for (const href of deps.js) {
+      preinitModule(href, { as: "script", crossOrigin: "", nonce });
+    }
+  });
+}

package/src/ssr/ssr-root.tsx

@@ -0,0 +1,261 @@
+import React from "react";
+import { expandSegmentFragments } from "../segment-fragments.js";
+import { renderSegments } from "../segment-system.js";
+import {
+  filterSegmentOrder,
+  filterRouteSegmentIds,
+} from "../browser/react/filter-segment-order.js";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { NonceContext } from "../browser/react/nonce-context.js";
+import { NavigationStoreContext } from "../browser/react/context.js";
+import type { NavigationStoreContextValue } from "../browser/react/context.js";
+import type { HandleData } from "../browser/types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import type {
+  EventController,
+  DerivedNavigationState,
+} from "../browser/event-controller.js";
+
+/**
+ * createFromReadableStream from @rangojs/router/internal/deps/ssr.
+ * Deserializes the Flight branch used to build the SSR VDOM.
+ */
+export type CreateFromReadableStream = <T>(
+  stream: ReadableStream<Uint8Array>,
+) => Promise<T>;
+
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+export interface RscPayload {
+  metadata?: {
+    segments?: ResolvedSegment[];
+    rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    matched?: string[];
+    pathname?: string;
+    params?: Record<string, string>;
+    basename?: string;
+    themeConfig?: ResolvedThemeConfig | null;
+    initialTheme?: Theme;
+    version?: string;
+  };
+}
+
+/**
+ * Consume an async generator and return a Promise that resolves with the final value.
+ * Used for SSR where we need to await all handle data before rendering.
+ */
+async function consumeAsyncGenerator(
+  generator: AsyncGenerator<HandleData, void, unknown>,
+): Promise<HandleData> {
+  let lastData: HandleData = {};
+  for await (const data of generator) {
+    lastData = data;
+  }
+  return lastData;
+}
+
+/**
+ * Create a minimal event controller for SSR.
+ * This provides the correct pathname so useNavigation returns the right value during SSR.
+ */
+function createSsrEventController(opts: {
+  pathname: string;
+  params?: Record<string, string>;
+  handleData?: HandleData;
+  matched?: string[];
+}): EventController {
+  const location = new URL(opts.pathname, "http://localhost");
+  let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
+  const handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: filterRouteSegmentIds(rawMatched),
+  };
+  const state: DerivedNavigationState = {
+    state: "idle",
+    isStreaming: false,
+    isNavigating: false,
+    location,
+    pendingUrl: null,
+    inflightActions: [],
+  };
+
+  return {
+    getState: () => state,
+    getLocation: () => location,
+    subscribe: () => () => {},
+    getActionState: () => ({
+      state: "idle",
+      actionId: null,
+      payload: null,
+      error: null,
+      result: null,
+    }),
+    subscribeToAction: () => () => {},
+    subscribeToHandles: () => () => {},
+    setHandleData: () => {},
+    getHandleState: () => handleState,
+    setRouteSegmentIds: () => {},
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
+    setLocation: () => {},
+    startNavigation: () => {
+      throw new Error("Navigation not supported during SSR");
+    },
+    abortNavigation: () => {},
+    startAction: () => {
+      throw new Error("Actions not supported during SSR");
+    },
+    abortAllActions: () => {},
+    getCurrentNavigation: () => null,
+    getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
+  };
+}
+
+/**
+ * Options for {@link createSsrRootComponent}.
+ */
+export interface SsrRootOptions {
+  /** createFromReadableStream for the SSR branch of the Flight stream. */
+  createFromReadableStream: CreateFromReadableStream;
+  /** The Flight stream branch to deserialize into the SSR VDOM. */
+  rscStream: ReadableStream<Uint8Array>;
+  /** Nonce for CSP; propagated to NonceContext. */
+  nonce?: string;
+  /**
+   * Fires once when the Flight payload root settles (resolve OR reject) — the
+   * signal that every client-module load the payload references completed and
+   * fizz can start emitting the tree. The capture pass gates its abort on
+   * this: a fully REPLAYED (prerendered) route's Flight stream goes
+   * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
+   * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
+   * graph), so an abort gated on Flight quiet alone fires first and freezes
+   * a zero-byte prelude. Masked-loader holes do NOT block this signal —
+   * they postpone below the root.
+   */
+  onPayloadSettled?: () => void;
+}
+
+/**
+ * Build the closure component that deserializes the Flight payload, consumes
+ * handles to completion, builds the segment tree, and wraps it in the
+ * NavigationStore / Nonce / Theme providers.
+ *
+ * The full-fizz path (renderHTML), the shell prerender pass (capture), and the
+ * shell resume pass all render this identical tree. `resume` requires the tree
+ * above the postponed holes to match the prerendered tree; rendering the same
+ * builder over the same replayed segments is what makes that hold. A fresh
+ * component instance per pass is fine — replay matches structure, not function
+ * identity.
+ *
+ * The memo slots (payload/handles/context/root) are closure-scoped to the
+ * returned instance, so each render pass memoizes independently. renderSegments
+ * is async: React.use() on a fresh promise would suspend and replay SsrRoot,
+ * re-running the whole segment-tree build unless the promise is memoized.
+ */
+export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
+  const { createFromReadableStream, rscStream, nonce, onPayloadSettled } = opts;
+
+  let payload: Promise<RscPayload> | undefined;
+  let handlesPromise: Promise<HandleData> | undefined;
+  let ssrContextValue: NavigationStoreContextValue | undefined;
+  let rootPromise: Promise<React.ReactNode> | undefined;
+
+  return function SsrRoot() {
+    if (payload === undefined) {
+      // Shell-HIT tails carry replayed segments as VERBATIM stored fragments
+      // (segment-fragments.ts, issue #700); expand them through this
+      // environment's deserializer before anything reads the segments. Every
+      // other payload (full render, capture, actions) has no envelopes and
+      // pays one field scan. onPayloadSettled fires AFTER expansion: the
+      // capture's fizz-readiness gate must include fragment module loads.
+      // Promise.resolve() adoption is load-bearing: some wirings (the build
+      // temp server's vendored Flight client) return a THENABLE Chunk whose
+      // .then returns undefined — chaining on it directly yields undefined.
+      payload = Promise.resolve(
+        createFromReadableStream<RscPayload>(rscStream),
+      ).then(async (resolvedPayload) => {
+        await expandSegmentFragments(
+          resolvedPayload.metadata?.segments,
+          createFromReadableStream,
+        );
+        return resolvedPayload;
+      });
+      if (onPayloadSettled) payload.then(onPayloadSettled, onPayloadSettled);
+    }
+    const resolved = React.use(payload);
+
+    const themeConfig = resolved.metadata?.themeConfig ?? null;
+    const pathname = resolved.metadata?.pathname ?? "/";
+
+    // Await handles before creating SSR event controller so hooks can
+    // read request-local handle data via NavigationStoreContext.
+    // The handles property is an async generator that yields on each push
+    // Memoize the promise since async generators can only be iterated once
+    let handleData: HandleData = {};
+    if (resolved.metadata?.handles) {
+      handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
+      handleData = React.use(handlesPromise);
+    }
+
+    // Create SSR context with request-local pathname/params/handles.
+    ssrContextValue ??= {
+      store: null as any,
+      eventController: createSsrEventController({
+        pathname,
+        params: resolved.metadata?.params,
+        handleData,
+        matched: resolved.metadata?.matched,
+      }),
+      navigate: async () => {},
+      refresh: async () => {},
+      version: resolved.metadata?.version,
+      basename: resolved.metadata?.basename,
+    };
+
+    // Build content tree from segments.
+    // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+    // Memoize like payload/handles above: renderSegments is async, so
+    // React.use() on a fresh promise suspends and replays SsrRoot, which
+    // would re-run the entire segment-tree build on every initial render.
+    rootPromise ??= Promise.resolve(
+      renderSegments(resolved.metadata?.segments ?? [], {
+        rootLayout: resolved.metadata?.rootLayout,
+      }),
+    );
+    let content: React.ReactNode = React.use(rootPromise);
+
+    // Wrap content with ThemeProvider if theme is enabled
+    if (themeConfig) {
+      content = (
+        <ThemeProvider
+          config={themeConfig}
+          initialTheme={resolved.metadata?.initialTheme}
+        >
+          {content}
+        </ThemeProvider>
+      );
+    }
+
+    // Wrap with NonceContext so client components (e.g. MetaTags) can
+    // apply CSP nonces to inline scripts during SSR. Always present to
+    // match the browser-side NavigationProvider tree shape for hydration.
+    content = (
+      <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
+    );
+
+    // Wrap with NavigationStoreContext for useNavigation hook
+    return (
+      <NavigationStoreContext.Provider value={ssrContextValue!}>
+        {content}
+      </NavigationStoreContext.Provider>
+    );
+  };
+}

package/src/static-handler.ts

@@ -31,46 +31,78 @@
  * ```
  */
 import type { ReactNode } from "react";
-import type { Handler, HandlerContext } from "./types.js";
-import type { PrerenderOptions } from "./prerender.js";
+import type { Handler } from "./types.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
+import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
-// -- Types ------------------------------------------------------------------
+export interface StaticHandlerOptions {
+  /**
+   * Keep handler in server bundle for live fallback (default: false).
+   * false: handler replaced with stub, source-only APIs excluded from bundle.
+   * true: handler stays in bundle, renders live at request time.
+   */
+  passthrough?: boolean;
+}
 
-export interface StaticHandlerDefinition<TParams extends Record<string, any> = any> {
+export interface StaticHandlerDefinition<
+  TParams extends Record<string, any> = any,
+> {
   readonly __brand: "staticHandler";
   /** Auto-generated unique ID (injected by Vite plugin). */
   $$id: string;
   /** In dev mode, the actual handler function that layout/path/parallel can call. */
   handler: Handler<TParams>;
   /** Static handler options (passthrough support). */
-  options?: PrerenderOptions;
+  options?: StaticHandlerOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
-// -- Function ---------------------------------------------------------------
+// Process-stable fallback id counter (mirrors createHandle/createLoader/Prerender).
+// Only assigned in bare unit tests where the Vite plugin did not inject an id.
+let runtimeStaticIdCounter = 0;
 
 export function Static<TParams extends Record<string, any> = {}>(
-  handler: (ctx: HandlerContext<TParams>) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions,
+  handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
+  options?: StaticHandlerOptions,
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
-// -- Implementation ---------------------------------------------------------
-
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
-  optionsOrId?: PrerenderOptions | string,
+  optionsOrId?: StaticHandlerOptions | string,
   maybeId?: string,
 ): StaticHandlerDefinition<TParams> {
-  let options: PrerenderOptions | undefined;
+  if (isCachedFunction(handler)) {
+    throw new Error(
+      'A "use cache" function cannot be used as a Static() handler. ' +
+        "Static handlers are rendered once at build time. Remove the " +
+        '"use cache" directive — Static already provides caching.',
+    );
+  }
+
+  let options: StaticHandlerOptions | undefined;
   let id: string;
 
   if (typeof optionsOrId === "string") {
     id = optionsOrId;
   } else {
-    options = optionsOrId as PrerenderOptions | undefined;
+    options = optionsOrId as StaticHandlerOptions | undefined;
     id = maybeId ?? "";
   }
 
+  if (!id && !isUnderTestRunner()) {
+    throw new Error(
+      "[rango] Static: missing $$id. Use `export const X = Static(...)` and " +
+        "ensure the exposeInternalIds Vite plugin is configured.",
+    );
+  }
+  if (!id) {
+    id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
+  }
+
   return {
     __brand: "staticHandler" as const,
     $$id: id,
@@ -79,11 +111,6 @@ export function Static<TParams extends Record<string, any>>(
   };
 }
 
-// -- Type guard -------------------------------------------------------------
-
-/**
- * Type guard to check if a value is a StaticHandlerDefinition.
- */
 export function isStaticHandler(
   value: unknown,
 ): value is StaticHandlerDefinition {