@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/skills/prerender/SKILL.md

@@ -11,6 +11,9 @@ deserialization path, same segment system. The worker handles every request --
 there are NO static .html or .rsc files served from assets. The worker reads
 pre-computed Flight payloads instead of executing handler code.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## API: Prerender
 
 ### Static Route (no params)
@@ -69,13 +72,14 @@ export const ProductPage = Prerender(
 
 Controls whether the handler stays in the RSC server bundle after build:
 
-|                | `passthrough: false` (default)          | `passthrough: true`                     |
-| -------------- | --------------------------------------- | --------------------------------------- |
-| Known params   | Served from pre-rendered Flight payload | Served from pre-rendered Flight payload |
-| Unknown params | Handler evicted, no live fallback       | Handler runs live at request time       |
-| Bundle size    | Handler code + imports removed          | Handler code kept in RSC bundle         |
-| `revalidate()` | Not allowed (handler gone)              | Allowed (handler can re-render)         |
-| `loading()`    | Ignored (segments fully resolved)       | Works for live fallback renders         |
+|                     | `passthrough: false` (default)          | `passthrough: true`                     |
+| ------------------- | --------------------------------------- | --------------------------------------- |
+| Known params        | Served from pre-rendered Flight payload | Served from pre-rendered Flight payload |
+| Unknown params      | Handler evicted, no live fallback       | Handler runs live at request time       |
+| `ctx.passthrough()` | Throws (not allowed)                    | Skips artifact, defers to live fallback |
+| Bundle size         | Handler code + imports removed          | Handler code kept in RSC bundle         |
+| `revalidate()`      | Not allowed (handler gone)              | Allowed (handler can re-render)         |
+| `loading()`         | Ignored (segments fully resolved)       | Works for live fallback renders         |
 
 ### When to use passthrough
 
@@ -98,6 +102,7 @@ Handlers receive `BuildContext` at build time, a subset of the runtime `HandlerC
 ```typescript
 interface BuildContext<TParams> {
   params: TParams; // From getParams
+  build: true; // Always true at build time
   use: <T>(handle: Handle<T>) => (data: T) => void; // Push handle data
   url: URL; // Synthetic URL from pattern + params
   pathname: string; // Pathname from synthetic URL
@@ -105,6 +110,12 @@ interface BuildContext<TParams> {
   set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
   get(key: string): any; // Read context variable (string key)
   get<T>(contextVar: ContextVar<T>): T | undefined; // Read typed context variable
+  reverse(
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ): string; // URL generation
+  passthrough(): PrerenderPassthroughResult; // Skip local artifact (passthrough routes only)
   // NOT available: req, headers, cookies, env (throws descriptive errors)
 }
 ```
@@ -130,6 +141,16 @@ All items inside the path's use() callback (child layouts, parallels) also recei
 `BuildContext` during pre-rendering. Loaders are the exception -- they run at
 request time with full server context.
 
+This is one reason prerender is a good fit for handler-first composition:
+the handler and its child layouts/parallels participate in the same full
+render pass, so data set with `ctx.set()` is available downstream via
+`ctx.get()`.
+
+At runtime, partial action revalidation follows a narrower rule: only
+revalidated segments are recomputed. If a child segment depends on data
+established by an outer handler/layout, that outer segment must also be
+revalidated, or the child must load/guard the data independently.
+
 ## Supported Export Patterns
 
 All of the following are equivalent and fully supported by the Vite transform:
@@ -218,11 +239,25 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 | `loading()`    | Ignored without passthrough. Works for live fallback with passthrough.                                                                                                                                                                                              |
 | `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when()` conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
+When passthrough revalidation is enabled, remember that revalidation is
+still partial: opting a child segment into revalidation does not
+implicitly re-run outer prerender-derived handlers/layouts.
+
 ## Dev Mode
 
-In dev mode, `Prerender` is a normal handler. Routes render live
-on every request. No stubbing, no build-time pre-rendering. The handler runs
-with full runtime context (not BuildContext).
+In dev mode there is no production-style prerender build pass and no handler
+stubbing.
+
+**Node.js dev server** — `Prerender` acts as a normal handler. Routes render
+live on every request with full runtime context (`ctx.build === false`).
+
+**Non-Node runtimes (Cloudflare workerd, Deno workers)** — Handlers that
+depend on Node APIs (e.g. `node:fs`) cannot run in-process. The Vite plugin
+can intercept these requests and resolve them via the `/__rsc_prerender`
+endpoint, which runs `matchForPrerender` in a Node.js temp server. In this
+path the handler receives `BuildContext` (`ctx.build === true`) and segments
+are resolved identically to production prerendering, then served on-demand.
+This only applies when `__PRERENDER_DEV_URL` is set by the plugin.
 
 ## Storage Layout
 
@@ -288,8 +323,10 @@ export const TocSidebar = Static(() => {
 
 ### Error behavior at build time
 
-| Throw type                  | Effect                                                |
+| Handler outcome             | Effect                                                |
 | --------------------------- | ----------------------------------------------------- |
+| JSX / `null`                | Normal prerender entry, log OK                        |
+| `return ctx.passthrough()`  | Skip entry, log PASS, continue (passthrough routes)   |
 | `throw new Skip("reason")`  | Skip entry, log SKIP, continue with remaining entries |
 | `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail the build      |
 
@@ -303,21 +340,108 @@ The build produces per-URL timing logs:
 ```
 [rsc-router] Pre-rendering 12 URL(s) (concurrency: 4)...
 [rsc-router]   OK   /articles/hello            (42ms)
+[rsc-router]   PASS /articles/remote-only      (5ms) - live fallback
 [rsc-router]   SKIP /articles/draft-post       (3ms) - Article is a draft
-[rsc-router]   FAIL /articles/broken           (15ms) - DB connection refused
-[rsc-router] Pre-render complete: 10 ok, 1 skipped, 1 failed (1204ms total)
+[rsc-router] Pre-render complete: 11 done, 1 skipped (1204ms total)
 
 [rsc-router] Rendering 3 static handler(s)...
 [rsc-router]   OK   DocsLayout                 (28ms)
 [rsc-router]   SKIP TocSidebar                 (1ms) - Not ready
-[rsc-router] Static render complete: 2 ok, 1 skipped (120ms total)
+[rsc-router] Static render complete: 2 done, 1 skipped (120ms total)
 ```
 
+A `FAIL` line is logged per-URL when a handler throws a non-Skip error. The
+error is re-thrown immediately, so no summary line is printed — the build
+stops at the first failure.
+
 ### Dev mode behavior
 
-In dev mode, `Skip` is a regular Error. Throwing it in a handler will surface
-as a runtime error (no build-time skip logic exists in dev). This matches the
-general dev-mode principle where Prerender handlers run live per request.
+**Node.js dev server** — `Skip` behaves like a regular runtime error because
+the handler runs live with `ctx.build === false`.
+
+**Non-Node runtimes using `/__rsc_prerender`** — `Skip` participates in the
+on-demand prerender path, so build-style skip logic does run for that request.
+The dev prerender endpoint treats it like a prerender miss and the request
+falls back according to normal dev/runtime behavior.
+
+## Per-Param Passthrough with ctx.passthrough()
+
+On `{ passthrough: true }` routes, a handler can return `ctx.passthrough()`
+to skip writing a local prerender artifact for a specific param set. At
+runtime, the missing entry falls through to the live handler.
+
+```typescript
+export const BlogPost = Prerender(
+  async () => [{ slug: "a" }, { slug: "b" }, { slug: "c" }],
+  async (ctx) => {
+    const post = await getPost(ctx.params.slug);
+    if (!post) return ctx.passthrough();
+    return <article>{post.content}</article>;
+  },
+  { passthrough: true },
+);
+```
+
+### Semantics
+
+- JSX or `null` from the handler produces a normal prerender entry.
+- `ctx.passthrough()` returns a sentinel that signals "no local artifact".
+  The build skips the manifest entry for that param set.
+- `ctx.passthrough()` on a non-passthrough route throws an invariant error.
+- `ctx.passthrough()` at runtime (`ctx.build === false`) also throws.
+  It is a build-time-only control flow.
+- `getParams()` still enumerates the param set; the handler decides per-param
+  whether to produce an artifact or defer to runtime.
+
+### Difference from Skip
+
+| Mechanism           | Effect on build        | Runtime behavior                                     |
+| ------------------- | ---------------------- | ---------------------------------------------------- |
+| `throw new Skip()`  | Skips entry, logs SKIP | No artifact, no live fallback unless passthrough     |
+| `ctx.passthrough()` | Skips entry, logs PASS | Always defers to live handler (requires passthrough) |
+
+Use `ctx.passthrough()` when you want the handler to run live at request time
+for specific params. Use `Skip` when you want to exclude params entirely.
+
+### Use case: Remote storage
+
+`ctx.passthrough()` enables a pattern where build-time data is stored in a
+remote KV store instead of the local prerender manifest. The handler
+pre-computes data during `getParams`, pushes it to KV, then calls
+`ctx.passthrough()` so the local build skips the artifact. At runtime,
+the live handler reads from KV:
+
+```typescript
+export const Product = Prerender(
+  async () => {
+    const products = await db.getFeaturedProducts();
+    // Pre-compute and store in remote KV during build
+    for (const p of products) {
+      await kv.put(`product:${p.id}`, await renderProduct(p));
+    }
+    return products.map(p => ({ id: p.id }));
+  },
+  async (ctx) => {
+    // At build time: skip local artifact, data is in KV
+    if (ctx.build) return ctx.passthrough();
+    // At runtime: read from KV
+    const cached = await kv.get(`product:${ctx.params.id}`);
+    if (cached) return cached;
+    return <Product data={await db.getProduct(ctx.params.id)} />;
+  },
+  { passthrough: true },
+);
+```
+
+### Build logs
+
+Passthrough entries are logged distinctly:
+
+```
+[rsc-router]   OK   /blog/a                          (42ms)
+[rsc-router]   PASS /blog/b                          (3ms) - live fallback
+[rsc-router]   OK   /blog/c                          (38ms)
+```
 
 ## Edge Cases and Constraints
 
@@ -471,3 +595,49 @@ At runtime, the cache-lookup middleware uses these flags:
 - `pr + hit` -- serve pre-rendered Flight payload
 - `pr + pt + miss` -- fall through to live handler (handler kept in bundle)
 - `pr + miss` (no pt) -- fall through (handler stubbed, no live render)
+
+## Contributor Checklist
+
+Before changing prerender behavior, read these docs and run these tests.
+
+### Docs to re-read
+
+- [Prerender API design](../../docs/prerender-api-design.md) -- canonical
+  architecture: build-time flow, runtime flow, storage, passthrough, intercept
+- [Execution model](../../docs/internal/execution-model.md) -- handler-first
+  ordering, middleware scope, context visibility rules
+- [Semantic change checklist](../../docs/internal/semantic-change-checklist.md)
+  -- gate for any change to execution semantics
+
+### Tests to run
+
+```bash
+# Core prerender e2e (passthrough, eviction, loaders, sub-use, intercept)
+pnpm --filter @rangojs/router exec playwright test prerender
+
+# Prerender-specific unit test
+pnpm --filter @rangojs/router run test:unit -- prerender-passthrough
+
+# Semantic matrix (prerender rows cover intercept + ctx propagation)
+pnpm --filter @rangojs/router exec playwright test semantic-matrix
+
+# Handler-first (ctx.set/get visibility with prerender handlers)
+pnpm --filter @rangojs/router exec playwright test handler-first
+```
+
+### Dev-only vs build-parity
+
+- Prerender e2e tests run against a real production build by default (the
+  fixture builds the test app). Dev-mode prerender behavior is tested via
+  `/__rsc_prerender` endpoint tests and node.js dev-server fallback.
+- Log-based assertions (build output lines, debug cache logs) are inherently
+  dev/build-only and do not need a production counterpart.
+- Behavioral assertions (rendered content, loader freshness, passthrough
+  fallback, intercept variant selection) must work in the production build.
+
+## Maintenance References
+
+- [Stability next steps plan](../../docs/internal/stability-next-steps-plan.md)
+  -- completed parity and cleanup pass (reference for decisions made)
+- [Test quality baseline](../../docs/internal/test-quality-baseline.md) --
+  measured test inventory, sleep debt, production coverage gaps

package/skills/route/SKILL.md

@@ -181,6 +181,47 @@ String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
 Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
 and intercepts can only read via `ctx.get()`.
 
+### Revalidation Contracts for Handler Data
+
+Handler-first guarantees apply within a single full render pass. For partial
+action revalidation, define named revalidation contracts and reuse them on both
+the producer route and the consumer child segments.
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCheckoutData = ({ actionId }) =>
+  actionId?.includes("src/actions/checkout.ts#") ?? false;
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidate(revalidateCheckoutData), // producer (route handler) reruns
+  layout(CheckoutLayout, () => [
+    revalidate(revalidateCheckoutData), // consumer reruns
+    parallel({ "@summary": CheckoutSummary }, () => [
+      revalidate(revalidateCheckoutData),
+    ]),
+  ]),
+]);
+```
+
+If children depend on multiple upstream domains, compose multiple contracts on
+the same segment (`revalidateAuthData`, `revalidateCheckoutData`, and so on).
+
+For cleaner route trees, expose contract helpers and spread them:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCheckout = () => [revalidate(revalidateCheckoutData)];
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidateCheckout(),
+  layout(CheckoutLayout, () => [revalidateCheckout()]),
+]);
+```
+
+For scope/revalidation guarantees and non-guarantees, see:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Redirects
 
 ### Basic redirect
@@ -242,7 +283,7 @@ Attach location state to any server response (not just redirects):
 
 ```typescript
 path("/dashboard", (ctx) => {
-  ctx.setLocationState([ServerInfo({ data: "welcome" })]);
+  ctx.setLocationState(ServerInfo({ data: "welcome" }));
   return <Dashboard />;
 }, { name: "dashboard" })
 ```

package/skills/router-setup/SKILL.md

@@ -99,6 +99,12 @@ interface RSCRouterOptions<TEnv> {
   // Theme configuration
   theme?: ThemeConfig | true;
 
+  // SSR options (streaming policy)
+  ssr?: SSROptions<TEnv>;
+
+  // Telemetry sink for structured lifecycle events
+  telemetry?: TelemetrySink;
+
   // Connection warmup (default: true)
   warmup?: boolean;
 
@@ -355,3 +361,74 @@ const router = createRouter({
 
 The warmup request is relative to the current page path, so it works correctly
 with subpath deployments (reverse proxy, base path).
+
+## Telemetry
+
+The router emits structured lifecycle events through a pluggable telemetry sink.
+Zero overhead when not configured.
+
+```typescript
+// Console sink for development
+import { createRouter, createConsoleSink } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
+```
+
+```typescript
+// OpenTelemetry for production
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
+
+```typescript
+// Custom sink
+const router = createRouter({
+  telemetry: {
+    emit(event) {
+      // Send to any observability backend
+      myTracer.record(event);
+    },
+  },
+});
+```
+
+Events emitted: `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, `revalidation.decision`.
+
+## SSR Streaming Policy
+
+Control whether HTML SSR responses stream progressively or wait for all content:
+
+```typescript
+import { createRouter, type SSRStreamMode } from "@rangojs/router";
+
+const router = createRouter({
+  ssr: {
+    resolveStreaming: ({ request }) => {
+      const ua = request.headers.get("user-agent") ?? "";
+      // Bots that can't process streamed HTML get a fully resolved page
+      if (/Googlebot|bingbot/i.test(ua)) return "allReady";
+      return "stream";
+    },
+  },
+});
+```
+
+`SSRStreamMode` is `"stream" | "allReady"`:
+
+- `"stream"` (default) — flush HTML as React renders. Suspense fallbacks appear first, then resolved content streams in. Best for real users (fastest TTFB).
+- `"allReady"` — await `stream.allReady` before flushing. The full page arrives in one shot. Use for bots that cannot execute JavaScript or process chunked HTML.
+
+The resolver receives `{ request, env, url }` and may be sync or async. It only runs on HTML SSR paths — RSC partials, `__rsc` requests, and response routes are unaffected.
+
+When `resolveStreaming` is not configured, the default is `"stream"`.

package/src/__internal.ts

@@ -160,7 +160,7 @@ export type {
 /**
  * @internal
  * Internal handler context with additional props for router internals.
- * Includes `_originalRequest` and `_currentSegmentId`.
+ * Includes `_currentSegmentId` and `_responseType`.
  */
 export type { InternalHandlerContext } from "./types.js";
 

package/src/bin/rango.ts

@@ -5,6 +5,7 @@ import {
   writePerModuleRouteTypesForFile,
   writeCombinedRouteTypes,
   detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
   type UnresolvableInclude,
 } from "../build/generate-route-types.ts";
 
@@ -131,22 +132,18 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     process.exit(0);
   }
 
+  // Phase 1: Classify files
   const routerFiles: string[] = [];
+  const urlsFiles: string[] = [];
 
   for (const filePath of files) {
     try {
       const source = readFileSync(filePath, "utf-8");
-
-      // Detect file type and generate accordingly
-      const isRouter = /\bcreateRouter\s*[<(]/.test(source);
-      const isUrls = source.includes("urls(");
-
-      if (isRouter) {
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerFiles.push(filePath);
       }
-
-      if (isUrls) {
-        writePerModuleRouteTypesForFile(filePath);
+      if (source.includes("urls(")) {
+        urlsFiles.push(filePath);
       }
     } catch (err) {
       console.warn(
@@ -155,9 +152,10 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     }
   }
 
-  // Check for unresolvable includes across all router files
+  // Phase 2: Collect diagnostics from all files BEFORE writing anything
   const allDiagnostics: Array<UnresolvableInclude & { routerFile: string }> =
     [];
+
   for (const routerFile of routerFiles) {
     const diagnostics = detectUnresolvableIncludes(routerFile);
     for (const d of diagnostics) {
@@ -165,10 +163,29 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     }
   }
 
-  if (allDiagnostics.length > 0 && mode === "default") {
-    // Hard error: unresolvable includes detected
+  // Also check standalone urls files not covered by router-level detection
+  const routerFileSet = new Set(routerFiles);
+  for (const urlsFile of urlsFiles) {
+    if (routerFileSet.has(urlsFile)) continue;
+    const diagnostics = detectUnresolvableIncludesForUrlsFile(urlsFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile: urlsFile });
+    }
+  }
+
+  // Deduplicate diagnostics (router and urls detection may find the same issue)
+  const seen = new Set<string>();
+  const uniqueDiagnostics = allDiagnostics.filter((d) => {
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  if (uniqueDiagnostics.length > 0 && mode === "default") {
+    // Hard error: no files written
     console.error("\n[rango] Unresolvable includes detected:\n");
-    formatDiagnostics(allDiagnostics);
+    formatDiagnostics(uniqueDiagnostics);
     console.error(
       "\nThe static parser cannot resolve these includes because they use " +
         "factory functions or dynamic expressions.\n\n" +
@@ -179,16 +196,20 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     process.exit(1);
   }
 
-  if (allDiagnostics.length > 0 && mode === "static") {
+  if (uniqueDiagnostics.length > 0 && mode === "static") {
     // Warning: partial output accepted
     console.warn(
       "\n[rango] Warning: partial output (unresolvable includes):\n",
     );
-    formatDiagnostics(allDiagnostics);
+    formatDiagnostics(uniqueDiagnostics);
     console.warn("");
   }
 
-  // Generate named-routes for any detected router files
+  // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
+  for (const urlsFile of urlsFiles) {
+    writePerModuleRouteTypesForFile(urlsFile);
+  }
+
   for (const routerFile of routerFiles) {
     const projectRoot = findProjectRoot(routerFile);
     writeCombinedRouteTypes(projectRoot, [routerFile]);
@@ -257,10 +278,8 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
-  // Use a single project root for all routers (find from the first entry)
-  const projectRoot = findProjectRoot(routerEntries[0]);
-
   for (const entry of routerEntries) {
+    const projectRoot = findProjectRoot(entry);
     const result = await discoverAndWriteRouteTypes({
       root: projectRoot,
       configFile,

package/src/browser/action-coordinator.ts

@@ -0,0 +1,97 @@
+import {
+  classifyActionResponse,
+  type ActionScenario,
+} from "./action-response-classifier.js";
+import type { ActionEntry } from "./event-controller.js";
+
+/**
+ * Plain data inputs for classifying a post-reconciliation action outcome.
+ * No browser objects or controller references — all values are snapshots.
+ */
+export interface ActionOutcomeInput {
+  /** This action's unique instance ID */
+  handleId: string;
+  /** All in-flight action entries (snapshot from event controller) */
+  inflightActions: Map<string, ActionEntry>;
+  /** Whether any concurrent actions occurred (controller-level shared flag) */
+  hadAnyConcurrentActions: boolean;
+  /** Segments revalidated by concurrent actions (from tracking set) */
+  revalidatedSegments: Set<string>;
+  /** window.location.pathname captured at action start */
+  actionStartPathname: string;
+  /** window.location.pathname at classification time */
+  currentPathname: string;
+  /** window.history.state?.key captured at action start */
+  actionStartLocationKey: string | undefined;
+  /** window.history.state?.key at classification time */
+  currentLocationKey: string | undefined;
+  /** Number of segments after reconciliation */
+  reconciledSegmentCount: number;
+  /** Number of matched segment IDs from server */
+  matchedCount: number;
+  /** Current intercept source URL (null when not on intercept route) */
+  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.
+ */
+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;
+  if (stillFetchingCount > 0) return null;
+
+  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) {
+    if (a.phase === "fetching" && a.id !== input.handleId) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * 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.
+ */
+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),
+  });
+}
+
+export type { ActionScenario };