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/handles/script.ts ADDED Viewed

@@ -0,0 +1,244 @@
+/**
+ * Built-in Script handle for injecting <script> tags into the document from
+ * route/layout handlers.
+ *
+ * Push from a SERVER handler with `ctx.use(Script)(config)`; render with the
+ * `<Scripts />` component (from `@rangojs/router/client`) placed in the Document
+ * `<head>` (and optionally a second `<Scripts position="body" />` at the top of
+ * `<body>`). This mirrors the Meta / <MetaTags> pair.
+ *
+ * The request CSP nonce is applied AUTOMATICALLY by <Scripts> to document-rendered
+ * scripts; consumers never pass a nonce. (An async script first loaded on a soft
+ * navigation is injected client-side without a nonce — it relies on
+ * 'strict-dynamic' or a host allowance; see the EXECUTION CONTRACT below and the
+ * /scripts skill.) A ScriptConfig is fully serializable (it crosses the
+ * server -> client handle-collection boundary), so callbacks like onLoad are NOT
+ * supported — a consumer needing them renders their own "use client" script.
+ *
+ * EXECUTION CONTRACT (see the /scripts skill for the full story):
+ * - Inline (`children`) and ordered external (`src`, optional `defer`) scripts
+ *   are DOCUMENT-LOAD scripts: they execute only when present in the initial HTML
+ *   response. <Scripts> freezes them after hydration, so a later client (soft)
+ *   navigation never inserts an inert copy — React creates client-mounted
+ *   <script> elements via innerHTML, which the HTML spec makes non-executing.
+ * - Async external scripts (`src` + `async: true`) are React RESOURCES: they load
+ *   once when first encountered, including after a soft navigation, deduped by
+ *   `src`. Use this for a vendor that should load on first visit to a route.
+ * - Reusing an `id` shapes the INITIAL document output (last-push-wins); it does
+ *   not re-run a script during navigation. Per-navigation behavior belongs in a
+ *   "use client" component or hook (see the GtmPageViews pattern in the demo).
+ *
+ * @example
+ * ```ts
+ * // External async loader (React resource — loads on first visit, even soft nav):
+ * ctx.use(Script)({ id: "stripe", src: "https://js.stripe.com/v3", async: true });
+ *
+ * // Inline bootstrap that self-injects its loader (GTM/GA4) — keep it inline so
+ * // React cannot hoist a declarative loader above the bootstrap:
+ * ctx.use(Script)({ id: "gtm", children: gtmBootstrap(containerId) });
+ *
+ * // External ordered (defer) with vendor attributes (document-load):
+ * ctx.use(Script)({
+ *   id: "plausible",
+ *   src: "https://plausible.io/js/script.js",
+ *   defer: true,
+ *   attributes: { "data-domain": "example.com" },
+ * });
+ * ```
+ */
+import type { ScriptHTMLAttributes } from "react";
+import { createHandle, type Handle } from "../handle.js";
+/**
+ * Extra attributes forwarded onto the emitted <script>. Typed by React, so the
+ * casing is React's (`crossOrigin`, not `crossorigin`) and value shapes are
+ * checked at compile time. `data-*` attributes are allowed. Two groups are
+ * excluded: the fields the Script handle manages itself (`id`, `src`, `async`,
+ * `defer`, `type`, `children`, `nonce`, `dangerouslySetInnerHTML` — set those via
+ * the ScriptConfig fields), and ALL `on*` event handlers (`onLoad`, `onError`,
+ * …): a ScriptConfig is serialized across the server -> client handle boundary, so
+ * a function cannot survive it — render your own "use client" script for callbacks.
+ */
+export type ScriptAttributes = Omit<
+  ScriptHTMLAttributes<HTMLScriptElement>,
+  | "id"
+  | "src"
+  | "async"
+  | "defer"
+  | "type"
+  | "children"
+  | "nonce"
+  | "dangerouslySetInnerHTML"
+  | `on${string}`
+> & {
+  [dataAttr: `data-${string}`]: string | number | boolean | undefined;
+};
+/** Fields shared by every script shape. */
+interface ScriptConfigBase {
+  /**
+   * Where <Scripts> renders this script.
+   * - "head" (default): the `<head>` <Scripts> site.
+   * - "body": the `<Scripts position="body" />` site at the top of <body>.
+   * Note: an external `async` script is hoisted into <head> by React regardless.
+   */
+  position?: "head" | "body";
+  /**
+   * The `type` attribute, as a free string: "module", "application/ld+json",
+   * "text/partytown", etc. Omitted means a classic script.
+   */
+  type?: string;
+  /** Extra React-cased attributes (`data-*`, `crossOrigin`, `integrity`, ...). */
+  attributes?: ScriptAttributes;
+}
+/**
+ * Inline script: a raw JS body rendered in place, escaped against `</script>`
+ * breakout. DOCUMENT-LOAD only (executes when present in the initial HTML;
+ * <Scripts> freezes it after hydration so navigation never inserts an inert
+ * copy). `id` is REQUIRED — inline scripts are never deduped by React, so a
+ * layout and a child pushing the same bootstrap would inject it twice. It is also
+ * rendered as the script's DOM `id`. Forbids `src`/`async`/`defer`. For analytics
+ * vendors (GTM/GA4/Segment) the body should
+ * create+append its own loader, so the loader is never a separate declarative tag
+ * React could hoist out of order.
+ */
+export interface InlineScriptConfig extends ScriptConfigBase {
+  id: string;
+  children: string;
+  src?: never;
+  async?: never;
+  defer?: never;
+}
+/**
+ * External async script: a React-hoisted, `src`-deduped RESOURCE (the
+ * fire-and-forget loader case). Loads once when first encountered, including
+ * after a soft navigation. Deduped by `src` (matching React); `id` is optional
+ * and, when set, is rendered as the DOM `id` (not used as the dedup key here).
+ * Forbids `children`/`defer`.
+ */
+export interface AsyncScriptConfig extends ScriptConfigBase {
+  src: string;
+  async: true;
+  id?: string;
+  children?: never;
+  defer?: never;
+}
+/**
+ * External ordered script: in-place, optionally `defer`. DOCUMENT-LOAD only
+ * (executes when present in the initial HTML; not re-run on navigation). `id` is
+ * optional (the dedup key falls back to `src`) and, when set, is rendered as the
+ * DOM `id`. Forbids `children`/`async`.
+ */
+export interface OrderedScriptConfig extends ScriptConfigBase {
+  src: string;
+  defer?: boolean;
+  id?: string;
+  children?: never;
+  async?: never;
+}
+/**
+ * A single script to inject, as a discriminated union — exactly one of:
+ * inline (`id` + `children`), external async (`src` + `async: true`), or external
+ * ordered (`src`, optional `defer`). Invalid combinations (both `src`+`children`,
+ * `async`+`defer`, inline without `id`) are compile errors. The CSP nonce is
+ * applied by <Scripts>, never here.
+ */
+export type ScriptConfig =
+  | InlineScriptConfig
+  | AsyncScriptConfig
+  | OrderedScriptConfig;
+/** A config's runtime view, for validating untyped/serialized input. */
+type LooseScriptConfig = {
+  id?: string;
+  src?: string;
+  children?: string;
+  async?: boolean;
+  defer?: boolean;
+};
+/**
+ * Dev-only validation. The discriminated union makes these states unrepresentable
+ * in TypeScript; the runtime checks exist only for untyped JavaScript callers and
+ * malformed serialized input, not as the primary contract.
+ */
+function validateConfigDev(config: ScriptConfig): void {
+  if (process.env.NODE_ENV === "production") return;
+  const c = config as LooseScriptConfig;
+  if (c.src != null && c.children != null) {
+    console.warn(
+      `[Script] A config has both "src" and "children"; they are mutually ` +
+        `exclusive — "src" wins and the inline body is ignored.`,
+    );
+  } else if (c.src == null && c.children == null) {
+    console.warn(
+      `[Script] A config has neither "src" nor "children"; it injects nothing.`,
+    );
+  } else if (c.src == null && c.id == null) {
+    console.warn(
+      `[Script] An inline script was pushed without an "id" and cannot be ` +
+        `deduplicated. Pass an "id" so a layout + child pushing the same script ` +
+        `inject it only once.`,
+    );
+  }
+  if (c.async && c.defer) {
+    console.warn(
+      `[Script] A config has both "async" and "defer"; they are mutually ` +
+        `exclusive.`,
+    );
+  }
+}
+/**
+ * Accumulate scripts across matched segments, parent -> child, preserving push
+ * order, last-push-wins per dedup key (mirroring the Meta handle).
+ *
+ * Dedup key:
+ * - async resources key by `src` ONLY — React itself dedups async scripts by src,
+ *   so two async configs with different ids but the same src must collapse to one
+ *   here (last wins) for a single, deterministic winner; otherwise React would
+ *   silently pick one with undefined attribute precedence.
+ * - everything else keys by `id ?? src`.
+ *
+ * An (untyped) inline script with neither `id` nor `src` cannot be deduplicated;
+ * it is kept and validateConfigDev warns.
+ */
+function collectScripts(segments: ScriptConfig[][]): ScriptConfig[] {
+  const result: ScriptConfig[] = [];
+  const keyToIndex = new Map<string, number>();
+  for (const configs of segments) {
+    for (const config of configs) {
+      validateConfigDev(config);
+      const isAsyncResource = config.src != null && config.async === true;
+      const key = isAsyncResource ? config.src : (config.id ?? config.src);
+      if (key === undefined) {
+        result.push(config);
+        continue;
+      }
+      const existing = keyToIndex.get(key);
+      if (existing !== undefined) {
+        result[existing] = config;
+      } else {
+        keyToIndex.set(key, result.length);
+        result.push(config);
+      }
+    }
+  }
+  return result;
+}
+/**
+ * Built-in handle for injecting scripts. Uses an explicit stable id (built-ins
+ * do not rely on the Vite id-injection plugin, which only covers consumer code).
+ */
+export const Script: Handle<ScriptConfig, ScriptConfig[]> = createHandle<
+  ScriptConfig,
+  ScriptConfig[]
+>(collectScripts, "__rsc_router_script__");

package/src/host/cookie-handler.ts CHANGED Viewed

@@ -1,9 +1,3 @@
-/**
- * Cookie Override Handler
- *
- * Manages cookie-based host override for development environments.
- */
 import type { HostOverrideConfig } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import { matchPattern, parseRequest } from "./pattern-matcher.js";
@@ -12,52 +6,21 @@ import {
   InvalidHostnameError,
   HostValidationError,
 } from "./errors.js";
+import { parseCookiesFromHeader } from "../server/cookie-parse.js";
-/**
- * Parse cookies from request
- */
 export function parseCookies(request: Request): Record<string, string> {
-  const cookieHeader = request.headers.get("cookie");
-  if (!cookieHeader) {
-    return {};
-  }
-  const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(";");
-  for (const pair of pairs) {
-    const [name, ...rest] = pair.trim().split("=");
-    if (name && rest.length > 0) {
-      const value = rest.join("=");
-      try {
-        cookies[name] = decodeURIComponent(value);
-      } catch {
-        cookies[name] = value;
-      }
-    }
-  }
-  return cookies;
+  return parseCookiesFromHeader(request.headers.get("cookie"));
 }
-/**
- * Get cookie value from request
- */
 export function getCookie(request: Request, name: string): string | undefined {
   const cookies = parseCookies(request);
   return cookies[name];
 }
-/**
- * Create Set-Cookie header to delete a cookie
- */
 export function createDeleteCookieHeader(name: string): string {
   return `${name}=; Max-Age=0; Path=/; Secure; HttpOnly`;
 }
-/**
- * Create error response with cookie deletion
- */
 export function createCookieErrorResponse(
   cookieName: string,
   message: string,
@@ -77,9 +40,6 @@ export function createCookieErrorResponse(
   );
 }
-/**
- * Check if current host is allowed to use override
- */
 export function isHostAllowed(
   request: Request,
   allowedHosts: string[],
@@ -95,12 +55,6 @@ export function isHostAllowed(
   return false;
 }
-/**
- * Handle cookie override logic
- *
- * Returns overridden hostname if valid, original hostname if no override.
- * Throws errors for invalid overrides.
- */
 export function handleCookieOverride(
   request: Request,
   config: HostOverrideConfig | undefined,
@@ -115,51 +69,46 @@ export function handleCookieOverride(
   const cookieValue = getCookie(request, cookieName);
   const { hostname: originalHostname } = parseRequest(request);
-  // No cookie - return original hostname
   if (!cookieValue) {
     return originalHostname;
   }
-  // Check if current host is allowed
   const allowed = isHostAllowed(request, allowedHosts);
-  // If not allowed, throw error
   if (!allowed) {
     throw new HostOverrideNotAllowedError(originalHostname, cookieName, {
       cause: { cookieValue, currentHost: originalHostname },
     });
   }
-  // If allowed and has custom validation, run it
   if (validate) {
     try {
       const validatedHostname = validate(request, cookieValue, input);
       return validatedHostname;
     } catch (error) {
-      // Wrap in HostValidationError
       const message = error instanceof Error ? error.message : String(error);
       throw new HostValidationError(message, error);
     }
   }
-  // Default validation - verify it's a valid hostname using URL constructor
+  // URL.hostname ASCII-lowercases the host, so compare the cookie value against
+  // its canonical lowercase form (a mixed-case host is valid) and reject only
+  // when it carries a path/port. Return the canonical host so downstream
+  // matching, which assumes lowercase, sees a consistent value.
   try {
-    // Try to construct a URL with the hostname to validate it
     const testUrl = new URL(`https://${cookieValue}`);
-    // Ensure the hostname matches what we provided (URL constructor normalizes it)
-    if (testUrl.hostname !== cookieValue) {
+    if (testUrl.hostname !== cookieValue.toLowerCase()) {
       throw new InvalidHostnameError(cookieValue, {
         cause: { original: cookieValue, normalized: testUrl.hostname },
       });
     }
+    return testUrl.hostname;
   } catch (error) {
-    // If URL constructor failed, throw InvalidHostnameError with cause
     if (error instanceof InvalidHostnameError) {
       throw error;
     }
     throw new InvalidHostnameError(cookieValue, { cause: error });
   }
-  return cookieValue;
 }

package/src/host/errors.ts CHANGED Viewed

@@ -4,16 +4,10 @@
  * All host router errors extend HostRouterError for easy instance checking.
  */
-/**
- * Error options with cause
- */
 interface ErrorOptions {
   cause?: unknown;
 }
-/**
- * Base error class for all host router errors
- */
 export class HostRouterError extends Error {
   cause?: unknown;
@@ -27,9 +21,6 @@ export class HostRouterError extends Error {
   }
 }
-/**
- * Error thrown when pattern validation fails
- */
 export class InvalidPatternError extends HostRouterError {
   constructor(pattern: string, reason: string, options?: ErrorOptions) {
     super(`Invalid pattern "${pattern}": ${reason}`, options);
@@ -38,9 +29,6 @@ export class InvalidPatternError extends HostRouterError {
   }
 }
-/**
- * Error thrown when cookie override is not allowed
- */
 export class HostOverrideNotAllowedError extends HostRouterError {
   constructor(currentHost: string, cookieName: string, options?: ErrorOptions) {
     super(
@@ -52,9 +40,6 @@ export class HostOverrideNotAllowedError extends HostRouterError {
   }
 }
-/**
- * Error thrown when cookie hostname is invalid
- */
 export class InvalidHostnameError extends HostRouterError {
   constructor(hostname: string, options?: ErrorOptions) {
     super(`Invalid hostname format: "${hostname}"`, options);
@@ -63,9 +48,6 @@ export class InvalidHostnameError extends HostRouterError {
   }
 }
-/**
- * Error thrown when custom validation fails
- */
 export class HostValidationError extends HostRouterError {
   constructor(message: string, cause?: unknown) {
     super(message, { cause });
@@ -74,9 +56,6 @@ export class HostValidationError extends HostRouterError {
   }
 }
-/**
- * Error thrown when no route matches
- */
 export class NoRouteMatchError extends HostRouterError {
   constructor(hostname: string, pathname: string, options?: ErrorOptions) {
     super(`No route matched for ${hostname}${pathname}`, options);
@@ -85,9 +64,6 @@ export class NoRouteMatchError extends HostRouterError {
   }
 }
-/**
- * Error thrown when handler type is invalid
- */
 export class InvalidHandlerError extends HostRouterError {
   constructor(handler: unknown, options?: ErrorOptions) {
     super(`Invalid handler type: ${typeof handler}`, options);

package/src/host/index.ts CHANGED Viewed

@@ -11,8 +11,8 @@
  *
  * const router = createHostRouter();
  *
- * router.host(['.']).map(() => import('./apps/main'));
- * router.host(['admin.*']).map(() => import('./apps/admin'));
+ * router.host(['.']).lazy(() => import('./apps/main'));
+ * router.host(['admin.*']).lazy(() => import('./apps/admin'));
  *
  * export default {
  *   fetch(request) {
@@ -20,6 +20,12 @@
  *   }
  * };
  * ```
+ *
+ * The host surface (`Handler`, `Middleware`, `match`, `HostOverrideConfig.validate`)
+ * types `input` as `RouterRequestInput<any>` by design: a host router fans out to
+ * heterogeneous sub-apps with differing env/vars shapes, so there is no single
+ * `TEnv`/`TVars` to thread through. `input.env`/`input.vars` are therefore `any`
+ * here; the typed env shape lives on each sub-app's `createRouter<TEnv>()`.
  */
 // Core router

package/src/host/pattern-matcher.ts CHANGED Viewed

@@ -12,15 +12,18 @@
  * - `**.example.com` - any depth subdomain
  * - `admin.*` - admin subdomain of any apex
  * - `example.com/admin` - specific domain with path prefix
+ *
+ * Apex vs subdomain is classified purely by dot-part COUNT (apex == exactly 2
+ * parts) — there is no Public Suffix List. A registrable domain under a
+ * multi-label public suffix (example.co.uk, shop.com.au) has 3+ parts and is
+ * therefore treated as a SUBDOMAIN, not an apex: `.`/`*` will NOT match it and
+ * `*.` WILL. If registrable-domain accuracy matters for a host-router consumer,
+ * supply an explicit apex/host hint rather than relying on the part count.
  */
 import { InvalidPatternError } from "./errors.js";
-/**
- * Normalize a pattern by removing trailing slashes from paths
- */
 export function normalizePattern(pattern: string): string {
-  // If pattern has a path component, remove trailing slash
   const slashIndex = pattern.indexOf("/");
   if (slashIndex !== -1) {
     const domain = pattern.slice(0, slashIndex);
@@ -30,9 +33,6 @@ export function normalizePattern(pattern: string): string {
   return pattern;
 }
-/**
- * Parse hostname and path from request URL
- */
 export function parseRequest(request: Request): {
   hostname: string;
   pathname: string;
@@ -46,26 +46,14 @@ export function parseRequest(request: Request): {
   return { hostname, pathname, parts };
 }
-/**
- * Count subdomain levels (0 for apex, 1+ for subdomains)
- */
 function getSubdomainLevel(parts: string[]): number {
-  // Apex domain has 2 parts (example.com)
-  // Single subdomain has 3 parts (www.example.com)
-  // Multi-level has 4+ parts (a.b.example.com)
   return Math.max(0, parts.length - 2);
 }
-/**
- * Check if hostname is an apex domain (no subdomains)
- */
 function isApexDomain(parts: string[]): boolean {
   return parts.length === 2;
 }
-/**
- * Match a single pattern against hostname and path
- */
 export function matchPattern(
   pattern: string,
   hostname: string,
@@ -74,19 +62,30 @@ export function matchPattern(
 ): boolean {
   const normalized = normalizePattern(pattern);
-  // Check if pattern has path component
   const slashIndex = normalized.indexOf("/");
   const hasPath = slashIndex !== -1;
-  const domainPattern = hasPath ? normalized.slice(0, slashIndex) : normalized;
+  // Hosts are case-insensitive (RFC 3986): lowercase the domain literal and the
+  // request host once so matching folds case. Wildcards (*, **, .) are
+  // unaffected by lowercasing. The path is left untouched (paths are
+  // case-sensitive).
+  const domainPattern = (
+    hasPath ? normalized.slice(0, slashIndex) : normalized
+  ).toLowerCase();
   const pathPattern = hasPath ? normalized.slice(slashIndex) : null;
-  // First match domain
-  const domainMatch = matchDomainPattern(domainPattern, hostname, parts);
+  const lowerHostname = hostname.toLowerCase();
+  const lowerParts =
+    lowerHostname === hostname ? parts : lowerHostname.split(".");
+  const domainMatch = matchDomainPattern(
+    domainPattern,
+    lowerHostname,
+    lowerParts,
+  );
   if (!domainMatch) {
     return false;
   }
-  // Then match path (prefix match)
   if (pathPattern) {
     return pathname === pathPattern || pathname.startsWith(pathPattern + "/");
   }
@@ -94,81 +93,62 @@ export function matchPattern(
   return true;
 }
-/**
- * Match domain pattern against hostname
- */
 function matchDomainPattern(
   pattern: string,
   hostname: string,
   parts: string[],
 ): boolean {
-  // Exact match
   if (pattern === hostname) {
     return true;
   }
-  // `.` or `*` - any apex domain
   if (pattern === "." || pattern === "*") {
     return isApexDomain(parts);
   }
-  // `**` - any domain (apex + all subdomains)
   if (pattern === "**") {
     return true;
   }
-  // `*.` - any single-level subdomain
   if (pattern === "*.") {
     return getSubdomainLevel(parts) === 1;
   }
-  // `**.` - any multi-level subdomain (2+ levels)
   if (pattern === "**.") {
     return getSubdomainLevel(parts) >= 2;
   }
-  // `*.tld` - any apex domain with specific TLD (e.g., *.com)
   if (pattern.startsWith("*.") && !pattern.includes(".", 2)) {
     const tld = pattern.slice(2);
     return isApexDomain(parts) && hostname.endsWith("." + tld);
   }
-  // `*.example.com` - single subdomain of specific domain
   if (pattern.startsWith("*.")) {
     const baseDomain = pattern.slice(2);
     if (hostname.endsWith("." + baseDomain)) {
-      // Count parts: if pattern is *.example.com (3 parts),
-      // hostname should have exactly 4 parts (www.example.com)
       const patternParts = baseDomain.split(".");
       return parts.length === patternParts.length + 1;
     }
     return false;
   }
-  // `**.example.com` - any depth subdomain of specific domain
   if (pattern.startsWith("**.")) {
     const baseDomain = pattern.slice(3);
     if (hostname.endsWith("." + baseDomain)) {
       const patternParts = baseDomain.split(".");
-      // Must have more parts than the base domain (i.e., has subdomains)
       return parts.length > patternParts.length;
     }
     return false;
   }
-  // `subdomain.*` - specific subdomain of any apex domain
-  // e.g., admin.* matches admin.example.com, admin.google.com
   if (pattern.endsWith(".*")) {
     const subdomain = pattern.slice(0, -2);
-    // Must be single-level subdomain (3 parts total)
     if (parts.length === 3 && parts[0] === subdomain) {
       return true;
     }
     return false;
   }
-  // `subdomain.**` - specific subdomain of any domain (including multi-level)
-  // e.g., admin.** matches admin.example.com, admin.sub.example.com
   if (pattern.endsWith(".**")) {
     const subdomain = pattern.slice(0, -3);
     if (parts.length >= 3 && parts[0] === subdomain) {
@@ -177,11 +157,8 @@ function matchDomainPattern(
     return false;
   }
-  // `subdomain.` - specific subdomain of any apex domain (no wildcard)
-  // e.g., admin. matches admin.example.com, admin.google.com
   if (pattern.endsWith(".") && !pattern.includes("*")) {
     const subdomain = pattern.slice(0, -1);
-    // Must be exactly 3 parts (subdomain.domain.tld)
     if (parts.length === 3 && parts[0] === subdomain) {
       return true;
     }
@@ -191,9 +168,6 @@ function matchDomainPattern(
   return false;
 }
-/**
- * Validate pattern format
- */
 export function validatePattern(pattern: string): void {
   if (!pattern || typeof pattern !== "string") {
     throw new InvalidPatternError(
@@ -203,12 +177,9 @@ export function validatePattern(pattern: string): void {
     );
   }
-  // Check for invalid characters (spaces, etc.)
   if (/\s/.test(pattern)) {
     throw new InvalidPatternError(pattern, "contains whitespace", {
       cause: { pattern },
     });
   }
-  // Additional validation can be added here
 }