@rangojs/router 0.0.0-experimental.80 → 0.0.0-experimental.80daa23e

package/skills/catalog.json

@@ -0,0 +1,289 @@
+{
+  "$schema-note": "Generated by tools/generate-skills-catalog.mjs — do not edit by hand.",
+  "package": "@rangojs/router",
+  "entry": "rango",
+  "skills": [
+    {
+      "name": "api-client",
+      "description": "Build a typed client for consuming your own response-route JSON APIs (no codegen). Use when calling your own JSON endpoints from another service or script, or you want typed fetch calls without a codegen step.",
+      "argumentHint": "",
+      "path": "skills/api-client/SKILL.md"
+    },
+    {
+      "name": "breadcrumbs",
+      "description": "Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.",
+      "argumentHint": "[setup]",
+      "path": "skills/breadcrumbs/SKILL.md"
+    },
+    {
+      "name": "bundle-analysis",
+      "description": "Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.",
+      "argumentHint": "<app-dir>",
+      "path": "skills/bundle-analysis/SKILL.md"
+    },
+    {
+      "name": "cache-guide",
+      "description": "When to use cache() DSL vs \"use cache\" directive — key differences and decision guide. Use when unsure which caching mechanism fits a given problem, comparing route/segment caching, function-level caching, and document-level caching, or asking \"which cache API should I use\".",
+      "argumentHint": "",
+      "path": "skills/cache-guide/SKILL.md"
+    },
+    {
+      "name": "caching",
+      "description": "Configure route/segment-subtree caching with memory, Cloudflare KV, or Vercel cache stores in @rangojs/router. Use when responses should be cached or revalidated, data is stale or not updating after code changes, or you are wiring up a cache store.",
+      "argumentHint": "[setup]",
+      "path": "skills/caching/SKILL.md"
+    },
+    {
+      "name": "client-urls",
+      "description": "Define client-component route groups with clientUrls() in a \"use client\" module — no handlers, useLoader at read sites, client-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a \"use client\" file work.",
+      "argumentHint": "[setup]",
+      "path": "skills/client-urls/SKILL.md"
+    },
+    {
+      "name": "cloudflare",
+      "description": "Deploy and operate @rangojs/router on Cloudflare Workers with the Cloudflare Vite plugin, typed D1/KV bindings, local migrations, secrets, streaming, preview parity, and built-worker deployment. Use when creating a Cloudflare Rango app, moving a Rango app to Workers, wiring D1 or KV, debugging dev/preview differences, or preparing a Worker deployment.",
+      "argumentHint": "",
+      "path": "skills/cloudflare/SKILL.md"
+    },
+    {
+      "name": "comparison",
+      "description": "Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.",
+      "argumentHint": "",
+      "path": "skills/comparison/SKILL.md"
+    },
+    {
+      "name": "composability",
+      "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.",
+      "argumentHint": "pattern-name",
+      "path": "skills/composability/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "",
+      "path": "skills/css/SKILL.md"
+    },
+    {
+      "name": "debug-manifest",
+      "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.",
+      "argumentHint": "",
+      "path": "skills/debug-manifest/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "",
+      "path": "skills/defer-hydration/SKILL.md"
+    },
+    {
+      "name": "deployment-caching",
+      "description": "Choose the deployment cache boundary for a Rango app: in-function segment/prerender/PPR caches, store-backed whole-response caching, or an external CDN cache. Use when comparing Cloudflare, Vercel, and Node deployments; deciding whether Cache-Control can reduce origin work; or reasoning about middleware, live loaders, PPR, and CDN behavior.",
+      "argumentHint": "[cloudflare|vercel|node]",
+      "path": "skills/deployment-caching/SKILL.md"
+    },
+    {
+      "name": "document-cache",
+      "description": "Cache complete HTTP responses in Rango's configured app store with createDocumentCacheMiddleware, using Cache-Control s-maxage as policy. Use when reusing a whole HTML/RSC response, comparing the store-backed middleware with a platform CDN cache, or deciding whether full-response caching is safe.",
+      "argumentHint": "[setup]",
+      "path": "skills/document-cache/SKILL.md"
+    },
+    {
+      "name": "fonts",
+      "description": "Load and configure web fonts with preload hints for optimal performance. Use when adding a custom font to a Rango app, fonts flash or swap on load (FOUT/FOIT), or you want font preload for performance.",
+      "argumentHint": "[provider]",
+      "path": "skills/fonts/SKILL.md"
+    },
+    {
+      "name": "handler-use",
+      "description": "Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites. Use when a handler needs its own default middleware/loader without repeating use() at every mount site, or deciding between handler-level defaults and per-route use().",
+      "argumentHint": "[handler]",
+      "path": "skills/handler-use/SKILL.md"
+    },
+    {
+      "name": "hooks",
+      "description": "Client-side React hooks for navigation, loaders, and state in @rangojs/router. Use when a client component needs the current URL, params, search params, navigation state, or loader data — e.g. \"how do I read the route param in a component\".",
+      "argumentHint": "[hook-name]",
+      "path": "skills/hooks/SKILL.md"
+    },
+    {
+      "name": "host-router",
+      "description": "Multi-app host routing with domain/subdomain patterns. Use when running multiple apps behind one domain or across subdomains, or routing requests to different apps based on hostname.",
+      "argumentHint": "",
+      "path": "skills/host-router/SKILL.md"
+    },
+    {
+      "name": "i18n",
+      "description": "Locale-aware routing with `include(\"/:locale?\", ...)`, locale resolution chains, and react-intl integration. Use when building a multi-language app, routes need a locale segment, or wiring up react-intl translations.",
+      "argumentHint": "[topic]",
+      "path": "skills/i18n/SKILL.md"
+    },
+    {
+      "name": "intercept",
+      "description": "Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router. Use when opening a route as a modal/overlay on top of the current page while keeping the URL shareable, or asking \"how do I show this page in a modal\".",
+      "argumentHint": "[@slot-name] [route-to-intercept]",
+      "path": "skills/intercept/SKILL.md"
+    },
+    {
+      "name": "layout",
+      "description": "Define layout routes that wrap child routes in @rangojs/router. Use when sharing a persistent UI shell (nav, sidebar) across nested routes, or asking how to wrap child pages with a common layout.",
+      "argumentHint": "[component]",
+      "path": "skills/layout/SKILL.md"
+    },
+    {
+      "name": "links",
+      "description": "URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse. Use when generating a link to a route by name instead of hardcoding a path, or a link breaks after routes move or get mounted elsewhere.",
+      "argumentHint": "[ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]",
+      "path": "skills/links/SKILL.md"
+    },
+    {
+      "name": "loader",
+      "description": "Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (ssr:false).",
+      "argumentHint": "[loader]",
+      "path": "skills/loader/SKILL.md"
+    },
+    {
+      "name": "middleware",
+      "description": "Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.",
+      "argumentHint": "[middleware-name]",
+      "path": "skills/middleware/SKILL.md"
+    },
+    {
+      "name": "migrate-nextjs",
+      "description": "Migrate a Next.js App Router project to @rangojs/router. Use when the user asks to \"migrate from Next.js\", \"convert Next.js to Rango\", \"replace Next.js\", or has a Next.js app they want to port.",
+      "argumentHint": "[path-to-nextjs-app]",
+      "path": "skills/migrate-nextjs/SKILL.md"
+    },
+    {
+      "name": "migrate-react-router",
+      "description": "Migrate a React Router v7/v6 project to @rangojs/router. Use when the user asks to \"migrate from React Router\", \"convert React Router to Rango\", \"replace React Router\", \"move from Remix to Rango\", or has a React Router / Remix app they want to port.",
+      "argumentHint": "path-to-react-router-app",
+      "path": "skills/migrate-react-router/SKILL.md"
+    },
+    {
+      "name": "mime-routes",
+      "description": "Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header. Use when the same URL needs to return JSON for API clients and HTML/RSC for browsers, or branching a handler on the Accept header.",
+      "argumentHint": "[negotiate|vary|accept]",
+      "path": "skills/mime-routes/SKILL.md"
+    },
+    {
+      "name": "observability",
+      "description": "Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing. Use when a request feels slow and you need to see where time is spent, or wiring up tracing/telemetry for production requests.",
+      "argumentHint": "",
+      "path": "skills/observability/SKILL.md"
+    },
+    {
+      "name": "parallel",
+      "description": "Define parallel routes for multi-column layouts, sidebars, and modal slots in @rangojs/router. Use when a layout needs multiple independently-loading regions (e.g. a sidebar and main panel), or rendering more than one route segment at the same URL.",
+      "argumentHint": "[@slot-name]",
+      "path": "skills/parallel/SKILL.md"
+    },
+    {
+      "name": "ppr",
+      "description": "PPR shell caching — opt a page route in with the `ppr` path option; the router serves the cached HTML shell instantly and resumes the live holes. Use when a page should render instantly from a cached shell while specific parts stay live, or asking about partial prerendering in Rango.",
+      "argumentHint": "[setup]",
+      "path": "skills/ppr/SKILL.md"
+    },
+    {
+      "name": "prerender",
+      "description": "Pre-render route segments at build time with Prerender and Passthrough live fallback. Use when a page's content is mostly static and shouldn't render on every request, speeding up cold responses, or deciding which routes to prerender vs render live.",
+      "argumentHint": "[passthrough]",
+      "path": "skills/prerender/SKILL.md"
+    },
+    {
+      "name": "rango",
+      "description": "Overview of @rangojs/router and available skills. Use when unsure which skill to reach for, starting a new task in a Rango app, or asking \"what can this router do\".",
+      "argumentHint": "",
+      "path": "skills/rango/SKILL.md"
+    },
+    {
+      "name": "react-compiler",
+      "description": "Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.",
+      "argumentHint": "",
+      "path": "skills/react-compiler/SKILL.md"
+    },
+    {
+      "name": "response-routes",
+      "description": "Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, or asking how to return raw JSON instead of RSC from a route.",
+      "argumentHint": "[json|text|html|xml|md|image|stream]",
+      "path": "skills/response-routes/SKILL.md"
+    },
+    {
+      "name": "route",
+      "description": "Define routes with path() in @rangojs/router. Use when creating a new page or route, or asking how to define a URL path and its handler.",
+      "argumentHint": "[pattern]",
+      "path": "skills/route/SKILL.md"
+    },
+    {
+      "name": "router-setup",
+      "description": "Create and configure the RSC router with createRouter. Use when bootstrapping a new Rango app, or configuring top-level router options like base path, cache store, or environment.",
+      "argumentHint": "[option]",
+      "path": "skills/router-setup/SKILL.md"
+    },
+    {
+      "name": "scripts",
+      "description": "Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle. Use when adding Google Tag Manager, an analytics snippet, or a third-party widget script to the page.",
+      "argumentHint": "[vendor]",
+      "path": "skills/scripts/SKILL.md"
+    },
+    {
+      "name": "server-actions",
+      "description": "Define and call server actions (`\"use server\"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation. Use when handling a form submission on the server, calling a server function from a client component, or needing optimistic UI after a mutation.",
+      "argumentHint": "[action]",
+      "path": "skills/server-actions/SKILL.md"
+    },
+    {
+      "name": "shell-manifest",
+      "description": "Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices. Use when a cached/prerendered shell needs to feed IDs or metadata to a live loader for freshly-fetched data.",
+      "argumentHint": "",
+      "path": "skills/shell-manifest/SKILL.md"
+    },
+    {
+      "name": "streams-and-websockets",
+      "description": "Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats. Use when streaming live updates to the browser, or opening a WebSocket connection from a route on Cloudflare Workers.",
+      "argumentHint": "[sse | websocket | agents]",
+      "path": "skills/streams-and-websockets/SKILL.md"
+    },
+    {
+      "name": "tailwind",
+      "description": "Set up Tailwind CSS v4 with the Document component and CSS imports. Use when adding Tailwind CSS to a Rango app, or Tailwind classes aren't being applied or generated.",
+      "argumentHint": "[setup]",
+      "path": "skills/tailwind/SKILL.md"
+    },
+    {
+      "name": "testing",
+      "description": "Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader or middleware, or asking how to test a route end-to-end in dev and production.",
+      "argumentHint": "[layer]",
+      "path": "skills/testing/SKILL.md"
+    },
+    {
+      "name": "theme",
+      "description": "Opt-in theme system with FOUC prevention for light/dark mode. Use when adding a light/dark mode toggle, or the page flashes the wrong theme on load (FOUC).",
+      "argumentHint": "[setup]",
+      "path": "skills/theme/SKILL.md"
+    },
+    {
+      "name": "typesafety",
+      "description": "Set up type-safe routes, params, and environment types in @rangojs/router. Use when route or search params aren't typed, TypeScript can't infer a loader's return type, or wiring up typed environment bindings.",
+      "argumentHint": "[setup]",
+      "path": "skills/typesafety/SKILL.md"
+    },
+    {
+      "name": "use-cache",
+      "description": "Function-level caching with the \"use cache\" directive for RSC data functions and components in @rangojs/router. Use when a single function or component should memoize its own output, not a whole route/segment subtree or HTTP response.",
+      "argumentHint": "[profile-name]",
+      "path": "skills/use-cache/SKILL.md"
+    },
+    {
+      "name": "vercel",
+      "description": "Deploy a Rango app to Vercel Functions (Build Output API v3). Use when deploying a Rango app to Vercel, or asking how the router works with Vercel Functions and the Build Output API.",
+      "argumentHint": "",
+      "path": "skills/vercel/SKILL.md"
+    },
+    {
+      "name": "view-transitions",
+      "description": "Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router. Use when navigation should animate smoothly between pages, or wiring up React View Transitions on a route or layout.",
+      "argumentHint": "[layout|route|parallel|intercept]",
+      "path": "skills/view-transitions/SKILL.md"
+    }
+  ]
+}

package/skills/client-urls/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: client-urls
+description: Define client-component route groups with clientUrls() in a "use client" module — no handlers, useLoader at read sites, client-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a "use client" file work.
+argument-hint: "[setup]"
+---
+
+# Client route groups with clientUrls()
+
+`clientUrls()` defines a route group inside a `"use client"` module. The
+components are client components, and there are **no handlers at all** — every
+data read is `useLoader` at the consumption site, waiting is scoped by the
+inline `<Suspense>` above each read, and per-loader `revalidate()` predicates
+run in the browser. The server shop pattern — `await ctx.use(ProductLoader)` in
+a handler — is pipeline-blocking by contract: no pending UI can ever cover that
+latency. `clientUrls()` makes that shape unrepresentable.
+
+This is the fastest-transition shape Rango has, and the natural fit for
+dashboard / admin / settings-style apps — high navigation frequency inside one
+layout, mostly tab/param/filter switches. Three things compound: the
+definition also matches in the browser, so a soft navigation presents
+optimistic pending UI immediately (`useOutlet().pending`) with no server
+round-trip to start; browser-run `revalidate()` predicates HOLD data across
+navigations that don't invalidate it (a tab switch re-runs nothing — only the
+decision crosses the wire); and any read that does refresh streams behind its
+own inline boundary instead of gating the commit. Add per-Link prefetch
+(`/links`) and a warmed click lands the complete page instantly.
+
+## Not this skill if…
+
+- You are defining server routes with handlers — that is `urls()`: see
+  `/route`.
+- You want loader mechanics (createLoader, caching a loader, fetchable
+  loaders) — see `/loader`. This skill covers what is _different_ inside
+  `clientUrls()`.
+- You want `useOutlet`/`useLoader`/`useHandle` reference — see `/hooks`.
+
+## The shape
+
+A `clientUrls()` module never ships route-definition code to the server as
+code. The Vite plugin discovers the module (it must be `"use client"`, contain
+`clientUrls(`, and **default-export** the result), evaluates it, and serializes
+a JSON **projection**: patterns, names, options, loader ids, which loaders are
+flagged, loading/transition presence. The server tree materializes real routes
+from that projection — loader stubs resolved by id from the server loader
+registry, your client components referenced but never executed server-side as
+route code. In the browser the same definition matches locally, so soft
+navigations inside the group present optimistic pending UI
+(`useOutlet().pending`) while the canonical partial Flight settles.
+
+Consequences you will hit:
+
+- **Components must be named function values.** `path("/x", HomePage)`, not
+  `path("/x", <HomePage />)` and not an inline arrow — the projection stores a
+  component reference, and an anonymous value throws
+  (`clientUrls() path() expects a named client component value`).
+- **Loaders must be `createLoader()` definitions** whose bodies are
+  `"use server"` — they execute on the server, addressed by id; the client
+  module only imports the definition object.
+- **Everything in the definition must be JSON-projectable.** That is why the
+  unsupported helpers below are rejected rather than silently dropped.
+
+## Defining and mounting
+
+```tsx
+// src/urls/shop.client.tsx
+"use client";
+
+import { Suspense } from "react";
+import { clientUrls, useLoader, Link } from "@rangojs/router/client";
+import { ProductsLoader, ProductLoader } from "@/loaders/products.js";
+
+function ShopLayout() {
+  /* useOutlet().content + chrome */
+}
+function ShopIndex() {
+  /* <Suspense><Grid/></Suspense> */
+}
+function ProductPage() {
+  /* useLoader(ProductLoader) under Suspense */
+}
+
+export default clientUrls(({ path, layout, loader, revalidate }) => [
+  layout(ShopLayout, () => [
+    path("/", ShopIndex, { name: "index" }, () => [loader(ProductsLoader)]),
+    path("/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader, () => [
+        revalidate(
+          ({
+            isAction,
+            currentParams,
+            nextParams,
+            defaultShouldRevalidate,
+          }) => {
+            if (isAction) return false;
+            return currentParams.slug !== nextParams.slug
+              ? defaultShouldRevalidate
+              : false;
+          },
+        ),
+      ]),
+    ]),
+  ]),
+]);
+```
+
+Mount it from the server tree like any module:
+
+```tsx
+// src/urls/index.tsx (server)
+import shopUrls from "./shop.client.js";
+
+include("/shop", shopUrls, { name: "shop" });
+```
+
+Route names compose through the include (`shop.index`, `shop.product`) and
+flow into the generated route map, so `href`/`reverse` and `Handler<"...">`
+typing work exactly as for server routes (`/typesafety`).
+
+## Helpers: what exists inside clientUrls()
+
+| Helper         | Notes                                                                                                                                                          |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see /ppr skill; loader routes need `loading()` or capture refuses); no response variants |
+| `layout()`     | Must contain at least one `path()`                                                                                                                             |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                         |
+| `loading()`    | Route/layout-level pending UI; inline `<Suspense>` at read sites is usually better                                                                             |
+| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
+| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
+
+`include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
+`notFoundBoundary` **throw** — and that is a design position, not a gap.
+Client route groups are a PERFORMANCE surface (instant presentation, held
+data, streaming reads), not full-feature routing; the server tree around the
+mount is the full-feature router. Put those helpers at or around the
+`include()` mount in the server `urls()` tree: middleware wrapping the mount
+runs for every route in the group; a `notFoundBoundary()` on an enclosing
+server layout catches loader-thrown `notFound()` from the group. (Caching
+still reaches the group's data the right way: `"use cache"` inside a loader
+body — the loaders stay the live layer, the expensive function is what
+caches.)
+
+Boundaries are a deliberate exclusion, not a projection limitation: the
+server-tree boundary around the mount gives group-scoped custom UI with the
+uniform server-resolved envelope (PE/no-JS correct), and INSIDE the group
+plain React error boundaries just work — every component is a client
+component, and a streamed loader rejection throws to the boundary above its
+`useLoader` read (siblings keep reading it from `error`). Per-read boundary +
+inline Suspense is the clientUrls idiom; a route-level DSL boundary would be
+the same regression `loading()` is relative to inline Suspense.
+
+## Outer layouts and middleware across group navigations
+
+With the common shape — `layout(<AdminRscLayout />, () => [middleware(requireAdmin), include("/admin", adminUrls)])` — middleware and layout handlers ride
+DIFFERENT schedules:
+
+- **Middleware runs on EVERY canonical request**, not just the first
+  encounter. Every navigation inside the group — including a tab switch whose
+  loaders all hold — still sends the canonical partial request (it commits
+  URL/history and carries the revalidation decisions), and middleware wraps
+  each one: `requireAdmin` re-authorizes every navigation, and its
+  `ctx.set()` variables are fresh for the group's loaders on every pass. The
+  instant feel comes from held data and optimistic presentation, not from
+  skipping the server.
+- **The outer layout handler does NOT re-run on within-group navigations** —
+  partial rendering holds its segment (and the parent chain skips on actions
+  by default). Layout-rendered data that must track the group belongs in
+  middleware `ctx.set()`, not the layout body.
+- The only thing that precedes middleware is the optimistic branch
+  (destination `loading()` / `useOutlet().pending`) — presentation, never
+  authorization.
+
+All three pinned by dev + production e2e in the router repository (a
+middleware-stamped header per request, a layout run-count stamp held across
+navigations).
+
+## Revalidation runs in the browser
+
+A server-tree `revalidate()` predicate executes on the server. A `clientUrls()`
+predicate is client-module code, so it executes **in the browser** with
+client-computable args — `currentUrl`, `nextUrl`, `currentParams`,
+`nextParams`, `defaultShouldRevalidate`, `stale`, `isAction`, `actionId` — and
+only its _decision_ crosses the wire with the navigation request. Requests that
+carry no decisions (no-JS, progressive enhancement, prefetch, document loads)
+follow the locked server defaults.
+
+Two scars worth copying:
+
+- A blunt `() => false` keeps serving the OLD product on product→product
+  navigations (same route, new param). Make predicates param-sensitive:
+  return `defaultShouldRevalidate` when the identifying param changed.
+- One action, per-loader outcomes: a cart badge loader revalidates on actions
+  (`isAction ? defaultShouldRevalidate : false`) while product/related loaders
+  hold — three freshness outcomes in a single commit, decided per loader.
+
+## Loaders are full citizens: signals and handles
+
+Everything a DSL loader can do in the server tree works here — the loader body
+is server code either way.
+
+**Authority signals.** A loader may `throw notFound()` or
+`throw redirect(url)`:
+
+```ts
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const moved = LEGACY_SLUGS[ctx.params.slug];
+  if (moved) throw redirect(`/shop/product/${moved}`);
+  if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);
+  return getProduct(ctx.params.slug);
+});
+```
+
+On a document load, `notFound()` streams the resolved not-found UI in the
+envelope and _opportunistically_ sets a real 404 status — the status write only
+wins if the rejection settles before the document Response is constructed (a
+fast, pre-fetch existence check usually wins; see `ssr: false` below
+for the deterministic version). On navigations the 404 UI swaps in with the
+URL preserved. A loader `redirect()` is always a client-side navigate — there
+is no document-lane 302 from loaders; pre-stream redirect authority belongs to
+middleware.
+
+**Handle writes.** `ctx.use(Handle)` from the loader body is the WRITE, with
+handler parity — `ctx.use(Meta)({ title })` pushes exactly like a handler
+push. Reads moved to `ctx.get(handle)`, gated behind `await ctx.rendered()`.
+Delivery follows the race model: pushes that settle before the handler barrier
+ride the SSR handle snapshot; later ones stream and apply post-hydration
+(document loads) or progressively (navigations). See `/loader` for the full
+contract.
+
+## `ssr: false` — the SSR-completeness opt-in
+
+By default every loader streams on every render, so nothing a slow loader
+produces is _guaranteed_ to be in the SSR'd HTML — data SSRs as the Suspense
+fallback, a late handle push applies post-hydration, a late `notFound()` loses
+the status race. When the loader feeds something that must exist in the
+document — `<head>` meta via a handle, or a real 404 status — flag it:
+
+```ts
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader, { ssr: false }, () => [revalidate(productData)]),
+  loader(RelatedLoader),   // untouched: still streams behind its boundary
+]),
+```
+
+The knob mirrors `loading(fallback, { ssr: false })` — SSR delivery is off
+for this loader, so nothing of it is left to stream in the document: document
+renders await this loader before first flush (data settled — no fallback
+paints; handle pushes beat the barrier snapshot; a thrown `notFound()` is a
+deterministic real 404, no warm-up race); client navigations stream exactly as
+before. Scoped per loader — the flagged loader awaits only itself, siblings
+keep streaming.
+
+Constraints:
+
+- A flagged loader must not `await ctx.rendered()` (or read handles via
+  `ctx.get(handle)`, which rendered() gates) — the document render awaits the
+  loader _before_ the render barrier resolves, so that wait is a cycle by
+  construction. It throws a deadlock error naming the fix.
+- `intercept()` loaders reject the flag — intercepts render on client
+  navigations only, so a document-render await can never apply.
+- It does not change PPR capture behavior: capture renders mask loaders and
+  skip the await.
+
+Every document load pays the flagged loader's latency before first byte —
+that is the point, but it is a real cost. Keep flagged loaders fast (existence
+checks before expensive fetches) and flag the loaders that need it, not the
+route.
+
+Pinned end to end by dev + production e2e in the router repository.
+
+## Intercepts
+
+```tsx
+export default clientUrls(({ path, intercept, loader, loading }) => [
+  path("/items", ItemsIndex, { name: "index" }),
+  path("/items/:id", ItemDetail, { name: "detail" }),
+  intercept("@modal", ".detail", ItemModal, () => [
+    loader(ItemLoader),
+    loading(<ModalSkeleton />),
+  ]),
+]);
+```
+
+Compared to the server `intercept()` (`/intercept`): the target must be a
+dot-local NAMED route in the same definition, there is no `when` selector and
+no middleware, and the use callback accepts `loader()`/`loading()` only —
+every field must be JSON-projectable. Scoping is module-local: only
+navigations originating inside this `clientUrls()` group render the intercept;
+a hard load of the target URL renders the full route.
+
+## Pitfalls
+
+- **Duplicate patterns or names throw** at definition time, per definition.
+- **`layout()` with no `path()` inside throws** — a client layout exists only
+  to wrap routes.
+- **`loading()` vs inline Suspense:** same-route SEARCH navigations
+  (filters, tabs) hold previous content by default — the canonical commit
+  runs in a `startTransition` when no new segments mount, and the wrapping
+  layout sees `useOutlet().pending === true` for the held window; a
+  route-level `loading()` no longer re-flashes there. PARAM navigations
+  still remount (fresh skeleton, fresh state) unless the route declares
+  `transition()` — that opt-in drops the param from the segment key. Inline
+  `<Suspense>` above each `useLoader` read is still the finer-grained tool
+  when different reads on one route should wait independently.
+- **Two parallel loaders with equal latency look "SSR'd" together.** Loaders
+  kick off in parallel, so awaiting one (`ssr: false`) gives
+  same-or-faster siblings time to settle coincidentally. Do not read "it was
+  in the HTML once" as a guarantee — only the flagged loader is guaranteed.
+- **Hook semantics shift inside a group.** `usePathname` is ABSOLUTE (mount
+  included) — never compare it to your own `path()` patterns; build local
+  links with `useHref()` (`groupHref("/items/1")` composes the mount).
+  `useRouter().push("cart")` (RELATIVE,
+  no leading slash) resolves against the mount; `push("/x")` stays
+  app-absolute by design (never auto-prefixed). `useSearchParams` carries REAL
+  values during SSR (live request seeds the SSR store; on ppr routes the
+  capture/resume renders seed the shell key's own sorted search — search is
+  part of shell identity, so static-part reads are legal).
+  `useNavigation`/`useLinkStatus` report the canonical nav, but a reader
+  inside optimistically-swapped content (destination WITH `loading()`)
+  unmounts at click — put status readers in surviving chrome. Errors: wrap
+  throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
+  (route-independent lane; `revalidate()` deliberately not consulted).
+  Pinned in the router repo's client-urls hook-probe e2e.
+- **Editing the module in dev:** projections refresh via HMR discovery; if a
+  route-shape edit ever serves stale routes, restart dev — and if you are
+  developing the router itself, rebuild the router dist before `pnpm dev`
+  (the discovery machinery ships compiled).
+
+## Reference app
+
+The router repository (not shipped in this package) carries a canonical
+consumer at `tests/vite-rsc-demo/src/urls/client-shop.client.tsx`: layout +
+index + product routes, param-sensitive predicates, action-scoped cart
+revalidation, loader-thrown `notFound()`/`redirect()`, loader-written
+Meta/Breadcrumbs, viewport prefetch on cards, and the `ssr: false`
+fixtures — with e2e suites next to it pinning each contract in dev and
+production. The sections above are self-contained; the app is corroboration,
+not required reading.