npm - @rangojs/router - Versions diffs - 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327 - Mend

@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

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 (440) hide show

package/AGENTS.md +8 -4
package/README.md +301 -797
package/dist/bin/rango.js +603 -145
package/dist/testing/vitest.js +82 -0
package/dist/vite/index.js +3750 -1160
package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
package/package.json +96 -24
package/skills/api-client/SKILL.md +211 -0
package/skills/breadcrumbs/SKILL.md +85 -6
package/skills/bundle-analysis/SKILL.md +159 -0
package/skills/cache-guide/SKILL.md +228 -33
package/skills/caching/SKILL.md +336 -19
package/skills/catalog.json +271 -0
package/skills/comparison/SKILL.md +50 -0
package/skills/comparison/agents/openai.yaml +4 -0
package/skills/comparison/references/framework-comparison.md +837 -0
package/skills/composability/SKILL.md +110 -4
package/skills/css/SKILL.md +76 -0
package/skills/debug-manifest/SKILL.md +5 -3
package/skills/defer-hydration/SKILL.md +235 -0
package/skills/document-cache/SKILL.md +87 -56
package/skills/fonts/SKILL.md +1 -1
package/skills/handler-use/SKILL.md +12 -10
package/skills/hooks/SKILL.md +73 -691
package/skills/hooks/data.md +273 -0
package/skills/hooks/handle-and-actions.md +103 -0
package/skills/hooks/navigation.md +110 -0
package/skills/hooks/outlets.md +41 -0
package/skills/hooks/state.md +228 -0
package/skills/hooks/urls.md +135 -0
package/skills/host-router/SKILL.md +129 -27
package/skills/i18n/SKILL.md +276 -0
package/skills/intercept/SKILL.md +75 -19
package/skills/layout/SKILL.md +40 -19
package/skills/links/SKILL.md +247 -17
package/skills/loader/SKILL.md +248 -10
package/skills/middleware/SKILL.md +25 -13
package/skills/migrate-nextjs/SKILL.md +205 -20
package/skills/migrate-react-router/SKILL.md +59 -670
package/skills/migrate-react-router/cloudflare-workers.md +129 -0
package/skills/migrate-react-router/component-migration.md +196 -0
package/skills/migrate-react-router/data-and-actions.md +225 -0
package/skills/migrate-react-router/route-mapping.md +271 -0
package/skills/mime-routes/SKILL.md +29 -2
package/skills/observability/SKILL.md +202 -0
package/skills/parallel/SKILL.md +40 -10
package/skills/ppr/SKILL.md +616 -0
package/skills/prerender/SKILL.md +72 -60
package/skills/rango/SKILL.md +318 -26
package/skills/react-compiler/SKILL.md +168 -0
package/skills/response-routes/SKILL.md +138 -49
package/skills/route/SKILL.md +117 -9
package/skills/router-setup/SKILL.md +44 -9
package/skills/scripts/SKILL.md +179 -0
package/skills/server-actions/SKILL.md +776 -0
package/skills/shell-manifest/SKILL.md +185 -0
package/skills/streams-and-websockets/SKILL.md +283 -0
package/skills/tailwind/SKILL.md +28 -4
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 +131 -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 +85 -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/theme/SKILL.md +1 -1
package/skills/typesafety/SKILL.md +45 -626
package/skills/typesafety/env-and-bindings.md +254 -0
package/skills/typesafety/generated-files-and-cli.md +335 -0
package/skills/typesafety/params-and-search.md +153 -0
package/skills/typesafety/route-types.md +209 -0
package/skills/use-cache/SKILL.md +74 -15
package/skills/vercel/SKILL.md +128 -0
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 +252 -158
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/logging.ts +28 -0
package/src/browser/merge-segment-loaders.ts +6 -4
package/src/browser/navigation-bridge.ts +94 -25
package/src/browser/navigation-client.ts +144 -79
package/src/browser/navigation-store-handle.ts +38 -0
package/src/browser/navigation-store.ts +161 -73
package/src/browser/navigation-transaction.ts +9 -59
package/src/browser/network-error-handler.ts +34 -7
package/src/browser/partial-update.ts +183 -144
package/src/browser/prefetch/cache.ts +242 -77
package/src/browser/prefetch/fetch.ts +325 -69
package/src/browser/prefetch/queue.ts +61 -12
package/src/browser/rango-state.ts +158 -76
package/src/browser/react/Link.tsx +58 -20
package/src/browser/react/NavigationProvider.tsx +202 -120
package/src/browser/react/ScrollRestoration.tsx +10 -6
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 +32 -7
package/src/browser/react/use-params.ts +20 -10
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 +145 -28
package/src/browser/scroll-restoration.ts +37 -22
package/src/browser/segment-reconciler.ts +31 -21
package/src/browser/segment-structure-assert.ts +2 -2
package/src/browser/server-action-bridge.ts +236 -65
package/src/browser/types.ts +102 -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 +203 -154
package/src/build/generate-route-types.ts +3 -1
package/src/build/index.ts +11 -3
package/src/build/prefix-tree-utils.ts +123 -0
package/src/build/route-trie.ts +152 -21
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 +456 -62
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 +128 -51
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 +13 -21
package/src/cache/cache-error.ts +104 -0
package/src/cache/cache-key-utils.ts +58 -13
package/src/cache/cache-policy.ts +108 -34
package/src/cache/cache-runtime.ts +421 -58
package/src/cache/cache-scope.ts +187 -96
package/src/cache/cache-tag.ts +149 -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 +2202 -372
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 +126 -41
package/src/cache/handle-snapshot.ts +70 -0
package/src/cache/index.ts +23 -20
package/src/cache/memory-segment-store.ts +243 -37
package/src/cache/profile-registry.ts +46 -31
package/src/cache/read-through-swr.ts +56 -12
package/src/cache/segment-codec.ts +13 -21
package/src/cache/shell-snapshot.ts +417 -0
package/src/cache/tag-invalidation.ts +230 -0
package/src/cache/types.ts +180 -99
package/src/cache/vercel/index.ts +11 -0
package/src/cache/vercel/vercel-cache-store.ts +1127 -0
package/src/client.rsc.tsx +41 -21
package/src/client.tsx +33 -61
package/src/cloudflare/index.ts +11 -0
package/src/cloudflare/tracing.ts +108 -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 +185 -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 +67 -37
package/src/handles/MetaTags.tsx +24 -53
package/src/handles/Scripts.tsx +183 -0
package/src/handles/breadcrumbs.ts +35 -8
package/src/handles/deferred-resolution.ts +127 -0
package/src/handles/is-thenable.ts +18 -0
package/src/handles/meta.ts +14 -40
package/src/handles/script.ts +244 -0
package/src/host/cookie-handler.ts +9 -60
package/src/host/errors.ts +13 -22
package/src/host/index.ts +9 -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 +97 -12
package/src/index.ts +98 -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 +78 -10
package/src/redirect-origin.ts +114 -0
package/src/regex-escape.ts +8 -0
package/src/render-error-thrower.tsx +20 -0
package/src/response-utils.ts +62 -0
package/src/reverse.ts +65 -39
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 +87 -59
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 +41 -20
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 +129 -30
package/src/router/handler-context.ts +27 -42
package/src/router/instrument.ts +355 -0
package/src/router/intercept-resolution.ts +39 -20
package/src/router/lazy-includes.ts +82 -59
package/src/router/loader-resolution.ts +167 -72
package/src/router/logging.ts +0 -6
package/src/router/manifest.ts +74 -40
package/src/router/match-api.ts +80 -55
package/src/router/match-context.ts +0 -22
package/src/router/match-handlers.ts +211 -165
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 +69 -79
package/src/router/metrics.ts +0 -34
package/src/router/middleware-types.ts +7 -134
package/src/router/middleware.ts +298 -172
package/src/router/navigation-snapshot.ts +7 -56
package/src/router/params-util.ts +23 -0
package/src/router/parse-pattern.ts +115 -0
package/src/router/pattern-matching.ts +181 -150
package/src/router/prefetch-cache-ttl.ts +51 -0
package/src/router/prefetch-limits.ts +37 -0
package/src/router/prerender-match.ts +112 -67
package/src/router/preview-match.ts +6 -2
package/src/router/request-classification.ts +50 -69
package/src/router/revalidation.ts +123 -73
package/src/router/route-snapshot.ts +14 -3
package/src/router/router-context.ts +6 -29
package/src/router/router-interfaces.ts +115 -36
package/src/router/router-options.ts +166 -5
package/src/router/router-registry.ts +2 -5
package/src/router/segment-resolution/fresh.ts +131 -86
package/src/router/segment-resolution/helpers.ts +86 -6
package/src/router/segment-resolution/loader-cache.ts +139 -39
package/src/router/segment-resolution/loader-mask.ts +67 -0
package/src/router/segment-resolution/loader-snapshot.ts +251 -0
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 +75 -0
package/src/router/telemetry-otel.ts +160 -200
package/src/router/telemetry.ts +105 -20
package/src/router/timeout.ts +0 -20
package/src/router/tracing.ts +215 -0
package/src/router/trie-matching.ts +171 -59
package/src/router/types.ts +9 -63
package/src/router/url-params.ts +57 -0
package/src/router.ts +157 -71
package/src/rsc/full-payload.ts +70 -0
package/src/rsc/handler-context.ts +3 -2
package/src/rsc/handler.ts +291 -217
package/src/rsc/helpers.ts +168 -46
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 +29 -42
package/src/rsc/nonce.ts +10 -1
package/src/rsc/origin-guard.ts +39 -25
package/src/rsc/progressive-enhancement.ts +124 -13
package/src/rsc/redirect-guard.ts +100 -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 +99 -189
package/src/rsc/rsc-rendering.ts +421 -76
package/src/rsc/runtime-warnings.ts +23 -10
package/src/rsc/server-action.ts +282 -116
package/src/rsc/shell-capture.ts +1158 -0
package/src/rsc/shell-serve.ts +150 -0
package/src/rsc/ssr-setup.ts +16 -0
package/src/rsc/transition-gate.ts +89 -0
package/src/rsc/types.ts +53 -5
package/src/runtime-env.ts +18 -0
package/src/search-params.ts +35 -30
package/src/segment-loader-promise.ts +49 -4
package/src/segment-system.tsx +350 -149
package/src/serialize.ts +243 -0
package/src/server/context.ts +208 -51
package/src/server/cookie-parse.ts +32 -0
package/src/server/cookie-store.ts +152 -5
package/src/server/handle-store.ts +21 -38
package/src/server/loader-registry.ts +33 -42
package/src/server/request-context.ts +395 -176
package/src/ssr/index.tsx +458 -178
package/src/ssr/ssr-root.tsx +228 -0
package/src/static-handler.ts +10 -13
package/src/testing/cache-status.ts +162 -0
package/src/testing/collect-handle.ts +46 -0
package/src/testing/dispatch.ts +813 -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 +199 -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 +584 -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 +56 -84
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 +20 -52
package/src/types/route-entry.ts +0 -6
package/src/types/segments.ts +135 -14
package/src/urls/include-helper.ts +19 -64
package/src/urls/include-provider.ts +71 -0
package/src/urls/index.ts +2 -11
package/src/urls/path-helper-types.ts +63 -17
package/src/urls/path-helper.ts +22 -106
package/src/urls/pattern-types.ts +72 -19
package/src/urls/response-types.ts +22 -29
package/src/urls/type-extraction.ts +98 -154
package/src/urls/urls-function.ts +1 -19
package/src/use-loader.tsx +292 -107
package/src/vercel/index.ts +11 -0
package/src/vercel/tracing.ts +88 -0
package/src/vite/debug.ts +185 -0
package/src/vite/discovery/bundle-postprocess.ts +8 -7
package/src/vite/discovery/dev-prerender-cache.ts +117 -0
package/src/vite/discovery/discover-routers.ts +127 -86
package/src/vite/discovery/discovery-errors.ts +255 -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 +45 -1
package/src/vite/discovery/virtual-module-codegen.ts +14 -34
package/src/vite/index.ts +4 -0
package/src/vite/inject-client-debug.ts +88 -0
package/src/vite/plugin-types.ts +210 -10
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-loader-hook.d.mts +23 -0
package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
package/src/vite/plugins/cloudflare-protocol-stub.ts +194 -0
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/vercel-output.ts +384 -0
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 +138 -27
package/src/vite/rango.ts +236 -138
package/src/vite/router-discovery.ts +927 -136
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 +71 -43
package/src/vite/utils/shared-utils.ts +142 -43
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/migrate-nextjs/SKILL.md CHANGED Viewed

@@ -32,6 +32,10 @@ Common reasons to migrate:
 - **Build-time rendering** — `Static()` and `Prerender()` provide explicit
   build-time rendering instead of mixing rendering and caching behind conventions.
   See: `/prerender`
+- **Partial prerendering, shipped** — the `ppr` path option caches a page's
+  HTML shell and resumes only the live holes on each request; loaders stay
+  fresh. The equivalent of Next's `experimental_ppr`, stable and per-route.
+  See: `/ppr`
 - **Composable route tree** — layouts, includes, middleware, parallels, and
   intercepts compose directly in the route definition.
   See: `/composability`, `/parallel`, `/intercept`
@@ -43,6 +47,34 @@ Common reasons to migrate:
 Work route-by-route, bottom-up. Start with leaf pages, then layouts, then middleware. Verify each route works before moving to the next.
+## Replace imports, never shim Next
+Do NOT create mock `next/*` modules, Vite aliases for `next/*`, or compatibility
+wrapper components (a local `Link` that forwards `href` to `to`, a fake
+`useRouter`, a stubbed `next/headers`). Shims freeze Next semantics into the
+app, hide unsupported behavior until runtime, and keep `next` in the dependency
+graph — the migration looks done but isn't. Replace every `next/*` import at
+its call site with the real Rango API:
+| Next import                                                                  | Replace with                                                                                   |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `next/link` `Link`                                                           | `Link` from `@rangojs/router/client` — rename `href` to `to` (see §6)                          |
+| `next/navigation` `useRouter`, `usePathname`, `useSearchParams`, `useParams` | same names from `@rangojs/router/client`                                                       |
+| `next/navigation` `redirect`, `notFound`                                     | `redirect`, `notFound` from `@rangojs/router`                                                  |
+| `next/headers` `cookies`, `headers`                                          | `cookies()`, `headers()` from `@rangojs/router` (server-only)                                  |
+| `next/cache` `revalidateTag`, `unstable_cache`                               | `updateTag`/`revalidateTag` from `@rangojs/router`; `"use cache"` (see §3 and `/use-cache`)    |
+| `next/server` `NextResponse`, `NextRequest`                                  | web-standard `Response`/`Request`; middleware via `router.use()` (see §4)                      |
+| `next/image` `Image`                                                         | plain `<img>` (keep explicit `width`/`height`) or your CDN's image URL — no built-in optimizer |
+| `next/font`                                                                  | see `/fonts`                                                                                   |
+| `next/script` `Script`                                                       | see `/scripts`                                                                                 |
+| `next-themes`                                                                | `theme: true` in `createRouter` (see §10)                                                      |
+If an import has no row here and no obvious Rango equivalent, stop and surface
+it to the user — do not mock it to keep the build green.
+Done means: `grep -rn "from ['\"]next" src/ app/` returns nothing, and `next`
+is gone from `package.json`.
 ## 1. Project Setup
 Replace Next.js tooling with Vite + Rango:
@@ -88,6 +120,21 @@ The Document component replaces `app/layout.tsx`'s `<html>` wrapper. See `/route
 | `app/shop/[...path]/page.tsx`   | `path("/shop/:path+", CatchAll, { name: "shopCatchAll" })` |
 | `app/docs/[[...slug]]/page.tsx` | `path("/docs/:slug*", Docs, { name: "docs" })`             |
+The catch-all remainder is a single string at `ctx.params.<name>` with the `/`
+separators preserved — split it to recover the array Next gives you:
+```typescript
+// app/docs/[[...slug]]/page.tsx  ->  params.slug is string[] | undefined in Next
+path("/docs/:slug*", (ctx) => {
+  // "" for /docs, "a/b/c" for /docs/a/b/c
+  const slug = ctx.params.slug === "" ? [] : ctx.params.slug.split("/");
+  return <Docs slug={slug} />;
+}, { name: "docs" });
+```
+`[...path]` (required, ≥1 segment) maps to `:path+`; `[[...slug]]` (optional,
+matches the bare parent too) maps to `:slug*` — which binds `""` at `/docs`.
 ### Layouts
 ```typescript
@@ -153,6 +200,18 @@ export const marketingPatterns = urls(({ path }) => [
 include("/", marketingPatterns, { name: "marketing" }),
 ```
+Next.js code-splits each route segment automatically. Rango's eager `include()`
+bundles the group into the entry chunk; to get Next-style per-section splitting,
+pass an async provider so the group loads on the first request under its prefix:
+```typescript
+// urls/admin.tsx: `export default adminPatterns` — loads on first /admin request
+include("/admin", () => import("./urls/admin"), { name: "admin" }),
+```
+Route types, `href()`, and prerender still see every route in the split group.
+See `/composability`.
 ### Parallel routes
 In Next.js, `@sidebar` and `@main` are both named slots. In Rango, the main content
@@ -193,9 +252,9 @@ The main content always goes through `<Outlet />` via the `path()` handler.
 // Rango: explicit intercept in layout
 layout(<ShopLayout />, () => [
   path("/product/:id", ProductPage, { name: "product" }),
-  intercept("@modal", ".product", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-  ]),
+  intercept("@modal", ".product", <ProductModal />, {
+    when: ({ from }) => from.pathname.startsWith("/shop"),
+  }),
 ])
 ```
@@ -225,7 +284,7 @@ Loaders are Rango's live data layer. Use them when you need:
 - **Client-side data refresh** — `useLoader()` in client components for reactive data
 - **Per-loader caching** — opt in with `loader(MyLoader, () => [cache({ ttl: 60 })])`; loaders stay live by default
-- **Revalidation control** — `revalidate()` targets specific loaders after actions
+- **Revalidation control** — `revalidate()` targets specific segments and loaders after actions
 - **Loading skeletons** — `loading()` shows a Suspense fallback while loaders resolve
 ```typescript
@@ -288,21 +347,136 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 Use `Passthrough()` whenever the Next.js route has `dynamicParams: true` (the
 default) or serves an open-ended param space. See `/prerender` for full API.
-### Revalidation: different model
+### Rendering-mode segment config
+Next.js route segment config maps onto Rango's explicit primitives:
+| Next.js segment config                              | Rango                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `dynamic = "force-static"` + `generateStaticParams` | `Static()` / `Prerender()` (see `/prerender`)                |
+| `revalidate = 60` (ISR)                             | `cache({ ttl: 60, swr: ... })` on the route (see `/caching`) |
+| `dynamic = "force-dynamic"`                         | the default — routes are dynamic unless you cache them       |
+| `dynamicParams = true`                              | `Passthrough()` (above)                                      |
+| `experimental_ppr = true`                           | the `ppr` path option (below, and `/ppr`)                    |
+### Partial prerendering → the `ppr` path option
+Next.js PPR statically prerenders a shell at build time and streams the parts
+inside `<Suspense>` at request time. Rango ships the same model as a path
+option — the shell is captured at runtime into the app cache store and resumed
+on later requests, with the holes rendered fresh per request:
+```typescript
+// Next.js: app/products/[id]/page.tsx
+export const experimental_ppr = true;
+export default async function Page({ params }) {
+  return (
+    <ProductShell>
+      <Suspense fallback={<PriceSkeleton />}>
+        <LivePrice id={params.id} />
+      </Suspense>
+    </ProductShell>
+  );
+}
+// Rango, step 1 — direct carry-over. Your Suspense tree IS the hole model:
+// hand the un-awaited promise down, keep the boundary, add the ppr option.
+// No loader, no loading(), no restructuring.
+function ProductPage(ctx: HandlerContext) {
+  const price = fetchPrice(ctx.params.id); // pending promise — NOT awaited
+  return (
+    <ProductShell>
+      <Suspense fallback={<PriceSkeleton />}>
+        <LivePrice price={price} /> {/* use(price) inside */}
+      </Suspense>
+    </ProductShell>
+  );
+}
+path("/products/:id", ProductPage, {
+  name: "product",
+  ppr: { ttl: 600, swr: 120 }, // or ppr: true (default ttl 300s)
+});
+// Rango, step 2 (optional refinement) — promote the fetch to a loader for a
+// GUARANTEED hole: loaders are masked at capture and fresh on every serve,
+// even when the value resolves instantly (a raw promise that settles fast
+// would bake into the shell). loading() is the loader's hole boundary.
+path(
+  "/products/:id",
+  ProductPage,
+  { name: "product", ppr: { ttl: 600, swr: 120 } },
+  () => [loader(LivePriceLoader), loading(<PriceSkeleton />)],
+),
+```
+Differences that matter during migration:
+- **The Suspense/promise model carries over.** As in Next, a still-pending
+  promise handed to a component that suspends under its own `<Suspense>`
+  postpones at capture and becomes a hole — existing Next PPR trees keep
+  working as-is, no `loading()` required. One container rule everywhere
+  (handlers, handles, loaders): awaited/settled data bakes into the shell; a
+  promise nested inside your data stays a live hole. For loaders, `loading()`
+  selects the lane: present = guaranteed live (masked at capture, fresh every
+  serve, immune to fast resolution — prefer it for per-request data); absent =
+  the bake lane (the settled container bakes and is snapshot-pinned per shell,
+  nested promises stay live). Identity reads (`cookies()`/`headers()`) where
+  the value would bake refuse the capture by construction.
+- **Shell freshness is explicit.** Next's PPR shell is fixed until the next
+  build; Rango's has `ttl`/`swr`/`tags` per route, and `updateTag()` /
+  `revalidateTag()` drop the shell (`revalidate()` does not — it is a data
+  lever and never touches shell HTML).
+- **`cookies()`/`headers()` in shell material THROW during capture** (in Next
+  they silently force dynamic rendering). Per-user reads must move behind a
+  `loading()` boundary (the live loader lane) or into a nested promise — the
+  refusal surfaces at migration time, which is the point.
+- **A store is required.** PPR needs the app-level `createRouter({ cache })`
+  store to implement the shell family (`MemorySegmentCacheStore`,
+  `CFCacheStore`, `VercelCacheStore`). Without one the route quietly stays
+  fully dynamic with a once-per-key warning.
+- **Middleware still guards every serve.** Auth middleware (global or route
+  DSL) runs before any shell byte on HIT and MISS alike — no Next-style "PPR
+  bypasses middleware" caveats to migrate around.
+A route without `ppr` pays zero cost. See `/ppr` for the full execution matrix,
+hole rules, and pitfalls.
+### Revalidation: two distinct axes
+Next.js conflates two things under "revalidation." Rango separates them — and
+tag-based cache invalidation now maps directly.
+**1. Cache invalidation (bust cached values) — direct equivalent.** Tag entries
+with `cache({ tags })` or runtime `cacheTag(...tags)`. `cacheTag()` works inside a
+`"use cache"` function (tags that entry) AND render-callable in a plain server
+component (no `"use cache"` needed — it tags the document / PPR shell the component
+renders into). Then invalidate by tag:
-Next.js uses path/tag-based cache invalidation (`revalidatePath`, `revalidateTag`)
-to bust cached responses. Rango does not currently have a direct equivalent.
+```typescript
+// Next.js                    Rango
+// revalidateTag("products")  →  await updateTag("products")  // in a server action: awaitable,
+//                                                            // read-your-own-writes (next render is fresh)
+//                            or  revalidateTag("products")    // in a route handler / webhook:
+//                                                            // background, non-blocking (hard-purge)
+```
-In Rango, separate these two concepts:
+`updateTag` is awaitable and immediate; `revalidateTag` is fire-and-forget. Both
+hard-purge (the next read re-renders fresh); the only difference is awaitability —
+despite the Next.js name, `revalidateTag` here is NOT stale-while-revalidate.
+Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) index by tag. Next's
+`revalidatePath` has no path-based equivalent — tag the relevant entries instead.
-**Partial rendering revalidation** — `revalidate()` controls which segments
-(layouts, paths, loaders, parallels) should re-run during partial action
-re-rendering. This is about the segment tree, not cache invalidation:
+**2. Partial-render selection (which segments re-run after an action).** This is
+NOT cache invalidation — it is `revalidate()`, controlling which segments
+(layouts, paths, loaders, parallels) recompute during partial action
+re-rendering:
 ```typescript
+import { updateBlog } from "./actions/blog";
 // Re-run this layout when a blog action fires
 layout(BlogLayout, () => [
-  revalidate(({ actionId }) => actionId?.includes("updateBlog") ?? false),
+  revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
 ]);
@@ -323,15 +497,18 @@ cache({ ttl: 60, swr: 300 }, () => [
 ]);
 ```
-The key shift is:
+The two axes compose: `updateTag()` / `revalidateTag()` bust cached values;
+`revalidate()` selects which segments re-render and stream to the client after an
+action.
-- Next.js asks "which cached path or tag should I invalidate?"
-- Rango asks "which segments should re-run after this action?"
+When migrating:
-When migrating `revalidatePath()` / `revalidateTag()` usage, the Rango version
-usually is not a 1:1 API replacement. Instead, decide which layouts, routes,
-loaders, or parallels should recompute after an action and declare
-`revalidate()` at those segment boundaries.
+- `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
+  `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
+- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+  route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
+- To also force specific segments to re-render after the action (independent of
+  cache busting), attach a `revalidate()` rule at those segment boundaries.
 ## 4. Middleware
@@ -463,6 +640,8 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data; `revalidateTag(tag)` is a background (non-blocking) hard-purge and is NOT read-your-own-writes, so reserve it for route handlers / webhooks (calling it from an action can leave that action's re-render stale). `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, to force specific matched segments (path/layout/parallel/intercept) and their loaders to re-render after an action, attach a `revalidate(({ actionId }) => ...)` rule to that segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
 ## 8. Metadata / Head
 Rango uses the `Meta` handle + `<MetaTags />` client component:
@@ -557,4 +736,10 @@ See `/theme` for full API including system detection and cookie persistence.
 10. [ ] Migrate API routes to `path.json()` / `path.text()`
 11. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
 12. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
-13. [ ] Run `npx rango generate src/` to generate route types
+13. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,
+        `force-static` → `Static()`/`Prerender()`, `experimental_ppr` → the
+        `ppr` path option (loader + `loading()` as the hole)
+14. [ ] Run `npx rango generate src/` to generate route types
+15. [ ] Verify no shims: `grep -rn "from ['\"]next" src/ app/` returns nothing,
+        no mock `next/*` modules or aliases exist, and `next` is out of
+        `package.json`