@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/skills/cloudflare/references/webhooks-and-crypto.md

@@ -0,0 +1,147 @@
+# Webhooks and WebCrypto on Workers
+
+## Contents
+
+- [Read the original request body](#read-the-original-request-body)
+- [Test signed webhooks offline](#test-signed-webhooks-offline)
+- [Port Node crypto carefully](#port-node-crypto-carefully)
+- [Use Stripe 22 on workerd](#use-stripe-22-on-workerd)
+- [Keep SDKs off the cold path](#keep-sdks-off-the-cold-path)
+
+## Read the original request body
+
+Signature verification must receive the exact bytes sent by the provider:
+
+```typescript
+path.json("/api/webhook", async (ctx) => {
+  const rawBody = await ctx.request.text();
+  const signature = ctx.request.headers.get("provider-signature");
+  await verify(rawBody, signature);
+  return { ok: true };
+});
+```
+
+`path.json` describes the response representation; it does not parse or
+reserialize the incoming request. Use `path.any` only when the handler needs a
+fully manual `Response` contract or several methods/representations.
+
+## Test signed webhooks offline
+
+Use a fixed, non-production secret in the e2e environment. For Stripe, serialize
+the body once, sign `${timestamp}.${rawBody}`, format the real
+`stripe-signature` header, and send the same string:
+
+```typescript
+const rawBody = JSON.stringify(event);
+const key = await crypto.subtle.importKey(
+  "raw",
+  new TextEncoder().encode(WEBHOOK_SECRET),
+  { name: "HMAC", hash: "SHA-256" },
+  false,
+  ["sign"],
+);
+const signature = await crypto.subtle.sign(
+  "HMAC",
+  key,
+  new TextEncoder().encode(`${timestamp}.${rawBody}`),
+);
+const hex = Array.from(new Uint8Array(signature), (byte) =>
+  byte.toString(16).padStart(2, "0"),
+).join("");
+
+await request.post("/api/webhook", {
+  data: rawBody,
+  headers: {
+    "content-type": "application/json",
+    "stripe-signature": `t=${timestamp},v1=${hex}`,
+  },
+});
+```
+
+Assert the real D1 mutation through the public application route. Run the case
+under both dev and preview. Do not pass an object to the HTTP client after
+signing a string; another serialization can invalidate the signature.
+
+## Port Node crypto carefully
+
+TypeScript 5.9 defaults `Uint8Array` to `Uint8Array<ArrayBufferLike>`, while DOM
+WebCrypto accepts `ArrayBufferView<ArrayBuffer>`. Annotate byte-producing
+helpers that feed `crypto.subtle` precisely:
+
+```typescript
+function fromBase64(value: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(atob(value).length);
+  // fill bytes...
+  return bytes;
+}
+```
+
+WebCrypto AES-GCM returns `ciphertext || authenticationTag`. When preserving a
+Node format that stored the tag separately, split the final 16 bytes on encrypt
+and append them again before decrypting.
+
+## Use Stripe 22 on workerd
+
+Stripe 22 publishes a `workerd` export whose defaults use `fetch` and
+SubtleCrypto. Webhook verification must use the asynchronous API; the sync API
+cannot run a SubtleCrypto provider synchronously:
+
+```bash
+pnpm add stripe@^22
+```
+
+```typescript
+import Stripe from "stripe";
+
+path.json("/api/webhooks/stripe", async (ctx) => {
+  const rawBody = await ctx.request.text();
+  const signature = ctx.request.headers.get("stripe-signature");
+  if (!signature) throw new Response("Missing signature", { status: 400 });
+
+  const event = await Stripe.webhooks.constructEventAsync(
+    rawBody,
+    signature,
+    ctx.env.STRIPE_WEBHOOK_SECRET,
+  );
+
+  await ctx.env.DB.prepare(
+    "INSERT OR IGNORE INTO stripe_events (id, type, payload) VALUES (?, ?, ?)",
+  )
+    .bind(event.id, event.type, rawBody)
+    .run();
+  return { received: true };
+});
+```
+
+Use a small idempotency table for the offline assertion:
+
+```sql
+CREATE TABLE stripe_events (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+Using `Stripe.createFetchHttpClient()` and
+`Stripe.createSubtleCryptoProvider()` explicitly is defensive but not required
+when the `workerd` export is selected. Static `Stripe.webhooks` also means
+signature verification does not require a fabricated API key or Stripe client
+instance. The webhook signing secret, not the API secret key, authenticates the
+payload.
+
+These defaults are specific to Stripe 22. Revalidate the export map and crypto
+provider behavior when upgrading the SDK major.
+
+## Keep SDKs off the cold path
+
+Put a large, rarely used webhook/billing group behind an async include:
+
+```typescript
+include("/", () => import("./urls/billing.js"), { name: "billing" });
+```
+
+Measure a before/after production build before claiming an SDK's incremental
+cost. A chunk that contains the SDK is not itself proof that every byte was
+introduced by that dependency.

package/skills/composability/SKILL.md

@@ -171,6 +171,20 @@ import { shopPatterns } from "./shop-patterns";
 urls(({ include }) => [include("/shop", shopPatterns, { name: "shop" })]);
 ```
 
+The `name` option controls whether the child's named routes join the parent
+route map:
+
+| Form                                           | Name behavior                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------------ |
+| `include("/shop", patterns)`                   | private module scope; child names stay out of the app-wide generated map |
+| `include("/shop", patterns, { name: "shop" })` | namespace children as `shop.index`, `shop.product`, ...                  |
+| `include("/shop", patterns, { name: "" })`     | flatten children into the parent namespace                               |
+
+Omission is intentional for reusable/local modules, not a missing default. Use
+`{ name: "" }` only when the child names are globally unique and meant to be
+reversed from elsewhere. Inside the module, dot-local reversal and
+`scopedReverse()` work without flattening.
+
 Async — the module is code-split behind a `() => import()` thunk. It becomes its
 own chunk that is NOT evaluated at startup; the router imports it on the first
 request that reaches the prefix, then caches it:

package/skills/debug-manifest/SKILL.md

@@ -8,18 +8,10 @@ argument-hint:
 
 Inspect the route manifest to verify parent relationships, shortCodes, and route structure.
 
-## Quick Access
-
-In development, visit:
-
-```
-http://localhost:PORT/?__debug_manifest
-```
-
-Returns formatted JSON. The HTTP endpoint shape is `{ routerId, routeManifest, routeAncestry, routeTrie, precomputedEntries }` (see below for the programmatic API shape).
-
 ## Programmatic Access
 
+Call `router.debugManifest()` — an `async` method on the router instance:
+
 ```typescript
 import { router } from "./router.js";
 

package/skills/links/SKILL.md

@@ -38,6 +38,18 @@ export const shopPatterns = urls(({ path, layout }) => [
 - **`.name`** — local route, resolved within the current `include()` scope
 - **`name`** — global route, from the named-routes definition
 
+The include site decides which global names exist:
+
+| Include site                                       | App-wide names                                     |
+| -------------------------------------------------- | -------------------------------------------------- |
+| `include("/shop", shopPatterns)`                   | none from the child; use `.name` inside the module |
+| `include("/shop", shopPatterns, { name: "shop" })` | `shop.index`, `shop.product`, ...                  |
+| `include("/shop", shopPatterns, { name: "" })`     | `index`, `product`, ... at the parent scope        |
+
+Flatten only when those names are intentionally unique across the whole parent
+map. Private includes are useful for reusable modules and still support
+mount-aware dot-local reversal.
+
 ```typescript
 // Inside a handler within shopPatterns (mounted at /shop)
 path("/product/:slug", (ctx) => {

package/skills/middleware/SKILL.md

@@ -197,6 +197,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.request; // Request object
   ctx.url; // Parsed URL
   ctx.params; // Route parameters
+  ctx.build; // in middleware: true only during Prerender + ppr build-shell capture (plain Prerender does not run middleware)
 
   // Access platform bindings (plain bindings from createRouter<TEnv>())
   ctx.env.DB; // D1Database
@@ -205,6 +206,9 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
+  // Opt the current request out of PPR shell lookup/capture.
+  ctx.dynamic();
+
   // Continue to next middleware/handler
   await next();
 
@@ -246,6 +250,35 @@ This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
 via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
 data; use Rango.Vars for app-wide middleware state.
 
+## Build-Time PPR Middleware
+
+Normal `Prerender` Flight payload collection does not run middleware: there is
+no request to wrap. The exception is `Prerender` + `ppr` build-shell capture.
+After the Flight payload exists, the shell producer replays global and route
+middleware for each generated URL before it captures HTML.
+
+In that build-shell pass:
+
+- `ctx.build === true`;
+- `ctx.waitUntil()` is inert;
+- `ctx.dynamic()` skips the baked shell for that URL;
+- context variables set by middleware are visible to the shell render.
+
+Use this to keep side effects predictable:
+
+```typescript
+export const commerceMiddleware: Middleware = async (ctx, next) => {
+  if (ctx.build) {
+    ctx.dynamic(); // leave this shell to runtime PPR
+    return next();
+  }
+
+  const session = await commerce.auth(ctx.request);
+  ctx.set("session", session);
+  return next();
+};
+```
+
 ## Redirect with State in Middleware
 
 ```typescript

package/skills/migrate-nextjs/SKILL.md

@@ -47,6 +47,24 @@ Common reasons to migrate:
 
 Work route-by-route, bottom-up. Start with leaf pages, then layouts, then middleware. Verify each route works before moving to the next.
 
+### Phase 0: choose the migration boundary
+
+Before changing routes, classify the project. This decides whether existing
+database/auth code can actually carry over:
+
+| Migration           | What stays                                               | Additional work                                                        |
+| ------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Framework only      | runtime, database, auth provider                         | Next-to-Rango surface mapping in this skill                            |
+| Host/runtime swap   | database and auth, but Node becomes Workers/another host | SDK/runtime compatibility, bindings, secrets, filesystem/crypto checks |
+| Datastore/auth swap | host may stay, database or identity provider changes     | schema/data migration, authorization replacement, session cutover      |
+| Both                | only the product behavior stays                          | all of the above, with staged parity and rollback                      |
+
+For Cloudflare Workers, read `/cloudflare` before scaffolding. For a host,
+datastore, or auth swap, also read
+[backend-host-swap.md](backend-host-swap.md). Do not treat RLS policies,
+database functions, provider callbacks, or secret management as incidental
+route work.
+
 ## Replace imports, never shim Next
 
 Do NOT create mock `next/*` modules, Vite aliases for `next/*`, or compatibility
@@ -200,6 +218,18 @@ export const marketingPatterns = urls(({ path }) => [
 include("/", marketingPatterns, { name: "marketing" }),
 ```
 
+The `include()` name has three deliberate modes:
+
+| Form                                            | Child route names                                                       |
+| ----------------------------------------------- | ----------------------------------------------------------------------- |
+| `include("/", patterns)`                        | private to the included module; omitted from the app-wide generated map |
+| `include("/", patterns, { name: "marketing" })` | globally registered as `marketing.home`, `marketing.pricing`, ...       |
+| `include("/", patterns, { name: "" })`          | flattened into the parent map as `home`, `pricing`, ...                 |
+
+Use the empty-string form only when the child names are intentionally global
+and unique. Inside a private/namespaced module, prefer dot-local reversal or
+`scopedReverse()` rather than flattening solely for convenience.
+
 Next.js code-splits each route segment automatically. Rango's eager `include()`
 bundles the group into the entry chunk; to get Next-style per-section splitting,
 pass an async provider so the group loads on the first request under its prefix:
@@ -262,7 +292,10 @@ layout(<ShopLayout />, () => [
 
 ### Server component data fetching
 
-Inline `fetch()` or direct DB calls in server components work as-is — no migration needed:
+Inline `fetch()` or direct DB calls in server components keep the same Rango
+shape when the target runtime, database, driver, and authentication model remain
+compatible. A Node-to-Workers or Postgres-to-D1 move is a separate migration;
+run the Phase 0 audit before carrying those calls over unchanged.
 
 ```typescript
 // Next.js:
@@ -695,6 +728,21 @@ path.json("/api/users", async (ctx) => {
 path.text("/api/health", () => "ok", { name: "apiHealth" })
 ```
 
+Response routes treat returned responses as control-flow responses. A thrown
+`RouterError` becomes a structured API error. Do not assume every Next
+`NextResponse`/throw pattern maps identically:
+
+| In a response route             | Use                                                                  |
+| ------------------------------- | -------------------------------------------------------------------- |
+| custom status/body/headers      | `return new Response(...)`                                           |
+| structured thrown API error     | `throw new RouterError(...)`                                         |
+| intentional off-origin redirect | validate the target, then `return redirect(url, { external: true })` |
+
+Rango guards every browser-followed cross-origin `Location`. A raw unbranded
+cross-origin 3xx is rewritten to the app root; `{ external: true }` is the
+explicit, auditable opt-out for OAuth/SSO/payment callbacks. Never set it on an
+unvalidated user-provided URL.
+
 See `/response-routes` for full API.
 
 ## 10. Theme / Dark Mode
@@ -724,22 +772,23 @@ See `/theme` for full API including system detection and cookie persistence.
 
 ## Migration Checklist
 
-1. [ ] Set up Vite config with `rango()` plugin
-2. [ ] Create Document component (replaces root `<html>` layout)
-3. [ ] Create `router.tsx` with `createRouter()`
-4. [ ] Convert file-based routes to `urls()` DSL in `urls.tsx`
-5. [ ] Migrate layouts to `layout()` with `<Outlet />`
-6. [ ] Convert data fetching to `createLoader()` + `ctx.use()`
-7. [ ] Migrate `middleware.ts` to `router.use()` (auth, guards, logging)
-8. [ ] Replace `next/link` with `Link` from `@rangojs/router/client`
-9. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
-10. [ ] Migrate API routes to `path.json()` / `path.text()`
-11. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
-12. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
-13. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,
+1. [ ] Classify the migration boundary (framework, host/runtime, datastore/auth, or both)
+2. [ ] Set up Vite config with `rango()` plugin (and read `/cloudflare` for Workers)
+3. [ ] Create Document component (replaces root `<html>` layout)
+4. [ ] Create `router.tsx` with `createRouter()`
+5. [ ] Convert file-based routes to `urls()` DSL in `urls.tsx`
+6. [ ] Migrate layouts to `layout()` with `<Outlet />`
+7. [ ] Convert data fetching to `createLoader()` + `ctx.use()`
+8. [ ] Migrate `middleware.ts` to `router.use()` (auth, guards, logging)
+9. [ ] Replace `next/link` with `Link` from `@rangojs/router/client`
+10. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
+11. [ ] Migrate API routes to `path.json()` / `path.text()`
+12. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
+13. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
+14. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,
         `force-static` → `Static()`/`Prerender()`, `experimental_ppr` → the
         `ppr` path option (loader + `loading()` as the hole)
-14. [ ] Run `npx rango generate src/` to generate route types
-15. [ ] Verify no shims: `grep -rn "from ['\"]next" src/ app/` returns nothing,
+15. [ ] Run `npx rango generate src/` to generate route types
+16. [ ] Verify no shims: `grep -rn "from ['\"]next" src/ app/` returns nothing,
         no mock `next/*` modules or aliases exist, and `next` is out of
         `package.json`

package/skills/migrate-nextjs/backend-host-swap.md

@@ -0,0 +1,120 @@
+# Backend and host swap audit
+
+Use this audit when the Next-to-Rango migration also changes runtime, database,
+or authentication provider. Route parity is not backend parity.
+
+## Contents
+
+- [Choose ownership](#choose-ownership)
+- [Inventory database guarantees](#inventory-database-guarantees)
+- [Replace authorization deliberately](#replace-authorization-deliberately)
+- [Extract shared server services](#extract-shared-server-services)
+- [Keep mutation side effects caller-owned](#keep-mutation-side-effects-caller-owned)
+- [Audit runtime compatibility](#audit-runtime-compatibility)
+- [Plan cutover and rollback](#plan-cutover-and-rollback)
+
+## Choose ownership
+
+Write down which system owns each concern before porting code:
+
+| Concern                     | Existing owner          | Target owner                | Proof required                  |
+| --------------------------- | ----------------------- | --------------------------- | ------------------------------- |
+| session issuance/revocation | auth provider/app       | provider/app                | login, logout, expiry, rotation |
+| tenant authorization        | RLS/service             | DAL/middleware/service      | cross-tenant denial tests       |
+| invariants/atomicity        | DB function/trigger     | DB constraint/batch/service | concurrent mutation tests       |
+| scheduled/background work   | host/provider           | Worker queue/cron/waitUntil | retry/idempotency test          |
+| secrets                     | host env/provider vault | target secret store         | no client bundle leakage        |
+
+Do not let a concern become "application code" without naming the module that
+now enforces it.
+
+## Inventory database guarantees
+
+Search the source database for more than tables:
+
+- row-level security policies and grants;
+- functions/RPCs, triggers, generated columns, views, and extensions;
+- unique/check/foreign-key constraints;
+- transaction isolation, row locks, advisory locks, and sequences;
+- storage objects, realtime subscriptions, and database webhooks.
+
+For each item, choose one target:
+
+1. preserve it in the target database;
+2. replace it with a transaction/batch and application service;
+3. reject the feature as unsupported and surface that product gap.
+
+SQLite/D1 does not provide Postgres RLS, stored procedures, or row-level locking
+semantics. A mechanical schema conversion is therefore incomplete even when
+every table exists.
+
+## Replace authorization deliberately
+
+When RLS disappears, build an actor/tenant-scoped data-access layer. Accept an
+actor and tenant scope at the repository boundary, verify membership/role, and
+perform the data query through that scope. Avoid exporting an unrestricted DB
+handle to page handlers.
+
+Tests must prove denial, not only success:
+
+- a user cannot read another tenant by guessing an ID;
+- a member cannot perform an owner/admin mutation;
+- a revoked session/token fails immediately enough for the product contract;
+- background jobs and webhooks use an explicit service identity;
+- every API/loader/action path reaches the same guard.
+
+## Extract shared server services
+
+Search server-only Next code for self-calls such as `fetch("/api/...")` or a
+fully qualified request back to the same deployment. On Workers that is a real
+subrequest with added latency and another authentication pass. Extract the
+business operation into a plain service function instead:
+
+```typescript
+async function createProposal(db, scope, actor, input) {
+  // validate, authorize, and mutate once
+}
+```
+
+Let the HTTP response route and an MCP/OAuth/server caller each authenticate in
+their own protocol, derive the same scope, and call that function in-process.
+Keep the HTTP route as an auth-and-delegate boundary for external clients, not
+as the unit of reuse inside the Worker.
+
+## Keep mutation side effects caller-owned
+
+Audit low-level mutations for bundled effects such as activity rows, audit
+logs, cache invalidation, emails, and webhooks. A primitive written for a direct
+edit can double-log when a reviewed proposal later composes the same primitive.
+Prefer an atomic mutation with caller-selected effects, or expose an explicit
+option such as `{ logActivity: false }`. Test composed flows for effect counts,
+not only final row state.
+
+## Audit runtime compatibility
+
+For a Node-to-Workers move, search for:
+
+- `node:*` modules, filesystem/process access, native addons, and TCP clients;
+- SDKs whose default HTTP or crypto implementation is Node-only;
+- synchronous crypto APIs and `Buffer`-specific formats;
+- long-running/background work that exceeds `waitUntil`;
+- response buffering that would destroy RSC streaming.
+
+Prefer web standards (`fetch`, `Request`, `Response`, WebCrypto) and provider
+bindings. Test the production bundle in `vite preview`; a successful TypeScript
+check does not prove an SDK runs in workerd.
+
+## Plan cutover and rollback
+
+Define:
+
+1. schema migration order and backfill scripts;
+2. dual-read/write period, if any;
+3. consistency checks and record counts;
+4. auth/session migration or forced reauthentication;
+5. DNS/traffic cutover;
+6. rollback source of truth and the point after which rollback is unsafe.
+
+Run behavior parity in both the old and new applications for protected reads,
+mutations, OAuth/provider callbacks, billing/webhooks, and failure paths. A page
+rendering successfully is not evidence that the backend contract survived.

package/skills/migrate-react-router/SKILL.md

@@ -97,12 +97,12 @@ nothing, and the packages are out of `package.json`.
 
 Each numbered step's full walkthrough lives in a companion file linked below.
 
-| Step                                                                                                                                           | File                                                   |
-| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| §1 Project Setup, §2 Route Mapping                                                                                                             | [`./route-mapping.md`](./route-mapping.md)             |
-| §3 Data Fetching (loaders, actions, `useLoaderData`/`useActionData`, `clientLoader`/`clientAction`, `shouldRevalidate`)                        | [`./data-and-actions.md`](./data-and-actions.md)       |
-| §4 Middleware / Route Protection, §5 Loading & Error States, §6 Navigation, §7 Metadata / Head, §8 API / Resource Routes, §9 Theme / Dark Mode | [`./component-migration.md`](./component-migration.md) |
-| §10 Cloudflare Workers (streaming, dev tooling, deploy)                                                                                        | [`./cloudflare-workers.md`](./cloudflare-workers.md)   |
+| Step                                                                                                                                           | File                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| §1 Project Setup, §2 Route Mapping                                                                                                             | [`./route-mapping.md`](./route-mapping.md)                                                             |
+| §3 Data Fetching (loaders, actions, `useLoaderData`/`useActionData`, `clientLoader`/`clientAction`, `shouldRevalidate`)                        | [`./data-and-actions.md`](./data-and-actions.md)                                                       |
+| §4 Middleware / Route Protection, §5 Loading & Error States, §6 Navigation, §7 Metadata / Head, §8 API / Resource Routes, §9 Theme / Dark Mode | [`./component-migration.md`](./component-migration.md)                                                 |
+| §10 Cloudflare Workers (streaming, dev tooling, deploy)                                                                                        | [`../cloudflare/references/streaming-and-deploy.md`](../cloudflare/references/streaming-and-deploy.md) |
 
 ## 11. Key Conceptual Differences
 

package/skills/mime-routes/SKILL.md

@@ -41,26 +41,33 @@ When an API client requests the same URL (`Accept: application/json`), the JSON
 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)
+4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
 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.
+RSC participates as a candidate alongside response-type variants under two MIME
+types: `text/html` (the document — its canonical representation) and
+`text/x-component` (the RSC flight wire format). 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.
+| Tag                  | MIME type                              |
+| -------------------- | -------------------------------------- |
+| RSC (plain `path()`) | `text/html` **and** `text/x-component` |
+| `json`               | `application/json`                     |
+| `text`               | `text/plain`                           |
+| `xml`                | `application/xml`                      |
+| `html`               | `text/html`                            |
+| `md`                 | `text/markdown`                        |
+
+Which representation an RSC win renders is decided by the same Accept header:
+the flight wire format is **explicit opt-in only** (`Accept: text/x-component`,
+or the internal `_rsc_*`/`__rsc` transport params the client runtime sends).
+Everything else — browsers, `curl` (`*/*`), a missing Accept header, mismatched
+types like `application/json` on a URL with no JSON variant — gets the HTML
+document. A generic HTTP client never sees the wire format by accident, and an
+explicit `Accept: text/x-component` selects the RSC flight stream even on a
+route where a response variant is defined first.
 
 Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
 
@@ -77,11 +84,12 @@ export const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-- `Accept: text/html` — RSC page
+- `Accept: text/html` — RSC page (HTML document)
 - `Accept: application/json` — JSON handler
 - `Accept: text/plain` — text handler
 - `Accept: application/xml` — XML handler
-- `Accept: */*` — RSC page (the primary, since it was registered first)
+- `Accept: */*` — RSC page as HTML (the primary, since it was registered first)
+- `Accept: text/x-component` — RSC page as the flight wire format
 
 ## Wildcard Routes