feat(router): resolve clientChunks follow-up gates; default-on is the 1.0 stance - #536

Problem

PR #535 shipped per-route client splitting (clientChunks) default-on but
explicitly labeled it "see it in action, not proven optimal", deferring four gates
to a follow-up (see docs/research/build-chunking-plan.md). Until those gates were
closed, a consumer had no measured reason to trust the default, no way to see
why their layout did or didn't split, and the user guide carried a stale claim
about the fallback behavior. This PR closes all four gates and takes a
deterministic stance.

Verdict: clientChunks ships DEFAULT-ON for 1.0

Optimized for apps at scale — the larger the app, the more wasteful it is to ship
every route's client code on every visit, and the smaller the fraction any single
user downloads. Apps where every route's client code is trivial (the small-app
case) opt out with one line. No public API shape changed; this PR makes the
existing default provably correct and observable.

What changes for a consumer

Before vs. after — observing the split (new)

# before: no way to know what the built-in strategy decided
pnpm build

# after: opt-in, zero-cost-when-off observability
DEBUG=rango:chunks pnpm build
# rango:chunks split  src/routes/dashboard/Chart.tsx -> app-dashboard
# rango:chunks shared src/parts/editor/Editor.tsx (no route-root marker; inherits default grouping)

The second line is the actionable case: app code that did not split by route.
The consumer either colocates it under a marker dir or passes a clientChunks
function — which is the supported configurability path, not widening an infinite
marker list.

End-to-end consumer example — the one-line opt-out

// vite.config.ts — small app where per-route client code is trivial:
export default defineConfig({ plugins: [rango({ clientChunks: false })] });

// or hand-tune: fold a specific route back into the shared chunk
rango({
  clientChunks: ({ normalizedId }) => {
    if (normalizedId.includes("/routes/tiny-route/")) return undefined; // shared
    const m = normalizedId.match(/\/routes\/([^/]+)\//);
    return m ? `route-${m[1]}` : undefined;
  },
});

The four gates, resolved

Gate 1 — cost-side benchmark: PASSED

tools/bench-client-chunks.mjs measures tests/vite-rsc-demo (5 feature routes,
~33 KB gz app client code) built both ways:

Honest cost side: +1 first-load request and +5% total client JS (per-chunk gzip
overhead), the latter fully paid only on a cold crawl of every route in one
session. Land-on-one-route and typical 1–3 route sessions both win. The win is a
function of app size — the baseline's every-route app chunk grows with total
app code, the split's per-route first-load does not.

Gate 2 — min-chunk-size coalescing: WON'T-FIX (by design)

Reopen trigger: a real consumer report of pathological fragmentation → the fix
would be a post-build chunk-merge pass (the only place real sizes exist), not a
callback change.

Gate 3 — CSS ordering / FOUC: COVERED

New e2e (e2e/mini.test.ts, /combined) renders client components from two
route groups on one page — the case where per-group <link> precedence actually
interacts (vite-plugin-react#1100). Asserts both stylesheets apply with the
correct cascade, deterministically across a reload, in dev and production.
mini gains a /combined route (and the synced router.named-routes.gen.ts).

Gate 4 — convention completeness: RESOLVED

• The clientChunks function is the configurability path for any layout — the marker list is intentionally finite, not the mechanism.
• New rango:chunks debug namespace surfaces every grouping decision (and the reason for a shared fallback), resolving the previously-silent behavior.
• Fixed a stale doc claim: unmarked paths inherit the default grouping (fold into the shared chunk); they are not forced into a parent-named app-components chunk (which would re-introduce cross-app leakage).

Semantics (unchanged contract, now documented + observable)

Code-change summary

• src/vite/debug.ts — add rango:chunks namespace.
• src/vite/utils/client-chunks.ts — log each grouping decision (split + the actionable shared-fallback) inside directoryClientChunks; control-flow refactor preserves behavior exactly (15 unit tests unchanged, resolveClientChunks(true) === directoryClientChunks still holds for zero per-call cost when the namespace is off).
• tools/bench-client-chunks.mjs — static cost-side analyzer (gzip sizes, shared baseline, per-route first-load + full-crawl model).
• tests/vite-rsc-demo/vite.config.ts — RANGO_BENCH_CHUNKS consumer-side toggle (also a live demo of the public opt-out; defaults to on when unset, so e2e is unaffected — verified the env-unset build emits identical chunk hashes).
• e2e/mini/src/router.tsx + .gen.ts + e2e/mini.test.ts — /combined multi-group CSS co-render route + dev/prod e2e.
• packages/rangojs-router/docs/client-chunking.md — corrected fallback section, observability section, measured cost-side table; docs/research/build-chunking-plan.md — gates marked RESOLVED with the deterministic stance.

Test plan

• Typecheck (12/12 packages)
• Unit (3315 pass) — incl. client-chunks.test.ts (15)
• Lint (oxlint, 0) + Format (oxfmt)
• e2e dev and production — mini clientChunks incl. new /combined (7 dev+prod), vite-rsc-demo kanban production (8) against the split build
• rango:chunks observability smoke-verified on a real build
• e2e-bucketing guard (pre-commit) green

Notes

• RANGO_BENCH_CHUNKS lives in the test app's own config (consumer-side), not the plugin — no plugin env knob (the research PoC env-gating was deliberately removed before feat(router): per-route client chunking via clientChunks (default-on) #535).
• Per-call debug logging fires once per build env (client + ssr); expected, opt-in only.