npm - @rangojs/router - Versions diffs - 0.0.0-experimental.132 → 0.0.0-experimental.133 - Mend

@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

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

package/AGENTS.md +8 -0
package/README.md +43 -2
package/dist/bin/rango.js +92 -16
package/dist/vite/index.js +166 -70
package/package.json +19 -18
package/skills/breadcrumbs/SKILL.md +1 -1
package/skills/bundle-analysis/SKILL.md +2 -2
package/skills/cache-guide/SKILL.md +2 -2
package/skills/caching/SKILL.md +16 -9
package/skills/debug-manifest/SKILL.md +4 -2
package/skills/document-cache/SKILL.md +2 -2
package/skills/handler-use/SKILL.md +1 -1
package/skills/hooks/SKILL.md +2 -2
package/skills/host-router/SKILL.md +1 -1
package/skills/intercept/SKILL.md +1 -1
package/skills/loader/SKILL.md +2 -0
package/skills/migrate-react-router/SKILL.md +4 -2
package/skills/mime-routes/SKILL.md +1 -1
package/skills/prerender/SKILL.md +2 -0
package/skills/rango/SKILL.md +12 -11
package/skills/response-routes/SKILL.md +2 -2
package/skills/route/SKILL.md +4 -0
package/skills/router-setup/SKILL.md +3 -0
package/skills/scripts/SKILL.md +179 -0
package/skills/testing/SKILL.md +1 -1
package/skills/testing/bindings.md +20 -6
package/skills/testing/cache-prerender.md +5 -2
package/skills/testing/client-components.md +2 -0
package/skills/testing/e2e-parity.md +1 -1
package/skills/testing/flight.md +8 -9
package/skills/testing/render-handler.md +1 -1
package/skills/testing/response-routes.md +1 -1
package/skills/testing/server-actions.md +11 -11
package/skills/testing/setup.md +3 -0
package/skills/typesafety/SKILL.md +3 -2
package/skills/use-cache/SKILL.md +10 -9
package/src/browser/event-controller.ts +109 -2
package/src/browser/partial-update.ts +12 -0
package/src/browser/prefetch/cache.ts +17 -0
package/src/browser/prefetch/fetch.ts +69 -2
package/src/browser/react/Link.tsx +30 -5
package/src/browser/react/NavigationProvider.tsx +12 -2
package/src/browser/react/location-state-shared.ts +14 -2
package/src/browser/react/use-href.tsx +8 -1
package/src/browser/react/use-link-status.ts +23 -2
package/src/browser/response-adapter.ts +14 -3
package/src/browser/rsc-router.tsx +3 -0
package/src/browser/scroll-restoration.ts +8 -3
package/src/browser/server-action-bridge.ts +46 -11
package/src/browser/types.ts +6 -0
package/src/build/generate-route-types.ts +0 -1
package/src/build/route-trie.ts +33 -9
package/src/build/route-types/include-resolution.ts +7 -1
package/src/build/route-types/router-processing.ts +0 -6
package/src/build/route-types/source-scan.ts +105 -7
package/src/cache/cache-policy.ts +42 -8
package/src/cache/cache-runtime.ts +65 -5
package/src/cache/cache-scope.ts +71 -11
package/src/cache/cache-tag.ts +7 -2
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 +85 -613
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/document-cache.ts +11 -0
package/src/cache/handle-snapshot.ts +8 -1
package/src/cache/profile-registry.ts +25 -1
package/src/cache/segment-codec.ts +9 -1
package/src/cache/types.ts +4 -0
package/src/client.rsc.tsx +38 -0
package/src/client.tsx +11 -0
package/src/components/DefaultDocument.tsx +8 -2
package/src/context-var.ts +1 -1
package/src/decode-loader-results.ts +7 -1
package/src/escape-script.ts +52 -0
package/src/handles/MetaTags.tsx +56 -5
package/src/handles/Scripts.tsx +183 -0
package/src/handles/breadcrumbs.ts +29 -11
package/src/handles/is-thenable.ts +19 -0
package/src/handles/meta.ts +46 -0
package/src/handles/script.ts +244 -0
package/src/host/cookie-handler.ts +7 -3
package/src/host/pattern-matcher.ts +16 -2
package/src/index.rsc.ts +5 -0
package/src/index.ts +5 -0
package/src/response-utils.ts +25 -0
package/src/route-definition/dsl-helpers.ts +7 -0
package/src/route-definition/redirect.ts +1 -2
package/src/router/content-negotiation.ts +58 -10
package/src/router/intercept-resolution.ts +9 -0
package/src/router/match-middleware/cache-store.ts +10 -1
package/src/router/middleware.ts +10 -3
package/src/router/pattern-matching.ts +25 -23
package/src/router/prefetch-cache-ttl.ts +51 -0
package/src/router/router-interfaces.ts +7 -0
package/src/router/router-options.ts +23 -0
package/src/router/segment-resolution/fresh.ts +10 -0
package/src/router/segment-resolution/helpers.ts +35 -1
package/src/router/segment-resolution/loader-cache.ts +10 -6
package/src/router/segment-resolution/revalidation.ts +6 -0
package/src/router/segment-resolution.ts +1 -0
package/src/router/trie-matching.ts +14 -9
package/src/router.ts +18 -10
package/src/rsc/handler.ts +52 -13
package/src/rsc/helpers.ts +7 -1
package/src/rsc/index.ts +1 -4
package/src/rsc/loader-fetch.ts +107 -37
package/src/rsc/progressive-enhancement.ts +18 -6
package/src/rsc/response-cache-serve.ts +238 -0
package/src/rsc/response-route-handler.ts +16 -133
package/src/rsc/rsc-rendering.ts +13 -4
package/src/rsc/server-action.ts +52 -6
package/src/rsc/types.ts +7 -0
package/src/search-params.ts +24 -5
package/src/segment-loader-promise.ts +17 -2
package/src/server/loader-registry.ts +16 -18
package/src/server/request-context.ts +47 -20
package/src/testing/dispatch.ts +108 -25
package/src/testing/flight.ts +25 -0
package/src/testing/internal/context.ts +25 -2
package/src/testing/render-handler.ts +3 -1
package/src/testing/render-route.tsx +15 -0
package/src/testing/run-loader.ts +10 -3
package/src/theme/ThemeProvider.tsx +20 -6
package/src/theme/ThemeScript.tsx +7 -3
package/src/theme/constants.ts +54 -3
package/src/theme/theme-script.ts +22 -7
package/src/types/request-scope.ts +8 -3
package/src/vite/plugins/cjs-to-esm.ts +8 -1
package/src/vite/plugins/expose-id-utils.ts +10 -1
package/src/vite/plugins/expose-ids/handler-transform.ts +5 -16
package/src/vite/plugins/expose-ids/loader-transform.ts +12 -5
package/src/vite/plugins/expose-ids/router-transform.ts +6 -1
package/src/vite/plugins/expose-internal-ids.ts +0 -1
package/src/vite/plugins/version-plugin.ts +5 -17
package/src/vite/plugins/virtual-entries.ts +12 -2
package/src/vite/rango.ts +15 -6
package/src/vite/utils/ast-handler-extract.ts +11 -4
package/src/vite/utils/directive-prologue.ts +40 -0
package/src/vite/utils/prerender-utils.ts +17 -2

package/AGENTS.md CHANGED Viewed

@@ -7,3 +7,11 @@ Run `/rango` to understand the API. Detailed guides for each feature are in the
 ## Development rules
 - Always commit generated files (e.g. `*.gen.ts`) alongside the source changes that produced them.
+## Repo-wide rules (read before pushing)
+This package inherits the repo-wide conventions in the root [`AGENTS.md`](../../AGENTS.md) and [`CLAUDE.md`](../../CLAUDE.md). The ones a package-scoped reader is most likely to miss:
+- **Pre-push gate** — before EVERY push, run all of the following from the **repo root** and fix any failures: `pnpm run typecheck`, `pnpm run test:unit:all`, `pnpm run lint`, `pnpm run format`.
+- **`test:unit:all` is recursive** — it runs the unit AND Flight/RSC suites for every package and consumer app (cloudflare-basic, mini, vite-rsc-demo, ...), not just `@rangojs/router`. A change can pass this package's own tests while breaking a consumer app's `@rangojs/router/testing` dogfood suite, so do not run only `pnpm --filter @rangojs/router test:unit`.
+- **Dev + prod e2e parity is mandatory** — every e2e test must cover BOTH dev and production modes; never add a dev-only test without its production counterpart. See the dev/prod bucketing convention in the root `AGENTS.md`.

package/README.md CHANGED Viewed

@@ -127,20 +127,29 @@ export const router = createRouter().routes(urlpatterns);
 "use client";
 import type { ReactNode } from "react";
-import { MetaTags } from "@rangojs/router/client";
+import { MetaTags, Scripts } from "@rangojs/router/client";
 export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
         <MetaTags />
+        <Scripts />
       </head>
-      <body>{children}</body>
+      <body>
+        <Scripts position="body" />
+        {children}
+      </body>
     </html>
   );
 }
 ```
+`<MetaTags />` and `<Scripts />` render the tags collected by the built-in `Meta`
+and `Script` handles (see [Meta Tags](#meta-tags) and [Scripts](#scripts)). The
+built-in `DefaultDocument` already includes all three sites, so this is only
+needed for a custom document.
 ## Defining Routes
 Rango is a named-route router first.
@@ -978,6 +987,38 @@ export function BlogPostPage(ctx: HandlerContext) {
 Render collected tags in the document with `<MetaTags />` from `@rangojs/router/client`.
+## Scripts
+Inject `<script>` tags (analytics, GTM, widgets) the same way, using the built-in
+`Script` handle — push a config from a handler, render with `<Scripts />`:
+```tsx
+import { Script } from "@rangojs/router";
+import type { HandlerContext } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+export function RootLayout(ctx: HandlerContext) {
+  // Inline bootstrap (GTM/GA4/Segment) — rendered with the request CSP nonce.
+  ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
+  // External async resource (loads on first encounter, deduped by src).
+  ctx.use(Script)({
+    id: "plausible",
+    src: "https://plausible.io/js/script.js",
+    async: true,
+    attributes: { "data-domain": "example.com" },
+  });
+  return <Outlet />;
+}
+```
+Render with `<Scripts />` (head) and `<Scripts position="body" />` (body) from
+`@rangojs/router/client` (both are wired in `DefaultDocument`). The request CSP
+nonce is applied automatically to document-rendered scripts. `ScriptConfig` is a
+discriminated union (inline / external-async / external-ordered), and inline +
+ordered scripts are document-load while async externals are React resources — see
+the [`/scripts` skill](./skills/scripts/SKILL.md) for the full execution contract
+and CSP guidance.
 ## CLI: `rango generate`
 Route types are generated automatically by the Vite plugin. The CLI is a manual fallback for generating types outside the dev server (e.g. in CI or for IDE support before first `pnpm dev`):

package/dist/bin/rango.js CHANGED Viewed

@@ -339,7 +339,7 @@ function extractIncludesWithDiagnostics(code, sourceFileArg) {
   return { resolved, unresolvable };
 }
 function resolveImportedVariable(code, localName) {
-  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  const importRegex = /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
   while ((match = importRegex.exec(code)) !== null) {
     const imports = match[1];
@@ -635,25 +635,39 @@ function isLineTerminator(ch) {
   const c = ch.charCodeAt(0);
   return c === 10 || c === 13 || c === 8232 || c === 8233;
 }
+function isRegexPositionAt(code, slashPos, prevChar) {
+  if (prevChar === void 0) return true;
+  if (prevChar === ")" || prevChar === "]" || prevChar === "}") return false;
+  if (!/[\w$]/.test(prevChar)) return true;
+  let k = slashPos - 1;
+  while (k >= 0 && /\s/.test(code[k])) k--;
+  const wordEnd = k + 1;
+  while (k >= 0 && /[\w$]/.test(code[k])) k--;
+  return REGEX_PRECEDING_KEYWORDS.has(code.slice(k + 1, wordEnd));
+}
 function makeCodeClassifier(code) {
   const n = code.length;
   let i = 0;
   let skipStart = -1;
   let skipEnd = -1;
+  let lastSig;
   return (q) => {
     if (q >= skipStart && q < skipEnd) return false;
     while (i < n && i <= q) {
       const c = code[i];
       const d = i + 1 < n ? code[i + 1] : "";
       let end = -1;
+      let transparent = false;
       if (c === "/" && d === "/") {
         let j = i + 2;
         while (j < n && !isLineTerminator(code[j])) j++;
         end = j;
+        transparent = true;
       } else if (c === "/" && d === "*") {
         let j = i + 2;
         while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
         end = Math.min(n, j + 2);
+        transparent = true;
       } else if (c === '"' || c === "'" || c === "`") {
         let j = i + 1;
         while (j < n) {
@@ -668,6 +682,29 @@ function makeCodeClassifier(code) {
           j++;
         }
         end = j;
+      } else if (c === "/" && d !== "/" && d !== "*" && isRegexPositionAt(code, i, lastSig)) {
+        let j = i + 1;
+        let inClass = false;
+        let closed = false;
+        while (j < n && !isLineTerminator(code[j])) {
+          const r = code[j];
+          if (r === "\\") {
+            j += 2;
+            continue;
+          }
+          if (r === "[") inClass = true;
+          else if (r === "]") inClass = false;
+          else if (r === "/" && !inClass) {
+            j++;
+            closed = true;
+            break;
+          }
+          j++;
+        }
+        if (closed) {
+          while (j < n && /[a-z]/.test(code[j])) j++;
+          end = j;
+        }
       }
       if (end >= 0) {
         if (q < end) {
@@ -676,7 +713,9 @@ function makeCodeClassifier(code) {
           return false;
         }
         i = end;
+        if (!transparent) lastSig = "x";
       } else {
+        if (!/\s/.test(c)) lastSig = c;
         i++;
       }
     }
@@ -693,9 +732,26 @@ function firstCodeMatchIndex(code, pattern) {
   }
   return -1;
 }
+var REGEX_PRECEDING_KEYWORDS;
 var init_source_scan = __esm({
   "src/build/route-types/source-scan.ts"() {
     "use strict";
+    REGEX_PRECEDING_KEYWORDS = /* @__PURE__ */ new Set([
+      "return",
+      "typeof",
+      "instanceof",
+      "in",
+      "of",
+      "new",
+      "delete",
+      "void",
+      "do",
+      "else",
+      "yield",
+      "await",
+      "case",
+      "throw"
+    ]);
   }
 });
@@ -1153,11 +1209,16 @@ async function initializeApp() {
     createTemporaryReferenceSet,
   };
-  await initBrowserApp({ rscStream, deps });
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
+  const app = createElement(Rango);
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(Rango))
+    strictMode === false ? app : createElement(StrictMode, null, app)
   );
 }
@@ -1186,13 +1247,37 @@ export const renderHTML = createSSRHandler({
   }
 });
+// src/vite/utils/directive-prologue.ts
+import { parseAst } from "vite";
+function hasUseClientDirective(source) {
+  let program;
+  try {
+    program = parseAst(source, { lang: "tsx" });
+  } catch {
+    return false;
+  }
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
+      if (node.expression.value === "use client") return true;
+      continue;
+    }
+    break;
+  }
+  return false;
+}
+var init_directive_prologue = __esm({
+  "src/vite/utils/directive-prologue.ts"() {
+    "use strict";
+  }
+});
 // src/vite/plugins/version-plugin.ts
 var version_plugin_exports = {};
 __export(version_plugin_exports, {
   createVersionPlugin: () => createVersionPlugin,
   isViteDepCachePath: () => isViteDepCachePath
 });
-import { parseAst } from "vite";
+import { parseAst as parseAst2 } from "vite";
 function isCodeModule(id) {
   return /\.(tsx?|jsx?)($|\?)/.test(id);
 }
@@ -1200,23 +1285,13 @@ function normalizeModuleId(id) {
   return id.split("?", 1)[0];
 }
 function getClientModuleSignature(source) {
+  if (!hasUseClientDirective(source)) return void 0;
   let program;
   try {
-    program = parseAst(source, { lang: "tsx" });
+    program = parseAst2(source, { lang: "tsx" });
   } catch {
     return void 0;
   }
-  let isUseClient = false;
-  for (const node of program.body ?? []) {
-    if (node?.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
-      if (node.expression.value === "use client") {
-        isUseClient = true;
-      }
-      continue;
-    }
-    break;
-  }
-  if (!isUseClient) return void 0;
   const exports = /* @__PURE__ */ new Set();
   let hasDefault = false;
   let hasExportAll = false;
@@ -1390,6 +1465,7 @@ var init_version_plugin = __esm({
   "src/vite/plugins/version-plugin.ts"() {
     "use strict";
     init_virtual_entries();
+    init_directive_prologue();
   }
 });