@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.bd6e11bc

package/skills/mime-routes/SKILL.md

@@ -108,6 +108,33 @@ 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.
 
+## Type Safety For Negotiated Paths
+
+`router.named-routes.gen.ts` validates route names, params, search, `href()`, and
+the `Rango.Path` type, but it does not carry response payload metadata. For MIME or
+response payload types, use one of these surfaces:
+
+- `RouteResponse<typeof patterns, "routeName">` for a specific response variant
+  by route name. This is the clearest option when several MIME variants share
+  one URL pattern.
+- `Rango.PathResponse<"/products/:id">` (ambient, no import) for global lookup by URL pattern or concrete path after the app
+  registers `typeof router.routeMap`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+`RegisteredRoutes` is what exposes the richer routeMap entries containing
+response payload metadata. Without it, URL-pattern response lookup has paths but
+no payloads, so response types resolve to `ResponseEnvelope<never>`.
+
 ## How It Works
 
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.

package/skills/observability/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: observability
+description: Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing
+argument-hint:
+---
+
+# Observability
+
+Use this when you need to understand request latency, cache decisions,
+revalidation behavior, loader overlap, or production traces.
+
+Rango exposes two complementary observability surfaces:
+
+1. **Performance timeline** (`debugPerformance`) — per-request waterfall for
+   local or targeted debugging. It prints to the console and emits
+   `Server-Timing`.
+2. **Structured telemetry** (`telemetry`) — lifecycle events sent to a pluggable
+   sink for production monitoring, OpenTelemetry, or custom metrics.
+
+The essentials are below. The exported `TelemetryEvent` union type
+(`import type { TelemetryEvent } from "@rangojs/router"`) is the full event
+contract — every event kind and its fields are typed there.
+
+## Performance timeline
+
+Enable globally while debugging:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+});
+```
+
+Or enable for selected requests from middleware:
+
+```typescript
+middleware(async (ctx, next) => {
+  if (ctx.url.searchParams.has("debug")) {
+    ctx.debugPerformance();
+  }
+  await next();
+});
+```
+
+Call `ctx.debugPerformance()` before `await next()`. The request then prints a
+shared-axis waterfall and adds a `Server-Timing` header.
+
+Read the timeline as intervals:
+
+- `handler:total` is the whole router request.
+- `render:total` / `ssr-render-html` show the render pass.
+- `loader:*` rows should overlap render work. If a loader starts only after the
+  render bar, it is serialized latency.
+- Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
+  appear as separate spans, so the slow phase is visible without guessing.
+
+## Structured telemetry
+
+Use telemetry when you want durable production events rather than a one-request
+debug waterfall.
+
+```typescript
+import { createRouter, createConsoleSink } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
+```
+
+For OpenTelemetry:
+
+```typescript
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
+
+Custom sinks implement `emit(event)`:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: {
+    emit(event) {
+      myMetrics.record(event);
+    },
+  },
+});
+```
+
+Events include `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, and `revalidation.decision`.
+
+## Debugging revalidation and stale data
+
+When stale UI or unexpected partial renders are the question, use all three
+layers together:
+
+```typescript
+import { createConsoleSink, createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+  telemetry: createConsoleSink(),
+});
+```
+
+Then inspect:
+
+- `revalidation.decision` telemetry to see which segment re-ran or skipped.
+- cache spans / `cache.decision` events to see hit, miss, stale, and background
+  revalidation behavior.
+- loader spans to confirm live loaders overlap the render rather than blocking
+  first paint.
+- the `Server-Timing` header to compare local logs with browser-network timing.
+
+## Zero-overhead defaults
+
+`debugPerformance` is off by default, and `telemetry` emits nothing unless a sink
+is configured. Per-request `ctx.debugPerformance()` lets you turn on the
+waterfall only for the route, user, or query param you are investigating.

package/skills/parallel/SKILL.md

@@ -8,9 +8,6 @@ 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
@@ -92,6 +89,73 @@ path("/dashboard/:id", (ctx) => {
 ])
 ```
 
+## 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:
@@ -109,6 +173,126 @@ 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.
+
+`transition` is allowed in the slot allow-list, but slot-level rendering does **not** currently apply a `<ViewTransition>` wrapper — only the layout/route wraps take effect at render time. For a modal-only morph today, use an element-level React `<ViewTransition>` inside the slot's component. The reverse direction is the useful guarantee: a layout-level `transition()` fires when the layout's default outlet content changes but **not** when a `<ParallelOutlet />` mounts new content (modal opens are not subtree updates of the layout VT). See [skills/view-transitions](../view-transitions/SKILL.md) for the wrap rules and the intercept caveat.
+
+### 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
@@ -153,7 +337,7 @@ parallel(
   () => [
     loader(CartLoader),
     // Revalidate when cart actions occur
-    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
   ]
 )
 ```
@@ -162,6 +346,13 @@ 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.
 
+A `revalidate()` callback may return a hard `boolean`, a soft
+`{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /
+`undefined`) to defer to the next revalidator. See
+[loader/SKILL.md#revalidate-return-shapes](../loader/SKILL.md#revalidate-return-shapes)
+for the full contract — it's the same across `loader()`, `path()`,
+`layout()`, `parallel()`, and `intercept()`.
+
 ### Revalidation Contracts for Parallel Dependencies
 
 Prefer named revalidation contracts shared by both the upstream producer and
@@ -170,7 +361,7 @@ the parallel consumer:
 ```typescript
 // revalidation-contracts.ts
 export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") ?? false;
+  actionId?.includes("src/actions/cart.ts#") || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -288,7 +479,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
       ]
     ),