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

@rangojs/router 0.0.0-experimental.0f44aca1

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

package/AGENTS.md +5 -0
package/README.md +899 -0
package/dist/bin/rango.js +1601 -0
package/dist/vite/index.js +5214 -0
package/package.json +176 -0
package/skills/breadcrumbs/SKILL.md +250 -0
package/skills/cache-guide/SKILL.md +262 -0
package/skills/caching/SKILL.md +220 -0
package/skills/composability/SKILL.md +172 -0
package/skills/debug-manifest/SKILL.md +112 -0
package/skills/document-cache/SKILL.md +182 -0
package/skills/fonts/SKILL.md +167 -0
package/skills/hooks/SKILL.md +704 -0
package/skills/host-router/SKILL.md +218 -0
package/skills/intercept/SKILL.md +313 -0
package/skills/layout/SKILL.md +310 -0
package/skills/links/SKILL.md +239 -0
package/skills/loader/SKILL.md +596 -0
package/skills/middleware/SKILL.md +339 -0
package/skills/mime-routes/SKILL.md +128 -0
package/skills/parallel/SKILL.md +305 -0
package/skills/prerender/SKILL.md +643 -0
package/skills/rango/SKILL.md +118 -0
package/skills/response-routes/SKILL.md +411 -0
package/skills/route/SKILL.md +385 -0
package/skills/router-setup/SKILL.md +439 -0
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +79 -0
package/skills/typesafety/SKILL.md +623 -0
package/skills/use-cache/SKILL.md +324 -0
package/src/__internal.ts +273 -0
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 +899 -0
package/src/browser/history-state.ts +80 -0
package/src/browser/index.ts +18 -0
package/src/browser/intercept-utils.ts +52 -0
package/src/browser/link-interceptor.ts +141 -0
package/src/browser/logging.ts +55 -0
package/src/browser/merge-segment-loaders.ts +134 -0
package/src/browser/navigation-bridge.ts +645 -0
package/src/browser/navigation-client.ts +215 -0
package/src/browser/navigation-store.ts +806 -0
package/src/browser/navigation-transaction.ts +295 -0
package/src/browser/network-error-handler.ts +61 -0
package/src/browser/partial-update.ts +550 -0
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 +360 -0
package/src/browser/react/NavigationProvider.tsx +386 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +59 -0
package/src/browser/react/filter-segment-order.ts +11 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +162 -0
package/src/browser/react/location-state.ts +107 -0
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 +218 -0
package/src/browser/react/use-client-cache.ts +58 -0
package/src/browser/react/use-handle.ts +162 -0
package/src/browser/react/use-href.tsx +40 -0
package/src/browser/react/use-link-status.ts +135 -0
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +99 -0
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 +171 -0
package/src/browser/response-adapter.ts +73 -0
package/src/browser/rsc-router.tsx +431 -0
package/src/browser/scroll-restoration.ts +400 -0
package/src/browser/segment-reconciler.ts +216 -0
package/src/browser/segment-structure-assert.ts +83 -0
package/src/browser/server-action-bridge.ts +667 -0
package/src/browser/shallow.ts +40 -0
package/src/browser/types.ts +538 -0
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 +382 -0
package/src/cache/cf/cf-cache-store.ts +540 -0
package/src/cache/cf/index.ts +25 -0
package/src/cache/document-cache.ts +369 -0
package/src/cache/handle-capture.ts +81 -0
package/src/cache/handle-snapshot.ts +41 -0
package/src/cache/index.ts +43 -0
package/src/cache/memory-segment-store.ts +328 -0
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 +342 -0
package/src/client.rsc.tsx +85 -0
package/src/client.tsx +601 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +27 -0
package/src/context-var.ts +86 -0
package/src/debug.ts +243 -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 +365 -0
package/src/handle.ts +135 -0
package/src/handles/MetaTags.tsx +246 -0
package/src/handles/breadcrumbs.ts +66 -0
package/src/handles/index.ts +7 -0
package/src/handles/meta.ts +264 -0
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 +222 -0
package/src/index.rsc.ts +233 -0
package/src/index.ts +277 -0
package/src/internal-debug.ts +11 -0
package/src/loader.rsc.ts +89 -0
package/src/loader.ts +64 -0
package/src/network-error-thrower.tsx +23 -0
package/src/outlet-context.ts +15 -0
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 +289 -0
package/src/route-content-wrapper.tsx +196 -0
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 -0
package/src/route-map-builder.ts +275 -0
package/src/route-name.ts +53 -0
package/src/route-types.ts +259 -0
package/src/router/content-negotiation.ts +116 -0
package/src/router/debug-manifest.ts +72 -0
package/src/router/error-handling.ts +287 -0
package/src/router/find-match.ts +158 -0
package/src/router/handler-context.ts +451 -0
package/src/router/intercept-resolution.ts +395 -0
package/src/router/lazy-includes.ts +234 -0
package/src/router/loader-resolution.ts +420 -0
package/src/router/logging.ts +248 -0
package/src/router/manifest.ts +267 -0
package/src/router/match-api.ts +620 -0
package/src/router/match-context.ts +266 -0
package/src/router/match-handlers.ts +440 -0
package/src/router/match-middleware/background-revalidation.ts +223 -0
package/src/router/match-middleware/cache-lookup.ts +634 -0
package/src/router/match-middleware/cache-store.ts +295 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +306 -0
package/src/router/match-middleware/segment-resolution.ts +192 -0
package/src/router/match-pipelines.ts +179 -0
package/src/router/match-result.ts +219 -0
package/src/router/metrics.ts +282 -0
package/src/router/middleware-cookies.ts +55 -0
package/src/router/middleware-types.ts +222 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +563 -0
package/src/router/prerender-match.ts +402 -0
package/src/router/preview-match.ts +170 -0
package/src/router/revalidation.ts +289 -0
package/src/router/router-context.ts +316 -0
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 +1239 -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 +170 -0
package/src/router.ts +1002 -0
package/src/rsc/handler-context.ts +45 -0
package/src/rsc/handler.ts +1089 -0
package/src/rsc/helpers.ts +198 -0
package/src/rsc/index.ts +36 -0
package/src/rsc/loader-fetch.ts +209 -0
package/src/rsc/manifest-init.ts +86 -0
package/src/rsc/nonce.ts +32 -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 +263 -0
package/src/search-params.ts +230 -0
package/src/segment-system.tsx +454 -0
package/src/server/context.ts +591 -0
package/src/server/cookie-store.ts +190 -0
package/src/server/fetchable-loader-store.ts +37 -0
package/src/server/handle-store.ts +308 -0
package/src/server/loader-registry.ts +133 -0
package/src/server/request-context.ts +914 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +51 -0
package/src/ssr/index.tsx +365 -0
package/src/static-handler.ts +114 -0
package/src/theme/ThemeProvider.tsx +297 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/constants.ts +62 -0
package/src/theme/index.ts +48 -0
package/src/theme/theme-context.ts +44 -0
package/src/theme/theme-script.ts +155 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
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 -0
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 -0
package/src/use-loader.tsx +354 -0
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 +16 -0
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/plugins/expose-action-id.ts +365 -0
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/plugins/version.d.ts +12 -0
package/src/vite/plugins/virtual-entries.ts +123 -0
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/utils/package-resolution.ts +121 -0
package/src/vite/utils/prerender-utils.ts +189 -0
package/src/vite/utils/shared-utils.ts +169 -0

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

@@ -0,0 +1,439 @@
+---
+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 per-request performance timeline (console waterfall + Server-Timing header)
+  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;
+  // SSR options (streaming policy)
+  ssr?: SSROptions<TEnv>;
+  // Telemetry sink for structured lifecycle events
+  telemetry?: TelemetrySink;
+  // Connection warmup (default: true)
+  warmup?: boolean;
+  // Prefetch cache TTL in seconds (default: 300)
+  // Controls in-memory cache duration and Cache-Control max-age for prefetch responses.
+  // Set to false to disable prefetch caching.
+  prefetchCacheTTL?: number | false;
+  // 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<AppBindings>({
+  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, { env, 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<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  // Cache config receives (env, ctx) separately
+  cache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: 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, { env, 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 } from "@rangojs/router";
+import { shopPatterns } from "./urls/shop";
+export const urlpatterns = urls(({ path, include }) => [
+  path("/", HomePage, { name: "home" }),
+  include("/shop", shopPatterns, { name: "shop" }),
+]);
+```
+## Environment Types
+```typescript
+// Bindings passed as TEnv to createRouter<TEnv>()
+interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+}
+// Variables declared via module augmentation
+interface AppVariables {
+  user?: { id: string; name: string };
+}
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+});
+// Register types globally for implicit typing
+declare global {
+  namespace RSCRouter {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
+  }
+}
+```
+## 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).
+## Telemetry
+The router emits structured lifecycle events through a pluggable telemetry sink.
+Zero overhead when not configured.
+```typescript
+// Console sink for development
+import { createRouter, createConsoleSink } from "@rangojs/router";
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
+```
+```typescript
+// OpenTelemetry for production
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
+```typescript
+// Custom sink
+const router = createRouter({
+  telemetry: {
+    emit(event) {
+      // Send to any observability backend
+      myTracer.record(event);
+    },
+  },
+});
+```
+Events emitted: `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, `revalidation.decision`.
+## SSR Streaming Policy
+Control whether HTML SSR responses stream progressively or wait for all content:
+```typescript
+import { createRouter, type SSRStreamMode } from "@rangojs/router";
+const router = createRouter({
+  ssr: {
+    resolveStreaming: ({ request }) => {
+      const ua = request.headers.get("user-agent") ?? "";
+      // Bots that can't process streamed HTML get a fully resolved page
+      if (/Googlebot|bingbot/i.test(ua)) return "allReady";
+      return "stream";
+    },
+  },
+});
+```
+`SSRStreamMode` is `"stream" | "allReady"`:
+- `"stream"` (default) — flush HTML as React renders. Suspense fallbacks appear first, then resolved content streams in. Best for real users (fastest TTFB).
+- `"allReady"` — await `stream.allReady` before flushing. The full page arrives in one shot. Use for bots that cannot execute JavaScript or process chunked HTML.
+The resolver receives `{ request, env, url }` and may be sync or async. It only runs on HTML SSR paths — RSC partials, `__rsc` requests, and response routes are unaffected.
+When `resolveStreaming` is not configured, the default is `"stream"`.

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,79 @@
+---
+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 } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+// In a loader
+export const SettingsLoader = createLoader(async (ctx) => {
+  const currentTheme = ctx.theme; // read from cookie
+  return { theme: currentTheme };
+});
+// In middleware
+export const themeMiddleware: Middleware = 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)