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

@rangojs/router 0.0.0-experimental.7 → 0.0.0-experimental.71

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

package/AGENTS.md +9 -0
package/README.md +942 -4
package/dist/bin/rango.js +1689 -0
package/dist/vite/index.js +4951 -930
package/package.json +70 -60
package/skills/breadcrumbs/SKILL.md +250 -0
package/skills/cache-guide/SKILL.md +294 -0
package/skills/caching/SKILL.md +93 -23
package/skills/composability/SKILL.md +172 -0
package/skills/debug-manifest/SKILL.md +12 -8
package/skills/document-cache/SKILL.md +18 -16
package/skills/fonts/SKILL.md +167 -0
package/skills/hooks/SKILL.md +334 -72
package/skills/host-router/SKILL.md +218 -0
package/skills/intercept/SKILL.md +131 -8
package/skills/layout/SKILL.md +100 -3
package/skills/links/SKILL.md +92 -31
package/skills/loader/SKILL.md +404 -44
package/skills/middleware/SKILL.md +173 -34
package/skills/mime-routes/SKILL.md +128 -0
package/skills/parallel/SKILL.md +204 -1
package/skills/prerender/SKILL.md +685 -0
package/skills/rango/SKILL.md +85 -16
package/skills/response-routes/SKILL.md +411 -0
package/skills/route/SKILL.md +257 -14
package/skills/router-setup/SKILL.md +210 -32
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +9 -8
package/skills/typesafety/SKILL.md +328 -89
package/skills/use-cache/SKILL.md +324 -0
package/src/__internal.ts +102 -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/app-version.ts +14 -0
package/src/browser/event-controller.ts +92 -64
package/src/browser/history-state.ts +80 -0
package/src/browser/intercept-utils.ts +52 -0
package/src/browser/link-interceptor.ts +24 -4
package/src/browser/logging.ts +55 -0
package/src/browser/merge-segment-loaders.ts +20 -12
package/src/browser/navigation-bridge.ts +296 -558
package/src/browser/navigation-client.ts +179 -69
package/src/browser/navigation-store.ts +73 -55
package/src/browser/navigation-transaction.ts +297 -0
package/src/browser/network-error-handler.ts +61 -0
package/src/browser/partial-update.ts +328 -313
package/src/browser/prefetch/cache.ts +206 -0
package/src/browser/prefetch/fetch.ts +150 -0
package/src/browser/prefetch/observer.ts +65 -0
package/src/browser/prefetch/policy.ts +48 -0
package/src/browser/prefetch/queue.ts +160 -0
package/src/browser/prefetch/resource-ready.ts +77 -0
package/src/browser/rango-state.ts +112 -0
package/src/browser/react/Link.tsx +230 -74
package/src/browser/react/NavigationProvider.tsx +87 -11
package/src/browser/react/context.ts +11 -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 +6 -1
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 +30 -126
package/src/browser/react/use-href.tsx +2 -2
package/src/browser/react/use-link-status.ts +6 -5
package/src/browser/react/use-navigation.ts +22 -63
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 +76 -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 +214 -58
package/src/browser/scroll-restoration.ts +127 -52
package/src/browser/segment-reconciler.ts +221 -0
package/src/browser/segment-structure-assert.ts +16 -0
package/src/browser/server-action-bridge.ts +510 -603
package/src/browser/shallow.ts +6 -1
package/src/browser/types.ts +141 -48
package/src/browser/validate-redirect-origin.ts +29 -0
package/src/build/generate-manifest.ts +235 -24
package/src/build/generate-route-types.ts +39 -0
package/src/build/index.ts +13 -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 +418 -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 +618 -0
package/src/build/route-types/scan-filter.ts +85 -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 +342 -0
package/src/cache/cache-scope.ts +167 -309
package/src/cache/cf/cf-cache-store.ts +571 -17
package/src/cache/cf/index.ts +13 -3
package/src/cache/document-cache.ts +116 -77
package/src/cache/handle-capture.ts +81 -0
package/src/cache/handle-snapshot.ts +41 -0
package/src/cache/index.ts +1 -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 +153 -0
package/src/cache/types.ts +72 -122
package/src/client.rsc.tsx +3 -1
package/src/client.tsx +105 -179
package/src/component-utils.ts +4 -4
package/src/components/DefaultDocument.tsx +5 -1
package/src/context-var.ts +156 -0
package/src/debug.ts +19 -9
package/src/errors.ts +108 -2
package/src/handle.ts +55 -29
package/src/handles/MetaTags.tsx +73 -20
package/src/handles/breadcrumbs.ts +66 -0
package/src/handles/index.ts +1 -0
package/src/handles/meta.ts +30 -13
package/src/host/cookie-handler.ts +21 -15
package/src/host/errors.ts +8 -8
package/src/host/index.ts +4 -7
package/src/host/pattern-matcher.ts +27 -27
package/src/host/router.ts +61 -39
package/src/host/testing.ts +8 -8
package/src/host/types.ts +15 -7
package/src/host/utils.ts +1 -1
package/src/href-client.ts +119 -29
package/src/index.rsc.ts +155 -19
package/src/index.ts +223 -30
package/src/internal-debug.ts +11 -0
package/src/loader.rsc.ts +26 -157
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 +186 -0
package/src/prerender.ts +524 -0
package/src/reverse.ts +351 -0
package/src/root-error-boundary.tsx +41 -29
package/src/route-content-wrapper.tsx +7 -4
package/src/route-definition/dsl-helpers.ts +982 -0
package/src/route-definition/helper-factories.ts +200 -0
package/src/route-definition/helpers-types.ts +434 -0
package/src/route-definition/index.ts +55 -0
package/src/route-definition/redirect.ts +101 -0
package/src/route-definition/resolve-handler-use.ts +149 -0
package/src/route-definition.ts +1 -1428
package/src/route-map-builder.ts +217 -123
package/src/route-name.ts +53 -0
package/src/route-types.ts +70 -8
package/src/router/content-negotiation.ts +215 -0
package/src/router/debug-manifest.ts +72 -0
package/src/router/error-handling.ts +9 -9
package/src/router/find-match.ts +160 -0
package/src/router/handler-context.ts +435 -86
package/src/router/intercept-resolution.ts +402 -0
package/src/router/lazy-includes.ts +237 -0
package/src/router/loader-resolution.ts +356 -128
package/src/router/logging.ts +251 -0
package/src/router/manifest.ts +154 -35
package/src/router/match-api.ts +555 -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 +108 -93
package/src/router/match-middleware/cache-lookup.ts +459 -10
package/src/router/match-middleware/cache-store.ts +98 -26
package/src/router/match-middleware/intercept-resolution.ts +57 -17
package/src/router/match-middleware/segment-resolution.ts +80 -6
package/src/router/match-pipelines.ts +10 -45
package/src/router/match-result.ts +135 -35
package/src/router/metrics.ts +240 -15
package/src/router/middleware-cookies.ts +55 -0
package/src/router/middleware-types.ts +220 -0
package/src/router/middleware.ts +324 -369
package/src/router/navigation-snapshot.ts +182 -0
package/src/router/pattern-matching.ts +211 -43
package/src/router/prerender-match.ts +502 -0
package/src/router/preview-match.ts +98 -0
package/src/router/request-classification.ts +310 -0
package/src/router/revalidation.ts +137 -38
package/src/router/route-snapshot.ts +245 -0
package/src/router/router-context.ts +41 -21
package/src/router/router-interfaces.ts +484 -0
package/src/router/router-options.ts +618 -0
package/src/router/router-registry.ts +24 -0
package/src/router/segment-resolution/fresh.ts +748 -0
package/src/router/segment-resolution/helpers.ts +268 -0
package/src/router/segment-resolution/loader-cache.ts +199 -0
package/src/router/segment-resolution/revalidation.ts +1379 -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 +291 -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 +78 -3
package/src/router.ts +740 -4252
package/src/rsc/handler-context.ts +45 -0
package/src/rsc/handler.ts +907 -797
package/src/rsc/helpers.ts +140 -6
package/src/rsc/index.ts +0 -20
package/src/rsc/loader-fetch.ts +229 -0
package/src/rsc/manifest-init.ts +90 -0
package/src/rsc/nonce.ts +14 -0
package/src/rsc/origin-guard.ts +141 -0
package/src/rsc/progressive-enhancement.ts +391 -0
package/src/rsc/response-error.ts +37 -0
package/src/rsc/response-route-handler.ts +347 -0
package/src/rsc/rsc-rendering.ts +246 -0
package/src/rsc/runtime-warnings.ts +42 -0
package/src/rsc/server-action.ts +356 -0
package/src/rsc/ssr-setup.ts +128 -0
package/src/rsc/types.ts +46 -11
package/src/search-params.ts +230 -0
package/src/segment-system.tsx +165 -17
package/src/server/context.ts +315 -58
package/src/server/cookie-store.ts +190 -0
package/src/server/fetchable-loader-store.ts +37 -0
package/src/server/handle-store.ts +113 -15
package/src/server/loader-registry.ts +24 -64
package/src/server/request-context.ts +607 -81
package/src/server.ts +35 -130
package/src/ssr/index.tsx +103 -30
package/src/static-handler.ts +126 -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 +791 -0
package/src/types/index.ts +88 -0
package/src/types/loader-types.ts +210 -0
package/src/types/route-config.ts +170 -0
package/src/types/route-entry.ts +109 -0
package/src/types/segments.ts +151 -0
package/src/types.ts +1 -1623
package/src/urls/include-helper.ts +197 -0
package/src/urls/index.ts +53 -0
package/src/urls/path-helper-types.ts +346 -0
package/src/urls/path-helper.ts +364 -0
package/src/urls/pattern-types.ts +107 -0
package/src/urls/response-types.ts +116 -0
package/src/urls/type-extraction.ts +372 -0
package/src/urls/urls-function.ts +98 -0
package/src/urls.ts +1 -802
package/src/use-loader.tsx +161 -81
package/src/vite/discovery/bundle-postprocess.ts +181 -0
package/src/vite/discovery/discover-routers.ts +348 -0
package/src/vite/discovery/prerender-collection.ts +439 -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 +117 -0
package/src/vite/discovery/virtual-module-codegen.ts +203 -0
package/src/vite/index.ts +15 -1129
package/src/vite/plugin-types.ts +103 -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 -53
package/src/vite/plugins/expose-id-utils.ts +299 -0
package/src/vite/plugins/expose-ids/export-analysis.ts +296 -0
package/src/vite/plugins/expose-ids/handler-transform.ts +209 -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 +786 -0
package/src/vite/plugins/performance-tracks.ts +88 -0
package/src/vite/plugins/refresh-cmd.ts +127 -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 +266 -0
package/src/vite/{virtual-entries.ts → plugins/virtual-entries.ts} +23 -14
package/src/vite/plugins/virtual-stub-plugin.ts +29 -0
package/src/vite/rango.ts +462 -0
package/src/vite/router-discovery.ts +918 -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 +207 -0
package/src/vite/utils/shared-utils.ts +170 -0
package/CLAUDE.md +0 -43
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/server/route-manifest-cache.ts +0 -173
package/src/vite/expose-handle-id.ts +0 -209
package/src/vite/expose-loader-id.ts +0 -426
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

@@ -25,31 +25,32 @@ 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";
+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