@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.125

package/src/server/request-context.ts

@@ -594,12 +594,9 @@ export function createRequestContext<TEnv>(
     version: stateVersion,
   } = options;
   const cookieHeader = request.headers.get("Cookie");
-  // One Set-Cookie per request no matter how many invalidateClientCache() calls.
   let rangoStateRotated = false;
   let parsedCookies: Record<string, string> | null = null;
 
-  // Create stub response for collecting headers/cookies.
-  // All cookie/header mutations go here; cookie reads derive from it.
   let stubResponse = initialResponse
     ? new Response(null, {
         status: initialResponse.status,
@@ -608,11 +605,9 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
-  // Create handle store and loader memoization for this request
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
 
-  // Lazy parse cookies from the original Cookie header
   const getParsedCookies = (): Record<string, string> => {
     if (!parsedCookies) {
       parsedCookies = parseCookiesFromHeader(cookieHeader);
@@ -620,7 +615,6 @@ export function createRequestContext<TEnv>(
     return parsedCookies;
   };
 
-  // Cached response cookie mutations — invalidated on setCookie/deleteCookie/setTheme
   let responseCookieCache: Map<string, string | null> | null = null;
   const getResponseCookies = (): Map<string, string | null> => {
     if (!responseCookieCache) {
@@ -632,8 +626,6 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
-  // Guard: throw if a response-level side effect is called inside a cache() scope.
-  // Uses ALS to detect the scope (set during segment resolution).
   function assertNotInsideCacheScopeALS(methodName: string): void {
     if (isInsideCacheScope()) {
       throw new Error(
@@ -644,8 +636,7 @@ export function createRequestContext<TEnv>(
     }
   }
 
-  // Effective cookie read: response stub Set-Cookie wins, then original header.
-  // The stub IS the source of truth for same-request mutations.
+  // Response stub Set-Cookie wins, then original header (source of truth for mutations).
   const effectiveCookie = (name: string): string | undefined => {
     const mutations = getResponseCookies();
     if (mutations.has(name)) {
@@ -655,14 +646,11 @@ export function createRequestContext<TEnv>(
     return getParsedCookies()[name];
   };
 
-  // Theme helpers (only used when themeConfig is provided)
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
-    // Use overlay-aware read so setTheme() in the same request is reflected
     const stored = effectiveCookie(themeConfig.storageKey);
     if (stored) {
-      // Validate stored value
       if (stored === "system" && themeConfig.enableSystem) {
         return "system";
       }
@@ -676,7 +664,6 @@ export function createRequestContext<TEnv>(
   const setTheme = (theme: Theme): void => {
     if (!themeConfig) return;
 
-    // Validate theme value
     if (theme !== "system" && !themeConfig.themes.includes(theme)) {
       console.warn(
         `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
@@ -684,7 +671,6 @@ export function createRequestContext<TEnv>(
       return;
     }
 
-    // Write to stub — effectiveCookie() will pick it up on next read
     stubResponse.headers.append(
       "Set-Cookie",
       serializeCookieValue(themeConfig.storageKey, theme, {
@@ -696,10 +682,8 @@ export function createRequestContext<TEnv>(
     invalidateResponseCookieCache();
   };
 
-  // Strip internal _rsc* params so userland sees a clean URL.
   const cleanUrl = stripInternalParams(url);
 
-  // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
@@ -840,7 +824,6 @@ export function createRequestContext<TEnv>(
       });
     },
 
-    // Placeholder - will be replaced below
     use: null as any,
 
     method: request.method,
@@ -869,7 +852,6 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    // Theme properties (only set when themeConfig is provided)
     get theme() {
       return themeConfig ? getTheme() : undefined;
     },
@@ -893,19 +875,17 @@ export function createRequestContext<TEnv>(
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
 
-    // Render barrier: deferred promise resolved after non-loader segments settle.
-    _renderBarrier: null as any, // set below
-    _resolveRenderBarrier: null as any, // set below
+    _renderBarrier: null as any,
+    _resolveRenderBarrier: null as any,
     _renderBarrierSegmentOrder: undefined,
 
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Lazy render barrier: only allocate the Promise when a loader actually
-  // calls rendered(). Requests that don't use rendered() pay zero cost.
+  // Lazy allocation: only create Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._renderBarrier = null as any;
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -916,9 +896,6 @@ export function createRequestContext<TEnv>(
       .map((s) => s.id);
     ctx._renderBarrierSegmentOrder = segOrder;
 
-    // Closing the guard window means no handler can still form a deadlock cycle
-    // with a rendered() loader: drop the dependency-tracking state and mark it
-    // closed. WHEN this runs is the only streaming/non-streaming difference.
     const closeGuard = () => {
       ctx._renderBarrierWaiters = undefined;
       ctx._handlerLoaderDeps = undefined;
@@ -926,20 +903,8 @@ export function createRequestContext<TEnv>(
     };
 
     if (ctx._treeHasStreaming) {
-      // Streaming: rendered() keeps waiting on handleStore.settled past this
-      // point, and loading() handlers are still in flight. The eager snapshot
-      // here would be incomplete, so leave it unset — rendered() builds and
-      // caches the complete one after settled. Keep the guard window OPEN so a
-      // handler that resumes and awaits a still-waiting rendered() loader is
-      // still caught; close it once settled (every tracked handler has finished
-      // then, so none can await a loader anymore). settled resolves after
-      // rendered() seals; if no loader used rendered(), nothing seals and the
-      // (empty) guard state is simply GC'd at request end.
       handleStore.settled.then(closeGuard);
     } else {
-      // Non-streaming: all handlers have settled by now. Build and cache the
-      // snapshot so loader ctx.use(handle) calls don't rebuild it, and close the
-      // guard window immediately.
       ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
         handleStore,
         segOrder,
@@ -950,9 +915,6 @@ export function createRequestContext<TEnv>(
   };
   Object.defineProperty(ctx, "_renderBarrier", {
     get() {
-      // Barrier already resolved (cache/prerender hit) or first lazy access.
-      // Either way, replace the getter with a concrete value to avoid
-      // repeated Promise.resolve() allocations on subsequent reads.
       const p = barrierResolved
         ? Promise.resolve()
         : new Promise<void>((resolve) => {
@@ -968,24 +930,16 @@ export function createRequestContext<TEnv>(
     configurable: true,
   });
 
-  // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
     loaderPromises,
     getContext: () => ctx,
   });
 
-  // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }
 
-/**
- * Parse Set-Cookie headers from a response into effective cookie state.
- * Returns a map of cookie name -> value (string) or name -> null (deleted).
- * Last-write-wins: later Set-Cookie entries for the same name overwrite earlier ones.
- * Max-Age=0 is treated as a delete.
- */
 const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
 
 function parseResponseCookies(response: Response): Map<string, string | null> {
@@ -993,7 +947,6 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   const setCookies = response.headers.getSetCookie();
 
   for (const header of setCookies) {
-    // First segment before ';' is the name=value pair
     const semiIdx = header.indexOf(";");
     const pair = semiIdx === -1 ? header : header.substring(0, semiIdx);
     const eqIdx = pair.indexOf("=");
@@ -1005,11 +958,9 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
       name = decodeURIComponent(pair.substring(0, eqIdx).trim());
       value = decodeURIComponent(pair.substring(eqIdx + 1).trim());
     } catch {
-      // Malformed encoding — skip this entry
       continue;
     }
 
-    // Max-Age=0 means the cookie is being deleted
     const isDeleted = MAX_AGE_ZERO_RE.test(header);
     result.set(name, isDeleted ? null : value);
   }
@@ -1017,9 +968,6 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   return result;
 }
 
-/**
- * Parse cookies from Cookie header
- */
 function parseCookiesFromHeader(
   cookieHeader: string | null,
 ): Record<string, string> {
@@ -1035,7 +983,7 @@ function parseCookiesFromHeader(
       try {
         cookies[name] = decodeURIComponent(raw);
       } catch {
-        // Malformed percent-encoded value (e.g. %zz, %2) - fall back to raw value
+        // Malformed percent-encoding: fall back to raw value
         cookies[name] = raw;
       }
     }
@@ -1044,9 +992,6 @@ function parseCookiesFromHeader(
   return cookies;
 }
 
-/**
- * Serialize a cookie for Set-Cookie header
- */
 function serializeCookieValue(
   name: string,
   value: string,
@@ -1074,20 +1019,12 @@ export interface CreateUseFunctionOptions<TEnv> {
   getContext: () => RequestContext<TEnv>;
 }
 
-/**
- * Create the use() function for loader and handle composition.
- *
- * This is the unified implementation used by both RequestContext and HandlerContext.
- * - For loaders: executes and memoizes loader functions
- * - For handles: returns a push function to add handle data
- */
 export function createUseFunction<TEnv>(
   options: CreateUseFunctionOptions<TEnv>,
 ): RequestContext["use"] {
   const { handleStore, loaderPromises, getContext } = options;
 
   return ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
-    // Handle case: return a push function
     if (isHandle(item)) {
       const handle = item;
       const ctx = getContext();
@@ -1100,30 +1037,24 @@ export function createUseFunction<TEnv>(
         );
       }
 
-      // Return a push function bound to this handle and segment
       return (
         dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
       ) => {
-        // If it's a function, call it immediately to get the promise
         const valueOrPromise =
           typeof dataOrFn === "function"
             ? (dataOrFn as () => Promise<unknown>)()
             : dataOrFn;
 
-        // Push directly - promises will be serialized by RSC and streamed
         handleStore.push(handle.$$id, segmentId, valueOrPromise);
       };
     }
 
-    // Loader case
     const loader = item as LoaderDefinition<any, any>;
 
-    // Return cached promise if already started
     if (loaderPromises.has(loader.$$id)) {
       return loaderPromises.get(loader.$$id);
     }
 
-    // Get loader function - either from loader object or fetchable registry
     let loaderFn = loader.fn;
     if (!loaderFn) {
       const fetchable = getFetchableLoader(loader.$$id);
@@ -1140,7 +1071,6 @@ export function createUseFunction<TEnv>(
 
     const ctx = getContext();
 
-    // Create loader context with recursive use() support
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
@@ -1157,7 +1087,6 @@ export function createUseFunction<TEnv>(
       use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
-        // Recursive call - will start dep loader if not already started
         return ctx.use(dep);
       }) as LoaderContext["use"],
       method: "GET",
@@ -1181,7 +1110,6 @@ export function createUseFunction<TEnv>(
       doneLoader();
     });
 
-    // Memoize for subsequent calls
     loaderPromises.set(loader.$$id, promise);
 
     return promise;

package/src/ssr/index.tsx

@@ -71,7 +71,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 +86,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>,
@@ -218,10 +218,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,
@@ -263,6 +263,7 @@ 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);
@@ -296,17 +297,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         };
 
         // 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

@@ -37,8 +37,6 @@ 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).
@@ -62,11 +60,8 @@ export interface StaticHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
-// -- Function ---------------------------------------------------------------
-
-// Process-stable fallback id counter (mirrors createHandle / createLoader /
-// Prerender). Only assigned in a bare unit test where the Vite plugin did not
-// inject an id; never fires in a real build (the plugin always injects).
+// 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> = {}>(
@@ -75,8 +70,6 @@ export function Static<TParams extends Record<string, any> = {}>(
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
-// -- Implementation ---------------------------------------------------------
-
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
   optionsOrId?: StaticHandlerOptions | string,
@@ -100,25 +93,12 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
-  // Throw unless under a test runner. The plugin always injects $$id for a
-  // supported `export const` Static on every build, so a missing id means either
-  // no plugin (a bare test — fall back below) or an UNSUPPORTED shape the plugin
-  // silently skipped (dev OR a real build — fail loud; a synthetic id would
-  // degrade to a silent static/prerender miss). The message is already small (no
-  // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
-  // runtime-safe — never a bare `process.env` access.
   if (!id && !isUnderTestRunner()) {
     throw new Error(
       "[rango] Static: missing $$id. Use `export const X = Static(...)` and " +
         "ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
-  // Under vitest with no plugin id: assign a process-stable runtime id so a
-  // whole-app router with Static() routes constructs in a bare test. Never
-  // reached in a real build (the throw above fires there); staticHandlerId is
-  // read only during RSC serving (never in dispatch / assertGeneratedRoutesMatch),
-  // and the build static manifest keys on the plugin id. Mirrors createHandle /
-  // createLoader / Prerender.
   if (!id) {
     id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
   }
@@ -131,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

@@ -37,18 +37,6 @@ export type ExpectedCacheStatus = CacheSegmentStatus;
 /** A target carrying response headers (a Response or a `{ headers }` object). */
 export type CacheStatusTarget = Response | { headers: Headers };
 
-/**
- * Parse an `X-Rango-Cache` header value into a `{ routeKey: status }` map.
- *
- * Header format: `<routeKey>=<status>, <routeKey2>=<status2>`. The key is the
- * route NAME (ctx.routeKey, e.g. `product.detail`), NOT the URL pattern —
- * see assertCacheStatus. Whitespace around entries and the `=` is tolerated.
- * Entries without a status are ignored.
- *
- * @example
- * parseCacheHeader("product.detail=hit, shop.layout=stale")
- * // => { "product.detail": "hit", "shop.layout": "stale" }
- */
 export function parseCacheHeader(
   headerValue: string | null | undefined,
 ): Record<string, string> {
@@ -71,25 +59,6 @@ function getHeaders(target: CacheStatusTarget): Headers {
   return target.headers;
 }
 
-/**
- * Assert that the `X-Rango-Cache` header reports `expected` status for the
- * given route. Throws a descriptive error when the header is missing (gate
- * off), the route is absent, or the status differs.
- *
- * `routeKey` is the route NAME (e.g. `product.detail`), the same id the header
- * carries — NOT the URL pattern (`/products/:id`). The signal is built from
- * ctx.routeKey (telemetry.ts), so a pattern-shaped key never matches.
- *
- * The header is produced by the RSC render pipeline, so get the Response from
- * the router's real fetch path (`router.fetch(...)`), with the debug cache
- * signal gate enabled (`debugCacheSignal: true` or `RANGO_TEST_SIGNALS=1`).
- * NOTE: `dispatch()` is the non-RSC primitive and never emits this header.
- *
- * @example
- * // debugCacheSignal must be enabled on the router under test.
- * const res = await router.fetch(new Request("https://app/products/42"));
- * assertCacheStatus(res, "product.detail", "hit");
- */
 export function assertCacheStatus(
   target: CacheStatusTarget,
   segment: string,
@@ -131,19 +100,6 @@ export interface CacheSink {
   events: TelemetryEvent[];
 }
 
-/**
- * Create a capturing telemetry sink for asserting on `cache.decision` events.
- *
- * This is the ZERO-production-surface path: no response header is emitted, the
- * consumer just inspects the captured events.
- *
- * @example
- * const { sink, events } = createCacheSink();
- * const router = createRouter({ telemetry: sink, ... });
- * // ...send a request through the router's RSC fetch path...
- * const decisions = filterCacheDecisions(events);
- * expect(decisions[0].segments?.[0].cacheStatus).toBe("hit");
- */
 export function createCacheSink(): CacheSink {
   const events: TelemetryEvent[] = [];
   const sink: TelemetrySink = {
@@ -154,9 +110,6 @@ export function createCacheSink(): CacheSink {
   return { sink, events };
 }
 
-/**
- * Filter captured telemetry events down to `cache.decision` events.
- */
 export function filterCacheDecisions(
   events: readonly TelemetryEvent[],
 ): CacheDecisionEvent[] {

package/src/testing/collect-handle.ts

@@ -17,27 +17,6 @@
 
 import { getCollectFn, type Handle } from "../handle.js";
 
-/**
- * Run a handle's collect function on per-segment pushed values.
- *
- * @param handle - The handle whose collect to run.
- * @param segments - Per-segment pushed values: each entry is the array of values
- *   one route segment pushed for this handle, in parent -> child order. Empty
- *   per-segment arrays are dropped before the collect runs, matching production
- *   collectHandleData (a segment that pushed nothing is not passed through).
- * @returns The accumulated value the handle's collect produces.
- *
- * @example
- * ```ts
- * // Default flatten
- * collectHandle(Breadcrumbs, [[{ label: "Home", href: "/" }], [{ label: "P", href: "/p" }]]);
- * // -> [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]
- *
- * // Custom "last wins"
- * const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
- * collectHandle(PageTitle, [["Home"], ["Product"]]); // -> "Product"
- * ```
- */
 export function collectHandle<TData, TAccumulated>(
   handle: Handle<TData, TAccumulated>,
   segments: ReadonlyArray<ReadonlyArray<TData>>,
@@ -55,9 +34,7 @@ export function collectHandle<TData, TAccumulated>(
     return segments.flat() as unknown as TAccumulated;
   }
 
-  // Match production collectHandleData (handle.ts): segments that pushed
-  // nothing (empty arrays) are dropped before the collect runs, so a collect
-  // that inspects segment count or indices sees the same input as at runtime.
+  // Drop empty arrays matching production behavior (segment count/indices).
   const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
   return collectFn(nonEmpty);
 }

package/src/testing/e2e/index.ts

@@ -1,8 +1,3 @@
-// Public entry for the consumer e2e harness. `createRangoE2E({ test, expect })`
-// wires the server fixture, page helpers, parity helpers, and matchers around
-// the consumer's Playwright `test`/`expect` objects so this module never
-// imports `@playwright/test` at runtime (type-only imports are erased).
-
 import type { Expect, TestType } from "@playwright/test";
 import {
   createUseFixture,
@@ -35,12 +30,6 @@ import {
 } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 
-// Cache-status helpers are pure (cache-status.ts imports only TYPES), so they
-// are safe to surface from this Playwright-runnable entry. Importing them from
-// the `@rangojs/router/testing` barrel does NOT work in a plain Playwright
-// runner — the barrel transitively pulls the build-only `@rangojs/router:version`
-// virtual via the route-manifest path. Asserting cache status on a real
-// response is an e2e activity, so this is their Playwright-safe home.
 export {
   assertCacheStatus,
   parseCacheHeader,
@@ -50,9 +39,6 @@ export {
   type ExpectedCacheStatus,
   type CacheStatusTarget,
 } from "../cache-status.js";
-
-// Re-export standalone helpers and all public types so the barrel can re-export
-// them from a single module.
 export {
   testId,
   waitForHydration,
@@ -87,7 +73,6 @@ export interface RangoE2E extends PageHelpers, Parity {
   useFixture: (options: FixtureOptions) => Fixture;
   testNoJs: TestType<any, any>;
   rangoMatchers: RangoMatchers;
-  // Standalone helpers, re-surfaced for convenience.
   testId: typeof testId;
   waitForHydration: typeof waitForHydration;
   waitForNavigation: typeof waitForNavigation;
@@ -102,12 +87,6 @@ export interface RangoE2E extends PageHelpers, Parity {
   measureTime: typeof measureTime;
 }
 
-/**
- * Wire the full e2e harness around a consumer's Playwright `test`/`expect`.
- *
- * @param defaultRoot - fallback app root for `parityDescribe` when a call omits
- *   `options.root`.
- */
 export function createRangoE2E({
   test,
   expect,
@@ -132,7 +111,6 @@ export function createRangoE2E({
     rangoMatchers,
     ...parity,
     ...pageHelpers,
-    // Standalone helpers.
     testId,
     waitForHydration,
     waitForNavigation,

package/src/testing/e2e/matchers.ts

@@ -1,6 +1,3 @@
-// Custom Playwright matchers for Rango assertions. Returned as an object
-// suitable for `expect.extend(...)`. v1 ships only `toHaveRangoPathname`.
-
 import type { Expect, Page } from "@playwright/test";
 
 interface MatcherResult {
@@ -12,17 +9,6 @@ export interface RangoMatchers {
   toHaveRangoPathname: (page: Page, expected: string) => MatcherResult;
 }
 
-/**
- * Build the matcher object for `expect.extend(createRangoMatchers(expect))`.
- *
- * `toHaveRangoPathname(page, expected)` asserts that the pathname of the page's
- * current URL equals `expected`.
- *
- * TODO: `toHaveSegments` / `toHaveParams` are intentionally not implemented.
- * They require a client-emitted signal (the active segment chain / resolved
- * params exposed on the page) that does not exist yet; implementing them by
- * scraping the DOM would be a guess. Add them once the router emits that signal.
- */
 export function createRangoMatchers(_expect: Expect): RangoMatchers {
   return {
     toHaveRangoPathname(page: Page, expected: string): MatcherResult {
@@ -39,8 +25,6 @@ export function createRangoMatchers(_expect: Expect): RangoMatchers {
   };
 }
 
-// Type augmentation so consumers can call `await expect(page).toHaveRangoPathname("/x")`
-// after `expect.extend(rangoMatchers)`, without re-declaring the matcher.
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace PlaywrightTest {