@rangojs/router 0.33.0 → 0.33.1

package/dist/bin/rango.js

@@ -229,7 +229,7 @@ ${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}
   }
   let discoverAndWriteRouteTypes;
   try {
-    const mod = await import("./runtime-discovery-CZ2QHT4Q.js");
+    const mod = await import("./runtime-discovery-3HH6BP3K.js");
     discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
   } catch (err) {
     if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "MODULE_NOT_FOUND") {

package/dist/bin/{runtime-discovery-CZ2QHT4Q.js → runtime-discovery-3HH6BP3K.js}

@@ -163,7 +163,7 @@ async function discoverAndWriteRouteTypes(opts) {
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc"
     );
   }
-  const { createTempRscServer } = await import("./temp-rsc-server-QRR6HD6T.js");
+  const { createTempRscServer } = await import("./temp-rsc-server-JALTIWLT.js");
   const { createDiscoveryState } = await import("./state-ACD2MGKJ.js");
   const { discoverClientUrlProjections } = await import("./client-urls-projection-DQLWPDAT.js");
   const {

package/dist/bin/{temp-rsc-server-QRR6HD6T.js → temp-rsc-server-JALTIWLT.js}

@@ -47,7 +47,7 @@ var DEFAULT_ROUTER_VERSIONS_KEY = "*";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.33.0",
+  version: "0.33.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/dist/vite/index.js

@@ -7327,7 +7327,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.33.0",
+  version: "0.33.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/app-structure/SKILL.md

@@ -120,6 +120,13 @@ here for the rules they share.
    by name, keep page-specific blocks in their route, and write such a rule
    for chrome that shows a param's data
    ([Prefetches are shared](#prefetches-are-shared)).
+10. **A layout keeps its `<Outlet />` in one place.** Branch inside one shape
+    (`<>{promo ? <Banner /> : null}<Outlet /></>`), never between a bare
+    `return <Outlet />` and a wrapped one: the outlet moves, and every page
+    below remounts when the branch flips, its state reset and its mount
+    effects run again. When an early return is unavoidable and the other
+    branch is only a fragment, give the outlet the same `key` in both
+    (`/layout`, "Moving the Outlet remounts its children").
 
 ## A small app: one module
 

package/skills/app-structure/large-app.md

@@ -893,6 +893,9 @@ stay inside the project module can come from `useReverse(routes)` in
   user's name): the capture is refused and the page never serves a shell.
 - **`prefetch: false` on every loader**: each click then waits for a fill.
   Flag the expensive, rarely-clicked ones.
+- **A layout that moves its `<Outlet />` between branches** (a bare
+  `return <Outlet />` on one, a wrapped one on another): every page below it
+  remounts when the branch flips. Keep one shape (`/layout`).
 - **A bare `isAction(refs)` predicate**: it is a hard `false` on navigation
   too, so the loader stops following param changes. Use
   `isAction() ? isAction(refs) : undefined` (`/loader`).

package/skills/client-urls/SKILL.md

@@ -745,6 +745,17 @@ a hard load of the target URL renders the full route.
   throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
   (route-independent lane; `revalidate()` deliberately not consulted).
   Pinned in the router repo's client-urls hook-probe e2e.
+- **An action called on the optimistic frame runs against the committed
+  page.** The destination mounts at the click, before the navigation
+  commits, so an action its mount effect calls is sent from the page the URL
+  bar still shows: the server runs it with that page's request context
+  (`ctx.url`, `ctx.params`, its middleware) and re-renders that page, not
+  the destination. Nothing of that render reaches the destination, and a
+  write still refreshes the destination once it commits (unless the action
+  called `keepClientCache()`). Pass what the action needs as arguments
+  instead of reading the request's URL or params. A link prefetched before
+  the click (the production default, `viewport`) usually commits before the
+  effect runs.
 - **Location state follows the same split as the route hooks.** Inside the
   optimistic branch (the destination and the group's client layouts)
   `useLocationState` reads the state the navigation carries (`<Link state>`,

package/skills/hooks/outlets.md

@@ -28,6 +28,10 @@ function DashboardLayout() {
 `ParallelOutlet` requires the name and reads clearer at the call site. See
 `/layout` and `/parallel` for the server side.
 
+An outlet that moves between a layout's branches (bare in one, wrapped in
+another) remounts its children; see `/layout`, "Moving the Outlet remounts its
+children".
+
 ### useOutlet()
 
 Access outlet content and its client-route presentation state programmatically:

package/skills/layout/SKILL.md

@@ -12,6 +12,12 @@ layout stays mounted while you navigate between the routes it wraps. This skill
 covers layout forms, outlets, orphan layouts (a layout inside a `path()`), and
 layout revalidation.
 
+**Rule: a layout keeps its `<Outlet />` in one place on every branch.** Branch
+around the outlet, never around it and the outlet together: an early
+`return <Outlet />` beside a wrapped one remounts every child segment each time
+the branch flips (state resets, mount effects and the actions they call run
+again). See [Moving the Outlet remounts its children](#moving-the-outlet-remounts-its-children).
+
 Related skills: `/parallel` (named slots rendered by a layout), `/intercept`
 (modal slots), `/route` (the routes a layout wraps), `/router-setup` (the
 `document` shell that renders `<html>`).
@@ -131,6 +137,49 @@ 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.
 
+### Moving the Outlet remounts its children
+
+React keeps a subtree mounted only while each element on its path keeps the
+same type at the same position. A layout that returns a bare `<Outlet />` on
+one branch and wraps it on another (a fragment, a `<div>`) moves the outlet,
+so when the branch flips, every child segment unmounts and mounts again:
+client state resets, mount effects run again (an action they call is sent
+again), and the content flashes. Prefer one shape with the branch inside it:
+
+```tsx
+// Remounts the children whenever `promo` flips
+function CategoryLayout({ promo }: { promo: boolean }) {
+  if (!promo) return <Outlet />;
+  return (
+    <>
+      <PromoBanner />
+      <Outlet />
+    </>
+  );
+}
+
+// Keeps them mounted: the outlet keeps its position
+function CategoryLayout({ promo }: { promo: boolean }) {
+  return (
+    <>
+      {promo ? <PromoBanner /> : null}
+      <Outlet />
+    </>
+  );
+}
+```
+
+A stable `key` on the outlet (`<Outlet key="outlet" />` in both branches)
+also keeps the children mounted when the only difference is a top-level
+fragment: React reads a component's unkeyed top-level fragment as a list of
+siblings and matches the keyed outlet across it. It does not help when one
+branch wraps the outlet in an element (a `<div>`, a provider): the outlet then
+sits one level deeper, and keys match only among siblings.
+
+All of this applies to `<ParallelOutlet />` too. To reset the children on
+purpose, change a `key` on a stable wrapper rather than relying on a shape
+change.
+
 ## Named Outlets
 
 For parallel routes, use named outlets (`<Outlet name="@sidebar" />` is

package/skills/ux-architecture/SKILL.md

@@ -941,7 +941,9 @@ Each entry: what the user sees, why, the fix.
 8. **Shared chrome in a route component.** It remounts on every navigation to
    another route: its state resets and its own fallbacks show again. Fix: move
    it into a `layout()` (a group `layout()` keeps its instance across its
-   routes; a server layout across everything below it).
+   routes; a server layout across everything below it). A layout that moves
+   its `<Outlet />` between branches remounts the children the same way; see
+   `/layout`, "Moving the Outlet remounts its children".
 9. **`useEffect` fetching.** A spinner after the page has shown, nothing
    prefetched or server-rendered, no re-run after an action, races on fast
    navigations. Fix: a loader read with `useLoader`; `useFetchLoader` for

package/src/browser/server-action-bridge.ts

@@ -885,14 +885,19 @@ export function createServerActionBridge(
         throw new Error("No matched segments in response");
       }
 
-      // Reconcile server segments with cached segments (single source of truth)
-      const reconciled = reconcileSegments({
-        actor: "action",
-        matched,
-        diff: diff || [],
-        serverSegments: segments || [],
-        cachedSegments,
-      });
+      // Reconcile server segments with cached segments (single source of
+      // truth). A page that left commits nothing (navigated-away), and the
+      // cache on screen is another page's: reconciling would report missing
+      // segments.
+      const reconciled = navigatedSince()
+        ? { segments: [], mainSegments: [], interceptSegments: [] }
+        : reconcileSegments({
+            actor: "action",
+            matched,
+            diff: diff || [],
+            serverSegments: segments || [],
+            cachedSegments,
+          });
       const fullSegments = reconciled.segments;
 
       const returnData = returnValue?.data;