@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80

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

@@ -8,6 +8,9 @@ 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
@@ -54,6 +57,108 @@ parallel({
 })
 ```
 
+## Reading Handler Data
+
+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} />;
+      },
+    }),
+  ]),
+])
+```
+
+## Setting Handles (Meta, Breadcrumbs)
+
+Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
+push handle data. The data is associated with the **parent** layout or route
+segment, not the parallel segment itself. This is because parallels execute
+after their parent handler and inherit its segment scope.
+
+This works well for document-level metadata — the handle data follows the
+parent's lifecycle (appears when the parent is mounted, removed when it
+unmounts).
+
+```typescript
+parallel({
+  "@meta": (ctx) => {
+    const meta = ctx.use(Meta);
+    meta({ title: "Product Detail" });
+    meta({ name: "description", content: "..." });
+    return null; // UI-less slot, only sets metadata
+  },
+  "@sidebar": (ctx) => <Sidebar />,
+})
+```
+
+Multiple parallels on the same parent can each push handle data — they all
+accumulate under the parent segment ID.
+
+### Pattern: `@meta` slot for per-route metadata overrides
+
+A dedicated `@meta` parallel slot lets routes define metadata separately from
+their handler logic. The layout sets defaults via a title template, and each
+route overrides via its own `@meta` slot. Since child segments push after
+parents and `collectMeta` uses last-wins deduplication, overrides work
+naturally.
+
+```typescript
+// Layout sets defaults
+layout((ctx) => {
+  ctx.use(Meta)({ title: { template: "%s | Store", default: "Store" } });
+  return <StoreLayout />;
+}, () => [
+  // Route with @meta override — decoupled from handler rendering
+  path("/:slug", ProductPage, { name: "product" }, () => [
+    parallel({
+      "@meta": async (ctx) => {
+        const product = await ctx.use(ProductLoader);
+        const meta = ctx.use(Meta);
+        meta({ title: product.name });
+        meta({ name: "description", content: product.description });
+        meta({
+          "script:ld+json": {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            name: product.name,
+            description: product.description,
+          },
+        });
+        return null; // UI-less slot
+      },
+    }),
+  ]),
+])
+```
+
+This keeps the route handler focused on rendering UI while metadata
+(title, description, Open Graph, JSON-LD) lives in a composable slot that
+can be added, removed, or swapped per route without touching the handler.
+
 ## Parallel Routes with Loaders
 
 Add loaders and loading states to parallel routes:
@@ -71,6 +176,124 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Composable Slots via `handler.use`
+
+Slot handlers can carry their own loader, loading, error/notFound boundaries, revalidation, and transition defaults via `.use`. The mount site then declares **just the slot names** — no per-call data wiring.
+
+```typescript
+const CartSummary: Handler = async (ctx) => {
+  const cart = await ctx.use(CartLoader);
+  return <CartSummaryView cart={cart} />;
+};
+CartSummary.use = () => [
+  loader(CartLoader),
+  loading(<CartSkeleton />),
+  revalidate(revalidateCartData),
+];
+
+// Same slot, no copy-pasted plumbing across layouts.
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+
+layout(<AccountLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/account", AccountIndex, { name: "account.index" }),
+]);
+```
+
+A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
+
+The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
+
+### Two scopes for explicit `use`: shared (broadcast) and slot-local
+
+`parallel({...slots}, () => [...use])` runs the shared `use()` callback **once per slot** ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)) — items in that callback land on every slot's entry. That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`). (Slots cannot bring `middleware` or `layout` — see the allowed-types note above.)
+
+For single-assignment items like `loading()`, broadcasting overwrites every slot's `handler.use` default. Pass a **slot descriptor** `{ handler, use }` instead — items in the descriptor's `use` apply only to that slot:
+
+```typescript
+// @cart gets a custom skeleton; @notifs keeps its handler.use default.
+parallel({
+  "@cart": {
+    handler: Cart,
+    use: () => [loading(<CustomCartSkeleton />)],
+  },
+  "@notifs": Notifs,
+});
+
+// Opt one slot out of streaming while siblings still stream the broadcast.
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] },
+    "@notifs": Notifs,
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript
@@ -97,7 +320,7 @@ Render different content based on context:
 ```typescript
 parallel({
   "@sidebar": (ctx) => {
-    const user = ctx.env.Variables.user;
+    const user = ctx.get("user");
     return user ? <UserSidebar user={user} /> : <GuestSidebar />;
   },
 })
@@ -120,6 +343,45 @@ parallel(
 )
 ```
 
+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 { revalidate } from "@rangojs/router";
+
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
 ## Named Outlets
 
 Use `ParallelOutlet` to render slots in layouts: