@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.13221847

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,11 +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;
@@ -160,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,
 });
@@ -170,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 });
   },
 };
 ```
@@ -184,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 } }),
   }),
 });
 
@@ -198,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 });
   },
 };
 ```
@@ -286,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" }),
 ]);
@@ -298,23 +314,29 @@ 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<AppEnv>({
+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
@@ -344,3 +366,74 @@ const router = createRouter({
 
 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/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