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

package/src/browser/react/index.ts

@@ -1,49 +1,4 @@
-// React exports for browser navigation
-
-// Hook with Zustand-style selectors
-export { useNavigation } from "./use-navigation.js";
-
-// Router actions hook (stable reference, no re-renders)
-export { useRouter } from "./use-router.js";
-
-// URL hooks
-export { usePathname } from "./use-pathname.js";
-export { useSearchParams } from "./use-search-params.js";
-export { useParams } from "./use-params.js";
-
-// Action state tracking hook
-export { useAction, type TrackedActionState } from "./use-action.js";
-
-// Segments state hook
-export { useSegments, type SegmentsState } from "./use-segments.js";
-
-// Handle data hook
-export { useHandle } from "./use-handle.js";
-
-// Mount-aware reverse hook
-export { useReverse } from "./use-reverse.js";
-
-// Provider
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./NavigationProvider.js";
-
-// Context (for advanced usage)
-export {
-  NavigationStoreContext,
-  type NavigationStoreContextValue,
-} from "./context.js";
-
-// Link component
-export { Link, type LinkProps, type PrefetchStrategy } from "./Link.js";
-
-// Link status hook
-export { useLinkStatus, type LinkStatus } from "./use-link-status.js";
-
-// Scroll restoration
-export {
-  ScrollRestoration,
-  useScrollRestoration,
-  type ScrollRestorationProps,
-} from "./ScrollRestoration.js";

package/src/browser/react/location-state-shared.ts

@@ -1,8 +1,3 @@
-/**
- * Shared location state utilities - works in both RSC and client contexts
- * No "use client" directive so it can be imported from RSC
- */
-
 import type { ReactElement } from "react";
 
 /**
@@ -26,16 +21,8 @@ export interface LocationStateOptions {
 
 type LocationStateUnsafeFn = (...args: never[]) => unknown;
 
-// Broadest constructor signature (`abstract` covers both abstract and concrete
-// classes). A class passed as state has a `new` signature, not a call signature,
-// so it slips past LocationStateUnsafeFn; at runtime the lazy-getter path
-// (`typeof value === "function"`) then mistakes it for a getter and throws.
 type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
 
-// `unknown` cannot be verified serializable, so it is rejected (callers must
-// supply a concrete type). `any` deliberately defeats type checking and is NOT
-// guardable — it is assignable to the branded error too, so the check always
-// passes; it remains an explicit escape hatch.
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> =
   IsAny<T> extends true ? false : unknown extends T ? true : false;

package/src/browser/react/location-state.ts

@@ -3,7 +3,6 @@
 import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
-// Re-export shared utilities and types
 export {
   createLocationState,
   isLocationStateEntry,

package/src/browser/react/use-action.ts

@@ -24,32 +24,24 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
   result: null,
 };
 
-/**
- * Normalize action ID - returns the ID as-is
- *
- * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
- * When using function references, we use the full ID for exact matching.
- * When using strings, the event controller supports suffix matching
- * (e.g., "addToCart" matches "hash#addToCart").
- */
-function normalizeActionId(actionId: string): string {
-  return actionId;
-}
-
 /**
  * Extract action ID from a server action function or string.
  *
  * Actions passed as props from server components lose their metadata
  * during RSC serialization - use a string action name instead.
+ *
+ * The extracted $$id (e.g. "hash#actionName" or "src/actions.ts#actionName")
+ * is returned as-is. Suffix-vs-exact matching against this ID happens
+ * downstream in the event controller, not here.
  */
-export function getActionId(action: ServerActionFunction | string): string {
+function getActionId(action: ServerActionFunction | string): string {
   invariant(
     typeof action === "function" || typeof action === "string",
     `useAction: action must be a function or string, got ${typeof action}`,
   );
   const actionId = (action as any)?.$$id;
   if (actionId) {
-    return normalizeActionId(actionId);
+    return actionId;
   }
 
   // If action is a string, use it directly
@@ -162,7 +154,6 @@ export function useAction<T>(
   });
   const prevSelected = useRef(baseState);
   prevSelected.current = baseState;
-  // useOptimistic allows immediate updates during transitions/actions
   const [optimisticState, setOptimisticState] = useOptimistic<
     T | TrackedActionState
   >(null!);

package/src/browser/react/use-handle.ts

@@ -43,7 +43,6 @@ export function useHandle<T, A, S>(
 ): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
       const collected = collectHandleData(
@@ -54,7 +53,6 @@ export function useHandle<T, A, S>(
       return selector ? selector(collected) : collected;
     }
 
-    // On client, use event controller state
     const state = ctx.eventController.getHandleState();
     const collected = collectHandleData(
       handle,
@@ -65,15 +63,12 @@ export function useHandle<T, A, S>(
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
 
-  // Track previous value for shallow comparison
   const prevValueRef = useRef(value);
   prevValueRef.current = value;
 
-  // Ref keeps the latest selector without re-subscribing on every render.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Subscribe to handle data changes (client only)
   useEffect(() => {
     if (!ctx) return;
 

package/src/browser/react/use-link-status.ts

@@ -82,11 +82,9 @@ export function useLinkStatus(): LinkStatus {
   const linkTo = useContext(LinkContext);
   const ctx = useContext(NavigationStoreContext);
 
-  // Get origin for URL normalization (stable across renders)
   const origin =
     typeof window !== "undefined" ? window.location.origin : "http://localhost";
 
-  // Base state for useOptimistic
   const [basePending, setBasePending] = useState<boolean>(() => {
     if (!ctx || linkTo === null) {
       return false;
@@ -97,7 +95,6 @@ export function useLinkStatus(): LinkStatus {
 
   const prevPending = useRef(basePending);
 
-  // useOptimistic allows immediate updates during transitions
   const [pending, setOptimisticPending] = useOptimistic(basePending);
 
   useEffect(() => {
@@ -105,7 +102,6 @@ export function useLinkStatus(): LinkStatus {
       return;
     }
 
-    // Subscribe to navigation state changes
     return ctx.eventController.subscribe(() => {
       const state = ctx.eventController.getState();
       const isPending = isPendingFor(linkTo, state.pendingUrl, origin);

package/src/browser/react/use-navigation.ts

@@ -46,7 +46,6 @@ export function useNavigation<T>(
     throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  // Base state for useOptimistic
   const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
     const publicState = toPublicState(ctx.eventController.getState());
     return selector ? selector(publicState) : publicState;
@@ -59,7 +58,6 @@ export function useNavigation<T>(
   // parent transition (e.g. <Link> click) is still pending.
   const optimisticPinnedRef = useRef(false);
 
-  // useOptimistic allows immediate updates during transitions/actions
   const [value, setOptimisticValue] = useOptimistic(baseValue);
 
   // Store selector in a ref so the subscription callback always uses the
@@ -72,7 +70,6 @@ export function useNavigation<T>(
 
   // Subscribe to event controller state changes (only runs on client)
   useEffect(() => {
-    // Subscribe to updates from event controller
     return ctx.eventController.subscribe(() => {
       const currentState = ctx.eventController.getState();
       const publicState = toPublicState(currentState);

package/src/browser/react/use-params.ts

@@ -50,8 +50,6 @@ export function useParams<T>(
   });
 
   const prevValue = useRef(value);
-  // Ref keeps the latest selector without re-subscribing. Event-driven by
-  // design: value updates on store events, not on selector identity change.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 

package/src/browser/react/use-search-params.ts

@@ -24,9 +24,6 @@ import type { ReadonlyURLSearchParams } from "../types.js";
 export function useSearchParams(): ReadonlyURLSearchParams {
   const ctx = useContext(NavigationStoreContext);
 
-  // Always initialize with empty URLSearchParams to match SSR output
-  // and avoid hydration mismatch. The useEffect below syncs from
-  // the real URL after hydration.
   const [searchParams, setSearchParams] = useState<ReadonlyURLSearchParams>(
     () => new URLSearchParams(),
   );
@@ -41,12 +38,10 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       const nextSearch = location.searchParams.toString();
       if (nextSearch !== prevSearch.current) {
         prevSearch.current = nextSearch;
-        // Create a snapshot so callers cannot mutate the source URLSearchParams
         setSearchParams(new URLSearchParams(nextSearch));
       }
     };
 
-    // Sync on mount (picks up search params from browser URL)
     update();
 
     return ctx.eventController.subscribe(update);

package/src/browser/react/use-segments.ts

@@ -86,31 +86,20 @@ export function useSegments<T>(
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Track selector identity to detect when the selector function changes.
-  // Only then do we eagerly recompute during render to avoid staleness.
-  // Without this guard, no-selector mode causes infinite re-renders because
-  // buildSegmentsState creates fresh arrays that fail Object.is checks.
   const prevSelectorIdentity = useRef(selector);
 
-  // Cache SegmentsState to stabilize nested references (path, segmentIds
-  // arrays) so selectors returning composite values don't cause spurious
-  // render-time setState calls.
   const segmentsCache = useRef<{
     location: URL;
     routeSegmentIds: string[];
     state: SegmentsState;
   } | null>(null);
 
-  // Recompute selected value from current store state and apply selector.
-  // Shared by the render-time eager check and the subscription callback.
   function recompute(
     sel: ((state: SegmentsState) => T) | undefined,
   ): T | SegmentsState {
     const location = ctx!.eventController.getLocation();
     const handleState = ctx!.eventController.getHandleState();
 
-    // Reuse cached state when inputs haven't changed by reference,
-    // keeping array/object references stable for composite selectors.
     const cache = segmentsCache.current;
     let segmentsState: SegmentsState;
     if (
@@ -165,8 +154,6 @@ export function useSegments<T>(
       unsubscribeNav();
       unsubscribeHandles();
     };
-    // Stable subscription: selector changes are handled via selectorRef,
-    // state comparison uses prevState ref. No re-subscribe needed.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 

package/src/browser/rsc-router.tsx

@@ -178,8 +178,8 @@ export async function initBrowserApp(
 
   // Register the active store on the module-level handle and wire the
   // jar-divergence observer before any getRangoState() read can detect a
-  // cross-tab/server rotation. The real boot path never populates the
-  // getNavigationStore() singleton, so this handle is the live reference.
+  // cross-tab/server rotation. There is no global store singleton, so this
+  // handle is the live reference.
   registerNavigationStore(store);
 
   // Seed router identity from the initial SSR payload so the first

package/src/browser/types.ts

@@ -14,7 +14,6 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
   metadata?: TMetadata;
   returnValue?: ActionResult;
-  formState?: unknown;
 }
 
 /**

package/src/browser/validate-redirect-origin.ts

@@ -17,11 +17,10 @@ export function validateRedirectOrigin(
       );
       return null;
     }
-    // Return pathname+search+hash for relative inputs, full href for absolute.
-    // This normalizes protocol-relative and other ambiguous forms.
-    return target.href.startsWith(currentOrigin)
-      ? target.href
-      : target.pathname + target.search + target.hash;
+    // Origin matched above, so target.href is same-origin: return the
+    // canonical full href. This normalizes protocol-relative and other
+    // ambiguous forms.
+    return target.href;
   } catch {
     console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
     return null;

package/src/build/route-trie.ts

@@ -63,6 +63,9 @@ export interface TrieNode {
  * @param routeAncestry - Map of route name to ancestry shortCodes
  * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
  * @param routeTrailingSlash - Optional map of route name to trailing slash mode
+ * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
+ * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
+ * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,

package/src/build/route-types/param-extraction.ts

@@ -37,12 +37,15 @@ export function formatRouteEntry(
 ): string {
   const hasSearch = search && Object.keys(search).length > 0;
 
+  // JSON.stringify the pattern and search values so backslashes and quotes in a
+  // route pattern (e.g. a custom regex constraint) survive interpolation into
+  // both the type-level string and the runtime NamedRoutes value.
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
 
   const searchBody = Object.entries(search!)
-    .map(([k, v]) => `${k}: "${v}"`)
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
     .join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }

package/src/build/route-types/router-processing.ts

@@ -617,9 +617,6 @@ export function writeCombinedRouteTypes(
       ? readFileSync(outPath, "utf-8")
       : null;
 
-    // When the static parser can't extract routes (e.g. callback-style urls()),
-    // write an empty placeholder so the build-time transform's injected import
-    // resolves. Runtime discovery will overwrite this with the real routes.
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
@@ -635,11 +632,6 @@ export function writeCombinedRouteTypes(
       hasSearchSchemas ? result.searchSchemas : undefined,
     );
     if (existing !== source) {
-      // On initial dev startup, don't overwrite a file from runtime discovery
-      // (which has all dynamic routes) with a smaller set from the static
-      // parser. The static parser can't see routes generated by Array.from()
-      // or other dynamic code. During HMR (file watcher), always write so
-      // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
         const existingCount = countPublicRouteEntries(existing);
         const newCount = Object.keys(result.routes).filter(

package/src/cache/cache-policy.ts

@@ -69,24 +69,6 @@ export function computeExpiration(
   return { staleAt, expiresAt };
 }
 
-// ============================================================================
-// Cache Key Resolution
-// ============================================================================
-
-/**
- * Resolve cache key using the 3-tier priority:
- * 1. keyFn (full override from route/loader cache options)
- * 2. store.keyGenerator (modifies default key)
- * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
- *
- * Errors from keyFn and store.keyGenerator propagate to the caller.
- * Cache identity is correctness-critical: if explicit key logic throws,
- * silently remapping to a different key could cause cache collisions or
- * serve stale/wrong data. Callers must handle the error or let it surface.
- *
- * Uses _getRequestContext (non-throwing) so that calls outside ALS
- * (e.g. build-time) gracefully fall back to defaultKey.
- */
 export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
@@ -95,34 +77,17 @@ export async function resolveCacheKey(
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
-  // Priority 1: Route/loader-level key function (full override)
   if (keyFn && requestCtx) {
     return await keyFn(requestCtx);
   }
 
-  // Priority 2: Store-level keyGenerator (modifies default key)
   if (store?.keyGenerator && requestCtx) {
     return await store.keyGenerator(requestCtx, defaultKey);
   }
 
-  // Priority 3: Default key (no custom key logic provided)
   return defaultKey;
 }
 
-// ============================================================================
-// Cache Tag Resolution
-// ============================================================================
-
-/**
- * Resolve cache tags from a tags option (static array or function of ctx).
- *
- * Fails open: a thrown tag callback falls back to no tags rather than
- * aborting the request. Tags are additive metadata (not identity), so a
- * missing tag does not cause cache collisions, only a missed invalidation.
- *
- * Shared by the cache() DSL (cache-scope) and loader caching (loader-cache)
- * so tag resolution behaves identically across every cache axis.
- */
 export function resolveTagsOption<TEnv>(
   tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
   ctx: RequestContext<TEnv> | undefined,
@@ -131,10 +96,6 @@ export function resolveTagsOption<TEnv>(
   if (!tags) return undefined;
   if (typeof tags === "function") {
     if (!ctx) {
-      // A dynamic tags function needs the request context to run. Without it
-      // (e.g. resolved outside a request, at build/prerender time) the entry is
-      // cached UNTAGGED and can never be invalidated - surface that rather than
-      // silently dropping the tags, matching the thrown-callback branch below.
       console.warn(
         `[${label}] Dynamic tags function present but no request context; ` +
           `caching without tags (this entry will not be tag-invalidatable).`,
@@ -167,25 +128,10 @@ function normalizeTagList(tags: string[]): string[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
-// ============================================================================
-// Cache Store Resolution
-// ============================================================================
-
-/**
- * Resolve cache store from the 2-tier priority:
- * 1. Explicit store from cache options
- * 2. App-level store from request context
- */
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
   if (explicitStore) {
-    // Register explicit per-scope stores so updateTag()/revalidateTag() can
-    // reach them. This is the single chokepoint every cache axis (segment,
-    // response, loader) resolves through, so registering here covers them all
-    // eagerly - no dependence on whether a tagged write has happened yet. The
-    // app-level store is intentionally not registered (always reachable via
-    // ctx._cacheStore).
     registerExplicitTaggedStore(explicitStore);
     return explicitStore;
   }

package/src/cache/cache-runtime.ts

@@ -46,6 +46,7 @@ import {
   runWithCacheTagScope,
 } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
+import type { CacheItemResult } from "./types.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -84,6 +85,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // cacheTag() call inside the function degrades to a no-op rather than
     // throwing "must be called inside a use cache function" - adopting cacheTag()
     // must not hard-fail in apps/tests without an item-capable cache configured.
+    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
+    // is intentionally NOT stamped here. It is a cached-path-only check; in the
+    // bypass the body actually executes, so the guarded side effects take effect
+    // and nothing is lost on a (non-existent) hit. Same applies to the
+    // non-serializable-args bypass below.
     if (!store?.getItem) {
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
@@ -185,23 +191,29 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Cache lookup
     const cached = await store.getItem(cacheKey);
 
+    // Serve a cached entry on the hit path: deserialize the stored value,
+    // replay handle data (gated on tainted args), and surface the entry's tags
+    // to the request set (the function did not re-run, so its runtime cacheTag()
+    // tags are only available from the stored entry). Shared by the fresh-hit
+    // and stale-hit branches; the only divergence is the stale branch scheduling
+    // background revalidation, which it does after this returns.
+    const serveCached = async (entry: CacheItemResult): Promise<any> => {
+      const result = await deserializeResult(entry.value);
+      if (entry.handles && hasTaintedArgs) {
+        const handleStore = requestCtx?._handleStore;
+        if (handleStore) {
+          const r = await decodeHandles(entry.handles);
+          if (r) restoreHandles(r, handleStore);
+        }
+      }
+      recordRequestTags(entry.tags, requestCtx);
+      return result;
+    };
+
     if (cached && !cached.shouldRevalidate) {
       // Fresh hit: deserialize and return
       try {
-        const result = await deserializeResult(cached.value);
-        // Restore handle data if present
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            const r = await decodeHandles(cached.handles);
-            if (r) restoreHandles(r, handleStore);
-          }
-        }
-        // Surface the hit's tags to the request set so a document built from a
-        // cached item is still tagged (the function did not re-run, so its
-        // runtime cacheTag() tags are only available from the stored entry).
-        recordRequestTags(cached.tags, requestCtx);
-        return result;
+        return await serveCached(cached);
       } catch (error) {
         // The stored value is corrupt/partial (failed RSC deserialize). Report
         // it, then fall through to fresh execution - the miss path below re-runs
@@ -217,16 +229,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     if (cached?.shouldRevalidate) {
       // Stale hit: return stale value, revalidate in background
       try {
-        const result = await deserializeResult(cached.value);
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            const r = await decodeHandles(cached.handles);
-            if (r) restoreHandles(r, handleStore);
-          }
-        }
-        // Tag the request with the stale entry's tags (see fresh-hit note).
-        recordRequestTags(cached.tags, requestCtx);
+        const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.

package/src/cache/cache-scope.ts

@@ -34,12 +34,6 @@ import {
 } from "./cache-policy.js";
 import type { RequestContext } from "../server/request-context.js";
 
-/**
- * Resolve tags for a cache() boundary from its config (static array or
- * function of ctx). Thin wrapper over the shared resolveTagsOption so the
- * cache() DSL and loader caching resolve tags identically.
- * @internal
- */
 export function resolveCacheTags(
   config: PartialCacheOptions | false,
   ctx: RequestContext | undefined,
@@ -54,17 +48,6 @@ function debugCacheLog(message: string): void {
   }
 }
 
-// ============================================================================
-// Key Generation (internal)
-// ============================================================================
-
-/**
- * Generate cache key base from host, pathname, route params, and search params.
- * Host is included to prevent cross-host cache collisions on shared stores.
- * Route params and search params are sorted alphabetically for deterministic keys.
- * Internal _rsc* and __* query params are excluded.
- * @internal
- */
 function getCacheKeyBase(
   host: string,
   pathname: string,
@@ -80,16 +63,6 @@ function getCacheKeyBase(
   return key;
 }
 
-/**
- * Generate default cache key for a route request.
- * Includes pathname, route params, and user-facing search params for
- * correct scoping. Internal _rsc* params are excluded.
- * Includes request type prefix since they produce different segment sets:
- * - doc: document requests (full page load)
- * - partial: navigation requests (client-side navigation)
- * - intercept: intercept navigation (modal/overlay routes)
- * @internal
- */
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,

package/src/cache/cache-tag.ts

@@ -18,35 +18,11 @@ import {
 
 const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
 
-/**
- * Normalize a tag for storage.
- *
- * Returns the tag unchanged if usable, or null if it is empty/whitespace-only
- * (dropped consistently in every environment - an empty tag matches nothing).
- *
- * Backend-specific constraints are intentionally NOT enforced here so the tag
- * primitive stays backend-agnostic. In particular, the CFCacheStore
- * encodeURIComponent's tags at serialization time so commas/spaces/non-Latin1
- * characters cannot corrupt the comma-delimited Cloudflare Cache-Tag header or
- * the HTTP marker header (it does not reject them). Keep tags short and
- * low-cardinality: a tag's KV marker key must stay under Cloudflare's 512-byte
- * limit, and a Cache-Tag value under 1024 bytes. The in-memory store has no
- * such limitations.
- *
- * @internal
- */
 export function normalizeTag(tag: string): string | null {
   if (!tag || !tag.trim()) return null;
   return tag;
 }
 
-/**
- * Normalize a tag collection: drop empty/whitespace-only tags so the WRITE path
- * matches the invalidate path (updateTag/revalidateTag/cacheTag all normalize).
- * Does not deduplicate - callers that need that wrap with a Set.
- *
- * @internal
- */
 export function normalizeTags(tags: Iterable<string>): string[] {
   const out: string[] = [];
   for (const tag of tags) {
@@ -89,19 +65,6 @@ export function cacheTag(...tags: string[]): void {
   }
 }
 
-/**
- * Record `tags` into the request-scoped tag set (ctx._requestTags), the union of
- * every cache tag resolved while producing the response. The document cache reads
- * this after the render settles so a full-page entry is tagged with everything its
- * content used, making it invalidatable by updateTag()/revalidateTag().
- *
- * Called at the tag-resolution sites: "use cache" stores (cache-runtime, both the
- * miss and read/hit paths), loader cache (cache-policy/loader-cache), and segment
- * cache() (cache-scope). Writes the field directly (not via ctx.set()) so it does
- * not trip the cache-scope side-effect guard, mirroring cacheTag() itself.
- *
- * @internal
- */
 export function recordRequestTags(
   tags: Iterable<string> | undefined,
   ctx: RequestContext | undefined = _getRequestContext(),