feat(client-urls): ppr as a projected group path option — shell caching for group routes - #817

Problem

A clientUrls group landing page had no shell-cache story at all: ppr was an explicit projection rejection (path option "ppr" is not supported), and since ppr is a leaf path option, the surrounding server tree could not supply it either — inside the mount, the leaves are the group's materialized routes. Every group landing paid the full live document render on every visit while equivalent hand-written server routes could opt into instant-TTFB shell serving.

The rejection was minimal-surface caution, not a structural exclusion: unlike parallel() (handler-valued, unrepresentable) or boundaries (server-tree envelope ownership), no reason was recorded for ppr — the config is pure JSON and the runtime capture/serve machinery is route-generic. The one thing that used to be genuinely unsound — a group static part reading search — was fixed by the shell search-identity work (capture/resume render the shell key's own search).

Before / after

"use client";
export default clientUrls(({ path, loader, loading }) => [
  // before: throws 'path option "ppr" is not supported'
  // after: shell caching, exactly like a hand-written ppr page
  path("/", ShopFront, { ppr: { ttl: 300, swr: 120 } }, () => [
    loader(FeaturedLoader),
    loading(<GridSkeleton />),
  ]),
]);

End-to-end example

A shop group mounted at include("/shop", shopUrls): the group chrome, nav, and its useSearchParams-derived filter markup freeze into a per-URL shell (/shop?filter=shoes and /shop?filter=hats are distinct shells — search is shell identity); the loading() subtree over FeaturedLoader stays the live hole. A HIT flushes the stored prelude in the first bytes and streams only the loader hole; the browser hydrates with zero errors and the group is immediately interactive.

Semantics

Code changes

• src/client-urls/types.ts — ClientPathOptions picks ppr.
• src/client-urls/client-urls.ts — validateClientPpr (DSL-time shape check: true or finite numbers + non-empty tags strings, unknown keys rejected).
• src/client-urls/server-projection.ts — rejection lifted; serializePpr (frozen defensive JSON copy, independent re-validation); materializedPathOptions passes it onto the server path() — path-helper stamps the manifest entry, which is the whole runtime wiring.
• Fixture: /client-urls-e2e/ppr group route (static markup + search read + delayed monotonic loader under loading()).
• Docs: client-urls.md supported surface + rejection list, feature-map, client-urls skill.

Test plan

• Unit: DSL validation matrix (accept/reject shapes) and projection round-trip (frozen copy, mutation isolation) in the clientUrls suites (56 green); manifest round-trip pin — materialized group path() → loadManifest → resolvePprConfig — red-proven (entry.ppr undefined without the materialization spread).
• E2e (shell-cache suite, dev + production): "clientUrls group route with ppr" — MISS → HIT, frozen prelude carries the group's static markup + its search value + the loading() fallback in the first flushed bytes, loader hole advances per request under the frozen shell, browser HIT hydrates with zero errors. Red-proven: without the projection the x-rango-shell header is absent entirely.
• Full shell-cache + client-urls sweeps: 64 dev / 65 production, all green.
• Typecheck, test:unit:all, lint, format, bucketing; no .gen.ts drift (the fixture route is unnamed).

Notes

• This deliberately ships ONLY the runtime shell axis for groups. Build-time baking (Static()/Prerender() analogs for groups — param enumeration via id-referenced server defs, baked Flight entries) is the next design conversation; this PR is its Phase 1 and changes nothing it would need to undo.
• The minimal-surface doctrine holds: no handler wrappers entered the group DSL — ppr is a JSON option riding the exact projection shape search/trailingSlash established.

Second commit: stream: "navigation" loaders BAKE at capture (per-loader lane; loading() optional when fully baked)

Follow-on from review discussion ("are loaders still dynamic? ideally stream:navigation's settled return bakes"). The flag's document promise — data/handle-pushes/status in the HTML before first flush — silently degraded under ppr: the loader was masked like any live loader and its data arrived in the resume stream, never the prelude. The capture lane decision is now per loader:

loading() becomes optional when every loader is flagged — nothing masks, the shell captures complete instead of the eternal-MISS refusal. Groups inherit through the existing awaitedLoaderIndices projection with zero group-specific code; the group-ppr probe now pins a baked group loader value frozen in the group shell.

Red-proven three ways: the flipped await-before-flush unit (flagged executes + registers its record at capture, plain sibling never runs), and both e2e pins fail without the capture branch — baked value absent from the prelude, and the fully-baked route degrades to eternal MISS. One placement rule documented in the fixture: a baked reader must not share its nearest Suspense boundary with a masked reader, or the whole boundary postpones and the baked value lands in the hole.

Additional test plan:

• Unit: await-before-flush capture test flipped to the new contract (194 segment-resolution/shell units green).
• E2e dev+prod: "stream:navigation loader bakes into the shell; nested promise and plain sibling stay live" (frozen-vs-live seqs across HITs), "fully-baked route needs no loading()", group probe extended.
• Sweeps: shell-cache + shell-cache-action + prerender-ppr + semantic-matrix (segment-resolution touched): 88 dev / 90 prod.
• Docs: loader-container-bake.md addendum (bake trigger moved to the flag), feature-map PPR rows, client-urls.md, the stream option docs on both DSL surfaces, fixture doctrine header.