@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/skills/composability/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: composability
+description: Reusable composition patterns with globally importable route helpers in @rangojs/router
+argument-hint: "pattern-name"
+---
+
+# Composability
+
+Route helpers can be imported directly from `@rangojs/router` and used to build reusable composition factories. This enables sharing common route configurations across multiple routes and modules.
+
+## Globally Importable Helpers
+
+These helpers can be imported and called outside the `urls()` callback parameter:
+
+```typescript
+import {
+  layout,
+  cache,
+  middleware,
+  revalidate,
+  loader,
+  loading,
+  parallel,
+  intercept,
+  when,
+  errorBoundary,
+  notFoundBoundary,
+} from "@rangojs/router";
+```
+
+They work because they use AsyncLocalStorage internally and resolve context at call time, not import time.
+
+## Why path() and include() Are Not Global
+
+`path()` and `include()` remain exclusive to the `urls()` callback:
+
+```typescript
+urls(({ path, include }) => [
+  path("/blog", BlogPage, { name: "blog" }),
+  include("/shop", shopPatterns, { name: "shop" }),
+]);
+```
+
+They define the route structure -- the URL patterns and how modules compose. Keeping them in the `urls()` callback makes the route tree readable at a glance. When scanning a URL file, `path()` and `include()` calls show what renders where. Moving them into factories would hide the routing structure and make it harder to understand which URLs exist and how they nest.
+
+The globally importable helpers (`cache`, `middleware`, `loading`, etc.) are configuration -- they modify behavior of routes but don't define routes themselves. Extracting them into factories doesn't obscure the route structure.
+
+## Composition Factories
+
+Define reusable factories that return arrays of use items:
+
+```typescript
+import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/router";
+
+// Shared caching configuration
+const withCaching = () => [
+  cache({ ttl: 600_000 }),
+  revalidate(({ actionId }) => !!actionId),
+];
+
+// Shared loading and error handling
+const withLoadingAndError = (skeleton: ReactNode) => [
+  loading(skeleton),
+  errorBoundary(() => <div>Something went wrong</div>),
+];
+
+// Shared auth middleware
+const withAuth = () => [
+  middleware(authMiddleware),
+  middleware(loggingMiddleware),
+];
+```
+
+## Using Factories in Routes
+
+Place factory calls inside `path()` or `layout()` use callbacks. The returned arrays are flattened automatically (up to 3 levels):
+
+```typescript
+import { urls } from "@rangojs/router";
+import { withCaching, withLoadingAndError, withAuth } from "./route-config";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  layout(<AppLayout />, () => [
+    withAuth(),
+
+    path("/blog", BlogIndex, { name: "blog" }, () => [
+      withCaching(),
+      withLoadingAndError(<BlogSkeleton />),
+    ]),
+
+    path("/shop", ShopIndex, { name: "shop" }, () => [
+      withCaching(),
+      withLoadingAndError(<ShopSkeleton />),
+    ]),
+  ]),
+]);
+```
+
+## Sharing Across Modules
+
+Factories can be defined in shared modules and reused across separate `urls()` definitions:
+
+```typescript
+// src/route-config.ts
+import { cache, revalidate, middleware } from "@rangojs/router";
+import { authMiddleware } from "./middleware/auth";
+
+export const withPublicDefaults = () => [
+  cache({ ttl: 300 }),
+  revalidate(({ actionId }) => !!actionId),
+];
+
+export const withProtectedDefaults = () => [
+  middleware(authMiddleware),
+  cache({ ttl: 60 }),
+];
+```
+
+```typescript
+// src/urls/blog.ts
+import { urls } from "@rangojs/router";
+import { withPublicDefaults } from "../route-config";
+
+export const blogPatterns = urls(({ path }) => [
+  path("/", BlogIndex, { name: "index" }, () => [withPublicDefaults()]),
+]);
+```
+
+```typescript
+// src/urls/admin.ts
+import { urls } from "@rangojs/router";
+import { withProtectedDefaults } from "../route-config";
+
+export const adminPatterns = urls(({ path }) => [
+  path("/", AdminDashboard, { name: "index" }, () => [withProtectedDefaults()]),
+]);
+```
+
+## Composition Types
+
+For typed factories, import the composition types:
+
+```typescript
+import type { RouteUseItem, LayoutUseItem, UseItems } from "@rangojs/router";
+
+// Factory for path() use callbacks
+const withCaching = (): RouteUseItem[] => [
+  cache({ ttl: 600_000 }),
+];
+
+// Factory for layout() use callbacks
+const withAuth = (): LayoutUseItem[] => [
+  middleware(authMiddleware),
+];
+
+// Factory that nests other factories (use UseItems for nested arrays)
+const withEverything = (): UseItems<RouteUseItem> => [
+  withCaching(),
+  loading(<Skeleton />),
+];
+```
+
+- `RouteUseItem[]` -- flat array for `path()` use callbacks
+- `LayoutUseItem[]` -- flat array for `layout()` use callbacks
+- `UseItems<T>` -- allows nested arrays from composing factories together
+
+## Rules
+
+- Helpers execute lazily -- factory functions are defined anywhere, but only called inside a `urls()` context (within `path()` or `layout()` use callbacks)
+- Calling helpers outside a `urls()` context throws an error
+- Nested arrays from factories are flattened automatically via `.flat(3)`
+- `path()` and `include()` cannot be used in factories -- they define route structure and must remain visible in the `urls()` callback

package/skills/debug-manifest/SKILL.md

@@ -11,6 +11,7 @@ Inspect the route manifest to verify parent relationships, shortCodes, and route
 ## Quick Access
 
 In development, visit:
+
 ```
 http://localhost:PORT/__debug_manifest
 ```
@@ -62,13 +63,13 @@ if (process.env.NODE_ENV !== "production") {
 
 ## ShortCode Format
 
-| Prefix | Meaning |
-|--------|---------|
-| **M** | Mount index (multiple `.routes()` calls) |
-| **L** | Layout |
-| **C** | Cache boundary |
-| **R** | Route |
-| **P** | Parallel slot |
+| Prefix | Meaning                                  |
+| ------ | ---------------------------------------- |
+| **M**  | Mount index (multiple `.routes()` calls) |
+| **L**  | Layout                                   |
+| **C**  | Cache boundary                           |
+| **R**  | Route                                    |
+| **P**  | Parallel slot                            |
 
 Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache → Route
 
@@ -85,7 +86,7 @@ Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache →
 import {
   serializeManifest,
   compareManifests,
-  formatManifestDiff
+  formatManifestDiff,
 } from "@rangojs/router/__internal";
 
 const oldManifest = await router.debugManifest();
@@ -99,10 +100,13 @@ console.log(formatManifestDiff(diff));
 ## Common Issues
 
 ### Routes have `parentShortCode: null`
+
 Routes should have a layout parent. Check that `urls()` handler is being wrapped in root layout.
 
 ### Missing layouts in hierarchy
+
 Verify `layout()` calls wrap child routes correctly.
 
 ### Wrong mount index
+
 Multiple `.routes()` calls create separate mounts (M0, M1, etc.). Use `include()` to share context.

package/skills/document-cache/SKILL.md

@@ -13,15 +13,15 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 Configure document cache in router:
 
 ```typescript
-import { createRSCRouter } from "@rangojs/router/server";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import { createRouter } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRSCRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx }),
+  documentCache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: ctx! }),
     skipPaths: ["/api", "/admin"],
     debug: process.env.NODE_ENV === "development",
   }),
@@ -35,7 +35,7 @@ export default router;
 Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, cache }) => [
   // Cache full page for 5 min, serve stale for 1 hour
@@ -56,11 +56,11 @@ export const urlpatterns = urls(({ path, cache }) => [
 ## Document Cache Options
 
 ```typescript
-createRSCRouter({
+createRouter({
   // ...
-  documentCache: (env) => ({
+  documentCache: (_env, ctx) => ({
     // Cache store (required)
-    store: new CFCacheStore({ ctx: env.ctx }),
+    store: new CFCacheStore({ ctx: ctx! }),
 
     // Skip specific paths
     skipPaths: ["/api", "/admin"],
@@ -102,6 +102,7 @@ Request → Check Cache
 ## Cache Status Header
 
 Response includes `x-document-cache-status`:
+
 - `HIT` - Fresh cache hit
 - `STALE` - Served stale, revalidating in background
 - `MISS` - Cache miss, response was generated fresh
@@ -109,6 +110,7 @@ Response includes `x-document-cache-status`:
 ## Cache Key Generation
 
 Default keys differentiate:
+
 - HTML requests: `{pathname}:html`
 - RSC partials: `{pathname}:{segmentHash}:rsc`
 
@@ -131,15 +133,15 @@ Segment hash ensures different cached responses for navigations from different s
 
 ```typescript
 // router.tsx
-import { createRSCRouter } from "@rangojs/router/server";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import { createRouter } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRSCRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx }),
+  documentCache: (_env, ctx) => ({
+    store: new CFCacheStore({ ctx: ctx! }),
     skipPaths: ["/api"],
     debug: process.env.NODE_ENV === "development",
   }),
@@ -148,7 +150,7 @@ const router = createRSCRouter<AppEnv>({
 export default router;
 
 // urls.tsx
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, cache, loader }) => [
   // Blog with document caching
@@ -170,11 +172,11 @@ export const urlpatterns = urls(({ path, layout, cache, loader }) => [
 
 ## Document Cache vs Segment Cache
 
-| Feature | Document Cache | Segment Cache |
-|---------|---------------|---------------|
-| Granularity | Full response | Individual segments |
-| Opt-in | `documentCache` in cache() | `cache({ ttl, swr })` |
-| Use case | Static pages | Dynamic compositions |
-| Key includes | URL + segment hash | Route params |
+| Feature      | Document Cache             | Segment Cache         |
+| ------------ | -------------------------- | --------------------- |
+| Granularity  | Full response              | Individual segments   |
+| Opt-in       | `documentCache` in cache() | `cache({ ttl, swr })` |
+| Use case     | Static pages               | Dynamic compositions  |
+| Key includes | URL + segment hash         | Route params          |
 
 Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.

package/skills/fonts/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: fonts
+description: Load and configure web fonts with preload hints for optimal performance
+argument-hint: [provider]
+---
+
+# Fonts
+
+Load web fonts in the Document component with `<link rel="preload">` for optimal performance. Fonts are declared in `<head>` alongside your stylesheet.
+
+## Google Fonts
+
+```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>
+        {/* Preconnect to Google Fonts */}
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link
+          rel="preconnect"
+          href="https://fonts.gstatic.com"
+          crossOrigin="anonymous"
+        />
+
+        {/* Load font stylesheet */}
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+          rel="stylesheet"
+        />
+
+        {/* App styles */}
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Then reference the font in CSS:
+
+```css
+/* src/index.css */
+body {
+  font-family: "Inter", sans-serif;
+}
+```
+
+Or with Tailwind (see `/tailwind`):
+
+```css
+/* src/index.css */
+@theme {
+  --font-sans: "Inter", sans-serif;
+}
+```
+
+## Self-Hosted Fonts
+
+Place font files in `public/fonts/` and use `@font-face`:
+
+```css
+/* src/index.css */
+@font-face {
+  font-family: "CustomFont";
+  src: url("/fonts/custom-regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "CustomFont";
+  src: url("/fonts/custom-bold.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+}
+
+body {
+  font-family: "CustomFont", sans-serif;
+}
+```
+
+Preload the most critical weight in the Document:
+
+```tsx
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link
+          rel="preload"
+          href="/fonts/custom-regular.woff2"
+          as="font"
+          type="font/woff2"
+          crossOrigin="anonymous"
+        />
+        <link rel="preload" href={styles} as="style" />
+        <link rel="stylesheet" href={styles} />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Fontsource (Recommended for Vite)
+
+`@fontsource-variable` packages are the recommended approach with Vite. Fonts are installed as npm dependencies, bundled by Vite, and served from your own domain -- no external requests, no privacy concerns, no FOUT from slow CDNs.
+
+```bash
+pnpm add @fontsource-variable/inter
+```
+
+Import the font CSS in your stylesheet. Vite resolves the `@fontsource-variable` import from `node_modules` and bundles the woff2 files as hashed assets automatically:
+
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+
+body {
+  font-family: "Inter Variable", sans-serif;
+}
+```
+
+With Tailwind:
+
+```css
+/* src/index.css */
+@import "@fontsource-variable/inter";
+@import "tailwindcss";
+
+@theme {
+  --font-sans: "Inter Variable", sans-serif;
+}
+```
+
+Why this is preferred over Google Fonts with Vite:
+
+- No external network requests at runtime -- fonts are bundled into your build output
+- No `<link rel="preconnect">` or extra stylesheet needed in the Document
+- Variable font = single file covers all weights, smaller total download
+- Vite handles cache-busting via content hashes
+- Works offline and in edge deployments (Cloudflare Workers) without external dependencies
+
+Browse available fonts at fontsource.org. Use `@fontsource-variable/*` for variable fonts and `@fontsource/*` for static fonts.
+
+## Performance Tips
+
+- Prefer `@fontsource-variable` with Vite for self-hosted, zero-config font loading
+- Use `font-display: swap` to prevent invisible text during font load
+- Preload only the most critical font weight (usually regular 400)
+- Prefer `woff2` format for smaller file sizes
+- Use variable fonts when multiple weights are needed to reduce total file count
+- `<link rel="preconnect">` eliminates DNS + TLS latency for external font providers