@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -0,0 +1,197 @@
+/**
+ * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ *
+ * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
+ * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
+ * function), and gateTransitions. So the
+ * predicate sees exactly the navigation/action metadata it would at runtime
+ * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
+ * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
+ * whether the transition would apply this request. The result also exposes the
+ * assembled `whenContext` so tests can assert the exact fields without reaching
+ * into private request-context state.
+ *
+ * This is the public way to exercise a transition gate: the full
+ * match -> render pipeline that wires these together only runs under real RSC
+ * rendering (which the Flight primitives do not drive), so without this primitive
+ * a consumer could not test their predicate through @rangojs/router/testing.
+ *
+ * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
+ */
+
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { applyViewTransitionDefault } from "../router/segment-resolution/view-transition-default.js";
+import { gateTransitions } from "../rsc/transition-gate.js";
+import { createTestRequestContext, type VarsInit } from "./internal/context.js";
+import type {
+  ResolvedSegment,
+  TransitionConfig,
+  TransitionWhenContext,
+} from "../types/segments.js";
+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;
+
+/**
+ * Options for runTransitionWhen. All navigation/action fields are optional and
+ * default to "absent", matching what the gate sees for an initial full load with
+ * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
+ * navigation source being unavailable, and omit the `action*` fields to model a
+ * plain (non-action) navigation.
+ */
+export interface RunTransitionWhenOptions<TEnv = any> {
+  /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
+  request?: Request | string;
+  /** Route params for the target (`nextParams`). */
+  params?: Record<string, string>;
+  /** Target route name (`toRouteName`). */
+  toRouteName?: string;
+  /** Environment bindings surfaced as `env` (and `ctx.env`). */
+  env?: TEnv;
+  /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
+  vars?: VarsInit;
+  /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
+  currentUrl?: string | URL;
+  /** Source route params (`currentParams`). */
+  currentParams?: Record<string, string>;
+  /** Source route name (`fromRouteName`). */
+  fromRouteName?: string;
+  /** Id of the action that triggered a revalidation (`actionId`). */
+  actionId?: string;
+  /** Url the action was submitted from (`actionUrl`). */
+  actionUrl?: string | URL;
+  /** The action's return value (`actionResult`). */
+  actionResult?: unknown;
+  /** FormData from a form action (`formData`). */
+  formData?: FormData;
+  /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
+  onError?: OnErrorCallback;
+  /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
+  ppr?: boolean;
+}
+
+/**
+ * Result of runTransitionWhen.
+ */
+export interface RunTransitionWhenResult<TEnv = any> {
+  /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
+  kept: boolean;
+  /** Convenience inverse of `kept`. */
+  dropped: boolean;
+  /**
+   * The production-assembled predicate context. Undefined when the config has
+   * no `when` predicate.
+   */
+  whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
+  /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
+  ctx: RequestContext<TEnv>;
+}
+
+export function runTransitionWhen<TEnv = any>(
+  config: TransitionConfig,
+  opts: RunTransitionWhenOptions<TEnv> = {},
+): RunTransitionWhenResult<TEnv> {
+  const { ctx } = createTestRequestContext<TEnv>({
+    env: opts.env,
+    request: opts.request,
+    vars: opts.vars,
+    params: opts.params,
+  });
+  const reqCtx = ctx as unknown as RequestContext<TEnv>;
+
+  // Target route name (the public field the gate reads for `toRouteName`).
+  if (opts.toRouteName !== undefined)
+    reqCtx.routeName = opts.toRouteName as RequestContext<TEnv>["routeName"];
+  // Source (match-time) data the gate reads for currentUrl/currentParams/fromRouteName.
+  if (opts.currentUrl !== undefined)
+    reqCtx._gateCurrentUrl = toURL(opts.currentUrl, reqCtx.url);
+  if (opts.currentParams !== undefined)
+    reqCtx._gateCurrentParams = opts.currentParams;
+  if (opts.fromRouteName !== undefined)
+    reqCtx._prevRouteKey = opts.fromRouteName;
+  // Action data the gate reads at the action-bearing call sites.
+  if (opts.actionId !== undefined) reqCtx._gateActionId = opts.actionId;
+  if (opts.actionUrl !== undefined)
+    reqCtx._gateActionUrl = toURL(opts.actionUrl, reqCtx.url);
+  if (opts.actionResult !== undefined)
+    reqCtx._gateActionResult = opts.actionResult;
+  if (opts.formData !== undefined) reqCtx._gateFormData = opts.formData;
+
+  let whenContext:
+    | TransitionWhenContext<Record<string, string>, TEnv>
+    | undefined;
+  const when = config.when;
+  const configForGate: TransitionConfig = when
+    ? {
+        ...config,
+        when: (c) => {
+          whenContext = c as TransitionWhenContext<
+            Record<string, string>,
+            TEnv
+          >;
+          return when(c);
+        },
+      }
+    : config;
+
+  return runWithRequestContext(reqCtx, () => {
+    if (opts.ppr) {
+      const entry = {
+        type: "route",
+        id: "tx-when-entry",
+        shortCode: "tx-when-seg",
+        parent: null,
+        transition: configForGate,
+        layout: [],
+        parallel: {},
+      } as unknown as EntryData;
+      evaluatePprTransitionWhen(
+        [entry],
+        reqCtx,
+        { params: reqCtx.params, routeName: opts.toRouteName },
+        (error, segmentId) =>
+          invokeOnError(
+            opts.onError,
+            error,
+            "rendering",
+            {
+              request: reqCtx.request,
+              url: reqCtx.url,
+              params: reqCtx.params,
+              segmentId,
+            },
+            "RSC",
+          ),
+      );
+    }
+    // Ordinary predicates are collected here and evaluated by the gate. PPR
+    // predicates keep the decision already evaluated before this step.
+    const serialized = applyViewTransitionDefault(
+      configForGate,
+      undefined,
+      "tx-when-seg",
+    );
+    const segment = {
+      id: "tx-when-seg",
+      namespace: "r",
+      type: "route",
+      index: 0,
+      component: null,
+      transition: serialized,
+    } as ResolvedSegment;
+    const [gatedSegment] = gateTransitions(
+      [segment],
+      reqCtx as Parameters<typeof gateTransitions>[1],
+      opts.onError,
+    );
+    const kept = gatedSegment.transition !== undefined;
+    return { kept, dropped: !kept, whenContext, ctx: reqCtx };
+  });
+}

package/src/testing/shell-status.ts

@@ -0,0 +1,206 @@
+/**
+ * PPR shell-status testing primitives for @rangojs/router consumers.
+ *
+ * Companion to `cache-status.ts` (segment/document cache): this module covers
+ * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`) and
+ * partial-navigation segment replay (`x-rango-ppr-replay: HIT`).
+ *
+ * ## Spike conclusions (plan 009)
+ *
+ * 1. **`dispatch` cannot exercise PPR.** It is deliberately RSC-free: no Flight,
+ *    no SSR, no `handleRscRendering` commit point. Seeding `MemorySegmentCacheStore`
+ *    + `ppr: true` on a response route is a no-op for shell serve/capture. The
+ *    production path lives in `rsc/rsc-rendering.ts` + `rsc/shell-capture.ts`.
+ *
+ * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
+ *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
+ *    HIT is reported only when matching consumes the captured segment record.
+ *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
+ *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
+ *
+ * 3. **Stays e2e-only:** live MISS → background capture → HIT (needs real
+ *    `captureShellHTML` / React `prerender` + resume fizz), browser resume of
+ *    holes, Cloudflare/Vercel live stores, nonce/eligibility fall-open, and
+ *    build-time producer B bake. Unit layer dogfoods the **store family + key
+ *    identity + header assert**; it must never stub a shell HIT response.
+ *
+ * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
+ * (Playwright — same pure helpers, no Vite virtuals).
+ */
+
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+import {
+  compileSearchParamsFilter,
+  type CacheSearchParams,
+} from "../cache/search-params-filter.js";
+
+/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
+export const SHELL_STATUS_HEADER: string = "x-rango-shell";
+
+/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
+export const PPR_REPLAY_STATUS_HEADER: string = "x-rango-ppr-replay";
+
+/** Values the serve path writes on `x-rango-shell`. */
+export type ShellStatus = "HIT" | "MISS";
+
+const PPR_REPLAY_BYPASS_REASONS = [
+  "method",
+  "dynamic",
+  "nonce",
+  "store-unavailable",
+  "passive-read-unsupported",
+  "no-navigation-context",
+  "prerender-store",
+  "intercept",
+  "cache-disabled",
+  "read-error",
+  "no-entry",
+  "invalid-version",
+  "corrupt-entry",
+  "handler-live-holes",
+  "transition-when",
+  "no-segment-snapshot",
+  "snapshot-miss",
+  "explicit-cache-hit",
+  "stale-build-entry",
+] as const;
+
+/** Bounded reasons a PPR partial request can fall open to ordinary matching. */
+export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
+
+/** Parsed `x-rango-ppr-replay` value. */
+export type PprReplayStatus =
+  | { outcome: "HIT"; freshness: "fresh" | "stale" }
+  | { outcome: "BYPASS"; reason: PprReplayBypassReason };
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type ShellStatusTarget = Response | { headers: Headers };
+
+/**
+ * Shell store key for a document URL — same formula as production
+ * `buildShellKey` in `rsc/shell-serve.ts` (host + pathname + sorted search +
+ * `:shell`). Kept here so the testing barrel never imports the shell-serve
+ * module (it pulls React). A parity test pins the two implementations.
+ *
+ * Accepts a `URL` or an absolute/relative request URL string (relative strings
+ * resolve against `http://localhost`). Pass the router's `cache.searchParams`
+ * config as `searchParams` when the app under test sets one — the production
+ * key applies it, so the expected key must too.
+ */
+export function shellCacheKey(
+  url: URL | string,
+  searchParams?: CacheSearchParams,
+): string {
+  const resolved =
+    typeof url === "string" ? new URL(url, "http://localhost") : url;
+  const sorted = sortedSearchString(
+    resolved.searchParams,
+    compileSearchParamsFilter(searchParams),
+  );
+  const searchSuffix = sorted ? `?${sorted}` : "";
+  return `${resolved.host}${resolved.pathname}${searchSuffix}:shell`;
+}
+
+function getHeaders(target: ShellStatusTarget): Headers {
+  return target.headers;
+}
+
+const PPR_REPLAY_BYPASS_REASON_SET = new Set<string>(PPR_REPLAY_BYPASS_REASONS);
+
+/**
+ * Read `x-rango-shell` from a response. Returns `null` when the header is
+ * absent (axis-1 / non-ppr / ineligible request).
+ */
+export function parseShellStatus(
+  target: ShellStatusTarget,
+): ShellStatus | null {
+  const raw = getHeaders(target).get(SHELL_STATUS_HEADER);
+  if (raw === null) return null;
+  const value = raw.trim();
+  if (value === "HIT" || value === "MISS") return value;
+  return null;
+}
+
+/**
+ * Assert a document response's `x-rango-shell` header equals `expected`.
+ * Throws when the header is missing, unrecognized, or mismatched.
+ *
+ * Use on real document GETs (e2e `page.request.get` / `router.fetch`). Do not
+ * invent a HIT Response in unit tests — that fakes the serve path.
+ */
+export function assertShellStatus(
+  target: ShellStatusTarget,
+  expected: ShellStatus,
+): void {
+  const headerValue = getHeaders(target).get(SHELL_STATUS_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertShellStatus: response has no ${SHELL_STATUS_HEADER} header. ` +
+        `The header is only set on document GETs to a ppr-declared route that ` +
+        `the serve path considered (axis-1 fall-open and non-ppr routes omit it).`,
+    );
+  }
+  const actual = headerValue.trim();
+  if (actual !== expected) {
+    throw new Error(
+      `assertShellStatus: expected "${expected}" but got "${actual}".`,
+    );
+  }
+}
+
+/** Parse the dedicated PPR partial-navigation replay decision header. */
+export function parsePprReplayStatus(
+  target: ShellStatusTarget,
+): PprReplayStatus | null {
+  const raw = getHeaders(target).get(PPR_REPLAY_STATUS_HEADER)?.trim();
+  if (!raw) return null;
+
+  const [outcome, detail, ...extra] = raw.split(";").map((part) => part.trim());
+  if (extra.length > 0 || !detail) return null;
+
+  if (outcome === "HIT") {
+    const freshness = detail.match(/^freshness=(fresh|stale)$/)?.[1];
+    if (freshness === "fresh" || freshness === "stale") {
+      return { outcome, freshness };
+    }
+    return null;
+  }
+
+  if (outcome === "BYPASS") {
+    const reason = detail.match(/^reason=(.+)$/)?.[1] as
+      | PprReplayBypassReason
+      | undefined;
+    if (reason && PPR_REPLAY_BYPASS_REASON_SET.has(reason)) {
+      return { outcome, reason };
+    }
+  }
+
+  return null;
+}
+
+/** Assert a partial response's PPR replay outcome and freshness/reason. */
+export function assertPprReplayStatus(
+  target: ShellStatusTarget,
+  expected: PprReplayStatus,
+): void {
+  const raw = getHeaders(target).get(PPR_REPLAY_STATUS_HEADER);
+  if (raw === null) {
+    throw new Error(
+      `assertPprReplayStatus: response has no ${PPR_REPLAY_STATUS_HEADER} header. ` +
+        "The header is set on partial requests to ppr-declared routes.",
+    );
+  }
+
+  const actual = parsePprReplayStatus(target);
+  if (!actual) {
+    throw new Error(
+      `assertPprReplayStatus: unrecognized ${PPR_REPLAY_STATUS_HEADER} value "${raw}".`,
+    );
+  }
+
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(
+      `assertPprReplayStatus: expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}.`,
+    );
+  }
+}

package/src/testing/vitest-stubs/cloudflare-email.ts

@@ -0,0 +1,9 @@
+// Stub for the `cloudflare:email` runtime virtual, shipped for Cloudflare
+// consumers (enable via `rangoTestAliases({ preset: "cloudflare" })`).
+export class EmailMessage {
+  constructor(
+    public from: string,
+    public to: string,
+    public raw: unknown,
+  ) {}
+}

package/src/testing/vitest-stubs/cloudflare-workers.ts

@@ -0,0 +1,21 @@
+// Stub for the `cloudflare:workers` runtime virtual, shipped for Cloudflare
+// consumers (enable via `rangoTestAliases({ preset: "cloudflare" })`). A CF app's
+// route tree commonly imports `cloudflare:workers` (e.g. `import { env } from
+// "cloudflare:workers"`), which does not resolve in a bare Vitest process.
+export const env: Record<string, unknown> = {};
+
+export class DurableObject<Env = unknown> {
+  constructor(
+    public ctx: unknown,
+    public env: Env,
+  ) {}
+}
+
+export class WorkerEntrypoint<Env = unknown> {
+  constructor(
+    public ctx: unknown,
+    public env: Env,
+  ) {}
+}
+
+export class RpcTarget {}

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

@@ -0,0 +1,16 @@
+// 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.
+export const createFromReadableStream = (): never => {
+  throw new Error("plugin-rsc stub: createFromReadableStream not available");
+};
+export const renderToReadableStream = (): never => {
+  throw new Error("plugin-rsc stub: renderToReadableStream not available");
+};
+export const loadServerAction = (): undefined => undefined;
+export const decodeReply = (): undefined => undefined;
+export const decodeAction = (): undefined => undefined;
+export const decodeFormState = (): undefined => undefined;
+export const createTemporaryReferenceSet = (): Record<string, never> => ({});

package/src/testing/vitest-stubs/version.ts

@@ -0,0 +1,5 @@
+// Stub for the build-only `@rangojs/router:version` virtual module, shipped so
+// consumers do not have to author it. The rango Vite plugin injects this at
+// build time; in a bare Vitest process it must be aliased to a stub. Empty
+// string keeps generated URLs free of a version path segment.
+export const VERSION = "";