@timber-js/app 0.2.0-alpha.209 → 0.2.0-alpha.210

package/src/client/browser-entry/action-dispatch.ts

@@ -44,7 +44,7 @@ export function setupServerActions(): void {
     refreshWhenIdle(): void {
       const router = getRouterOrNull();
       if (!router) return;
-      router.runWhenIdle(() => void router.refresh());
+      router.runWhenIdle(() => void router.refresh({ transitionType: 'revalidate' }));
     },
     // Every hold below is `applyActionResult` — the router's own refresh
     // or piggybacked commit. If it has not settled in `holdTimeoutMs`, the
@@ -56,7 +56,7 @@ export function setupServerActions(): void {
     recoverStalledHold(): void {
       const router = getRouterOrNull();
       if (!router) return;
-      void router.refresh();
+      void router.refresh({ transitionType: 'revalidate' });
     },
   });
 
@@ -74,7 +74,7 @@ export function setupServerActions(): void {
 
       let hasRevalidation = false;
       let hasRedirect = false;
-      const reval: { paths: string | null } = { paths: null };
+      let invalidated = false;
 
       const actionHeaders: Record<string, string> = {
         'Accept': RSC_CONTENT_TYPE,
@@ -103,30 +103,35 @@ export function setupServerActions(): void {
         }
         hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
         hasRedirect = res.headers.get('X-Timber-Redirect') != null;
-        reval.paths = res.headers.get('X-Timber-Revalidation-Path');
+        invalidated = res.headers.get('X-Timber-Invalidated') === '1';
         return res;
       });
 
       const decoded = await createFromFetch(response);
 
-      // TIM-1454: Invalidate non-matching paths unconditionally — the
-      // mutation happened server-side regardless of navigation state.
-      if (reval.paths) {
-        if (router) {
-          for (const p of reval.paths.split(' ')) {
-            router.invalidatePath(p);
-          }
-        }
+      // The mutation happened server-side, and the next thing on screen is
+      // not a full render of the current page: revalidatePath named only
+      // other pages (TIM-1454), or the action redirected — from its body, or
+      // from a current-page revalidation whose render redirected (TIM-1461).
+      // Cached payloads go with the eviction below; this covers the mounted
+      // shared layouts the segment cache would otherwise let the server skip
+      // on the next navigation (TIM-1466). The tree and refresh branches
+      // re-render every layout, so they need neither.
+      if (router && (invalidated || hasRedirect)) {
+        router.suppressSegmentReuse();
       }
 
-      // TIM-1476: When the server reports any revalidation, evict all
-      // prefetch cache entries and history stack payloads — the mutation
-      // may affect data any route reads, not just the paths the server
-      // named. Placed before the redirect branch so an internal redirect
-      // via router.navigate() cannot consume a stale prefetch (codex on
-      // #1131). In-flight prefetch singleflights are fenced by the
-      // eviction generation and will not repopulate the cache.
-      if (router && (hasRevalidation || reval.paths)) {
+      // TIM-1476: Evict all prefetch cache entries and history stack
+      // payloads after every action — the mutation may affect data any route
+      // reads, not just the paths the server named, and an action that
+      // revalidated nothing still mutated (TIM-1518). Placed before every
+      // branch: before the redirect so an internal redirect via
+      // router.navigate() cannot consume a stale prefetch (codex on #1131),
+      // and synchronously before applyActionResult's hold so a navigation
+      // that supersedes the refresh cannot either. In-flight prefetch
+      // singleflights are fenced by the eviction generation and will not
+      // repopulate the cache.
+      if (router) {
         router.evictStaleCaches();
       }
 
@@ -178,7 +183,7 @@ export function setupServerActions(): void {
               .then(
                 (applied) => {
                   if (!applied) {
-                    // Synchronous eviction already ran at line 121 — only
+                    // Synchronous eviction already ran above — only
                     // the refresh flag needs deferral (TIM-1518).
                     queue.markNeedsRefresh();
                   }
@@ -192,7 +197,7 @@ export function setupServerActions(): void {
         return wrapper._action;
       }
 
-      // revalidatePath was called but only for non-current paths —
+      // revalidatePath was called but only for other pages —
       // caches were already invalidated above, so no refresh is needed
       // unless a navigation ran while this action was in flight. That
       // navigation may have consumed a pre-mutation prefetch before the
@@ -200,7 +205,7 @@ export function setupServerActions(): void {
       // now on screen. The other branches catch this through
       // applyActionResult's epoch check; this one must check itself
       // (TIM-1483).
-      if (reval.paths) {
+      if (invalidated) {
         if (router && epoch && !router.isEpochCurrent(epoch)) {
           queue.markNeedsRefresh();
         }
@@ -212,11 +217,6 @@ export function setupServerActions(): void {
       // the queue until the refresh commits so the next action captures a
       // current epoch (codex on #1125).
       if (router && epoch) {
-        // TIM-1518: Evict synchronously so a navigation that supersedes
-        // this action's refresh cannot consume a pre-mutation prefetch.
-        // The deferred eviction in .then() ran as a microtask — after the
-        // superseding navigation had already consumed a stale entry.
-        router.evictStaleCaches();
         hold(
           router.applyActionResult(epoch).then(
             (applied) => {

package/src/client/browser-entry/post-hydration.ts

@@ -61,7 +61,17 @@ export function setupPostHydration({ router, navApiController }: PostHydrationOp
 
     const state = window.history.state;
     const scrollY = state && typeof state.scrollY === 'number' ? state.scrollY : 0;
-    void router.handlePopState(window.location.pathname + locationSearch(), scrollY);
+    // `popstate` does not say which way the user went, and timber writes no
+    // index into `history.state` to work it out: any `pushState` the app
+    // makes itself (nuqs, a shallow update) can overwrite it. So the render is
+    // tagged `navigation-traverse`. The Navigation API path (navigation-api.ts)
+    // is the one that knows back from forward (TIM-1471).
+    void router.handlePopState(
+      window.location.pathname + locationSearch(),
+      scrollY,
+      undefined,
+      'navigation-traverse'
+    );
   });
 
   // Keep scroll position up to date as the user scrolls.

package/src/client/browser-entry/router-init.ts

@@ -215,7 +215,12 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     queueMicrotask(() => router?.settleHandoffs());
 
     publishTree(tree, params, newNavState);
-    render(renderTree(tree, newNavState, params), null);
+    // No transition types: this is not a navigation, and a
+    // `<ViewTransition>` keyed on the router's types must not mistake a
+    // query-string sync for one. It is still a transition commit, though, so
+    // it claims whatever types a still-suspended navigation queued
+    // (design/37-navigation-api.md §"The claim window").
+    render(renderTree(tree, newNavState, params), null, []);
   }
 
   window.history.pushState = function (
@@ -294,7 +299,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     //
     // `_url` names the pending URL the router already published to its own
     // pending store before calling here; the transition has no use for it.
-    navigateTransition: (_url: string, owner: RenderOwner, perform, onCommit) => {
+    navigateTransition: (_url: string, owner: RenderOwner, types, perform, onCommit) => {
       return navigateTransition(
         owner,
         async () => {
@@ -330,6 +335,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
           };
         },
         render,
+        types,
         onCommit
       );
     },
@@ -364,9 +370,9 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
           _departingUrl: departingUrl,
         });
       },
-      onTraverse: async (url, scrollY, signal) => {
+      onTraverse: async (url, scrollY, signal, direction) => {
         // Back/forward — delegate to the router's popstate handler.
-        await router.handlePopState(url, scrollY, signal);
+        await router.handlePopState(url, scrollY, signal, direction);
       },
       onShallowNavigate: (destinationUrl: string) => {
         const search = new URL(destinationUrl).search;

package/src/client/history.ts

@@ -93,28 +93,6 @@ export class HistoryStack {
     return this.entries.has(routerUrlKey(url));
   }
 
-  delete(url: string): boolean {
-    return this.entries.delete(routerUrlKey(url));
-  }
-
-  /**
-   * Delete all entries whose pathname matches `pathname` (TIM-1465).
-   * Used by `invalidatePath` when the invalidation target has no search
-   * string — `/products` should evict `/products?page=1` too, because
-   * `revalidatePath('/products')` invalidates the route regardless of
-   * query.
-   */
-  deleteByPathname(pathname: string): void {
-    pathname = routerUrlKey(pathname);
-    for (const url of this.entries.keys()) {
-      const qIndex = url.indexOf('?');
-      const urlPathname = qIndex === -1 ? url : url.slice(0, qIndex);
-      if (urlPathname === pathname) {
-        this.entries.delete(url);
-      }
-    }
-  }
-
   /**
    * Evict every entry (TIM-1476). Called after a server action that
    * revalidated data — history entries are equally stale since they replay

package/src/client/index.ts

@@ -64,7 +64,8 @@ export { usePendingNavigation } from './use-pending-navigation.ts';
 export { useLinkStatus, LinkStatusContext } from './use-link-status.ts';
 export type { LinkStatus } from './use-link-status.ts';
 export { useRouter } from './use-router.ts';
-export type { AppRouterInstance } from './use-router.ts';
+export type { AppRouterInstance, NavigateOptions } from './use-router.ts';
+export type { NavigationTransitionType } from './router-types.ts';
 export { usePathname } from './use-pathname.ts';
 export { replaceUrl } from './shallow-url.ts';
 // useSearchParams removed from public exports — lives in next/navigation shim only.

package/src/client/link.tsx

@@ -94,6 +94,11 @@ export interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorEleme
    * Set to false for tabbed interfaces where content changes within a fixed layout.
    */
   scroll?: boolean;
+  /**
+   * Replace the current history entry instead of pushing a new one, so Back
+   * skips the page the link was on.
+   */
+  replace?: boolean;
   /**
    * Preserve search params from the current URL across navigation.
    *
@@ -117,6 +122,23 @@ export interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorEleme
    * Has no effect during SSR.
    */
   onNavigate?: OnNavigateHandler;
+  /**
+   * View transition types to add to this link's navigation, beside the
+   * router's own `navigation-forward`. A `<ViewTransition>` in the
+   * destination (or the page being left) can key its animation on them:
+   *
+   * ```tsx
+   * <Link href="/products/1" transitionTypes={['to-detail']}>…</Link>
+   * ```
+   *
+   * The router adds them in the transition that renders the destination. A
+   * `startTransition(() => { addTransitionType(t); router.push(href) })` in
+   * an `onClick` does not work in timber: the destination reaches React only
+   * after its fetch, in a later transition, and React hands types added in
+   * the click to whatever transition commits next — not to that one
+   * (design/37-navigation-api.md §"Transition types").
+   */
+  transitionTypes?: readonly string[];
   children?: ReactNode;
 }
 
@@ -475,10 +497,12 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
     href,
     prefetch,
     scroll,
+    replace,
     segmentParams,
     searchParams,
     preserveSearchParams,
     onNavigate,
+    transitionTypes,
     onClick: userOnClick,
     onMouseEnter: userOnMouseEnter,
     children,
@@ -620,7 +644,12 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
           if (committed) clear();
         };
         setIsPending(true);
-        const navigation = router.navigate(absoluteHref, { scroll: shouldScroll, onCommit });
+        const navigation = router.navigate(absoluteHref, {
+          scroll: shouldScroll,
+          replace,
+          transitionTypes,
+          onCommit,
+        });
         navigation.then(settle, (error: unknown) => {
           clear();
           // Rethrow, so a navigation error that the router did not already

package/src/client/navigation-api.ts

@@ -19,6 +19,7 @@
 
 import { isHardNavigating } from './navigation-root.tsx';
 import { stripRscCacheKey } from '../shared/rsc-cache-key.ts';
+import type { TraverseDirection } from './router-types.ts';
 
 // ─── Feature Detection ───────────────────────────────────────────
 
@@ -38,6 +39,29 @@ export function getNavigationApi(): Navigation | null {
   return window.navigation;
 }
 
+// ─── Traverse Direction ──────────────────────────────────────────
+
+/**
+ * Which way a traversal goes, as the view transition type the router adds
+ * for it (design/37-navigation-api.md §"Transition types").
+ *
+ * The Navigation API numbers the session's entries, so a traversal to a
+ * lower index is back and to a higher one is forward — including a jump of
+ * several entries (`history.go(-3)`). An index of -1 means the entry is not
+ * in this document's list, and then the direction is unknown.
+ */
+export function traverseDirection(
+  destinationIndex: number,
+  currentIndex: number | undefined
+): TraverseDirection {
+  if (currentIndex === undefined || currentIndex < 0 || destinationIndex < 0) {
+    return 'navigation-traverse';
+  }
+  if (destinationIndex < currentIndex) return 'navigation-back';
+  if (destinationIndex > currentIndex) return 'navigation-forward';
+  return 'navigation-traverse';
+}
+
 // ─── Navigation API Controller ───────────────────────────────────
 
 /**
@@ -60,9 +84,15 @@ export interface NavigationApiCallbacks {
 
   /**
    * Handle a traversal (back/forward button). The Navigation API intercepts
-   * the traversal and delegates to us for RSC replay/fetch.
+   * the traversal and delegates to us for RSC replay/fetch. `direction` is
+   * the view transition type the render adds — see `traverseDirection`.
    */
-  onTraverse: (url: string, scrollY: number, signal: AbortSignal) => Promise<void>;
+  onTraverse: (
+    url: string,
+    scrollY: number,
+    signal: AbortSignal,
+    direction: TraverseDirection
+  ) => Promise<void>;
 
   /**
    * Called when a shallow URL update is intercepted (e.g., nuqs with
@@ -231,6 +261,9 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
         | null
         | undefined;
       const scrollY = entryState && typeof entryState.scrollY === 'number' ? entryState.scrollY : 0;
+      // Read before intercept(): the current entry is still the one the
+      // user is leaving.
+      const direction = traverseDirection(event.destination.index, nav.currentEntry?.index);
 
       event.intercept({
         // Manual scroll — we handle scroll restoration ourselves
@@ -238,7 +271,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
         scroll: 'manual',
         focusReset: 'manual',
         async handler() {
-          await callbacks.onTraverse(url, scrollY, event.signal);
+          await callbacks.onTraverse(url, scrollY, event.signal, direction);
         },
       });
     } else if (event.navigationType === 'push' || event.navigationType === 'replace') {

package/src/client/navigation-root.tsx

@@ -71,8 +71,20 @@ export interface RenderedTree {
  * navigation, a revalidation, a popstate replay, a shallow search re-wrap —
  * and it is always a synchronous `startTransition` around `root.render`.
  * The production one is `createReactRoot().render`.
+ *
+ * `types` are the view transition types this render animates as
+ * (design/37-navigation-api.md §"Transition types"). They are added with
+ * `addTransitionType` inside that same `startTransition`, and nowhere else:
+ * React queues types per root and hands them to the next transition-only
+ * commit, so a type added in any other scope describes whichever tree commits
+ * next rather than this one (TIM-1463, TIM-1471). Empty for the shallow search
+ * re-wrap, which re-renders the displayed page rather than changing it.
  */
-export type NavigationRender = (element: ReactNode, publish: (() => void) | null) => void;
+export type NavigationRender = (
+  element: ReactNode,
+  publish: (() => void) | null,
+  types: readonly string[]
+) => void;
 
 // ─── Hard Navigation Guard ──────────────────────────────────────
 

package/src/client/navigation-transition.ts

@@ -224,6 +224,11 @@ export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOw
  * how `<Link>` keeps `isPending` up until the destination is on screen
  * without scheduling anything against React's lanes (TIM-1418).
  *
+ * `types` are the view transition types `render` adds beside the tree
+ * (design/37-navigation-api.md §"Transition types"). They are fixed before
+ * `perform` runs — what a render animates as is decided by the operation that
+ * started it, not by what the fetch returns.
+ *
  * `owner` is the `RenderOwner` for this render (TIM-1481). Supersession is
  * detected via `owner.outcome` (sync) and `owner.displaced` (async).
  * No module-level state; no globalThis singleton.
@@ -234,6 +239,7 @@ export function navigateTransition(
   owner: RenderOwner,
   perform: () => Promise<TransitionResult>,
   render: NavigationRender,
+  types: readonly string[],
   onCommit?: (outcome: CommitOutcome) => void
 ): Promise<void> {
   const superseded = () => new DOMException('Navigation superseded', 'AbortError');
@@ -267,13 +273,17 @@ export function navigateTransition(
       //
       // This is THE update that must not hide the departing page (TIM-1306);
       // `render` is the synchronous transition around `root.render`.
-      render(element, () => {
-        try {
-          commit();
-        } finally {
-          settleCommit('committed');
-        }
-      });
+      render(
+        element,
+        () => {
+          try {
+            commit();
+          } finally {
+            settleCommit('committed');
+          }
+        },
+        types
+      );
       // React may commit the tree before this settles — that is the point:
       // the destination reveals as React is able to render it
       // rather than waiting for the whole Flight stream. The await is here so

package/src/client/react-root.ts

@@ -19,7 +19,7 @@
  * `container` is `document` in production; tests pass an element.
  */
 
-import { createElement, startTransition, type ReactNode } from 'react';
+import { addTransitionType, createElement, startTransition, type ReactNode } from 'react';
 import { createRoot, hydrateRoot, type HydrationOptions, type Root } from 'react-dom/client';
 import { NavigationRoot, type NavigationRender, type RenderedTree } from './navigation-root.tsx';
 import type { TopLoaderConfig } from './top-loader.tsx';
@@ -55,13 +55,22 @@ export function createReactRoot(options: {
     hydrate(element, hydrationOptions) {
       root = hydrateRoot(container, rootElement({ element, publish: null }), hydrationOptions);
     },
-    render(element, publish) {
+    render(element, publish, types) {
       const target = (root ??= createRoot(container));
       // Synchronous, and returns nothing: an async callback would drop the
       // transition scope at its first await, and a returned thenable would
       // open an action scope that holds the commit until it settles
       // (TIM-1306, TIM-1307 — see client/navigation-transition.ts).
+      //
+      // The view transition types go in this scope and no other: React
+      // queues them on the root when the scope closes, and only if the root
+      // then has a transition pending — which `target.render` just made true.
+      // They are claimed by the next transition-only commit, so from here
+      // until this tree commits, another transition commit on the root can
+      // take them, and a superseding render merges its types with these
+      // (design/37-navigation-api.md §"The claim window", TIM-1471).
       startTransition(() => {
+        for (const type of types) addTransitionType(type);
         target.render(rootElement({ element, publish }));
       });
     },

package/src/client/router-effects.ts

@@ -146,8 +146,13 @@ export interface NavigationRecoveryDeps {
   /** The owner that holds the router right now, or null when idle. */
   currentOwner: () => RenderOwner | null;
   leaveSpaIfOwned: SpaExits['leaveSpaIfOwned'];
-  /** Replace the current entry with `url` — the router's own `navigate()`. */
-  navigate: (url: string) => Promise<void>;
+  /**
+   * Replace the current entry with `url` — the router's own `navigate()`,
+   * rendering with `types`: the view transition types of the render the
+   * redirect interrupted, so a redirected Back still animates as Back and a
+   * link's own `transitionTypes` survive the hop (TIM-1471).
+   */
+  navigate: (url: string, types: readonly string[]) => Promise<void>;
 }
 
 /**
@@ -181,13 +186,15 @@ export function createNavigationRecovery({
     error: unknown,
     owner: RenderOwner,
     url: string,
-    fromUrl: string
+    fromUrl: string,
+    /** The view transition types of the render that failed. */
+    types: readonly string[]
   ): Promise<boolean> {
     if (error instanceof RedirectError) {
       // Same ownership rule as leaving the SPA: a superseded navigation must
       // not steer the document to the destination it was abandoned for.
       if (currentOwner() !== owner) return true;
-      await navigate(error.redirectUrl);
+      await navigate(error.redirectUrl, types);
       return true;
     }
     // A server error, a non-RSC response and a version skew all end the same

package/src/client/router-pipeline.ts

@@ -81,6 +81,8 @@ export interface NavigationPipeline {
   renderViaTransition: (
     url: string,
     owner: RenderOwner,
+    /** The view transition types the render adds (`NavigationRender`). */
+    types: readonly string[],
     perform: () => Promise<NavigationPayload>,
     /** See `NavigationOptions.onCommit`. */
     onCommit?: (outcome: CommitOutcome) => void
@@ -183,6 +185,7 @@ export function createNavigationPipeline({
   async function renderViaTransition(
     url: string,
     owner: RenderOwner,
+    types: readonly string[],
     perform: () => Promise<NavigationPayload>,
     onCommit?: (outcome: CommitOutcome) => void
   ): Promise<void> {
@@ -203,6 +206,7 @@ export function createNavigationPipeline({
     await deps.navigateTransition(
       url,
       owner,
+      types,
       async (wrapPayload) => {
         const result = await perform();
         // Await the payload's *root row* — the same thing React would suspend

package/src/client/router-types.ts

@@ -16,11 +16,70 @@ import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
 import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
 import type { NavigationEpoch } from './router-lifecycle.ts';
 
+/**
+ * The view transition type the router adds to a render it hands React —
+ * exactly one per navigation, traversal, refresh or revalidation render,
+ * beside any `transitionTypes` the caller passed.
+ * A `<ViewTransition>` keys its animations on these
+ * (design/37-navigation-api.md §"Transition types", TIM-1471).
+ *
+ * - `navigation-forward` — a push or replace (`<Link>`, `router.push`,
+ *   a server action redirect, a non-shallow nuqs update), or a traversal
+ *   forward through history.
+ * - `navigation-back` — a traversal back through history.
+ * - `navigation-traverse` — a traversal whose direction the router cannot
+ *   know: the History API fallback, where `popstate` carries no index.
+ * - `refresh` — `router.refresh()`.
+ * - `revalidate` — the page re-rendered after a server action.
+ *
+ * The shallow search re-wrap and hydration add none. A server redirect the
+ * router follows keeps the types of the render it interrupted.
+ */
+export type NavigationTransitionType =
+  | 'navigation-forward'
+  | 'navigation-back'
+  | 'navigation-traverse'
+  | 'refresh'
+  | 'revalidate';
+
+/** The type a traversal adds: its direction, when the router knows it. */
+export type TraverseDirection = Extract<
+  NavigationTransitionType,
+  'navigation-forward' | 'navigation-back' | 'navigation-traverse'
+>;
+
+/** Options for `RouterInstance.refresh`. */
+export interface RefreshOptions {
+  /** See `NavigationOptions.onCommit`. */
+  onCommit?: (outcome: CommitOutcome) => void;
+  /**
+   * Why the page is being re-fetched, as the view transition type the render
+   * adds: `refresh` (the default) when the user asked, `revalidate` when a
+   * server action left the page to be re-fetched.
+   */
+  transitionType?: Extract<NavigationTransitionType, 'refresh' | 'revalidate'>;
+}
+
 export interface NavigationOptions {
   /** Set to false to prevent scroll-to-top on forward navigation */
   scroll?: boolean;
   /** Use replaceState instead of pushState (replaces current history entry) */
   replace?: boolean;
+  /**
+   * View transition types to add to this navigation, beside the router's own
+   * `navigation-forward`. They are added in the router's transition, the one
+   * that renders the destination — not in the caller's: React claims types
+   * per root at the next transition commit, and the destination is handed to
+   * React only after its fetch, so a type added around the `navigate()` call
+   * never reaches it (design/37-navigation-api.md §"Transition types").
+   */
+  transitionTypes?: readonly string[];
+  /**
+   * @internal The complete view transition types for this render, replacing
+   * `navigation-forward` + `transitionTypes`. Set only when the router
+   * follows a redirect, which keeps the types of the render it interrupted.
+   */
+  _renderTypes?: readonly string[];
   /**
    * Runs exactly once, when React commits this navigation's tree — or when
    * the navigation is abandoned (superseded or failed) and no such commit
@@ -97,6 +156,8 @@ export interface RouterDeps {
   navigateTransition: (
     pendingUrl: string,
     owner: RenderOwner,
+    /** The view transition types this render adds; see `NavigationRender`. */
+    types: readonly string[],
     perform: (
       wrapPayload: (
         payload: unknown,
@@ -184,9 +245,19 @@ export interface RouterInstance {
   /** Navigate to a new URL (forward navigation) */
   navigate(url: string, options?: NavigationOptions): Promise<void>;
   /** Full re-render of the current URL — no state tree sent */
-  refresh(options?: { onCommit?: (outcome: CommitOutcome) => void }): Promise<void>;
-  /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
-  handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;
+  refresh(options?: RefreshOptions): Promise<void>;
+  /**
+   * Handle a traversal (back/forward button). scrollY is read from the
+   * destination entry's state. `direction` is the transition type the
+   * render adds; it defaults to `navigation-traverse`, the type for a
+   * traversal whose direction is unknown.
+   */
+  handlePopState(
+    url: string,
+    scrollY?: number,
+    externalSignal?: AbortSignal,
+    direction?: TraverseDirection
+  ): Promise<void>;
   /** Whether a navigation is currently in flight */
   isPending(): boolean;
   /** The URL currently being navigated to, or null if idle */
@@ -237,10 +308,13 @@ export interface RouterInstance {
    */
   settleHandoffs(): void;
   /**
-   * Invalidate client caches for a path so the next navigation fetches
-   * fresh data. Called when `revalidatePath` targeted a non-current path.
+   * Make the next navigation a full render: the server re-renders every
+   * segment instead of skipping the shared layouts the client reports as
+   * mounted (TIM-1466). Called when `revalidatePath` named a page other
+   * than the current one — a layout that page shares with this one may now
+   * be stale, and the server cannot tell that from the state tree.
    */
-  invalidatePath(path: string): void;
+  suppressSegmentReuse(): void;
   /**
    * Evict all prefetch cache entries and history stack payloads (TIM-1476).
    * Called after a server action that revalidated data — the mutation may