@rangojs/router 0.5.1 → 0.5.2

package/src/vite/plugins/server-ref-hashing.ts

@@ -0,0 +1,74 @@
+import type { Plugin } from "vite";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import { computeProductionHash } from "./client-ref-hashing.js";
+import { registerServerReferenceRegex } from "./server-reference-pattern.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+/**
+ * Replace dev-style server-reference ids with their production hashes. The temp
+ * server renders Static/Prerender in a dev/serve Vite server, so plugin-rsc mints
+ * a dev-style id (e.g. "/src/urls/prerender.tsx"); rewriting only the id (group 2)
+ * leaves the hoisted function and its trailing encrypted .bind(...) untouched.
+ * Exported for testing; used by hashServerRefs. Returns null if nothing changed.
+ */
+export function transformServerRefs(
+  code: string,
+  projectRoot: string,
+): string | null {
+  if (!code.includes("registerServerReference")) return null;
+
+  let hasReplacement = false;
+  const result = code.replace(
+    registerServerReferenceRegex(),
+    (match, _value: string, refKey: string) => {
+      // The temp server is not a long-lived HMR server, so ids are bare; strip a
+      // query suffix defensively so the hash matches plugin-rsc's manifest key.
+      const cleanKey = refKey.split("?")[0]!;
+      const hash = computeProductionHash(projectRoot, cleanKey);
+      if (hash === cleanKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    },
+  );
+
+  return hasReplacement ? result : null;
+}
+
+/**
+ * Server-side analog of hashClientRefs. Runs in the build-discovery temp server
+ * (a dev/serve Vite server, where plugin-rsc mints dev-style ids), rewriting
+ * registerServerReference ids to production hashes AFTER plugin-rsc's
+ * rsc:use-server transform (enforce:"post"), so the Flight serializer bakes the
+ * production hash into the stored prerender/static payloads.
+ *
+ * Without this, a server-created action embedded in a prerendered/static Flight
+ * is stored with a dev-style id that the production hash-keyed server-references
+ * manifest cannot resolve -> "server reference not found" on a build-time-cache
+ * hit. Mirrors hashClientRefs, which already does exactly this for the client
+ * half of the same payload (which is why client refs in stored Flight are
+ * already production hashes while server refs were not).
+ */
+export function hashServerRefs(projectRoot: string): Plugin {
+  const counter = createCounter(debug, "hash-server-refs");
+  return {
+    name: "@rangojs/router:hash-server-refs",
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformServerRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    },
+  };
+}

package/src/vite/plugins/server-reference-pattern.ts

@@ -0,0 +1,10 @@
+// plugin-rsc's rsc:use-server transform emits inline/exported server references
+// as `registerServerReference(<value>, "<id>", "<name>")`, where <value> is a
+// hoisted identifier (no top-level comma) and a trailing `.bind(null,
+// encryptActionBoundArgs(...))` lies OUTSIDE the call. Two plugins parse this
+// same shape -- expose-action-id ($id wrapping) and server-ref-hashing (id ->
+// production hash) -- so the pattern has a single owner here. Returns a fresh
+// /g RegExp per call to avoid sharing lastIndex state across callers.
+export function registerServerReferenceRegex(): RegExp {
+  return /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+}

package/src/vite/rango.ts

@@ -2,7 +2,9 @@ import { type PluginOption } from "vite";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
+import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import {
+  createLoaderScanStubPlugin,
   exposeInternalIds,
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
@@ -275,6 +277,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         entries: finalEntries,
         serverHandler: false,
         clientChunks,
+        // Share one encryption key with the build-discovery temp server so
+        // build-time prerender/static inline-action bound args decrypt at runtime.
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }) as PluginOption,
     );
     plugins.push(clientRefDedup());
@@ -521,6 +526,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       rsc({
         entries: finalEntries,
         clientChunks,
+        // Share one encryption key with the build-discovery temp server so
+        // build-time prerender/static inline-action bound args decrypt at runtime.
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }) as PluginOption,
     );
     plugins.push(clientRefDedup());
@@ -551,6 +559,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     },
   });
 
+  plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());
   plugins.push(exposeInternalIds());

package/src/vite/router-discovery.ts

@@ -45,6 +45,8 @@ import {
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
 import { hashClientRefs } from "./plugins/client-ref-hashing.js";
+import { hashServerRefs } from "./plugins/server-ref-hashing.js";
+import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
   createDiscoveryState,
@@ -224,9 +226,26 @@ async function createTempRscServer(
           ssr: "virtual:entry-ssr",
           rsc: state.resolvedEntryPath!,
         },
+        // The temp server renders Static/Prerender output and encrypts inline-
+        // action bound args. Give it the SAME key as the main build/dev runtime
+        // (defineEncryptionKeyExpr is process-cached) so those args decrypt at
+        // invocation. Unconditional, NOT build-only: under Cloudflare/workerd dev
+        // the RSC env has no module runner, so prerender is rendered by THIS temp
+        // server (via /__rsc_prerender), and the action decrypts in the main
+        // runtime with the rango.ts key -- gating on forceBuild left dev encrypting
+        // with the temp server's own random key, failing decryptActionBoundArgs.
+        // (hashServerRefs stays build-only: dev keeps dev-style ids the dev runtime
+        // resolves directly.)
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }),
-      // hashClientRefs only in build mode — production bundles need hashed refs
-      ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
+      // hashClientRefs/hashServerRefs only in build mode — production bundles
+      // need hashed refs. hashServerRefs is the server-side analog: it rewrites
+      // registerServerReference dev-style ids to production hashes so a
+      // server-created action embedded in prerendered/static Flight resolves
+      // against the production manifest on a build-time-cache hit.
+      ...(options.forceBuild
+        ? [hashClientRefs(state.projectRoot), hashServerRefs(state.projectRoot)]
+        : []),
       createVersionPlugin(),
       // Before the stub plugin, so "virtual:entry-ssr" resolves to the real
       // SSR entry when the shell endpoint needs it (see the option doc).

package/src/vite/utils/shared-utils.ts

@@ -249,16 +249,21 @@ export function onwarn(
   defaultHandler(warning);
 }
 
+/**
+ * All of `browser/prefetch/` belongs to the eager "router" chunk — including
+ * the modules reachable only via loader.ts's dynamic import. #766 split those
+ * into a separate lazy chunk to trim the eager runtime (~2.3 KB gzip), but
+ * production's `defaultPrefetch: "viewport"` loads them on almost every page,
+ * so the split became a document -> router -> runtime request waterfall
+ * (measured 502 ms critical-path latency in a deployed worker). Same-chunk
+ * placement resolves the dynamic import without a network fetch
+ * (`Promise.resolve().then(...)` in the emitted chunk), and the merged chunk
+ * gzips smaller than the two chunks did apart. Do not re-split without new
+ * information (AGENTS.md, Bundle hygiene, rejected optimizations).
+ */
 export function getManualChunks(id: string): string | undefined {
   const normalized = Vite.normalizePath(id);
 
-  if (
-    /\/browser\/prefetch\/(?:runtime|fetch|queue|observer|policy|resource-ready)\.[cm]?[jt]sx?(?:[?#].*)?$/.test(
-      normalized,
-    )
-  ) {
-    return undefined;
-  }
   if (
     normalized.includes("node_modules/react/") ||
     normalized.includes("node_modules/react-dom/") ||

package/dist/types.backup/__internal.d.ts

@@ -1,127 +0,0 @@
-/**
- * Internal Types - Implementation Details
- *
- * @internal
- * These types are for internal use only and should not be relied upon by consumers.
- * They may change without notice between versions.
- *
- * If you find yourself needing these types, please open an issue to discuss
- * adding them to the public API.
- */
-/**
- * @internal
- * Internal representation of a resolved route segment.
- * Used during route matching and rendering pipeline.
- */
-export type { ResolvedSegment, SegmentMetadata } from "./types.js";
-/**
- * @internal
- * Internal match result from route resolution.
- */
-export type { MatchResult, SlotState } from "./types.js";
-/**
- * @internal
- * Context for intercept route selection.
- */
-export type { InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "./server/context.js";
-/**
- * @internal
- * RSC protocol payload structure.
- */
-export type { RscPayload, ReactFormState } from "./rsc/types.js";
-/**
- * @internal
- * Internal navigation store interface.
- */
-export type { NavigationStore, NavigationBridge, RscMetadata, ActionResult, InflightAction, NavigationState, TrackedActionState, ActionStateListener, SegmentCache, SegmentState, NavigationUpdate, } from "./browser/types.js";
-/**
- * @internal
- * Internal handle storage mechanism.
- */
-export type { HandleStore, HandleData } from "./server/handle-store.js";
-/**
- * @internal
- * Segment handle data in cache.
- */
-export type { SegmentHandleData } from "./cache/types.js";
-/**
- * @internal
- * Internal cache entry data structure.
- */
-export type { CachedEntryData, CacheGetResult, SerializedSegmentData, CacheDefaults, } from "./cache/types.js";
-/**
- * @internal
- * Router context for AsyncLocalStorage.
- */
-export type { RouterContext, RevalidationContext, InterceptResult, } from "./router/router-context.js";
-/**
- * @internal
- * Route match context during pipeline processing.
- */
-export type { MatchContext, MatchPipelineState, } from "./router/match-context.js";
-/**
- * @internal
- * Pattern matching result.
- */
-export type { RouteMatchResult } from "./router/pattern-matching.js";
-/**
- * @internal
- * Entry data during route traversal.
- */
-export type { EntryData, InterceptEntry, MetricsStore, PerformanceMetric, EntryCacheConfig, EntryPropCommon, EntryPropDatas, LoaderEntry, EntryPropSegments, } from "./server/context.js";
-/**
- * @internal
- * Internal handler context with additional props for router internals.
- * Includes `_currentSegmentId` and `_responseType`.
- */
-export type { InternalHandlerContext } from "./types.js";
-/**
- * @internal
- * Builds React element trees from route segments.
- */
-export { renderSegments } from "./segment-system.js";
-/**
- * @internal
- * Error sanitization and network error utilities.
- */
-export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
-/**
- * @internal
- * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
- */
-export type { ScopedRouteMap } from "./types.js";
-/**
- * @internal
- * Type-level utilities for reverse URL generation.
- */
-export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
-/**
- * @internal
- * Individual telemetry event types.
- */
-export type { RequestStartEvent, RequestEndEvent, RequestErrorEvent, RequestTimeoutEvent, LoaderStartEvent, LoaderEndEvent, LoaderErrorEvent, HandlerErrorEvent, CacheDecisionEvent, RevalidationDecisionEvent, } from "./router/telemetry.js";
-/**
- * @internal
- * Type guard for prerender handler definitions.
- */
-export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
-/**
- * @internal
- * Type guard for static handler definitions.
- */
-export { isStaticHandler } from "./static-handler.js";
-/**
- * @internal
- * Sentinel used to tag response-type route entries.
- */
-export { RESPONSE_TYPE } from "./urls.js";
-/**
- * @internal
- * Debug utilities for route matching performance analysis.
- */
-export { enableMatchDebug, getMatchDebugStats, } from "./router/pattern-matching.js";
-/**
- * @internal
- * Debug utilities for manifest inspection and comparison.
- */
-export { serializeManifest, compareManifests, formatManifestDiff, type SerializedEntry, type SerializedManifest, } from "./debug.js";

package/dist/types.backup/bin/rango.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types.backup/browser/action-coordinator.d.ts

@@ -1,57 +0,0 @@
-import type { ActionEntry } from "./event-controller.js";
-/**
- * Post-reconciliation action outcome (discriminated union). Error and
- * full-update-unsupported cases are handled inline in the bridge before
- * reconciliation; this only covers successfully-reconciled partial responses.
- */
-type ActionScenario = {
-    type: "navigated-away";
-    historyKeyChanged: boolean;
-    onInterceptRoute: boolean;
-} | {
-    type: "hmr-missing";
-} | {
-    type: "consolidation-needed";
-    segmentIds: string[];
-} | {
-    type: "concurrent-skip";
-    otherFetchingCount: number;
-} | {
-    type: "normal";
-};
-/**
- * Plain data inputs for classifying a post-reconciliation action outcome.
- * No browser objects or controller references — all values are snapshots.
- */
-export interface ActionOutcomeInput {
-    /** This action's unique instance ID */
-    handleId: string;
-    /** All in-flight action entries (snapshot from event controller) */
-    inflightActions: Map<string, ActionEntry>;
-    /** Whether any concurrent actions occurred (controller-level shared flag) */
-    hadAnyConcurrentActions: boolean;
-    /** Segments revalidated by concurrent actions (from tracking set) */
-    revalidatedSegments: Set<string>;
-    /** window.location.pathname captured at action start */
-    actionStartPathname: string;
-    /** window.location.pathname at classification time */
-    currentPathname: string;
-    /** window.history.state?.key captured at action start */
-    actionStartLocationKey: string | undefined;
-    /** window.history.state?.key at classification time */
-    currentLocationKey: string | undefined;
-    /** Number of segments after reconciliation */
-    reconciledSegmentCount: number;
-    /** Number of matched segment IDs from server */
-    matchedCount: number;
-    /** Current intercept source URL (null when not on intercept route) */
-    currentInterceptSource: string | null;
-}
-/**
- * Classify a post-reconciliation action outcome. Ordered priority chain: each
- * case assumes the earlier ones are false (e.g. concurrent-skip only applies on
- * the still-current route, consolidation only once no action is still fetching).
- * The bridge calls this to decide whether to render, skip, consolidate, or refetch.
- */
-export declare function classifyActionOutcome(input: ActionOutcomeInput): ActionScenario;
-export {};

package/dist/types.backup/browser/action-fence.d.ts

@@ -1,33 +0,0 @@
-/**
- * Action fence: a refcounted flag that is raised while a server action is in
- * flight and lowered when it resolves.
- *
- * It replaces the eager cache clear the action bridge used to do at action
- * start. While the fence is up, the decision of whether the action invalidated
- * anything is deferred to the response:
- *
- * - prefetch consumption is suspended (a queued prefetch result is not served),
- * - a genuine navigation during the flight fetches with `cache: "no-store"` so
- *   it cannot be served stale bytes from the browser's Vary-keyed HTTP cache,
- * - popstate reads are treated as stale-while-revalidate.
- *
- * Nothing is wiped, rotated, or broadcast while the fence is up — that is what
- * keeps a sibling tab from seeing a pre-commit signal. Refcounted so concurrent
- * actions compose: each action raises and lowers its own reference, and the
- * fence is down only when the count reaches zero.
- *
- * The refcount is a single module-level counter, not keyed by routerId.
- * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
- * read it unscoped, so an action in one router would suppress another router's
- * navigation/prefetch caches. This is correct only because two routers cannot
- * coexist in one live document: an SPA navigation crossing a host-router
- * boundary forces a full document reload (src/router/request-classification.ts
- * app-switch terminal), so there is always exactly one live router per
- * document. A future multi-router-in-one-document feature must not silently
- * inherit this global, cross-router cache suppression.
- */
-export declare function enterActionFence(): void;
-export declare function exitActionFence(): void;
-export declare function isActionFenceActive(): boolean;
-/** Test-only: reset the refcount between cases. */
-export declare function __resetActionFence(): void;

package/dist/types.backup/browser/app-shell.d.ts

@@ -1,34 +0,0 @@
-import type { ComponentType, ReactNode } from "react";
-/**
- * App-shell metadata: the per-router fields describing the "envelope" around
- * the current app's segment tree — the rootLayout (Document), basename,
- * version, and router identity. Set once from the initial RSC payload and read
- * through the AppShellRef when rendering segments.
- *
- * This is a per-document value. A navigation that crosses a host-router app
- * boundary is a full document load (the server returns X-RSC-Reload for it;
- * see request-classification.ts, mode "app-switch"), so the target app's shell
- * — along with everything else document-level (theme, warmup, prefetch-TTL) —
- * is established fresh by the target app's own load. The shell is never swapped
- * in place within a session.
- */
-export interface AppShell {
-    /** Router identity. Used to namespace per-app client state (e.g. the
-     *  rango-state localStorage key) so sibling apps on the same origin
-     *  cannot observe each other's cache invalidations. */
-    routerId?: string;
-    rootLayout?: ComponentType<{
-        children: ReactNode;
-    }>;
-    basename?: string;
-    version?: string;
-}
-/**
- * Container for the active app shell. Read-through via `get()` so closures
- * (e.g. the segment renderer) capture the ref and read the shell at call time
- * rather than closing over a stale snapshot.
- */
-export interface AppShellRef {
-    get(): AppShell;
-}
-export declare function createAppShellRef(initial: AppShell): AppShellRef;

package/dist/types.backup/browser/app-version.d.ts

@@ -1,6 +0,0 @@
-/**
- * Mutable app version — updated after HMR revalidation.
- * Read by prefetch, navigation, and context code.
- */
-export declare function getAppVersion(): string | undefined;
-export declare function setAppVersion(version: string | undefined): void;

package/dist/types.backup/browser/connection-warmup.d.ts

@@ -1,31 +0,0 @@
-/**
- * Connection warmup: keep TLS alive after idle periods.
- *
- * After IDLE_TIMEOUT of no user interaction the connection is marked "cold".
- * On the next pointer/touch interaction or a visibility change, a HEAD request
- * warms the TLS connection before the user actually clicks a link.
- *
- * Extracted from NavigationProvider so the idle/cold/warmup state machine is
- * unit-testable with an injected environment (document, fetch, timers).
- *
- * Ordering bug this guards against: the warmup listeners (mousemove/touchstart)
- * share events with the idle-reset listeners, and the idle-reset listener is
- * registered first, so it clears the live "cold" flag before the warmup
- * listener reads it on the same event. A separate coldLatch — set when the
- * connection goes cold and cleared only when warmup fires or listeners detach,
- * never by the idle reset — lets the warmup decision see the pre-reset cold
- * state regardless of listener ordering.
- */
-type TimerHandle = ReturnType<typeof setTimeout>;
-export interface WarmupEnv {
-    doc: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
-    fetch: typeof fetch;
-    setTimeout: (fn: () => void, ms: number) => TimerHandle;
-    clearTimeout: (handle: TimerHandle | undefined) => void;
-}
-/**
- * Start the connection-warmup state machine. Returns a cleanup function that
- * cancels timers and removes all listeners.
- */
-export declare function startConnectionWarmup(env?: WarmupEnv): () => void;
-export {};

package/dist/types.backup/browser/cookie-name.d.ts

@@ -1,66 +0,0 @@
-/**
- * Rango state cookie: value codec and attribute serialization.
- *
- * Shared by the client (the document.cookie writer in rango-state.ts) and the
- * server (the Set-Cookie writer in invalidateClientCache). Environment-agnostic:
- * no window/document access and no name composition.
- *
- * Name RESOLUTION deliberately lives elsewhere (router init, see
- * router/state-cookie-name.ts). Keeping composition out of this shared module
- * is what lets the client read the server-resolved name verbatim and compose
- * nothing.
- */
-/** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
-export declare const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
-/** Internal response header carrying the keepClientCache() directive. */
-export declare const KEEP_CACHE_HEADER = "x-rango-keep-cache";
-/** True for a per-client signal header. */
-export declare function isPerClientSignalHeader(name: string): boolean;
-/** True if `headers` carries any per-client signal. */
-export declare function hasPerClientSignal(headers: Headers): boolean;
-/** Remove every per-client signal header from `headers` in place. */
-export declare function stripPerClientSignals(headers: Headers): void;
-/**
- * Read the raw, UNDECODED value of a single cookie from a cookie string (a
- * `document.cookie` jar or a request `Cookie` header). Shared by both seats so
- * the client mirror and the server monotonic-guard read the SAME jar entry —
- * their agreement is the guard's contract. First match wins (the entry the
- * client's mirror holds); exact name boundary via the `=`; an empty value
- * (`name=`) returns null (treated as absent, not a usable prior value).
- */
-export declare function getRawCookieValue(cookieString: string | null, name: string): string | null;
-/**
- * Encode a state value for the wire: `encodeURIComponent(version):timestamp`.
- * Only the build-derived version is encoded (it is arbitrary); the `:`
- * separator and numeric timestamp stay raw, so the `{version}:{timestamp}`
- * shape survives and `:` is a legal cookie-value octet.
- */
-export declare function encodeStateValue(version: string, timestamp: number): string;
-/** Parsed state value. `version` is decoded; `timestamp` is the raw integer. */
-export interface StateValue {
-    version: string;
-    timestamp: number;
-}
-/**
- * Decode a wire value back into `{version, timestamp}`. Returns null for a
- * malformed value (no `:`, empty version, or non-numeric timestamp) so callers
- * mint fresh instead of trusting garbage.
- */
-export declare function decodeStateValue(raw: string): StateValue | null;
-/**
- * Mint a fresh state value whose timestamp is strictly greater than the previous
- * one, so a re-mint inside the same millisecond (or a backward clock step) still
- * differs from the current value. `prevRaw` is the current wire value (the
- * client's in-memory mirror, or the server's inbound header/cookie) or null; its
- * timestamp is the floor. Shared by both seats so the monotonic guard lives once.
- */
-export declare function mintStateValue(version: string, prevRaw: string | null): string;
-/**
- * Attribute string for the state cookie. Session cookie (no Max-Age/Expires),
- * Path=/ (whole app), SameSite=Lax (sent on top-level navigations), and Secure
- * only on https so the document.cookie write does not silently fail on plain
- * http dev. Never HttpOnly (the client reads and writes it).
- */
-export declare function stateCookieAttributes(secure: boolean): string;
-/** Serialize a full `name=value` cookie string with the state attributes. */
-export declare function serializeStateCookie(name: string, value: string, secure: boolean): string;