npm - @rangojs/router - Versions diffs - 0.0.0-experimental.3 → 0.0.0-experimental.30 - Mend

@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

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

package/AGENTS.md +5 -0
package/README.md +883 -4
package/dist/bin/rango.js +1601 -0
package/dist/vite/index.js +4655 -747
package/package.json +78 -50
package/skills/cache-guide/SKILL.md +262 -0
package/skills/caching/SKILL.md +54 -25
package/skills/composability/SKILL.md +172 -0
package/skills/debug-manifest/SKILL.md +12 -8
package/skills/document-cache/SKILL.md +23 -21
package/skills/fonts/SKILL.md +167 -0
package/skills/hooks/SKILL.md +390 -63
package/skills/host-router/SKILL.md +218 -0
package/skills/intercept/SKILL.md +133 -10
package/skills/layout/SKILL.md +102 -5
package/skills/links/SKILL.md +239 -0
package/skills/loader/SKILL.md +366 -29
package/skills/middleware/SKILL.md +173 -36
package/skills/mime-routes/SKILL.md +128 -0
package/skills/parallel/SKILL.md +80 -3
package/skills/prerender/SKILL.md +643 -0
package/skills/rango/SKILL.md +86 -16
package/skills/response-routes/SKILL.md +411 -0
package/skills/route/SKILL.md +227 -14
package/skills/router-setup/SKILL.md +225 -32
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +12 -11
package/skills/typesafety/SKILL.md +401 -75
package/skills/use-cache/SKILL.md +324 -0
package/src/__internal.ts +10 -4
package/src/bin/rango.ts +321 -0
package/src/browser/action-coordinator.ts +97 -0
package/src/browser/action-response-classifier.ts +99 -0
package/src/browser/event-controller.ts +87 -64
package/src/browser/history-state.ts +80 -0
package/src/browser/intercept-utils.ts +52 -0
package/src/browser/link-interceptor.ts +20 -4
package/src/browser/logging.ts +55 -0
package/src/browser/merge-segment-loaders.ts +20 -12
package/src/browser/navigation-bridge.ts +201 -553
package/src/browser/navigation-client.ts +124 -71
package/src/browser/navigation-store.ts +33 -50
package/src/browser/navigation-transaction.ts +295 -0
package/src/browser/network-error-handler.ts +61 -0
package/src/browser/partial-update.ts +267 -317
package/src/browser/prefetch/cache.ts +146 -0
package/src/browser/prefetch/fetch.ts +135 -0
package/src/browser/prefetch/observer.ts +65 -0
package/src/browser/prefetch/policy.ts +42 -0
package/src/browser/prefetch/queue.ts +88 -0
package/src/browser/rango-state.ts +112 -0
package/src/browser/react/Link.tsx +173 -73
package/src/browser/react/NavigationProvider.tsx +138 -27
package/src/browser/react/context.ts +6 -0
package/src/browser/react/filter-segment-order.ts +11 -0
package/src/browser/react/index.ts +12 -12
package/src/browser/react/location-state-shared.ts +95 -53
package/src/browser/react/location-state.ts +60 -15
package/src/browser/react/mount-context.ts +37 -0
package/src/browser/react/nonce-context.ts +23 -0
package/src/browser/react/shallow-equal.ts +27 -0
package/src/browser/react/use-action.ts +29 -51
package/src/browser/react/use-client-cache.ts +5 -3
package/src/browser/react/use-handle.ts +49 -65
package/src/browser/react/use-href.tsx +20 -188
package/src/browser/react/use-link-status.ts +6 -5
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +27 -78
package/src/browser/react/use-params.ts +65 -0
package/src/browser/react/use-pathname.ts +47 -0
package/src/browser/react/use-router.ts +63 -0
package/src/browser/react/use-search-params.ts +56 -0
package/src/browser/react/use-segments.ts +80 -97
package/src/browser/response-adapter.ts +73 -0
package/src/browser/rsc-router.tsx +111 -26
package/src/browser/scroll-restoration.ts +92 -16
package/src/browser/segment-reconciler.ts +216 -0
package/src/browser/segment-structure-assert.ts +83 -0
package/src/browser/server-action-bridge.ts +504 -584
package/src/browser/shallow.ts +6 -1
package/src/browser/types.ts +92 -57
package/src/browser/validate-redirect-origin.ts +29 -0
package/src/build/generate-manifest.ts +438 -0
package/src/build/generate-route-types.ts +36 -0
package/src/build/index.ts +35 -0
package/src/build/route-trie.ts +265 -0
package/src/build/route-types/ast-helpers.ts +25 -0
package/src/build/route-types/ast-route-extraction.ts +98 -0
package/src/build/route-types/codegen.ts +102 -0
package/src/build/route-types/include-resolution.ts +411 -0
package/src/build/route-types/param-extraction.ts +48 -0
package/src/build/route-types/per-module-writer.ts +128 -0
package/src/build/route-types/router-processing.ts +469 -0
package/src/build/route-types/scan-filter.ts +78 -0
package/src/build/runtime-discovery.ts +231 -0
package/src/cache/background-task.ts +34 -0
package/src/cache/cache-key-utils.ts +44 -0
package/src/cache/cache-policy.ts +125 -0
package/src/cache/cache-runtime.ts +338 -0
package/src/cache/cache-scope.ts +120 -303
package/src/cache/cf/cf-cache-store.ts +119 -7
package/src/cache/cf/index.ts +8 -2
package/src/cache/document-cache.ts +101 -72
package/src/cache/handle-capture.ts +81 -0
package/src/cache/handle-snapshot.ts +41 -0
package/src/cache/index.ts +0 -15
package/src/cache/memory-segment-store.ts +191 -13
package/src/cache/profile-registry.ts +73 -0
package/src/cache/read-through-swr.ts +134 -0
package/src/cache/segment-codec.ts +256 -0
package/src/cache/taint.ts +98 -0
package/src/cache/types.ts +72 -122
package/src/client.rsc.tsx +10 -15
package/src/client.tsx +114 -135
package/src/component-utils.ts +4 -4
package/src/components/DefaultDocument.tsx +5 -1
package/src/context-var.ts +86 -0
package/src/debug.ts +17 -7
package/src/errors.ts +108 -2
package/src/handle.ts +34 -19
package/src/handles/MetaTags.tsx +73 -20
package/src/handles/meta.ts +30 -13
package/src/host/cookie-handler.ts +165 -0
package/src/host/errors.ts +97 -0
package/src/host/index.ts +53 -0
package/src/host/pattern-matcher.ts +214 -0
package/src/host/router.ts +352 -0
package/src/host/testing.ts +79 -0
package/src/host/types.ts +146 -0
package/src/host/utils.ts +25 -0
package/src/href-client.ts +135 -49
package/src/index.rsc.ts +182 -17
package/src/index.ts +238 -24
package/src/internal-debug.ts +11 -0
package/src/loader.rsc.ts +27 -142
package/src/loader.ts +27 -10
package/src/network-error-thrower.tsx +3 -1
package/src/outlet-provider.tsx +45 -0
package/src/prerender/param-hash.ts +37 -0
package/src/prerender/store.ts +185 -0
package/src/prerender.ts +463 -0
package/src/reverse.ts +330 -0
package/src/root-error-boundary.tsx +41 -29
package/src/route-content-wrapper.tsx +9 -11
package/src/route-definition/dsl-helpers.ts +934 -0
package/src/route-definition/helper-factories.ts +200 -0
package/src/route-definition/helpers-types.ts +430 -0
package/src/route-definition/index.ts +52 -0
package/src/route-definition/redirect.ts +93 -0
package/src/route-definition.ts +1 -1388
package/src/route-map-builder.ts +241 -112
package/src/route-name.ts +53 -0
package/src/route-types.ts +70 -9
package/src/router/content-negotiation.ts +116 -0
package/src/router/debug-manifest.ts +72 -0
package/src/router/error-handling.ts +9 -9
package/src/router/find-match.ts +158 -0
package/src/router/handler-context.ts +371 -81
package/src/router/intercept-resolution.ts +395 -0
package/src/router/lazy-includes.ts +234 -0
package/src/router/loader-resolution.ts +215 -122
package/src/router/logging.ts +248 -0
package/src/router/manifest.ts +155 -32
package/src/router/match-api.ts +620 -0
package/src/router/match-context.ts +5 -3
package/src/router/match-handlers.ts +440 -0
package/src/router/match-middleware/background-revalidation.ts +80 -93
package/src/router/match-middleware/cache-lookup.ts +382 -9
package/src/router/match-middleware/cache-store.ts +51 -22
package/src/router/match-middleware/intercept-resolution.ts +55 -17
package/src/router/match-middleware/segment-resolution.ts +24 -6
package/src/router/match-pipelines.ts +10 -45
package/src/router/match-result.ts +34 -29
package/src/router/metrics.ts +235 -15
package/src/router/middleware-cookies.ts +55 -0
package/src/router/middleware-types.ts +222 -0
package/src/router/middleware.ts +324 -367
package/src/router/pattern-matching.ts +321 -30
package/src/router/prerender-match.ts +400 -0
package/src/router/preview-match.ts +170 -0
package/src/router/revalidation.ts +137 -38
package/src/router/router-context.ts +36 -21
package/src/router/router-interfaces.ts +452 -0
package/src/router/router-options.ts +592 -0
package/src/router/router-registry.ts +24 -0
package/src/router/segment-resolution/fresh.ts +570 -0
package/src/router/segment-resolution/helpers.ts +263 -0
package/src/router/segment-resolution/loader-cache.ts +198 -0
package/src/router/segment-resolution/revalidation.ts +1241 -0
package/src/router/segment-resolution/static-store.ts +67 -0
package/src/router/segment-resolution.ts +21 -0
package/src/router/segment-wrappers.ts +289 -0
package/src/router/telemetry-otel.ts +299 -0
package/src/router/telemetry.ts +300 -0
package/src/router/timeout.ts +148 -0
package/src/router/trie-matching.ts +239 -0
package/src/router/types.ts +77 -3
package/src/router.ts +688 -3656
package/src/rsc/handler-context.ts +45 -0
package/src/rsc/handler.ts +786 -760
package/src/rsc/helpers.ts +140 -6
package/src/rsc/index.ts +5 -25
package/src/rsc/loader-fetch.ts +209 -0
package/src/rsc/manifest-init.ts +86 -0
package/src/rsc/nonce.ts +14 -0
package/src/rsc/origin-guard.ts +141 -0
package/src/rsc/progressive-enhancement.ts +379 -0
package/src/rsc/response-error.ts +37 -0
package/src/rsc/response-route-handler.ts +347 -0
package/src/rsc/rsc-rendering.ts +235 -0
package/src/rsc/runtime-warnings.ts +42 -0
package/src/rsc/server-action.ts +348 -0
package/src/rsc/ssr-setup.ts +128 -0
package/src/rsc/types.ts +40 -14
package/src/search-params.ts +230 -0
package/src/segment-system.tsx +57 -61
package/src/server/context.ts +202 -51
package/src/server/cookie-store.ts +190 -0
package/src/server/fetchable-loader-store.ts +37 -0
package/src/server/handle-store.ts +94 -15
package/src/server/loader-registry.ts +15 -56
package/src/server/request-context.ts +422 -70
package/src/server.ts +36 -120
package/src/ssr/index.tsx +157 -26
package/src/static-handler.ts +114 -0
package/src/theme/ThemeProvider.tsx +21 -15
package/src/theme/ThemeScript.tsx +5 -5
package/src/theme/constants.ts +5 -2
package/src/theme/index.ts +4 -14
package/src/theme/theme-context.ts +4 -30
package/src/theme/theme-script.ts +21 -18
package/src/types/boundaries.ts +158 -0
package/src/types/cache-types.ts +198 -0
package/src/types/error-types.ts +192 -0
package/src/types/global-namespace.ts +100 -0
package/src/types/handler-context.ts +687 -0
package/src/types/index.ts +88 -0
package/src/types/loader-types.ts +183 -0
package/src/types/route-config.ts +170 -0
package/src/types/route-entry.ts +102 -0
package/src/types/segments.ts +148 -0
package/src/types.ts +1 -1577
package/src/urls/include-helper.ts +197 -0
package/src/urls/index.ts +53 -0
package/src/urls/path-helper-types.ts +339 -0
package/src/urls/path-helper.ts +329 -0
package/src/urls/pattern-types.ts +95 -0
package/src/urls/response-types.ts +106 -0
package/src/urls/type-extraction.ts +372 -0
package/src/urls/urls-function.ts +98 -0
package/src/urls.ts +1 -726
package/src/use-loader.tsx +85 -77
package/src/vite/discovery/bundle-postprocess.ts +184 -0
package/src/vite/discovery/discover-routers.ts +344 -0
package/src/vite/discovery/prerender-collection.ts +385 -0
package/src/vite/discovery/route-types-writer.ts +258 -0
package/src/vite/discovery/self-gen-tracking.ts +47 -0
package/src/vite/discovery/state.ts +110 -0
package/src/vite/discovery/virtual-module-codegen.ts +203 -0
package/src/vite/index.ts +11 -782
package/src/vite/plugin-types.ts +131 -0
package/src/vite/plugins/cjs-to-esm.ts +93 -0
package/src/vite/plugins/client-ref-dedup.ts +115 -0
package/src/vite/plugins/client-ref-hashing.ts +105 -0
package/src/vite/{expose-action-id.ts → plugins/expose-action-id.ts} +72 -51
package/src/vite/plugins/expose-id-utils.ts +287 -0
package/src/vite/plugins/expose-ids/export-analysis.ts +296 -0
package/src/vite/plugins/expose-ids/handler-transform.ts +179 -0
package/src/vite/plugins/expose-ids/loader-transform.ts +74 -0
package/src/vite/plugins/expose-ids/router-transform.ts +110 -0
package/src/vite/plugins/expose-ids/types.ts +45 -0
package/src/vite/plugins/expose-internal-ids.ts +569 -0
package/src/vite/plugins/refresh-cmd.ts +65 -0
package/src/vite/plugins/use-cache-transform.ts +323 -0
package/src/vite/plugins/version-injector.ts +83 -0
package/src/vite/plugins/version-plugin.ts +254 -0
package/src/vite/{virtual-entries.ts → plugins/virtual-entries.ts} +29 -15
package/src/vite/plugins/virtual-stub-plugin.ts +29 -0
package/src/vite/rango.ts +510 -0
package/src/vite/router-discovery.ts +785 -0
package/src/vite/utils/ast-handler-extract.ts +517 -0
package/src/vite/utils/banner.ts +36 -0
package/src/vite/utils/bundle-analysis.ts +137 -0
package/src/vite/utils/manifest-utils.ts +70 -0
package/src/vite/{package-resolution.ts → utils/package-resolution.ts} +25 -29
package/src/vite/utils/prerender-utils.ts +189 -0
package/src/vite/utils/shared-utils.ts +169 -0
package/CLAUDE.md +0 -3
package/src/browser/lru-cache.ts +0 -69
package/src/browser/request-controller.ts +0 -164
package/src/cache/memory-store.ts +0 -253
package/src/href-context.ts +0 -33
package/src/href.ts +0 -255
package/src/vite/expose-handle-id.ts +0 -209
package/src/vite/expose-loader-id.ts +0 -357
package/src/vite/expose-location-state-id.ts +0 -177
/package/src/vite/{version.d.ts → plugins/version.d.ts} +0 -0

package/skills/tailwind/SKILL.md ADDED Viewed

@@ -0,0 +1,129 @@
+---
+name: tailwind
+description: Set up Tailwind CSS v4 with the Document component and CSS imports
+argument-hint: [setup]
+---
+# Tailwind CSS
+Set up Tailwind CSS v4 with the Rango router. Styles are loaded through the Document component using Vite's `?url` CSS import.
+## Install
+```bash
+pnpm add -D tailwindcss @tailwindcss/vite
+```
+## Vite Plugin
+```typescript
+// vite.config.ts
+import tailwindcss from "@tailwindcss/vite";
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    // ... other plugins
+  ],
+});
+```
+## CSS Entry Point
+```css
+/* src/index.css */
+@import "tailwindcss";
+```
+## Document Component
+Import the CSS file with `?url` to get a hashed URL, then preload and link it in `<head>`:
+```tsx
+// src/document.tsx
+"use client";
+import type { ReactNode } from "react";
+import { MetaTags } from "@rangojs/router/client";
+import styles from "./index.css?url";
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body className="font-sans antialiased text-slate-900 bg-slate-50">
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+The `?url` suffix tells Vite to return the processed CSS file's URL instead of injecting it as a side effect. This gives you a stable, hashed asset path that works in both development and production.
+## Customizing the Theme
+Tailwind v4 uses CSS `@theme` for customization:
+```css
+/* src/index.css */
+@import "tailwindcss";
+@theme {
+  --font-sans: "Inter", system-ui, sans-serif;
+  --color-primary: #3b82f6;
+  --color-secondary: #64748b;
+  --breakpoint-3xl: 1920px;
+}
+```
+## Dark Mode
+Combine with the Rango theme system (see `/theme`):
+```typescript
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  theme: { attribute: "class" },
+});
+```
+Then use Tailwind's `dark:` variant which reads the `class` attribute:
+```tsx
+<div className="bg-white dark:bg-slate-900 text-slate-900 dark:text-white">
+  Content
+</div>
+```
+## With Custom Fonts
+Use `@fontsource-variable` for self-hosted fonts bundled by Vite (see `/fonts` for all options):
+```bash
+pnpm add @fontsource-variable/inter
+```
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+@import "tailwindcss";
+@theme {
+  --font-sans: "Inter Variable", system-ui, sans-serif;
+}
+```
+No extra `<link>` tags needed in the Document -- Vite bundles the font files from `node_modules` automatically.
+## Notes
+- `?url` import is required -- bare CSS imports inject styles as a side effect and do not work with SSR streaming
+- `<link rel="preload" as="style">` eliminates render-blocking by starting the download early
+- Tailwind v4 does not need a `tailwind.config.js` -- use `@theme` in CSS instead
+- The `@tailwindcss/vite` plugin handles content detection automatically

package/skills/theme/SKILL.md CHANGED Viewed

@@ -11,45 +11,46 @@ Opt-in theme system with FOUC prevention.
 ## Enable
 ```typescript
-import { createRSCRouter } from "@rangojs/router/server";
+import { createRouter } from "@rangojs/router";
 // Simple - all defaults
-const router = createRSCRouter<Env>({
+const router = createRouter<Env>({
   document: Document,
   urls: urlpatterns,
   theme: true,
 });
 // Custom config
-const router = createRSCRouter<Env>({
+const router = createRouter<Env>({
   document: Document,
   urls: urlpatterns,
   theme: {
-    defaultTheme: "system",      // "light" | "dark" | "system"
+    defaultTheme: "system", // "light" | "dark" | "system"
     themes: ["light", "dark"],
-    attribute: "class",          // or "data-theme"
+    attribute: "class", // or "data-theme"
     storageKey: "theme",
-  }
+  },
 });
 ```
 ## Server (in loaders/middleware)
 ```typescript
-import { createLoader, createMiddleware } from "@rangojs/router/server";
+import { createLoader } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 // In a loader
-export const SettingsLoader = createLoader("settings", async (ctx) => {
-  const currentTheme = ctx.theme;    // read from cookie
+export const SettingsLoader = createLoader(async (ctx) => {
+  const currentTheme = ctx.theme; // read from cookie
   return { theme: currentTheme };
 });
 // In middleware
-export const themeMiddleware = createMiddleware(async (ctx, next) => {
+export const themeMiddleware: Middleware = async (ctx, next) => {
   // Set theme based on user preference
   ctx.setTheme("dark");
   await next();
-});
+};
 ```
 ## Client