@rangojs/router 0.12.2 → 0.12.4

package/dist/types/client-urls/server-projection.d.ts

@@ -54,6 +54,14 @@ export interface ClientUrlProjection {
 export declare function serializeClientUrlPatterns(patterns: ClientUrlPatterns): ClientUrlProjection;
 export declare function isClientUrlPatterns(value: unknown): value is ClientUrlPatterns;
 export declare function isClientUrlReference(value: unknown): value is ClientUrlReference;
+/**
+ * A clientUrls() definition object or, on the server, its client reference.
+ * Run this BEFORE any duck-typing of the value (`typeof === "function"`,
+ * `.handler` reads): a client reference is a callable Proxy that throws on
+ * unknown property reads, so a later shape check would either invoke it as a
+ * thunk or surface React's "cannot dot into a client module" error.
+ */
+export declare function isClientUrlSource(value: unknown): value is ClientUrlDefinitionSource;
 export declare function setClientUrlProjection(reference: string | ClientUrlReference, projection: ClientUrlProjection): void;
 export declare function getClientUrlProjection(reference: string | ClientUrlReference): ClientUrlProjection | undefined;
 export declare function clearClientUrlProjections(): void;

package/dist/types/urls/include-provider.d.ts

@@ -1,12 +1,16 @@
 import type { UrlPatterns } from "./pattern-types.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 /**
  * What an async `include()` provider may resolve to: a `urls()` value directly,
  * or a module namespace whose `default` export is a `urls()` value (the shape
  * produced by `() => import("./routes")` when the route module does
- * `export default urls(...)`).
+ * `export default urls(...)`). A `clientUrls()` module resolves the same way
+ * (`() => import("./shop.client")`); on the server its `default` is the client
+ * reference, adapted exactly as the eager `include(prefix, clientUrlsDefault)`
+ * form.
  */
-export type IncludeModule<TEnv = any> = UrlPatterns<TEnv> | {
-    default: UrlPatterns<TEnv>;
+export type IncludeModule<TEnv = any> = UrlPatterns<TEnv> | ClientUrlPatterns | {
+    default: UrlPatterns<TEnv> | ClientUrlPatterns;
 };
 /**
  * An async/lazy include provider: a thunk returning a `urls()` value (or a
@@ -22,6 +26,7 @@ export type IncludeProvider<TEnv = any> = () => IncludeModule<TEnv> | Promise<In
 export declare function isIncludeProvider(value: unknown): value is IncludeProvider;
 /**
  * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
- * `urls()` value directly or a module whose `default` export is one.
+ * `urls()`/`clientUrls()` value directly or a module whose `default` export is
+ * one.
  */
 export declare function resolveIncludeModule<TEnv = any>(mod: IncludeModule<TEnv>, id?: string): UrlPatterns<TEnv>;

package/dist/types/urls/path-helper-types.d.ts

@@ -40,10 +40,12 @@ export type TextResponsePathFn<TEnv> = <const TPattern extends string, const TNa
 /**
  * What an async include() provider resolves to. Route types (`TRoutes`) are
  * inferred from the resolved `urls()` value so `href()` and named routes stay
- * type-safe through a code-split module (`() => import("./routes")`).
+ * type-safe through a code-split module (`() => import("./routes")`). A
+ * clientUrls() module's default export types as ClientUrlPatterns, so
+ * `() => import("./shop.client")` infers the group's names the same way.
  */
-type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | {
-    default: UrlPatterns<TEnv, TRoutes, TResponses>;
+type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | {
+    default: UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes>;
 };
 /** include() argument: an eager `urls()` value or an async provider thunk. */
 export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);

package/dist/vite/index.js

@@ -3746,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.12.2",
+  version: "0.12.4",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -201,13 +201,13 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "vitest": "^4.1.9",
     "@shared/e2e": "0.0.1"
   },

package/skills/client-urls/SKILL.md

@@ -112,6 +112,10 @@ import shopUrls from "./shop.client.js";
 include("/shop", shopUrls, { name: "shop" });
 ```
 
+The async form works without a server wrapper module too:
+`include("/shop", () => import("./shop.client.js"), { name: "shop" })` — same
+behavior, no startup win, uniform with code-split server groups.
+
 Route names compose through the include (`shop.index`, `shop.product`) and
 flow into the generated route map, so `href`/`reverse` and `Handler<"...">`
 typing work exactly as for server routes (`/typesafety`).

package/skills/view-transitions/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: [layout|route|parallel|intercept]
 `transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
 1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions.
-2. **`<ViewTransition>` (the animation, layered on top).** On experimental React, rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs experimental React; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
+2. **`<ViewTransition>` (the animation, layered on top).** On React 19.3+ (or an experimental build), rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs 19.3+; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
-> The `<ViewTransition>` layer requires React experimental (the build that exports `<ViewTransition>` / `addTransitionType`). On stable React that layer is a no-op — but the `startTransition` driving (content hold) still applies.
+> The `<ViewTransition>` layer requires a React that exports `<ViewTransition>` / `addTransitionType`: stable 19.3+ or an experimental build. Rango feature-detects it; on React 19.2 that layer is a no-op — but the `startTransition` driving (content hold) still applies.
 
 ## Purpose: `startTransition` vs `<ViewTransition>`
 
@@ -24,11 +24,11 @@ These are two **independent** mechanisms. `startTransition` controls _fallbacks_
 
 The bottom-left cell is the key constraint: a view transition cannot exist without a `startTransition`. So once you reach for `transition()`, the only real choice is _startTransition_ vs _startTransition + ViewTransition_:
 
-| What you want                          | Config                                              | Effect                                                                                                 |
-| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| nothing (default nav)                  | no `transition()`                                   | remount + skeleton on param change                                                                     |
-| `startTransition` only                 | `transition({ viewTransition: false })`             | hold content; place your own `<ViewTransition>` where you want it                                      |
-| `startTransition` + `<ViewTransition>` | `transition({})` / `transition({ enter, exit, … })` | hold + router cross-fade (experimental React; on stable it degrades to the `startTransition`-only row) |
+| What you want                          | Config                                              | Effect                                                                                                        |
+| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| nothing (default nav)                  | no `transition()`                                   | remount + skeleton on param change                                                                            |
+| `startTransition` only                 | `transition({ viewTransition: false })`             | hold content; place your own `<ViewTransition>` where you want it                                             |
+| `startTransition` + `<ViewTransition>` | `transition({})` / `transition({ enter, exit, … })` | hold + router cross-fade (React 19.3+ or experimental; on 19.2 it degrades to the `startTransition`-only row) |
 
 `createRouter({ viewTransition: "auto" \| false })` sets the app-wide default for the third row; a per-segment `viewTransition` wins. See [Opting out of the router boundary](#opting-out-of-the-router-boundary-place-your-own-viewtransition) for the full opt-out story.
 
@@ -322,6 +322,24 @@ On stable React the "VT" column is always a no-op (there is no `<ViewTransition>
 
 > On **stable** React there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
+## Testing a transition() route
+
+On React 19.3+ a transition commit briefly keeps the exiting `<ViewTransition>`
+host in the DOM next to the entering one (hidden, carrying React's `vt-*`
+attributes) for a few hundred milliseconds. A strict Playwright locator on a
+test id that exists in both the old and the new view (same route, different
+params; a hard load followed by a revalidation commit) resolves to two elements
+during that window. Target the entering host, which is appended after the
+exiting one:
+
+```ts
+const page$ = page.getByTestId("feature-page").last();
+await expect(page$).toBeVisible();
+```
+
+Waiting for `toHaveCount(1)` first is not enough: the count passes through 1
+before the second host is inserted.
+
 ## Recommendations
 
 **Put `<ParallelOutlet />` in layouts, not routes.** A route-level `transition` wraps the route component itself, so a `<ParallelOutlet />` rendered directly inside that route component remains inside the route VT subtree — modal opens on a route with a parallel outlet _will_ trigger the route's VT walker. The narrowing fix only applies at layout boundaries. If you combine intercept modals with route-level transitions, mount the slot one level up in a layout.

package/src/client-urls/server-projection.ts

@@ -359,6 +359,19 @@ export function isClientUrlReference(
   }
 }
 
+/**
+ * A clientUrls() definition object or, on the server, its client reference.
+ * Run this BEFORE any duck-typing of the value (`typeof === "function"`,
+ * `.handler` reads): a client reference is a callable Proxy that throws on
+ * unknown property reads, so a later shape check would either invoke it as a
+ * thunk or surface React's "cannot dot into a client module" error.
+ */
+export function isClientUrlSource(
+  value: unknown,
+): value is ClientUrlDefinitionSource {
+  return isClientUrlPatterns(value) || isClientUrlReference(value);
+}
+
 /**
  * Strip vite's HMR timestamp query from a module id. After an HMR update of
  * a clientUrls module, the RSC graph re-imports it under

package/src/router.ts

@@ -3,10 +3,7 @@ import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
-import {
-  isClientUrlPatterns,
-  isClientUrlReference,
-} from "./client-urls/server-projection.js";
+import { isClientUrlSource } from "./client-urls/server-projection.js";
 import type { ClientUrlPatterns } from "./client-urls/types.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
@@ -784,10 +781,7 @@ export function createRouter<TEnv = any>(
       // same lazy include materialization, so no ordering, one-definition, or
       // deferral rules exist. Prefixing, wrapping RSC layouts, and middleware
       // scope still come from mounting through include() in urls() yourself.
-      if (
-        isClientUrlPatterns(patternsOrBuilder) ||
-        isClientUrlReference(patternsOrBuilder)
-      ) {
+      if (isClientUrlSource(patternsOrBuilder)) {
         const clientSource = patternsOrBuilder as ClientUrlPatterns;
         patternsOrBuilder = urls(({ include }) => [
           include("/", clientSource, { name: "" }),

package/src/segment-system.tsx

@@ -40,8 +40,9 @@ function segDebugLog(msg: string, details?: Record<string, unknown>): void {
   console.log(prefix);
 }
 
-// ViewTransition is only available in React experimental.
-// Access via namespace import to avoid compile-time errors on stable React.
+// ViewTransition ships in React 19.3+ (and experimental builds); older stable
+// releases lack it. Feature-detect via the namespace import so the router
+// compiles against any supported React and degrades to a no-op boundary.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
@@ -435,7 +436,7 @@ export async function renderSegments(
       nodeContent = registerLazyRef(resolvedComponent);
     }
 
-    // Wrap with <ViewTransition> if transition config exists (React experimental only).
+    // Wrap with <ViewTransition> if transition config exists (React 19.3+ / experimental).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
     // in transitions without adding custom animation classes. Named element-level
     // <ViewTransition> components inside (with name/share props) morph independently

package/src/urls/include-helper.ts

@@ -13,8 +13,7 @@ import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
 import {
   clientUrlIncludePatterns,
-  isClientUrlPatterns,
-  isClientUrlReference,
+  isClientUrlSource,
 } from "../client-urls/server-projection.js";
 import type { ClientUrlPatterns } from "../client-urls/types.js";
 
@@ -77,14 +76,11 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   ): IncludeItem => {
     const { ctx } = requireDslContext("include() must be called inside urls()");
 
-    // clientUrls() sources mount through include() like any urls() module.
-    // Detect them FIRST: a client REFERENCE is a callable proxy, so the
-    // downstream provider check (`typeof === "function"`) would otherwise
-    // invoke it as an async include thunk. The substituted handler defers
-    // materialization to evaluation time, when the discovery-installed
-    // projection is available; the include machinery then applies URL and
-    // route-name prefixes exactly as for server modules.
-    if (isClientUrlPatterns(patterns) || isClientUrlReference(patterns)) {
+    // clientUrls() sources mount like any urls() module: the adapter defers
+    // materialization to evaluation time (projection installed by then) and
+    // the include machinery applies URL/name prefixes as for server modules.
+    // Ordering: see isClientUrlSource.
+    if (isClientUrlSource(patterns)) {
       patterns = clientUrlIncludePatterns(patterns) as UrlPatterns<TEnv>;
     }
 

package/src/urls/include-provider.ts

@@ -1,14 +1,23 @@
 import type { UrlPatterns } from "./pattern-types.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
+import {
+  clientUrlIncludePatterns,
+  isClientUrlSource,
+} from "../client-urls/server-projection.js";
 
 /**
  * What an async `include()` provider may resolve to: a `urls()` value directly,
  * or a module namespace whose `default` export is a `urls()` value (the shape
  * produced by `() => import("./routes")` when the route module does
- * `export default urls(...)`).
+ * `export default urls(...)`). A `clientUrls()` module resolves the same way
+ * (`() => import("./shop.client")`); on the server its `default` is the client
+ * reference, adapted exactly as the eager `include(prefix, clientUrlsDefault)`
+ * form.
  */
 export type IncludeModule<TEnv = any> =
   | UrlPatterns<TEnv>
-  | { default: UrlPatterns<TEnv> };
+  | ClientUrlPatterns
+  | { default: UrlPatterns<TEnv> | ClientUrlPatterns };
 
 /**
  * An async/lazy include provider: a thunk returning a `urls()` value (or a
@@ -36,9 +45,19 @@ function isUrlPatterns(value: unknown): value is UrlPatterns {
   );
 }
 
+/**
+ * A `urls()` value as is; a `clientUrls()` source through the same adapter the
+ * eager include() path applies (ordering: see isClientUrlSource).
+ */
+function toUrlPatterns(value: unknown): UrlPatterns | undefined {
+  if (isClientUrlSource(value)) return clientUrlIncludePatterns(value);
+  return isUrlPatterns(value) ? value : undefined;
+}
+
 /**
  * Normalize an async provider's resolved value to a `UrlPatterns`. Accepts a
- * `urls()` value directly or a module whose `default` export is one.
+ * `urls()`/`clientUrls()` value directly or a module whose `default` export is
+ * one.
  */
 export function resolveIncludeModule<TEnv = any>(
   mod: IncludeModule<TEnv>,
@@ -53,8 +72,8 @@ export function resolveIncludeModule<TEnv = any>(
   // 404s with a misleading error). A bare `() => urls(...)` provider (no
   // module) has no `default`, so it still resolves via the mod-as-value branch.
   const def = (mod as { default?: unknown })?.default;
-  if (isUrlPatterns(def)) return def as UrlPatterns<TEnv>;
-  if (isUrlPatterns(mod)) return mod as UrlPatterns<TEnv>;
+  const resolved = toUrlPatterns(def) ?? toUrlPatterns(mod);
+  if (resolved) return resolved as UrlPatterns<TEnv>;
   // The common failure is a module namespace whose `default` is missing or not a
   // urls() value (e.g. only named exports); `typeof` alone says "object" and
   // hides that, so name the keys present. "provider" (not "async provider") —
@@ -65,7 +84,7 @@ export function resolveIncludeModule<TEnv = any>(
       : typeof mod;
   throw new Error(
     `[@rangojs/router] include() provider${id ? ` for "${id}"` : ""} must ` +
-      `resolve to a urls() value — either returned directly or as the module's ` +
-      `\`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
+      `resolve to a urls() or clientUrls() value — either returned directly or ` +
+      `as the module's \`default\` export (e.g. \`export default urls(...)\`). Got ${got}.`,
   );
 }

package/src/urls/path-helper-types.ts

@@ -160,7 +160,9 @@ export type TextResponsePathFn<TEnv> = <
 /**
  * What an async include() provider resolves to. Route types (`TRoutes`) are
  * inferred from the resolved `urls()` value so `href()` and named routes stay
- * type-safe through a code-split module (`() => import("./routes")`).
+ * type-safe through a code-split module (`() => import("./routes")`). A
+ * clientUrls() module's default export types as ClientUrlPatterns, so
+ * `() => import("./shop.client")` infers the group's names the same way.
  */
 type IncludeResolved<
   TEnv,
@@ -168,7 +170,12 @@ type IncludeResolved<
   TResponses extends Record<string, unknown>,
 > =
   | UrlPatterns<TEnv, TRoutes, TResponses>
-  | { default: UrlPatterns<TEnv, TRoutes, TResponses> };
+  | ClientUrlPatterns<TRoutes>
+  | {
+      default:
+        | UrlPatterns<TEnv, TRoutes, TResponses>
+        | ClientUrlPatterns<TRoutes>;
+    };
 
 /** include() argument: an eager `urls()` value or an async provider thunk. */
 export type IncludeArg<