@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20

package/skills/mime-routes/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: mime-routes
+description: Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header
+argument-hint: [negotiate|vary|accept]
+---
+
+# Content Negotiation (MIME Routes)
+
+Content negotiation lets you register multiple response types on the same URL pattern.
+The router inspects the `Accept` header and dispatches to the matching handler.
+All negotiated responses include `Vary: Accept` for correct CDN/cache behavior.
+
+See also: `/response-routes` for the base response route API (path.json, path.text, etc.).
+
+## Defining Negotiated Routes
+
+Declare the same URL pattern with both an RSC route and one or more response-type routes.
+Order within the `urls()` array does not matter — the trie merges them at build time.
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout, include }) => [
+  // RSC page + JSON API on the same URL
+  path("/products/:id", ProductPage, { name: "product" }),
+  path.json(
+    "/products/:id",
+    (ctx) => {
+      return db.getProduct(ctx.params.id);
+    },
+    { name: "productJson" },
+  ),
+]);
+```
+
+When a browser requests `/products/42` (`Accept: text/html`), the RSC page renders.
+When an API client requests the same URL (`Accept: application/json`), the JSON handler runs.
+
+## Negotiation Rules
+
+1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
+2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
+3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
+4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins)
+5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
+
+RSC participates as a `text/html` candidate alongside response-type variants.
+There is no special short-circuit — RSC follows the same negotiation rules as other types.
+
+The MIME mapping used for matching:
+
+| Tag                  | MIME type                                                    |
+| -------------------- | ------------------------------------------------------------ |
+| RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
+| `json`               | `application/json`                                           |
+| `text`               | `text/plain`                                                 |
+| `xml`                | `application/xml`                                            |
+| `html`               | `text/html`                                                  |
+| `md`                 | `text/markdown`                                              |
+
+RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
+The browser's RSC runtime decodes this transparently — clients requesting `text/html` get
+the RSC page rendered normally.
+
+Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
+
+## Multiple Response Types
+
+A single URL can have an RSC route plus multiple response-type variants:
+
+```typescript
+export const urlpatterns = urls(({ path }) => [
+  path("/data", DataPage, { name: "data" }),
+  path.json("/data", () => ({ format: "json" }), { name: "dataJson" }),
+  path.text("/data", () => "plain text", { name: "dataText" }),
+  path.xml("/data", () => "<root>xml</root>", { name: "dataXml" }),
+]);
+```
+
+- `Accept: text/html` — RSC page
+- `Accept: application/json` — JSON handler
+- `Accept: text/plain` — text handler
+- `Accept: application/xml` — XML handler
+- `Accept: */*` — first variant (JSON, since it was registered first)
+
+## Wildcard Routes
+
+Content negotiation works with wildcard `/*` patterns:
+
+```typescript
+path("/files/*", FileBrowserPage, { name: "files" }),
+path.json("/files/*", (ctx) => {
+  const filePath = ctx.params["*"];
+  return { entries: listDir(filePath) };
+}, { name: "filesJson" }),
+```
+
+## Response-Only Negotiation (No RSC Primary)
+
+Two or more response-type routes can share a URL without an RSC route.
+The last registered route becomes the primary; earlier ones become variants:
+
+```typescript
+path.json("/api/data", () => ({ format: "json" }), { name: "dataJson" }),
+path.text("/api/data", () => "plain text version", { name: "dataText" }),
+```
+
+Without an RSC primary, there is no `text/html` candidate — the Accept header
+picks among the response-type candidates directly.
+
+## How It Works
+
+1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.
+   RSC routes become the primary trie leaf; response-type routes are stored in the `nv`
+   (negotiate variants) array on the leaf. The `rf` (rsc-first) flag tracks definition order.
+2. **Runtime**: `previewRoute()` reads `negotiateVariants` from the trie match result.
+   It parses the `Accept` header (extracting q-values and order), builds a candidate list
+   (RSC as `text/html` + response-type variants), and calls `pickNegotiateVariant()`.
+3. **Candidate matching**: walks the client's sorted Accept list (by q desc, then order asc),
+   matching each entry against candidates. Wildcards (`*/*`, `text/*`) fall back to definition order.
+4. **Vary header**: both the response-route handler wrapper and the RSC handler wrapper
+   append `Vary: Accept` when the `negotiated` flag is set on the preview result.
+
+## Caching Considerations
+
+`Vary: Accept` is set automatically on all negotiated responses. This tells CDNs and
+HTTP caches to store separate entries per Accept header value. No additional cache
+configuration is needed for negotiated routes — the framework handles it.

package/skills/parallel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parallel
-description: Define parallel routes for multi-column layouts, sidebars, and modal slots in rsc-router
+description: Define parallel routes for multi-column layouts, sidebars, and modal slots in @rangojs/router
 argument-hint: [@slot-name]
 ---
 
@@ -8,38 +8,41 @@ argument-hint: [@slot-name]
 
 Parallel routes render multiple components simultaneously in named slots.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Parallel Routes
 
 ```typescript
-import { map } from "rsc-router/server";
-import { ParallelOutlet } from "rsc-router";
-
-// Handler definition
-export default map<typeof routes>(({ route, layout, parallel }) => [
-  layout(
-    () => (
-      <DashboardLayout>
-        <aside>
-          <ParallelOutlet name="@sidebar" />
-        </aside>
-        <main>
-          <Outlet />
-        </main>
-        <div className="notifications">
-          <ParallelOutlet name="@notifications" />
-        </div>
-      </DashboardLayout>
-    ),
-    () => [
-      parallel({
-        "@sidebar": () => <Sidebar />,
-        "@notifications": () => <NotificationPanel />,
-      }),
-
-      route("dashboard.index", DashboardIndex),
-      route("dashboard.analytics", Analytics),
-    ]
-  ),
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <aside>
+        <ParallelOutlet name="@sidebar" />
+      </aside>
+      <main>
+        <Outlet />
+      </main>
+      <div className="notifications">
+        <ParallelOutlet name="@notifications" />
+      </div>
+    </div>
+  );
+}
+
+export const urlpatterns = urls(({ path, layout, parallel }) => [
+  layout(<DashboardLayout />, () => [
+    parallel({
+      "@sidebar": () => <Sidebar />,
+      "@notifications": () => <NotificationPanel />,
+    }),
+
+    path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+    path("/dashboard/analytics", Analytics, { name: "dashboard.analytics" }),
+  ]),
 ]);
 ```
 
@@ -49,207 +52,254 @@ Access route params and loaders in parallel slots:
 
 ```typescript
 parallel({
-  "@sidebar": (ctx) => {
-    const user = ctx.get("user");
-    return <UserSidebar user={user} />;
-  },
-  "@details": async (ctx) => {
-    const data = await ctx.use(DetailsLoader);
-    return <DetailsPanel data={data} productId={ctx.params.id} />;
-  },
+  "@sidebar": (ctx) => <Sidebar userId={ctx.params.userId} />,
+  "@related": (ctx) => <RelatedProducts slug={ctx.params.slug} />,
 })
 ```
 
-## Parallel Routes with Configuration
+## Reading Handler Data
 
-Add loaders, loading states, and revalidation to slots:
+Parallels can read `ctx.set()` values from their parent handler or layout
+via `ctx.get()`. The handler always executes before its parallels
+(handler-first).
+
+Visibility follows tree structure:
+
+- Layout-level parallels see layout data, but not path handler data
+  (the path is a separate entry).
+- Parallels inside a path (or its orphan layouts) see both layout and
+  path handler data.
+
+This applies to full render passes. During partial action revalidation,
+only revalidated segments are recomputed. If a parallel depends on data
+set by an outer handler or layout, revalidate that outer segment too, or
+have the parallel reload/guard the data itself.
+
+```typescript
+path("/dashboard/:id", (ctx) => {
+  const user = await getUser(ctx.params.id);
+  ctx.set("user", user);
+  return <DashboardPage user={user} />;
+}, { name: "dashboard" }, () => [
+  layout(DashboardLayout, () => [
+    parallel({
+      "@sidebar": (ctx) => {
+        const user = ctx.get("user");
+        return <Sidebar role={user?.role} />;
+      },
+    }),
+  ]),
+])
+```
+
+## Parallel Routes with Loaders
+
+Add loaders and loading states to parallel routes:
 
 ```typescript
 parallel(
   {
-    "@sidebar": async (ctx) => {
-      const categories = await ctx.use(CategoriesLoader);
-      return <CategorySidebar categories={categories} />;
-    },
-    "@cart": async (ctx) => {
-      const cart = await ctx.use(CartLoader);
-      return <CartPreview cart={cart} />;
-    },
+    "@sidebar": () => <CategorySidebar />,
   },
   () => [
     loader(CategoriesLoader),
-    loader(CartLoader),
     loading(<SidebarSkeleton />),
-    revalidate(({ actionId }) => actionId?.includes("cart") ?? false),
+    revalidate(() => false),  // Never revalidate sidebar
   ]
 )
 ```
 
-## Independent Slot Revalidation
-
-Each parallel slot can control its own revalidation:
+## Multiple Parallel Slots
 
 ```typescript
-layout(<DashboardLayout />, () => [
-  // Sidebar only revalidates on sidebar actions
-  parallel(
-    { "@sidebar": SidebarComponent },
-    () => [
-      revalidate(({ actionId }) => actionId?.includes("sidebar") ?? false),
-    ]
-  ),
-
-  // Main content revalidates on route changes
-  parallel(
-    { "@main": MainComponent },
-    () => [
-      revalidate(({ currentParams, nextParams }) =>
-        currentParams.id !== nextParams.id
-      ),
-    ]
-  ),
-
-  route("dashboard.index", DashboardIndex),
-])
-```
-
-## Parallel Routes for Modals
-
-Use parallel routes with intercept for modal patterns:
-
-```typescript
-layout(
-  () => (
-    <ShopLayout>
-      <Outlet />
-      <ParallelOutlet name="@modal" />
-    </ShopLayout>
-  ),
-  () => [
-    parallel({
-      "@modal": () => null, // Empty by default
-    }),
-
-    // Intercept product detail into modal
-    intercept(
-      "@modal",
-      "products.detail",
-      (ctx) => <ProductModal id={ctx.params.id} />,
-      () => [
-        loader(ProductLoader),
-        loading(<ProductModalSkeleton />),
-      ]
+layout(<ShopLayout />, () => [
+  parallel({
+    "@promoBanner": () => (
+      <div className="promo-banner">
+        Summer Sale! 50% off selected items
+      </div>
     ),
+    "@sidebar": () => <CategorySidebar />,
+    "@cartPreview": () => <CartPreview />,
+    "@notification": () => <CartNotification />,
+  }),
 
-    route("products.index", ProductList),
-    route("products.detail", ProductDetail),
-  ]
-)
+  path("/shop", ShopIndex, { name: "shop" }),
+])
 ```
 
 ## Conditional Parallel Content
 
+Render different content based on context:
+
 ```typescript
 parallel({
   "@sidebar": (ctx) => {
     const user = ctx.get("user");
-    if (!user) return null; // Hide for guests
-    if (user.role === "admin") {
-      return <AdminSidebar />;
-    }
-    return <UserSidebar />;
+    return user ? <UserSidebar user={user} /> : <GuestSidebar />;
   },
 })
 ```
 
-## Parallel Routes with Error Boundaries
+## Parallel Routes with Revalidation
+
+Control when parallel routes revalidate:
 
 ```typescript
 parallel(
   {
-    "@sidebar": async (ctx) => {
-      const data = await ctx.use(SidebarLoader);
-      return <Sidebar data={data} />;
-    },
+    "@cart": () => <CartSummary />,
   },
   () => [
-    loader(SidebarLoader),
-    errorBoundary(({ error, reset }) => (
-      <div className="sidebar-error">
-        <p>Sidebar failed to load</p>
-        <button onClick={reset}>Retry</button>
-      </div>
-    )),
+    loader(CartLoader),
+    // Revalidate when cart actions occur
+    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
   ]
 )
 ```
 
-## ParallelOutlet Component
+Revalidating only the parallel does not re-run outer handlers/layouts.
+If the slot reads `ctx.get()` data established above it, opt the outer
+segment into revalidation as well.
+
+### Revalidation Contracts for Parallel Dependencies
+
+Prefer named revalidation contracts shared by both the upstream producer and
+the parallel consumer:
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#") ?? false;
+
+layout(CartLayout, () => [
+  revalidate(revalidateCartData), // producer reruns
+  parallel(
+    { "@cart": CartSummary },
+    () => [revalidate(revalidateCartData)], // consumer reruns
+  ),
+]);
+```
+
+If the slot consumes multiple upstream domains, compose the contracts on both
+segments.
+
+Handoff helper style also works:
 
 ```typescript
-import { ParallelOutlet } from "rsc-router";
+import { revalidate } from "@rangojs/router";
 
-function Layout() {
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
+## Named Outlets
+
+Use `ParallelOutlet` to render slots in layouts:
+
+```typescript
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function MyLayout() {
   return (
-    <div className="layout">
-      {/* Named slot - renders content from parallel() */}
-      <ParallelOutlet name="@sidebar" />
+    <div>
+      <header>
+        <ParallelOutlet name="@header" />
+      </header>
+
+      <div className="content">
+        <aside>
+          <ParallelOutlet name="@sidebar" />
+        </aside>
+
+        <main>
+          <Outlet />  {/* Main route content */}
+        </main>
 
-      {/* Main route content */}
-      <Outlet />
+        <aside>
+          <ParallelOutlet name="@rightPanel" />
+        </aside>
+      </div>
 
-      {/* Another slot */}
-      <ParallelOutlet name="@footer" />
+      <footer>
+        <ParallelOutlet name="@footer" />
+      </footer>
     </div>
   );
 }
 ```
 
-## Dashboard Example
+## Complete Example
 
 ```typescript
-// Complete dashboard with multiple panels
-export default map<typeof routes>(({ route, layout, parallel, loader }) => [
-  layout(
-    () => (
-      <div className="dashboard-grid">
-        <header>
-          <ParallelOutlet name="@header" />
-        </header>
-        <nav>
-          <ParallelOutlet name="@nav" />
-        </nav>
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function ShopLayout() {
+  return (
+    <div className="shop">
+      <ParallelOutlet name="@promoBanner" />
+      <div className="content">
+        <aside>
+          <ParallelOutlet name="@sidebar" />
+        </aside>
         <main>
           <Outlet />
         </main>
         <aside>
-          <ParallelOutlet name="@activity" />
+          <ParallelOutlet name="@cartPreview" />
         </aside>
       </div>
+      <ParallelOutlet name="@notification" />
+    </div>
+  );
+}
+
+export const shopPatterns = urls(({
+  path,
+  layout,
+  parallel,
+  loader,
+  loading,
+  revalidate,
+}) => [
+  layout(<ShopLayout />, () => [
+    // Simple parallel slot
+    parallel({
+      "@promoBanner": () => <PromoBanner />,
+    }),
+
+    // Parallel slot with loader
+    parallel(
+      { "@sidebar": () => <CategorySidebar /> },
+      () => [
+        loader(CategoriesLoader),
+        revalidate(() => false),
+      ]
+    ),
+
+    // Parallel slot with revalidation
+    parallel(
+      { "@cartPreview": () => <CartPreview /> },
+      () => [
+        loader(CartLoader),
+        loading(<CartSkeleton />),
+        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      ]
     ),
-    () => [
-      parallel({
-        "@header": () => <DashboardHeader />,
-        "@nav": (ctx) => <Navigation user={ctx.get("user")} />,
-        "@activity": async (ctx) => {
-          const activity = await ctx.use(ActivityLoader);
-          return <ActivityFeed items={activity} />;
-        },
-      }, () => [
-        loader(ActivityLoader),
-        revalidate(({ actionId }) => actionId?.includes("activity") ?? false),
-      ]),
-
-      route("dashboard.index", DashboardHome),
-      route("dashboard.projects", Projects),
-      route("dashboard.settings", Settings),
-    ]
-  ),
-]);
-```
 
-## Slot Naming Convention
+    // Notification slot
+    parallel({
+      "@notification": () => <CartNotification />,
+    }),
 
-- Prefix with `@` (e.g., `@sidebar`, `@modal`, `@header`)
-- Use lowercase with hyphens for multi-word names (`@user-panel`)
-- Common names: `@sidebar`, `@modal`, `@header`, `@footer`, `@notifications`, `@breadcrumbs`
+    // Routes
+    path("/", ShopIndex, { name: "index" }),
+    path("/product/:slug", ProductPage, { name: "product" }),
+  ]),
+]);
+```