@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

package/src/ssr/index.tsx

@@ -1,6 +1,9 @@
 import React from "react";
 import { renderSegments } from "../segment-system.js";
-import { filterSegmentOrder } from "../browser/react/filter-segment-order.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";
@@ -71,7 +74,7 @@ export interface SSRRenderOptions {
  */
 export interface SSRDependencies<TEnv = unknown> {
   /**
-   * createFromReadableStream from @vitejs/plugin-rsc/ssr
+   * createFromReadableStream from @rangojs/router/internal/deps/ssr
    */
   createFromReadableStream: <T>(
     stream: ReadableStream<Uint8Array>,
@@ -86,7 +89,7 @@ export interface SSRDependencies<TEnv = unknown> {
   ) => Promise<ReactDOMReadableStream>;
 
   /**
-   * injectRSCPayload from rsc-html-stream/server
+   * injectRSCPayload from @rangojs/router/internal/deps/html-stream-server
    */
   injectRSCPayload: (
     rscStream: ReadableStream<Uint8Array>,
@@ -129,6 +132,7 @@ interface RscPayload {
     matched?: string[];
     pathname?: string;
     params?: Record<string, string>;
+    basename?: string;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
     version?: string;
@@ -161,9 +165,11 @@ function createSsrEventController(opts: {
 }): EventController {
   const location = new URL(opts.pathname, "http://localhost");
   let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
   const handleState = {
     data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: filterRouteSegmentIds(rawMatched),
   };
   const state: DerivedNavigationState = {
     state: "idle",
@@ -213,10 +219,10 @@ function createSsrEventController(opts: {
  *
  * @example
  * ```tsx
- * import { createSSRHandler } from "rsc-router/ssr";
- * import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+ * import { createSSRHandler } from "@rangojs/router/ssr";
+ * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
- * import { injectRSCPayload } from "rsc-html-stream/server";
+ * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
  * export const renderHTML = createSSRHandler({
  *   createFromReadableStream,
@@ -258,9 +264,11 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       let payload: Promise<RscPayload> | undefined;
       let handlesPromise: Promise<HandleData> | undefined;
       let ssrContextValue: NavigationStoreContextValue | undefined;
+      let rootPromise: Promise<React.ReactNode> | undefined;
       function SsrRoot() {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
+
         const themeConfig = resolved.metadata?.themeConfig ?? null;
         const pathname = resolved.metadata?.pathname ?? "/";
 
@@ -286,20 +294,20 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           navigate: async () => {},
           refresh: async () => {},
           version: resolved.metadata?.version,
+          basename: resolved.metadata?.basename,
         };
 
         // Build content tree from segments.
-        // Order must match NavigationProvider: NavigationStoreContext > ThemeProvider > content
-        const reconstructedRoot = renderSegments(
-          resolved.metadata?.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 =
-          reconstructedRoot instanceof Promise
-            ? React.use(reconstructedRoot)
-            : reconstructedRoot;
+        let content: React.ReactNode = React.use(rootPromise);
 
         // Wrap content with ThemeProvider if theme is enabled
         if (themeConfig) {

package/src/static-handler.ts

@@ -32,10 +32,19 @@
  */
 import type { ReactNode } from "react";
 import type { Handler } from "./types.js";
-import type { PrerenderOptions, StaticBuildContext } from "./prerender.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,
@@ -46,22 +55,24 @@ export interface StaticHandlerDefinition<
   /** 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: StaticBuildContext) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions,
+  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> {
   if (isCachedFunction(handler)) {
@@ -72,22 +83,25 @@ export function Static<TParams extends Record<string, any>>(
     );
   }
 
-  let options: PrerenderOptions | undefined;
+  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) {
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[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,
@@ -97,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 {

package/src/testing/cache-status.ts

@@ -0,0 +1,162 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal). Assert with
+ *    `assertCacheDecision(events, routeKey, expected)` (the one-call counterpart
+ *    of `assertCacheStatus`) or filter raw via `filterCacheDecisions`.
+ *
+ * Both paths report the SAME coarse route-level signal — pick by TRANSPORT, not
+ * by meaning: the header is the only signal a black-box Playwright `Response`
+ * carries (needs the debug gate ON); the sink is the only zero-production-surface
+ * option and the only one exposing per-segment `shouldRevalidate`.
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+
+import type {
+  CacheDecisionEvent,
+  CacheSegmentStatus,
+  TelemetryEvent,
+  TelemetrySink,
+} from "../router/telemetry.js";
+
+const CACHE_HEADER = "X-Rango-Cache";
+
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | { headers: Headers };
+
+export function parseCacheHeader(
+  headerValue: string | null | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!headerValue) return result;
+  for (const rawEntry of headerValue.split(",")) {
+    const entry = rawEntry.trim();
+    if (entry.length === 0) continue;
+    const eq = entry.indexOf("=");
+    if (eq === -1) continue;
+    const id = entry.slice(0, eq).trim();
+    const status = entry.slice(eq + 1).trim();
+    if (id.length === 0 || status.length === 0) continue;
+    result[id] = status;
+  }
+  return result;
+}
+
+function getHeaders(target: CacheStatusTarget): Headers {
+  return target.headers;
+}
+
+export function assertCacheStatus(
+  target: CacheStatusTarget,
+  segment: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const headerValue = getHeaders(target).get(CACHE_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertCacheStatus: response has no ${CACHE_HEADER} header. ` +
+        `Enable the debug cache signal via createRouter({ debugCacheSignal: true }) ` +
+        `or RANGO_TEST_SIGNALS=1.`,
+    );
+  }
+  const map = parseCacheHeader(headerValue);
+  const actual = map[segment];
+  if (actual === undefined) {
+    const known = Object.keys(map);
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" not found in ${CACHE_HEADER} ` +
+        `("${headerValue}"). Known segments: ${
+          known.length > 0 ? known.join(", ") : "(none)"
+        }.`,
+    );
+  }
+  if (actual !== expected) {
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" expected "${expected}" but got "${actual}".`,
+    );
+  }
+}
+
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+  /** Wire into `createRouter({ telemetry: sink })`. */
+  sink: TelemetrySink;
+  /** All telemetry events captured so far, in emit order. */
+  events: TelemetryEvent[];
+}
+
+export function createCacheSink(): CacheSink {
+  const events: TelemetryEvent[] = [];
+  const sink: TelemetrySink = {
+    emit(event: TelemetryEvent): void {
+      events.push(event);
+    },
+  };
+  return { sink, events };
+}
+
+export function filterCacheDecisions(
+  events: readonly TelemetryEvent[],
+): CacheDecisionEvent[] {
+  return events.filter(
+    (e): e is CacheDecisionEvent => e.type === "cache.decision",
+  );
+}
+
+/**
+ * Telemetry-path counterpart of {@link assertCacheStatus}: assert a captured
+ * `cache.decision` event reported `expected` for the segment keyed by `routeKey`
+ * (the route NAME, the same coarse key the header path uses). Throws an
+ * actionable error when no matching segment was captured, or on a mismatch.
+ *
+ * Pairs with {@link createCacheSink}: wire `createRouter({ telemetry: sink })`,
+ * drive an RSC request, then assert against the recorded `events`. This is the
+ * zero-production-surface path (no header to enable). NOTE: `events` accumulates
+ * across requests, so the FIRST matching segment wins — slice or recreate the
+ * sink between requests for the same `routeKey`.
+ */
+export function assertCacheDecision(
+  events: readonly TelemetryEvent[],
+  routeKey: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const segments = filterCacheDecisions(events).flatMap(
+    (d) => d.segments ?? [],
+  );
+  const seg = segments.find((s) => s.id === routeKey);
+  if (seg === undefined) {
+    const known = segments.map((s) => s.id);
+    throw new Error(
+      `assertCacheDecision: no cache.decision segment for routeKey "${routeKey}". ` +
+        `Seen: ${known.length > 0 ? known.join(", ") : "(none)"}. Wire ` +
+        `createRouter({ telemetry: createCacheSink().sink }) and drive an RSC request.`,
+    );
+  }
+  if (seg.cacheStatus !== expected) {
+    throw new Error(
+      `assertCacheDecision: routeKey "${routeKey}" expected "${expected}" but got "${seg.cacheStatus}".`,
+    );
+  }
+}

package/src/testing/collect-handle.ts

@@ -0,0 +1,40 @@
+/**
+ * collectHandle — unit-test a handle's `collect`/accumulator function directly.
+ *
+ * A handle's collect function (the `createHandle(collect)` argument that maps the
+ * per-segment pushed values into the accumulated result) is otherwise not
+ * directly reachable: createHandle keeps it in a private registry keyed by the
+ * handle's `$$id` and returns only `{ __brand, $$id }`. This primitive runs that
+ * REAL registered collect on per-segment values you provide and returns the
+ * accumulated result — so the mapper/accumulator is unit-testable without a full
+ * route match.
+ *
+ * It relies on createHandle registering the collect even in a bare test (it
+ * assigns a runtime fallback id when the Vite plugin did not inject one). If a
+ * handle's module was never imported (so createHandle never ran), the collect is
+ * unregistered and this falls back to a flat array with a warning.
+ */
+
+import { getCollectFn, type Handle } from "../handle.js";
+
+export function collectHandle<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  segments: ReadonlyArray<ReadonlyArray<TData>>,
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id) as
+    | ((segments: TData[][]) => TAccumulated)
+    | undefined;
+
+  if (!collectFn) {
+    console.warn(
+      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect ` +
+        `function. Import the handle's module so createHandle() runs. Falling ` +
+        `back to a flat array.`,
+    );
+    return segments.flat() as unknown as TAccumulated;
+  }
+
+  // Drop empty arrays matching production behavior (segment count/indices).
+  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
+  return collectFn(nonEmpty);
+}