@rangojs/router 0.16.0 → 0.18.0

package/skills/testing/server-actions.md

@@ -22,6 +22,7 @@
 | `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                             |
 | `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                         |
 | `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                            |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                        |
 | `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (value is `{version}:{timestamp}`, default `"0"`). |
 
 ### Context — `RequestContext<TEnv>` (what your code receives)
@@ -52,7 +53,12 @@
 | `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing.                               |
 | `locationState`   | `Record<string, unknown>` | The flash set via `ctx.setLocationState()` / `redirect({ state })`, as the flat `{ key: value }` the client reads.                                                                                |
 
-Low-level variant: when you already hold a context from `createTestRequestContext(opts)`, call `runWithRequestContext(ctx, fn)` (re-exported from `@rangojs/router/testing`) to enter it directly. `runInRequestContext` is the one-call convenience over `createTestRequestContext` + `runWithRequestContext`.
+Low-level building blocks (all from `@rangojs/router/testing`):
+
+- `createTestRequestContext(opts)` builds the context WITHOUT entering it and returns `{ ctx, request, url, variables, stateCookieName }`. Its `ctx.reverse` accepts any name from your `routeMap`.
+- `runWithRequestContext(ctx, fn)` enters a context you already hold. `runInRequestContext` is the one-call convenience over these two, plus the result snapshot.
+- `toRequest(request?, init?)` normalizes a `Request | string | undefined` into a `Request` (strings resolve against `http://localhost/`).
+- `seedVariables(variables, vars?)` writes a `VarsInit` (object or `[key, value]` tuples) into a raw variables record, the same way the `vars` option does.
 
 ## Recipe
 
@@ -60,10 +66,13 @@ Low-level variant: when you already hold a context from `createTestRequestContex
 import { it, expect } from "vitest";
 import { runInRequestContext } from "@rangojs/router/testing";
 import { loginAction } from "../src/actions/login"; // sets a session cookie + flash, then throw redirect("/app")
+import { logoutAction, dismissBannerAction } from "../src/actions/session"; // invalidateClientCache() / keepClientCache()
+
+const env = { DB: fakeDb }; // your binding double (see ./bindings.md)
 
 it("sets the session cookie + flash and redirects", async () => {
   const { thrown, cookies, locationState } = await runInRequestContext(
-    () => loginAction(input),
+    () => loginAction({ email: "ada@example.com", password: "pw" }),
     {
       env,
       request: new Request("https://app.test/admin", {
@@ -97,7 +106,7 @@ it("asserts the client-cache directives an action issued", async () => {
 
 - The snapshot fires whether `fn` RETURNS or THROWS. A `throw redirect("/app")` on the success path is captured on `thrown` (NOT re-thrown), so no try/catch is needed; assert on `thrown` for a throwing action.
 - There is no cookies / headers option. Seed a request cookie by passing a full `Request` with the `Cookie` header (as in the recipe).
-- `runWithRequestContext(ctx, fn)` is the low-level entry when you already hold a context; `runInRequestContext` is the one-call convenience over `createTestRequestContext` + `runWithRequestContext`.
+- An action has no loader context, so `runLoader` is the wrong shape for it even when the action reads cookies or vars; use `runInRequestContext`.
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/server-tree.md

@@ -18,6 +18,8 @@
 | `vars`             | `VarsInit`                | Context variables visible via `ctx.get(...)`, as a prior middleware would have set them. Object form (`{ user }`) or `[key, value]` tuples.                                                                                                                                                                                            |
 | `clientComponents` | `Record<string, unknown>` | The `"use client"` components reachable from the tree, keyed by the boundary name to register each as a client reference (in place) so it serializes as an `I` row. Omit when `rangoUseClientTransform()` auto-discovers them, or for pure server-only trees. First-wins per worker; already-registered references are left untouched. |
 
+It also accepts the rest of `RenderToFlightStringOptions` — `routeMap`, `theme`, `cacheStore`, `cacheProfiles` — with the same meaning as in [`./flight.md`](./flight.md).
+
 ### Context — what your code receives
 
 A server component rendered here runs under a real request context: `getRequestContext()` resolves, `ctx.params`/`ctx.routeName`/`ctx.env` reflect the options, `ctx.get(MyVar)` reads a seeded `var`, and cookies come off the request. Same seeding as the handler-test primitives — you render an **element** you build (`<Page />`); to run a route **handler** `(ctx) => rsc` use `renderHandler` (see `./render-handler.md`).
@@ -64,6 +66,10 @@ Every SERVER/HOST element a server component produced (`<article>`, `<h2>`), in
 
 Concatenates every string/number leaf of a node's subtree in document order — the clean way to assert rendered text, instead of `JSON.stringify(tree).toContain(...)`.
 
+#### `assertFlightTreeRuntimeAvailable()`
+
+Throws a descriptive error when a `@vitejs/plugin-rsc` subpath the round trip relies on (the vendored client deserializer or `registerClientReference`) no longer exports the expected function — the counterpart of `assertFlightRuntimeAvailable()` in `./flight.md`. Call it in a `beforeAll` to fail fast after a plugin-rsc upgrade.
+
 ## Recipe
 
 ```tsx
@@ -74,8 +80,11 @@ import {
   findElements,
   textContent,
 } from "@rangojs/router/testing/flight";
+import { flightMatchers } from "@rangojs/router/testing/flight-matchers";
 import { PriceTag } from "./PriceTag.js"; // a "use client" component (any filename)
 
+expect.extend(flightMatchers); // for toMatchFlight below
+
 async function ProductPanel({ amount, asOf }: { amount: number; asOf: Date }) {
   await Promise.resolve();
   return (

package/skills/testing/setup.md

@@ -12,13 +12,15 @@ Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolv
 | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `preset` | `"node" \| "cloudflare"` | Deployment preset, matching `rango({ preset })` in the Vite plugin. `"cloudflare"` additionally stubs the `cloudflare:workers` / `cloudflare:email` runtime virtuals a CF route tree imports. A string (not a boolean) so more presets can be added without an API change. Default `"node"`. |
 
-### Functions
+### Exports
 
-| Function                    | Returns                                   | Use                                                                                                                                                                                                                                        |
+| Export                      | Returns / value                           | Use                                                                                                                                                                                                                                        |
 | --------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                                                        |
 | `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
-| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                                                 |
+| `rangoInlineDeps`           | `RegExp[]` (`[/@rangojs[/\\]router/]`)    | The `server.deps.inline` patterns on their own. Use in the rsc project (`test.server.deps.inline`), or wherever you call `rangoTestAliases` directly instead of `rangoTestConfig`.                                                         |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` / `renderHandler` auto-discover client islands from the server tree's imports.                                                                |
+| `rangoUseCacheTransform()`  | a Vite plugin (`enforce: "post"`)         | Add to the rsc project `plugins`. Runs the rango plugin's `"use cache"` transform with dev ids (`<path>#<name>`, the path relative to the root its `configResolved` reads) so a directive function caches.                                 |
 
 ### Returns — `RangoTestConfig` (from `rangoTestConfig`)
 
@@ -53,6 +55,7 @@ import { defineConfig } from "vitest/config";
 import {
   rangoTestAliases,
   rangoUseClientTransform,
+  rangoUseCacheTransform,
   rangoInlineDeps,
 } from "@rangojs/router/testing/vitest";
 
@@ -60,7 +63,7 @@ import {
 process.env.NODE_ENV = "production";
 
 export default defineConfig({
-  plugins: [rangoUseClientTransform()],
+  plugins: [rangoUseClientTransform(), rangoUseCacheTransform()],
   resolve: {
     conditions: ["react-server"],
     alias: rangoTestAliases({ preset: "cloudflare" }), // or { preset: "node" }
@@ -109,12 +112,13 @@ Scripts:
 
 - Node >= 23 requires `rangoTestConfig()`, not bare `rangoTestAliases()`. `@rangojs/router` is consumed as SOURCE (exports -> `./src/*.ts`), and Node >= 23 refuses to type-strip `.ts` under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). `rangoTestConfig` ships as compiled JS AND adds `server.deps.inline: [/@rangojs[/\\]router/]` so Vite (not Node) transpiles rango source. With bare `rangoTestAliases` you must wire `deps.inline` yourself.
 - Two separate projects. The node/DOM project keeps React on its CLIENT build; the Flight project uses the `react-server` condition in a separate `vitest.rsc.config.ts`. The main project must NOT set `react-server` — it flips React to the no-hooks server build and breaks every `renderRoute` / client test.
-- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`). `renderToFlightString` / `renderServerTree` now self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
+- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub. `renderToFlightString`, `renderServerTree`, and `renderHandler` all detect this exact misconfiguration and reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
 - `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
 - The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
 - The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
 - Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`. The transform's `registerClientReference` import is resolved from `@rangojs/router`'s `@vitejs/plugin-rsc` — the consumer does not need a direct plugin-rsc dependency.
+- Wire `rangoUseCacheTransform()` into the rsc project `plugins` so a function written with `"use cache"` is wrapped as in dev. `rango()` runs that transform only in its `rsc` environment and Vitest transforms in `ssr`, so without it the directive is inert and the function runs on every call. See [`./render-handler.md`](./render-handler.md#a-use-cache-hit).
 
 ## See also
 

package/skills/theme/SKILL.md

@@ -1,82 +1,207 @@
 ---
 name: theme
-description: Opt-in theme system with FOUC prevention for light/dark mode. Use when adding a light/dark mode toggle, or the page flashes the wrong theme on load (FOUC).
+description: Opt-in light/dark theme system with FOUC prevention, server-side theme access, and a useTheme() hook. Use when adding a light/dark mode toggle, reading or setting the theme in handlers or middleware, or when the page flashes the wrong theme on load (FOUC).
 argument-hint: [setup]
 ---
 
 # Theme Support
 
-Opt-in theme system with FOUC prevention.
+Opt-in theme system. Enabling it gives you:
+
+- an inline script (rendered by `<Html.Meta />`) that applies the stored theme
+  to `<html>` before first paint, so there is no flash of the wrong theme;
+- `ctx.theme` / `ctx.setTheme()` in handlers and middleware;
+- the `useTheme()` hook in client components (the provider is added for you).
+
+The theme is stored in a cookie (so the server can read it) and in
+localStorage.
 
 ## Enable
 
 ```typescript
 import { createRouter } from "@rangojs/router";
 
-// Simple - all defaults
-const router = createRouter<Env>({
+// All defaults
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
   theme: true,
 });
 
-// Custom config
-const router = createRouter<Env>({
+// Custom config (values shown are the defaults unless noted)
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
   theme: {
     defaultTheme: "system", // "light" | "dark" | "system"
     themes: ["light", "dark"],
-    attribute: "class", // or "data-theme"
-    storageKey: "theme",
+    attribute: "class", // or any "data-*" attribute, e.g. "data-theme"
+    storageKey: "theme", // cookie and localStorage key
+    enableSystem: true, // resolve "system" via prefers-color-scheme
+    enableColorScheme: true, // set style="color-scheme: ..." on <html>
+    value: { dark: "theme-dark" }, // optional: attribute value per theme (not a default)
   },
 });
 ```
 
-## Server (in handlers/middleware)
+With `attribute: "class"` the resolved theme is added as a class on `<html>`
+(`<html class="dark">`); with a `data-*` attribute it is set as that
+attribute's value (`<html data-theme="dark">`). `"system"` resolves to
+`"light"` or `"dark"` before it is applied. With `enableSystem: false`,
+`"system"` is not a valid theme and a `"system"` default falls back to the
+first entry in `themes`.
+
+## Document requirements
+
+- Render `<Html.Meta />` in `<head>`: it emits the FOUC-prevention script
+  first, before the meta tags. The default Document already does this.
+- Add `suppressHydrationWarning` to `<html>`: the script changes its
+  `class`/`style` before React hydrates.
+
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import { Html } from "@rangojs/router/client";
+
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <Html.Meta />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+A Document that does not render `<Html.Meta />` can place `<ThemeScript />`
+from `@rangojs/router/theme` in `<head>` instead. It takes the resolved config
+(`config: ResolvedThemeConfig`) and an optional `nonce`.
+
+## Server (handlers and middleware)
+
+`ctx.theme` is the stored theme, or `defaultTheme` when there is none.
+`ctx.setTheme(theme)` sets the theme cookie on the response; invalid values
+are rejected with a console warning. Both are typed optional because they only
+exist when `theme` is configured.
+
+`ctx.theme` is the visitor's theme cookie, so a handler reads it only on a
+route whose output is rendered per request:
 
 ```typescript
 import type { Middleware } from "@rangojs/router";
 
-// In a handler
+// In a handler on a route without ppr or cache()
 path("/settings", (ctx) => {
-  const currentTheme = ctx.theme; // read from cookie
+  const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
   return <SettingsPage theme={currentTheme} />;
 });
 
-// In middleware
-export const themeMiddleware: Middleware = async (ctx, next) => {
-  // Set theme based on user preference
-  ctx.setTheme("dark");
+// In middleware: apply a theme chosen through a query param
+export const themeFromQuery: Middleware = async (ctx, next) => {
+  const requested = ctx.url.searchParams.get("theme");
+  if (requested === "light" || requested === "dark") {
+    ctx.setTheme?.(requested);
+  }
   await next();
 };
 ```
 
-Theme accessors are handler/middleware-only — the loader context has no
-`ctx.theme`/`ctx.setTheme`. A loader that needs the theme reads the cookie
-directly via `cookies()` (loaders always run fresh, so the read is safe).
+### On `ppr` and `cache()` routes
+
+A `ppr` shell and a `cache()` entry are shared by every visitor, so a handler
+there must not read the visitor's theme. `ctx.theme` (handler and middleware)
+and `getRequestContext().theme` are guarded like `cookies()`:
+
+| Where the theme is read                                    | What happens                                                                                          |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| a handler on a `ppr` route                                 | The shell capture is refused (warned once per URL); every request stays a MISS                        |
+| inside a `cache()` boundary                                | Throws on a cache miss, like `cookies()`                                                              |
+| inside a `"use cache"` function (handler or middleware)    | Throws; read it outside and pass it in as an argument                                                 |
+| after `ctx.dynamic()` on `ppr`                             | Allowed: that render is never captured                                                                |
+| middleware `ctx.set()` of the theme, read by a handler     | Not guarded: the first visitor's theme bakes into the shell or `cache()` entry, like a session object |
+| a route with no `ppr` or `cache()` above it, or middleware | Allowed: rendered per request                                                                         |
+| a loader with its own `cache()` and no `key()`             | The miss fails and stores nothing (#972), like a `cookies()` read there; key the theme                |
+
+The theme getters are read-only and non-enumerable: `{ ...ctx }` and
+`Object.assign({}, ctx)` do not carry `theme`, and assigning it throws.
+
+`ctx.setTheme()` throws in a handler on these routes too, like any response
+write there; call it from middleware.
+
+Read the theme where it is per request instead:
+
+- `useTheme()` in a client component. The `<html>` class is right before
+  paint (the theme script sets it). On a `ppr` HIT the shell carries the
+  no-cookie default (`defaultTheme`), whoever captured it: a visitor with no
+  stored theme sees the default, and one with a stored theme sees it after
+  hydration.
+- A live loader (no `ssr: false`). Loaders do not get `ctx.theme` or
+  `ctx.setTheme`; read the cookie directly. A live loader runs on every
+  request, HITs included, and on a `ppr` route needs `loading()` or an inline
+  `<Suspense>` above its reader. A bake-lane loader (`ssr: false`) runs at
+  capture, where this `cookies()` read refuses the capture, and so does a
+  loader a handler awaits with `ctx.use()`.
+
+```typescript
+import { cookies, createLoader } from "@rangojs/router";
+
+export const ThemedLoader = createLoader(async () => {
+  const theme = cookies().get("theme")?.value ?? "system"; // storageKey
+  return loadThemedAssets(theme);
+});
+```
+
+If you bind it with its own `cache()`, the entry is shared across users, so the
+miss fails unless it has a `key()`. Any `key()` switches that check off, so
+make it include the theme:
+
+```typescript
+loader(ThemedLoader, () => [
+  cache({
+    ttl: 300,
+    key: () => `themed:${cookies().get("theme")?.value ?? "system"}`,
+  }),
+]);
+```
 
 ## Client
 
 ```tsx
 "use client";
-import { useTheme } from "@rangojs/router/theme";
+import { useTheme, type Theme } from "@rangojs/router/theme";
 
-function ThemeToggle() {
-  const { theme, setTheme, resolvedTheme, systemTheme, themes } = useTheme();
+export function ThemeToggle() {
+  const { theme, setTheme, resolvedTheme, themes } = useTheme();
 
   return (
-    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
-      <option value="system">System</option>
-      <option value="light">Light</option>
-      <option value="dark">Dark</option>
-    </select>
+    <label>
+      Theme ({resolvedTheme})
+      <select value={theme} onChange={(e) => setTheme(e.target.value as Theme)}>
+        {themes.map((t) => (
+          <option key={t} value={t}>
+            {t}
+          </option>
+        ))}
+      </select>
+    </label>
   );
 }
 ```
 
-## Notes
+`useTheme()` returns:
+
+- `theme`: the stored setting (`"light" | "dark" | "system"`)
+- `setTheme(theme)`: update the theme; writes the cookie and localStorage
+- `resolvedTheme`: what is actually shown (`"system"` resolved)
+- `systemTheme`: the current OS preference (`"light" | "dark"`)
+- `themes`: the configured themes, with `"system"` first when `enableSystem` is on
+
+`useTheme()` throws when `theme` is not enabled in `createRouter()`.
+
+## Related
 
-- `<MetaTags />` auto-renders inline script for FOUC prevention
-- Add `suppressHydrationWarning` to `<html>`
-- Theme persists in localStorage + cookie (for SSR)
+- `/tailwind`: pairing `attribute: "class"` with Tailwind's `dark:` variant
+- `/css`: where document stylesheets go
+- `/router-setup`: the Document component

package/skills/typesafety/SKILL.md

@@ -1,17 +1,27 @@
 ---
 name: typesafety
-description: Set up type-safe routes, params, and environment types in @rangojs/router. Use when route or search params aren't typed, TypeScript can't infer a loader's return type, or wiring up typed environment bindings.
+description: Set up type-safe route names, params, search params, response payloads, and environment types in @rangojs/router. Use when route or search params aren't typed, ctx.env or ctx.get() is untyped, TypeScript can't infer a loader's return type, or wiring RegisteredRoutes / the generated route map.
 argument-hint: [setup]
 ---
 
 # Type Safety Setup
 
-@rangojs/router provides end-to-end type safety for routes, parameters, and
-environment. Without it: `ctx.reverse()`/`href()` accept any string (typos
-404 at runtime, not compile time), `ctx.search`/`ctx.params` fall back to
-loose `Record<string, string>`, and `ctx.env`/`ctx.get()` are untyped so a
-missing binding surfaces as `undefined` in production instead of a build
-error.
+This skill covers how route names, params, search params, response payloads,
+environment bindings, and context variables get their types. Use it when
+setting up a new app's type surfaces or when one of them resolves to
+`any`/`unknown`/`never` unexpectedly.
+
+What you lose without the setup:
+
+- `ctx.reverse()` accepts any name and `href()` any `/${string}` path, so a
+  typo 404s at runtime instead of failing to compile.
+- `Handler<"name">` is rejected (there is no generated map to look the name
+  up in), so `ctx.params`/`ctx.search` can't be inferred from the route.
+- `ctx.env` is `unknown` until `Rango.Env` is registered (every binding access
+  is a compile error), and string-key `ctx.get("key")` returns `any` until
+  `Rango.Vars` is registered (a typo'd key is silently accepted).
+- `Rango.PathResponse` resolves to `never` until `Rango.RegisteredRoutes` is
+  registered.
 
 Each topic's full setup, code, and caveats live in a companion file linked
 below. Read the one for your case.
@@ -48,5 +58,6 @@ below. Read the one for your case.
   scoped context tokens, handle typing, passing loaders/handles as typed
   props, and location state typing.
 
-See `/links` for the full URL generation guide (per-module `*.gen.ts`,
-`useReverse`).
+Related skills: `/links` (URL generation: `ctx.reverse`, `href`,
+`useReverse`, per-module `*.gen.ts`), `/response-routes` (response payload
+typing), `/api-client` (typed fetch client over `RouteResponse`).