npm - @rangojs/router - Versions diffs - 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c - Mend

@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (392) hide show

package/AGENTS.md +8 -0
package/README.md +126 -16
package/dist/bin/rango.js +319 -95
package/dist/testing/vitest.js +82 -0
package/dist/vite/index.js +2724 -1053
package/package.json +68 -14
package/skills/api-client/SKILL.md +211 -0
package/skills/breadcrumbs/SKILL.md +64 -2
package/skills/bundle-analysis/SKILL.md +159 -0
package/skills/cache-guide/SKILL.md +224 -32
package/skills/caching/SKILL.md +279 -17
package/skills/composability/SKILL.md +27 -3
package/skills/css/SKILL.md +76 -0
package/skills/debug-manifest/SKILL.md +4 -2
package/skills/document-cache/SKILL.md +78 -55
package/skills/handler-use/SKILL.md +11 -9
package/skills/hooks/SKILL.md +243 -29
package/skills/host-router/SKILL.md +83 -23
package/skills/i18n/SKILL.md +276 -0
package/skills/intercept/SKILL.md +68 -19
package/skills/layout/SKILL.md +13 -9
package/skills/links/SKILL.md +190 -23
package/skills/loader/SKILL.md +235 -9
package/skills/middleware/SKILL.md +18 -10
package/skills/migrate-nextjs/SKILL.md +43 -19
package/skills/migrate-react-router/SKILL.md +8 -2
package/skills/mime-routes/SKILL.md +28 -1
package/skills/observability/SKILL.md +172 -0
package/skills/parallel/SKILL.md +18 -7
package/skills/prerender/SKILL.md +65 -60
package/skills/rango/SKILL.md +251 -24
package/skills/react-compiler/SKILL.md +168 -0
package/skills/response-routes/SKILL.md +115 -48
package/skills/route/SKILL.md +46 -5
package/skills/router-setup/SKILL.md +30 -8
package/skills/scripts/SKILL.md +179 -0
package/skills/server-actions/SKILL.md +775 -0
package/skills/tailwind/SKILL.md +27 -3
package/skills/testing/SKILL.md +130 -0
package/skills/testing/bindings.md +103 -0
package/skills/testing/cache-prerender.md +127 -0
package/skills/testing/client-components.md +124 -0
package/skills/testing/e2e-parity.md +125 -0
package/skills/testing/flight.md +91 -0
package/skills/testing/handles.md +129 -0
package/skills/testing/loader.md +128 -0
package/skills/testing/middleware.md +99 -0
package/skills/testing/render-handler.md +122 -0
package/skills/testing/response-routes.md +95 -0
package/skills/testing/reverse-and-types.md +84 -0
package/skills/testing/server-actions.md +107 -0
package/skills/testing/server-tree.md +128 -0
package/skills/testing/setup.md +123 -0
package/skills/typesafety/SKILL.md +322 -29
package/skills/use-cache/SKILL.md +57 -14
package/skills/view-transitions/SKILL.md +337 -0
package/src/__augment-tests__/augment.ts +81 -0
package/src/__augment-tests__/augmented.check.ts +116 -0
package/src/__internal.ts +0 -65
package/src/browser/action-coordinator.ts +53 -36
package/src/browser/action-fence.ts +47 -0
package/src/browser/app-shell.ts +39 -0
package/src/browser/connection-warmup.ts +134 -0
package/src/browser/cookie-name.ts +140 -0
package/src/browser/event-controller.ts +192 -150
package/src/browser/history-state.ts +21 -0
package/src/browser/index.ts +3 -3
package/src/browser/invalidate-client-cache.ts +52 -0
package/src/browser/navigation-bridge.ts +94 -25
package/src/browser/navigation-client.ts +121 -84
package/src/browser/navigation-store-handle.ts +38 -0
package/src/browser/navigation-store.ts +115 -67
package/src/browser/navigation-transaction.ts +9 -59
package/src/browser/network-error-handler.ts +34 -7
package/src/browser/partial-update.ts +147 -128
package/src/browser/prefetch/cache.ts +107 -56
package/src/browser/prefetch/fetch.ts +204 -34
package/src/browser/prefetch/queue.ts +6 -3
package/src/browser/rango-state.ts +158 -76
package/src/browser/react/Link.tsx +30 -7
package/src/browser/react/NavigationProvider.tsx +283 -118
package/src/browser/react/ScrollRestoration.tsx +10 -6
package/src/browser/react/deferred-handle-resolution.ts +75 -0
package/src/browser/react/filter-segment-order.ts +66 -7
package/src/browser/react/index.ts +0 -48
package/src/browser/react/location-state-shared.ts +178 -8
package/src/browser/react/location-state.ts +39 -14
package/src/browser/react/use-action.ts +6 -15
package/src/browser/react/use-handle.ts +17 -14
package/src/browser/react/use-href.tsx +8 -1
package/src/browser/react/use-link-status.ts +33 -8
package/src/browser/react/use-navigation.ts +10 -5
package/src/browser/react/use-params.ts +11 -11
package/src/browser/react/use-reverse.ts +106 -0
package/src/browser/react/use-router.ts +25 -3
package/src/browser/react/use-search-params.ts +0 -5
package/src/browser/react/use-segments.ts +11 -21
package/src/browser/response-adapter.ts +99 -8
package/src/browser/rsc-router.tsx +91 -24
package/src/browser/scroll-restoration.ts +30 -17
package/src/browser/segment-structure-assert.ts +2 -2
package/src/browser/server-action-bridge.ts +214 -55
package/src/browser/types.ts +80 -9
package/src/browser/validate-redirect-origin.ts +43 -16
package/src/build/collect-fallback-refs.ts +107 -0
package/src/build/generate-manifest.ts +60 -35
package/src/build/generate-route-types.ts +2 -1
package/src/build/index.ts +8 -2
package/src/build/prefix-tree-utils.ts +123 -0
package/src/build/route-trie.ts +117 -14
package/src/build/route-types/ast-route-extraction.ts +15 -8
package/src/build/route-types/codegen.ts +16 -5
package/src/build/route-types/include-resolution.ts +117 -23
package/src/build/route-types/param-extraction.ts +6 -3
package/src/build/route-types/per-module-writer.ts +22 -6
package/src/build/route-types/router-processing.ts +55 -28
package/src/build/route-types/scan-filter.ts +1 -1
package/src/build/route-types/source-scan.ts +216 -0
package/src/build/runtime-discovery.ts +9 -20
package/src/cache/cache-error.ts +104 -0
package/src/cache/cache-key-utils.ts +29 -13
package/src/cache/cache-policy.ts +108 -34
package/src/cache/cache-runtime.ts +224 -41
package/src/cache/cache-scope.ts +188 -82
package/src/cache/cache-tag.ts +103 -0
package/src/cache/cf/cf-base64.ts +33 -0
package/src/cache/cf/cf-cache-constants.ts +127 -0
package/src/cache/cf/cf-cache-store.ts +1989 -378
package/src/cache/cf/cf-cache-types.ts +349 -0
package/src/cache/cf/cf-kv-utils.ts +46 -0
package/src/cache/cf/cf-tag-marker-memo.ts +105 -0
package/src/cache/cf/index.ts +6 -16
package/src/cache/document-cache.ts +89 -21
package/src/cache/handle-snapshot.ts +70 -0
package/src/cache/index.ts +10 -20
package/src/cache/memory-segment-store.ts +136 -37
package/src/cache/profile-registry.ts +46 -31
package/src/cache/read-through-swr.ts +56 -12
package/src/cache/segment-codec.ts +9 -17
package/src/cache/tag-invalidation.ts +230 -0
package/src/cache/types.ts +37 -100
package/src/client.rsc.tsx +44 -21
package/src/client.tsx +36 -61
package/src/cloudflare/index.ts +11 -0
package/src/cloudflare/tracing.ts +109 -0
package/src/component-utils.ts +19 -0
package/src/components/DefaultDocument.tsx +8 -2
package/src/context-var.ts +18 -6
package/src/decode-loader-results.ts +52 -0
package/src/defer.ts +196 -0
package/src/deps/ssr.ts +0 -1
package/src/encode-kv.ts +49 -0
package/src/errors.ts +30 -4
package/src/escape-script.ts +52 -0
package/src/handle.ts +31 -23
package/src/handles/MetaTags.tsx +62 -19
package/src/handles/Scripts.tsx +183 -0
package/src/handles/breadcrumbs.ts +37 -8
package/src/handles/is-thenable.ts +19 -0
package/src/handles/meta.ts +51 -40
package/src/handles/script.ts +244 -0
package/src/host/cookie-handler.ts +9 -60
package/src/host/errors.ts +0 -24
package/src/host/index.ts +8 -2
package/src/host/pattern-matcher.ts +23 -52
package/src/host/router.ts +107 -99
package/src/host/testing.ts +40 -27
package/src/host/types.ts +37 -4
package/src/host/utils.ts +1 -1
package/src/href-client.ts +137 -22
package/src/index.rsc.ts +96 -12
package/src/index.ts +94 -14
package/src/internal-debug.ts +11 -10
package/src/loader-store.ts +500 -0
package/src/loader.rsc.ts +20 -13
package/src/loader.ts +12 -11
package/src/missing-id-error.ts +68 -0
package/src/outlet-context.ts +1 -1
package/src/outlet-provider.tsx +1 -5
package/src/prerender/param-hash.ts +16 -16
package/src/prerender/store.ts +32 -37
package/src/prerender.ts +61 -6
package/src/redirect-origin.ts +100 -0
package/src/regex-escape.ts +8 -0
package/src/render-error-thrower.tsx +20 -0
package/src/response-utils.ts +34 -0
package/src/reverse.ts +65 -40
package/src/root-error-boundary.tsx +1 -19
package/src/route-content-wrapper.tsx +19 -77
package/src/route-definition/dsl-helpers.ts +304 -309
package/src/route-definition/helper-factories.ts +28 -140
package/src/route-definition/helpers-types.ts +82 -55
package/src/route-definition/index.ts +1 -2
package/src/route-definition/redirect.ts +44 -11
package/src/route-definition/resolve-handler-use.ts +12 -1
package/src/route-definition/use-item-types.ts +29 -0
package/src/route-map-builder.ts +0 -16
package/src/route-types.ts +19 -46
package/src/router/basename.ts +14 -0
package/src/router/content-negotiation.ts +73 -25
package/src/router/error-handling.ts +45 -18
package/src/router/find-match.ts +44 -23
package/src/router/handler-context.ts +27 -43
package/src/router/instrument.ts +350 -0
package/src/router/intercept-resolution.ts +39 -20
package/src/router/lazy-includes.ts +10 -47
package/src/router/loader-resolution.ts +155 -72
package/src/router/logging.ts +0 -6
package/src/router/manifest.ts +18 -29
package/src/router/match-api.ts +9 -24
package/src/router/match-context.ts +0 -22
package/src/router/match-handlers.ts +58 -58
package/src/router/match-middleware/background-revalidation.ts +40 -24
package/src/router/match-middleware/cache-lookup.ts +159 -285
package/src/router/match-middleware/cache-store.ts +64 -52
package/src/router/match-middleware/intercept-resolution.ts +0 -22
package/src/router/match-middleware/segment-resolution.ts +0 -22
package/src/router/match-pipelines.ts +1 -42
package/src/router/match-result.ts +44 -74
package/src/router/metrics.ts +0 -34
package/src/router/middleware-types.ts +7 -134
package/src/router/middleware.ts +247 -166
package/src/router/navigation-snapshot.ts +0 -51
package/src/router/params-util.ts +23 -0
package/src/router/pattern-matching.ts +85 -94
package/src/router/prefetch-cache-ttl.ts +51 -0
package/src/router/prerender-match.ts +104 -65
package/src/router/preview-match.ts +3 -1
package/src/router/request-classification.ts +28 -62
package/src/router/revalidation.ts +123 -73
package/src/router/route-snapshot.ts +0 -1
package/src/router/router-context.ts +3 -28
package/src/router/router-interfaces.ts +83 -35
package/src/router/router-options.ts +136 -5
package/src/router/router-registry.ts +2 -5
package/src/router/segment-resolution/fresh.ts +97 -84
package/src/router/segment-resolution/helpers.ts +86 -6
package/src/router/segment-resolution/loader-cache.ts +76 -39
package/src/router/segment-resolution/revalidation.ts +272 -320
package/src/router/segment-resolution/static-store.ts +19 -5
package/src/router/segment-resolution/streamed-handler-telemetry.ts +52 -0
package/src/router/segment-resolution/view-transition-default.ts +56 -0
package/src/router/segment-resolution.ts +5 -1
package/src/router/segment-wrappers.ts +6 -5
package/src/router/state-cookie-name.ts +33 -0
package/src/router/substitute-pattern-params.ts +56 -0
package/src/router/telemetry-otel.ts +161 -199
package/src/router/telemetry.ts +96 -19
package/src/router/timeout.ts +0 -20
package/src/router/tracing.ts +206 -0
package/src/router/trie-matching.ts +162 -64
package/src/router/types.ts +9 -63
package/src/router/url-params.ts +0 -5
package/src/router.ts +110 -55
package/src/rsc/handler-context.ts +3 -2
package/src/rsc/handler.ts +264 -220
package/src/rsc/helpers.ts +100 -6
package/src/rsc/index.ts +2 -5
package/src/rsc/json-route-result.ts +38 -0
package/src/rsc/loader-fetch.ts +114 -38
package/src/rsc/manifest-init.ts +28 -41
package/src/rsc/origin-guard.ts +39 -25
package/src/rsc/progressive-enhancement.ts +117 -11
package/src/rsc/redirect-guard.ts +99 -0
package/src/rsc/response-cache-serve.ts +238 -0
package/src/rsc/response-error.ts +79 -12
package/src/rsc/response-route-handler.ts +88 -188
package/src/rsc/rsc-rendering.ts +98 -76
package/src/rsc/runtime-warnings.ts +23 -10
package/src/rsc/server-action.ts +281 -117
package/src/rsc/ssr-setup.ts +16 -0
package/src/rsc/transition-gate.ts +89 -0
package/src/rsc/types.ts +23 -5
package/src/runtime-env.ts +18 -0
package/src/search-params.ts +35 -30
package/src/segment-loader-promise.ts +31 -4
package/src/segment-system.tsx +254 -143
package/src/serialize.ts +243 -0
package/src/server/context.ts +163 -51
package/src/server/cookie-parse.ts +32 -0
package/src/server/cookie-store.ts +80 -5
package/src/server/handle-store.ts +21 -38
package/src/server/loader-registry.ts +33 -42
package/src/server/request-context.ts +287 -178
package/src/ssr/index.tsx +21 -16
package/src/static-handler.ts +10 -13
package/src/testing/cache-status.ts +162 -0
package/src/testing/collect-handle.ts +40 -0
package/src/testing/dispatch.ts +701 -0
package/src/testing/dom.entry.ts +22 -0
package/src/testing/e2e/fixture.ts +188 -0
package/src/testing/e2e/index.ts +128 -0
package/src/testing/e2e/matchers.ts +35 -0
package/src/testing/e2e/page-helpers.ts +272 -0
package/src/testing/e2e/parity.ts +387 -0
package/src/testing/e2e/server.ts +195 -0
package/src/testing/flight-matchers.ts +97 -0
package/src/testing/flight-normalize.ts +11 -0
package/src/testing/flight-runtime.d.ts +57 -0
package/src/testing/flight-tree.ts +682 -0
package/src/testing/flight.entry.ts +52 -0
package/src/testing/flight.ts +257 -0
package/src/testing/generated-routes.ts +183 -0
package/src/testing/index.ts +105 -0
package/src/testing/internal/context.ts +371 -0
package/src/testing/internal/flight-client-globals.ts +30 -0
package/src/testing/internal/seed-vars.ts +54 -0
package/src/testing/render-handler.ts +357 -0
package/src/testing/render-route.tsx +581 -0
package/src/testing/run-loader.ts +385 -0
package/src/testing/run-middleware.ts +205 -0
package/src/testing/run-transition-when.ts +164 -0
package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
package/src/testing/vitest-stubs/version.ts +5 -0
package/src/testing/vitest.ts +305 -0
package/src/theme/ThemeProvider.tsx +20 -58
package/src/theme/ThemeScript.tsx +7 -9
package/src/theme/constants.ts +52 -13
package/src/theme/index.ts +0 -7
package/src/theme/theme-context.ts +1 -5
package/src/theme/theme-script.ts +22 -21
package/src/theme/use-theme.ts +0 -3
package/src/types/boundaries.ts +0 -35
package/src/types/cache-types.ts +13 -4
package/src/types/error-types.ts +30 -90
package/src/types/global-namespace.ts +54 -41
package/src/types/handler-context.ts +110 -62
package/src/types/index.ts +3 -10
package/src/types/loader-types.ts +11 -9
package/src/types/request-scope.ts +112 -0
package/src/types/route-config.ts +6 -50
package/src/types/route-entry.ts +0 -6
package/src/types/segments.ts +135 -14
package/src/urls/include-helper.ts +9 -56
package/src/urls/index.ts +1 -11
package/src/urls/path-helper-types.ts +29 -12
package/src/urls/path-helper.ts +17 -106
package/src/urls/pattern-types.ts +36 -19
package/src/urls/response-types.ts +22 -29
package/src/urls/type-extraction.ts +58 -139
package/src/urls/urls-function.ts +1 -19
package/src/use-loader.tsx +292 -107
package/src/vite/debug.ts +185 -0
package/src/vite/discovery/bundle-postprocess.ts +8 -7
package/src/vite/discovery/discover-routers.ts +126 -85
package/src/vite/discovery/discovery-errors.ts +194 -0
package/src/vite/discovery/gate-state.ts +171 -0
package/src/vite/discovery/prerender-collection.ts +96 -68
package/src/vite/discovery/route-types-writer.ts +40 -84
package/src/vite/discovery/self-gen-tracking.ts +27 -1
package/src/vite/discovery/state.ts +44 -0
package/src/vite/discovery/virtual-module-codegen.ts +14 -34
package/src/vite/index.ts +2 -0
package/src/vite/inject-client-debug.ts +36 -0
package/src/vite/plugin-types.ts +126 -8
package/src/vite/plugins/cjs-to-esm.ts +16 -19
package/src/vite/plugins/client-ref-dedup.ts +16 -11
package/src/vite/plugins/client-ref-hashing.ts +28 -15
package/src/vite/plugins/cloudflare-protocol-stub.ts +1 -21
package/src/vite/plugins/expose-action-id.ts +48 -95
package/src/vite/plugins/expose-id-utils.ts +88 -55
package/src/vite/plugins/expose-ids/export-analysis.ts +101 -34
package/src/vite/plugins/expose-ids/handler-transform.ts +11 -90
package/src/vite/plugins/expose-ids/loader-transform.ts +14 -24
package/src/vite/plugins/expose-ids/router-transform.ts +118 -29
package/src/vite/plugins/expose-internal-ids.ts +505 -486
package/src/vite/plugins/performance-tracks.ts +26 -25
package/src/vite/plugins/refresh-cmd.ts +1 -1
package/src/vite/plugins/use-cache-transform.ts +73 -83
package/src/vite/plugins/version-injector.ts +40 -29
package/src/vite/plugins/version-plugin.ts +37 -40
package/src/vite/plugins/virtual-entries.ts +39 -25
package/src/vite/rango.ts +109 -118
package/src/vite/router-discovery.ts +718 -119
package/src/vite/utils/ast-handler-extract.ts +26 -35
package/src/vite/utils/banner.ts +1 -1
package/src/vite/utils/bundle-analysis.ts +10 -15
package/src/vite/utils/client-chunks.ts +184 -0
package/src/vite/utils/directive-prologue.ts +40 -0
package/src/vite/utils/forward-user-plugins.ts +171 -0
package/src/vite/utils/manifest-utils.ts +4 -59
package/src/vite/utils/package-resolution.ts +20 -52
package/src/vite/utils/prerender-utils.ts +54 -39
package/src/vite/utils/shared-utils.ts +90 -41
package/src/browser/action-response-classifier.ts +0 -99
package/src/browser/react/use-client-cache.ts +0 -58
package/src/browser/shallow.ts +0 -40
package/src/handles/index.ts +0 -7
package/src/network-error-thrower.tsx +0 -23
package/src/router/middleware-cookies.ts +0 -55

package/skills/tailwind/SKILL.md CHANGED Viewed

@@ -37,7 +37,11 @@ export default defineConfig({
 ## Document Component
-Import the CSS file with `?url` to get a hashed URL, then preload and link it in `<head>`:
+Import the CSS file with `?url` to get a hashed URL, then preload and link it in
+`<head>`. Give the `<link rel="stylesheet">` a `precedence` prop so React 19
+manages it as a resource — de-duped by `href`, ordered, and loaded before paint
+(no flash of unstyled content). See
+[Stylesheets and cross-app navigation](#stylesheets-and-cross-app-navigation):
 ```tsx
 // src/document.tsx
@@ -51,8 +55,8 @@ export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
-        <link rel="preload" href={styles} as="style" />
-        <link rel="stylesheet" href={styles} />
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
         <MetaTags />
       </head>
       <body className="font-sans antialiased text-slate-900 bg-slate-50">
@@ -63,6 +67,26 @@ export function Document({ children }: { children: ReactNode }) {
 }
 ```
+## Stylesheets and cross-app navigation
+The `precedence` prop opts a `<link rel="stylesheet">` into React 19's managed
+stylesheet model — React de-duplicates it by `href`, orders it by precedence, and
+loads it before paint (avoiding a flash of unstyled content). It is the
+recommended way to render a stylesheet link, which is why the example above uses
+it. (A bare side-effect `import "./index.css"` also produces managed CSS via
+`@vitejs/plugin-rsc`, but carries an SSR-streaming caveat — prefer the `?url` +
+`<link precedence>` form for document CSS. See `/css`.)
+For **host-router** apps (`/host-router`), a client-side navigation that crosses
+an app boundary is a **full document load**, not a soft swap — the framework
+redirects on an app switch. So each app's document (its stylesheets, theme, meta)
+is always re-established cleanly by the target app's own load; you do not have to
+coordinate stylesheet `href`s or `precedence` across apps. (This replaced an
+earlier soft cross-app swap, under which a stylesheet shared across apps — every
+app's `@import "tailwindcss"` compiles to one hashed asset — could be dropped by
+React's by-`href` resource dedup if the apps disagreed on `precedence`. The full
+reload removes that footgun entirely.)
 The `?url` suffix tells Vite to return the processed CSS file's URL instead of injecting it as a side effect. This gives you a stable, hashed asset path that works in both development and production.
 ## Customizing the Theme

package/skills/testing/SKILL.md ADDED Viewed

@@ -0,0 +1,130 @@
+---
+name: testing
+description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement)
+argument-hint: [layer]
+---
+# Testing @rangojs/router apps
+Rango ships six consumer-facing testing entries, one per test runtime/dependency:
+`@rangojs/router/testing` (unit + integration, under a Vite-driven Vitest
+project), `@rangojs/router/testing/vitest` (the `rangoTestConfig`/`rangoTestAliases`
+setup preset), `@rangojs/router/testing/dom` (`renderRoute`, needs RTL + a DOM
+env), `@rangojs/router/testing/e2e` (the Playwright harness),
+`@rangojs/router/testing/flight` (real Flight, react-server condition only), and
+`@rangojs/router/testing/flight-matchers` (the Flight matchers).
+The hard problem in an RSC app is that the layer you reach for is dictated by
+**what the behavior touches** — a pure predicate is a one-line vitest test; a real
+async Server Component cannot be a plain node test at all. Pick the layer
+**first**, then the primitive. Reaching one layer too high (e2e for a reverse
+function) is slow; one too low (a node test for Flight) fails to compile or
+silently asserts nothing.
+This page is the router. Each primitive's full API (options, the seeded context
+your code receives, the return shape), a minimal recipe, and its caveats live in a
+dedicated sub-file linked from the decision tree below. Read the one for your case.
+> **Setup is the first wall.** The vitest projects, the `rangoTestConfig` vs
+> `rangoTestAliases` choice (Node >= 23), and the react-server `@rangojs/router ->
+index.rsc.ts` alias are all in [`./setup.md`](./setup.md). Read it before writing
+> `vitest.config.ts`. Platform bindings (`env.DB`/DO/R2) are your own double —
+> [`./bindings.md`](./bindings.md).
+For the long-form prose guide (setup walkthrough + migration), see
+[`docs/testing.md`](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md)
+(the `docs/` directory is not shipped in the published package, so this is an
+absolute link).
+## When to use
+Use this skill when adding or changing tests for a Rango app: a loader,
+middleware, a server action, a route map, a client component, a response route,
+cache/SWR behavior, prerender, or a navigation/PE flow.
+Two non-negotiable mandates (from the repo's `CLAUDE.md`, and they apply to
+consumer apps too):
+- **Every e2e covers BOTH dev and production.** A dev-only e2e is not acceptable.
+  Use `parityDescribe` — it generates the dev and production describes from one
+  body, so you cannot forget the prod half. See [`./e2e-parity.md`](./e2e-parity.md).
+- **Progressive-enhancement parity** is a first-class assertion. A form-driven
+  flow must produce the same observable result with JS on and JS off. Use
+  `expectParity`.
+## The read-first shape
+Four import roots, each matched to the dependency/runtime that can load it — this
+split is forced by hard walls, not preference:
+- `@rangojs/router/testing` — unit + integration primitives. Run these under a
+  **Vite-driven Vitest** project with the rango Vite plugin active (the router
+  internals import the `@rangojs/router:version` virtual; without the plugin, the
+  preset stubs it). References neither React, RTL, Playwright, nor the RSC runtime.
+- `@rangojs/router/testing/dom` — `renderRoute` (the RTL component stub). Kept
+  separate so the unit barrel stays free of React/RTL; it lazy-loads
+  `@testing-library/react` and needs a DOM env (happy-dom/jsdom).
+- `@rangojs/router/testing/e2e` — the Playwright harness. Kept separate so it
+  loads in a plain (non-Vite) Playwright runner; the helpers take your
+  `test`/`expect`, so this entry never imports `@playwright/test` at runtime.
+- `@rangojs/router/testing/flight` — real Flight rendering. Its serializer loads
+  only under the `react-server` node condition; pulling it elsewhere throws.
+The single rule that drives everything:
+> **If the behavior needs a real Flight render, it cannot be a plain vitest node
+> test.** It is either `renderToFlightString`/`renderServerTree`/`renderHandler`
+> (under the react-server vitest project) or an e2e test. There is no middle
+> ground in node.
+## Decision tree: behavior -> layer -> primitive
+Each primitive links to its sub-file (API + recipe + caveats).
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                     | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | -------------------------------- |
+| a pure function / `reverse` / `href` / a predicate (`revalidate`, `isAction`)                                                      | unit + types | [`reverse`/`@ts-expect-error`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                    | `@rangojs/router/testing`        |
+| a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
+| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                               | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                        | `@rangojs/router/testing/flight` |
+| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                        | `@rangojs/router/testing/e2e`    |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md) | `@rangojs/router/testing[/e2e]`  |
+| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                    | (any primitive's `env` option)   |
+Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
+`/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,
+`/typesafety`.
+## Sub-files
+- Cross-cutting: [`setup.md`](./setup.md), [`bindings.md`](./bindings.md)
+- Unit (node): [`loader.md`](./loader.md), [`middleware.md`](./middleware.md),
+  [`server-actions.md`](./server-actions.md), [`handles.md`](./handles.md),
+  [`reverse-and-types.md`](./reverse-and-types.md)
+- Unit (DOM): [`client-components.md`](./client-components.md)
+- RSC unit: [`flight.md`](./flight.md), [`server-tree.md`](./server-tree.md),
+  [`render-handler.md`](./render-handler.md)
+- Integration: [`response-routes.md`](./response-routes.md)
+- E2E: [`e2e-parity.md`](./e2e-parity.md), [`cache-prerender.md`](./cache-prerender.md)
+## Pre-push checklist (mirror CLAUDE.md)
+Before pushing, run all of these and fix any failure:
+1. `pnpm run typecheck` (or `pnpm exec tsc --noEmit`)
+2. `pnpm run test:unit` (node + DOM vitest)
+3. `pnpm run test:unit:rsc` (the react-server Flight project)
+4. `pnpm run lint`
+5. `pnpm run format`
+And: **every e2e has a production counterpart.** `parityDescribe` makes this
+automatic — if you wrote a plain `test.describe` for a behavior, convert it.

package/skills/testing/bindings.md ADDED Viewed

@@ -0,0 +1,103 @@
+# Testing platform bindings — your double is the seam
+**Layer:** cross-cutting (unit/integration) · **Seam:** the `env` option every primitive takes
+The node primitives test the router's seams; the moment your loader/middleware/action calls a **platform binding** (`env.DB`, a Durable Object stub, `env.R2`), you have crossed out of rango and into your app's I/O. The router machinery is real — what you seed is the binding double behind it, injected through `env`.
+## Where it plugs in
+rango ships **no doubles** for platform bindings — they are app- and schema-specific. You build the double and inject it through the `env` option that every primitive already accepts:
+- `runLoader(body, { env })`
+- `runMiddleware(fn, { request, env })`
+- `runInRequestContext(fn, { request, env })`
+- `renderHandler(handler, { request, env })`
+- `dispatch(router, { request, env })`
+- `renderToFlightString(el, { env })`
+Inside the run, `getRequestContext().env` (and anything that reads it — `cache()`, your loaders, your middleware) sees the object you passed.
+## Driver contract
+The work here is matching the binding's **driver contract**, not its public API. A double that satisfies the public surface but not the driver's wire shape mounts green and proves nothing.
+- **Per-method shapes.** `drizzle-orm/d1` serves SELECTs through `.raw()` and writes (INSERT/UPDATE/DELETE) through `.run()`. The two return different shapes and hit different code paths in the decoder. Model **both**.
+- **`.raw()` (reads).** Must serve **positional row arrays in schema-column order**, with the driver-level encodings so the decoder round-trips `Date`/JSON. NOT `{ column: value }` objects.
+- **`.run()` (writes).** Returns `{ success, meta }` — no rows — and bypasses the row responder entirely.
+## Recipe
+```ts
+import { describe, it, expect } from "vitest";
+import {
+  runLoader,
+  runMiddleware,
+  runInRequestContext,
+} from "@rangojs/router/testing";
+import { bundleLoaderBody } from "../app/loaders";
+import { requireMembership } from "../app/middleware";
+import { authorizeAction } from "../app/actions";
+// A D1Database double satisfying drizzle-orm/d1's driver contract.
+// rango ships no double for D1 — build your own to match the driver.
+const fakeD1 = {
+  prepare: () => ({
+    // .raw() serves positional rows in schema-column order, driver-encoded.
+    raw: async () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+    // .run() returns { success, meta }, no rows.
+    run: async () => ({ success: true, meta: { changes: 1 } }),
+    all: async () => ({ results: [], success: true, meta: {} }),
+    first: async () => null,
+    bind: (..._args: unknown[]) => ({
+      raw: async () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+      run: async () => ({ success: true, meta: { changes: 1 } }),
+      all: async () => ({ results: [], success: true, meta: {} }),
+      first: async () => null,
+    }),
+  }),
+  batch: async (stmts: unknown[]) =>
+    stmts.map(() => ({ results: [], success: true, meta: {} })),
+  exec: async (_sql: string) => ({ count: 0, duration: 0 }),
+};
+describe("bindings seam", () => {
+  it("loader reads through env.DB", async () => {
+    const result = await runLoader(bundleLoaderBody, { env: { DB: fakeD1 } });
+    expect(result).toMatchObject({ slug: "acme" });
+  });
+  it("middleware reads through env.DB", async () => {
+    const { nextCalled, response } = await runMiddleware(requireMembership, {
+      request: "/t/acme/edit",
+      env: { DB: fakeD1 },
+    });
+    expect(nextCalled).toBe(1); // membership passed, chain continued
+    expect(response.status).toBe(200);
+  });
+  it("action reads through env.DB", async () => {
+    const { result } = await runInRequestContext(
+      () => authorizeAction({ id: 1 }),
+      {
+        env: { DB: fakeD1 },
+        request: "/t/acme/edit",
+      },
+    );
+    expect(result).toBe(true);
+  });
+});
+```
+## Caveats
+- rango ships **no doubles** for platform bindings (`env.DB`, Durable Objects, `env.R2`) by design — they are app- and schema-specific. Inject your own double through the `env` option every primitive takes.
+- This is usually the **single biggest effort** in a consumer unit suite, and the work is matching the **driver contract**, not the binding's public API.
+- `drizzle-orm/d1`: a `D1Database` double must serve **positional row arrays in schema-column order** for drizzle's `.raw()` path (with driver-level encodings so the decoder round-trips `Date`/JSON), NOT `{ column: value }` objects — an object-shaped double returns silently-wrong or empty rows.
+- The contract is **per-method**: SELECTs go through `.raw()` (positional rows); writes (INSERT/UPDATE/DELETE) go through `.run()`, which returns `{ success, meta }` (no rows) and bypasses the row responder entirely. Model **both** paths — a read-only `.raw()` double silently no-ops every write.
+- Keep the double at the **binding boundary**; never mock a rango primitive to dodge building it.
+## See also
+- (cross-cutting)
+- Siblings: `./loader.md`, `./middleware.md`, `./server-actions.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"

package/skills/testing/cache-prerender.md ADDED Viewed

@@ -0,0 +1,127 @@
+# Testing cache / SWR / prerender — assertCacheStatus
+**Layer:** e2e + signal · **Import:** the cache-status helpers (`assertCacheStatus`/`parseCacheHeader`/`createCacheSink`/`assertCacheDecision`/`filterCacheDecisions`) are re-exported from BOTH entries — use `@rangojs/router/testing` from a Vitest unit/integration test, and `@rangojs/router/testing/e2e` from a plain Playwright runner (the e2e barrel avoids the Vite-only virtuals the main barrel pulls in). · **DSL it tests:** `cache()` / `"use cache"` / loader cache / `Prerender(...)` (see `/caching`, `/prerender`, `/use-cache`)
+The router's REAL cache pipeline runs (runtime cache, SWR revalidation, prerender lookup); you SEED nothing — you drive a request through the real fetch path and read the resulting cache decision. The decision surfaces two ways: the `X-Rango-Cache` response header (a debug gate) or a captured `cache.decision` telemetry event.
+## Which path to use
+Both report the SAME coarse route-level signal (keyed by the route NAME). Pick by **transport**, not by meaning:
+| Path          | Helper                                                                     | Transport                                                                                       | Needs the debug gate?                             | Production surface                | Per-segment `shouldRevalidate`? |
+| ------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------- | ------------------------------- |
+| **Header**    | `assertCacheStatus(res, routeKey, expected)` / `parseCacheHeader`          | the `X-Rango-Cache` response header — the ONLY signal a black-box Playwright `Response` carries | Yes (`debugCacheSignal` / `RANGO_TEST_SIGNALS=1`) | the header (gated off by default) | no                              |
+| **Telemetry** | `assertCacheDecision(events, routeKey, expected)` / `filterCacheDecisions` | a captured `cache.decision` event off a `createCacheSink()` sink                                | No                                                | zero                              | yes (the only path exposing it) |
+Use the header path when all you have is a black-box `Response` (a Playwright `APIResponse`); use the telemetry path when you can wire `createRouter({ telemetry: sink })` and want zero production surface or per-segment `shouldRevalidate`. `assertCacheDecision` is the one-call counterpart of `assertCacheStatus` (parallel `(…, routeKey, expected)` shape — captured `events` in place of a `Response`); reach for raw `filterCacheDecisions` only when you need the per-segment event fields directly.
+## API
+### Options — `assertCacheStatus(target, segment, expected)`
+| Field      | Type                                                                                                          | Meaning                                                                                                                                                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `target`   | `Response \| { headers: Headers }` (`CacheStatusTarget`)                                                      | The thing carrying the `X-Rango-Cache` header: a `Response` from `router.fetch(...)`, or any `{ headers: Headers }`. A Playwright `APIResponse` exposes headers as a method, so wrap it: `{ headers: new Headers(res.headers()) }`. |
+| `segment`  | `string`                                                                                                      | The route NAME (e.g. `product.detail`), the same id the header carries — NOT the URL pattern (`/products/:id`).                                                                                                                     |
+| `expected` | `"hit" \| "miss" \| "stale" \| "prerendered" \| "passthrough"` (`ExpectedCacheStatus` = `CacheSegmentStatus`) | The cache status you assert for that route.                                                                                                                                                                                         |
+### Context — what your code under test emits
+The header / event is produced by the router's RSC render pipeline from `ctx.routeKey`. Your code does not call these helpers — it just runs under a router with the gate (or telemetry sink) wired. The helpers READ the emitted signal.
+| Field                                 | Type                    | Meaning                                                                                    |
+| ------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
+| `CacheSegmentSignal.id`               | `string`                | Segment id. v1: the route key, since status is route-level.                                |
+| `CacheSegmentSignal.type`             | `string`                | Segment type. v1: `"route"` for the coarse route-level entry.                              |
+| `CacheSegmentSignal.cacheStatus`      | `CacheSegmentStatus`    | Resolved status (`hit`/`miss`/`stale`/`prerendered`/`passthrough`).                        |
+| `CacheSegmentSignal.shouldRevalidate` | `boolean?`              | Whether stale-while-revalidate was triggered for this segment.                             |
+| `CacheDecisionEvent.segments`         | `CacheSegmentSignal[]?` | The coarse route-level signal array (present only when telemetry or the debug gate is on). |
+### Returns
+```ts
+// assertCacheStatus throws on mismatch / missing header / unknown segment; returns void.
+assertCacheStatus(target, segment, expected): void
+// parseCacheHeader -> the raw { routeKey: status } map. "a=hit, b=stale" -> { a: "hit", b: "stale" }.
+parseCacheHeader(headerValue: string | null | undefined): Record<string, string>
+// createCacheSink -> a sink to wire via createRouter({ telemetry: sink }), plus the array it records into.
+createCacheSink(): { sink: TelemetrySink; events: TelemetryEvent[] }
+// assertCacheDecision -> the one-call telemetry assert (counterpart of assertCacheStatus).
+// Throws on mismatch / no matching segment / unknown routeKey; returns void.
+assertCacheDecision(events: readonly TelemetryEvent[], routeKey: string, expected: ExpectedCacheStatus): void
+// filterCacheDecisions -> narrow captured events to cache.decision events (raw form).
+filterCacheDecisions(events: readonly TelemetryEvent[]): CacheDecisionEvent[]
+```
+## Recipe
+```ts
+// In a Playwright e2e, import from the e2e entry —
+// the @rangojs/router/testing barrel pulls a build-only virtual that does not
+// resolve in a plain Playwright runner.
+import { expect, test } from "@playwright/test";
+import { assertCacheStatus, createRangoE2E } from "@rangojs/router/testing/e2e";
+const { parityDescribe } = createRangoE2E({ test, expect });
+parityDescribe("product page caches", (f) => {
+  test("second request is a hit", async ({ page }) => {
+    // The key is the route NAME (the X-Rango-Cache id), NOT the URL pattern.
+    // Playwright APIResponse.headers() is a method returning a plain record, so
+    // wrap it in a Headers to match CacheStatusTarget (`{ headers: Headers }`).
+    const first = await page.request.get(f.url("/products/1"));
+    assertCacheStatus(
+      { headers: new Headers(first.headers()) },
+      "product.detail",
+      "miss",
+    );
+    const second = await page.request.get(f.url("/products/1"));
+    assertCacheStatus(
+      { headers: new Headers(second.headers()) },
+      "product.detail",
+      "hit",
+    );
+  });
+});
+```
+Zero-prod-surface alternative — the telemetry sink. No header at all; you inspect captured `cache.decision` events:
+```ts
+import {
+  createCacheSink,
+  assertCacheDecision,
+  filterCacheDecisions,
+} from "@rangojs/router/testing";
+const { sink, events } = createCacheSink();
+const router = createRouter({ telemetry: sink }).routes(urlpatterns);
+// ...drive a request through the router's RSC fetch path...
+// One-call assert (counterpart of assertCacheStatus), keyed by the route NAME:
+assertCacheDecision(events, "product.detail", "stale");
+// Or read the raw event when you need per-segment fields (shouldRevalidate):
+const decision = filterCacheDecisions(events)[0];
+expect(decision.segments?.[0].cacheStatus).toBe("stale");
+expect(decision.segments?.[0].shouldRevalidate).toBe(true);
+```
+`events` accumulates across requests, so the FIRST matching segment for a `routeKey` wins — slice or recreate the sink between requests for the same route.
+## Caveats
+- The `X-Rango-Cache` header is emitted ONLY when the gate is on: `createRouter({ debugCacheSignal: true })` or `process.env.RANGO_TEST_SIGNALS === "1"`. Off by default — zero production surface. With the gate off, `assertCacheStatus` throws a clear "header missing" error.
+- v1 is COARSE: route-level, keyed by the route NAME (e.g. `product.detail`), NOT the URL pattern (`/products/:id`); not per-individual-segment. The signal is built from `ctx.routeKey`, so a pattern-shaped key never matches. (`parseCacheHeader` exposes the raw `{ routeKey: status }` map if you need it.)
+- Prerender is indistinguishable from a cache hit by design — no static `.html`/`.rsc` files, the worker handles every request and looks up a stored Flight payload; the browser cannot tell. Do not assert "prerendered" from the DOM. Assert via the signal (`assertCacheStatus(res, seg, "prerendered")`) and run prerender assertions in PRODUCTION mode (the build-time artifacts only exist after `pnpm build`).
+- In a Playwright e2e import the cache-status helpers from the `/e2e` entry — the `@rangojs/router/testing` barrel is Vitest-only (it pulls a build-only virtual that does not resolve in a plain Playwright runner). Zero-prod-surface alternative: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits this header — get the Response from the router's real RSC fetch path.
+## See also
+- `/caching`, `/prerender`, `/use-cache` — the DSL this tests
+- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/client-components.md ADDED Viewed

@@ -0,0 +1,124 @@
+# Testing a client component — renderRoute
+**Layer:** unit (DOM) · **Import:** `@rangojs/router/testing/dom` · **DSL it tests:** a client component reading router context (see `/hooks`)
+RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`). It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed.
+## API
+### Options — `RenderRouteOptions`
+| Field           | Type                                                                   | Meaning                                                                                                                                                                                                              |
+| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`       | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                 |
+| `loaderData`    | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                       |
+| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                  |
+| `params`        | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                               |
+| `locationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                         |
+| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                        |
+| `handle`        | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                       |
+| `routeMap`      | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                      |
+| `basename`      | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root. |
+| `mount`         | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                          |
+| `theme`         | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                        |
+| `nonce`         | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                |
+`RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational.
+### Context — client hooks it makes resolve (what your code receives)
+| Hook                           | Meaning                                                                                       |
+| ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `useParams`                    | Params from the matched leaf pattern, with `options.params` merged over.                      |
+| `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix. |
+| `useHref`                      | Resolve an href against the mount/basename.                                                   |
+| `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                   |
+| `useNavigation`                | Navigation controller state — stays `idle` (see caveat).                                      |
+| `useRouter`                    | The router handle, including `.basename`.                                                     |
+| `usePathname`                  | Current committed pathname.                                                                   |
+| `useSearchParams`              | Search params from the `request` URL.                                                         |
+| `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
+| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path).                                                 |
+| `useLocationState`             | SEEDED `history.state` value.                                                                 |
+| `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
+| `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
+| `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                           |
+### Returns — `RenderRouteResult`
+Extends RTL's `RenderResult` (`getByTestId`, `getByText`, `getByRole`, `container`, ...) with:
+```ts
+type RenderRouteResult = RenderResult & {
+  router: {
+    navigate(url: string): Promise<void>; // client-only nav, re-resolves the same routes
+    pathname(): string;
+    params(): Record<string, string>;
+    store: NavigationStore; // advanced
+    eventController: EventController; // advanced
+  };
+};
+```
+## Recipe
+```tsx
+// @vitest-environment happy-dom
+import { describe, it, expect, afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { Outlet, useParams, useReverse } from "@rangojs/router/client";
+afterEach(cleanup);
+function Layout() {
+  return (
+    <div>
+      <span data-testid="shell">shell</span>
+      <Outlet />
+    </div>
+  );
+}
+function Product() {
+  const { productId } = useParams<{ productId: string }>();
+  const reverse = useReverse({ product: "/products/:productId" });
+  return (
+    <a data-testid="link" href={reverse("product", { productId: "2" })}>
+      {productId}
+    </a>
+  );
+}
+it("resolves params + reverse + Outlet through the layout chain", async () => {
+  const { getByTestId, router } = await renderRoute(
+    [
+      { path: "/products", Component: Layout }, // layout (root)
+      { path: "/products/:productId", Component: Product }, // leaf (last)
+    ],
+    { request: "/products/1" },
+  );
+  expect(getByTestId("shell").textContent).toBe("shell");
+  expect(getByTestId("link").getAttribute("href")).toBe("/products/2");
+  await router.navigate("/products/2"); // client-only nav, re-resolves the same routes
+  expect(router.pathname()).toBe("/products/2");
+});
+```
+## Caveats
+- Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run.
+- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e.
+- CATCH — streaming `use(promise)` Suspense content (e.g. an async breadcrumb `content: Promise<ReactNode>`): a plain `Promise.resolve(node)` does NOT flush its Suspense retry in RTL/happy-dom, so the DOM stays on the fallback. Assert the PENDING fallback with `new Promise(() => {})`; for the ARRIVED state pass an already-settled promise so `use()` reads it synchronously: `const p = Promise.resolve(node) as any; p.status = "fulfilled"; p.value = node;`. The real pending->resolved transition is an e2e concern.
+- ARIA gotcha — an explicit `role` on a `<Link>` (e.g. `<Link role="tab">` in a tablist) OVERRIDES the implicit `link` role, so `getByRole("link")` finds nothing. Query the explicit role (`getByRole("tab")`) or fall back to `getByText` / `getByTestId` and assert `getAttribute("href")`.
+- `ctx.theme` is undefined unless `theme` is passed; the typed `ctx.search` defaults to `{}` (seed `searchData` on `runLoader`, not here).
+- Use `mount` only for an `include()` prefix. An OPTIONAL param in the matched pattern (`/:locale?/c/:group` at `/en/c/wine`) auto-fills `locale` from the match — production parity, `useReverse` merges `useParams()` — so no `mount` is needed; a locale "dropping" from a reversed URL is usually a missing `mount` seed, not an auto-fill gap.
+- Needs a DOM env (`// @vitest-environment happy-dom`, or jsdom) and `@testing-library/react` (optional peers).
+- Don't hand-roll a `NavigationProvider`/router-context mock to test a client component — `renderRoute` mounts the REAL provider, so a hand-mock both duplicates effort and drifts from the production context shape.
+- MULTI-APP `href` typing. When a `renderRoute` suite imports client components across apps, the global `Rango.GeneratedRouteMap` augmentations collide and `href()` stops typechecking (app A's route union rejects app B's name). Runtime is unaffected — it is purely the global `href` typing. Keep the suite single-app, or split tsconfig programs per app (see [`./reverse-and-types.md`](./reverse-and-types.md) and `/typesafety`).
+## See also
+- `/hooks` — the DSL this tests
+- Siblings: `./handles.md`, `./reverse-and-types.md`, `./render-handler.md`, `./e2e-parity.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Reverse and components" (and the "Catch: streaming `use(promise)` Suspense content" subsection)