@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

package/skills/response-routes/SKILL.md

@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,28 +241,78 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
-### PathResponse (global lookup by URL pattern)
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
 
-Look up response type from the merged route map by URL pattern:
+### Rango.PathResponse (global lookup by URL pattern or concrete path)
+
+`Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
+which carries response payload metadata. That surface is **not** auto-wired —
+without the augmentation below, `Rango.PathResponse` falls back to the generated
+path/search map, or to a permissive map when nothing is generated. Either way, it
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
-import type { PathResponse } from "@rangojs/router/client";
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+With that in place, look up the response type by URL pattern (ambient, no import):
+
+```typescript
 // After include("/api", apiPatterns) in main urls
-type Health = PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+type Health = Rango.PathResponse<"/api/health">;
+// = { status: string; timestamp: number }
+
+// RSC routes (no JSON payload) return never
+type Home = Rango.PathResponse<"/">;
+// = never
+```
 
-// RSC routes return ResponseEnvelope<never>
-type Home = PathResponse<"/">;
-// = ResponseEnvelope<never>
+`Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
+wrapper whose response is inferred from the path you pass:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
+return: `path.json()` serializes with `JSON.stringify`, so a handler returning
+`{ createdAt: Date }` resolves to the bare `{ createdAt: string }`. This
+runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
+`RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
+both response lookups report the identical wire shape.
+
+For local/scoped response typing without global augmentation, prefer
+`RouteResponse<typeof patterns, "routeName">` (see the section above) — it reads
+the response payload straight from the `urls()` patterns and needs no
+`RegisteredRoutes` wiring.
+
 ### ParamsFor with Response Routes
 
 ```typescript
@@ -361,15 +422,17 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { PathResponse, ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router/client";
 
-// Scoped (before mount) -- use the module directly
+// Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
-// After mounting -- names get prefixed
-type BlogStats = PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// After mounting -- names get prefixed.
+// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// otherwise it resolves to never.
+type BlogStats = Rango.PathResponse<"/blog/api/stats">;
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -413,7 +476,11 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/route/SKILL.md

@@ -33,6 +33,26 @@ urls(({ path }) => [
 ]);
 ```
 
+### Optional URL params at runtime
+
+Absent optional params are **omitted from `ctx.params`** — `ctx.params.<name>`
+reads as `undefined`, matching the `RouteParams<"name">` type
+(`{ query?: string }`). Use `??` to default and `=== undefined` to check
+absence:
+
+```typescript
+path("/search/:query?", (ctx) => {
+  const query = ctx.params.query ?? ""; // works — undefined coalesces
+  if (ctx.params.query === undefined) return <EmptySearch />;
+  return <Results query={ctx.params.query} />;
+}, { name: "search" });
+```
+
+For the common pattern of an optional locale prefix
+(`include("/:locale?", routes)`) and the wider react-intl integration —
+locale detection, fallback chains, URL generation with absent locale —
+see `/i18n`.
+
 ## Route Handler Patterns
 
 ### Component Function
@@ -214,14 +234,24 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 
 ### Revalidation Contracts for Handler Data
 
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether this segment re-runs and streams to the client on a
+> navigation or action — never whether a cached value is stale. The cache
+> decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
+> `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
 Handler-first guarantees apply within a single full render pass. For partial
 action revalidation, define named revalidation contracts and reuse them on both
 the producer route and the consumer child segments.
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCheckoutData = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") ?? false;
+import * as CheckoutActions from "./actions/checkout";
+
+// Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
+// so when the same segment composes multiple contracts the later ones never run.
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -250,9 +280,6 @@ path("/checkout", CheckoutPage, { name: "checkout" }, () => [
 ]);
 ```
 
-For scope/revalidation guarantees and non-guarantees, see:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Redirects
 
 ### Basic redirect
@@ -269,6 +296,12 @@ path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
 path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 ```
 
+> **Redirecting from a route with `loading()`:** an `async` handler that returns
+> a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
+> so the redirect is rendered into the RSC stream instead of becoming an HTTP
+> redirect. Issue the redirect from `middleware`, a loader, or a **synchronous**
+> handler return instead. (Dev logs a warning if this is hit.)
+
 ### Redirect with location state
 
 Carry typed state through redirects (e.g. flash messages):
@@ -383,6 +416,10 @@ urls(({ path, layout }) => [
 ])
 ```
 
+## View Transitions
+
+A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.
+
 ## Handler-attached `.use`
 
 Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.

package/skills/router-setup/SKILL.md

@@ -71,7 +71,7 @@ urls(
 ## Router Options
 
 ```typescript
-interface RSCRouterOptions<TEnv> {
+interface RangoOptions<TEnv> {
   // URL patterns from urls() function
   urls: UrlPatterns;
 
@@ -405,7 +405,7 @@ interface AppBindings {
   KV: KVNamespace;
 }
 
-// Variables declared via module augmentation
+// Variables declared via global namespace augmentation
 interface AppVariables {
   user?: { id: string; name: string };
 }
@@ -417,7 +417,7 @@ const router = createRouter<AppBindings>({
 
 // Register types globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }

package/skills/server-actions/SKILL.md

@@ -32,35 +32,37 @@ Actions mutate state; route handlers and loaders read the latest state. After
 an action finishes, Rango performs a server-side revalidation render for the
 matched route so the UI receives fresh segment output and loader data.
 
-The main control point is `revalidate(({ actionId }) => ...)` on the segment
-that owns the data. This applies to `path()` handlers, `layout()` handlers,
-`parallel()` slots, `intercept()` routes, and loader registrations:
+The main control point is `revalidate((ctx) => ...)` on the segment that owns
+the data. Match specific actions by imported reference with `ctx.isAction()`;
+use raw `actionId` only when you intentionally need path or directory matching.
+This applies to `path()` handlers, `layout()` handlers, `parallel()` slots,
+`intercept()` routes, and loader registrations:
 
 ```typescript
 // urls.tsx — path/layout/parallel/intercept/loader/revalidate are passed in by urls()
 import { urls } from "@rangojs/router";
+import * as CartActions from "./actions/cart";
 
 export const urlpatterns = urls(({ path, loader, revalidate }) => [
   // The loader belongs to the route that consumes its data — nest it inside
   // the owning path() so the segment owns its data dependency.
   path("/cart", CartPage, { name: "cart" }, () => [
-    revalidate(
-      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-    ),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     loader(CartLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
   ]),
 ]);
 ```
 
-For module-level `"use server"` files, the `actionId` passed to every
+`ctx.isAction()` resolves the imported action reference the same way the router
+derives `actionId`, so it matches in both dev and production and survives action
+renames/moves as type errors instead of silent substring drift.
+
+For module-level `"use server"` files, the raw `actionId` passed to every
 server-side `revalidate()` predicate is path-bearing in the server/RSC
-environment in both dev and production: `src/actions/cart.ts#addToCart`. This
-is intentional so path, layout, parallel, intercept, and loader revalidation
-predicates can filter by action file, directory, or export name.
+environment in both dev and production: `src/actions/cart.ts#addToCart`. This is
+the escape hatch for broad filters by action file, directory, or export name.
 
 Actions and the follow-up revalidation render share one request context.
 Values written in the action with `ctx.set(MyVar, value)` or `ctx.set("key",
@@ -91,15 +93,18 @@ export async function switchTenant(tenantId: string) {
 ```typescript
 // urls.tsx
 import { urls } from "@rangojs/router";
+import * as TenantActions from "./actions/tenant";
 import { ChangedTenant } from "./context";
 
 export const urlpatterns = urls(({ path, revalidate }) => [
   path("/dashboard/:tenantId", DashboardPage, { name: "dashboard" }, () => [
-    revalidate(
-      ({ actionId, context }) =>
-        actionId?.startsWith("src/actions/tenant.ts#") &&
-        context.get(ChangedTenant) === context.params.tenantId,
-    ),
+    revalidate((ctx) => {
+      if (!ctx.isAction(TenantActions)) return undefined;
+      return (
+        ctx.context.get(ChangedTenant) === ctx.context.params.tenantId ||
+        undefined
+      );
+    }),
   ]),
 ]);
 ```
@@ -380,13 +385,18 @@ re-render so the UI updates. Rango runs the action, then evaluates
 `revalidate()` on matched segments and loaders. Each path, layout, parallel,
 intercept, or loader rule decides whether that piece re-renders/re-resolves.
 
-The `actionId` arrives as part of the revalidation context — match it to
-scope re-runs to specific actions.
+Use `ctx.isAction()` for specific actions or modules. It accepts one action,
+several actions, or a namespace import (`import * as CartActions`). Pair it with
+`|| undefined` for "revalidate on match, otherwise defer to defaults/downstream
+rules."
 
 ```typescript
 // urls.tsx — inside the urls() callback. Nest each loader inside the path(),
 // layout(), or parallel() that owns its data so the route tree mirrors the
 // data dependencies.
+import * as AccountActions from "./actions/account";
+import * as CartActions from "./actions/cart";
+
 urls(({ path, loader, revalidate }) => [
   path("/", HomePage, { name: "home" }, () => [
     // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
@@ -395,36 +405,37 @@ urls(({ path, loader, revalidate }) => [
 
   // Re-render the cart page handler AND re-resolve its loader after cart actions
   path("/cart", CartPage, { name: "cart" }, () => [
-    revalidate(
-      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-    ),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     loader(CartLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
   ]),
 
-  // Re-run after any action under src/actions/account/
+  // Re-run after any action exported by the account actions module
   path("/account", AccountPage, { name: "account" }, () => [
     loader(AccountLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/account/") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(AccountActions) || undefined),
     ]),
   ]),
 ]);
 ```
 
-`actionId` is stable per action. For actions exported from a module-level
-`"use server"` file, the ID is prefixed with the source file path
-(`src/actions/cart.ts#addToCart`), so substring matching by file path is the
-recommended scope. **Inline `"use server"` actions** (declared inside an RSC
-component) intentionally keep their hashed IDs — file paths are withheld
-from the client for security. If you need file-path-based revalidation
-predicates, define the action in a module-level `"use server"` file rather
-than inline. See `/loader` for the full revalidation contract (deferred
-returns, soft suggestions).
+The raw `actionId` string stays available for broad path filters:
+
+```typescript
+// Match any action under src/actions/account/, including modules not imported here.
+revalidate(
+  ({ actionId }) => actionId?.startsWith("src/actions/account/") || undefined,
+);
+```
+
+For actions exported from a module-level `"use server"` file, the ID is prefixed
+with the source file path (`src/actions/cart.ts#addToCart`). **Inline `"use
+server"` actions** (declared inside an RSC component) intentionally keep their
+hashed IDs — file paths are withheld from the client for security. If you need
+file-path-based revalidation predicates, define the action in a module-level
+`"use server"` file rather than inline. See `/loader` for the full revalidation
+contract (deferred returns, soft suggestions).
 
 ### Cross-segment dependencies
 
@@ -434,8 +445,9 @@ stale context. Share the same `revalidate` predicate on both producer and
 consumer:
 
 ```typescript
-const revalidateCart = ({ actionId }) =>
-  actionId?.startsWith("src/actions/cart.ts#") ?? false;
+import * as CartActions from "./actions/cart";
+
+const revalidateCart = (ctx) => ctx.isAction(CartActions) || undefined;
 
 urls(({ path, layout, loader, revalidate }) => [
   layout(CartLayout, () => [
@@ -453,7 +465,10 @@ See `/middleware` for the full cross-segment revalidation contract.
 
 `redirect()` works inside actions. Both `return redirect(...)` and
 `throw redirect(...)` are supported and behave the same way for the
-client. Throwing is clearer when the redirect is conditional.
+client. Throwing is clearer when the redirect is conditional, and it keeps
+the action's return type narrow (e.g. `Promise<void>`) — `redirect()` returns
+a `Response`, so the `return` form needs `Promise<Response>` in the signature.
+Prefer `throw redirect(...)`; never cast with `as any`.
 
 ```typescript
 "use server";
@@ -478,6 +493,27 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+### Same-origin by default (open-redirect protection)
+
+`redirect()` is same-origin by default on every path — JS, no-JS PE, and
+full-page. A cross-origin target (e.g. from unvalidated user input) is blocked
+and the user is sent to the app root instead, so `redirect(userInput)` can never
+become an open redirect. To intentionally redirect off-host (an OAuth provider,
+say), opt in explicitly:
+
+```typescript
+throw redirect("https://accounts.google.com/o/oauth2/v2/auth?...", {
+  external: true,
+});
+```
+
+`{ external: true }` is the audit point: passing user input with it re-opens the
+cross-origin risk and is your responsibility (the Rails `allow_other_host: true`
+model). Omit it and off-host targets stay blocked. `external` only waives the
+**same-origin** rule, not scheme safety: the target must be `http(s)` — a
+`javascript:` or `data:` URL is still neutralized, so a forged or mistaken
+`external` target can never become a scriptable navigation.
+
 ## Error Handling
 
 ### Validation errors — return them as state

package/skills/tailwind/SKILL.md

@@ -37,7 +37,11 @@ export default defineConfig({
 
 ## Document Component
 
-Import the CSS file with `?url` to get a hashed URL, then preload and link it in `<head>`:
+Import the CSS file with `?url` to get a hashed URL, then preload and link it in
+`<head>`. Give the `<link rel="stylesheet">` a `precedence` prop so React 19
+manages it as a resource — de-duped by `href`, ordered, and loaded before paint
+(no flash of unstyled content). See
+[Stylesheets and cross-app navigation](#stylesheets-and-cross-app-navigation):
 
 ```tsx
 // src/document.tsx
@@ -51,8 +55,8 @@ export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
-        <link rel="preload" href={styles} as="style" />
-        <link rel="stylesheet" href={styles} />
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
         <MetaTags />
       </head>
       <body className="font-sans antialiased text-slate-900 bg-slate-50">
@@ -63,6 +67,26 @@ export function Document({ children }: { children: ReactNode }) {
 }
 ```
 
+## Stylesheets and cross-app navigation
+
+The `precedence` prop opts a `<link rel="stylesheet">` into React 19's managed
+stylesheet model — React de-duplicates it by `href`, orders it by precedence, and
+loads it before paint (avoiding a flash of unstyled content). It is the
+recommended way to render a stylesheet link, which is why the example above uses
+it. (A bare side-effect `import "./index.css"` also produces managed CSS via
+`@vitejs/plugin-rsc`, but carries an SSR-streaming caveat — prefer the `?url` +
+`<link precedence>` form for document CSS. See `/css`.)
+
+For **host-router** apps (`/host-router`), a client-side navigation that crosses
+an app boundary is a **full document load**, not a soft swap — the framework
+redirects on an app switch. So each app's document (its stylesheets, theme, meta)
+is always re-established cleanly by the target app's own load; you do not have to
+coordinate stylesheet `href`s or `precedence` across apps. (This replaced an
+earlier soft cross-app swap, under which a stylesheet shared across apps — every
+app's `@import "tailwindcss"` compiles to one hashed asset — could be dropped by
+React's by-`href` resource dedup if the apps disagreed on `precedence`. The full
+reload removes that footgun entirely.)
+
 The `?url` suffix tells Vite to return the processed CSS file's URL instead of injecting it as a side effect. This gives you a stable, hashed asset path that works in both development and production.
 
 ## Customizing the Theme