feat(router): rango state session cookie + invalidateClientCache/keepClientCache - #560

…lumbing

Additive, no behavior change. Adds the stateCookiePrefix router option, resolves
the rango state cookie name once at router init ({sanitizedPrefix}_{sanitizedRouterId};
the prefix charset excludes _ so the first _ is always the prefix/routerId
boundary, keeping the name injective), exposes resolvedStateCookieName on the
router, and ships it in payload metadata following the prefetchCacheTTL path.

New cookie-name.ts (value codec + attribute serialization, shared client/server,
no name composition) and state-cookie-name.ts (server-only name composition).
Nothing consumes the cookie yet; the storage cutover is Phase 2.

Unit: cookie-name (encode/decode round-trip, malformed -> null, attributes),
state-cookie-name (default + sanitization + empty-fallback + injective separator).

Rewrites rango-state.ts to store the X-Rango-State value in a session cookie
named by the server-resolved name (initRangoState now takes the resolved name,
not routerId; bare default prefix when metadata lacks it). The per-request
document.cookie read IS the cross-tab value sync, so the storage event is gone.
An in-memory mirror is a write-through fallback authoritative only when the
cookie is unreadable; cookieBacked tracks jar presence so an external clear is
detected once. Adds the max(now, prev+1) monotonic guard, one-time legacy
localStorage cleanup, and an unregistered external-rotation observer hook
(wired to the store handle in Phase 3). Couples cache-key lifecycle to the
session: clearing cookies takes the state with it.

Ships stateCookieName on RscMetadata (client read).

Unit: boot keep-vs-mint, per-request read, mirror-on-unreadable, monotonic
guard, legacy cleanup, observer fires-once/self-rotation-silent/external-clear/
multi-app-isolation. E2e rango-state-invalidation reads the cookie now (dev
green; full dev+prod at the pre-bridge checkpoint).

Adds a dependency-light navigation-store-handle module that holds the live
store reference (the getNavigationStore singleton is never populated by the real
boot path) and wires the jar-divergence observer: when a per-request cookie read
detects an EXTERNAL rotation (sibling tab, server Set-Cookie, cookie clear),
this tab marks its history cache stale. The history cache is not state-keyed, so
the value rotation alone never reaches it.

Splits the store's stale-marking: markHistoryCacheStale() marks history entries
only, WITHOUT clearing the prefetch caches or rotating the state (the existing
markCacheAsStale path still does both). This is load-bearing: routing the
observer through the prefetch-clearing path would re-rotate on every observed
rotation and ping-pong across tabs.

Boot registers the store on the handle before any getRangoState() read.

Unit: handle register/get, observer fires once on external rotation with no
re-rotation (no ping-pong), silent on self-rotation; markHistoryCacheStale
marks entries stale.

…ache

Adds invalidateClientCache(), exported from the root entry and selected by
export conditions like cookies():
- default (index.ts -> browser/invalidate-client-cache.ts): client seat. Guards
  document (SSR no-op + dev warning behind a foldable NODE_ENV check), then marks
  the history cache stale + broadcasts (SWR, same path as the action bridge),
  with a pre-boot clearPrefetchCache fallback.
- react-server (index.rsc.ts -> server/cookie-store.ts): server seat. Writes ONE
  rotated Set-Cookie via the resolved cookie name, idempotent within a request,
  inert (dev warning) outside a request context (non-throwing _getRequestContext),
  and guarded inside a cache boundary (assertNotInsideCacheContext, allowed in
  loaders). The timestamp is max(serverNow, inboundClientTs+1) so a same-ms server
  rotation still differs from the client value.

Mechanics: createRequestContext gains stateCookieName + version (threaded from the
router at handler.ts), captured by a new closure method ctx._rotateStateCookie()
that appends the raw Set-Cookie with a literal ':' (not serializeCookieValue's
URL-encoded form). prerender synthetic contexts get a no-op.

Removes useClientCache + ClientCacheControls (hard delete, pre-release hygiene):
the hook, its barrel re-export (browser/react/index.ts), client.tsx exports, the
client.rsc.tsx comment, two navigation-store.ts comments, its test; migrates the
vite-rsc-demo dogfood to invalidateClientCache() (root import); documentation-imports
gains a positive root entry for invalidateClientCache and drops useClientCache.

Docs-sync: feature-map.md (export enumeration + cookie-based cross-tab note, fixed
the stale 'page visibility events' wording), feature-file-map.md (new rango-state
row, dropped use-client-cache), SKILL.md, and registers the design doc in the
package docs hub.

Unit: server seat (one Set-Cookie, literal colon, idempotent, monotonic-vs-inbound,
no-name no-op, cache-guard throw) + client seat (SSR no-op, store mark-stale,
pre-boot fallback). E2e client/server seat deferred to the pre-bridge checkpoint.

Replaces the action bridge's eager clear-at-start with a refcounted fence whose
invalidation decision is deferred to the response.

New action-fence.ts: a refcounted flag raised while any action is in flight.
While up: prefetch consumption is suspended (navigation-client canUsePrefetch),
a genuine mid-action navigation fetches with cache:no-store so the browser HTTP
cache can't serve stale prefetched bytes (navigation-client doFreshFetch), and
popstate is treated as SWR (navigation-bridge isStale || fenceActive). Nothing
is rotated/wiped/broadcast while up, so sibling tabs see no pre-commit signal.

server-action-bridge: :164 markCacheAsStaleAndBroadcast becomes enterActionFence;
exitActionFence in finally (refcount lifts at zero). The response is read for the
x-rango-keep-cache directive, which gates every terminal invalidation site
(navigated-away, normal, hmr-missing, consolidation) on !keepCache. A directive-free
action reproduces today's post-commit end state; the decision is per-response, so a
concurrent directive-free action still invalidates.

keepClientCache(): root entry, export-condition selected. react-server
(cookie-store) sets the x-rango-keep-cache response header via a new
ctx._setKeepCacheDirective() (idempotent .set), inert outside a request, guarded
inside a cache boundary. default (browser/invalidate-client-cache) is a warn no-op.

Gate: semantic matrix stays green (39, dev+prod) — directive-free actions are
observationally equivalent; rango-state-invalidation still rotates end to end.

Unit: action-fence refcount (incl. not-dropped-while-pending), keepClientCache
server seat (header, idempotent, inert, cache-guard) + client no-op. The keep /
invalidate SEAT e2e (new test-app routes) lands with Phase 6.

…ores (Finding #3)

A Set-Cookie (e.g. a rango state rotation from invalidateClientCache(), or any
cookie a loader set on a cached document) stored in a SHARED response store is
replayed to every client on a hit — pinning them to one value and even rolling
a rotated client back to a prior one. The x-rango-keep-cache directive header is
the mirror: a replayed 'keep' would suppress invalidation for replayed clients.

Primary chokepoint: shouldCacheResponse (document-cache.ts) now returns null
when the response carries Set-Cookie or x-rango-keep-cache, so the document-cache
middleware never stores them. Defense-in-depth: MemorySegmentCacheStore and the
CF KV envelope strip both headers in putResponse (public, reachable directly by
tag-revalidation re-puts that bypass the chokepoint). CF L1 cache.put already
throws on Set-Cookie responses (platform behavior).

Unit: document-cache refuses an s-maxage response carrying Set-Cookie or
x-rango-keep-cache; MemorySegmentCacheStore strips both while keeping other
headers.

…ction)

Adds test-app routes exercising the new directives on the existing
/loader-cookie/action-sets-cookie page: actionKeepCache (keepClientCache only)
and actionKeepThenInvalidate (both verbs), with buttons.

E2e (dev + production):
- keepClientCache() leaves the rango-state value unchanged (the fence-and-defer
  directive suppresses the automatic rotation end to end);
- keepClientCache() + invalidateClientCache() still rotates (invalidation wins:
  the explicit Set-Cookie from the server seat lands regardless), which also
  exercises the invalidateClientCache server seat end to end.

No routes added/removed, so no generated-route-file change.

…tion)

A browser-code invalidateClientCache() (the client seat) rotates the rango state
value via markCacheAsStaleAndBroadcast -> clearPrefetchCache -> invalidateRangoState.
Adds an InvalidateClientCacheButton to the action-sets-cookie page and asserts the
value rotates (version preserved, timestamp advanced) dev + production. All three
seats are now e2e-covered: client invalidate, server invalidate, and keepClientCache.

…ation gaps)

The fence-and-defer restructure scattered invalidation across terminal scenarios
that not every action path reaches, breaking main's invariant that EVERY action
invalidates. Three defects, one family:

- Mutate-then-redirect actions (Flight metadata.redirect and X-RSC-Redirect
  paths) returned before the scenario switch, so no rotation/wipe/stale-mark/
  broadcast — Back served the pre-mutation page as fresh.
- The simple-redirect path returns a never-settling promise, so createFromFetch
  never settled and the finally (the only exitActionFence) never ran: the fence
  refcount leaked permanently, disabling prefetch + forcing no-store/SWR for the
  whole session.
- Error, abort, intercept navigated-away, and concurrent-skip/consolidation
  terminals all skipped invalidation, breaking the 'same end state as today'
  parity row (incl. a directive-free action overlapping a keep action never
  invalidating).

Fix: one latched finalizeAction() — invalidate once unless keepCache, then
exitActionFence — called from the finally AND before the never-settling
SPA-redirect returns. Removes the five scattered per-scenario invalidation gates;
the scenarios keep only their revalidation refetches (suppressed on keep).

Gate: semantic matrix 39 (dev+prod) still green; rango-state + keep/invalidate
e2e green. Redirect-invalidation / Back e2e to follow.

… cookie, observer/fence gaps

Addresses the review findings beyond the bridge family:

- #6 decodeStateValue wraps decodeURIComponent in try/catch: a malformed
  percent-escape ('%:1') returned null instead of throwing (was a 500 on the
  server seat and a boot failure on the client).
- #4 CF L1 putResponse strips Set-Cookie + the directive header (only KV/L2 was
  covered); the in-repo guarantee no longer depends on the unverified platform
  Set-Cookie rejection, and nothing platform-side rejects the custom directive.
- #5 the three full-document payloads that omitted stateCookieName (PE re-render,
  PE error boundary, notFound) now ship it; a PE-booted or 404 session no longer
  binds the bare default cookie name while the server writes {prefix}_{routerId}.
- #8 _rotateStateCookie's monotonic guard falls back to the request Cookie when
  X-Rango-State is absent (action POSTs / plain fetch carry no router header but
  do send the cookie), so a same-ms server mint can't silently equal the client.
- #7 popstate restore calls getRangoState() before reading the stale bit so the
  jar-divergence observer can mark history stale — a server Set-Cookie rotation
  is no longer invisible to a popstate-first interaction.
- #9 prefetch fetches get the fence's cache:no-store too (was navigation-only).
- #10 the directive header is now KEEP_CACHE_HEADER + an isPerClientSignalHeader()
  helper shared by all strip sites (was a bare literal in 5 files). Strip-all
  Set-Cookie is the documented rule (a shared store can't know the cookie name);
  the design doc's match-rule line and fence-terminal enumeration are amended.

Unit: malformed-escape decode, server mint from the Cookie header. Gates: full
unit suite (3614), semantic matrix 39, rango-state e2e 6 — all green.

Quality cleanups from a 4-angle review (no behavior change):
- Hoist the monotonic mint rule into cookie-name.ts mintStateValue(version,
  prevRaw); the client mintValue and the server _rotateStateCookie now both call
  it (was the max(now, prev+1) guard hand-copied into both seats).
- document-cache reuses a new hasPerClientSignal(headers) instead of open-coding
  the Set-Cookie / x-rango-keep-cache presence check, keeping the signal list in
  one module alongside isPerClientSignalHeader.
- Extract the duplicated makeJar cookie-jar mock into src/__tests__/cookie-jar-mock.ts;
  rango-state and navigation-store-handle suites import it.
- Drop a redundant second assertion in the keepClientCache idempotency test.

Three review rounds over the rango-state cookie branch (#560).

Correctness:
- Action fence leaked on the X-RSC-Reload (version-mismatch) terminal: like the
  simple-redirect and router-id-mismatch terminals it navigates away via a
  never-settling promise, so the finally never runs. finalizeAction() now runs
  in onReload, skipping invalidation (the mismatch short-circuits server-side, so
  nothing mutated and a broadcast would only risk hard-reloading a sibling).
- _rotateStateCookie's monotonic guard read the prior value through the decoding
  getParsedCookies, double-decoding any version containing ':' or '%' (NaN
  timestamp -> prevTs 0 -> same-ms collision the divergence observer can't see).
  Reads raw via the shared getRawCookieValue now; an empty header/cookie counts
  as absent (no '' short-circuit of the ?? chain).
- CF response cache replayed per-client signals on READ: a pre-fix or
  pinned-`version` KV envelope (or L1 entry) could replay one client's Set-Cookie
  to another. toClientResponse and kvGetResponse strip now; the KV hd filter is
  inside the corrupt-envelope try so a malformed hd evicts rather than throwing.
- finalizeAction wraps invalidation in try/finally so a throw can't leak the
  fence; removed the dead NavigationStore.broadcastCacheInvalidation.

Consolidation:
- One PER_CLIENT_SIGNAL_HEADERS source for the strip/predicate/presence helpers.
- One getRawCookieValue shared by both seats — their agreement IS the guard's
  contract, so the client mirror and server read the same jar entry.

Tests (dev + production where e2e):
- Latch exactly-once per terminal incl. simple-redirect (success + keepCache) and
  reload (no invalidation); equals-mirror observer no-op.
- credentials-not-omit + no-store-under-fence on navigation and prefetch fetches.
- percent-encoded + empty header/cookie server mint.
- CF read-side strip: KV replay, malformed-hd evict, L1 serve.
- cookie-cleared-mid-session mints fresh via popstate; Back-after-redirect
  revalidates the pre-mutation page.

Docs: design-doc terminal enumeration (+reload), keep-row exemption + end-state
delta, read-side strip rule; feature-file-map (+action-fence).