@rangojs/router 0.0.0-experimental.4 → 0.0.0-experimental.40

package/skills/route/SKILL.md

@@ -74,8 +74,45 @@ path("/product/:slug", async (ctx) => {
 
 ```typescript
 path("/product/:slug", ProductPage, {
-  name: "product",  // Route name for href() and navigation
-})
+  name: "product", // Route name for href() and navigation
+});
+```
+
+### Typed Search Params
+
+Add a `search` schema to get typed `ctx.search`:
+
+```typescript
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?", sort: "string?" },
+});
+```
+
+Use `Handler<"name">` for typed search params (resolves from the generated route map automatically):
+
+```typescript
+import type { Handler } from "@rangojs/router";
+
+export const SearchPage: Handler<"search"> = (ctx) => {
+  // ctx.search is typed: { q: string; page?: number; sort?: string }
+  const { q, page, sort } = ctx.search;
+  // ctx.searchParams is always URLSearchParams
+  return <SearchResults q={q} page={page} sort={sort} />;
+};
+```
+
+Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
+Missing params are `undefined` regardless of required/optional. The required/optional
+distinction is a consumer-facing contract (for `href()` and `reverse()` autocomplete).
+
+Use `RouteSearchParams<"name">` and `RouteParams<"name">` to extract types for props:
+
+```typescript
+import type { RouteSearchParams, RouteParams } from "@rangojs/router";
+
+type SP = RouteSearchParams<"search">; // { q: string; page?: number; sort?: string }
+type P = RouteParams<"blogPost">; // { slug: string }
 ```
 
 ## Route Children
@@ -90,17 +127,193 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ])
 ```
 
+## Handler Data Ownership
+
+When a route has children (orphan layouts, parallels), the handler executes
+first. Use `ctx.set(key, value)` to share data with children, who read it
+via `ctx.get(key)`. Caching wraps all segments together, so either all run
+or none do.
+
+### Typed context variables with createVar
+
+Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
+The token is imported by both the handler (producer) and layout (consumer),
+making the data contract explicit and compile-time verified:
+
+```typescript
+import { createVar } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+// Typed token -- shared between handler and layout
+interface DashboardData {
+  title: string;
+  stats: { views: number };
+}
+const Dashboard = createVar<DashboardData>();
+
+path("/dashboard/:id", async (ctx) => {
+  const data = await fetchDashboard(ctx.params.id);
+  ctx.set(Dashboard, data);   // type-checked
+  return <DashboardPage data={data} />;
+}, { name: "dashboard" }, () => [
+  layout((ctx) => {
+    const data = ctx.get(Dashboard);  // typed as DashboardData | undefined
+    return (
+      <div>
+        <h1>{data?.title}</h1>
+        <Outlet />
+        <ParallelOutlet name="@sidebar" />
+      </div>
+    );
+  }),
+  parallel({
+    "@sidebar": (ctx) => {
+      const data = ctx.get(Dashboard);
+      return <Sidebar stats={data?.stats} />;
+    },
+  }),
+])
+```
+
+String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
+`createVar<T>()` is preferred for type safety.
+
+Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
+and intercepts can only read via `ctx.get()`.
+
+### Revalidation Contracts for Handler Data
+
+Handler-first guarantees apply within a single full render pass. For partial
+action revalidation, define named revalidation contracts and reuse them on both
+the producer route and the consumer child segments.
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCheckoutData = ({ actionId }) =>
+  actionId?.includes("src/actions/checkout.ts#") ?? false;
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidate(revalidateCheckoutData), // producer (route handler) reruns
+  layout(CheckoutLayout, () => [
+    revalidate(revalidateCheckoutData), // consumer reruns
+    parallel({ "@summary": CheckoutSummary }, () => [
+      revalidate(revalidateCheckoutData),
+    ]),
+  ]),
+]);
+```
+
+If children depend on multiple upstream domains, compose multiple contracts on
+the same segment (`revalidateAuthData`, `revalidateCheckoutData`, and so on).
+
+For cleaner route trees, expose contract helpers and spread them:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCheckout = () => [revalidate(revalidateCheckoutData)];
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidateCheckout(),
+  layout(CheckoutLayout, () => [revalidateCheckout()]),
+]);
+```
+
+For scope/revalidation guarantees and non-guarantees, see:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
+## Redirects
+
+### Basic redirect
+
+```typescript
+import { redirect } from "@rangojs/router";
+
+path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
+```
+
+### Redirect with custom status
+
+```typescript
+path("/moved", () => redirect("/new-location", 301), { name: "moved" });
+```
+
+### Redirect with location state
+
+Carry typed state through redirects (e.g. flash messages):
+
+```typescript
+import { redirect, createLocationState } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+
+path(
+  "/save",
+  (ctx) => {
+    // ... save logic
+    return redirect("/dashboard", {
+      state: [FlashMessage({ text: "Item saved!" })],
+    });
+  },
+  { name: "save" },
+);
+
+// With custom status + state
+path(
+  "/action",
+  (ctx) => {
+    return redirect("/target", {
+      status: 303,
+      state: [FlashMessage({ text: "Action complete" })],
+    });
+  },
+  { name: "action" },
+);
+```
+
+Read the state on the target page with `useLocationState(FlashMessage)`. The
+`{ flash: true }` option makes it auto-clear. Without `{ flash: true }`,
+state persists on back/forward. See `/hooks` for details.
+
+### ctx.setLocationState()
+
+Attach location state to any server response (not just redirects):
+
+```typescript
+path("/dashboard", (ctx) => {
+  ctx.setLocationState(ServerInfo({ data: "welcome" }));
+  return <Dashboard />;
+}, { name: "dashboard" })
+```
+
+State flows to the browser via the RSC payload and is merged into
+`history.pushState()`. Only works for SPA (partial) navigations.
+
 ## Handler Context
 
 Every handler receives a context object:
 
 ```typescript
-interface HandlerContext<TParams = Record<string, string>> {
-  params: TParams;           // URL parameters
-  request: Request;          // Original request
-  url: URL;                  // Parsed URL
-  env: TEnv;                 // Environment (bindings + variables)
-  use<T>(handle: Handle<T>): T;  // Access handles
+interface HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch = {}> {
+  params: TParams; // URL parameters
+  request: Request; // Original request
+  searchParams: URLSearchParams; // Query params (always URLSearchParams)
+  search: {} | ResolveSearchSchema<TSearch>; // Typed search params (from search schema)
+  url: URL; // Parsed URL
+  env: TEnv; // Environment (bindings + variables)
+  set(key: string, value: any): void; // Set context variable (untyped string key)
+  set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
+  get(key: string): any; // Read context variable (untyped string key)
+  get<T>(contextVar: ContextVar<T>): T | undefined; // Read typed context variable
+  use<T>(handle: Handle<T>): T; // Access handles
+  reverse(
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ): string; // URL generation
+  setLocationState(entries: LocationStateEntry[]): void; // Attach state to response
 }
 ```
 
@@ -111,11 +324,11 @@ path("/product/:slug", (ctx) => {
   // Access URL params
   const { slug } = ctx.params;
 
-  // Access query params
-  const tab = ctx.url.searchParams.get("tab");
+  // Access query params (untyped - use search schema for typed access)
+  const tab = ctx.searchParams.get("tab");
 
-  // Access environment
-  const db = ctx.env.Bindings.DB;
+  // Access platform bindings
+  const db = ctx.env.DB;
 
   // Access handles
   const breadcrumbs = ctx.use(Breadcrumbs);
@@ -142,8 +355,7 @@ urls(({ path, layout }) => [
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router";
-import { Breadcrumbs } from "./handles/breadcrumbs";
+import { urls, Breadcrumbs } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, loader, loading }) => [
   // Simple route

package/skills/router-setup/SKILL.md

@@ -50,20 +50,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading }) => [
 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
-]);
+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
@@ -76,7 +78,7 @@ interface RSCRouterOptions<TEnv> {
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
-  // Enable performance metrics
+  // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
   // Default error boundary
@@ -97,8 +99,25 @@ interface RSCRouterOptions<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>;
+  nonce?: (
+    request: Request,
+    env: TEnv,
+  ) => string | true | Promise<string | true>;
 
   // RSC version string (for router.fetch)
   version?: string;
@@ -157,7 +176,7 @@ import { createRouter } from "@rangojs/router";
 import { Document } from "./document";
 import { urlpatterns } from "./urls";
 
-export const router = createRouter<AppEnv>({
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
 });
@@ -167,7 +186,7 @@ import { router } from "./router";
 
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-    return router.fetch(request, { Bindings: env, Variables: {}, ctx });
+    return router.fetch(request, { env, ctx });
   },
 };
 ```
@@ -181,12 +200,12 @@ For per-request cache configuration (e.g., Cloudflare Workers with ExecutionCont
 import { createRouter } from "@rangojs/router";
 import { CFCacheStore } from "@rangojs/router/cache";
 
-export const router = createRouter<AppEnv>({
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  // Cache config receives env with ctx for ExecutionContext access
-  cache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx, defaults: { ttl: 60 } }),
+  // Cache config receives (env, ctx) separately
+  cache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: ctx!, defaults: { ttl: 60 } }),
   }),
 });
 
@@ -195,7 +214,7 @@ import { router } from "./router";
 
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-    return router.fetch(request, { Bindings: env, Variables: {}, ctx });
+    return router.fetch(request, { env, ctx });
   },
 };
 ```
@@ -283,10 +302,10 @@ export const shopPatterns = urls(({ path, layout }) => [
 ]);
 
 // src/urls.tsx
-import { urls, include } from "@rangojs/router";
+import { urls } from "@rangojs/router";
 import { shopPatterns } from "./urls/shop";
 
-export const urlpatterns = urls(({ path }) => [
+export const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/shop", shopPatterns, { name: "shop" }),
 ]);
@@ -295,21 +314,126 @@ export const urlpatterns = urls(({ path }) => [
 ## Environment Types
 
 ```typescript
-import type { RouterEnv } from "@rangojs/router";
-
+// 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 };
 }
 
-type AppEnv = RouterEnv<AppBindings, AppVariables>;
+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.
 
-const router = createRouter<AppEnv>({
+```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

@@ -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

@@ -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