fix(router): PPR capture retry-in-place, quiet expected aborts, DSL middleware() attachment - #644

Problem

The just-merged PPR shell cache (#641) had three cold-start DX defects observed in a live dev session — all cosmetic (every route eventually HIT), but they made a healthy route look broken:

1. A /shell-cache route with loading() (a perfectly capturable shape) needed ~5 MISS requests before it flipped to HIT, and every one of those requests dumped a full DOMException [AbortError] stack to the console.
2. The once-per-key no usable shell warning fired for that route and blamed "a loader route without a route-level loading() boundary" — but the route had loading(). The real cause was cold modules, and the message sent the user hunting for a route-shape bug that didn't exist.

Root causes (both found by instrumenting a live dev server, not guessed):

• The abort dumps were React's prerender default onError. Capture works by aborting (controller.abort() freezes the prelude and postpones the live holes); captureShellHTML passed no onError, so React logged the abort reason once per pending hole, on every capture that still had a live hole at abort time — i.e. every cold capture.
• The multi-request warmup was cold vite module transforms outlasting the task-quantized quiesce, so the first capture froze an unfinished shell (trivial prelude, sanity gate refuses). The old code stored nothing and waited for the next HTTP request to try again; several requests each warmed a bit more until one stuck.

Before vs. after (the user's log transcript)

Cold GET /shell-cache (a loading()-equipped route), server output:

Before — ~5 MISS requests, two DOMException dumps per cold capture:

[ShellCache] MISS /shell-cache
DOMException [AbortError]: This operation was aborted
    at AbortController.abort (node:internal/abort_controller:506:18)
    at captureShellHTML (src/ssr/index.tsx:460:16)
    at captureAndStoreShell (src/rsc/shell-capture.ts:376:20)
    ... (x2, repeated across ~5 requests until HIT)

After — MISS then HIT in 1-2 requests, clean log (retry healed in the same background task, so no breadcrumb was even needed here):

[ShellCache] MISS /shell-cache
[ShellCache] HIT /shell-cache

For a route that genuinely can't capture (/shell-cache/no-hole, no loading()), the retry breadcrumbs and the rewritten warning replace the stack dumps:

[ShellCache] capture attempt 1/2 for .../shell-cache/no-hole:shell aborted before shell completed (cold modules?) — retrying
[ShellCache] capture attempt 2/2 for .../shell-cache/no-hole:shell aborted — giving up until next request
[rango] Shell capture for ".../shell-cache/no-hole:shell" produced no usable shell after an in-place retry ... Two things cause this, told apart by whether the route ever flips to HIT:
  1. Cold-start warmup ... This SELF-HEALS ...
  2. A loader route WITHOUT a route-level loading() boundary ... the route NEVER flips to HIT. Add loading() ...
See the /ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md) ... or the design doc: https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/design/ppr-shell-resume.md

Consumer-facing changes

1. Attach the shell middleware via the urls() middleware() DSL

Route middleware wraps the render pass with a Response-returning next() — exactly the onion the shell middleware needs. It now works attached per-subtree, not only via router.use():

// before: global only
router.use("/products/*", createShellCacheMiddleware({ ttlSeconds: 600 }));

// after: also colocated, per-subtree, via the DSL
export const productPatterns = urls(({ path, layout, loader, loading, middleware }) => [
  layout(ProductShellLayout, () => [
    middleware(createShellCacheMiddleware({ ttlSeconds: 600, swrSeconds: 120 })),
    path("/products/:id", PricePage, { name: "product" }, () => [
      loader(LivePriceLoader),
      loading(<PriceSkeleton />),
    ]),
  ]),
]);

MISS -> HIT and HIT composition are byte-identical to the global attachment (proven by new dev+prod e2e in both apps). Actions bypass it for free (a POST is non-GET), and the background capture never re-enters it.

2. tags option for operational shell invalidation

createShellCacheMiddleware({
  tags: (ctx) => [`tenant:${ctx.get("tenant")}`],  // string[] | (ctx) => string[]
});

Unioned with the tags the capture auto-collects (every cacheTag(...) from shell material). Invalidating any tag a shell carries drops that shell -> MISS -> recapture.

Semantics table

Code-change summary

• src/ssr/index.tsx — createShellCaptureHandler threads deps.onError; prerender gets an onError that swallows the deliberate abort and reports genuine errors. This is the fix for the DOMException noise — it lives at the prerender call because that's the exact source (React's default onError).
• src/rsc/shell-capture.ts — runShellCapture is a two-attempt loop (attemptCapture x2, 400ms delay); captureAndStoreShell returns a discriminated outcome (stored | no-shell, or throws a genuine error) instead of warning itself; concise debug breadcrumbs gated on the descriptor's debug; rewritten once-per-key warning (both causes + shipped-safe pointer); exponential refused-capture backoff in scheduleShellCapture; option-tags union collected-tags in attemptCapture.
• src/cache/shell-cache.ts — tags option; debug + tags threaded onto the _shellCapture descriptor; _shellCaptureRun bypass guard at the top of the handler (scar tissue for DSL attachment).
• src/server/request-context.ts — debug field on the _shellCapture descriptor type.
• Docs: docs/design/ppr-shell-resume.md (retry-in-place + exponential backoff); skills/ppr/SKILL.md (Attaching via middleware(), Invalidation: tags vs revalidate(), cold-start pitfall, tags option).

Deliverable 4(a) verification (definitive)

Route middleware attached via urls() middleware() does NOT re-run inside the background capture. router.match() only collects route middleware into the MatchResult (src/router/match-result.ts:258); it is executed by the RSC handler's executeRender() (src/rsc/handler.ts:1198-1221), which the background capture bypasses entirely (runShellCapture calls ctx.router.match() directly, then buildFullPayload + Flight render — never executeMiddleware). The _shellCaptureRun bypass guard makes inertness inside any capture render a hard invariant regardless of attachment or future changes.

Test plan

• Unit (router): retry cases a-d (null->heal, abort->retry, non-abort->no retry+report once, both fail->warn once); captureAndStoreShell outcome contract; exponential backoff (window + expiry + success-clears); option-tags union collected-tags into putShell; middleware _shellCaptureRun bypass (no getShell, no flags); descriptor debug/tags threading. pnpm run test:unit:all green (router 4791 + all consumer dogfood suites).
• e2e dev + production (test-app): existing shell-cache suite (regression gate — the retry touches every capture path) 10 dev / 9 prod; new shell-cache-dsl 4/4 both; new shell-cache-action (hole mutation, shell+updateTag, DSL POST bypass, no-JS PE) 4 dev / 5 prod.
• e2e dev + production (cloudflare-basic): ppr-shell 13 dev / 12 prod incl. the new DSL describe.
• typecheck (repo, 15/15), lint (0/0), format, check:e2e-bucketing OK.
• Manual smoke (the user's complaint, reproduced on the fix): cold /shell-cache -> MISS->HIT at GET2, no DOMException dumps, no warning; /shell-cache/no-hole -> concise retry breadcrumbs + rewritten warning + shipped-safe pointer, no dumps.

Notes / call-outs

• Runtime doc pointers now use the shipped-path + GitHub-URL convention (a05c825). The only runtime-emitted docs/ string was the no usable shell warning; it now points at the /ppr skill (ships in the tarball) plus the absolute GitHub URL for the design doc. JSDoc/code comments keep repo-relative paths (read in-repo). A sweep of src/ confirmed no other runtime strings carried an unshipped docs/ path.
• Exponential (not flat) backoff was a mid-review correction. A flat 60s backoff made the cloudflare dev PPR e2e time out: under cold miniflare + parallel load a cold-but-eligible route could fail the retry, and a flat 60s window blocked warmToHit's multi-request recovery — re-breaking the very cold-start DX this PR fixes. Escalating from 1s lets eligible routes recover immediately while a truly doomed route ramps to the 60s cap. Production (pre-built modules -> capture on attempt 1) never trips it.
• A native <form action={serverAction}> drifts in a frozen shell (React encodes server-action form fields differently between the capture and serve render). The 10(c) PE fixture therefore lives on its own /shell-cache-action/pe route exercised only no-JS (nothing hydrates), documented inline; the JS-action routes keep their forms out of the frozen shell.
• cloudflare-basic scope: got the cheap subset — the DSL attachment (4c) + nav links. The full action-correctness suite (10a-d) stays in test-app (the mandated app); porting the cached+tagged-shell / PE / mutable-state fixtures to cloudflare's KV store was not "cheap" and would duplicate coverage.