@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/dist/_chunks/use-segment-params-DzTBpkvj.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-segment-params-DzTBpkvj.js","names":[],"sources":["../../src/client/use-pending-navigation.ts","../../src/client/navigation-context.ts","../../src/client/top-loader.tsx","../../src/client/navigation-root.tsx","../../src/client/params-context.ts","../../src/client/use-segment-params.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\nimport { getRouterOrNull } from './router-ref.ts';\n\nfunction subscribe(onStoreChange: () => void): () => void {\n  const router = getRouterOrNull();\n  if (!router) return () => {};\n  return router.onPendingChange(onStoreChange);\n}\n\nfunction getSnapshot(): boolean {\n  const router = getRouterOrNull();\n  return router ? router.isPending() : false;\n}\n\nconst getServerSnapshot = getSnapshot;\n\n/**\n * Returns true while an RSC navigation is in flight.\n *\n * Reads from the router's external pending store via useSyncExternalStore.\n * Only components that call this hook re-render when pending state\n * changes — no full-tree re-render.\n *\n * ```tsx\n * 'use client'\n * import { usePendingNavigation } from '@timber-js/app/client'\n *\n * export function NavBar() {\n *   const isPending = usePendingNavigation()\n *   return (\n *     <nav className={isPending ? 'opacity-50' : ''}>\n *       <Link href=\"/dashboard\">Dashboard</Link>\n *     </nav>\n *   )\n * }\n * ```\n */\nexport function usePendingNavigation(): boolean {\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n","'use client';\n\n/**\n * NavigationContext — React context for navigation state.\n *\n * Holds the current pathname and search, updated atomically with the RSC\n * tree on each navigation. This replaces the previous useSyncExternalStore\n * approach for usePathname() and useSearchParams(), which suffered from a\n * timing gap: the new tree could commit before the external store\n * re-renders fired, causing a frame where both old and new active states\n * were visible simultaneously.\n *\n * Segment params are NOT here — see the note on NavigationState below.\n *\n * By wrapping the RSC payload element in NavigationProvider inside\n * renderRoot(), the context value and the element tree are passed to\n * reactRoot.render() in the same call — atomic by construction.\n * All consumers (usePathname, useSearchParams) see the new values in the\n * same render pass as the new tree.\n *\n * During SSR, no NavigationProvider is mounted. Hooks fall back to\n * the ALS-backed getSsrData() for per-request isolation.\n *\n * IMPORTANT: createContext and useContext are NOT available in the RSC\n * environment (React Server Components use a stripped-down React).\n * The context is lazily initialized on first access, and all functions\n * that depend on these APIs are safe to call from any environment —\n * they return null or no-op when the APIs aren't available.\n *\n * SINGLETON GUARANTEE: All shared mutable state uses globalThis via\n * Symbol.for keys. The RSC client bundler can duplicate this module\n * across chunks (browser-entry graph + client-reference graph). With\n * ESM output, each chunk gets its own module scope — module-level\n * variables would create separate singleton instances per chunk.\n * globalThis guarantees a single instance regardless of duplication.\n *\n * This workaround will be removed when Rolldown ships `format: 'app'`\n * (module registry format that deduplicates like webpack/Turbopack).\n * See design/27-chunking-strategy.md.\n *\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport React, { createElement, type ReactNode } from 'react';\nimport type { SlotParamsRecord } from '../shared/slot-params.ts';\n\n// ---------------------------------------------------------------------------\n// Context type\n// ---------------------------------------------------------------------------\n\n/**\n * What the browser knows about the current location.\n *\n * Params are deliberately absent: they are a property of the tree the server\n * rendered, not of the address bar, and they now travel inside the payload as\n * the payload root. Keeping a copy here meant the router had to thread\n * the record from a response header into context on every path — navigation,\n * traversal, prefetch, revalidation — and each of those was a place to drop it\n * (TIM-1294).\n */\nexport interface NavigationState {\n  pathname: string;\n  search: string;\n}\n\n// ---------------------------------------------------------------------------\n// Lazy context initialization\n// ---------------------------------------------------------------------------\n\n/**\n * The context is created lazily to avoid calling createContext at module\n * level. In the RSC environment, React.createContext doesn't exist —\n * calling it at import time would crash the server.\n *\n * Context instances are stored on globalThis (NOT in module-level\n * variables) because the ESM bundler can duplicate this module across\n * chunks. Module-level variables would create separate instances per\n * chunk — the provider in NavigationRoot (index chunk) would use\n * context A while the consumer in usePendingNavigation (shared chunk)\n * reads from context B. globalThis guarantees a single instance.\n *\n * See design/27-chunking-strategy.md §\"Singleton Safety\"\n */\n\n// Symbol keys for globalThis storage — prevents collisions with user code\nconst NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');\n\nfunction getOrCreateContext(): React.Context<NavigationState | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as\n    | React.Context<NavigationState | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  // createContext may not exist in the RSC environment\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<NavigationState | null>(null);\n    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the navigation context. Returns null during SSR (no provider)\n * or in the RSC environment (no context available).\n * Internal — used by usePathname() and useSearchParams().\n */\nexport function useNavigationContext(): NavigationState | null {\n  const ctx = getOrCreateContext();\n  if (!ctx) return null;\n  // useContext may not exist in the RSC environment — caller wraps in try/catch\n  if (typeof React.useContext !== 'function') return null;\n  // eslint-disable-next-line rules-of-hooks -- conditional on environment, not render path\n  return React.useContext(ctx);\n}\n\n// ---------------------------------------------------------------------------\n// Provider component\n// ---------------------------------------------------------------------------\n\nexport interface NavigationProviderProps {\n  value: NavigationState;\n  children?: ReactNode;\n}\n\n/**\n * Wraps children with NavigationContext.Provider.\n *\n * Used in browser-entry.ts renderRoot to wrap the RSC payload element\n * so that navigation state updates atomically with the tree render.\n */\nexport function NavigationProvider({\n  value,\n  children,\n}: NavigationProviderProps): React.ReactElement {\n  const ctx = getOrCreateContext();\n  if (!ctx) {\n    // RSC environment — no context available. Return children as-is.\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Module-level state for renderRoot to read\n// ---------------------------------------------------------------------------\n\n/**\n * Navigation state communicated between the router and renderRoot.\n *\n * The router calls setNavigationState() before renderRoot(). The\n * renderRoot callback reads via getNavigationState() to create the\n * NavigationProvider with the correct params/pathname.\n *\n * This is NOT used by hooks directly — hooks read from React context.\n *\n * Stored on globalThis (like the context instances above) because the\n * router lives in one chunk while renderRoot lives in another. Module-\n * level variables would be separate per chunk.\n */\nconst NAV_STATE_KEY = Symbol.for('__timber_nav_state');\n\nfunction _getNavStateStore(): { current: NavigationState } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_STATE_KEY]) {\n    g[NAV_STATE_KEY] = { current: { pathname: '/', search: '' } };\n  }\n  return g[NAV_STATE_KEY] as { current: NavigationState };\n}\n\nexport function setNavigationState(state: NavigationState): void {\n  _getNavStateStore().current = state;\n}\n\nexport function getNavigationState(): NavigationState {\n  return _getNavStateStore().current;\n}\n\n// ---------------------------------------------------------------------------\n// Pending navigation state lives in the router, not here\n// ---------------------------------------------------------------------------\n\n/**\n * There was a second React context here — `PendingNavigationContext`, holding\n * the in-flight navigation URL, provided by `NavigationRoot` out of a\n * `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone\n * (TIM-1307).\n *\n * Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and\n * `TopLoader` both subscribe to the router's external pending store via\n * `useSyncExternalStore`: sync priority, immune to transition entanglement,\n * and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).\n * The context was a parallel representation of the same fact that no consumer\n * ever migrated to, and one that could not even agree with the store — a\n * navigation superseded by a cached popstate replay left its URL set until the\n * next full navigation, because the staleness guard skipped the clear and no\n * other path touched it.\n *\n * One representation, and it is the router's. See\n * design/19-client-navigation.md §\"How Pending State Works\".\n */\n","/**\n * TopLoader — Built-in progress bar for client navigations.\n *\n * Shows an animated progress bar at the top of the viewport while an RSC\n * navigation is in flight. Injected automatically by the framework into\n * NavigationRoot — users never render this component directly.\n *\n * Configuration is via timber.config.ts `topLoader` key. Enabled by default.\n * Users who want a fully custom progress indicator disable the built-in one\n * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.\n *\n * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%\n * width over ~30s using ease-out timing. When navigation completes, the bar\n * snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).\n *\n * Phase transitions are derived synchronously during render (React's\n * getDerivedStateFromProps pattern) — no useEffect needed for state tracking.\n * The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.\n *\n * When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar\n * stays invisible during the delay period. If navigation finishes before the\n * delay, the bar was never visible so the finish transition is also invisible.\n *\n * See design/19-client-navigation.md §\"usePendingNavigation()\"\n * See LOCAL-336 for design decisions.\n */\n\n'use client';\n\nimport { useState, createElement } from 'react';\nimport { usePendingNavigation } from './use-pending-navigation.ts';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface TopLoaderConfig {\n  /** Whether the top-loader is enabled. Default: true. */\n  enabled?: boolean;\n  /** Bar color. Default: '#2299DD'. */\n  color?: string;\n  /** Bar height in pixels. Default: 3. */\n  height?: number;\n  /** Show subtle glow/shadow effect. Default: false. */\n  shadow?: boolean;\n  /** Delay in ms before showing the bar. Default: 0. */\n  delay?: number;\n  /** CSS z-index. Default: 1600. */\n  zIndex?: number;\n}\n\n// ─── Defaults ────────────────────────────────────────────────────\n\nconst DEFAULT_COLOR = '#2299DD';\nconst DEFAULT_HEIGHT = 3;\nconst DEFAULT_SHADOW = false;\nconst DEFAULT_DELAY = 0;\nconst DEFAULT_Z_INDEX = 1600;\n\n// ─── Keyframes ───────────────────────────────────────────────────\n\n// Unique keyframes name to avoid collisions with user styles.\nconst CRAWL_KEYFRAMES = '__timber_top_loader_crawl';\nconst APPEAR_KEYFRAMES = '__timber_top_loader_appear';\nconst FINISH_KEYFRAMES = '__timber_top_loader_finish';\n\n// Track whether the @keyframes rules have been injected into the document.\nlet keyframesInjected = false;\n\n/**\n * Inject the @keyframes rules into the document head once.\n * Called during render (idempotent). Uses a <style> tag so the\n * animations are available for inline-styled elements.\n */\nfunction ensureKeyframes(): void {\n  if (keyframesInjected) return;\n  if (typeof document === 'undefined') return;\n\n  const style = document.createElement('style');\n  style.textContent = `\n@keyframes ${CRAWL_KEYFRAMES} {\n  0% { width: 0%; }\n  100% { width: 90%; }\n}\n@keyframes ${APPEAR_KEYFRAMES} {\n  from { opacity: 0; }\n  to { opacity: 1; }\n}\n@keyframes ${FINISH_KEYFRAMES} {\n  0% { width: 90%; opacity: 1; }\n  50% { width: 100%; opacity: 1; }\n  100% { width: 100%; opacity: 0; }\n}\n`;\n  document.head.appendChild(style);\n  keyframesInjected = true;\n}\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Internal top-loader component. Injected by NavigationRoot.\n *\n * Reads pending navigation state from the router's external store, via\n * usePendingNavigation() — the one pending representation (TIM-1307).\n * Phase transitions are derived synchronously during render:\n *\n *   hidden → crawling:   when isPending becomes true\n *   crawling → finishing: when isPending becomes false\n *   finishing → hidden:   when CSS transition ends (onTransitionEnd)\n *   finishing → crawling: when isPending becomes true again\n *\n * No useEffect — all state changes are either derived during render\n * (getDerivedStateFromProps pattern) or triggered by DOM events.\n */\nexport function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {\n  // Read pending state from the router's external store via\n  // useSyncExternalStore (inside usePendingNavigation). Only this\n  // component re-renders when pending changes — no full-tree re-render.\n  const isPending = usePendingNavigation();\n\n  const color = config?.color ?? DEFAULT_COLOR;\n  const height = config?.height ?? DEFAULT_HEIGHT;\n  const shadow = config?.shadow ?? DEFAULT_SHADOW;\n  const delay = config?.delay ?? DEFAULT_DELAY;\n  const zIndex = config?.zIndex ?? DEFAULT_Z_INDEX;\n\n  const [phase, setPhase] = useState<'hidden' | 'crawling' | 'finishing'>('hidden');\n\n  // ─── Synchronous phase derivation (getDerivedStateFromProps) ──\n  // React allows setState during render if the value changes — it\n  // immediately re-renders with the updated state before committing.\n\n  if (isPending && (phase === 'hidden' || phase === 'finishing')) {\n    setPhase('crawling');\n  }\n  if (!isPending && phase === 'crawling') {\n    setPhase('finishing');\n  }\n\n  // Inject keyframes on first visible render (idempotent)\n  if (phase !== 'hidden') {\n    ensureKeyframes();\n  }\n\n  if (phase === 'hidden') return null;\n\n  // ─── Styles ──────────────────────────────────────────────────\n\n  const containerStyle: React.CSSProperties = {\n    position: 'fixed',\n    top: 0,\n    left: 0,\n    width: '100%',\n    height: `${height}px`,\n    zIndex,\n    pointerEvents: 'none',\n  };\n\n  const barStyle: React.CSSProperties = {\n    height: '100%',\n    backgroundColor: color,\n    ...(phase === 'crawling'\n      ? {\n          // Crawl from 0% to 90% over 30s. When delay > 0, both the crawl\n          // and a visibility animation are delayed — the bar stays at width 0%\n          // and opacity 0 during the delay, then appears and starts crawling.\n          // With delay 0, the appear animation is instant (0s duration, no delay).\n          animation: [\n            `${CRAWL_KEYFRAMES} 30s ease-out ${delay}ms forwards`,\n            `${APPEAR_KEYFRAMES} 0s ${delay}ms both`,\n          ].join(', '),\n        }\n      : {\n          // Finishing: fill to 100% then fade out via a keyframe animation.\n          // We use a keyframe instead of a CSS transition because the\n          // animation-to-transition handoff is unreliable — the browser\n          // may not capture the animated width as the transition's \"from\"\n          // value when both the animation removal and transition are\n          // applied in the same render frame.\n          animation: `${FINISH_KEYFRAMES} 400ms ease forwards`,\n        }),\n    ...(shadow\n      ? {\n          boxShadow: `0 0 10px ${color}, 0 0 5px ${color}`,\n        }\n      : {}),\n  };\n\n  // Clean up the finishing phase when the finish animation completes.\n  const handleAnimationEnd =\n    phase === 'finishing'\n      ? (e: React.AnimationEvent) => {\n          if (e.animationName === FINISH_KEYFRAMES) {\n            setPhase('hidden');\n          }\n        }\n      : undefined;\n\n  return createElement(\n    'div',\n    {\n      'style': containerStyle,\n      'aria-hidden': 'true',\n      'data-timber-top-loader': '',\n    },\n    createElement('div', { style: barStyle, onAnimationEnd: handleAnimationEnd })\n  );\n}\n","/**\n * NavigationRoot — Wrapper component for transition-based rendering.\n *\n * Solves the \"new boundary has no old content\" problem for client-side\n * navigation. When React renders a completely new Suspense boundary via\n * root.render(), it shows the fallback immediately — root.render() is\n * always an urgent update regardless of startTransition.\n *\n * NavigationRoot holds the current element in React state. Navigation\n * updates call startTransition(() => setState(newElement)), which IS\n * a transition update. React keeps the old committed tree visible while\n * the new tree resolves, instead of hiding it behind a Suspense fallback.\n *\n * The navigation's async work runs OUTSIDE the transition scope and every\n * state update it schedules gets its own synchronous `startTransition` — a\n * transition scope does not survive an `await`, and an async callback that\n * returns a thenable defers the commit past the promise callers await. See\n * the long comment on `_navigateTransition` (TIM-1306).\n *\n * This component holds no pending state. The `TopLoader` it renders and the\n * public `usePendingNavigation()` both subscribe to the router's external\n * pending store; NavigationRoot's own `pendingUrl` was a second, unread\n * representation of the same fact and is gone (TIM-1307).\n *\n * Hard navigation guard: When a hard navigation is triggered (500 error,\n * version skew), the component throws an unresolved thenable AFTER all\n * hooks to suspend forever — preventing React from rendering children\n * during page teardown. The throw must come after hooks to satisfy\n * React's rules (same hook count every render) while still preventing\n * child renders that could hit hook count mismatches in components\n * whose positions shift during teardown. This pattern is borrowed from\n * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).\n *\n * See design/05-streaming.md §\"deferSuspenseFor\"\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport {\n  createElement,\n  Fragment,\n  startTransition,\n  useLayoutEffect,\n  useRef,\n  useState,\n  type ReactNode,\n} from 'react';\nimport { TopLoader, type TopLoaderConfig } from './top-loader.tsx';\n\n// ─── Transition Result ──────────────────────────────────────────\n\n/**\n * What a navigation's `perform()` hands back to the transition.\n *\n * Declared once and shared by every layer that passes it along — the router's\n * `RouterDeps.navigateTransition` imports it too — so a field cannot be added\n * to the producer and dropped by the adapter in between. `E` is the element\n * type: `ReactNode` here, `unknown` in the router, which never touches it.\n */\nexport interface TransitionResult<E = ReactNode> {\n  /** The wrapped tree to render. */\n  element: E;\n  /** Resolves when the Flight stream finishes decoding, or null. */\n  decodePromise: Promise<void> | null;\n  /**\n   * Publishes the navigation's state — segment cache, pathname, address bar,\n   * history stack, and the client's record of the mounted tree — and\n   * announces it to listeners outside React.\n   *\n   * Run when React commits this tree, not when the tree is handed over: a\n   * tree React is still waiting on, or one a later navigation replaces first,\n   * has been given to React without being on screen. A superseded navigation\n   * never runs it and leaves every one of those consumers describing the\n   * route still on screen (TIM-1301).\n   */\n  commit: () => void;\n}\n\n/**\n * The tree NavigationRoot holds in state, and the state publish that belongs\n * to it. They travel as one object so React's commit of the tree is the event\n * that publishes — see the effect in NavigationRoot.\n */\ninterface RenderedTree {\n  element: ReactNode;\n  publish: (() => void) | null;\n}\n\n// ─── Navigation Transition Counter ──────────────────────────────\n// Monotonically increasing counter that increments each time\n// navigateTransition() is called. Used to detect stale transitions:\n// if a newer transition started while the current one's perform()\n// was in flight, the current transition is stale and should reject.\n//\n// Separate from the link-pending navId (which only increments on\n// link clicks). This counter covers all navigation types: link clicks,\n// programmatic navigate(), refresh(), and handlePopState().\n//\n// Uses globalThis for singleton guarantee across chunks — same pattern\n// as NavigationContext and the link pending store.\n\nconst NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');\n\n/**\n * `waiters` are woken on every bump so an in-flight navigation can stop\n * waiting on its own payload the moment it is superseded — see\n * `settleOnDecodeOrSupersession`.\n */\ninterface TransitionCounter {\n  id: number;\n  waiters: Set<() => void>;\n}\n\nfunction getTransitionCounter(): TransitionCounter {\n  const g = globalThis as Record<symbol, unknown>;\n  const existing = g[NAV_TRANSITION_KEY] as Partial<TransitionCounter> | undefined;\n  if (!existing) {\n    const created: TransitionCounter = { id: 0, waiters: new Set() };\n    g[NAV_TRANSITION_KEY] = created;\n    return created;\n  }\n  // A duplicated copy of this module may have created the singleton before\n  // `waiters` existed. The object is shared across chunks, so fill it in\n  // rather than replacing it — replacing would strand the other copy's id.\n  existing.waiters ??= new Set();\n  return existing as TransitionCounter;\n}\n\n/** Bump the counter and wake everything waiting on an older transition. */\nfunction bumpTransitionCounter(): number {\n  const counter = getTransitionCounter();\n  counter.id += 1;\n  for (const wake of [...counter.waiters]) wake();\n  return counter.id;\n}\n\n/**\n * Invalidate all in-flight navigation transitions. Any navigateTransition()\n * call whose perform() has not yet committed will reject with AbortError\n * instead of committing its element.\n *\n * Called by the router when a render supersedes in-flight navigations\n * WITHOUT going through navigateTransition() — the cached popstate replay\n * renders via transitionRender(), which doesn't bump the counter, so a\n * stale forward navigation's setElement would otherwise pass the\n * `counter.id !== transId` guard and commit the forward page over the\n * replayed back page (TIM-1022).\n */\nexport function supersedeNavigationTransitions(): void {\n  bumpTransitionCounter();\n}\n\n/**\n * Wait for the payload to finish decoding, OR for this transition to be\n * superseded — whichever happens first.\n *\n * A superseded navigation must stop waiting on its own stream. The stream is\n * deliberately NOT aborted once its tree has been handed to React (the tree\n * may be on screen with boundaries still feeding from it — see\n * `handedOffNavAbort` in `client/router.ts`), so there is nothing left to make\n * `decodePromise` settle promptly. Awaiting it bare would keep the loser's\n * `router.navigate()` promise pending for the rest of the stream — and\n * forever if it stalls — which is what `<Link>`'s `isPending` is timed\n * against, so the losing link would sit spinning while the winner loaded\n * (codex on #1004).\n *\n * A decode *failure* still propagates: it is a real error for this\n * navigation, and the caller's recovery is timed against it.\n */\nfunction settleOnDecodeOrSupersession(\n  decodePromise: Promise<void>,\n  counter: TransitionCounter,\n  transId: number\n): Promise<void> {\n  if (counter.id !== transId) return Promise.resolve();\n  return new Promise<void>((resolve, reject) => {\n    const stopWaiting = (): void => {\n      counter.waiters.delete(wake);\n    };\n    const wake = (): void => {\n      if (counter.id !== transId) {\n        stopWaiting();\n        resolve();\n      }\n    };\n    counter.waiters.add(wake);\n    decodePromise.then(\n      () => {\n        stopWaiting();\n        resolve();\n      },\n      (error: unknown) => {\n        stopWaiting();\n        reject(error instanceof Error ? error : new Error(String(error)));\n      }\n    );\n  });\n}\n\n// ─── Hard Navigation Guard ──────────────────────────────────────\n\n/**\n * Module-level flag indicating a hard (MPA) navigation is in progress.\n *\n * When true:\n * - NavigationRoot throws an unresolved thenable to suspend forever,\n *   preventing React from rendering children during page teardown\n *   (avoids \"Rendered more hooks\" crashes).\n * - The Navigation API handler skips interception, letting the browser\n *   perform a full page load (prevents infinite loops where\n *   window.location.href → navigate event → router.navigate → 500 →\n *   window.location.href → ...).\n *\n * Uses globalThis for singleton guarantee across chunks (same pattern\n * as NavigationContext). See design/19-client-navigation.md §\"Singleton\n * Guarantee via globalThis\".\n */\nconst HARD_NAV_KEY = Symbol.for('__timber_hard_navigating');\n\nfunction getHardNavStore(): { value: boolean } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[HARD_NAV_KEY]) {\n    g[HARD_NAV_KEY] = { value: false };\n  }\n  return g[HARD_NAV_KEY] as { value: boolean };\n}\n\n/**\n * Set the hard-navigating flag. Call this BEFORE setting\n * window.location.href or window.location.reload() to prevent:\n * 1. React from rendering children during page teardown\n * 2. Navigation API from intercepting the hard navigation\n */\nexport function setHardNavigating(value: boolean): void {\n  getHardNavStore().value = value;\n}\n\n/**\n * Check if a hard navigation is in progress.\n * Used by NavigationRoot (throw unresolvedThenable) and by the\n * Navigation API handler (skip interception).\n */\nexport function isHardNavigating(): boolean {\n  return getHardNavStore().value;\n}\n\n/**\n * A thenable that never resolves. When thrown during React render,\n * it causes the component to suspend forever — React keeps the\n * old committed tree visible and never attempts to render children.\n *\n * This is the same pattern Next.js uses in app-router.tsx for MPA\n * navigations (pushRef.mpaNavigation → throw unresolvedThenable).\n */\n// for React's Suspense mechanism. Same pattern as Next.js's unresolvedThenable.\n// eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable\nconst unresolvedThenable = { then() {} } as PromiseLike<never>;\n\n// ─── Module-level functions ──────────────────────────────────────\n\n/**\n * Module-level reference to the state setter wrapped in startTransition.\n * Used for non-navigation renders (applyRevalidation, popstate replay).\n */\nlet _transitionRender: ((element: ReactNode) => void) | null = null;\n\n/**\n * Module-level reference to the navigation transition function.\n *\n * Runs the fetch OUTSIDE any transition scope and wraps only the state update\n * that hands the resulting tree to React — describing this as \"a full\n * navigation in a single startTransition\" is the shape TIM-1306 removed.\n */\nlet _navigateTransition:\n  | ((url: string, perform: () => Promise<TransitionResult>) => Promise<void>)\n  | null = null;\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Root wrapper component that enables transition-based rendering.\n *\n * Renders the TopLoader alongside the tree it holds in state. Neither adds a\n * DOM element on the hydration path, so the tree matches the server HTML.\n *\n * Usage in browser-entry.ts:\n *   const rootEl = createElement(NavigationRoot, { initial: wrapped });\n *   reactRoot = hydrateRoot(document, rootEl);\n *\n * Subsequent navigations:\n *   navigateTransition(url, async () => { fetch; return wrappedElement; });\n *\n * Non-navigation renders:\n *   transitionRender(newWrappedElement);\n */\nexport function NavigationRoot({\n  initial,\n  topLoaderConfig,\n}: {\n  initial: ReactNode;\n  topLoaderConfig?: TopLoaderConfig;\n}): ReactNode {\n  const [rendered, setRendered] = useState<RenderedTree>({ element: initial, publish: null });\n\n  // Publish the navigation's state when React commits its tree — not when the\n  // tree is handed over. A tree React is still waiting on, or one a later\n  // navigation replaces before React renders it, has been *given* to React\n  // without being on screen; publishing then describes a route the user never\n  // saw, which is the defect this ordering exists to prevent (TIM-1301).\n  //\n  // A **layout** effect, so the publish lands before the browser paints and,\n  // more importantly, before every descendant's passive effect. A destination\n  // component that navigates from a mount effect — a redirect guard, a\n  // `refresh()` on mount — would otherwise start its navigation while the\n  // segment cache, address bar and pathname still described the departing\n  // route, and send an X-Timber-State-Tree for a tree that is no longer\n  // mounted (codex on #998).\n  //\n  // Descendant *layout* effects still run first: React runs layout effects\n  // child-before-parent, and the only way to precede them would be a fiber\n  // rendered as an earlier sibling of the payload. That is not free here —\n  // `server/ssr-wrappers.tsx` mirrors this component's fiber shape so `useId`\n  // agrees across hydration, and an extra sibling shifts every id in the\n  // payload subtree. A layout effect that navigates on mount is the price.\n  //\n  // Keyed on the tree object rather than on the effect run. A publish moves\n  // the address bar, which is not idempotent, so any second invocation for the\n  // same tree — an effect re-run React is entitled to perform — must be a\n  // no-op rather than a second history entry.\n  const publishedRef = useRef<RenderedTree | null>(null);\n  useLayoutEffect(() => {\n    if (publishedRef.current === rendered) return;\n    publishedRef.current = rendered;\n    rendered.publish?.();\n  }, [rendered]);\n\n  // NOTE: We use standalone `startTransition` (imported from 'react'),\n  // NOT `useTransition`. The `useTransition` hook's `startTransition`\n  // is tied to a single fiber and tracks one async callback at a time.\n  // When two navigations overlap (click slow-page, then click dashboard),\n  // calling useTransition's startTransition twice with concurrent async\n  // callbacks corrupts React's internal hook tracking — causing\n  // \"Rendered more hooks than during the previous render.\"\n  //\n  // Standalone `startTransition` creates independent transition lanes\n  // for each call, so concurrent navigations don't interfere. We don't\n  // need useTransition's `isPending` — pending state lives in the router's\n  // external store, which TopLoader and usePendingNavigation() subscribe to.\n  //\n  // This matches the Next.js pattern (TIM-625): \"No useTransition in\n  // the router at all — only standalone startTransition.\"\n\n  // Non-navigation render (revalidation, popstate cached replay).\n  // Non-navigation render (revalidation, popstate cached replay). Both publish\n  // synchronously in the router before calling this — neither has an in-flight\n  // window in which it could be superseded — so there is nothing to publish\n  // on commit.\n  _transitionRender = (newElement: ReactNode) => {\n    startTransition(() => {\n      setRendered({ element: newElement, publish: null });\n    });\n  };\n\n  // Full navigation transition.\n  //\n  // The async work runs OUTSIDE any transition scope, and each state update is\n  // its own synchronous `startTransition`. Two React behaviours force that\n  // shape; both were measured on React 19.2.7 (tests/navigation-transition-\n  // suspense.test.ts pins the observable half).\n  //\n  // 1. A transition scope does not survive an `await`. `startTransition`\n  //    restores the previous scope in its `finally`, which for an async\n  //    callback runs when that callback RETURNS — i.e. at its first `await`.\n  //    So an update scheduled past an await inside `startTransition(async …)`\n  //    is an ordinary urgent update:\n  //\n  //      startTransition(() => setEl(x))                     -> 'HOME' held\n  //      startTransition(async () => { await p; setEl(x) })  -> fallback shown\n  //\n  //    Left uncorrected, every navigation whose new tree suspends replaces the\n  //    visible page with a Suspense fallback — the exact thing this component\n  //    exists to prevent (TIM-1306). React documents the caveat under\n  //    `startTransition`: updates after an await need their own transition.\n  //\n  // 2. Re-wrapping *inside* the async callback is not enough. Returning a\n  //    thenable from `startTransition` hands it to `ReactSharedInternals.S`,\n  //    which calls react-dom's `entangleAsyncAction`. That opens an action\n  //    scope: `currentEntangledLane` collects EVERY transition update\n  //    scheduled while the scope is open — including one from a nested,\n  //    fully synchronous `startTransition` — and rendering that lane throws\n  //    `currentEntangledActionThenable`, suspending until the action settles.\n  //    Which is after the promise `navigateTransition` hands back, so a caller\n  //    that awaits a navigation and then reads the DOM sees the departing\n  //    page, and the TIM-1301 publish (a layout effect on the commit) is just\n  //    as late. (Not `ReactSharedInternals.asyncTransitions` — that counter is\n  //    write-only in 19.2.7.)\n  //\n  // No async action is created here, so every navigation commits as soon as\n  // React can render its destination — where TIM-1301 put it. That\n  // now holds for ALL of them. It used not to hold for `<Link>`, which wrapped\n  // `router.navigate()` in its own `useTransition`: that action scope\n  // entangled this component's updates just the same, so a Link navigation\n  // committed only once the payload had finished decoding, and with it\n  // `pushState`, the segment cache and `timber:navigation-end`. Link now calls\n  // `router.navigate()` outside any transition and tracks its own `isPending`\n  // with a plain `useState` (TIM-1307).\n  //\n  // Nothing here may reopen an action scope: no `startTransition` callback in\n  // this path may return a thenable, and no caller may invoke this from inside\n  // a React action scope. That is a rule about `startTransition`, not about\n  // `perform` — `perform` is async by contract and is awaited OUTSIDE any\n  // transition scope, which is exactly why it is safe.\n  //\n  // Standalone `startTransition` rather than `useTransition`'s is still\n  // deliberate — see the TIM-625 note above; each navigation needs an\n  // independent lane.\n  //\n  // `url` is unused: it named the pending state this component used to hold,\n  // and the router already publishes the same URL to its own pending store\n  // before calling here. It stays in the signature because the router's\n  // `RouterDeps.navigateTransition` adapter passes it and the argument reads\n  // at the call site.\n  _navigateTransition = (_url: string, perform: () => Promise<TransitionResult>) => {\n    // Increment the transition counter SYNCHRONOUSLY (before any await). Each\n    // call gets a unique transId; the counter is the same globalThis\n    // singleton, so a newer call always has a higher id.\n    const counter = getTransitionCounter();\n    const transId = bumpTransitionCounter();\n\n    const superseded = () => new DOMException('Navigation superseded', 'AbortError');\n\n    return (async () => {\n      const { element, decodePromise, commit } = await perform();\n      if (counter.id !== transId) {\n        decodePromise?.catch(() => {});\n        throw superseded();\n      }\n      // Hand the tree over with its commit attached. The effect above runs\n      // it if and when React commits this tree, so a navigation that is\n      // superseded while its payload streams publishes nothing (TIM-1301).\n      //\n      // This is THE update that must not hide the departing page (TIM-1306).\n      startTransition(() => {\n        setRendered({ element, publish: commit });\n      });\n      // React may commit the tree before this settles — that is the point:\n      // the destination reveals as React is able to render it\n      // rather than waiting for the whole Flight stream. The await is here so\n      // the promise this function hands back still means \"the payload is\n      // decoded\", which is what the router's scroll restoration, the\n      // Navigation API deferred and `<Link>`'s `isPending` are timed against.\n      //\n      // ...unless this navigation loses first, in which case it stops waiting\n      // on a stream that is no longer its business. See\n      // `settleOnDecodeOrSupersession`.\n      if (decodePromise) await settleOnDecodeOrSupersession(decodePromise, counter, transId);\n      if (counter.id !== transId) throw superseded();\n    })();\n  };\n\n  // ─── Hard navigation guard ─────────────────────────────────\n  // When a hard navigation is in progress (500 error, version skew),\n  // suspend forever to prevent React from rendering children during\n  // page teardown. This avoids \"Rendered more hooks\" crashes in\n  // CHILD components whose hook counts may shift during teardown.\n  //\n  // CRITICAL: This throw MUST come AFTER all hooks (the useState,\n  // useRef and useLayoutEffect above). React requires the same hooks\n  // to run on every render. If we threw before hooks, React would see\n  // 0 hooks on the re-render vs 3 on the initial render — triggering\n  // the exact \"Rendered more hooks\" error we're trying to prevent.\n  //\n  // By placing it after hooks but before the return, all hooks\n  // satisfy React's rules, but the thrown thenable prevents any\n  // children from rendering. Same pattern as Next.js app-router.tsx\n  // (pushRef.mpaNavigation — also placed after all hooks).\n  if (isHardNavigating()) {\n    throw unresolvedThenable;\n  }\n\n  // Inject TopLoader alongside the element tree. It subscribes to the router's\n  // pending store itself, so it takes no props from here beyond its config,\n  // and only it re-renders when a navigation starts or ends. Rendered only\n  // when not explicitly disabled via config.\n  //\n  // This Fragment is a FORK — two children — so it advances React's tree\n  // context and shifts every `useId` below it. `server/ssr-wrappers.tsx`\n  // mirrors it for exactly that reason; a single-child wrapper would not need\n  // a mirror. See tests/ssr-wrapper-parity.test.ts.\n  const showTopLoader = topLoaderConfig?.enabled !== false;\n  if (!showTopLoader) return rendered.element;\n  return createElement(\n    Fragment,\n    null,\n    createElement(TopLoader, { config: topLoaderConfig }),\n    rendered.element\n  );\n}\n\n// ─── Public API ──────────────────────────────────────────────────\n\n/**\n * Trigger a transition render for non-navigation updates.\n * React keeps the old committed tree visible while any new Suspense\n * boundaries in the update resolve.\n *\n * Used for: applyRevalidation, popstate replay with cached payload.\n */\nexport function transitionRender(element: ReactNode): void {\n  if (_transitionRender) {\n    _transitionRender(element);\n  }\n}\n\n/**\n * Run a full navigation, handing its tree to React in a transition.\n *\n * The `perform` callback fetches the RSC payload, updates router state, and\n * returns the wrapped React element. `perform` is async by contract and runs\n * OUTSIDE any transition scope — only the `setRendered` that hands its result\n * over is wrapped, in a synchronous `startTransition`.\n *\n * Do not call this from inside a React action scope, and never let a\n * `startTransition` callback in this path return a thenable: either opens an\n * action scope that entangles the update and defers the commit until the\n * action settles (TIM-1306, TIM-1307).\n *\n * Returns a Promise that resolves when the async work completes — the payload\n * is fetched, decoded, and handed to React. It does **not** wait for React to\n * commit the tree, so the state that publishes on that commit (address bar,\n * segment cache, history entry, pathname) may still be a beat behind when it\n * resolves. Anything that needs the destination to be current should listen\n * for `timber:navigation-end`, which is dispatched by the publish itself.\n *\n * Awaiting the publish here was tried and rejected: it makes the promise\n * depend on a React commit, which never arrives if the root unmounts\n * mid-navigation, and deadlocks any caller that awaits a navigation inside\n * `act()`.\n *\n * Used for: navigate(), refresh(), popstate with fetch.\n */\nexport function navigateTransition(\n  url: string,\n  perform: () => Promise<TransitionResult>\n): Promise<void> {\n  if (_navigateTransition) {\n    return _navigateTransition(url, perform);\n  }\n  // Fallback: no NavigationRoot mounted (shouldn't happen in production).\n  // Nothing can supersede a transition that does not exist, so the commit\n  // runs unconditionally.\n  return perform().then((result) => result.commit());\n}\n\n/**\n * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).\n *\n * When there's no RSC payload, we can't create a React root immediately —\n * `createRoot(document).render(...)` would blank the SSR HTML. Instead,\n * this sets up `_transitionRender` and `_navigateTransition` so that the\n * first client navigation triggers root creation via `createAndMount`.\n *\n * After `createAndMount` runs, NavigationRoot renders and overwrites these\n * callbacks with its real `startTransition`-based implementations.\n */\nexport function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {\n  let mounted = false;\n  const mountOnce = (element: ReactNode) => {\n    if (mounted) return;\n    mounted = true;\n    createAndMount(element);\n  };\n  _transitionRender = (element: ReactNode) => {\n    mountOnce(element);\n  };\n  _navigateTransition = async (_url: string, perform: () => Promise<TransitionResult>) => {\n    const { element, commit } = await perform();\n    commit();\n    mountOnce(element);\n  };\n}\n","/**\n * Segment params context — the one channel params use to reach the browser.\n *\n * Params ride the RSC payload's root row as a sibling of the tree\n * (`{ tree, params, slotParams }`), rather than in four side channels that\n * raced to seed them: a response header, an inline script, and two build-time\n * manifest fields all previously carried the same record, each with its own\n * `JSON.stringify` (TIM-1294).\n *\n * Riding the payload is what makes them *typed*. `defineSchema` takes any\n * `Codec<T>`, so a coerced param is whatever the codec returned — a `Date`, a\n * `bigint` — and `JSON.stringify` either flattened it to a string or threw\n * mid-response. React Flight carries those values natively, so the client\n * reads the value the server produced instead of a lossy copy of it. See\n * design/41-global-params.md §\"Transport\".\n *\n * **The client owns the provider.** There is exactly one `ParamsProvider` in\n * the browser's tree, rendered by `PayloadRoot` above the point where a\n * partial navigation splices the new payload into the retained tree. It has to\n * be there and it has to be alone: a provider *inside* the payload lands below\n * the retained region, whose own root is the departing route's provider, so\n * every reader in a skipped layout resolves to the departing record and no\n * amount of wrapping above it helps (TIM-1297).\n *\n * Ordering still holds without a bootstrap contract, for the same reason it\n * did when the provider was in the tree: a provider renders before its own\n * descendants by construction, so `useSegmentParams()` is correct during\n * hydration without anything having to run before `hydrateRoot()`.\n */\n\n'use client';\n\nimport React, { createElement, useMemo, use } from 'react';\nimport { _setCurrentParams, _setCurrentSlotParams } from './state.ts';\nimport { toNullProtoRecord, type CoercedParams } from '../shared/param-value.ts';\nimport { readPublishedParams, type PublishedParams } from '../shared/payload-root.ts';\nimport type { SlotParamsRecord } from '../shared/slot-params.ts';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport type ParamsContextValue = PublishedParams;\n\n// ─── Context ─────────────────────────────────────────────────────\n\n/**\n * SINGLETON GUARANTEE: globalThis + `Symbol.for`, the same pattern as\n * `NavigationContext` and `SegmentUpdateContext`.\n *\n * The RSC client bundler can duplicate a module across chunks, and with ESM\n * output each chunk gets its own module scope — so a bare `createContext` at\n * module level yields one context per chunk. This module is now reached from\n * *both* graphs: `PayloadRoot` is imported by the browser entry, while\n * `useParamsContext()` arrives through the client-reference graph with the\n * app's own components. A duplicate would put the provider on instance A and\n * every reader on instance B, so `useContext` returns `null` and every\n * `useSegmentParams()` call silently falls back to the module snapshot.\n *\n * This module was the one client context without the guard — harmless while\n * the provider travelled inside the payload, in the same graph as its readers,\n * and load-bearing the moment the client started rendering it (TIM-1297).\n *\n * The React APIs are reached through the namespace rather than named imports,\n * for the same reason `segment-update-context.ts` and `navigation-context.ts`\n * do it: React's `react-server` export provides neither `createContext` nor\n * `useContext`, and a *named* ESM import of a missing export fails at module\n * instantiation — before any feature check could run. This module is reachable\n * from every entry a Server Component imports, so the named form crashed\n * those entries outright (codex, PR #992; originally reproduced against\n * `@timber-js/app/segment-params`, an entry point since deleted by TIM-1342 —\n * the hazard is unchanged for the entries that remain).\n *\n * See design/19-client-navigation.md §\"Singleton Guarantee via globalThis\"\n */\nconst PARAMS_CTX_KEY = Symbol.for('__timber_params_ctx');\n\nfunction getOrCreateContext(): React.Context<ParamsContextValue | null> {\n  const store = globalThis as Record<symbol, unknown>;\n  const existing = store[PARAMS_CTX_KEY] as React.Context<ParamsContextValue | null> | undefined;\n  if (existing !== undefined) return existing;\n  if (typeof React.createContext !== 'function') {\n    // RSC environment — no contexts here. Nothing in this module runs on that\n    // side; it only has to import cleanly.\n    return undefined as unknown as React.Context<ParamsContextValue | null>;\n  }\n  const ctx = React.createContext<ParamsContextValue | null>(null);\n  store[PARAMS_CTX_KEY] = ctx;\n  return ctx;\n}\n\nconst ParamsContext = getOrCreateContext();\n\n/**\n * Read the params provided by the tree. Returns null when no provider is\n * above the caller — a component rendered outside a timber route, a\n * `useSegmentParams()` call from outside React entirely, or any component\n * during SSR (where the params reach the hook through the ALS-backed SSR data\n * context instead, and there is no client-owned tree to hold a provider).\n */\nexport function useParamsContext(): ParamsContextValue | null {\n  return React.useContext(ParamsContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface ParamsProviderProps {\n  params: CoercedParams;\n  slotParams: SlotParamsRecord | null;\n  children?: React.ReactNode;\n}\n\n/**\n * Provides the current navigation's params to everything below it.\n *\n * Rendered only by `PayloadRoot`. Not exported: a second provider anywhere in\n * the tree would shadow this one for the region below it, which is precisely\n * the defect TIM-1297 fixed.\n *\n * The module-level snapshot in `state.ts` is written during render rather\n * than in an effect. It is the fallback path for `useSegmentParams()` called\n * outside a component (tests, module scope), and an effect would leave that\n * path reading the *previous* route's params for the whole commit — the\n * window in which a navigation's components actually run. Writing during\n * render is safe here because the value is derived entirely from props: a\n * double-invoked render in StrictMode writes the same record twice.\n */\nfunction ParamsProvider({ params, slotParams, children }: ParamsProviderProps) {\n  // Restore the null prototype the wire could not carry. Flight rejects a\n  // null-prototype object, so `withPublishedParams` flattens the records;\n  // rebuilding them here is what keeps `params.constructor` returning\n  // `undefined` instead of a function for a param the route does not define\n  // (design/13-security.md #36c). Memoized on the props so a re-render with\n  // the same records does not rebuild — the identity of what the hook returns\n  // is load-bearing for `useEffect` dependencies (TIM-1285).\n  const value = useMemo(\n    () => ({\n      params: toNullProtoRecord(params),\n      slotParams: toNullProtoRecord(slotParams),\n    }),\n    [params, slotParams]\n  );\n\n  // Keep the out-of-component fallback in step with the tree being rendered.\n  _setCurrentParams(value.params);\n  _setCurrentSlotParams(value.slotParams);\n\n  return createElement(ParamsContext.Provider, { value }, children);\n}\n\n// ─── Payload root ────────────────────────────────────────────────\n\n/**\n * The client's root: publishes a payload's params over the tree being shown.\n *\n * Rendered at the same position in the wrapper chain on **every** render path\n * — hydration, full navigation, partial navigation, popstate replay, shallow\n * search sync, and revalidation from a server action. Being unconditional is\n * load-bearing twice over: an element type that appears on one render and not\n * the next remounts everything below it, destroying exactly the layout state a\n * partial navigation exists to preserve; and a reader in a skipped layout has\n * to have *some* provider above it on every path or it falls back to the\n * module-level snapshot.\n *\n * `children` is the tree to display, which is not always `source`'s tree:\n *\n * - Full navigation, hydration, replay — `source` is the payload being shown,\n *   and `children` is its own tree.\n * - **Partial navigation** — `children` is the *retained* tree and `source` is\n *   the *incoming* payload. This is the case the whole design exists for: the\n *   retained tree is not re-rendered, so the destination's params can only\n *   reach it from above, and this provider is above it.\n *\n * `source` may be a thenable, in which case this suspends on the payload's\n * root row. That happens on the hydration path only, where the payload\n * promise was going to be rendered at this position anyway. Every other path\n * resolves the row in the router — inside the navigation transition — and\n * hands over a settled value, so a decode rejection surfaces where React\n * renders the tree and is caught by the error boundary *around* it, rather\n * than here, above every boundary the app has.\n */\nexport function PayloadRoot({ source, children }: { source: unknown; children?: React.ReactNode }) {\n  const resolved = isThenable(source) ? use(source) : source;\n  const { params, slotParams } = readPublishedParams(resolved);\n  return createElement(ParamsProvider, { params, slotParams }, children);\n}\n\nfunction isThenable(value: unknown): value is Promise<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { then?: unknown }).then === 'function'\n  );\n}\n","/**\n * useParams() — client-side hook for accessing route params.\n *\n * Returns the dynamic route parameters for the current URL.\n * When called with a route pattern argument, TypeScript narrows\n * the return type to the exact params shape for that route.\n *\n * Two layers of type narrowing work together:\n * 1. The generic overload here uses the Routes interface directly —\n *    `useParams<R>()` returns `Routes[R]['segmentParams']`.\n * 2. Build-time codegen generates per-route string-literal overloads\n *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).\n *\n * When the Routes interface is empty (no codegen yet), the generic\n * overload has `keyof Routes = never`, so only the fallback matches.\n *\n * During SSR, params are read from the ALS-backed SSR data context\n * (populated by ssr-entry.ts) to ensure correct per-request isolation\n * across concurrent requests with streaming Suspense.\n *\n * Reactivity: On the client, useParams() reads from ParamsContext, published\n * by the one provider the client renders above the merge point\n * (`PayloadRoot`). Params update atomically with the tree because they travel\n * on the same payload root — there is no separate channel that could be\n * seeded a render early or late (TIM-1294, TIM-1297).\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n *\n * Design doc: design/09-typescript.md §\"Typed Routes\"\n */\n\nimport type { CoercedParams } from '../shared/param-value.ts';\nimport type { Routes } from '../index.ts';\nimport { getSsrData } from './ssr-data.ts';\nimport {\n  currentParams,\n  currentSlotParams,\n  _setCurrentParams,\n  _setCurrentSlotParams,\n  paramsListeners,\n} from './state.ts';\nimport { resolveSegmentParams, type SlotParamsRecord } from '../shared/slot-params.ts';\nimport { useParamsContext } from './params-context.ts';\n\n// ---------------------------------------------------------------------------\n// Module-level subscribe/notify pattern — kept for backward compat and tests\n// ---------------------------------------------------------------------------\n\n/**\n * Subscribe to params changes.\n * Retained for backward compatibility with tests that verify the\n * subscribe/notify contract. On the client, useParams() reads from\n * NavigationContext instead.\n */\nexport function subscribe(callback: () => void): () => void {\n  paramsListeners.add(callback);\n  return () => paramsListeners.delete(callback);\n}\n\n/**\n * Get the current params snapshot (module-level fallback).\n * Used by tests and by the hook when called outside a React component.\n */\nexport function getSnapshot(): CoercedParams {\n  return currentParams;\n}\n\n// ---------------------------------------------------------------------------\n// Framework API — called by the segment router on each navigation\n// ---------------------------------------------------------------------------\n\n/**\n * Set the current route params in the module-level store.\n *\n * Called by the router on each navigation. This updates the fallback\n * snapshot used by tests and by the hook when called outside a React\n * component (no NavigationContext available).\n *\n * On the client, the primary reactivity path is NavigationContext —\n * the router calls setNavigationState() then renderRoot() which wraps\n * the element in NavigationProvider. setCurrentParams is still called\n * for the module-level fallback.\n *\n * During SSR, params are also available via getSsrData().params\n * (ALS-backed).\n */\nexport function setCurrentParams(params: CoercedParams): void {\n  _setCurrentParams(params);\n}\n\n/**\n * Set the per-slot params snapshot in the module-level store.\n *\n * Paired with `setCurrentParams`: the router calls both on every navigation,\n * including with `null` when a response carries no slot params, so a slot's\n * params from the *previous* route cannot be read on the next one. Fill and\n * serve are paired; so are fill and clear. See TIM-1285.\n */\nexport function setCurrentSlotParams(slotParams: SlotParamsRecord | null): void {\n  _setCurrentSlotParams(slotParams);\n}\n\n/**\n * Notify all legacy subscribers that params have changed.\n *\n * Retained for backward compatibility with tests. On the client,\n * the NavigationContext + renderRoot pattern replaces this — params\n * update atomically with the tree render, so explicit notification\n * is no longer needed.\n */\nexport function notifyParamsListeners(): void {\n  for (const listener of paramsListeners) {\n    listener();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public hook\n// ---------------------------------------------------------------------------\n\n/**\n * Read the current route's dynamic params.\n *\n * The optional `_route` argument exists only for TypeScript narrowing —\n * it does not affect the runtime return value.\n *\n * On the client, reads from ParamsContext, published by `PayloadRoot` above\n * everything the navigation renders. Params update atomically with the RSC\n * tree — no timing gap.\n *\n * During SSR, reads from the ALS-backed SSR data context to ensure\n * per-request isolation across concurrent requests with streaming Suspense.\n *\n * When called outside a React component (e.g., in test assertions),\n * falls back to the module-level snapshot.\n *\n * @overload Typed — when a known segment path is passed, returns the\n *   exact params shape from the generated Routes interface.\n * @overload Fallback — returns the generic params record.\n */\nexport function useSegmentParams<R extends keyof Routes>(\n  segmentPath: R\n): Routes[R] extends { segmentParams: infer P } ? P : CoercedParams;\nexport function useSegmentParams(segmentPath?: string): CoercedParams;\nexport function useSegmentParams(segmentPath?: string): CoercedParams {\n  // Try the client-owned provider first. It sits above everything a navigation\n  // renders, so any component on the page — initial document, full navigation,\n  // or a layout the server skipped — has one above it. Absent during SSR,\n  // where the ALS path below is the answer. When called outside a React\n  // component, useContext throws — caught below.\n  try {\n    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path\n    const paramsContext = useParamsContext();\n    if (paramsContext !== null) {\n      return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);\n    }\n  } catch {\n    // No React dispatcher available (called outside a component).\n    // Fall through to module-level snapshot below.\n  }\n\n  // SSR path: read from ALS-backed SSR data context.\n  // Falls back to module-level currentParams for tests.\n  const ssrData = getSsrData();\n  if (ssrData) return resolveSegmentParams(ssrData.params, ssrData.slotParams, segmentPath);\n  return resolveSegmentParams(currentParams, currentSlotParams, segmentPath);\n}\n"],"mappings":";;;;;;AAGA,SAAS,UAAU,eAAuC;CACxD,MAAM,SAAS,gBAAgB;CAC/B,IAAI,CAAC,QAAQ,aAAa,CAAC;CAC3B,OAAO,OAAO,gBAAgB,aAAa;AAC7C;AAEA,SAAS,cAAuB;CAC9B,MAAM,SAAS,gBAAgB;CAC/B,OAAO,SAAS,OAAO,UAAU,IAAI;AACvC;AAEA,IAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;AAuB1B,SAAgB,uBAAgC;CAC9C,OAAO,qBAAqB,WAAW,aAAa,iBAAiB;AACvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC8CA,IAAM,cAAc,OAAO,IAAI,kBAAkB;AAEjD,SAAS,uBAAwE;CAC/E,MAAM,WAAY,WAAuC;CAGzD,IAAI,aAAa,KAAA,GAAW,OAAO;CAEnC,IAAI,OAAO,MAAM,kBAAkB,YAAY;EAC7C,MAAM,MAAM,MAAM,cAAsC,IAAI;EAC5D,WAAwC,eAAe;EACvD,OAAO;CACT;AAEF;;;;;;AAOA,SAAgB,uBAA+C;CAC7D,MAAM,MAAM,qBAAmB;CAC/B,IAAI,CAAC,KAAK,OAAO;CAEjB,IAAI,OAAO,MAAM,eAAe,YAAY,OAAO;CAEnD,OAAO,MAAM,WAAW,GAAG;AAC7B;;;;;;;AAiBA,SAAgB,mBAAmB,EACjC,OACA,YAC8C;CAC9C,MAAM,MAAM,qBAAmB;CAC/B,IAAI,CAAC,KAEH,OAAO;CAET,OAAO,cAAc,IAAI,UAAU,EAAE,MAAM,GAAG,QAAQ;AACxD;;;;;;;;;;;;;;AAmBA,IAAM,gBAAgB,OAAO,IAAI,oBAAoB;AAErD,SAAS,oBAAkD;CACzD,MAAM,IAAI;CACV,IAAI,CAAC,EAAE,gBACL,EAAE,iBAAiB,EAAE,SAAS;EAAE,UAAU;EAAK,QAAQ;CAAG,EAAE;CAE9D,OAAO,EAAE;AACX;AAEA,SAAgB,mBAAmB,OAA8B;CAC/D,kBAAkB,CAAC,CAAC,UAAU;AAChC;AAEA,SAAgB,qBAAsC;CACpD,OAAO,kBAAkB,CAAC,CAAC;AAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AE3EA,IAAM,qBAAqB,OAAO,IAAI,iCAAiC;AAYvE,SAAS,uBAA0C;CACjD,MAAM,IAAI;CACV,MAAM,WAAW,EAAE;CACnB,IAAI,CAAC,UAAU;EACb,MAAM,UAA6B;GAAE,IAAI;GAAG,yBAAS,IAAI,IAAI;EAAE;EAC/D,EAAE,sBAAsB;EACxB,OAAO;CACT;CAIA,SAAS,4BAAY,IAAI,IAAI;CAC7B,OAAO;AACT;;AAGA,SAAS,wBAAgC;CACvC,MAAM,UAAU,qBAAqB;CACrC,QAAQ,MAAM;CACd,KAAK,MAAM,QAAQ,CAAC,GAAG,QAAQ,OAAO,GAAG,KAAK;CAC9C,OAAO,QAAQ;AACjB;;;;;;;;;;;;;AAcA,SAAgB,iCAAuC;CACrD,sBAAsB;AACxB;;;;;;;;;;;;;;;;;AAmEA,IAAM,eAAe,OAAO,IAAI,0BAA0B;AAE1D,SAAS,kBAAsC;CAC7C,MAAM,IAAI;CACV,IAAI,CAAC,EAAE,eACL,EAAE,gBAAgB,EAAE,OAAO,MAAM;CAEnC,OAAO,EAAE;AACX;;;;;;;AAQA,SAAgB,kBAAkB,OAAsB;CACtD,gBAAgB,CAAC,CAAC,QAAQ;AAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACjKA,IAAM,iBAAiB,OAAO,IAAI,qBAAqB;AAEvD,SAAS,qBAA+D;CACtE,MAAM,QAAQ;CACd,MAAM,WAAW,MAAM;CACvB,IAAI,aAAa,KAAA,GAAW,OAAO;CACnC,IAAI,OAAO,MAAM,kBAAkB,YAGjC;CAEF,MAAM,MAAM,MAAM,cAAyC,IAAI;CAC/D,MAAM,kBAAkB;CACxB,OAAO;AACT;AAEA,IAAM,gBAAgB,mBAAmB;;;;;;;;AASzC,SAAgB,mBAA8C;CAC5D,OAAO,MAAM,WAAW,aAAa;AACvC;;;;;;;;;;;;;;;;;;ACbA,SAAgB,iBAAiB,QAA6B;CAC5D,kBAAkB,MAAM;AAC1B;;;;;;;;;AAUA,SAAgB,qBAAqB,YAA2C;CAC9E,sBAAsB,UAAU;AAClC;AA4CA,SAAgB,iBAAiB,aAAqC;CAMpE,IAAI;EAEF,MAAM,gBAAgB,iBAAiB;EACvC,IAAI,kBAAkB,MACpB,OAAO,qBAAqB,cAAc,QAAQ,cAAc,YAAY,WAAW;CAE3F,QAAQ,CAGR;CAIA,MAAM,UAAU,WAAW;CAC3B,IAAI,SAAS,OAAO,qBAAqB,QAAQ,QAAQ,QAAQ,YAAY,WAAW;CACxF,OAAO,qBAAqB,eAAe,mBAAmB,WAAW;AAC3E"}

package/docs/learn/04-loading-states.mdx

@@ -1,67 +0,0 @@
----
-title: 'You Might Not Need A loading.tsx'
-description: 'When timber commits the HTTP status code and why it matters.'
-slug: 'loading-states'
-notAI: true
----
-
-# You Might Not Need A `loading.tsx`
-
-Most React frameworks push you towards building page-level skeletons or loading states. Though it's entirely trivial to build out that experience with timber, we nudge you away from that for several reasons.
-
-This is not referring to loading states on things like mutations (like submitting a form) or other actions. This is referring to initial (server) or secondary (client) page loading.
-
-This is how we as frontend engineers make browsing the web a less anxiety-inducing experience.
-
-### Loading States Are an Extra Class of UI to Maintain
-
-You have to design loading states. Decide between spinners and skeletons, and then mimic your UI in the skeleton.
-
-### Loading States Cause Content Layout Shift
-
-Loading states are fixed and content is most often dynamic both in size (think text length) and count (think number of rows). So even if you work incredibly hard to avoid major CLS, you'll invariably end up with CLS somewhere.
-
-### Loading States Are a Flash of UI
-
-Loading states are inherently temporary, so this adds flashes of content. This causes anxiety as the page spasms before finally reaching an undetermined final state. The user is left in a daze wondering if the page is finally ready.
-
-Every possible "finite state" of UI is another that you and the user have to keep in context. You'll be _surprised_ how much simpler a website feels when a page has one major representation, vs several.
-
-### Loading States Hide Prior Context
-
-Go to an old PHP site and click a URL. The _browser_ shows a loading state, but the prior page remains visible. The new page only becomes visible once it is ready. There's little advantage to hiding the past context while the user waits for the new context to load.
-
-### timber Includes a Global Route-Based Loading State
-
-On every route change, timber triggers a global page-level toploader loading state. If you want to add a secondary loading state that dims the prior content, you can easily do so.
-
-### Loading States Break JavaScript Disabled Requests
-
-`curl` a page with a `loading.tsx` and you'll get back a shell, not the content. Though people downsell the cost, it genuinely does hinder both SEO and agentic requests.
-
-Leaning on the web as intended is always better than assuming _all_ consumers have JavaScript enabled. Plus, sticking JavaScript in between your _hot_ rendering path is _inherently_ slower. It's just not necessary when you adopt a comprehensive web architecture like React Server Components.
-
-### Loading States Break Status Codes
-
-Loading states flush before the content is even fetched. This feels _faster_, but you are flushing before you know if the user is authenticated, the data exists, or any other class of issue. By flushing immediately, you are forced to send a 200 and lean on JavaScript-injected meta tags to signify errors.
-
-This breaks the contract of the web for any consumer that isn't a human. Use real status codes, you will gain downstream benefits from doing so.
-
-### Most Loading States Paper Over a Bad Data Architecture
-
-People often use loading states because their database is poorly optimized, or 50ms away from their rendering server, or otherwise. With a well designed data infrastructure, you can often fetch your data plenty fast to render your entire page in < 100ms.
-
-And when you can't, you can stream and flush those rare pages trivially.
-
-### Loading States Still Have Value, but More-So as Opt-In Secondary or Tertiary Content
-
-To add a loading state as a small sub-section of a page is trivial – just wrap your component in `<Suspense>` and you can defer slower, lower priority content.
-
-If you decide you want a full page level loading state, you can wrap your layout or page in `<Suspense>` on a case by case basis. No `loading.tsx` needed.
-
-
---------
-
-A `loading.tsx` forces your flush point up ever so slightly, but you give up all the things above. Instead, timber asks you to place `<Suspense>` boundaries yourself – thereby _explicitly_ opting into the flush point.
-
-Now you get a calm, performant website that doesn't have immense content-layout-shift, doesn't hide prior content during loading, and can return proper status codes. The `loading.tsx` seems innocent enough, but its cost both cognitively and architecturally is high.

package/docs/learn/04b-the-flush-point.mdx

@@ -1,115 +0,0 @@
----
-title: 'The Flush Point'
-description: 'When timber commits the HTTP status code and why it matters.'
-slug: 'the-flush-point'
-# notAI: true
----
-
-# The Flush Point
-
-The flush point is when the framework sends the first byte of HTML to the browser and commits the HTTP status code. In a traditional PHP website, this happens all at once.
-
-But modern web frameworks, and notably react server components, have embraced a streaming architecture. Allowing you to send content _after_ the flush point.
-
-While this is ultimately incredibly powerful, it brings forth confusion because contextually, code can have different side effects depending on _when_ you call it.
-
-On a next.js app, if I call `notFound()` inside of a `page.tsx` that has a sibling `loading.tsx` – my status code will return `200`. By obfuscating the flush point, we've actually just made developer clarity murky.
-
-So timber works differently. At no point does timber flush early, unless _you_ (the developer), choose to place a `<Suspense>` boundary. Often this will end up being below your `page.tsx` level, so you'll still have access to controlling and sending proper status codes.
-
-------
-
-AI below..
-
-## The Problem
-
-Most streaming frameworks send a `200 OK` immediately and figure out the real outcome later:
-
-```
-Request → 200 OK → ... render ... → oh, it's a 404
-```
-
-By the time the server discovers the page doesn't exist, the status code is already sent. The client sees `200`. Search engines see `200`. CDNs cache it as `200`.
-
-This breaks search engines (deleted pages never deindex), CDNs (404s get cached as successes), monitoring (zero errors while users see broken pages), and `curl`/scripts (`curl -f` won't detect the failure).
-
-## timber's Solution
-
-timber holds the response until it knows the real outcome:
-
-```
-Request arrives
-  → Route matched
-  → proxy.ts runs
-  → middleware.ts runs
-  → access.ts runs
-  → React shell renders (onShellReady)
-  → ✓ Status code committed ← flush point
-  → Shell HTML sent to browser
-  → Suspense boundaries stream in
-```
-
-The status code commits when **all three** conditions are met:
-
-1. Middleware completed without returning a response
-2. All access checks passed (or denied with a real status code)
-3. React's `onShellReady` fired — the synchronous shell rendered without error
-
-A missing page returns a real `404`. A failed auth check returns a real `403`. A redirect returns a real `302`. The HTTP layer tells the truth.
-
-## Before and After the Flush
-
-**Before the flush** (blocking):
-
-- `proxy.ts` — global request processing
-- `middleware.ts` — route-level request processing
-- `access.ts` — authorization gates
-- Synchronous component rendering (the shell)
-
-**After the flush** (streaming):
-
-- `<Suspense>` boundaries resolve and stream in
-- Slow data loads complete
-- The page progressively fills in
-
-``` leading="none"
-         ┌─────── flush point
-         │
-         ▼
-├────────┤──────────────────────────┤
- blocking    streaming
- (shell)     (suspense boundaries)
-```
-
-Everything before the flush determines the status code. Everything after streams progressively. You control the boundary by choosing what goes inside `<Suspense>` and what doesn't.
-
-## Pages Work Without JavaScript
-
-Because timber holds the flush until the shell is complete, the browser receives a fully-formed HTML document. Content is visible, links work as standard `<a>` tags, and forms submit as standard POSTs. JavaScript adds client-side navigation, interactive components, and streaming updates — but the page works without it.
-
-This isn't a special mode. It's how timber works by default.
-
-## Early Hints
-
-timber doesn't make you wait for assets while the shell renders. At route-match time — before middleware runs — timber sends `103 Early Hints` with CSS, JS, and font URLs. The browser starts downloading assets while the server is still working:
-
-```
-103 Early Hints
-Link: </styles/main.css>; rel=preload; as=style
-Link: </chunks/page-abc.js>; rel=modulepreload
-
-... middleware runs, shell renders ...
-
-200 OK
-<html>...
-```
-
-You get the correctness of a held flush with the performance of early resource loading.
-
-## How to Think About It
-
-Primary content — the data that defines whether a page exists, who can see it, and what it contains — should load before the flush. Put it in your components directly.
-
-Secondary content — recommendations, activity feeds, analytics widgets — can load after the flush. Wrap it in `<Suspense>`.
-
-The flush point is the dividing line between "what the page _is_" and "what the page _also shows_."

package/docs/learn/12-client-navigation.mdx

@@ -1,176 +0,0 @@
----
-title: 'Client Navigation'
-description: 'The Link component, useRouter, segment cache, and scroll restoration.'
-slug: 'client-navigation'
----
-
-# Client Navigation
-
-timber.js supports client-side navigation via the `<Link>` component. Clicking a link fetches an RSC payload from the server and reconciles the DOM without a full page reload.
-
-## `<Link>`
-
-```tsx
-import { Link } from '@timber-js/app/client';
-
-<Link href="/about">About</Link>
-<Link href="/products/123">Product</Link>
-<Link href="/dashboard" replace>Dashboard</Link>
-```
-
-`<Link>` type-checks `href` against the generated route map. Invalid routes produce a TypeScript error.
-
-## `useRouter`
-
-For programmatic navigation:
-
-```tsx title="app/components/logout-button.tsx"
-'use client';
-
-import { useRouter } from '@timber-js/app/client';
-
-declare function logout(): Promise<void>;
-
-export function LogoutButton() {
-  const router = useRouter();
-
-  async function handleLogout() {
-    await logout();
-    router.push('/login');
-  }
-
-  return <button onClick={handleLogout}>Log out</button>;
-}
-```
-
-| Method                 | Description                              |
-| ---------------------- | ---------------------------------------- |
-| `router.push(href)`   | Navigate to a new URL                    |
-| `router.replace(href)` | Navigate without adding a history entry |
-| `router.refresh()`    | Re-fetch the current route's RSC payload |
-| `router.back()`       | Go back in history                       |
-| `router.forward()`    | Go forward in history                    |
-
-## `usePathname`
-
-Returns the current pathname:
-
-```tsx
-'use client';
-import { usePathname, Link } from '@timber-js/app/client';
-
-export function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
-  const pathname = usePathname();
-  const isActive = pathname === href;
-  return (
-    <Link href={href} className={isActive ? 'font-bold' : ''}>
-      {children}
-    </Link>
-  );
-}
-```
-
-## `useSelectedLayoutSegment`
-
-Returns the active segment within a layout — useful for highlighting nav items:
-
-```tsx
-'use client';
-import { useSelectedLayoutSegment } from '@timber-js/app/client';
-
-export function DashboardNav() {
-  const segment = useSelectedLayoutSegment();
-  // segment is "settings", "projects", etc.
-}
-```
-
-## `useLinkStatus`
-
-Track per-link pending state during navigation:
-
-```tsx
-'use client';
-import { Link, useLinkStatus } from '@timber-js/app/client';
-
-function NavItemInner({ children }: { children: React.ReactNode }) {
-  const { isPending } = useLinkStatus();
-  return <span className={isPending ? 'opacity-50' : ''}>{children}</span>;
-}
-
-export function NavItem({ href, children }: { href: string; children: React.ReactNode }) {
-  return (
-    <Link href={href}>
-      <NavItemInner>{children}</NavItemInner>
-    </Link>
-  );
-}
-```
-
-## Segment Cache
-
-Opt-in via `clientSegmentCache: true` in `timber.config.ts`. When enabled, the client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
-
-```ts title="timber.config.ts"
-export default {
-  clientSegmentCache: true,
-};
-```
-
-```
-/dashboard/settings → /dashboard/team
-
-  Root Layout       ← sync, mounted → skip
-  Auth Layout       ← sync, mounted → skip
-  Dashboard Layout  ← sync, mounted → skip
-  Team Page         ← new            → fetch from server
-```
-
-Sync layouts stay cached while mounted. Async layouts always re-render. Pages always re-render. Client component state in shared layouts is preserved — counters, form inputs, scroll positions survive navigation.
-
-When disabled (the default), every client navigation gets a full RSC payload from the server. This is simpler and avoids edge cases with stale cached layouts, at the cost of slightly larger payloads on navigation.
-
-Back/forward navigation replays cached RSC payloads instantly — no server roundtrip.
-
-## Scroll Restoration
-
-- **Forward navigation** scrolls to the top of the page.
-- **Back/forward** restores the saved scroll position.
-- **Hash fragments** — `<Link href="/docs/api#install">` commits the full URL (including the `#fragment`) to the address bar and scrolls to the matching element after render, just like a plain `<a>` without JavaScript. If no element matches, navigation falls back to scroll-to-top.
-
-Pass `scroll={false}` to `<Link>` or `router.push` to preserve the current scroll position:
-
-```tsx
-<Link href="/dashboard/settings" scroll={false}>Settings</Link>
-```
-
-```tsx
-router.push('/dashboard/settings', { scroll: false });
-```
-
-### Custom Scroll Containers
-
-If your layout uses a custom scrollable container, add `data-timber-scroll-restoration`:
-
-```tsx
-<main className="overflow-y-auto h-screen" data-timber-scroll-restoration>
-  {children}
-</main>
-```
-
-## `Link.onNavigate`
-
-Intercept navigation for view transitions:
-
-```tsx
-<Link
-  href="/gallery"
-  onNavigate={(e) => {
-    if (document.startViewTransition) {
-      e.preventDefault();
-      document.startViewTransition(() => e.navigate());
-    }
-  }}
->
-  Gallery
-</Link>
-```