@rangojs/router 0.0.0-experimental.98 → 0.0.0-experimental.99

package/dist/vite/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.98",
+  "version": "0.0.0-experimental.99",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/handler-use/SKILL.md

@@ -59,6 +59,8 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 | `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
 | Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
 
+For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
+
 If `handler.use()` returns a disallowed item for a mount site, registration throws:
 
 ```

package/skills/intercept/SKILL.md

@@ -197,6 +197,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

package/skills/layout/SKILL.md

@@ -118,6 +118,8 @@ function ShopLayout() {
 }
 ```
 
+A layout's `transition()` config wraps the content that flows through `<Outlet />` — not the layout chrome itself, and not sibling `<ParallelOutlet />` slots. Stacking transitions across nested layouts collapses around the deepest default outlet content. See [skills/view-transitions](../view-transitions/SKILL.md) for the full wrap rules and intercept-modal interaction.
+
 ## Named Outlets
 
 For parallel routes, use named outlets:

package/skills/parallel/SKILL.md

@@ -237,6 +237,8 @@ A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an
 
 The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
 
+`transition` is allowed in the slot allow-list, but slot-level rendering does **not** currently apply a `<ViewTransition>` wrapper — only the layout/route wraps take effect at render time. For a modal-only morph today, use an element-level React `<ViewTransition>` inside the slot's component. The reverse direction is the useful guarantee: a layout-level `transition()` fires when the layout's default outlet content changes but **not** when a `<ParallelOutlet />` mounts new content (modal opens are not subtree updates of the layout VT). See [skills/view-transitions](../view-transitions/SKILL.md) for the wrap rules and the intercept caveat.
+
 ### Two scopes for explicit `use`: shared (broadcast) and slot-local
 
 `parallel({...slots}, () => [...use])` runs the shared `use()` callback **once per slot** ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)) — items in that callback land on every slot's entry. That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`). (Slots cannot bring `middleware` or `layout` — see the allowed-types note above.)

package/skills/route/SKILL.md

@@ -403,6 +403,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/view-transitions/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: view-transitions
+description: Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router
+argument-hint: [layout|route|parallel|intercept]
+---
+
+# View Transitions
+
+Rango wires React's experimental `<ViewTransition>` into the segment tree via the `transition()` helper. Each segment can declare its own transition config; rango wraps it at the right tree position so navigations morph the right pieces and modals do not.
+
+> Requires React experimental (the build that exports `<ViewTransition>` and `addTransitionType`). With stable React, `transition()` is a no-op — your routes still render, just without view-transition wrappers.
+
+## What `transition()` does
+
+`transition(config)` attaches a [`TransitionConfig`](#transitionconfig) to the surrounding entry. Where the wrap actually lands in the rendered React tree depends on the segment type:
+
+| Segment type                      | Wrap location                                                                                                                                                                                                                                                                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `layout()`                        | Around the layout's **default outlet content** (what the layout's `<Outlet />` renders), recursively pushed past nested layouts. Parallel slots (`<ParallelOutlet />`) are siblings of the wrap, not subtree members.                                                                                                             |
+| `path()` / `route()`              | Around the **route's component itself** (the leaf content).                                                                                                                                                                                                                                                                       |
+| `parallel()` / `intercept()` slot | `transition()` is accepted by the DSL today, but slot-level rendering does not currently apply a `<ViewTransition>` wrapper. Mount intercept slots in layouts so layout transitions stay scoped to the default outlet. For modal-specific morphs today, use an element-level React `<ViewTransition>` inside the modal component. |
+
+The layout case is the important one: stacking a layout transition does **not** wrap the layout chrome (header, sidebar, modal slot); it only morphs whatever flows through that layout's `<Outlet />`.
+
+## Basic Usage
+
+A simple cross-fade between pages that share a layout:
+
+```tsx
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+function ShopShell({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="shop">
+      <NavBar />
+      <main>
+        <Outlet /> {/* fade applies HERE */}
+      </main>
+      <Footer />
+    </div>
+  );
+}
+
+export const urlpatterns = urls(({ layout, path, transition }) => [
+  layout(<ShopShell />, () => [
+    transition({ default: "page-fade" }),
+    path("/", ShopIndex, { name: "index" }),
+    path("/about", AboutPage, { name: "about" }),
+    path("/contact", ContactPage, { name: "contact" }),
+  ]),
+]);
+```
+
+```css
+::view-transition-old(root) {
+  animation: fade-out 200ms ease both;
+}
+::view-transition-new(root) {
+  animation: fade-in 200ms ease both;
+}
+.page-fade {
+  /* class hooks per phase */
+}
+```
+
+Navigating between `/`, `/about`, and `/contact` morphs the `<Outlet />` content with the `page-fade` class. The shell (NavBar, Footer) does not morph because the wrap sits inside the shell, not around it.
+
+## Direction-aware transitions
+
+`ViewTransitionClass` accepts an object form keyed by transition type. Rango tags forward navigations as `"navigation"` and back/forward popstate as `"navigation-back"`:
+
+```tsx
+layout(<ShopShell />, () => [
+  transition({
+    default: {
+      navigation: "slide-left",
+      "navigation-back": "slide-right",
+    },
+  }),
+  path("/", ShopIndex, { name: "index" }),
+  path("/about", AboutPage, { name: "about" }),
+]);
+```
+
+```css
+.slide-left {
+  animation-name: slide-from-right;
+}
+.slide-right {
+  animation-name: slide-from-left;
+}
+```
+
+> Note: `"action"` is only tagged on partial-update action/refetch paths today; ordinary `server-action-bridge` commits (`useAction` / `useActionState` revalidations) are not currently tagged. Don't rely on an `action`-keyed class to fire on every form action.
+
+## Wrapper form: applying transition to a group of routes
+
+`transition(config, () => [...])` creates a transparent layout that applies the config to its children — useful when you want a transition without authoring a real layout component:
+
+```tsx
+urls(({ path, transition }) => [
+  // No layout component, but every route inside gets the fade.
+  transition({ default: "fade" }, () => [
+    path("/", HomePage, { name: "home" }),
+    path("/about", AboutPage, { name: "about" }),
+  ]),
+  // Outside the wrapper — no transition applied.
+  path("/admin", AdminPage, { name: "admin" }),
+]);
+```
+
+## Intercept (modal) interaction
+
+This is where the rango-specific behavior pays off. A common shape:
+
+```tsx
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function GalleryShell() {
+  return (
+    <>
+      <NavBar />
+      <main>
+        <Outlet /> {/* page transition lands here */}
+      </main>
+      <ParallelOutlet name="@modal" />{" "}
+      {/* modal mounts here — sibling of the VT */}
+    </>
+  );
+}
+
+export const urlpatterns = urls(
+  ({ layout, path, intercept, transition, loader, loading }) => [
+    layout(<GalleryShell />, () => [
+      transition({ default: "fade" }),
+
+      path("/", GalleryFeed, { name: "feed" }),
+      path("/photos/:id", PhotoPage, { name: "photo" }),
+
+      intercept("@modal", "photo", <PhotoModal />, () => [
+        loader(PhotoLoader),
+        loading(<PhotoModalSkeleton />),
+      ]),
+    ]),
+  ],
+);
+```
+
+| Action                                          | What fires                                                                                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Navigate `/` ↔ `/about` (within `GalleryShell`) | Layout transition fires; `<Outlet />` content cross-fades                                                                      |
+| Click `<Link to="/photos/42" />` from `/`       | Soft navigation opens `<PhotoModal />` in `@modal`; **no** view transition fires on the underlying feed                        |
+| Submit a form action inside `<PhotoModal />`    | Revalidation commits without firing the layout VT; modal subtree identity is preserved (no remount, `useActionState` survives) |
+| Close modal via `router.back()`                 | Underlying page is restored; **no** view transition fires                                                                      |
+| Direct URL load `/photos/42`                    | Renders the full `<PhotoPage />` with no modal; the layout transition applies on subsequent in-layout navs                     |
+
+The "no VT on modal open" guarantee holds at any depth — if the layout that owns `@modal` is itself nested inside another transitioned layout, the outer transition is pushed past the inner layout into its default outlet content, so the modal slot ends up outside both VTs.
+
+## Per-route transition
+
+Routes are leaves: their `transition()` wraps the route component itself.
+
+```tsx
+urls(({ path, transition }) => [
+  path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+    transition({ default: "fade-in" }),
+  ]),
+]);
+```
+
+This is the right level for one-off route-specific morphs that should not propagate to siblings.
+
+## TransitionConfig
+
+`transition()` accepts the props of React's `<ViewTransition>` (minus `children`/refs). Each phase prop accepts either a plain class string or an object keyed by transition type:
+
+```ts
+import type { TransitionConfig } from "@rangojs/router";
+
+interface TransitionConfig {
+  enter?: string | Record<string, string>;
+  exit?: string | Record<string, string>;
+  update?: string | Record<string, string>;
+  share?: string | Record<string, string>;
+  default?: string | Record<string, string>; // fallback for any phase
+  name?: string; // explicit view-transition-name
+}
+```
+
+- `default` is the catch-all if a phase-specific prop is unset.
+- The object form keys are React transition types tagged by rango: `"navigation"` (forward navigations), `"navigation-back"` (popstate cache restores), and `"action"` (partial-update action/refetch paths only — see the caveat in "Direction-aware transitions").
+- `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
+
+## 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.
+
+**Don't stack `transition()` on every layout level.** When ancestor and descendant layouts both configure transitions, both wraps end up nested around the deepest default outlet content. Two VTs fire on every nav within the inner layout. That's usually not what you want — pick the level where the morph belongs and apply it once.
+
+**Need a modal-only morph?** Per-slot `transition()` is currently a no-op at render time, so use an element-level React `<ViewTransition>` inside the modal component (or a CSS animation) for the modal-entrance effect.
+
+**Action revalidation inside a modal is safe.** Server-action submits inside an open modal don't fire the underlying layout VT. Modal subtree identity is preserved across revalidation — so `useActionState`, focus, and scroll all survive the round-trip.
+
+## Notes
+
+- `transition()` is part of the route DSL. The allow-list table in [skills/handler-use](../handler-use/SKILL.md) permits it inside `layout()`, `path()`/`route()`, `parallel()` (per-slot or shared), and `intercept()`. At render time, only the layout and route wraps actually take effect today; `parallel()`/`intercept()` slot-level rendering does not currently apply the wrap.
+- Wrap location for layouts: rango walks the rendered tree past `MountContextProvider`/`OutletProvider`/`LoaderBoundary` for layout segments and applies the wrap at the first non-layout target ([segment-system.tsx](../../src/segment-system.tsx) — `wrapDefaultOutletContent`). This is what keeps parallel slots out of the VT subtree.
+- Tree consistency: the wrapper structure is identical across normal commits, intercept-active commits, and action revalidations — React never sees an element-type swap, so layout/modal subtrees are not remounted across these transitions.
+- Element-level `<ViewTransition>` (importing it directly from React and using `name`/`share` to morph specific elements across pages) composes with rango's segment-level wraps as usual; rango doesn't intercept those.
+- See also: [skills/intercept](../intercept/SKILL.md), [skills/parallel](../parallel/SKILL.md), [skills/layout](../layout/SKILL.md).

package/src/browser/navigation-bridge.ts

@@ -541,7 +541,14 @@ export function createNavigationBridge(
             },
             scroll: { restore: true, isStreaming },
           };
-          const hasTransition = cachedSegments.some((s) => s.transition);
+          // Intercept-driven popstate (entering OR leaving an intercept) only
+          // mutates the parallel slot; the main outlet shows the same content.
+          // Skip startViewTransition in those cases — same rationale as the
+          // intercept guard in partial-update.ts's hasTransition computation.
+          const hasTransition =
+            !isIntercept &&
+            !isLeavingIntercept &&
+            cachedSegments.some((s) => s.transition);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {

package/src/browser/partial-update.ts

@@ -14,7 +14,10 @@ const addTransitionType: ((type: string) => void) | undefined =
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import { reconcileSegments } from "./segment-reconciler.js";
 import type { ReconcileActor } from "./segment-reconciler.js";
-import { hasActiveIntercept as hasActiveInterceptSlots } from "./intercept-utils.js";
+import {
+  hasActiveIntercept as hasActiveInterceptSlots,
+  isInterceptSegment,
+} from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
 import { debugLog } from "./logging.js";
@@ -28,6 +31,23 @@ function toScrollPayload(
   return { enabled: scroll !== false ? scroll : false };
 }
 
+/**
+ * Whether to wrap an update in startViewTransition.
+ *
+ * Intercept-driven updates only mutate the parallel slot — the main outlet
+ * shows the same content — so transitions on the underlying main segments
+ * shouldn't fire (otherwise their elements get hoisted above the modal).
+ */
+function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
+  let hasIntercept = false;
+  let hasTransition = false;
+  for (const s of segments) {
+    if (isInterceptSegment(s)) hasIntercept = true;
+    else if (s.transition) hasTransition = true;
+  }
+  return !hasIntercept && hasTransition;
+}
+
 /**
  * Configuration for creating a partial updater
  */
@@ -338,10 +358,7 @@ export function createPartialUpdater(
             scroll: toScrollPayload(commitScroll),
           };
 
-          const cachedHasTransition = existingSegments.some(
-            (s) => s.transition,
-          );
-          if (cachedHasTransition) {
+          if (shouldStartViewTransition(existingSegments)) {
             startTransition(() => {
               if (addTransitionType) {
                 addTransitionType("navigation");
@@ -527,7 +544,7 @@ export function createPartialUpdater(
 
       // Emit update to trigger React render.
       // Scroll info is included so NavigationProvider applies it after React commits.
-      const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+      const hasTransition = shouldStartViewTransition(reconciled.segments);
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
@@ -589,9 +606,7 @@ export function createPartialUpdater(
           })
         : tx.commit(segmentIds, segments);
 
-      const fullHasTransition = segments.some(
-        (s: ResolvedSegment) => s.transition,
-      );
+      const fullHasTransition = shouldStartViewTransition(segments);
       const fullScrollPayload = toScrollPayload(fullScroll);
 
       if (mode.type === "stale-revalidation") {

package/src/segment-system.tsx

@@ -131,6 +131,47 @@ export interface RenderSegmentsOptions {
   rootLayout?: ComponentType<RootLayoutProps>;
 }
 
+function createViewTransitionBoundary(
+  transition: NonNullable<ResolvedSegment["transition"]>,
+  children: ReactNode,
+): ReactNode {
+  return createElement(ReactViewTransition, {
+    ...transition,
+    children,
+  });
+}
+
+function wrapDefaultOutletContent(
+  content: ReactNode,
+  transition: NonNullable<ResolvedSegment["transition"]>,
+): ReactNode {
+  if (!React.isValidElement(content)) {
+    return createViewTransitionBoundary(transition, content);
+  }
+
+  const props = content.props as any;
+
+  if (content.type === MountContextProvider) {
+    return React.cloneElement(content, {
+      children: wrapDefaultOutletContent(props.children, transition),
+    } as any);
+  }
+
+  if (content.type === OutletProvider && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      content: wrapDefaultOutletContent(props.content, transition),
+    } as any);
+  }
+
+  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      outletContent: wrapDefaultOutletContent(props.outletContent, transition),
+    } as any);
+  }
+
+  return createViewTransitionBoundary(transition, content);
+}
+
 /**
  * Render segments into a React tree with proper layout nesting
  *
@@ -273,17 +314,27 @@ export async function renderSegments(
     // in transitions without adding custom animation classes. Named element-level
     // <ViewTransition> components inside (with name/share props) morph independently
     // from the parent's default cross-fade.
-    if (ReactViewTransition && node.segment.transition) {
-      nodeContent = createElement(ReactViewTransition, {
-        ...node.segment.transition,
-        children: nodeContent,
-      });
-    }
-
-    // Common props for OutletProvider
-    const outletContent: ReactNode =
+    //
+    // For layouts, wrap the outlet content (what `<Outlet />` renders) rather
+    // than the layout component itself. Parallel slots like `<ParallelOutlet
+    // name="@modal" />` read from a separate context channel and end up as
+    // siblings of the VT in the rendered tree, so modal mounts don't trigger a
+    // subtree update on the layout-level VT — which would otherwise make
+    // React's commit walker fire `document.startViewTransition` and apply
+    // view-transition-names to the underlying main subtree (cover/title/etc.).
+    let outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
 
+    const transition = node.segment.transition;
+
+    if (ReactViewTransition && transition) {
+      if (node.segment.type === "layout") {
+        outletContent = wrapDefaultOutletContent(outletContent, transition);
+      } else {
+        nodeContent = createViewTransitionBoundary(transition, nodeContent);
+      }
+    }
+
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
     const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);