test(ppr): e2e-pin the layout-loader trap + slot escape; design doc for loader container bake - #661

Problem

The most common production shape — an app-wide layout registering session/basket-style loaders, with ppr on a page beneath it — dead-ends today: every shell capture refuses and the route stays x-rango-shell: MISS forever. A real storefront migration hit this and was misled twice: the refusal warning's route-level framing ("add loading() to the loader route") suggested a fix that does not work when the loaders live on a layout, and nothing pinned the actual rules. Only the route-level variant (/shell-cache/no-hole) had e2e coverage.

What this PR does

Pins the trap in its exact consumer shapes, pins the working escape, and adds the design doc for the real fix. No framework behavior changes — the router behaves identically before and after this PR.

New e2e (test-app suite AND cloudflare-basic twin — dev + production in both)

The cloudflare-basic twin runs the same three pins on the real KV-backed CFCacheStore under workerd (dev worker + built preview worker).

Design doc: docs/design/loader-container-bake.md

One promise doctrine for all three lanes: a loader on a no-loading() entry executes during capture, its settled container bakes, nested promises hole at the consumer's <Suspense> — { static: 'baked', dynamic: promise }, the return shape as the entire API. Key grounding: axis 1 already implements container-settles/nested-streams for loading()-less loaders (now e2e-pinned by this PR), so the design makes capture match axis 1 rather than inventing semantics. Covers capture unmasking, the identity guard dropping its loader exemption during capture (fail-closed), HIT parity via a third capture-data-snapshot family with a fresh-run + recorded-container overlay, rollout (default-on: the only affected shape is today's eternal-MISS refusal), and open questions. The trap tests in this PR are the red→green vehicle for the implementation.

Also included: the promise-holes docs expansion already on main gets its e2e backing here (the /ppr layout-with-loaders playbook's slot pattern was previously source-verified only).

Consumer story

Nothing to adopt in this PR. For a consumer hitting the trap today, the pinned escape is the playbook shape:

layout(StoreChrome, () => [
  parallel({
    "@basket": {
      handler: () => <BasketBadge loader={BasketLoader} />,
      use: () => [loader(BasketLoader), loading(<BadgeSkeleton />)],
    },
  }),
  path("/", HomePage, { name: "home", ppr: true }),
]),

Chrome bakes into the shell; the badge is a badge-sized hole; no page-level skeleton exists. After the design doc ships, the same app drops the slot machinery and declares liveness by return shape alone.

Semantics table (all pinned, none changed)

Code changes

• packages/rangojs-router/e2e/test-app: shell-cache.defs.ts (+2 loaders), shell-cache.tsx (+2 layouts, 3 routes), components/ShellBadge.tsx (new), router.named-routes.gen.ts
• packages/rangojs-router/e2e/shell-cache.test.ts: +3 tests in the shared spec (runs in both dev and (production) describes)
• tests/cloudflare-basic: mirrored fixtures (loaders/ppr-shell.ts, pages/ppr-shell.tsx, components/PprShellBadge.tsx, urls.tsx), +3 tests in e2e/ppr-shell.test.ts (describePprShell dev + production), router.named-routes.gen.ts
• packages/rangojs-router/docs/design/loader-container-bake.md (new)

Test plan

• shell-cache suite: 38 passed × dev + production (test-app)
• ppr-shell suite: 34 passed × dev + production (cloudflare-basic, workerd)
• pnpm run typecheck, pnpm run test:unit:all, pnpm run lint, pnpm run format, pnpm check:e2e-bucketing
• *.gen.ts regenerated and committed for both apps that gained routes

Notes

• The dev-worker test output incidentally captures the live refusal warning firing with the misleading route-level text — supporting evidence for the warning fix listed in the design doc's rollout section (deliberately not implemented here; this PR is pins + design only).
• The nonce→axis-1 interaction has zero e2e coverage anywhere (cloudflare-basic-nonce has no ppr tests); deliberately left out of this PR since nonce work is in flight elsewhere.