@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/client/segment-cache.ts

@@ -1,18 +1,30 @@
 // Segment Cache — stores the mounted segment tree and prefetched payloads
 // See design/19-client-navigation.md for architecture details.
 
-import type { HeadElement } from './head';
+import type { PublishedParams } from '../shared/payload-root.ts';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
+import { createSingleflight } from '../cache/singleflight.ts';
 
 // ─── Types ───────────────────────────────────────────────────────
 
-/** A prefetched RSC result with optional head elements and segment metadata. */
+/** A prefetched RSC result with optional segment metadata. */
 export interface PrefetchResult {
   payload: unknown;
-  headElements: HeadElement[] | null;
+  /**
+   * Completion of the full Flight stream, when the prefetch is still decoding.
+   * Carried through to the navigation that consumes the entry so a decode
+   * failure reaches *that* navigation's recovery rather than dying with the
+   * prefetch (TIM-1275).
+   */
+  decodePromise?: Promise<void> | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
-  params?: Record<string, string | string[]> | null;
+  /**
+   * The params published beside `payload`, split off the same payload root.
+   * Carried so a consumed prefetch publishes the params of the tree it is
+   * about to render, and not the ones already on screen.
+   */
+  params?: PublishedParams | Promise<PublishedParams>;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
 }
@@ -24,20 +36,33 @@ export interface PrefetchResult {
 export interface SegmentNode {
   /** The segment's URL pattern (e.g., "/", "/dashboard", "/projects/[id]") */
   segment: string;
+  /**
+   * The segment's `app/` directory path, groups included (e.g. `/(browse)/feed`).
+   * Undefined for slot nodes and for servers that predate the field.
+   */
+  treePath?: string;
   /** The RSC flight payload for this segment (opaque to the cache) */
   payload: unknown;
-  /** Whether the segment is async (async layouts always re-render on navigation) */
-  isAsync: boolean;
+  /**
+   * Whether the segment/slot is request-dependent (calls getHeaders,
+   * getSearchParams, cookies, etc.). Request-dependent segments always
+   * re-render on navigation. For segments, this is still based on the
+   * AsyncFunction heuristic (to be replaced separately). For slots,
+   * this is taint-tracked via ALS.
+   */
+  isRequestDependent: boolean;
   /** Child segments keyed by segment path */
   children: Map<string, SegmentNode>;
-}
-
-/**
- * Serialized state tree sent via X-Timber-State-Tree header.
- * Only sync segments are included — async segments always re-render.
- */
-export interface StateTree {
-  segments: string[];
+  /** Parallel route slots keyed by slot path (e.g., "/@sidebar") */
+  slots?: Map<string, SegmentNode>;
+  /** Whether this slot's access.ts denied on its last render. */
+  denied?: boolean;
+  /**
+   * Content key for slot nodes — opaque string the server computed from
+   * owner parts, slot name, entry file, and slot params. Advertised back
+   * to the server so it can decide skips by key membership (TIM-1370).
+   */
+  contentKey?: string;
 }
 
 // ─── Segment Cache ───────────────────────────────────────────────
@@ -77,15 +102,33 @@ export class SegmentCache {
    * client can actually merge (i.e., segments whose cached element tree
    * contains an inner SegmentProvider the merger can splice into).
    *
+   * `treePaths` is collected UNFILTERED, unlike `segments` and `slots`. Those
+   * two answer "what may the server skip re-rendering?", so every reason a
+   * segment cannot be reused is a reason to leave it out. `treePaths` answers
+   * "what is mounted right now?" for interception scoping — a request-dependent
+   * layout is still on screen, and dropping it would silently narrow the scope
+   * the server sees and cancel a modal that should open (TIM-1282).
+   *
    * This is a performance optimization only, NOT a security boundary.
    * The server always runs all access.ts files regardless of the state tree.
    */
   serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
+    const slots: string[] = [];
+    const treePaths: string[] = [];
     if (this.root) {
       collectSyncSegments(this.root, segments, mergeableFilter);
+      collectSyncSlots(this.root, slots);
+      collectTreePaths(this.root, treePaths);
+    }
+    const tree: StateTree = { segments };
+    if (slots.length > 0) {
+      tree.slots = slots;
     }
-    return { segments };
+    if (treePaths.length > 0) {
+      tree.treePaths = treePaths;
+    }
+    return tree;
   }
 }
 
@@ -95,7 +138,7 @@ function collectSyncSegments(
   out: string[],
   mergeableFilter?: Set<string>
 ): void {
-  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {
+  if (!node.isRequestDependent && (!mergeableFilter || mergeableFilter.has(node.segment))) {
     out.push(node.segment);
   }
   for (const child of node.children.values()) {
@@ -103,17 +146,44 @@ function collectSyncSegments(
   }
 }
 
-// ─── Segment Tree Builder ────────────────────────────────────────
+/**
+ * Recursively collect the `app/` directory path of every mounted segment.
+ *
+ * Slots are not walked: a slot's own sub-tree can never own an intercepting
+ * slot's scope, because scopes are always ordinary segments (`interception.ts`
+ * derives one from the slot owner's ancestor chain).
+ */
+function collectTreePaths(node: SegmentNode, out: string[]): void {
+  if (node.treePath) out.push(node.treePath);
+  for (const child of node.children.values()) {
+    collectTreePaths(child, out);
+  }
+}
 
 /**
- * Segment metadata from the server, sent via X-Timber-Segments header.
- * Describes a rendered segment's path and whether it's async.
+ * Recursively collect content keys from cacheable slots.
+ *
+ * The server advertises a content key per slot on every render (TIM-1370),
+ * encoding the owner's URL parts, the slot name, the matched entry file,
+ * and the slot's params. The client stores this key and sends it back on
+ * the next navigation so the server can decide skips by key membership —
+ * no departing URL reconstruction needed.
  */
-export interface SegmentInfo {
-  path: string;
-  isAsync: boolean;
+function collectSyncSlots(node: SegmentNode, out: string[]): void {
+  if (node.slots) {
+    for (const slot of node.slots.values()) {
+      if (!slot.isRequestDependent && !slot.denied && slot.contentKey) {
+        out.push(slot.contentKey);
+      }
+    }
+  }
+  for (const child of node.children.values()) {
+    collectSyncSlots(child, out);
+  }
 }
 
+// ─── Segment Tree Builder ────────────────────────────────────────
+
 /**
  * Build a SegmentNode tree from flat segment metadata.
  *
@@ -129,77 +199,294 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   // Need at least a root segment to build a tree
   if (segments.length === 0) return undefined;
 
-  // Exclude the leaf (page) — pages always re-render on navigation.
-  // Only layouts are cached in the segment tree.
-  const layouts = segments.length > 1 ? segments.slice(0, -1) : segments;
+  // Separate slot entries from segment entries. Slots are attached to
+  // their parent segment node after the main chain is built.
+  const segmentEntries: SegmentInfo[] = [];
+  const slotEntries: SegmentInfo[] = [];
+  for (const info of segments) {
+    if (info.slot) {
+      slotEntries.push(info);
+    } else {
+      segmentEntries.push(info);
+    }
+  }
 
+  // Build the main segment chain.
   let root: SegmentNode | undefined;
   let parent: SegmentNode | undefined;
+  const nodeById = new Map<string, SegmentNode>();
 
-  for (const info of layouts) {
+  for (const info of segmentEntries) {
+    const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
-      segment: info.path,
+      segment: id,
+      treePath: info.treePath,
       payload: null,
-      isAsync: info.isAsync,
+      isRequestDependent: info.isRequestDependent,
       children: new Map(),
     };
 
+    nodeById.set(id, node);
+
     if (!root) {
       root = node;
     }
 
     if (parent) {
-      parent.children.set(info.path, node);
+      parent.children.set(id, node);
     }
 
     parent = node;
   }
 
+  // Attach slot entries to their parent segment nodes.
+  for (const slotInfo of slotEntries) {
+    const parentId = slotInfo.parentSegment;
+    const parentNode = parentId ? nodeById.get(parentId) : root;
+    if (!parentNode) continue;
+
+    const slotId = slotInfo.segmentId ?? slotInfo.path;
+    const slotNode: SegmentNode = {
+      segment: slotId,
+      payload: null,
+      isRequestDependent: slotInfo.isRequestDependent,
+      children: new Map(),
+      denied: slotInfo.denied,
+      contentKey: slotInfo.contentKey,
+    };
+
+    if (!parentNode.slots) {
+      parentNode.slots = new Map();
+    }
+    parentNode.slots.set(slotId, slotNode);
+  }
+
   return root;
 }
 
 // ─── Prefetch Cache ──────────────────────────────────────────────
 
-interface PrefetchEntry {
+interface ReadyEntry {
   result: PrefetchResult;
   expiresAt: number;
 }
 
+/** Sentinel value for negative cache entries (URL is not a route). */
+const NEGATIVE_ENTRY: PrefetchResult = Object.freeze({ payload: null });
+
+/**
+ * Timeout for the in-flight singleflight (TIM-1438). Per CLAUDE.md's
+ * singleflight rule: "Never write a coalescing Map without a timeout."
+ * A hung prefetch cannot block clicks or suppress hovers forever.
+ */
+const PREFETCH_SINGLEFLIGHT_TIMEOUT_MS = 5_000;
+
+/**
+ * Identifies a prefetched payload. A payload is addressed by *every* input that
+ * changes the server's answer, not by the destination alone.
+ *
+ * The server's answer for a destination depends on where the request came
+ * from — that is the whole mechanism behind intercepting routes, and it also
+ * drives slot-skip resolution. A prefetch issued from `/gallery` is a modal
+ * payload; the same URL prefetched from `/` is the full page. Keying on the
+ * destination alone let the first click after a hover be answered with
+ * whichever variant happened to be fetched (TIM-1265).
+ *
+ * `from` alone stopped being enough in TIM-1282. It is a pathname, and once
+ * interception scope comes from the rendered tree rather than the address, one
+ * pathname no longer names one source tree: `/photo/1` is the address both for
+ * a modal open over `(browse)` and for `(landing)`'s canonical page. A key
+ * without the scope hands the modal payload to the canonical page's click,
+ * which renders it without the server's scope check ever running.
+ *
+ * The two reads happen at different instants — `scope` is sampled at hover and
+ * again at click — which is why a tree that changed in between produces a
+ * *miss* and a refetch rather than a wrong hit.
+ */
+export interface PrefetchKey {
+  /** Destination URL — hash-less `pathname + search`, as navigate() fetches it. */
+  url: string;
+  /** Departing pathname — the `X-Timber-URL` the prefetch was issued with. */
+  from: string;
+  /**
+   * The rendered scope the prefetch was issued with — the `treePaths` half of
+   * `X-Timber-State-Tree`, joined. Empty when none crossed.
+   */
+  scope: string;
+}
+
+/**
+ * Compose the map key. Length-prefixed rather than delimiter-joined for the
+ * same reason `shared/rsc-cache-key.ts` is: any delimiter is forgeable by a
+ * value containing it, and a URL may contain any character a delimiter could.
+ */
+function prefetchMapKey(key: PrefetchKey): string {
+  return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
+}
+
+/**
+ * The `scope` half of a `PrefetchKey`, derived from the state tree that will
+ * actually be sent. Taking it from the header value rather than re-walking the
+ * cache is the point: the key varies by exactly what the request varies by.
+ */
+export function prefetchScopeOf(stateTree: StateTree | undefined): string {
+  return stateTree?.treePaths?.join('\u0000') ?? '';
+}
+
+/** Outcome of a prefetch flight — discriminated so NonRscResponse is a
+ *  success (stores a negative entry) rather than a rejection. */
+export type FlightOutcome = { kind: 'ready'; result: PrefetchResult } | { kind: 'non-route' };
+
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
  * 30 seconds. When a link is clicked, the prefetched payload is consumed
  * (moved to the history stack) and removed from this cache.
  *
+ * In-flight dedup (TIM-1438): concurrent fetches for the same key are
+ * coalesced by a `createSingleflight` instance. A hover starts a flight;
+ * a click for the same key joins it instead of issuing a duplicate. The
+ * singleflight enforces a 5-second timeout and cleans up automatically
+ * on settlement.
+ *
  * timber.js does NOT prefetch on viewport intersection — only explicit
  * hover on <Link prefetch> triggers a prefetch.
  */
 export class PrefetchCache {
   private static readonly TTL_MS = 30_000;
-  private entries = new Map<string, PrefetchEntry>();
+  private entries = new Map<string, ReadyEntry>();
+  private flights = createSingleflight({ timeoutMs: PREFETCH_SINGLEFLIGHT_TIMEOUT_MS });
+  private evictionGen = 0;
 
-  set(url: string, result: PrefetchResult): void {
-    this.entries.set(url, {
+  set(key: PrefetchKey, result: PrefetchResult): void {
+    this.entries.set(prefetchMapKey(key), {
       result,
       expiresAt: Date.now() + PrefetchCache.TTL_MS,
     });
   }
 
-  get(url: string): PrefetchResult | undefined {
-    const entry = this.entries.get(url);
+  get(key: PrefetchKey): PrefetchResult | undefined {
+    const mapKey = prefetchMapKey(key);
+    const entry = this.entries.get(mapKey);
     if (!entry) return undefined;
     if (Date.now() >= entry.expiresAt) {
-      this.entries.delete(url);
+      this.entries.delete(mapKey);
       return undefined;
     }
     return entry.result;
   }
 
+  /** True if a ready or negative entry exists for this key. */
+  has(key: PrefetchKey): boolean {
+    return this.get(key) !== undefined;
+  }
+
   /** Get and remove the entry (used when navigation consumes a prefetch) */
-  consume(url: string): PrefetchResult | undefined {
-    const result = this.get(url);
+  consume(key: PrefetchKey): PrefetchResult | undefined {
+    const result = this.get(key);
     if (result !== undefined) {
-      this.entries.delete(url);
+      this.entries.delete(prefetchMapKey(key));
     }
     return result;
   }
+
+  /**
+   * Fetch or coalesce with an in-flight fetch for this key (TIM-1438).
+   *
+   * Concurrent callers (hover + click, repeated hovers) get the same
+   * promise. On success the result is stored as a ready entry. On
+   * NonRscResponse a negative entry is stored and the outcome is
+   * `{ kind: 'non-route' }`. Other errors (network, version skew)
+   * reject — the singleflight cleans up the key and subsequent callers
+   * retry.
+   *
+   * The singleflight signal is passed to `doFetch` so a timed-out flight
+   * aborts the underlying fetch rather than leaving it running.
+   */
+  fetchOrCoalesce(
+    key: PrefetchKey,
+    doFetch: (signal: AbortSignal) => Promise<PrefetchResult>,
+    isNonRoute: (error: unknown) => boolean
+  ): Promise<FlightOutcome> {
+    // Capture the eviction generation before the flight starts. If an
+    // action evicts caches while this flight is in progress, the gen
+    // will have bumped and the stale result is discarded (TIM-1476).
+    const genAtStart = this.evictionGen;
+    return this.flights.do(prefetchMapKey(key), async (signal) => {
+      try {
+        const result = await doFetch(signal);
+        if (!signal.aborted && this.evictionGen === genAtStart) this.set(key, result);
+        return { kind: 'ready' as const, result };
+      } catch (err) {
+        if (isNonRoute(err)) {
+          if (!signal.aborted && this.evictionGen === genAtStart) this.setNegative(key);
+          return { kind: 'non-route' as const };
+        }
+        throw err;
+      }
+    });
+  }
+
+  /**
+   * Join an in-flight singleflight fetch if one exists for this key.
+   * Returns the in-flight promise or undefined. Used by the click path to
+   * coalesce with a hover prefetch without starting a new flight — when no
+   * flight exists, the click issues its own fetch with the navigation's
+   * abort signal so superseded navigations abort immediately (TIM-1438).
+   */
+  joinInflight(key: PrefetchKey): Promise<FlightOutcome> | undefined {
+    return this.flights.get(prefetchMapKey(key)) as Promise<FlightOutcome> | undefined;
+  }
+
+  /**
+   * Store a negative entry — the URL is not a route (non-RSC Content-Type).
+   *
+   * Keyed like every other entry even though "not a route" does not actually
+   * vary by departing URL: a source-independent negative would be a second
+   * keying rule to keep correct, and the only cost of the uniform one is a
+   * repeated fetch for a link hovered from a second page.
+   */
+  setNegative(key: PrefetchKey): void {
+    this.set(key, NEGATIVE_ENTRY);
+  }
+
+  /** Check if the entry is a negative cache entry (URL is not a route). */
+  isNegative(key: PrefetchKey): boolean {
+    return this.get(key) === NEGATIVE_ENTRY;
+  }
+
+  /**
+   * Invalidate all entries whose destination URL matches (TIM-1454).
+   * Used by `revalidatePath` on a non-current route so the next navigation
+   * fetches fresh data instead of replaying a stale prefetch.
+   */
+  invalidateUrl(url: string): void {
+    for (const [mapKey] of this.entries) {
+      if (mapKey.endsWith(':' + url)) {
+        this.entries.delete(mapKey);
+      }
+    }
+  }
+
+  /**
+   * Evict all ready entries and fence in-flight singleflights (TIM-1476).
+   * Called after a server action that revalidated data — the mutation may
+   * affect any route, not just the paths the server named. In-flight
+   * singleflights are not aborted (they may carry post-mutation data),
+   * but their results are discarded if they complete after eviction:
+   * `fetchOrCoalesce` captures the generation before the flight and
+   * skips the store when it has been bumped.
+   *
+   * Consumers that join an in-flight flight via `joinInflight` must
+   * check `getEvictionGen()` before and after the await: if the gen
+   * changed, the result predates the eviction and must be discarded
+   * (codex on #1131 round 2).
+   */
+  clearReady(): void {
+    this.entries.clear();
+    this.evictionGen++;
+  }
+
+  getEvictionGen(): number {
+    return this.evictionGen;
+  }
 }

package/src/client/segment-context.ts

@@ -60,10 +60,13 @@ export function SegmentProvider({
 }: SegmentProviderProps) {
   const value = useMemo(
     () => ({ segments, parallelRouteKeys }),
-    // segments and parallelRouteKeys are static per layout — they don't change
-    // across navigations. The layout's position in the tree is fixed.
-    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout
-    [segments.join('/'), parallelRouteKeys.join(',')]
+    // segments and parallelRouteKeys are static per layout — the layout's
+    // position in the tree is fixed. The arrays are used directly as deps
+    // (React Compiler requires simple expressions here). Referential stability
+    // of the context value doesn't matter: every consumer
+    // (useSelectedLayoutSegment/useSelectedLayoutSegments) also calls
+    // usePathname(), so it re-renders on every navigation regardless.
+    [segments, parallelRouteKeys]
   );
   return createElement(SegmentContext.Provider, { value }, children);
 }

package/src/client/segment-outlet.tsx

@@ -0,0 +1,96 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Each layout in the segment tree is wrapped with a SegmentOutlet that:
+ * 1. Knows its segment path (prop from the server)
+ * 2. Reads from SegmentUpdateContext for partial navigation updates
+ * 3. Reads from — and, at commit, writes to — the router's slot content
+ *    cache, so a skipped parallel slot keeps showing what it last committed
+ *
+ * On full navigation: receives new children via props and renders them.
+ * On partial navigation (this segment skipped): the context map has no entry
+ * for this path, so the outlet renders its children — which, because the
+ * router re-wraps the *retained* tree, are the same elements as before,
+ * preserving layout state.
+ * On partial navigation (this segment updated): the context map has content
+ * for this path, so the outlet renders the update.
+ * On a skipped parallel slot (`skip=true`, children null): the outlet renders
+ * the content it last committed for this path.
+ *
+ * Uses React context instead of useSyncExternalStore to stay compatible
+ * with concurrent rendering (transitions). All outlets re-render when the
+ * context value changes, but each bails out quickly if its segment has
+ * no update — same approach as Next.js LayoutRouter.
+ *
+ * Render is a pure read. The only write — recording committed slot content —
+ * happens in a layout effect, so a render React throws away (a superseded
+ * transition, a Suspense retry) cannot poison what a later `skip=true`
+ * resolves to (TIM-1423). See client/slot-content-cache-context.ts.
+ *
+ * Security: performance optimization only. The server always runs all
+ * access.ts files regardless of segment skipping.
+ * See design/13-security.md §"State tree manipulation".
+ */
+
+'use client';
+
+import { useContext, useLayoutEffect, type ReactNode } from 'react';
+import { SegmentUpdateContext } from './segment-update-context.ts';
+import { SlotContentCacheContext } from './slot-content-cache-context.ts';
+
+export interface SegmentOutletProps {
+  /**
+   * Unique identifier for this segment. For normal segments this is the
+   * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
+   * group name (e.g., "/(marketing)") to distinguish siblings that share
+   * the same urlPath. For slots this includes the slot name (e.g., "/@sidebar").
+   * Must match the segmentId used in state-tree-diff.ts.
+   */
+  segmentPath: string;
+
+  /** The segment's React subtree (layout + inner content). */
+  children: ReactNode;
+
+  /**
+   * When true, the outlet renders the content it last committed for this
+   * path instead of `children`. Used for skipped parallel route slots — the
+   * server sends an empty SegmentOutlet with skip=true, and the client keeps
+   * the previously committed slot content.
+   */
+  skip?: boolean;
+}
+
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * Resolution order, all reads:
+ *   1. An update in SegmentUpdateContext for this path → render it.
+ *   2. `skip` → render the committed content for this path (null if none —
+ *      a fresh outlet with nothing committed yet renders empty and is fully
+ *      rendered on the next navigation).
+ *   3. Otherwise → render `children`.
+ *
+ * Whatever a non-skip render resolves to is recorded once React commits it.
+ * A skip render records nothing: it displayed the cache, it did not add to it.
+ */
+export function SegmentOutlet({ segmentPath, children, skip }: SegmentOutletProps) {
+  const updates = useContext(SegmentUpdateContext);
+  const cache = useContext(SlotContentCacheContext);
+
+  const update = updates.get(segmentPath);
+  const hasUpdate = update !== undefined;
+  const content: ReactNode = hasUpdate
+    ? update
+    : skip
+      ? (cache?.get(segmentPath) ?? null)
+      : children;
+
+  // Commit-time write. `hasUpdate || !skip` is "this render brought its own
+  // content" — the one case where the cache learns something new.
+  const record = hasUpdate || !skip;
+  useLayoutEffect(() => {
+    if (record && cache !== null) cache.set(segmentPath, content);
+  }, [record, cache, segmentPath, content]);
+
+  return content;
+}

package/src/client/segment-update-context.ts

@@ -0,0 +1,23 @@
+/**
+ * SegmentUpdateContext — React context for partial navigation updates.
+ *
+ * During partial navigation (server skips unchanged sync layouts), the
+ * router builds a Map of segment path → ReactNode updates and passes it
+ * as the context value. Mounted SegmentOutlet components read from this
+ * context to decide whether to render the update or their cached content.
+ *
+ * Singleton across bundler-duplicated chunks via `createGlobalContext`.
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { createGlobalContext } from './global-context.ts';
+
+export const EMPTY_SEGMENT_UPDATES = new Map<string, ReactNode>();
+
+export const SegmentUpdateContext = createGlobalContext<Map<string, ReactNode>>(
+  '__timber_segment_update_ctx',
+  EMPTY_SEGMENT_UPDATES
+);

package/src/client/shallow-url.ts

@@ -0,0 +1,22 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+
+import { getNavigationApi } from './navigation-api.ts';
+
+export function replaceUrl(url: string): void {
+  const nav = getNavigationApi();
+  if (nav) {
+    nav.navigate(url, {
+      history: 'replace',
+      info: { shallow: true },
+    });
+  } else {
+    history.replaceState(history.state, '', url);
+  }
+}