@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/client/link.tsx

@@ -14,14 +14,62 @@
 // Typed Link: design/09-typescript.md §"Typed Link"
 // - href validated against known routes (via codegen overloads, not runtime)
 // - params prop typed per-route, URL interpolated at runtime
-// - searchParams prop serialized via SearchParamsDefinition
+// - searchParams prop is a query string (from `definition.buildSearchParams()`)
+//   or a plain object whose values are String()-coerced
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
-import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
-import { LinkStatusProvider } from './link-status-provider.js';
-import { getRouterOrNull } from './router-ref.js';
+import {
+  useRef,
+  useState,
+  type AnchorHTMLAttributes,
+  type ReactNode,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
+import type { LinkFunction } from './index.ts';
+import { classifyUrlSegment, type UrlSegment } from '../routing/segment-classify.ts';
+import {
+  validateNavigationHref as validateLinkHref,
+  isInternalHref,
+} from '../shared/href-validation.ts';
+import { LinkStatusContext } from './use-link-status.ts';
+import { getRouterOrNull } from './router-ref.ts';
+import { getSsrData } from './ssr-data.ts';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.ts';
+import { getLinkCodec } from '../params/codec-registry.ts';
+import { locationSearch } from './location-search.ts';
+import { stripRscCacheKey } from '../shared/rsc-cache-key.ts';
+import type { LinkStatus } from './use-link-status.ts';
+
+const LINK_PENDING: LinkStatus = { isPending: true };
+const LINK_IDLE: LinkStatus = { isPending: false };
+
+// ─── Current Search Params ────────────────────────────────────────
+
+/**
+ * Read the current URL's search string without requiring a React hook.
+ * On the client, reads window.location.search. During SSR, reads the raw
+ * query string from the request context (getSsrData) — the same `''` or
+ * `?…` shape, preserving repeated keys (`?tag=a&tag=b`) so the
+ * server-rendered href matches what the hydrated client rebuilds from the
+ * address bar (TIM-1428). Returns empty string if unavailable.
+ */
+function getCurrentSearch(): string {
+  if (typeof window !== 'undefined') return locationSearch();
+  return getSsrData()?.search ?? '';
+}
+
+/** Native in-page scrolling needs neither an RSC navigation nor a prefetch. */
+function isNativeFragmentLink(anchor: HTMLAnchorElement): boolean {
+  // Default browser navigation follows the rendered anchor, which may differ
+  // from a freshly resolved preserveSearchParams URL after a shallow update.
+  const href = anchor.href;
+  const hashIndex = href.indexOf('#');
+  // Compare browser-serialized URLs, excluding only fragments. URL.hash and
+  // URL.search erase the distinction between absent and explicitly empty
+  // delimiters, but '/current' and '/current?' are different documents.
+  return hashIndex !== -1 && href.slice(0, hashIndex) === window.location.href.split('#', 1)[0];
+}
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -33,8 +81,12 @@ export type OnNavigateHandler = (e: OnNavigateEvent) => void;
 
 /**
  * Base props shared by all Link variants.
+ *
+ * Exported so the public `LinkFunction` interface (declared in
+ * `./index.ts`, where module augmentation can merge into it) can
+ * compose this without duplication.
  */
-interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+export interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
   /** Prefetch the RSC payload on hover */
   prefetch?: boolean;
   /**
@@ -42,6 +94,25 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
    * 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.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Useful for route-group gating where a search param (e.g. `?private=access`)
+   * must persist across internal navigations. The target href's own search params
+   * always take precedence over preserved ones.
+   *
+   * During SSR, reads search params from the request context. On the client,
+   * reads from the current URL and updates reactively when the URL changes.
+   */
+  preserveSearchParams?: true | string[];
   /**
    * Called before client-side navigation commits. Call `e.preventDefault()`
    * to cancel the default navigation — the caller is then responsible for
@@ -51,84 +122,103 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
    * Has no effect during SSR.
    */
   onNavigate?: OnNavigateHandler;
-  children?: ReactNode;
-}
-
-/**
- * Link with a fully-resolved string href.
- * When using a string href with params already interpolated,
- * the params prop is not available.
- */
-export interface LinkPropsWithHref extends LinkBaseProps {
-  href: string;
-  params?: never;
   /**
-   * Typed search params — serialized via the route's SearchParamsDefinition.
-   * Mutually exclusive with an inline query string in href.
+   * 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").
    */
-  searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-  };
+  transitionTypes?: readonly string[];
+  children?: ReactNode;
 }
 
+// ─── Typed Link Props ────────────────────────────────────────────
+
 /**
- * Link with a route pattern + params for interpolation.
- * e.g. <Link href="/products/[id]" params={{ id: "123" }}>
- *      <Link href="/products/[id]" params={{ id: 123 }}>
+ * Widen server-side string params to string | number for Link convenience.
+ * Exported for use by codegen-generated overloads.
  */
-export interface LinkPropsWithParams extends LinkBaseProps {
-  /** Route pattern with dynamic segments (e.g. "/products/[id]") */
-  href: string;
-  /**
-   * Dynamic segment values to interpolate into the href.
-   * Single dynamic segments accept string | number (numbers are stringified).
-   * Catch-all segments accept string[].
-   */
-  params: Record<string, string | number | string[]>;
-  /**
-   * Typed search params — serialized via the route's SearchParamsDefinition.
-   */
-  searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-  };
-}
+export type LinkSegmentParams<T> = {
+  [K in keyof T]: [string] extends [T[K]] ? string | number : T[K];
+};
 
-export type LinkProps = LinkPropsWithHref | LinkPropsWithParams;
+// ─── External Href Types ─────────────────────────────────────────
+//
+// `ExternalHref` and the public `LinkFunction` interface live in
+// `./index.ts` rather than this file. They MUST be originally declared
+// in the same module that the codegen augments (`@timber-js/app/client`)
+// so that codegen-generated per-route call signatures merge with the
+// same interface that types the `Link` constant. Re-exporting an
+// interface via `export type {}` does NOT participate in module
+// augmentation merging — only originally-declared interfaces do.
+// See TIM-624.
+
+// ─── searchParams prop shapes ────────────────────────────────────
+//
+// Two shapes, discriminated at runtime by `typeof === 'string'`:
+//
+//   1. Codec-aware (preferred) — a query string built from a definition:
+//        searchParams={productParams.buildSearchParams({ page: 2, search: 'boots' })}
+//      `buildSearchParams` applies each codec, honours `withUrlKey` aliases,
+//      and omits values equal to their default. It is typed `Partial<T>` at
+//      the call site, so the definition supplies the type checking.
+//
+//   2. Plain object (escape hatch) — every value is String()-coerced:
+//        searchParams={{ ref: 'email' }}
+//      No codecs, no aliases. This is for one-off params that have no
+//      definition. Passing a *definition's* keys this way is a mistake the
+//      types cannot catch: `{ search: 'x' }` emits `?search=x`, where the
+//      definition would emit `?q=x`. Prefer (1) whenever a definition exists.
+//
+// Why a STRING and not a URLSearchParams: a Link is routinely rendered by a
+// Server Component, so this prop crosses the RSC Flight boundary before the
+// client Link runs. `URLSearchParams` is iterable, and React serializes any
+// iterable as an array — so the prop arrived as `[['pg','2'], …]`, fell into
+// the plain-object branch, and rendered `?0=pg&0=2`. Strings survive Flight
+// unchanged. (Codex P1 on PR #1021; reproduced against a live dev server.)
+//
+// TIM-1343 removed the third shape — a flat values object resolved against a
+// runtime registry keyed by href. It required scanning a `params.ts`
+// convention file, a generated registry module, and eager imports of every
+// route's definition into all three entries, to save one `.buildSearchParams`
+// call. See design/23-search-params.md §"Link Integration".
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ParamValue = string | number | string[] | { toString(): string; [key: string]: any };
 
-// ─── Dangerous URL Scheme Detection ──────────────────────────────
+type LinkSearchParamsProp = string | Record<string, unknown>;
 
 /**
- * Reject dangerous URL schemes that could execute script.
- * Security: design/13-security.md § Link scheme injection (test #9)
+ * Runtime-only loose props used internally by the Link implementation.
+ * Not exposed to callers — the public API uses LinkFunction.
  */
-const DANGEROUS_SCHEMES = /^\s*(javascript|data|vbscript):/i;
-
-export function validateLinkHref(href: string): void {
-  if (DANGEROUS_SCHEMES.test(href)) {
-    throw new Error(
-      `<Link> received a dangerous href: "${href}". ` +
-        'javascript:, data:, and vbscript: URLs are not allowed.'
-    );
-  }
+interface LinkRuntimeProps extends LinkBaseProps {
+  href: string;
+  segmentParams?: Record<string, ParamValue>;
+  searchParams?: LinkSearchParamsProp;
 }
 
-// ─── Internal Link Detection ─────────────────────────────────────
+// Legacy exports for backward compat (used by buildLinkProps, tests, etc.)
+export type LinkPropsWithHref = LinkBaseProps & {
+  href: string;
+  segmentParams?: never;
+  searchParams?: LinkSearchParamsProp;
+};
+export type LinkPropsWithParams = LinkRuntimeProps & {
+  segmentParams: Record<string, ParamValue>;
+};
+export type LinkProps = LinkRuntimeProps;
 
-/** Returns true if the href is an internal path (not an external URL) */
-export function isInternalHref(href: string): boolean {
-  // Relative paths, root-relative paths, and hash links are internal
-  if (href.startsWith('/') || href.startsWith('#') || href.startsWith('?')) {
-    return true;
-  }
-  // Anything with a protocol scheme is external
-  if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
-    return false;
-  }
-  // Bare relative paths (e.g., "dashboard") are internal
-  return true;
-}
+export { validateLinkHref, isInternalHref };
 
 // ─── URL Interpolation ──────────────────────────────────────────
 
@@ -141,57 +231,114 @@ export function isInternalHref(href: string): boolean {
  * - [...param]       → catch-all (joined with /)
  * - [[...param]]     → optional catch-all (omitted if undefined/empty)
  */
-export function interpolateParams(
-  pattern: string,
-  params: Record<string, string | number | string[]>
-): string {
-  return (
-    pattern
-      .replace(
-        /\[\[\.\.\.(\w+)\]\]|\[\.\.\.(\w+)\]|\[(\w+)\]/g,
-        (_match, optionalCatchAll, catchAll, single) => {
-          if (optionalCatchAll) {
-            const value = params[optionalCatchAll];
-            if (value === undefined || (Array.isArray(value) && value.length === 0)) {
-              return '';
-            }
-            const segments = Array.isArray(value) ? value : [value];
-            return segments.map(encodeURIComponent).join('/');
-          }
+/**
+ * Parse a route pattern's path portion into classified segments.
+ * Exported for testing. Uses the shared character-based classifier.
+ */
+export function parseSegments(pattern: string): UrlSegment[] {
+  return pattern.split('/').filter(Boolean).map(classifyUrlSegment);
+}
 
-          if (catchAll) {
-            const value = params[catchAll];
-            if (value === undefined) {
-              throw new Error(
-                `<Link> missing required catch-all param "${catchAll}" for pattern "${pattern}".`
-              );
-            }
-            const segments = Array.isArray(value) ? value : [value];
-            if (segments.length === 0) {
-              throw new Error(
-                `<Link> catch-all param "${catchAll}" must have at least one segment for pattern "${pattern}".`
-              );
-            }
-            return segments.map(encodeURIComponent).join('/');
-          }
+/**
+ * Resolve a single classified segment into its string representation.
+ * Returns null for optional catch-all with no value (filtered out before join).
+ *
+ * When schema codecs are registered (via virtual:timber-schema), uses
+ * codec.serialize() for URL construction instead of plain String().
+ */
+function resolveSegment(
+  seg: UrlSegment,
+  params: Record<string, ParamValue>,
+  pattern: string
+): string | null {
+  switch (seg.kind) {
+    case 'static':
+      return seg.value;
+
+    case 'optional-catch-all': {
+      const value = params[seg.name];
+      if (value === undefined || (Array.isArray(value) && value.length === 0)) {
+        return null;
+      }
+      const codec = getLinkCodec(`[[...${seg.name}]]`);
+      if (codec) {
+        const serialized = codec.serialize(value);
+        if (!serialized) return null;
+        // Codec returns a path string (may contain '/') — encode each segment
+        return serialized.split('/').map(encodeURIComponent).join('/');
+      }
+      const segments = Array.isArray(value) ? value : [value];
+      return segments.map(encodeURIComponent).join('/');
+    }
 
-          // single dynamic segment
-          const value = params[single];
-          if (value === undefined) {
-            throw new Error(`<Link> missing required param "${single}" for pattern "${pattern}".`);
-          }
-          if (Array.isArray(value)) {
-            throw new Error(
-              `<Link> param "${single}" expected a string but received an array for pattern "${pattern}".`
-            );
-          }
-          // Accept numbers — coerce to string for URL interpolation
-          return encodeURIComponent(String(value));
+    case 'catch-all': {
+      const value = params[seg.name];
+      if (value === undefined) {
+        throw new Error(
+          `<Link> missing required catch-all param "${seg.name}" for pattern "${pattern}".`
+        );
+      }
+      const codec = getLinkCodec(`[...${seg.name}]`);
+      if (codec) {
+        const serialized = codec.serialize(value);
+        if (!serialized) {
+          throw new Error(
+            `<Link> catch-all param "${seg.name}" codec returned null for pattern "${pattern}".`
+          );
         }
-      )
-      // Clean up trailing slash from empty optional catch-all
-      .replace(/\/+$/, '') || '/'
-  );
+        // Codec returns a path string (may contain '/') — encode each segment
+        return serialized.split('/').map(encodeURIComponent).join('/');
+      }
+      const segments = Array.isArray(value) ? value : [value];
+      if (segments.length === 0) {
+        throw new Error(
+          `<Link> catch-all param "${seg.name}" must have at least one segment for pattern "${pattern}".`
+        );
+      }
+      return segments.map(encodeURIComponent).join('/');
+    }
+
+    case 'dynamic': {
+      const value = params[seg.name];
+      if (value === undefined) {
+        throw new Error(`<Link> missing required param "${seg.name}" for pattern "${pattern}".`);
+      }
+      if (Array.isArray(value)) {
+        throw new Error(
+          `<Link> param "${seg.name}" expected a string but received an array for pattern "${pattern}".`
+        );
+      }
+      const codec = getLinkCodec(`[${seg.name}]`);
+      const str = codec ? (codec.serialize(value) ?? String(value)) : String(value);
+      const encoded = encodeURIComponent(str);
+      const prefix = seg.prefix ?? '';
+      const suffix = seg.suffix ?? '';
+      return prefix + encoded + suffix;
+    }
+  }
+}
+
+/**
+ * Split a URL pattern into the path portion and any trailing ?query/#hash suffix.
+ * Uses URL parsing for correctness rather than manual index arithmetic.
+ */
+function splitPatternSuffix(pattern: string): [path: string, suffix: string] {
+  if (!pattern.includes('?') && !pattern.includes('#')) {
+    return [pattern, ''];
+  }
+  const url = new URL(pattern, 'http://x');
+  const suffix = url.search + url.hash;
+  const path = pattern.slice(0, pattern.length - suffix.length);
+  return [path, suffix];
+}
+
+export function interpolateParams(pattern: string, params: Record<string, ParamValue>): string {
+  const [pathPart, suffix] = splitPatternSuffix(pattern);
+
+  const resolved = parseSegments(pathPart)
+    .map((seg) => resolveSegment(seg, params, pattern))
+    .filter((s): s is string => s !== null);
+  return ('/' + resolved.join('/') || '/') + suffix;
 }
 
 // ─── Resolve Href ───────────────────────────────────────────────
@@ -201,16 +348,41 @@ export function interpolateParams(
  *
  * Handles:
  * - params interpolation into route patterns
- * - searchParams serialization via SearchParamsDefinition
+ * - searchParams serialization (see the two shapes documented above)
  * - Validation that searchParams and inline query strings are exclusive
  */
+/**
+ * Tolerate a leading '?'. `buildSearchParams()` never emits one, but callers
+ * hand-rolling a query string reasonably might, and silently producing
+ * `?%3Fa=b` for it would be a worse failure than accepting both.
+ */
+function stripLeadingQuestionMark(qs: string): string {
+  return qs.startsWith('?') ? qs.slice(1) : qs;
+}
+
+/**
+ * Escape-hatch serialization for a plain object: String()-coerce every
+ * value, append arrays as repeated keys, skip null/undefined.
+ *
+ * Deliberately codec-free and alias-free — see the shape docs above.
+ */
+function coerceToQueryString(values: Record<string, unknown>): string {
+  const usp = new URLSearchParams();
+  for (const [key, val] of Object.entries(values)) {
+    if (val === undefined || val === null) continue;
+    if (Array.isArray(val)) {
+      for (const item of val) usp.append(key, String(item));
+    } else {
+      usp.set(key, String(val));
+    }
+  }
+  return usp.toString();
+}
+
 export function resolveHref(
   href: string,
-  params?: Record<string, string | number | string[]>,
-  searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-  }
+  params?: Record<string, ParamValue>,
+  searchParams?: LinkSearchParamsProp
 ): string {
   let resolvedPath = href;
 
@@ -229,7 +401,16 @@ export function resolveHref(
       );
     }
 
-    const qs = searchParams.definition.serialize(searchParams.values);
+    // A string is already a serialized query (from
+    // `definition.buildSearchParams()`), so it passes through untouched.
+    // `typeof` is the only discriminator that survives the RSC Flight
+    // boundary — see the shape docs above for what happened when this was
+    // an object test.
+    const qs =
+      typeof searchParams === 'string'
+        ? stripLeadingQuestionMark(searchParams)
+        : coerceToQueryString(searchParams);
+
     if (qs) {
       resolvedPath = `${resolvedPath}?${qs}`;
     }
@@ -250,11 +431,8 @@ interface LinkOutputProps {
  */
 export function buildLinkProps(
   props: Pick<LinkPropsWithHref, 'href'> & {
-    params?: Record<string, string | number | string[]>;
-    searchParams?: {
-      definition: SearchParamsDefinition<Record<string, unknown>>;
-      values: Record<string, unknown>;
-    };
+    params?: Record<string, ParamValue>;
+    searchParams?: LinkSearchParamsProp;
   }
 ): LinkOutputProps {
   const resolvedHref = resolveHref(props.href, props.params, props.searchParams);
@@ -302,24 +480,109 @@ function shouldInterceptClick(
  * navigation via the router. No global event delegation — each Link owns
  * its own click handling.
  *
- * Supports typed routes via codegen overloads. At runtime:
- * - `params` prop interpolates dynamic segments in the href pattern
+ * Supports typed routes via the Routes interface (populated by codegen).
+ * At runtime:
+ * - `segmentParams` prop interpolates dynamic segments in the href pattern
  * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
+ *
+ * Typed via the LinkFunction callable interface. The base call signature
+ * forbids segmentParams; per-route signatures are added by codegen via
+ * interface merging. See TIM-624.
  */
-export function Link({
-  href,
-  prefetch,
-  scroll,
-  params,
-  searchParams,
-  onNavigate,
-  onClick: userOnClick,
-  onMouseEnter: userOnMouseEnter,
-  children,
-  ...rest
-}: LinkProps) {
-  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
-  const internal = isInternalHref(resolvedHref);
+// Cast to LinkFunction — the callable interface provides the public type,
+// but the implementation destructures LinkRuntimeProps internally.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const Link: LinkFunction = function LinkImpl(props: any) {
+  const {
+    href,
+    prefetch,
+    scroll,
+    replace,
+    segmentParams,
+    searchParams,
+    preserveSearchParams,
+    onNavigate,
+    transitionTypes,
+    onClick: userOnClick,
+    onMouseEnter: userOnMouseEnter,
+    children,
+    ...rest
+  } = props as LinkRuntimeProps;
+  const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
+
+  // ─── Per-link pending state ─────────────────────────────────────────
+  // Local `useState`, deliberately NOT `useTransition` (TIM-1307).
+  //
+  // Either shape keeps the re-render local — the state lives on this Link's
+  // own fiber, so no sibling link is touched. The difference is what wrapping
+  // `router.navigate()` in a transition does to the REST of the app: returning
+  // a thenable from `startTransition` hands it to `ReactSharedInternals.S`,
+  // which calls react-dom's `entangleAsyncAction`. That opens an action scope
+  // whose `currentEntangledLane` collects every transition update scheduled
+  // while it is open — including the router's `root.render` of `NavigationRoot`, which is a
+  // fully synchronous `startTransition` in a different component — and
+  // rendering that lane suspends on `currentEntangledActionThenable` until the
+  // action settles. `navigateTransition` awaits `decodePromise`, so a Link
+  // navigation used to commit only after the whole Flight stream had decoded,
+  // while `useRouter().push()` committed as soon as React could render it.
+  //
+  // Two commit-timing regimes, and the slower one was the dominant path: no
+  // streaming reveal, and the TIM-1301 publish (address bar, segment cache,
+  // `timber:navigation-end`) waited for full decode. Not opening an action
+  // scope is what collapses them into one.
+  //
+  // `isPending` runs from the click until BOTH `router.navigate()` has settled
+  // (after `decodePromise` — the lifecycle the router's pending store and the
+  // TopLoader use) AND the navigation's `onCommit` has fired. The second
+  // condition is what keeps the flag honest: the promise resolves on decode,
+  // and a destination with a pending Suspense boundary is still off screen
+  // then. A clear scheduled at that point — urgent or in its own transition —
+  // can commit ahead of the suspended tree, so the link flashes idle for a
+  // frame while the old page is still showing (TIM-1418). Wrapping the clear
+  // in `startTransition` was tried: it only holds when both updates share a
+  // lane, and React assigns lanes per event, so the decode-time clear and the
+  // click-time `root.render` never do. (Next.js gets the shared lane because
+  // it hands React the tree in the click event; timber fetches first.) The
+  // commit itself is the only signal that cannot beat the commit, and it is
+  // the router's to give: `onCommit` fires exactly once, on the commit or
+  // when the navigation is abandoned — superseded or failed — so the link
+  // can never be left pending for a commit that will not come.
+  //
+  // Order is not fixed: a destination that does not suspend commits before
+  // decode finishes (streaming reveal), so whichever of settle/commit comes
+  // second clears.
+  //
+  // `clickSeq` guards the same-link double click: the first navigation is
+  // superseded (its promise RESOLVES — `runNavigation` swallows AbortErrors —
+  // and its `onCommit` fires) while the second is still in flight, and only
+  // the newest click for this link may clear its flag. Written on click and
+  // nowhere else, so there is no reset for a settle handler to race.
+  const [isPending, setIsPending] = useState(false);
+  const clickSeq = useRef(0);
+  const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
+
+  // Preserve search params from the current URL when requested.
+  // Read via getCurrentSearch() rather than a hook, to avoid an
+  // unconditional hook call for a prop most links don't pass. On the
+  // client, window.location.search is always current; during SSR,
+  // getSsrData() provides the request's raw query string.
+  const internal = isInternalHref(baseHref);
+
+  // Only preserve search params for internal links — leaking current
+  // page params (tokens, UTM, etc.) to external domains is a data leak.
+  const resolvedHref =
+    preserveSearchParams && internal
+      ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+      : baseHref;
+
+  // Event callbacks may update the URL, so resolve preserved params at use time.
+  const resolveEventUrl = () =>
+    new URL(
+      preserveSearchParams
+        ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+        : resolvedHref,
+      window.location.href
+    );
 
   // ─── Click handler ───────────────────────────────────────────
   // Each Link component owns its click handling. The router is
@@ -332,6 +595,10 @@ export function Link({
 
         if (!shouldInterceptClick(event, resolvedHref)) return;
 
+        // Native anchor scrolling is not an SPA navigation. Decide before
+        // onNavigate can cancel it, just as we do before hover prefetching.
+        if (isNativeFragmentLink(event.currentTarget)) return;
+
         // Call onNavigate if provided — allows caller to cancel
         if (onNavigate) {
           let prevented = false;
@@ -347,11 +614,59 @@ export function Link({
         }
 
         const router = getRouterOrNull();
-        if (!router) return; // SSR or pre-hydration — fall through to browser nav
+        if (!router) return;
+
+        // Keep the post-callback read: onNavigate may change the current URL
+        // and therefore the search params to preserve or fragment locality.
+        const resolved = resolveEventUrl();
+        if (isNativeFragmentLink(event.currentTarget)) return;
 
         event.preventDefault();
+
         const shouldScroll = scroll !== false;
-        void router.navigate(resolvedHref, { scroll: shouldScroll });
+        // Keep the #fragment — the router commits it to the address bar and
+        // scrolls to the matching element after render. The hash is stripped
+        // from the RSC fetch URL inside the router (TIM-1035).
+        const absoluteHref = resolved.pathname + stripRscCacheKey(resolved.search) + resolved.hash;
+
+        const seq = ++clickSeq.current;
+        let settled = false;
+        let committed = false;
+        const clear = () => {
+          if (clickSeq.current === seq) setIsPending(false);
+        };
+        const onCommit = () => {
+          committed = true;
+          if (settled) clear();
+        };
+        const settle = () => {
+          settled = true;
+          if (committed) clear();
+        };
+        setIsPending(true);
+        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
+          // recover from surfaces as an unhandled rejection — the same
+          // regime as `useRouter().push()`'s `void router.navigate(...)`.
+          //
+          // It used to reach the nearest error boundary instead: React
+          // re-throws a rejected async action during render (measured on
+          // 19.2.7). That replaced the departing page with the app's error
+          // UI, which contradicts what every other failure path here
+          // promises — a navigation that fails leaves the user on the page
+          // they were already looking at (TIM-1306). Recoverable failures
+          // never get here anyway; `runNavigation` swallows AbortErrors and
+          // `recoverFromNavigationError` turns a failed fetch into a full
+          // document load.
+          throw error;
+        });
       }
     : userOnClick; // External links — just pass through user's onClick
 
@@ -362,14 +677,16 @@ export function Link({
           userOnMouseEnter?.(event);
           const router = getRouterOrNull();
           if (router) {
-            router.prefetch(resolvedHref);
+            if (isNativeFragmentLink(event.currentTarget)) return;
+            const resolved = resolveEventUrl();
+            router.prefetch(resolved.pathname + stripRscCacheKey(resolved.search));
           }
         }
       : userOnMouseEnter;
 
   return (
     <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>
-      <LinkStatusProvider href={resolvedHref}>{children}</LinkStatusProvider>
+      <LinkStatusContext.Provider value={linkStatus}>{children}</LinkStatusContext.Provider>
     </a>
   );
-}
+};