@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/skills/host-router/SKILL.md

@@ -22,9 +22,9 @@ import { createHostRouter } from "@rangojs/router/host";
 
 const router = createHostRouter();
 
-router.host(["."]).map(() => import("./apps/main"));
-router.host(["admin.*"]).map(() => import("./apps/admin"));
-router.host(["api.*"]).map(() => import("./apps/api"));
+router.host(["."]).lazy(() => import("./apps/main"));
+router.host(["admin.*"]).lazy(() => import("./apps/admin"));
+router.host(["api.*"]).lazy(() => import("./apps/api"));
 
 export default {
   fetch(request: Request, env: Env, ctx: ExecutionContext) {
@@ -33,7 +33,31 @@ export default {
 };
 ```
 
-Each `.map()` receives either a direct handler `(request, input) => Response` or a lazy import `() => import(...)`. Lazy imports resolve a module with a `default` export that is either a handler function or another `HostRouter` (for nesting).
+## Inline handlers (`.map`) vs lazy mounts (`.lazy`)
+
+A host pattern maps to one of two things, and you pick the method by intent:
+
+| Method  | Argument                       | Use for                                                      |
+| ------- | ------------------------------ | ------------------------------------------------------------ |
+| `.map`  | `(request, input) => Response` | An inline request handler that produces a response directly. |
+| `.lazy` | `() => import("./sub-app")`    | A lazily-imported handler or nested host router (a sub-app). |
+
+```typescript
+// Lazy mount: the module's default export is a handler or a HostRouter.
+router.host(["admin.*"]).lazy(() => import("./apps/admin"));
+
+// Inline handler: returns a Response itself (sync or async).
+router.host(["health.*"]).map(() => new Response("ok"));
+router
+  .host(["echo.*"])
+  .map((request) => new Response(new URL(request.url).pathname));
+```
+
+Why two methods instead of one overloaded `.map()`:
+
+- **Build-time discovery** invokes only `.lazy()` mounts (to trigger each sub-app's `createRouter()` registration). Inline `.map()` handlers are never invoked during discovery, so they can't crash it or pollute its errors.
+- `.map(() => import("./sub-app"))` is a **type error** — a lazy import resolves to a module, not a `Response`. Use `.lazy()` for imports. (If the types are bypassed, e.g. from JS, a `.map()` handler that resolves to a module throws a clear `HostRouterError` at request time instead of returning the module.)
+- A lazy loader may declare an ignored parameter (`.lazy((_request?) => import("./x"))`); `.lazy()` accepts it because intent is explicit, not inferred from the signature.
 
 ## Pattern Syntax
 
@@ -42,7 +66,7 @@ Each `.map()` receives either a direct handler `(request, input) => Response` or
 | `.` or `*`        | Any apex domain (`example.com`)                |
 | `**`              | Any domain (apex + all subdomains)             |
 | `*.`              | Any single-level subdomain (`www.example.com`) |
-| `**. `            | Any multi-level subdomain (`a.b.example.com`)  |
+| `**.`             | Any multi-level subdomain (`a.b.example.com`)  |
 | `example.com`     | Exact domain                                   |
 | `*.com`           | Any apex `.com` domain                         |
 | `*.example.com`   | Single subdomain of `example.com`              |
@@ -65,8 +89,8 @@ const hosts = defineHosts({
   app: [".", "www.*"],
 });
 
-router.host(hosts.admin).map(() => import("./apps/admin"));
-router.host(hosts.app).map(() => import("./apps/main"));
+router.host(hosts.admin).lazy(() => import("./apps/admin"));
+router.host(hosts.app).lazy(() => import("./apps/main"));
 ```
 
 Returns a frozen object — keys are autocompleted by TypeScript.
@@ -88,7 +112,7 @@ router.use(async (request, input, next) => {
 router
   .host(["admin.*"])
   .use(requireAuth)
-  .map(() => import("./apps/admin"));
+  .lazy(() => import("./apps/admin"));
 ```
 
 Middleware signature: `(request: Request, input: RouterRequestInput, next: () => Promise<Response>) => Promise<Response>`
@@ -165,12 +189,26 @@ Logs pattern matching, route registration, and cookie override decisions to cons
 ## Testing
 
 ```typescript
-import { createTestRequest, testPattern } from "@rangojs/router/host/testing";
+import {
+  createTestRequest,
+  testPattern,
+  matchesHost,
+} from "@rangojs/router/host/testing";
 
-// Test pattern matching
+// Test pattern matching (host-only)
 testPattern("admin.*", "admin.example.com"); // true
 testPattern([".", "www.*"], "example.com"); // true
 
+// Path-based patterns need the third pathname arg (defaults to "/", so a
+// host-only pattern still works with two args):
+testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin"); // true
+
+// Or match a pattern against a real Request (hostname + pathname from the URL):
+matchesHost(
+  "**.workers.dev/admin",
+  new Request("https://foo.workers.dev/admin"),
+); // true
+
 // Create requests for integration tests
 const request = createTestRequest({
   host: "admin.example.com",
@@ -179,40 +217,62 @@ const request = createTestRequest({
 });
 
 // Test which route would match (without executing)
-router.test("admin.example.com"); // { pattern, handler } | null
+router.test("admin.example.com"); // { pattern, handler, kind } | null
 ```
 
 ## Error Types
 
 All errors extend `HostRouterError`:
 
-| Error                         | When                                        |
-| ----------------------------- | ------------------------------------------- |
-| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces |
-| `HostOverrideNotAllowedError` | Cookie override from disallowed host        |
-| `InvalidHostnameError`        | Cookie value isn't a valid hostname         |
-| `HostValidationError`         | Custom `validate` function threw            |
-| `NoRouteMatchError`           | No host pattern matched the request         |
-| `InvalidHandlerError`         | Handler is not a function                   |
+| Error                         | When                                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces                                                       |
+| `HostOverrideNotAllowedError` | Cookie override from disallowed host                                                              |
+| `InvalidHostnameError`        | Cookie value isn't a valid hostname                                                               |
+| `HostValidationError`         | Custom `validate` function threw                                                                  |
+| `NoRouteMatchError`           | No host pattern matched the request                                                               |
+| `InvalidHandlerError`         | Handler is not a function, or a lazy mount resolved to a module without a usable `default` export |
+| `HostRouterError`             | A `.map()` inline handler resolved to a module namespace (a misused lazy import — use `.lazy()`)  |
 
 See the fallback section above for a `NoRouteMatchError` catch example.
 
 ## Nesting Host Routers
 
-A lazy handler can resolve to another `HostRouter`:
+A lazy mount can resolve to another `HostRouter`:
 
 ```typescript
 // apps/regional.ts
 import { createHostRouter } from "@rangojs/router/host";
 
 const regional = createHostRouter();
-regional.host(["us.*"]).map(() => import("./regions/us"));
-regional.host(["eu.*"]).map(() => import("./regions/eu"));
+regional.host(["us.*"]).lazy(() => import("./regions/us"));
+regional.host(["eu.*"]).lazy(() => import("./regions/eu"));
 
 export default regional;
 ```
 
 ```typescript
 // host-router.ts
-router.host(["**.regional.example.com"]).map(() => import("./apps/regional"));
+router.host(["**.regional.example.com"]).lazy(() => import("./apps/regional"));
 ```
+
+## Cross-app navigation is a full document load
+
+A client-side navigation that crosses an app boundary (e.g. a `<Link>` or
+intercepted `<a>` from the app at `/` into an app mounted at `/shop`) is a **hard
+document navigation**, not a soft in-tree swap. When the server sees a partial
+(SPA) request whose router id doesn't match the matched app, it returns
+`X-RSC-Reload` and the client does a real document navigation to the target.
+
+Why a reload rather than a soft swap: a soft swap can't faithfully re-establish
+the target app's **document-level** state. Stylesheets shared across apps are
+dropped by React 19's by-`href` resource dedup; and theme, warmup, and
+prefetch-TTL are document-lifetime (captured once at load — see
+`browser/app-shell.ts`), so the target app's config would never take effect. A
+full document load re-establishes the target app's entire document — CSS, theme,
+meta, everything — by construction. So you do **not** need to coordinate
+stylesheet `href`s, `precedence`, theme config, etc. across independently-authored
+apps; each app owns its own document.
+
+**Within-app** navigation is unchanged — a normal soft SPA update (the document
+stays mounted). Only crossing an app boundary triggers the reload.

package/skills/i18n/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: i18n
+description: Locale-aware routing with `include("/:locale?", ...)`, locale resolution chains, and react-intl integration
+argument-hint: "[topic]"
+---
+
+# Internationalization (i18n) and Locale Routing
+
+Rango doesn't ship an i18n module. The router gives you the URL primitives
+(optional include prefixes, constraints, typed reverse) and you compose
+them with whatever message library you use — `react-intl`, `lingui`,
+`@formatjs/intl`, or hand-rolled.
+
+This skill covers:
+
+- Mounting routes under an optional locale prefix (`/`, `/en`, `/gb`)
+- Constraining the prefix to a known locale set
+- Resolving the active locale (URL → cookie → `Accept-Language` → default)
+- Generating localized URLs via `reverse()` round-trip
+- Wiring `react-intl` into an RSC route tree
+
+## URL Shape: Optional Locale Prefix
+
+Mount your localized routes under an optional include prefix so the
+default locale lives at the bare URL and other locales get a prefix:
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+import { menuRoutes } from "./menu";
+
+export const urlpatterns = urls(({ include }) => [
+  include("/:locale?", menuRoutes, { name: "menu" }),
+]);
+```
+
+URLs that match:
+
+| URL            | Matched route   | `ctx.params.locale` |
+| -------------- | --------------- | ------------------- |
+| `/`            | `menu.index`    | `undefined`         |
+| `/en`          | `menu.index`    | `"en"`              |
+| `/c/breads`    | `menu.category` | `undefined`         |
+| `/en/c/breads` | `menu.category` | `"en"`              |
+
+> **Constrain to known locales** when you want unknown locales to fall
+> through to other routes (or 404) instead of being treated as a slug:
+>
+> ```typescript
+> include("/:locale(en|gb|fr)?", menuRoutes, { name: "menu" });
+> ```
+>
+> `/de` now 404s (constraint rejects `de`), and `/c/breads` continues to
+> match `menu.category` with `locale: undefined`. Without the constraint,
+> `/de` would match `menu.index` with `locale: "de"`.
+
+## Reading the Locale in Handlers
+
+Absent optionals are `undefined` (not `""`), so `??` coalesces correctly:
+
+```typescript
+import { Handler } from "@rangojs/router";
+
+export const MenuIndex: Handler<"menu.index"> = (ctx) => {
+  // ctx.params.locale is `string | undefined`
+  const locale = resolveLocale(ctx);
+  return <Welcome locale={locale} />;
+};
+```
+
+The `resolveLocale` helper below implements a typical fallback chain.
+
+## Locale Resolution
+
+URL is the strongest signal but you usually want a fallback chain:
+
+1. **URL prefix** — if the user navigates to `/gb/...`, honor it
+2. **Cookie** — sticky preference set by a previous language switcher
+3. **`Accept-Language`** — browser hint
+4. **Default** — your app default
+
+Put it in a small helper that every locale-aware handler calls:
+
+```typescript
+// lib/locale.ts
+import { cookies, headers } from "@rangojs/router";
+
+export const SUPPORTED_LOCALES = ["en", "gb", "fr"] as const;
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+const DEFAULT_LOCALE: Locale = "en";
+
+const isSupported = (v: string): v is Locale =>
+  (SUPPORTED_LOCALES as readonly string[]).includes(v);
+
+export function resolveLocale(ctx: {
+  params: Record<string, string | undefined>;
+}): Locale {
+  const fromUrl = ctx.params.locale;
+  if (fromUrl && isSupported(fromUrl)) return fromUrl;
+
+  const fromCookie = cookies().get("locale")?.value;
+  if (fromCookie && isSupported(fromCookie)) return fromCookie;
+
+  const accept = headers().get("accept-language") ?? "";
+  for (const tag of accept.split(",")) {
+    const code = tag.split(";")[0].trim().split("-")[0];
+    if (isSupported(code)) return code as Locale;
+  }
+  return DEFAULT_LOCALE;
+}
+```
+
+If you want to redirect to the canonical URL when the resolved locale
+doesn't match the URL (e.g., user has `gb` cookie but visits `/`), do
+that in a global middleware so it covers actions too:
+
+```typescript
+import { redirect } from "@rangojs/router";
+
+router.use("/*", async (ctx, next) => {
+  const fromUrl = ctx.params.locale;
+  const resolved = resolveLocale(ctx);
+  if (resolved !== DEFAULT_LOCALE && !fromUrl) {
+    return redirect(`/${resolved}${ctx.url.pathname}`);
+  }
+  await next();
+});
+```
+
+## Generating Localized URLs
+
+`reverse()` treats `undefined` and `""` for an optional param as "absent"
+and collapses the segment cleanly. The round-trip is symmetric with the
+matcher:
+
+```typescript
+ctx.reverse("menu.index", { locale: "" }); // → "/"
+ctx.reverse("menu.index", { locale: undefined }); // → "/"
+ctx.reverse("menu.index", { locale: "en" }); // → "/en"
+ctx.reverse("menu.category", { locale: "en", slug: "breads" }); // → "/en/c/breads"
+ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads"
+```
+
+If the active locale is the app default and your URL strategy hides it
+(`"en"` → `/`, others → `/<locale>`), normalize before calling reverse:
+
+```typescript
+const normalized = locale === DEFAULT_LOCALE ? undefined : locale;
+const href = ctx.reverse("menu.category", { locale: normalized, slug });
+```
+
+## react-intl Integration
+
+`react-intl` needs a `<IntlProvider>` wrapping the tree, with `locale`
+and `messages` props. The cleanest split: load messages on the server
+(handler or layout), pass them through to a client provider component.
+
+### Messages loader
+
+Load message bundles per locale. Keep them server-side so they stream
+through the RSC payload and don't bloat the client bundle:
+
+```typescript
+// lib/messages.ts
+import type { Locale } from "./locale";
+
+const loaders: Record<Locale, () => Promise<Record<string, string>>> = {
+  en: () => import("../messages/en.json").then((m) => m.default),
+  gb: () => import("../messages/gb.json").then((m) => m.default),
+  fr: () => import("../messages/fr.json").then((m) => m.default),
+};
+
+export async function loadMessages(locale: Locale) {
+  return loaders[locale]();
+}
+```
+
+### Server layout: hand off to the client provider
+
+```tsx
+// layouts/intl-layout.tsx (server component)
+import type { ReactNode } from "react";
+import { resolveLocale } from "../lib/locale";
+import { loadMessages } from "../lib/messages";
+import { IntlClientProvider } from "../components/intl-client-provider";
+
+export async function IntlLayout({
+  ctx,
+  children,
+}: {
+  ctx: any;
+  children: ReactNode;
+}) {
+  const locale = resolveLocale(ctx);
+  const messages = await loadMessages(locale);
+  return (
+    <IntlClientProvider locale={locale} messages={messages}>
+      {children}
+    </IntlClientProvider>
+  );
+}
+```
+
+### Client provider
+
+```tsx
+// components/intl-client-provider.tsx
+"use client";
+
+import { IntlProvider } from "react-intl";
+import type { ReactNode } from "react";
+
+export function IntlClientProvider({
+  locale,
+  messages,
+  children,
+}: {
+  locale: string;
+  messages: Record<string, string>;
+  children: ReactNode;
+}) {
+  return (
+    <IntlProvider
+      locale={locale}
+      defaultLocale="en"
+      messages={messages}
+      onError={(err) => {
+        if (err.code === "MISSING_TRANSLATION") return; // common, log only
+        console.error(err);
+      }}
+    >
+      {children}
+    </IntlProvider>
+  );
+}
+```
+
+### Mounting
+
+Wrap your localized routes with the layout:
+
+```typescript
+import { urls } from "@rangojs/router";
+import { IntlLayout } from "./layouts/intl-layout";
+import { menuRoutes } from "./menu";
+
+export const urlpatterns = urls(({ layout, include }) => [
+  layout(IntlLayout, () => [
+    include("/:locale?", menuRoutes, { name: "menu" }),
+  ]),
+]);
+```
+
+`<FormattedMessage>`, `useIntl()`, etc. work in any client component
+under the layout. Server components can use `formatjs`'s `createIntl()`
+directly with the same `messages` map for static text.
+
+## Common Pitfalls
+
+| Pitfall                                                       | Fix                                                                                    |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `ctx.params.locale === ""` returns `false`                    | Absent optionals are `undefined`, not `""`. Use `=== undefined` or `??`.               |
+| `ctx.params.locale ?? "en"` returns `""`                      | Pre-fix behavior. After the include-prefix fix this works correctly.                   |
+| Bare `/` 404s when mounted via `include("/:locale?", routes)` | Requires the all-optional pattern fix in `compilePattern` (shipped).                   |
+| Unknown locale (e.g. `/de`) matches as `locale: "de"`         | Add a constraint: `:locale(en\|gb\|fr)?`. Unknown values now 404.                      |
+| Reverse produces `//c/breads` for absent locale               | `reverse()` collapses `undefined`/`""` segments — should not happen. File a bug.       |
+| Locale switcher loses search params                           | Read `ctx.url.search` and pass to `reverse(..., undefined, parsedSearch)`.             |
+| Action middleware can't read `ctx.params.locale`              | Route middleware doesn't wrap action execution. Use global `router.use()` for actions. |
+
+## Cross-references
+
+- `/route` — optional URL param syntax and runtime contract
+- `/typesafety` — `RouteParams<"name">` typing for optionals
+- `/middleware` — global vs route middleware scope (matters for actions)
+- `/server-actions` — actions and the global-vs-route middleware boundary
+- `/links` — `ctx.reverse()` and locale-aware URL generation

package/skills/intercept/SKILL.md

@@ -8,9 +8,6 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Basic Intercept
 
 ```typescript
@@ -26,7 +23,7 @@ function ShopLayout() {
   );
 }
 
-export const urlpatterns = urls(({ path, layout, intercept, loader }) => [
+export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) => [
   layout(<ShopLayout />, () => [
     // Intercept product detail - shows modal during soft navigation
     intercept(
@@ -110,8 +107,10 @@ Use named revalidation contracts on both the outer producer and the intercept
 consumer when they share `ctx.set()` data:
 
 ```typescript
-export const revalidateProductShell = ({ actionId }) =>
-  actionId?.includes("src/actions/product.ts#") ?? false;
+import * as ProductActions from "./actions/product";
+
+export const revalidateProductShell = (ctx) =>
+  ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns
@@ -143,18 +142,41 @@ layout(ProductLayout, () => [
 ]);
 ```
 
-## Conditional Intercept with when()
+## Conditional Intercept with the `when` config
 
-Only intercept based on navigation context:
+Only intercept based on navigation context. `when` is the 4th argument
+(an `InterceptConfig` object); the other use-items go in the 5th-argument
+callback.
 
 ```typescript
 intercept(
   "@modal",
   "product",
   <ProductModal />,
+  // Only intercept when coming from a different section
+  { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
+  () => [
+    loader(ProductLoader),
+  ]
+)
+```
+
+`when` is a match-time selector receiving `{ from, to, params, segments, ... }`.
+Pass an array of predicates for AND logic (all must return true). Omit `when`
+entirely and the intercept always activates.
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  {
+    when: [
+      ({ from }) => from.pathname.startsWith("/shop"),
+      ({ params }) => params.slug !== "featured",
+    ],
+  },
   () => [
-    // Only intercept when coming from a different section
-    when(({ from }) => !from.pathname.startsWith("/shop/product/")),
     loader(ProductLoader),
   ]
 )
@@ -197,6 +219,31 @@ function ModalWrapper({ children }) {
 }
 ```
 
+## Interaction with View Transitions
+
+A layout that owns the `@modal` slot can also configure `transition()` for page
+fades — opening a modal does **not** fire the layout's view transition. Rango
+narrows the layout's `<ViewTransition>` wrap to the layout's default outlet
+content, so `<ParallelOutlet />` (the slot where the modal mounts) is a sibling
+of the wrap, not inside its subtree. Form actions submitted from inside an open
+modal also commit without firing the underlying layout's transition, and the
+modal subtree identity is preserved across revalidation (no remount,
+`useActionState` survives). Closing the modal restores the page without a
+stray transition.
+
+For a modal-only morph (e.g. when intercepted URLs change while the modal
+stays open), use an element-level React `<ViewTransition>` inside the modal
+component — `transition()` accepted on `intercept()` via the DSL is not
+applied to slot rendering today.
+
+Caveat: route-level `transition()` wraps the route component itself, so a
+`<ParallelOutlet />` rendered directly inside that route component would still
+be inside the route's VT subtree. Mount the slot in a layout instead when you
+combine intercept modals with route-level transitions.
+
+See [skills/view-transitions](../view-transitions/SKILL.md) for the full
+contract and direction-aware examples.
+
 ## Interaction with Prerender
 
 When the target route of an intercept uses `Prerender`, the intercept handler is
@@ -218,10 +265,13 @@ layout(ShopLayout, () => [
   ]),
 
   // This intercept is also pre-rendered at build time
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname.startsWith("/shop") },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 
@@ -229,8 +279,8 @@ Build-time behavior:
 
 - The intercept handler (`<ProductModal />`) is resolved with BuildContext
 - Result is stored under the key `"detail/paramHash/i"` (intercept variant)
-- `when()` conditions are skipped at build time (all intercepts pre-rendered unconditionally)
-- `when()` is still evaluated at runtime by the intercept-resolution middleware
+- `when` config conditions are skipped at build time (all intercepts pre-rendered unconditionally)
+- `when` is still evaluated at runtime by the intercept-resolution middleware
 
 Runtime behavior:
 
@@ -281,7 +331,6 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
-  when,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -293,8 +342,8 @@ export const shopPatterns = urls(({
       "@modal",
       "product",  // Route name (without prefix)
       <ProductModalContent />,
+      { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
       () => [
-        when(({ from }) => !from.pathname.startsWith("/shop/product/")),
         layout(<ModalWrapper />),
         loading(<ProductModalSkeleton />),
         loader(ProductLoader, () => [cache()]),
@@ -314,7 +363,7 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`.)
 
 ```typescript
 const QuickViewModal: Handler = async (ctx) => {