@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

package/skills/view-transitions/SKILL.md

@@ -6,11 +6,33 @@ argument-hint: [layout|route|parallel|intercept]
 
 # View Transitions
 
-Rango wires React's experimental `<ViewTransition>` into the segment tree via the `transition()` helper. Each segment can declare its own transition config; rango wraps it at the right tree position so navigations morph the right pieces and modals do not.
+`transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
-> Requires React experimental (the build that exports `<ViewTransition>` and `addTransitionType`). With stable React, `transition()` is a no-op — your routes still render, just without view-transition wrappers.
+1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions.
+2. **`<ViewTransition>` (the animation, layered on top).** On experimental React, rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs experimental React; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
-## What `transition()` does
+> The `<ViewTransition>` layer requires React experimental (the build that exports `<ViewTransition>` / `addTransitionType`). On stable React that layer is a no-op — but the `startTransition` driving (content hold) still applies.
+
+## Purpose: `startTransition` vs `<ViewTransition>`
+
+These are two **independent** mechanisms. `startTransition` controls _fallbacks_ (hold the old content vs. flash the Suspense skeleton) and is what lets a view transition fire at all; the `<ViewTransition>` boundary is the _visual cross-fade_.
+
+|                            | `startTransition` **OFF**                                                      | `startTransition` **ON**                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| **`<ViewTransition>` OFF** | plain nav — remount on param change, skeleton flash, no animation              | **hold** content (no skeleton flash); a consumer-placed `<ViewTransition>` still morphs; no router cross-fade |
+| **`<ViewTransition>` ON**  | **impossible** — React never activates `<ViewTransition>` outside a Transition | hold + router cross-fade                                                                                      |
+
+The bottom-left cell is the key constraint: a view transition cannot exist without a `startTransition`. So once you reach for `transition()`, the only real choice is _startTransition_ vs _startTransition + ViewTransition_:
+
+| What you want                          | Config                                              | Effect                                                                                                 |
+| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| nothing (default nav)                  | no `transition()`                                   | remount + skeleton on param change                                                                     |
+| `startTransition` only                 | `transition({ viewTransition: false })`             | hold content; place your own `<ViewTransition>` where you want it                                      |
+| `startTransition` + `<ViewTransition>` | `transition({})` / `transition({ enter, exit, … })` | hold + router cross-fade (experimental React; on stable it degrades to the `startTransition`-only row) |
+
+`createRouter({ viewTransition: "auto" \| false })` sets the app-wide default for the third row; a per-segment `viewTransition` wins. See [Opting out of the router boundary](#opting-out-of-the-router-boundary-place-your-own-viewtransition) for the full opt-out story.
+
+## What `transition()` does (wrap location)
 
 `transition(config)` attaches a [`TransitionConfig`](#transitionconfig) to the surrounding entry. Where the wrap actually lands in the rendered React tree depends on the segment type:
 
@@ -186,12 +208,72 @@ interface TransitionConfig {
   share?: string | Record<string, string>;
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
+  viewTransition?: "auto" | false; // boundary opt-out (see below)
 }
 ```
 
 - `default` is the catch-all if a phase-specific prop is unset.
 - The object form keys are React transition types tagged by rango: `"navigation"` (forward navigations), `"navigation-back"` (popstate cache restores), and `"action"` (partial-update action/refetch paths only — see the caveat in "Direction-aware transitions").
 - `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
+- `viewTransition` toggles whether rango places its own `<ViewTransition>` boundary. `"auto"` (default) wraps as described above; `false` opts out — see the next section.
+
+## Opting out of the router boundary (place your own `<ViewTransition>`)
+
+By default a `transition()` segment gets a rango-placed `<ViewTransition>` boundary — a cross-fade of the whole outlet/route. If you'd rather animate specific elements yourself (place `<ViewTransition name="...">` in your components), set `viewTransition: false`. The router then contributes **no boundary of its own** but still:
+
+- drives the navigation commit through `startTransition` (so React runs `document.startViewTransition`, and your own `<ViewTransition>` elements animate on navigation — driving is what they need, not a router boundary), and
+- holds same-route content (stale-while-revalidate; no skeleton flash).
+
+```tsx
+// Router drives the transition + holds content, but places NO cross-fade.
+// Only your <ViewTransition name="hero"> morphs.
+urls(({ path, transition }) => [
+  path("/product/:id", ProductPage, { name: "product" }, () => [
+    transition({ viewTransition: false }),
+  ]),
+]);
+
+// ProductPage renders the boundary itself, exactly where it's wanted:
+function ProductPage() {
+  return (
+    <ViewTransition name="hero">
+      <img src={cover} />
+    </ViewTransition>
+  );
+}
+```
+
+This is the rango analogue of the "router triggers, you place the names" model used by React Router / TanStack: rango guarantees navigations run inside a React transition; you own the boundaries.
+
+**App-wide default.** Flip the default for every `transition()` segment at the router level. A per-segment `viewTransition` still overrides it.
+
+```ts
+const router = createRouter<AppEnv>({ viewTransition: false });
+// Now `transition({})` drives + holds but places no boundary anywhere.
+// Re-enable a router boundary on one route with transition({ viewTransition: "auto" }).
+```
+
+**Precedence (per-route vs router default).** A bare `transition({})` has no per-route `viewTransition`, so it inherits the router default (`"auto"` unless `createRouter({ viewTransition: false })`). An explicit per-route value always wins. The `viewTransition` flag only toggles the boundary — `startTransition` driving and content-hold are on in every row below (they key off `transition()` presence, not this flag):
+
+| per-route (`transition(...)`)            | router (`createRouter`) | resolved boundary        | result      |
+| ---------------------------------------- | ----------------------- | ------------------------ | ----------- |
+| `transition({})` (unset)                 | `"auto"` (default)      | wrap                     | **ST + VT** |
+| `transition({})` (unset)                 | `false`                 | no wrap                  | **ST only** |
+| `transition({ viewTransition: "auto" })` | `"auto"`                | wrap                     | ST + VT     |
+| `transition({ viewTransition: "auto" })` | `false`                 | wrap (per-route wins)    | **ST + VT** |
+| `transition({ viewTransition: false })`  | `"auto"`                | no wrap (per-route wins) | **ST only** |
+| `transition({ viewTransition: false })`  | `false`                 | no wrap                  | ST only     |
+
+On stable React the "VT" column is always a no-op (there is no `<ViewTransition>`), so every row collapses to its `startTransition`-only behavior there.
+
+| Config                                               | Router boundary  | startTransition driving (no skeleton flash) | Your own `<ViewTransition name>`   |
+| ---------------------------------------------------- | ---------------- | ------------------------------------------- | ---------------------------------- |
+| no `transition()`                                    | —                | no                                          | does not fire on nav               |
+| `transition({})` / `{ viewTransition: "auto" }`      | yes (cross-fade) | yes                                         | fires, under the router cross-fade |
+| `transition({ viewTransition: false })`              | none             | yes                                         | fires alone                        |
+| global `viewTransition: false`, route `transition()` | none             | yes                                         | fires alone                        |
+
+> On **stable** React there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
 ## Recommendations
 

package/src/__augment-tests__/augment.ts

@@ -0,0 +1,81 @@
+/**
+ * Simulates a consumer augmenting the Rango global namespace, the way a real
+ * app does in router.tsx (Env/Vars) and via the generated router.named-routes.gen.ts
+ * (GeneratedRouteMap).
+ *
+ * This file is compiled ONLY by tsconfig.augment-check.json and is excluded from
+ * the main program, so the global augmentation here does not leak into the rest
+ * of the type tests, which assert the UNAUGMENTED fallbacks
+ * (see src/__tests__/augmentation-fallback-types.test.ts).
+ */
+
+export interface TestBindings {
+  DB: { query: (sql: string) => string };
+  SECRET: string;
+}
+
+export interface TestVars {
+  user?: { id: string; role: "admin" | "user" };
+  requestId?: string;
+}
+
+/**
+ * A userland domain type that controls its own JSON wire shape via `toJSON()`.
+ * This is the augmentation hook: `Rango.JsonSerialize` honors `toJSON()`, so a
+ * consumer adjusts how their type serializes with no registry API.
+ */
+export class Money {
+  constructor(public cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+
+/**
+ * Mirrors `typeof router.routeMap`: the same routes as the generated map, plus a
+ * response route whose payload carries a userland class (`Money`, with
+ * `toJSON()`) and a `Date` — used to assert `Rango.PathResponse` reports the
+ * serialized JSON wire shape.
+ */
+export interface TestRegisteredRoutes {
+  readonly home: "/";
+  readonly "blog.post": "/blog/:slug";
+  readonly search: {
+    readonly path: "/search";
+    readonly search: { readonly q: "string"; readonly page: "number?" };
+  };
+  readonly order: {
+    readonly path: "/orders/:id";
+    readonly response: { id: string; total: Money; placedAt: Date };
+  };
+}
+
+declare global {
+  namespace Rango {
+    interface Env extends TestBindings {}
+    interface Vars extends TestVars {}
+    interface RegisteredRoutes extends TestRegisteredRoutes {}
+    // Mirrors the shape emitted into router.named-routes.gen.ts: plain string
+    // patterns, plus { path, search } objects for routes with a search schema.
+    interface GeneratedRouteMap {
+      readonly home: "/";
+      readonly "blog.post": "/blog/:slug";
+      readonly search: {
+        readonly path: "/search";
+        readonly search: { readonly q: "string"; readonly page: "number?" };
+      };
+    }
+
+    // Userland serialization overrides: full-transform replacement that
+    // special-cases one type and delegates the rest to the built-in. Isolated to
+    // this augment-check program, so the main suite's built-in behavior (e.g.
+    // JsonSerialize<bigint> = never) is unaffected — demonstrating overrides are
+    // per-project augmentation.
+    interface JsonSerializeOverride<T> {
+      app: T extends bigint ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
+  }
+}

package/src/__augment-tests__/augmented.check.ts

@@ -0,0 +1,116 @@
+/**
+ * Compile-only assertions for the AUGMENTED Rango namespace.
+ *
+ * Pins the type-safety contract a consumer gets after augmenting Env, Vars, and
+ * GeneratedRouteMap. A regression in the fallback chains (global-namespace.ts)
+ * turns these into tsc errors. Run via tsconfig.augment-check.json.
+ */
+import "./augment.js";
+import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
+import type { DefaultRouteName } from "../types/global-namespace.js";
+import { href } from "../href-client.js";
+import type { Money, TestBindings } from "./augment.js";
+
+type Expect<T extends true> = T;
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+
+// Env: ctx.env resolves to the augmented bindings, not `unknown`/`any`.
+const envHandler: Handler<"home"> = (ctx) => {
+  type _envIsBindings = Expect<Equal<typeof ctx.env, TestBindings>>;
+  ctx.env.DB.query("select 1");
+  // @ts-expect-error - unknown binding is rejected once Env is augmented
+  ctx.env.MISSING();
+  return null;
+};
+void envHandler;
+
+// Vars: ctx.get is keyed by the augmented Vars.
+const varsHandler: Handler<"home"> = (ctx) => {
+  const user = ctx.get("user");
+  type _userTyped = Expect<
+    Equal<typeof user, { id: string; role: "admin" | "user" } | undefined>
+  >;
+  // @ts-expect-error - unknown var key is rejected once Vars is augmented
+  ctx.get("nope");
+  return null;
+};
+void varsHandler;
+
+// routeName narrows to the generated route names.
+type _routeName = Expect<
+  Equal<DefaultRouteName, "home" | "blog.post" | "search">
+>;
+
+// RouteParams / RouteSearchParams resolve from the generated map with no
+// explicit route map argument.
+type _params = Expect<Equal<RouteParams<"blog.post">, { slug: string }>>;
+type _search = Expect<
+  Equal<RouteSearchParams<"search">, { q: string | undefined; page?: number }>
+>;
+
+// href / Rango.Path read GeneratedRouteMap even without a manual RegisteredRoutes
+// augmentation — this is the core of the "rango generate alone enables typed
+// href()" guarantee. The paths below come from the generated map in augment.ts.
+href("/");
+href("/blog/anything");
+href("/search");
+// @ts-expect-error - path is not in the generated route map
+href("/not-a-route");
+
+// Rango.Path is the ambient input type for wrapper functions around href().
+// No import needed — it reads the same generated map href() does.
+function wrappedHref(path: Rango.Path): string {
+  return href(path);
+}
+const arrowHref = (path: Rango.Path): string => href(path);
+
+wrappedHref("/blog/anything");
+arrowHref("/search?q=hello");
+// @ts-expect-error - wrapper preserves the same generated-map validation
+wrappedHref("/not-a-route");
+
+// Userland serialization augmentation: a consumer's custom class adjusts its JSON
+// wire shape via toJSON(), and Rango.PathResponse reports the serialized payload
+// (Money -> number, Date -> string) — both by pattern and by concrete path.
+type _orderWireByPattern = Expect<
+  Equal<
+    Rango.PathResponse<"/orders/:id">,
+    { id: string; total: number; placedAt: string }
+  >
+>;
+type _orderWireByPath = Expect<
+  Equal<
+    Rango.PathResponse<"/orders/42">,
+    { id: string; total: number; placedAt: string }
+  >
+>;
+
+// Project serialization overrides: the consumer augments JsonSerializeOverride /
+// FlightSerializeOverride (see augment.ts) with a full transform that delegates to
+// the built-in, and the transforms honor it — winning over the built-in rules.
+// bigint normally JSON-serializes to `never`; Money is a class React Flight would
+// otherwise reject structurally. Delegation keeps every other type (incl. the
+// /orders payload above) on the built-in behavior.
+type _jsonOverride = Expect<Equal<Rango.JsonSerialize<bigint>, string>>;
+type _jsonOverrideNested = Expect<
+  Equal<
+    Rango.JsonSerialize<{ id: bigint; name: string }>,
+    { id: string; name: string }
+  >
+>;
+type _flightOverride = Expect<Equal<Rango.FlightSerialize<Money>, number>>;
+
+// Reference the top-level assertion aliases so they are unambiguously evaluated.
+export type _Assertions = [
+  _routeName,
+  _params,
+  _search,
+  _orderWireByPattern,
+  _orderWireByPath,
+  _jsonOverride,
+  _jsonOverrideNested,
+  _flightOverride,
+];

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

@@ -1,9 +1,21 @@
-import {
-  classifyActionResponse,
-  type ActionScenario,
-} from "./action-response-classifier.js";
 import type { ActionEntry } from "./event-controller.js";
 
+/**
+ * Post-reconciliation action outcome (discriminated union). Error and
+ * full-update-unsupported cases are handled inline in the bridge before
+ * reconciliation; this only covers successfully-reconciled partial responses.
+ */
+type ActionScenario =
+  | {
+      type: "navigated-away";
+      historyKeyChanged: boolean;
+      onInterceptRoute: boolean;
+    }
+  | { type: "hmr-missing" }
+  | { type: "consolidation-needed"; segmentIds: string[] }
+  | { type: "concurrent-skip"; otherFetchingCount: number }
+  | { type: "normal" };
+
 /**
  * Plain data inputs for classifying a post-reconciliation action outcome.
  * No browser objects or controller references — all values are snapshots.
@@ -33,20 +45,15 @@ export interface ActionOutcomeInput {
   currentInterceptSource: string | null;
 }
 
-/**
- * Compute consolidation segments from concurrent action state.
- *
- * Returns segment IDs that need re-fetching when concurrent actions
- * have each revalidated different parts of the tree, or null if
- * consolidation is not needed.
- */
+// Segment IDs to re-fetch when concurrent actions each revalidated different
+// parts of the tree; null when consolidation does not apply. Returns null while
+// any action is still fetching — consolidation must wait for all to land.
 function computeConsolidationSegments(
   input: ActionOutcomeInput,
 ): string[] | null {
   if (!input.hadAnyConcurrentActions) return null;
   if (input.revalidatedSegments.size === 0) return null;
 
-  // Can't consolidate while any action is still waiting for a server response
   const stillFetchingCount = [...input.inflightActions.values()].filter(
     (a) => a.phase === "fetching",
   ).length;
@@ -55,9 +62,6 @@ function computeConsolidationSegments(
   return Array.from(input.revalidatedSegments);
 }
 
-/**
- * Count other actions still in "fetching" phase (excluding this handle).
- */
 function countOtherFetchingActions(input: ActionOutcomeInput): number {
   let count = 0;
   for (const [, a] of input.inflightActions) {
@@ -69,29 +73,42 @@ function countOtherFetchingActions(input: ActionOutcomeInput): number {
 }
 
 /**
- * Classify a post-reconciliation action outcome into one of 5 scenarios.
- *
- * This is the single entry point for post-action decision logic.
- * It gathers consolidation and concurrency data from the plain inputs,
- * then delegates to the pure classifyActionResponse function.
- *
- * The server-action-bridge calls this after reconciliation to decide
- * whether to render, skip, consolidate, or refetch.
+ * Classify a post-reconciliation action outcome. Ordered priority chain: each
+ * case assumes the earlier ones are false (e.g. concurrent-skip only applies on
+ * the still-current route, consolidation only once no action is still fetching).
+ * The bridge calls this to decide whether to render, skip, consolidate, or refetch.
  */
 export function classifyActionOutcome(
   input: ActionOutcomeInput,
 ): ActionScenario {
-  return classifyActionResponse({
-    actionStartPathname: input.actionStartPathname,
-    currentPathname: input.currentPathname,
-    actionStartLocationKey: input.actionStartLocationKey,
-    currentLocationKey: input.currentLocationKey,
-    reconciledSegmentCount: input.reconciledSegmentCount,
-    matchedCount: input.matchedCount,
-    currentInterceptSource: input.currentInterceptSource,
-    consolidationSegments: computeConsolidationSegments(input),
-    otherFetchingActionCount: countOtherFetchingActions(input),
-  });
-}
+  if (
+    input.currentPathname !== input.actionStartPathname ||
+    input.currentLocationKey !== input.actionStartLocationKey
+  ) {
+    return {
+      type: "navigated-away",
+      historyKeyChanged:
+        input.currentLocationKey !== input.actionStartLocationKey,
+      onInterceptRoute: input.currentInterceptSource !== null,
+    };
+  }
+
+  if (input.reconciledSegmentCount < input.matchedCount) {
+    return { type: "hmr-missing" };
+  }
+
+  const consolidationSegments = computeConsolidationSegments(input);
+  if (consolidationSegments && consolidationSegments.length > 0) {
+    return { type: "consolidation-needed", segmentIds: consolidationSegments };
+  }
+
+  const otherFetchingActionCount = countOtherFetchingActions(input);
+  if (otherFetchingActionCount > 0) {
+    return {
+      type: "concurrent-skip",
+      otherFetchingCount: otherFetchingActionCount,
+    };
+  }
 
-export type { ActionScenario };
+  return { type: "normal" };
+}

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;
+}