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

package/skills/testing/server-tree.md

@@ -0,0 +1,128 @@
+# Inspecting the rendered tree — renderServerTree, findClientBoundaries, findElements
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` · **DSL it tests:** client islands across the boundary + server-rendered host content (see `/route`)
+
+`renderServerTree` serializes the real Flight (identical bytes to `renderToFlightString`) and then deserializes it back to an inspectable React element tree you traverse — that serialize/deserialize round-trip is REAL; what you SEED is the element you render plus the request context (`request`/`headers`/`params`/`vars`/`env`). The win over the wire string: a client boundary's props come back as real JS values (a `Date` is a `Date`, not the opaque `$D...` encoding) and you can confirm a `"use client"` component actually crossed the boundary (an `I` row) instead of being inlined. There is NO hydration and NO interaction — boundaries are inert placeholders carrying props.
+
+## API
+
+### Options — `RenderServerTreeOptions` (extends `RenderToFlightStringOptions`)
+
+| Field              | Type                      | Meaning                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`          | `Request \| string`       | The request the render runs under (absolute URL, path, or a `Request`). Defaults to `http://localhost/`. A server component reading `getRequestContext()` sees this url/cookies. A passed `Request`'s headers win; `headers` is then ignored.                                                                                          |
+| `headers`          | `HeadersInit`             | Request headers (e.g. `Cookie`) visible to the server tree, when `request` is a string.                                                                                                                                                                                                                                                |
+| `env`              | `unknown`                 | Env / bindings exposed as `ctx.env`. Defaults to `{}`.                                                                                                                                                                                                                                                                                 |
+| `params`           | `Record<string, string>`  | Route params exposed via `ctx.params` and loader contexts.                                                                                                                                                                                                                                                                             |
+| `routeName`        | `string`                  | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                        |
+| `vars`             | `VarsInit`                | Context variables visible via `ctx.get(...)`, as a prior middleware would have set them. Object form (`{ user }`) or `[key, value]` tuples.                                                                                                                                                                                            |
+| `clientComponents` | `Record<string, unknown>` | The `"use client"` components reachable from the tree, keyed by the boundary name to register each as a client reference (in place) so it serializes as an `I` row. Omit when `rangoUseClientTransform()` auto-discovers them, or for pure server-only trees. First-wins per worker; already-registered references are left untouched. |
+
+### Context — what your code receives
+
+A server component rendered here runs under a real request context: `getRequestContext()` resolves, `ctx.params`/`ctx.routeName`/`ctx.env` reflect the options, `ctx.get(MyVar)` reads a seeded `var`, and cookies come off the request. Same seeding as the handler-test primitives — you render an **element** you build (`<Page />`); to run a route **handler** `(ctx) => rsc` use `renderHandler` (see `./render-handler.md`).
+
+### Returns — `RenderServerTreeResult`
+
+```ts
+renderServerTree(element, opts?): Promise<{ flight: string; tree: unknown }>
+```
+
+| Field    | Type      | Meaning                                                                                                                                                                                                  |
+| -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flight` | `string`  | The raw Flight wire string (so `toMatchFlight` assertions still apply).                                                                                                                                  |
+| `tree`   | `unknown` | The deserialized React element tree. Server elements are plain React elements; each client boundary is an inert placeholder whose `props` are the real deserialized JS values that crossed the boundary. |
+
+#### `findClientBoundaries(tree, selector?) -> ClientBoundary[]`
+
+Every client boundary in document order; always an array (no throw on zero/many — destructure `const [tag] = ...` and assert `.length` when the count matters; no match yields `[]`). `selector` is a STRING (match by export name) or a `BoundarySelector` object, criteria AND-ed.
+
+| `BoundarySelector` | Type                                    | Meaning                                                                                    |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `name`             | `string`                                | Match the boundary's export name (same as a bare string).                                  |
+| `testId`           | `string`                                | Match `props["data-testid"]` exactly (a `data-testid` you passed AS A PROP to the island). |
+| `props`            | `Record<string, unknown>`               | Subset deep-equal match (Date/Map/Set/array/nested-object aware); unlisted props ignored.  |
+| `where`            | `(boundary: ClientBoundary) => boolean` | Arbitrary predicate.                                                                       |
+
+`ClientBoundary` = `{ id, name, props (excludes children), children, element }`.
+
+#### `findElements(tree, selector?) -> FoundElement[]`
+
+Every SERVER/HOST element a server component produced (`<article>`, `<h2>`), in document order; always an array. `selector` is a host TAG string (`"h2"`) or an `ElementSelector` object, criteria AND-ed.
+
+| `ElementSelector` | Type                                 | Meaning                                                                            |
+| ----------------- | ------------------------------------ | ---------------------------------------------------------------------------------- |
+| `tag`             | `string`                             | Match the host tag name (`"article"`, `"h2"`).                                     |
+| `testId`          | `string`                             | Match `props["data-testid"]` exactly (on a host element).                          |
+| `props`           | `Record<string, unknown>`            | Subset deep-equal match (Date/Map/Set/array/nested aware).                         |
+| `text`            | `string \| RegExp`                   | Match the element's text content (substring for a string, `.test()` for a RegExp). |
+| `where`           | `(element: FoundElement) => boolean` | Arbitrary predicate.                                                               |
+
+`FoundElement` = `{ tag, props (excludes children), children, text, element }`.
+
+#### `textContent(node) -> string`
+
+Concatenates every string/number leaf of a node's subtree in document order — the clean way to assert rendered text, instead of `JSON.stringify(tree).toContain(...)`.
+
+## Recipe
+
+```tsx
+import { it, expect } from "vitest";
+import {
+  renderServerTree,
+  findClientBoundaries,
+  findElements,
+  textContent,
+} from "@rangojs/router/testing/flight";
+import { PriceTag } from "./PriceTag.js"; // a "use client" component (any filename)
+
+async function ProductPanel({ amount, asOf }: { amount: number; asOf: Date }) {
+  await Promise.resolve();
+  return (
+    <article>
+      <h2>Wine</h2>
+      <PriceTag amount={amount} currency="USD" asOf={asOf} />
+    </article>
+  );
+}
+
+it("client props survive the serialize -> deserialize round trip", async () => {
+  const { flight, tree } = await renderServerTree(
+    <ProductPanel amount={19.5} asOf={new Date("2026-01-02T00:00:00Z")} />,
+    // Omit clientComponents when rangoUseClientTransform() is wired (see ./setup.md);
+    // otherwise register islands explicitly:
+    { clientComponents: { PriceTag } },
+  );
+  expect(flight).toMatchFlight("PriceTag"); // wire assertions still work
+
+  const [tag] = findClientBoundaries(tree, "PriceTag");
+  expect(tag.props.amount).toBe(19.5); // a real number
+  expect(tag.props.asOf).toBeInstanceOf(Date); // a real Date, not "$D..."
+});
+
+it("asserts the server-rendered host content", async () => {
+  const { tree } = await renderServerTree(
+    <ProductPanel amount={19.5} asOf={new Date("2026-01-02T00:00:00Z")} />,
+    { clientComponents: { PriceTag } },
+  );
+  const [h2] = findElements(tree, "h2");
+  expect(h2.text).toBe("Wine");
+  expect(textContent(tree)).toContain("Wine"); // instead of JSON.stringify(tree)
+});
+```
+
+## Caveats
+
+- This renders an ELEMENT you build (`<Page />`). To test a route HANDLER (a `(ctx) => rsc` function registered via `path(...)`), use `renderHandler` (see [`./render-handler.md`](./render-handler.md)) — handlers have their own util. Do NOT wrap a handler in `createElement` and render it here: a handler is not a component, so React would invoke it with `props` as its argument instead of the real `HandlerContext`, and the seeded `params`/`vars` plus `ctx.use`/`ctx.reverse`/`ctx.get`/`cookies()` would all be absent.
+- Island auto-discovery from the server tree's imports needs `rangoUseClientTransform()` in the rsc project (see `./setup.md`). Without it a plainly-imported island is just a function the serializer renders server-side — register islands explicitly via `{ clientComponents: { PriceTag } }`.
+- Same alias requirement as `./flight.md`: a rendered component (or handler) that reads `getRequestContext()`/`cookies()` from the `@rangojs/router` barrel needs the `index.rsc.ts` alias (see `./setup.md`), or it hits the throwing out-of-react-server stub.
+- A client boundary's props come back as REAL JS values after deserialization (a `Date` is a `Date`, not a `$D...` encoding) — but there is NO hydration and NO interaction; boundaries are inert placeholders carrying props.
+- Server COMPONENTS do not survive Flight as identities (they are executed during serialization), so `findElements` matches the host elements they PRODUCED, not the component function. Client islands keep identity — use `findClientBoundaries` for those.
+- `findClientBoundaries` finds islands (`I` rows); `findElements` finds host elements. A `testId` on an island matches with `findClientBoundaries`; a `testId` on a host element matches with `findElements`. Use `textContent(node)` in place of `JSON.stringify(tree).toContain`.
+- A true interactive, clickable DOM `renderServer` is intentionally NOT shipped: in-process happy-dom hydration re-tests React more than your app and misses server/client divergence (the only hydration bug worth a dedicated test, which needs a real browser). Test interaction at e2e.
+
+## See also
+
+- `/route` — the DSL this tests
+- Siblings: `./flight.md`, `./render-handler.md`, `./setup.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderServerTree — serialize then deserialize to an inspectable tree" (and the "findElements / textContent" subsection)

package/skills/testing/setup.md

@@ -0,0 +1,120 @@
+# Testing setup — the two vitest projects
+
+**Layer:** cross-cutting (vitest config) · **Import:** `@rangojs/router/testing/vitest`
+
+Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolves the bare specifier to its react-server impls so your app's router / loaders / middleware import in a bare Vitest process. You SEED nothing here — this file only wires the two projects every other recipe builds on. The node/DOM project keeps React on its CLIENT build; the Flight project flips to the `react-server` condition.
+
+## API
+
+### Options — `RangoTestAliasOptions`
+
+| Field    | Type                     | Meaning                                                                                                                                                                                                                                                                                      |
+| -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preset` | `"node" \| "cloudflare"` | Deployment preset, matching `rango({ preset })` in the Vite plugin. `"cloudflare"` additionally stubs the `cloudflare:workers` / `cloudflare:email` runtime virtuals a CF route tree imports. A string (not a boolean) so more presets can be added without an API change. Default `"node"`. |
+
+### Functions
+
+| Function                    | Returns                                   | Use                                                                                                                                                                                                         |
+| --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                         |
+| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                  |
+
+### Returns — `RangoTestConfig` (from `rangoTestConfig`)
+
+```ts
+interface RangoTestConfig {
+  alias: TestAlias[]; // -> test.alias
+  server: { deps: { inline: RegExp[] } }; // [/@rangojs[/\\]router/] -> test.server.deps.inline
+}
+```
+
+## Recipe
+
+```ts
+// vitest.config.ts — the node + DOM project (keeps React on its CLIENT build)
+import { defineConfig } from "vitest/config";
+import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ["test/**/*.test.{ts,tsx}"],
+    environment: "node", // renderRoute tests add a `// @vitest-environment happy-dom` pragma
+    // `preset: "cloudflare"` also stubs cloudflare:workers / cloudflare:email (default "node").
+    ...rangoTestConfig({ preset: "cloudflare" }),
+  },
+});
+```
+
+```ts
+// vitest.rsc.config.ts — the Flight project (react-server condition)
+import { defineConfig } from "vitest/config";
+import {
+  rangoTestAliases,
+  rangoUseClientTransform,
+} from "@rangojs/router/testing/vitest";
+
+// Production React in this process AND any forked worker (forks inherit env).
+process.env.NODE_ENV = "production";
+
+export default defineConfig({
+  plugins: [rangoUseClientTransform()],
+  resolve: {
+    conditions: ["react-server"],
+    alias: rangoTestAliases({ preset: "cloudflare" }), // or { preset: "node" }
+  },
+  test: {
+    globals: true,
+    include: ["**/*.rsc-test.{ts,tsx}"],
+    pool: "forks",
+    execArgv: ["--conditions=react-server"], // or React throws "react-server condition must be enabled"
+  },
+});
+```
+
+```ts
+// example.test.ts — one test in the node/DOM project, importing real app code
+import { describe, it, expect } from "vitest";
+import { dispatch } from "@rangojs/router/testing";
+import { createRouter } from "@rangojs/router";
+import { apiPatterns } from "../src/api/urls"; // path.json(...) routes only, no Prerender()
+
+const router = createRouter().routes(apiPatterns);
+
+describe("api", () => {
+  it("serializes a JSON response route", async () => {
+    const res = await dispatch(router, { request: "/health" });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+});
+```
+
+Scripts:
+
+```jsonc
+{
+  "scripts": {
+    "test:unit": "vitest run",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts",
+  },
+}
+```
+
+## Caveats
+
+- Node >= 23 requires `rangoTestConfig()`, not bare `rangoTestAliases()`. `@rangojs/router` is consumed as SOURCE (exports -> `./src/*.ts`), and Node >= 23 refuses to type-strip `.ts` under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). `rangoTestConfig` ships as compiled JS AND adds `server.deps.inline: [/@rangojs[/\\]router/]` so Vite (not Node) transpiles rango source. With bare `rangoTestAliases` you must wire `deps.inline` yourself.
+- Two separate projects. The node/DOM project keeps React on its CLIENT build; the Flight project uses the `react-server` condition in a separate `vitest.rsc.config.ts`. The main project must NOT set `react-server` — it flips React to the no-hooks server build and breaks every `renderRoute` / client test.
+- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`).
+- `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
+- The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
+- The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
+- The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
+- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`.
+
+## See also
+
+- (cross-cutting)
+- Siblings: `./flight.md`, `./server-tree.md`, `./render-handler.md`, `./response-routes.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")

package/src/__internal.ts

@@ -9,10 +9,6 @@
  * adding them to the public API.
  */
 
-// ============================================================================
-// Segment Resolution (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal representation of a resolved route segment.
@@ -26,10 +22,6 @@ export type { ResolvedSegment, SegmentMetadata } from "./types.js";
  */
 export type { MatchResult, SlotState } from "./types.js";
 
-// ============================================================================
-// Intercept System (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Context for intercept route selection.
@@ -40,10 +32,6 @@ export type {
   InterceptWhenFn,
 } from "./server/context.js";
 
-// ============================================================================
-// Browser State (Internal)
-// ============================================================================
-
 /**
  * @internal
  * RSC protocol payload structure.
@@ -68,10 +56,6 @@ export type {
   NavigationUpdate,
 } from "./browser/types.js";
 
-// ============================================================================
-// Handle System (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal handle storage mechanism.
@@ -84,26 +68,17 @@ export type { HandleStore, HandleData } from "./server/handle-store.js";
  */
 export type { SegmentHandleData } from "./cache/types.js";
 
-// ============================================================================
-// Cache Internals
-// ============================================================================
-
 /**
  * @internal
  * Internal cache entry data structure.
  */
 export type {
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
   SerializedSegmentData,
   CacheDefaults,
 } from "./cache/types.js";
 
-// ============================================================================
-// Router Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Router context for AsyncLocalStorage.
@@ -114,10 +89,6 @@ export type {
   InterceptResult,
 } from "./router/router-context.js";
 
-// ============================================================================
-// Match Pipeline (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Route match context during pipeline processing.
@@ -133,10 +104,6 @@ export type {
  */
 export type { RouteMatchResult } from "./router/pattern-matching.js";
 
-// ============================================================================
-// Server Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Entry data during route traversal.
@@ -153,10 +120,6 @@ export type {
   EntryPropSegments,
 } from "./server/context.js";
 
-// ============================================================================
-// Handler Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal handler context with additional props for router internals.
@@ -164,30 +127,18 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
-// ============================================================================
-// Rendering (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Builds React element trees from route segments.
  */
 export { renderSegments } from "./segment-system.js";
 
-// ============================================================================
-// Error Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Error sanitization and network error utilities.
  */
 export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
 
-// ============================================================================
-// Type Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
@@ -217,10 +168,6 @@ export type {
   RevalidationDecisionEvent,
 } from "./router/telemetry.js";
 
-// ============================================================================
-// Pre-render / Static Handler Guards (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Type guard for prerender handler definitions.
@@ -233,20 +180,12 @@ export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
  */
 export { isStaticHandler } from "./static-handler.js";
 
-// ============================================================================
-// URL Pattern Internals
-// ============================================================================
-
 /**
  * @internal
  * Sentinel used to tag response-type route entries.
  */
 export { RESPONSE_TYPE } from "./urls.js";
 
-// ============================================================================
-// Route Match Debug (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Debug utilities for route matching performance analysis.
@@ -256,10 +195,6 @@ export {
   getMatchDebugStats,
 } from "./router/pattern-matching.js";
 
-// ============================================================================
-// Debug Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Debug utilities for manifest inspection and comparison.

package/src/browser/action-coordinator.ts

@@ -5,7 +5,7 @@ import type { ActionEntry } from "./event-controller.js";
  * full-update-unsupported cases are handled inline in the bridge before
  * reconciliation; this only covers successfully-reconciled partial responses.
  */
-export type ActionScenario =
+type ActionScenario =
   | {
       type: "navigated-away";
       historyKeyChanged: boolean;

package/src/browser/action-fence.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+
+let fenceCount = 0;
+
+export function enterActionFence(): void {
+  fenceCount++;
+}
+
+export function exitActionFence(): void {
+  if (fenceCount > 0) fenceCount--;
+}
+
+export function isActionFenceActive(): boolean {
+  return fenceCount > 0;
+}
+
+/** Test-only: reset the refcount between cases. */
+export function __resetActionFence(): void {
+  fenceCount = 0;
+}

package/src/browser/cookie-name.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
+
+/** Internal response header carrying the keepClientCache() directive. */
+export const KEEP_CACHE_HEADER = "x-rango-keep-cache";
+
+// Per-client signal headers (lower-case) that a SHARED response cache must never
+// store or replay (Finding #3): a `Set-Cookie` (rango state rotation, or any
+// cookie a loader set) and the keepClientCache() directive. Strip-all-Set-Cookie
+// is deliberate — a shared store can't know the resolved cookie name, and any
+// per-client cookie in a cacheable document is the hazard. Single source for the
+// predicate, presence check, and strip below.
+const PER_CLIENT_SIGNAL_HEADERS: readonly string[] = [
+  "set-cookie",
+  KEEP_CACHE_HEADER,
+];
+
+/** True for a per-client signal header. */
+export function isPerClientSignalHeader(name: string): boolean {
+  return PER_CLIENT_SIGNAL_HEADERS.includes(name.toLowerCase());
+}
+
+/** True if `headers` carries any per-client signal. */
+export function hasPerClientSignal(headers: Headers): boolean {
+  return PER_CLIENT_SIGNAL_HEADERS.some((name) => headers.has(name));
+}
+
+/** Remove every per-client signal header from `headers` in place. */
+export function stripPerClientSignals(headers: Headers): void {
+  for (const name of PER_CLIENT_SIGNAL_HEADERS) headers.delete(name);
+}
+
+/**
+ * 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 function getRawCookieValue(
+  cookieString: string | null,
+  name: string,
+): string | null {
+  if (!cookieString) return null;
+  const target = name + "=";
+  for (const part of cookieString.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith(target)) {
+      const value = trimmed.slice(target.length);
+      return value === "" ? null : value;
+    }
+  }
+  return 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 function encodeStateValue(version: string, timestamp: number): string {
+  return `${encodeURIComponent(version)}:${timestamp}`;
+}
+
+/** 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 function decodeStateValue(raw: string): StateValue | null {
+  const colon = raw.indexOf(":");
+  if (colon <= 0) return null;
+  const timestamp = Number(raw.slice(colon + 1));
+  if (!Number.isFinite(timestamp)) return null;
+  let version: string;
+  try {
+    version = decodeURIComponent(raw.slice(0, colon));
+  } catch {
+    // A malformed percent-escape (e.g. "%:1") must mint fresh, not throw —
+    // a thrown URIError here would 500 the server seat or fail client boot.
+    return null;
+  }
+  return { version, timestamp };
+}
+
+/**
+ * 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 function mintStateValue(
+  version: string,
+  prevRaw: string | null,
+): string {
+  const prevTs = prevRaw ? (decodeStateValue(prevRaw)?.timestamp ?? 0) : 0;
+  const ts = Math.max(Date.now(), prevTs + 1);
+  return encodeStateValue(version, ts);
+}
+
+/**
+ * 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 function stateCookieAttributes(secure: boolean): string {
+  return `; Path=/; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+
+/** Serialize a full `name=value` cookie string with the state attributes. */
+export function serializeStateCookie(
+  name: string,
+  value: string,
+  secure: boolean,
+): string {
+  return `${name}=${value}${stateCookieAttributes(secure)}`;
+}