feat(router): ctx.dynamic() PPR shell opt-out + ctx.build; build-shell capture replays middleware - #734

Problem

A Prerender() route that also declares ppr gets its shell baked at vite build (producer B) and served x-rango-shell: HIT from the first request after deploy. But that build capture ran no middleware — so a route whose middleware seeds a variable the shell renders, or that must decide per-request whether the URL is even shell-eligible, could not be captured faithfully. And at runtime there was no way for a request to opt off the shared-shell axis: once a shell existed, every visitor got it, even when middleware meant to force per-request rendering.

Concretely: a consumer writes middleware(authGate, () => [ path("/pp/:slug", Article, { ppr }) ]). If authGate needs some slugs rendered fresh per request, they had no lever — the shell was served regardless. And build-time capture couldn't be told "skip baking this URL".

Solution — ctx.dynamic() + ctx.build

ctx.dynamic() opts the current request off the PPR shell axis. ctx.build marks the build-time capture pass. Both are available on the request, middleware, and handler contexts.

Before vs. after

// BEFORE — no opt-out; a warmed shell is served to everyone.
export const gate: Middleware = async (ctx, next) => next();

// AFTER — force fresh rendering for signed-in users, shell for anonymous.
export const gate: Middleware = async (ctx, next) => {
  if (ctx.get(User)) ctx.dynamic(); // runs BEFORE the shell HIT commit -> axis 1
  return next();
};

End-to-end consumer example

// urls.tsx
const gate: Middleware = async (ctx, next) => {
  // Build-time shell capture replays middleware with ctx.build === true.
  // Skip baking a shell for URLs we never want frozen; they keep runtime capture.
  if (ctx.build && ctx.params.slug === "live") ctx.dynamic();
  return next();
};

export const patterns = urls(({ path, middleware }) => [
  middleware(gate, () => [
    path("/article/:slug", Article, { name: "article", ppr: { ttl: 300 } }),
  ]),
]);

// Article.test.ts — now unit-testable through the public testing primitives
import { runMiddleware } from "@rangojs/router/testing";

const r = await runMiddleware(gate, { request: "/article/live", build: true });
expect(r.ctx.build).toBe(true);
expect(r.dynamic).toBe(true); // the opt-out is observable

Semantics

ctx.build: true only during producer-B shell capture (and prerender/static contexts). ctx.waitUntil() is inert when ctx.build is true, so replayed middleware fires no background work.

Code-change summary

• src/prerender/build-shell-capture.ts — build capture now previewMatches, then replays global (matchMiddleware) + route (buildRouteMiddlewareEntries) middleware through executeMiddleware before the capture. A {outcome, response} envelope adapts response-based middleware (which may short-circuit with a real Response) to the capture's outcome union; new "dynamic" outcome. The two vite/discovery callers already treat non-stored as "keep runtime capture".
• src/server/request-context.ts — build, dynamic(), _dynamic (@internal) on RequestContext; waitUntil() early-returns when build.
• src/router/{middleware-types,middleware}.ts, src/types/handler-context.ts, src/router/handler-context.ts, src/router/prerender-match.ts — build/dynamic() wired onto every context (real delegation on live/handler contexts, inert stub on prerender/static).
• src/rsc/rsc-rendering.ts — !reqCtx._dynamic guards the shell serve gate and the MISS capture-schedule.
• src/testing/{run-middleware,render-handler,internal/context}.ts — build option + dynamic result field on the public primitives.

Test plan

• typecheck (router + test-app)
• test:unit:all — router unit (5185) + RSC (69) + all consumer dogfood suites, exit 0
• lint (oxlint --deny-warnings, 0/0) · format (oxfmt) · check:docs-api · check:e2e-bucketing
• Unit — build-shell-capture.test.ts: route-mismatch, build-load-failure passthrough, middleware dynamic() short-circuit, middleware→stored, in-render dynamic() discard. request-scope.test.ts: build marker + inert waitUntil + dynamic() delegation on all three contexts. rsc-rendering-shell-ppr.test.ts: dynamic() during axis-1 MISS suppresses capture; before-commit bypass of a warm shell; HIT-tail dynamic() stays HIT.
• Userland — run-middleware.test.ts (build gating + dynamic result + inert waitUntil) and render-handler.rsc-test.tsx (HandlerContext.build/dynamic) through the public @rangojs/router/testing primitives.
• e2e (dev + production) — prerender-ppr.test.ts: build ctx.dynamic() skips the baked shell (MISS then runtime HIT); runtime ctx.dynamic() keeps the route off the shell axis. Both run in the (dev) and (production) describes via runPrerenderPprSpec.

Notes

• dynamic() deliberately scopes to the PPR shell only; a Prerender() route's B-segments still replay at runtime (documented on the JSDoc, execution-model.md, and feature-map.md).
• Behavior shift for consumers: global middleware now runs at build-shell-capture time. Side-effectful global middleware should guard with if (!ctx.build) (or rely on the inert waitUntil); documented in skills/middleware/SKILL.md.
• Deferred (low, contracts already unit-covered): an e2e that warms a shell then bypasses it via a query-gated dynamic() (the pre-commit warm-shell bypass is pinned at unit level in rsc-rendering-shell-ppr.test.ts).

_{Review method: 6-angle adversarial review (correctness, PPR semantics, type/API hygiene, test coverage, simplification, docs) + dedicated simplify pass; 13 findings addressed, 1 refuted.}