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/src/component-utils.ts CHANGED Viewed

@@ -5,6 +5,7 @@
  */
 import type { ComponentType } from "react";
+import { isUnderTestRunner } from "./runtime-env.js";
 /**
  * Symbol used by React to mark client component references.
@@ -48,11 +49,21 @@ export function isClientComponent(
  *
  * @param component - The component to check
  * @param name - Name to use in error message (e.g., "document")
+ * @param opts.allowServerInTest - When true AND running under a test runner
+ *   (`isUnderTestRunner()`), relax ONLY the "use client" requirement: a server
+ *   component is accepted. The plugin's "use client" transform does not run in a
+ *   bare unit test, so a real exported `document` (almost every app sets one) has
+ *   no client marker and would otherwise throw at `createRouter`, blocking
+ *   `dispatch`/`assertGeneratedRoutesMatch` against the real router. The document
+ *   reference is irrelevant to those (no Flight render). The "not a JSX element"
+ *   guard still fires, and a real dev/build still throws (mirrors the runtime
+ *   fallback-id gating in handle.ts/loader.ts).
  * @throws Error if the component is not a client component
  */
 export function assertClientComponent(
   component: ComponentType<unknown> | unknown,
   name: string,
+  opts?: { allowServerInTest?: boolean },
 ): asserts component is ComponentType<unknown> {
   if (typeof component !== "function") {
     throw new Error(
@@ -62,6 +73,14 @@ export function assertClientComponent(
     );
   }
+  // Under a test runner the "use client" transform did not run, so a real
+  // server-rendered `document` has no client marker; accept it (the reference is
+  // never serialized in dispatch/route-map checks). Outside a test runner this
+  // still throws — the build-time safety net is preserved.
+  if (opts?.allowServerInTest && isUnderTestRunner()) {
+    return;
+  }
   if (!isClientComponent(component)) {
     throw new Error(
       `${name} must be a client component with "use client" directive at the top of the file. ` +

package/src/components/DefaultDocument.tsx CHANGED Viewed

@@ -2,11 +2,13 @@
 import type { ReactNode, ReactElement } from "react";
 import { MetaTags } from "../handles/MetaTags.js";
+import { Scripts } from "../handles/Scripts.js";
 /**
  * Default document component that provides a basic HTML structure.
  * Used when no custom document is provided to createRouter.
- * Includes MetaTags for automatic charset, viewport, and route meta support.
+ * Includes MetaTags for automatic charset, viewport, and route meta support,
+ * and Scripts (head + body sites) so the Script handle works out of the box.
  *
  * Uses suppressHydrationWarning on <html> because the theme script
  * may modify class/style attributes before React hydrates.
@@ -20,8 +22,12 @@ export function DefaultDocument({
     <html lang="en" suppressHydrationWarning>
       <head>
         <MetaTags />
+        <Scripts />
       </head>
-      <body>{children}</body>
+      <body>
+        <Scripts position="body" />
+        {children}
+      </body>
     </html>
   );
 }

package/src/context-var.ts CHANGED Viewed

@@ -12,7 +12,7 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
- * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
  * export const User = createVar<UserData>({ cache: false });
  *
  * // handler
@@ -26,7 +26,7 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
-  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  /** When false, ctx.get(var) throws inside a cache() boundary. */
   readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
@@ -35,9 +35,9 @@ export interface ContextVar<T> {
 export interface ContextVarOptions {
   /**
    * When false, marks this variable as non-cacheable.
-   * Setting or getting this var inside a cache() boundary or "use cache"
-   * function will throw. Use for inherently request-specific data (user
-   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   * Reading this var with ctx.get() inside a cache() boundary throws. Use for
+   * inherently request-specific data (user sessions, auth tokens, etc.) that
+   * must never be baked into cached segments.
    *
    * @default true
    */
@@ -70,13 +70,25 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
+/**
+ * Does a variables object hold any entries? Counts both string keys and the
+ * symbol-keyed entries (context vars are stored under symbols), so an object
+ * carrying only symbol-keyed vars is still reported as non-empty.
+ */
+export function hasContextVars(variables: object): boolean {
+  return (
+    Object.keys(variables).length > 0 ||
+    Object.getOwnPropertySymbols(variables).length > 0
+  );
+}
 /**
  * Symbol used as a Set stored on the variables object to track
  * which keys hold non-cacheable values (from write-level { cache: false }).
  */
 const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
   "rango:non-cacheable-keys",
-) as any;
+);
 function getNonCacheableKeys(variables: any): Set<string | symbol> {
   if (!variables[NON_CACHEABLE_KEYS]) {

package/src/decode-loader-results.ts ADDED Viewed

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+import { isLoaderDataResult } from "./types.js";
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+    // null/undefined is the producer's ONLY "no boundary found" sentinel
+    // (loader-resolution.ts sets fallback: null for the no-boundary and the
+    // fallback-render-threw cases). A matched boundary's rendered ReactNode can
+    // legitimately be falsy (0, "", false), so test for null explicitly rather
+    // than truthiness, otherwise a valid falsy fallback is discarded and the
+    // original loader error is rethrown.
+    if (result.fallback != null) {
+      errorFallback = result.fallback;
+    } else {
+      // No boundary: rethrow preserving the ErrorInfo identity (name/stack/
+      // code/cause) instead of a stripped generic Error.
+      const info = result.error;
+      const err = new Error(
+        info.message,
+        info.cause !== undefined ? { cause: info.cause } : undefined,
+      );
+      if (info.name) err.name = info.name;
+      if (info.stack) err.stack = info.stack;
+      if (info.code !== undefined) (err as { code?: string }).code = info.code;
+      throw err;
+    }
+  }
+  return { loaderData, errorFallback };
+}

package/src/defer.ts ADDED Viewed

@@ -0,0 +1,196 @@
+/**
+ * Deferred handle values — "decide synchronously, resolve late".
+ *
+ * A handle is pushed from code that holds `ctx` (a route/layout handler), so the
+ * decision to push lands before the handles stream seals. But the value often
+ * isn't known there — it may come from a deep async component far from the
+ * handler. `ctx.use(Handle).defer()` reserves the handle's slot now (synchronous,
+ * so ordering and the pre-seal timing hold) and returns a resolver with the SAME
+ * signature as the push: you call it later, anywhere in the render, with the same
+ * value you would have passed to the push.
+ *
+ *   const breadcrumb = ctx.use(Breadcrumbs);   // (item) => void  &  .defer()
+ *   const resolve = breadcrumb.defer({ timeoutMs: 5000, else: null });
+ *   // deep async component, far from ctx:
+ *   resolve({ label, href, content });          // identical call, just deferred
+ *
+ * Under the hood the reserved slot is a Promise the renderer `use()`s; RSC Flight
+ * streams it as a late row, so a deferred-aware consumer reading the handle
+ * (`useHandle`) sees that entry as a `Promise` until it resolves (see
+ * {@link DeferredHandleEntry}). The hazard that guards against bugs: a deferred
+ * slot whose resolver is never called would keep the Flight stream — and the HTTP
+ * response — open forever. So a deferred auto-resolves to `else` after `timeoutMs`
+ * (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is never called,
+ * degrading gracefully (and warning in dev) instead of hanging the request.
+ */
+/** Default auto-resolve window. Long enough for genuine deep async work, short
+ *  enough that a forgotten resolve does not hang the response indefinitely. */
+export const DEFAULT_DEFER_TIMEOUT_MS = 10_000;
+/** Options for `ctx.use(Handle).defer()`. */
+export interface DeferOptions<TData> {
+  /**
+   * Auto-resolve to `else` after this many ms if the resolver is never called,
+   * so a forgotten resolve cannot hold the Flight stream — and thus the HTTP
+   * response — open. Defaults to {@link DEFAULT_DEFER_TIMEOUT_MS}. `0` or
+   * `Infinity` disable the timeout intentionally (not recommended on a request
+   * path). Any other non-finite or negative value is treated as a mistake and
+   * falls back to the default rather than silently disabling the safety net.
+   * Named `timeoutMs` to match the router's `*Ms` duration convention.
+   */
+  timeoutMs?: number;
+  /**
+   * Value the slot resolves to if the timeout fires before the resolver is
+   * called. Defaults to `undefined` (the deferred item is skipped/empty). For
+   * renderable handle content, `null` is the usual graceful fallback, so the
+   * type admits `null` even when `TData` does not.
+   */
+  else?: TData | null;
+}
+/**
+ * The call signature shared by a handle push and the resolver returned by
+ * `.defer()`: a concrete value, a `Promise` of the value (Flight streams it as a
+ * late row), or a thunk returning a `Promise` (called immediately).
+ */
+export type HandlePushFn<TData> = (
+  data: TData | Promise<TData> | (() => Promise<TData>),
+) => void;
+/**
+ * The push function returned by `ctx.use(Handle)`. Call it to push a value now,
+ * or call `.defer()` to reserve the slot now and resolve the value later (e.g.
+ * from a deep async component) with a timeout safety net.
+ */
+export type HandlePush<TData> = HandlePushFn<TData> & {
+  /**
+   * Reserve this handle's slot synchronously and return a resolver that is
+   * push-equal: it takes the same argument shapes as the push (value, Promise, or
+   * thunk) and behaves identically. Two things the resolver adds over a direct
+   * push: a timeout (if the resolver is never called, the slot auto-resolves to
+   * `options.else` after `options.timeoutMs`; calling the resolver cancels it),
+   * and — on the action/revalidation path only — a thunk it runs does NOT
+   * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
+   * because a deferred resolver fires after the handler phase has closed.
+   *
+   * The reserved slot appears in the accumulated handle data as a pending
+   * `Promise` until it resolves (see {@link DeferredHandleEntry}); a
+   * deferred-aware consumer narrows thenable entries (`use()`/`await` + null
+   * check) before dereferencing.
+   */
+  defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
+};
+/**
+ * A handle entry a deferred-aware consumer may read from `useHandle`: either a
+ * resolved value, or a pending `Promise` that resolves to the value, to `else`,
+ * or (when no `else` was given) `undefined` on timeout. Reading code should treat
+ * thenable entries as such and narrow before dereferencing.
+ */
+export type DeferredHandleEntry<TData> =
+  | TData
+  | Promise<TData | null | undefined>;
+// Internal: a timeout-bounded { promise, resolve }. Not part of the public API
+// (the public surface is `ctx.use(Handle).defer()`); exported for `withDefer`
+// and unit tests only. Resolves to `T`, the `else` fallback, or `undefined`.
+export function createDeferred<T>(options?: {
+  timeoutMs?: number;
+  fallback?: T | null;
+}): {
+  promise: Promise<T | null | undefined>;
+  resolve: (value: T | null | undefined) => void;
+} {
+  let resolveInner!: (value: T | null | undefined) => void;
+  let settled = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const promise = new Promise<T | null | undefined>((resolve) => {
+    resolveInner = resolve;
+  });
+  const finish = (value: T | null | undefined): void => {
+    if (settled) return;
+    settled = true;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    resolveInner(value);
+  };
+  // 0 and Infinity are documented intentional disables. Any other non-finite or
+  // negative value (NaN, -1, a bad parsed config/env) is a mistake — fall back to
+  // the default rather than SILENTLY disabling the safety net, which would let a
+  // forgotten resolve hang the Flight stream and the response forever.
+  const requested = options?.timeoutMs ?? DEFAULT_DEFER_TIMEOUT_MS;
+  let ms: number;
+  if (requested === 0 || requested === Infinity) {
+    ms = requested;
+  } else if (Number.isFinite(requested) && requested > 0) {
+    ms = requested;
+  } else {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        `[rango] defer(): invalid timeout ${String(requested)}; using the ` +
+          `${DEFAULT_DEFER_TIMEOUT_MS}ms default so the safety net stays on. ` +
+          `Use 0 or Infinity to disable the timeout intentionally.`,
+      );
+    }
+    ms = DEFAULT_DEFER_TIMEOUT_MS;
+  }
+  if (ms > 0 && ms !== Infinity) {
+    timer = setTimeout(() => {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[rango] A deferred handle value was not resolved within ${ms}ms; ` +
+            `resolving to the fallback so the response can flush. Call the ` +
+            `resolver from the component that produces the value, or raise timeoutMs.`,
+        );
+      }
+      finish(options?.fallback);
+    }, ms);
+    // Don't let a pending timer alone keep a Node process alive (no-op on workerd).
+    (timer as { unref?: () => void }).unref?.();
+  }
+  return { promise, resolve: finish };
+}
+/**
+ * Attach `.defer()` to a handle push function. The deferred slot is reserved by
+ * pushing the deferred promise through the same push (so ordering, sealing, and
+ * Flight streaming all reuse the existing path); the returned resolver settles it.
+ */
+export function withDefer<TData>(push: HandlePushFn<TData>): HandlePush<TData> {
+  const handlePush = push as HandlePush<TData>;
+  // Safe to mutate push in place: each ctx.use(Handle) call (request-context.ts,
+  // loader-resolution.ts) builds a fresh closure, so .defer never leaks across
+  // handles or requests.
+  handlePush.defer = (options) => {
+    const deferred = createDeferred<TData>({
+      timeoutMs: options?.timeoutMs,
+      fallback: options?.else,
+    });
+    // Reserve the slot now by pushing the pending promise (the renderer use()s it).
+    push(deferred.promise as Promise<TData>);
+    // The resolver is push-equal: a thunk is invoked immediately (as push does)
+    // and a Promise is adopted by the reserved slot. Calling it settles the slot
+    // and cancels the timeout — the timeout only fires if it is never called.
+    const resolveSlot = deferred.resolve as (
+      value: TData | Promise<TData>,
+    ) => void;
+    return (data) => {
+      // The thunk runs without re-entering the push-callback scope a direct push
+      // thunk gets on the action/revalidation path (loader-resolution.ts): a
+      // deferred resolver fires from a deep component after the handler phase has
+      // closed, so there is no live deadlock-guard window to exempt.
+      resolveSlot(
+        typeof data === "function" ? (data as () => Promise<TData>)() : data,
+      );
+    };
+  };
+  return handlePush;
+}

package/src/deps/ssr.ts CHANGED Viewed

	@@ -1,2 +1 @@
1	- // Re-export @vitejs/plugin-rsc/ssr for internal use by virtual entries
2 1	export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";

package/src/encode-kv.ts ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * Shared key=value serialization core.
+ *
+ * One encode+join rule shared by every deterministic query-string serializer
+ * in the codebase (cache keys, route-param strings, search-param strings,
+ * prerender param hashes). Each call site differs only in how it pre-filters
+ * and orders the pairs it hands in, plus whether it sorts; the encoding itself
+ * (`encodeURIComponent(k)=encodeURIComponent(v)` joined by `&`) is identical.
+ *
+ * Dependency-free leaf module so any layer (build-time prerender hashing,
+ * runtime cache keys, client search-param serialization) can import it without
+ * pulling in cache/router internals.
+ */
+export interface EncodeKVOptions {
+  /**
+   * Sort pairs by key in codepoint (byte) order before joining. Byte order via
+   * the `<` operator, NOT localeCompare, so the result is identical across
+   * Node, Workers, and browsers regardless of runtime locale.
+   *
+   * Defaults to false (insertion order preserved).
+   */
+  sort?: boolean;
+}
+/**
+ * Serialize an array of [key, value] pairs to a deterministic query string
+ * (no leading `?`). Both key and value are passed through encodeURIComponent
+ * so a key/value containing `&` or `=` cannot collide with a structurally
+ * different pair set.
+ *
+ * Callers are responsible for any filtering (e.g. dropping reserved params) and
+ * any value coercion (e.g. String(v), skipping null/undefined) BEFORE calling.
+ * This function never inspects or skips values; it encodes exactly what it is
+ * given so each call site keeps its own existing output.
+ */
+export function encodeKV(
+  pairs: Iterable<readonly [string, string]>,
+  options: EncodeKVOptions = {},
+): string {
+  const list = [...pairs];
+  if (list.length === 0) return "";
+  if (options.sort) {
+    list.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+  return list
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}

package/src/errors.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 /**
- * Custom error classes for RSC Router
+ * Custom error classes for Rango
  *
  * All errors include:
  * - Descriptive names for easy identification
@@ -27,6 +27,17 @@ export class RouteNotFoundError extends Error {
   }
 }
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails.
+export function isRouteNotFoundError(
+  error: unknown,
+): error is RouteNotFoundError {
+  return (
+    error instanceof RouteNotFoundError ||
+    (error instanceof Error && error.name === "RouteNotFoundError")
+  );
+}
 /**
  * Thrown when data is not found (e.g., product with ID doesn't exist)
  * Use this in handlers/loaders to trigger the nearest notFoundBoundary
@@ -109,6 +120,24 @@ export class BuildError extends Error {
   }
 }
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export class DslContextError extends Error {
+  name = "DslContextError" as const;
+  cause?: unknown;
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, DslContextError.prototype);
+    this.cause = options?.cause;
+  }
+}
 /**
  * Thrown when a network request fails (server unreachable, no internet, etc.)
  * This error triggers the root error boundary with retry capability.
@@ -196,7 +225,6 @@ export function isNetworkError(error: unknown): boolean {
 export class RouterError extends Error {
   name = "RouterError" as const;
   code: string;
-  type?: string;
   status: number;
   cause?: unknown;
@@ -205,7 +233,6 @@ export class RouterError extends Error {
     message: string,
     options?: {
       status?: number;
-      type?: string;
       cause?: unknown;
     },
   ) {
@@ -213,7 +240,6 @@ export class RouterError extends Error {
     Object.setPrototypeOf(this, RouterError.prototype);
     this.code = code;
     this.status = options?.status ?? 500;
-    this.type = options?.type;
     this.cause = options?.cause;
   }
 }

package/src/escape-script.ts ADDED Viewed

@@ -0,0 +1,52 @@
+/**
+ * Escape a JSON (or JSON-derived) string for safe embedding inside an HTML
+ * <script> element via dangerouslySetInnerHTML. Without this a value containing
+ * "</script>" closes the tag early — the rest of the page leaks as raw HTML, and
+ * in an executable script the trailing content runs. Escaping "<" defeats the
+ * early close; ">" and "&" are escaped for completeness so the serialized payload
+ * can never form HTML syntax. The result is still valid JSON and a valid JS
+ * string literal (\uXXXX escapes are legal in both) and re-parses identically.
+ *
+ * Used by every site that interpolates JSON.stringify(...) into inline <script>
+ * content: the JSON-LD meta descriptors (handles/MetaTags) and the FOUC theme
+ * init script (theme/theme-script).
+ */
+export function escapeJsonForScript(json: string): string {
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+}
+/**
+ * Escape an inline <script> body so it cannot terminate or corrupt the document.
+ * Two sequences are rewritten, each via a JS escape that is valid in string,
+ * template, regex (including the `u`/`v` flags), and JSON contexts — so the body
+ * still parses identically as code AND as JSON (application/json, ld+json):
+ * - "</script" -> "<\/script": stops a literal close tag inside the body from
+ *   ending the element early. `\/` is a valid JSON escape and a valid regex escape.
+ * - "<!--": the "!" (U+0021) is emitted as a unicode escape (see the replacement
+ *   string below), so the literal "<!--" token never reaches the HTML parser. A
+ *   literal "<!--" puts the parser into the "script data escaped" state and a
+ *   following "<script" into "script data DOUBLE escaped", where the real
+ *   "</script>" no longer closes the element — `var x = "<!--<script>"` would
+ *   swallow the rest of the document. The unicode-escape form decodes back to "!"
+ *   in string/template/JSON/regex contexts, unlike "\!" (invalid JSON, invalid
+ *   /u-regex escape).
+ * Real operators such as `a < b` and `a && b` are untouched (unlike
+ * escapeJsonForScript, which \u-escapes every "<", "&", ">").
+ *
+ * GUARANTEE / LIMITATION: value-preserving for the contexts where these sequences
+ * legitimately appear — string/template literals, regexes (incl. `u`/`v`), and
+ * JSON. It is NOT source-text-preserving (e.g. String.raw`</script>` sees the
+ * extra backslash), and it cannot rewrite "</script"/"<!--" that appear as bare
+ * code (a legacy `<!--` line comment, or `</script` outside any literal) — neither
+ * occurs in valid script payloads. Not a general sanitizer for arbitrary UNTRUSTED
+ * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
+ * inlining it as code.
+ *
+ * Used by the Script handle's <Scripts> renderer for inline `children`.
+ */
+export function escapeScriptBody(js: string): string {
+  return js.replace(/<!--/g, "<\\u0021--").replace(/<\/(script)/gi, "<\\/$1");
+}

package/src/handle.ts CHANGED Viewed

@@ -1,3 +1,6 @@
+import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 /**
  * Handle definition for accumulating data across route segments.
  *
@@ -43,10 +46,10 @@ function defaultCollect<T>(segments: T[][]): T[] {
 // Used by useHandle() to recover collect when handle is deserialized from RSC prop.
 const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
-/**
- * Look up a collect function from the registry by handle $$id.
- * Returns undefined if not registered (falls back to defaultCollect in useHandle).
- */
+// Monotonic counter for runtime fallback ids (see createHandle). Only used
+// when no build id was injected (a bare unit test).
+let runtimeHandleIdCounter = 0;
 export function getCollectFn(
   id: string,
 ): ((segments: unknown[][]) => unknown) | undefined {
@@ -93,28 +96,36 @@ export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
-  const handleId = __injectedId ?? "";
+  let handleId = __injectedId ?? "";
-  if (!handleId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rsc-router] Handle is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)",
-    );
+  // No build-injected id. Under a test runner: fall back to a synthetic id so the
+  // collect registers below and the handle is exercisable in tests (useHandle,
+  // collectHandle, renderRoute's `handles` run the REAL collect). Otherwise (dev
+  // or a real build) it means an UNSUPPORTED handler shape the plugin skipped —
+  // fail loud. The rich, stack-parsing diagnostic stays behind the NODE_ENV check
+  // so a production build folds it away and tree-shakes missing-id-error.ts out,
+  // shipping the small throw instead. isUnderTestRunner() is runtime-safe.
+  if (!handleId) {
+    if (isUnderTestRunner()) {
+      handleId = `__rango_runtime_handle_${runtimeHandleIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Handle", "createHandle");
+    } else {
+      throw new Error(
+        "[rango] Handle is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createHandle(...)`.",
+      );
+    }
   }
   const collectFn =
     collect ??
     (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
-  // Register collect in module-level registry so useHandle() can recover it
-  // when the handle is deserialized from RSC props (toJSON strips collect).
-  if (handleId) {
-    collectRegistry.set(
-      handleId,
-      collectFn as (segments: unknown[][]) => unknown,
-    );
-  }
+  collectRegistry.set(
+    handleId,
+    collectFn as (segments: unknown[][]) => unknown,
+  );
   return {
     __brand: "handle" as const,
@@ -122,9 +133,6 @@ export function createHandle<TData, TAccumulated = TData[]>(
   };
 }
-/**
- * Type guard to check if a value is a Handle.
- */
 export function isHandle(value: unknown): value is Handle<unknown, unknown> {
   return (
     typeof value === "object" &&
@@ -151,7 +159,7 @@ export function collectHandleData<TData, TAccumulated>(
   const collectFn = getCollectFn(handle.$$id);
   if (!collectFn && process.env.NODE_ENV !== "production") {
     console.warn(
-      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+      `[rango] Handle "${handle.$$id}" has no registered collect function. ` +
         `Falling back to flat array. Ensure the handle module is imported so ` +
         `createHandle() runs and registers the collect function.`,
     );