@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/skills/composability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: composability
-description: Reusable composition patterns with globally importable route helpers in @rangojs/router
+description: Reusable composition patterns with globally importable route helpers in @rangojs/router. Use when sharing loaders, middleware, or handler logic across multiple route files, or avoiding copy-pasting the same route setup everywhere.
 argument-hint: "pattern-name"
 ---
 
@@ -22,7 +22,6 @@ import {
   loading,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
 } from "@rangojs/router";
@@ -55,7 +54,9 @@ import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/
 // Shared caching configuration
 const withCaching = () => [
   cache({ ttl: 600_000 }),
-  revalidate(({ actionId }) => !!actionId),
+  // Defer on navigation (|| undefined) so each route keeps its own param/search
+  // revalidation default; only force a re-run when an action ran.
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
 ];
 
 // Shared loading and error handling
@@ -71,6 +72,29 @@ const withAuth = () => [
 ];
 ```
 
+> **Factories compose logic, not just values.** A `revalidate()` predicate in a
+> shared factory applies its logic to _every_ route that composes it, so a
+> footgun here is amplified across the app. Two rules:
+>
+> 1. Use `|| undefined` (defer), not `?? false` (hard short-circuit), in shared
+>    predicates — a hard `false` ends the chain and overrides each consuming
+>    route's own default, and a downstream revalidator never runs. See `/loader`
+>    → "`|| undefined` (defer) vs `?? false` (hard)".
+> 2. Match actions with `ctx.isAction(Action)`, not an inline
+>    `actionId.includes("…")` buried in a factory: it resolves the action from an
+>    imported reference, so a rename is a compile error in one place instead of
+>    silent drift across every consumer.
+>
+> Remember the axis: a factory's `revalidate()` controls client-update
+> selection, while its `cache()` controls stored-value freshness. They are
+> independent even when bundled in the same factory (`/cache-guide` → "Two axes").
+
+> **Keep factories small and intention-named.** The anti-pattern that kills
+> readability is over-bundling — a `withDefaults()` that secretly adds five
+> things — and factory-of-factories nesting (leaning on `.flat(3)`). Surprising
+> config stays inline; extract only the boring, repeated parts; compose by
+> _naming concerns_ (`withAuth()`, `withCaching()`), not by hiding them.
+
 ## Using Factories in Routes
 
 Place factory calls inside `path()` or `layout()` use callbacks. The returned arrays are flattened automatically (up to 3 levels):
@@ -107,7 +131,7 @@ import { authMiddleware } from "./middleware/auth";
 
 export const withPublicDefaults = () => [
   cache({ ttl: 300 }),
-  revalidate(({ actionId }) => !!actionId),
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
 ];
 
 export const withProtectedDefaults = () => [
@@ -136,6 +160,102 @@ export const adminPatterns = urls(({ path }) => [
 ]);
 ```
 
+## Code-splitting a route group with async include()
+
+`include()` takes a route module two ways. Eager — the module is already in the
+graph:
+
+```typescript
+import { shopPatterns } from "./shop-patterns";
+
+urls(({ include }) => [include("/shop", shopPatterns, { name: "shop" })]);
+```
+
+The `name` option controls whether the child's named routes join the parent
+route map:
+
+| Form                                           | Name behavior                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------------ |
+| `include("/shop", patterns)`                   | private module scope; child names stay out of the app-wide generated map |
+| `include("/shop", patterns, { name: "shop" })` | namespace children as `shop.index`, `shop.product`, ...                  |
+| `include("/shop", patterns, { name: "" })`     | flatten children into the parent namespace                               |
+
+Omission is intentional for reusable/local modules, not a missing default. Use
+`{ name: "" }` only when the child names are globally unique and meant to be
+reversed from elsewhere. Inside the module, dot-local reversal and
+`scopedReverse()` work without flattening.
+
+Async — the module is code-split behind a `() => import()` thunk. It becomes its
+own chunk that is NOT evaluated at startup; the router imports it on the first
+request that reaches the prefix, then caches it:
+
+```typescript
+urls(({ include }) => [
+  include("/shop", () => import("./shop-patterns"), { name: "shop" }),
+]);
+```
+
+The split module exposes its `urls()` value as the default export (convention):
+
+```typescript
+// src/shop-patterns.ts
+import { urls } from "@rangojs/router";
+
+export const shopPatterns = urls(({ path, include }) => [
+  path("/", ShopHome, { name: "home" }),
+  include("/product", productPatterns, { name: "product" }), // nesting is fine
+]);
+
+export default shopPatterns; // async include() resolves this
+```
+
+**Prefer the async form** for any route group that is a natural,
+independently-loadable unit (a localized section, an admin area, an API surface
+with heavy handlers) — it trims the eagerly-parsed entry bundle and keeps that
+subgraph off the cold-start path. The **eager form is still fully valid** (not
+deprecated): keep it for small groups, or ones that share most of their module
+graph with the entry (the bundler keeps shared modules common regardless, so
+splitting a thin group buys little). Both match identically at runtime — only the
+module's runtime evaluation timing differs.
+
+What you do NOT lose by splitting: build-time discovery `await`s the provider, so
+`href()`, `reverse()`, generated route types, and prerender still see every route
+in the group — including nested `include()`s inside the split module. Only the
+module's runtime evaluation defers. `rango generate` resolves the `() => import()`
+the same way, so a code-split group is still fully typed.
+
+### Sizing async include groups (measured)
+
+The first request into an async group pays that group's chunk import; every
+request after that is flat. Measured on a deployed Cloudflare worker with
+26k routes (2026-07, warm RTT floor ~23 ms):
+
+| Group size                 | First-hit latency                    |
+| -------------------------- | ------------------------------------ |
+| ~240 routes                | ~75 ms (≈ RTT + eval)                |
+| ~5,000 routes              | ~137 ms                              |
+| ~9,000 routes              | ~188 ms                              |
+| 3-level nested async chain | ~464 ms (levels import sequentially) |
+
+Three rules fall out of those numbers:
+
+1. **Prefer more, smaller groups over few giant ones.** First-hit cost scales
+   with routes-per-chunk; fifty 250-route groups each cost a fraction of one
+   9k-route group, and only the group actually visited pays anything.
+2. **Keep async-include chains shallow on latency-sensitive paths.** Each
+   nested `() => import()` level awaits in sequence, so depth multiplies the
+   first hit. Nesting eager includes inside one async module costs one chunk;
+   nesting async inside async costs one chunk per level.
+3. **Give sibling groups distinct static prefixes.** Siblings that share a
+   static prefix (`include("/x/:a", …)` next to `include("/x/:b", …)`) all
+   import on the first hit to that prefix — the router cannot tell which one
+   matches before loading them.
+
+Warm-path matching is O(path segments) via the precomputed trie regardless of
+group layout — this sizing only shapes cold/first-hit behavior. For
+latency-critical prefixes, a post-deploy warmup ping (one request per prefix)
+erases first-hit cost for the isolate entirely.
+
 ## Composition Types
 
 For typed factories, import the composition types:

package/skills/css/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: css
+description: Import and apply CSS in a Rango app. Render document/app stylesheets in the Document `<head>` with Vite's `?url` import plus a `precedence`-managed `<link rel="stylesheet">` (React 19 resource model — deduped, ordered, loaded before paint). Use when wiring global/app CSS or a Document `<head>` stylesheet, or when deciding between `?url` + `<link>` and side-effect imports. Cross-app (host-router) navigation is a full document load, so each app's document CSS is always re-established by its own load.
+argument-hint:
+---
+
+# CSS imports
+
+Document/app CSS in Rango lives in the Document `<head>`, loaded with Vite's
+`?url` import and a `precedence`-managed `<link rel="stylesheet">`. This page is
+the why and the one cross-app caveat; `/tailwind` is the concrete setup, `/theme`
+is dark mode, `/fonts` is fonts.
+
+## The pattern
+
+```tsx
+// document.tsx
+"use client";
+
+import type { ReactNode } from "react";
+import { MetaTags } from "@rangojs/router/client";
+import styles from "./index.css?url";
+
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+- **`?url`** returns the processed file's hashed URL instead of injecting it as a
+  side effect, giving a stable asset path that works in dev and production.
+- **`precedence`** opts the `<link rel="stylesheet">` into React 19's managed
+  stylesheet model: React de-duplicates it by `href`, orders it by precedence
+  (any string value — it only decides cascade order relative to other managed
+  sheets), and loads it **before paint**, so there is no flash of unstyled
+  content. This is the recommended way to render a stylesheet link.
+
+## Cross-app (host-router) navigation
+
+You do **not** need to coordinate CSS across apps mounted under one host router.
+A client-side navigation that crosses an app boundary is a **full document load**
+(the server returns `X-RSC-Reload` on an app switch — see `/host-router`), so the
+target app's entire document — its stylesheets, theme, meta — is re-established
+by the target app's own load. Each app owns its document; how one app renders a
+stylesheet has no effect on another.
+
+(This replaced an earlier soft cross-app swap. Under it, a stylesheet shared
+across apps by `href` — classically every app's `@import "tailwindcss"` compiling
+to one hashed asset — could be silently dropped by React's by-`href` resource
+dedup when the apps disagreed on `precedence` (one unmanaged, one managed). The
+full reload removes that footgun entirely, which is the main reason cross-app
+navigation is a hard boundary.)
+
+## Side-effect imports vs `?url`
+
+A bare `import "./index.css"` (no `?url`, no `<link>`) also produces _managed_ CSS
+— `@vitejs/plugin-rsc` collects it via `import.meta.viteRsc.loadCss` and injects
+it with a precedence. It is fine for **component-local** CSS that loads with its
+client chunk. For **document-level** CSS, prefer the `?url` + `<link precedence>`
+form above: a side-effect import is not guaranteed to be in the initial streamed
+`<head>` (an SSR-streaming caveat), whereas the explicit `<link>` is.
+
+## Related
+
+- `/tailwind` — Tailwind v4 setup using this pattern.
+- `/host-router` — multi-app routing; why cross-app navigation is a full reload.
+- `/theme` — dark mode / theme attribute.
+- `/fonts` — self-hosted fonts via `@fontsource`.

package/skills/debug-manifest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-manifest
-description: Debug and inspect route manifest structure
+description: Debug and inspect route manifest structure. Use when routes aren't matching as expected, you need to see the generated route tree, or a path resolves to the wrong handler.
 argument-hint:
 ---
 
@@ -8,18 +8,10 @@ argument-hint:
 
 Inspect the route manifest to verify parent relationships, shortCodes, and route structure.
 
-## Quick Access
-
-In development, visit:
-
-```
-http://localhost:PORT/__debug_manifest
-```
-
-Returns formatted JSON with all routes and layouts.
-
 ## Programmatic Access
 
+Call `router.debugManifest()` — an `async` method on the router instance:
+
 ```typescript
 import { router } from "./router.js";
 
@@ -32,6 +24,8 @@ if (process.env.NODE_ENV !== "production") {
 
 ## Manifest Structure
 
+The programmatic `router.debugManifest()` call returns `{ routes, layouts, totalRoutes, totalLayouts }`:
+
 ```json
 {
   "routes": {

package/skills/defer-hydration/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: defer-hydration
+description: Keep the full body HTML in a PPR shell's first paint while moving a heavy subtree's hydration off the initial main-thread task — a gated Suspense boundary with the content as its own fallback, released on first idle. Use when a shell HIT paints fast but one long hydration task blocks the main thread, TTI/INP is poor despite instant paint, or a plain Suspense boundary left an empty hole in the frozen prelude.
+argument-hint:
+---
+
+# Deferred hydration: gated boundary, content-as-fallback
+
+PPR (`/ppr`) makes first paint instant — the frozen prelude flushes before any
+render work. It does nothing about what happens next: React hydrates the page
+as one synchronous main-thread task, and on a content-heavy page that task can
+block every click and scroll handler for seconds. Measured on a production
+storefront homepage (shell HIT, production build, M-series laptop): a single
+2543ms task. On the dev server the same page produced a 7.2s task — the page
+was dead for ~11s. Fast paint, frozen page.
+
+The obvious fix — wrap the heavy subtree in `<Suspense>` so it hydrates later —
+trades the paint away: under shell capture that boundary postpones, and the
+frozen prelude ships an empty `<main>`. This recipe gets both: the full body
+HTML in the prelude AND its hydration off the initial task, released on first
+idle at retry-lane priority.
+
+|                                  | baseline | plain `fallback={null}` boundary | gated content-as-fallback |
+| -------------------------------- | -------- | -------------------------------- | ------------------------- |
+| body in first paint              | yes      | **no — empty `<main>`**          | yes                       |
+| worst main-thread task           | 2543ms   | 844ms                            | **386ms**                 |
+| total blocked time (>50ms tasks) | 2705ms   | 1436ms                           | **554ms**                 |
+| interactive (menu click works)   | ~3.5s    | ~1.6s                            | ~1.6s                     |
+
+Measure your own page before and after — the win depends on how much of the
+hydration cost lives under the boundary (see "Verifying and measuring").
+
+## The recipe
+
+~40 lines, plain React, no rango imports — copy it into your app:
+
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import { Suspense, startTransition, use, useEffect } from "react";
+
+let released = false;
+let releaseFn: (() => void) | undefined;
+const gate = new Promise<void>((resolve) => {
+  releaseFn = resolve;
+});
+
+function releaseHydrationGate() {
+  if (released) return;
+  released = true;
+  // Transition so the boundary retry/hydration is scheduled non-urgent,
+  // never as a sync flush from the idle callback.
+  startTransition(() => releaseFn?.());
+}
+
+function HydrationGate() {
+  // Server: inert (children SSR normally). Client before release: suspend,
+  // so React skips hydrating the boundary and KEEPS the server DOM.
+  if (typeof window !== "undefined" && !released) use(gate);
+  return null;
+}
+
+function ReleaseHydrationGate() {
+  // Sibling of the boundary — NEVER under it (its effect would deadlock
+  // holding its own key). Hydrates with the early pass.
+  useEffect(() => {
+    if (released) return;
+    if ("requestIdleCallback" in window) {
+      requestIdleCallback(releaseHydrationGate, { timeout: 1500 });
+    } else {
+      setTimeout(releaseHydrationGate, 200);
+    }
+  }, []);
+  return null;
+}
+
+export function DeferredHydration({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <ReleaseHydrationGate />
+      <Suspense fallback={children}>
+        <HydrationGate />
+        {children}
+      </Suspense>
+    </>
+  );
+}
+```
+
+Wrap the heavy subtree — typically the page body under the app chrome:
+
+```tsx
+<DeferredHydration>
+  <HomePageBody />
+</DeferredHydration>
+```
+
+The chrome (header, nav — whatever must respond to the first click) stays
+outside the boundary and hydrates in the early, now-small task. Everything
+inside hydrates after first idle.
+
+## Why `fallback={children}` is load-bearing
+
+This is not a style choice; it is the half of the recipe that makes it
+PPR-compatible.
+
+Shell capture aborts on flight byte-quiet (`src/rsc/shell-capture.ts`,
+`FLIGHT_QUIET_HOPS`): once the Flight source has been byte-silent for the
+quiet window, the fizz render freezes. A big HTML subtree under _any_
+`<Suspense>` boundary cannot finish inside that window, so the boundary always
+postpones — boundary placement cannot fix it. Verified both ways: wrapping the
+client island from outside AND placing the boundary inside the island both
+baked `<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the
+frozen prelude.
+
+With the content as the fallback, the unavoidable postpone _becomes the
+delivery mechanism_: the shell bakes the fallback, and the fallback IS the
+body. In `/ppr` hole-doctrine terms, this is the PHYSICS class exploited
+deliberately — you cannot stop the boundary from becoming a hole, so you make
+the hole's baked fallback carry the real markup.
+
+## Why the client gate is free
+
+Suspending during hydration keeps the **server DOM**, not the fallback. When
+`HydrationGate` suspends on the client, React skips hydrating that boundary
+and leaves the baked HTML in place — visible, styled, inert. On release, the
+boundary retries on the retry lane (interruptible, non-urgent thanks to the
+`startTransition` in `releaseHydrationGate`), and the existing DOM hydrates in
+place. No blank, no flicker, no re-paint.
+
+## The sync-update trap (scar tissue)
+
+A **synchronous** update that reaches into a dehydrated boundary makes React
+abandon hydration and client-render it instead. That client render suspends on
+the gate and renders the fallback. With `fallback={children}` this is a visual
+no-op (but wasted work); with `fallback={null}` it blanks the page.
+
+The corollary: provider data syncs that land right after the chrome hydrates —
+basket, wishlist, auth state read from storage in an effect — MUST be
+`startTransition`-wrapped. This was measured, not theorized: without the
+transitions, the boundary was force-hydrated synchronously and the split
+evaporated (the 2543ms task survived intact).
+
+```tsx
+useEffect(() => {
+  const stored = readBasketFromStorage();
+  startTransition(() => setBasket(stored)); // NOT a bare setBasket(stored)
+}, []);
+```
+
+## Pre-release interaction semantics
+
+Between paint and release (window ≈ one idle, capped by the `requestIdleCallback`
+timeout — 1500ms in the reference):
+
+- **Native anchors work** — they are plain HTML in the server DOM, plus any
+  click-delegation living above the boundary.
+- **React `onClick`s inside the gated subtree queue** via React's event replay
+  and fire on hydration after release.
+
+If the gated subtree's first-click latency matters more than idle timing,
+release on interaction instead (see Variations).
+
+## Known cost: the body rides twice (measure it, don't guess)
+
+On a shell HIT the gated subtree's HTML is in the response twice — once as the
+baked fallback in the prelude, once as the resumed hole content (the resume
+re-renders and re-ships it; there is no bake-through). Homepage measurement:
+234KB → 302KB gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth,
+not render-blocking — the visible prelude streams first — but it is real bytes
+on every document GET. Weigh it per page; on a small body the recipe may not
+pay for itself.
+
+## Verifying and measuring
+
+Production build only — dev-server hydration numbers are noise (module
+transforms dominate; the 7.2s dev task above vs 2543ms in production).
+
+**Body in the prelude.** Fetch the document and check a distinctive piece of
+body markup appears BEFORE the first resumed segment:
+
+```
+curl -s -H "Accept: text/html" http://localhost:4173/ \
+  | awk '{ if (match($0, /<div hidden id="S:/)) { print substr($0, 1, RSTART); exit } print }' \
+  | grep -c "Best Sellers"    # any string unique to the gated body
+```
+
+`0` with `<!--$?--><template id="B:` markers inside `<main>` means an empty
+hole baked instead — the fallback is not the content (wrong boundary, or a
+plain `fallback={null}`/skeleton boundary).
+
+**Main-thread tasks.** Paste a longtask observer in the console before
+reloading, then compare the worst task with the recipe on and off:
+
+```js
+new PerformanceObserver((l) =>
+  l
+    .getEntries()
+    .forEach((e) => console.log("longtask", Math.round(e.duration))),
+).observe({ entryTypes: ["longtask"] });
+```
+
+**Interactivity.** Click the chrome (menu, nav) immediately after paint — it
+should respond while the gated body is still inert.
+
+## Variations
+
+- **Release on visible** — an `IntersectionObserver` per boundary instead of
+  `requestIdleCallback`: below-the-fold sections hydrate only when scrolled
+  near.
+- **Release on first interaction** — a capture-phase listener
+  (`pointerdown`/`keydown` on `window`) that releases immediately: the queued
+  event replays into the touched boundary and React's selective hydration
+  prioritizes it. Best when the gated subtree is itself the interaction
+  target.
+- **One shared gate vs per-boundary gates** — the reference uses one
+  module-level gate (first release wins, all boundaries hydrate together).
+  Multiple independent boundaries (visible-based, per-section) need one
+  gate/`released` pair per boundary — factor the module into a
+  `createHydrationGate()` if you go there.
+
+## What this deliberately is not
+
+The duplicated payload has an obvious framework-level fix: a "bake-through"
+boundary that bakes the boundary _content_ into the prelude and skips the
+redundant hole resume. That is deliberately NOT part of this recipe — a recipe
+has zero API commitment, and React's `<Activity>`/postpone work may land under
+this exact space. The recipe survives that future; a primitive might not.
+
+## Related
+
+- `/ppr` — the shell/hole mechanics this recipe rides on (hole doctrine:
+  PHYSICS class), and why the capture postpones any big Suspense subtree
+- `src/rsc/shell-capture.ts` — the byte-quiet capture window
+  (`FLIGHT_QUIET_HOPS`) that makes `fallback={children}` mandatory