feat(router)!: group-stable segment for clientUrls() — the optimistic instance survives the commit - #852

Problem

0.13.0 renders a clientUrls() destination optimistically, but each projected route is its own server segment keyed by id-params, so the canonical commit mounted the destination as a new segment and unmounted the optimistic branch. The instance the user was already interacting with was replaced: text typed into a field during the wait was lost, and effects ran twice. The design doc recorded this as the phase-one limitation and named the fix.

Before / after

// Same group, same code. Click A -> B behind a slow middleware, type into B.
<input data-testid="search" />

End-to-end example

// src/urls/portal.client.tsx
"use client";
import { Suspense, useState } from "react";
import { clientUrls, Link, useLoader, useParams } from "@rangojs/router/client";
import { SiteLoader } from "./portal.loader.js";

function Site() {
  const { siteId } = useParams<{ siteId: string }>();
  const [filter, setFilter] = useState("");
  return (
    <article>
      <input value={filter} onChange={(e) => setFilter(e.target.value)} />
      <Suspense fallback={<h1>{siteId}</h1>}>
        <SiteName />
      </Suspense>
      <Link to="/portal/sites/beta">Beta</Link>
    </article>
  );
}
function SiteName() {
  const { data } = useLoader(SiteLoader);
  return <h1>{data.name}</h1>;
}

export default clientUrls(({ path, loader }) => [
  path("/sites/:siteId", Site, { name: "site" }, () => [loader(SiteLoader)]),
]);

Clicking Beta from Acme keeps Site mounted and filter intact; the heading holds "Acme" until Beta's loader lands, then swaps. No transition() needed for the hold.

Semantics

Code changes

• src/client-urls/server-projection.ts — every materialized route gets clientGroup = the include's URL prefix ("/" at root).
• src/urls/pattern-types.ts (PathOptions.clientGroup, internal), src/urls/path-helper.ts, src/server/context.ts (EntryData), src/router/segment-resolution/fresh.ts + revalidation.ts, src/types/segments.ts (ResolvedSegment), src/cache/segment-codec.ts — carry the key from the DSL to the browser and through the segment cache.
• src/segment-system.tsx — group routes: React key cg:<group>; one wrapper shape (no LoaderBoundary/RouteContentWrapper, always StreamedLoaderErrorBoundary); the id-params identity is computed once and passed as the boundary's resetKey.

  const idParamsKey = paramStr ? `${id}-${paramStr}` : id;
  const key = clientGroup ? `cg:${clientGroup}` : idParamsKey;

• src/route-content-wrapper.tsx — StreamedLoaderErrorBoundary clears its caught marker in getDerivedStateFromProps when resetKey changes. Found by the e2e: a surviving boundary kept rendering LoaderRedirect for /legacy after the redirect had landed on /state, so the target never rendered (also the vite-rsc-demo "moved product redirects" flakes).
• src/client-urls/client-root.tsx — the wrapper chain (OutletProvider + OptimisticLocationContext.Provider, Suspense when the route declares loading()) is identical in the optimistic and canonical states; only prop values change.
• src/browser/partial-update.ts — a navigation that presented optimistically commits in the transition lane, so a read that still suspends holds the presented content instead of flashing a fallback.
• Docs: docs/design/client-urls-optimistic-destination.md (mechanics 4 rewritten, phase two marked shipped, the boundary-reset scar recorded), docs/client-urls.md (navigation authority, same-route section), skills/client-urls/SKILL.md (transition() row).
• E2e: both slow-middleware suites type into B during the window and assert the value after the commit; client-urls.test.ts "same-route param navs hold previous content in a group, with or without transition()" replaces the plain-twin re-stream expectation.

Why the shape is uniform client-side rather than by emitting loading() for every group route server-side: loading() masks loaders during PPR shell capture (entryLoadingMasksLoaders), so a synthetic server-side loading() would silently change capture for group routes without one. Keeping the segment's loading value intact and only changing what renderSegments builds leaves every server contract as it was.

Test plan

• Unit: segment-system.test.tsx "keys clientUrls() group routes by the group and gives them one wrapper shape"; client-root.test.tsx "keeps the optimistic instance across the canonical commit" (typed state survives, mount effect runs once); new streamed-loader-error-boundary.test.tsx pins the reset and the no-reset case; existing view-transition and client-urls pins green.
• E2e dev + production, test-app and cloudflare-basic: slow-middleware suites (state persists across the commit; presentation timings unchanged), client-urls (redirect-with-state probe, same-route hold with and without transition()), loader-behavior (tree-structure rule), conditional-transition, prefetch-transition, client-reverse, location-state.
• E2e vite-rsc-demo client-shop-* (the redirect flakes from the first run disappeared with the boundary reset; one remaining flake was a dev-server setup timeout).
• pnpm run typecheck, pnpm run test:unit:all, pnpm run lint, pnpm run format, check:e2e-bucketing, check:e2e-parity --strict, check:docs-api.

Notes

• Release: minor bump. Same-route param navigations inside a group now hold by default; transition() in a group no longer changes the hold, only the animation.
• /simplify applied: the id-params identity is computed once for the key and the reset key; the shapeLoading indirection became direct group gates; type comments point at the segment-system branch instead of repeating it. Three of four reviewers stalled; their angles were covered by hand. Skipped: deriving the group from mountPath (a server route mounted at the same prefix would wrongly take the group key and shape), adding clientGroup to segment-structure-assert (static per segment id).
• Local runs during this PR hit a heavily loaded machine: full cloudflare-basic runs took up to an hour and timed out the 5 s-middleware cases in dev; the same cases pass in about 20 s when run alone. No timeout was changed.