npm - @rangojs/router - Versions diffs - 0.0.0-experimental.10 - Mend

@rangojs/router 0.0.0-experimental.10

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

package/CLAUDE.md +43 -0
package/README.md +19 -0
package/dist/bin/rango.js +227 -0
package/dist/vite/index.js +3039 -0
package/package.json +171 -0
package/skills/caching/SKILL.md +191 -0
package/skills/debug-manifest/SKILL.md +108 -0
package/skills/document-cache/SKILL.md +180 -0
package/skills/fonts/SKILL.md +165 -0
package/skills/hooks/SKILL.md +442 -0
package/skills/intercept/SKILL.md +190 -0
package/skills/layout/SKILL.md +213 -0
package/skills/links/SKILL.md +180 -0
package/skills/loader/SKILL.md +246 -0
package/skills/middleware/SKILL.md +202 -0
package/skills/mime-routes/SKILL.md +124 -0
package/skills/parallel/SKILL.md +228 -0
package/skills/prerender/SKILL.md +283 -0
package/skills/rango/SKILL.md +54 -0
package/skills/response-routes/SKILL.md +358 -0
package/skills/route/SKILL.md +173 -0
package/skills/router-setup/SKILL.md +346 -0
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +78 -0
package/skills/typesafety/SKILL.md +394 -0
package/src/__internal.ts +175 -0
package/src/bin/rango.ts +24 -0
package/src/browser/event-controller.ts +876 -0
package/src/browser/index.ts +18 -0
package/src/browser/link-interceptor.ts +121 -0
package/src/browser/lru-cache.ts +69 -0
package/src/browser/merge-segment-loaders.ts +126 -0
package/src/browser/navigation-bridge.ts +913 -0
package/src/browser/navigation-client.ts +165 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +600 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +346 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +53 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +120 -0
package/src/browser/react/location-state.ts +62 -0
package/src/browser/react/mount-context.ts +32 -0
package/src/browser/react/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +203 -0
package/src/browser/react/use-href.tsx +40 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +140 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +164 -0
package/src/browser/rsc-router.tsx +352 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/segment-structure-assert.ts +67 -0
package/src/browser/server-action-bridge.ts +762 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +478 -0
package/src/build/generate-manifest.ts +377 -0
package/src/build/generate-route-types.ts +828 -0
package/src/build/index.ts +36 -0
package/src/build/route-trie.ts +239 -0
package/src/cache/cache-scope.ts +563 -0
package/src/cache/cf/cf-cache-store.ts +428 -0
package/src/cache/cf/index.ts +19 -0
package/src/cache/document-cache.ts +340 -0
package/src/cache/index.ts +58 -0
package/src/cache/memory-segment-store.ts +150 -0
package/src/cache/memory-store.ts +253 -0
package/src/cache/types.ts +392 -0
package/src/client.rsc.tsx +83 -0
package/src/client.tsx +643 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +23 -0
package/src/debug.ts +233 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +295 -0
package/src/handle.ts +130 -0
package/src/handles/MetaTags.tsx +193 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/host/cookie-handler.ts +159 -0
package/src/host/errors.ts +97 -0
package/src/host/index.ts +56 -0
package/src/host/pattern-matcher.ts +214 -0
package/src/host/router.ts +330 -0
package/src/host/testing.ts +79 -0
package/src/host/types.ts +138 -0
package/src/host/utils.ts +25 -0
package/src/href-client.ts +202 -0
package/src/href-context.ts +33 -0
package/src/index.rsc.ts +121 -0
package/src/index.ts +165 -0
package/src/loader.rsc.ts +207 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/prerender/param-hash.ts +35 -0
package/src/prerender/store.ts +40 -0
package/src/prerender.ts +156 -0
package/src/reverse.ts +267 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +193 -0
package/src/route-definition.ts +1431 -0
package/src/route-map-builder.ts +242 -0
package/src/route-types.ts +220 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +158 -0
package/src/router/intercept-resolution.ts +387 -0
package/src/router/loader-resolution.ts +327 -0
package/src/router/manifest.ts +216 -0
package/src/router/match-api.ts +621 -0
package/src/router/match-context.ts +264 -0
package/src/router/match-middleware/background-revalidation.ts +236 -0
package/src/router/match-middleware/cache-lookup.ts +382 -0
package/src/router/match-middleware/cache-store.ts +276 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +281 -0
package/src/router/match-middleware/segment-resolution.ts +184 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +213 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.ts +791 -0
package/src/router/pattern-matching.ts +407 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +301 -0
package/src/router/segment-resolution.ts +1315 -0
package/src/router/trie-matching.ts +172 -0
package/src/router/types.ts +163 -0
package/src/router.gen.ts +6 -0
package/src/router.ts +2423 -0
package/src/rsc/handler.ts +1443 -0
package/src/rsc/helpers.ts +64 -0
package/src/rsc/index.ts +56 -0
package/src/rsc/nonce.ts +18 -0
package/src/rsc/types.ts +236 -0
package/src/segment-system.tsx +442 -0
package/src/server/context.ts +466 -0
package/src/server/handle-store.ts +229 -0
package/src/server/loader-registry.ts +174 -0
package/src/server/request-context.ts +554 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +171 -0
package/src/ssr/index.tsx +296 -0
package/src/theme/ThemeProvider.tsx +291 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/constants.ts +59 -0
package/src/theme/index.ts +58 -0
package/src/theme/theme-context.ts +70 -0
package/src/theme/theme-script.ts +152 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types.ts +1757 -0
package/src/urls.gen.ts +8 -0
package/src/urls.ts +1282 -0
package/src/use-loader.tsx +346 -0
package/src/vite/expose-action-id.ts +344 -0
package/src/vite/expose-handle-id.ts +209 -0
package/src/vite/expose-loader-id.ts +426 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/expose-prerender-handler-id.ts +429 -0
package/src/vite/index.ts +2068 -0
package/src/vite/package-resolution.ts +125 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +114 -0

package/skills/router-setup/SKILL.md ADDED Viewed

@@ -0,0 +1,346 @@
+---
+name: router-setup
+description: Create and configure the RSC router with createRouter
+argument-hint: [option]
+---
+# Router Setup with createRouter
+## Basic Router Creation
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+});
+export default router;
+```
+## URL Patterns (Django-style)
+```typescript
+// src/urls.tsx
+import { urls } from "@rangojs/router";
+import { HomePage } from "./pages/home";
+import { AboutPage } from "./pages/about";
+import { ProductPage } from "./pages/product";
+import { RootLayout } from "./layouts/RootLayout";
+export const urlpatterns = urls(({ path, layout, loader, loading }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+  layout(<RootLayout />, () => [
+    path("/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader),
+      loading(<ProductSkeleton />),
+    ]),
+  ]),
+]);
+```
+## The urls() DSL
+The `urls()` function provides a callback with all available DSL functions:
+```typescript
+urls(({
+  path,        // Define a route
+  layout,      // Wrap routes in a layout
+  parallel,    // Define parallel routes (slots)
+  loader,      // Add data loader
+  loading,     // Add loading skeleton
+  cache,       // Configure caching
+  middleware,  // Add middleware
+  revalidate,  // Control revalidation
+  intercept,   // Intercept routes for modals
+  when,        // Conditional rendering
+}) => [
+  // Route definitions here
+]);
+```
+## Router Options
+```typescript
+interface RSCRouterOptions<TEnv> {
+  // URL patterns from urls() function
+  urls: UrlPatterns;
+  // Document component wrapping entire app
+  document?: ComponentType<{ children: ReactNode }>;
+  // Enable performance metrics
+  debugPerformance?: boolean;
+  // Default error boundary
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
+  // Default not-found boundary
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
+  // Component for 404 routes
+  notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
+  // Error logging callback
+  onError?: OnErrorCallback<TEnv>;
+  // Global cache configuration
+  cache?: CacheConfig<TEnv>;
+  // Theme configuration
+  theme?: ThemeConfig | true;
+  // Connection warmup (default: true)
+  warmup?: boolean;
+  // CSP nonce provider (for router.fetch)
+  nonce?: (request: Request, env: TEnv) => string | true | Promise<string | true>;
+  // RSC version string (for router.fetch)
+  version?: string;
+}
+```
+## Using the Request Handler
+The router provides a `fetch` method to handle RSC requests:
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+export const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  nonce: () => true, // Auto-generate nonce for CSP
+});
+// src/worker.tsx (Cloudflare Workers)
+import { router } from "./router";
+export default { fetch: router.fetch };
+```
+## Document Component
+```typescript
+// src/document.tsx
+import type { ReactNode } from "react";
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>My App</title>
+      </head>
+      <body>
+        <div id="root">{children}</div>
+      </body>
+    </html>
+  );
+}
+```
+## Using with Cloudflare Workers
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+export const router = createRouter<AppEnv>({
+  document: Document,
+  urls: urlpatterns,
+});
+// src/worker.tsx
+import { router } from "./router";
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return router.fetch(request, { Bindings: env, Variables: {}, ctx });
+  },
+};
+```
+### With Dynamic Cache Configuration
+For per-request cache configuration (e.g., Cloudflare Workers with ExecutionContext):
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
+export const router = createRouter<AppEnv>({
+  document: Document,
+  urls: urlpatterns,
+  // Cache config receives env with ctx for ExecutionContext access
+  cache: (env) => ({
+    store: new CFCacheStore({ ctx: env.ctx, defaults: { ttl: 60 } }),
+  }),
+});
+// src/worker.tsx
+import { router } from "./router";
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return router.fetch(request, { Bindings: env, Variables: {}, ctx });
+  },
+};
+```
+## Complete Example
+```typescript
+// src/urls.tsx
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+// Pages
+import { HomePage } from "./pages/home";
+import { AboutPage } from "./pages/about";
+import { BlogIndexPage, BlogPostPage } from "./pages/blog";
+// Layouts
+import { RootLayout } from "./layouts/RootLayout";
+import { BlogLayout } from "./layouts/BlogLayout";
+// Loaders
+import { BlogPostLoader, BlogSidebarLoader } from "./loaders/blog";
+export const urlpatterns = urls(({ path, layout, parallel, loader, loading, cache }) => [
+  // Simple routes
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+  // Blog with layout and loaders
+  layout(<BlogLayout />, () => [
+    // Sidebar as parallel route
+    parallel({ "@sidebar": () => <BlogSidebar /> }, () => [
+      loader(BlogSidebarLoader),
+    ]),
+    // Cached blog routes
+    cache({ ttl: 60 }, () => [
+      path("/blog", BlogIndexPage, { name: "blog" }),
+      path("/blog/:slug", BlogPostPage, { name: "blogPost" }, () => [
+        loader(BlogPostLoader),
+        loading(<BlogPostSkeleton />),
+      ]),
+    ]),
+  ]),
+]);
+```
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  defaultErrorBoundary: ({ error, reset }) => (
+    <div>
+      <h1>Something went wrong</h1>
+      <button onClick={reset}>Try again</button>
+    </div>
+  ),
+  notFound: ({ pathname }) => (
+    <div>
+      <h1>404</h1>
+      <p>Page not found: {pathname}</p>
+    </div>
+  ),
+});
+export default router;
+```
+## Including Sub-patterns
+```typescript
+// src/urls/shop.tsx
+import { urls } from "@rangojs/router";
+export const shopPatterns = urls(({ path, layout }) => [
+  path("/", ShopIndex, { name: "index" }),
+  path("/product/:slug", ProductPage, { name: "product" }),
+]);
+// src/urls.tsx
+import { urls, include } from "@rangojs/router";
+import { shopPatterns } from "./urls/shop";
+export const urlpatterns = urls(({ path }) => [
+  path("/", HomePage, { name: "home" }),
+  include("/shop", shopPatterns, { name: "shop" }),
+]);
+```
+## Environment Types
+```typescript
+import type { RouterEnv } from "@rangojs/router";
+interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+}
+interface AppVariables {
+  user?: { id: string; name: string };
+}
+type AppEnv = RouterEnv<AppBindings, AppVariables>;
+const router = createRouter<AppEnv>({
+  document: Document,
+  urls: urlpatterns,
+});
+```
+## Connection Warmup
+Enabled by default. Keeps TCP+TLS connections alive so navigations after idle periods
+don't pay handshake costs.
+After 60s of no user interaction, the connection is marked cold. When the user returns
+(tab becomes visible or first mouse/touch), a `HEAD ?_rsc_warmup` request re-establishes
+the TLS connection before the next navigation. The server responds with 204 No Content
+before any middleware or routing runs.
+```typescript
+// Enabled by default
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+});
+// Disable warmup
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  warmup: false,
+});
+```
+The warmup request is relative to the current page path, so it works correctly
+with subpath deployments (reverse proxy, base path).

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 ADDED Viewed

@@ -0,0 +1,78 @@
+---
+name: theme
+description: Opt-in theme system with FOUC prevention for light/dark mode
+argument-hint: [setup]
+---
+# Theme Support
+Opt-in theme system with FOUC prevention.
+## Enable
+```typescript
+import { createRouter } from "@rangojs/router";
+// Simple - all defaults
+const router = createRouter<Env>({
+  document: Document,
+  urls: urlpatterns,
+  theme: true,
+});
+// Custom config
+const router = createRouter<Env>({
+  document: Document,
+  urls: urlpatterns,
+  theme: {
+    defaultTheme: "system",      // "light" | "dark" | "system"
+    themes: ["light", "dark"],
+    attribute: "class",          // or "data-theme"
+    storageKey: "theme",
+  }
+});
+```
+## Server (in loaders/middleware)
+```typescript
+import { createLoader, createMiddleware } from "@rangojs/router";
+// In a loader
+export const SettingsLoader = createLoader("settings", async (ctx) => {
+  const currentTheme = ctx.theme;    // read from cookie
+  return { theme: currentTheme };
+});
+// In middleware
+export const themeMiddleware = createMiddleware(async (ctx, next) => {
+  // Set theme based on user preference
+  ctx.setTheme("dark");
+  await next();
+});
+```
+## Client
+```tsx
+"use client";
+import { useTheme } from "@rangojs/router/theme";
+function ThemeToggle() {
+  const { theme, setTheme, resolvedTheme, systemTheme, themes } = useTheme();
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+      <option value="system">System</option>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+    </select>
+  );
+}
+```
+## Notes
+- `<MetaTags />` auto-renders inline script for FOUC prevention
+- Add `suppressHydrationWarning` to `<html>`
+- Theme persists in localStorage + cookie (for SSR)