@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.186

package/dist/_chunks/navigation-root-B29qg0_T.js

@@ -0,0 +1,274 @@
+import { n as getRouterOrNull } from "./router-ref-DuYuV_0Q.js";
+import React, { createElement, useSyncExternalStore } from "react";
+//#region src/client/use-pending-navigation.ts
+function subscribe(onStoreChange) {
+	const router = getRouterOrNull();
+	if (!router) return () => {};
+	return router.onPendingChange(onStoreChange);
+}
+function getSnapshot() {
+	const router = getRouterOrNull();
+	return router ? router.isPending() : false;
+}
+var getServerSnapshot = getSnapshot;
+/**
+* Returns true while an RSC navigation is in flight.
+*
+* Reads from the router's external pending store via useSyncExternalStore.
+* Only components that call this hook re-render when pending state
+* changes — no full-tree re-render.
+*
+* ```tsx
+* 'use client'
+* import { usePendingNavigation } from '@timber-js/app/client'
+*
+* export function NavBar() {
+*   const isPending = usePendingNavigation()
+*   return (
+*     <nav className={isPending ? 'opacity-50' : ''}>
+*       <Link href="/dashboard">Dashboard</Link>
+*     </nav>
+*   )
+* }
+* ```
+*/
+function usePendingNavigation() {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+//#endregion
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current pathname and search, updated atomically with the RSC
+* tree on each navigation. This replaces the previous useSyncExternalStore
+* approach for usePathname() and useSearchParams(), which suffered from a
+* timing gap: the new tree could commit before the external store
+* re-renders fired, causing a frame where both old and new active states
+* were visible simultaneously.
+*
+* Segment params are NOT here — see the note on NavigationState below.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (usePathname, useSearchParams) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in usePendingNavigation (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by usePathname() and useSearchParams().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		pathname: "/",
+		search: ""
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+/**
+* There was a second React context here — `PendingNavigationContext`, holding
+* the in-flight navigation URL, provided by `NavigationRoot` out of a
+* `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone
+* (TIM-1307).
+*
+* Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and
+* `TopLoader` both subscribe to the router's external pending store via
+* `useSyncExternalStore`: sync priority, immune to transition entanglement,
+* and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).
+* The context was a parallel representation of the same fact that no consumer
+* ever migrated to, and one that could not even agree with the store — a
+* navigation superseded by a cached popstate replay left its URL set until the
+* next full navigation, because the staleness guard skipped the clear and no
+* other path touched it.
+*
+* One representation, and it is the router's. See
+* design/19-client-navigation.md §"How Pending State Works".
+*/
+//#endregion
+//#region src/client/top-loader.tsx
+/**
+* TopLoader — Built-in progress bar for client navigations.
+*
+* Shows an animated progress bar at the top of the viewport while an RSC
+* navigation is in flight. Injected automatically by the framework into
+* NavigationRoot — users never render this component directly.
+*
+* Configuration is via timber.config.ts `topLoader` key. Enabled by default.
+* Users who want a fully custom progress indicator disable the built-in one
+* (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
+*
+* Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+* width over ~30s using ease-out timing. When navigation completes, the bar
+* snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+*
+* Phase transitions are derived synchronously during render (React's
+* getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+* The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+*
+* When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+* stays invisible during the delay period. If navigation finishes before the
+* delay, the bar was never visible so the finish transition is also invisible.
+*
+* See design/19-client-navigation.md §"usePendingNavigation()"
+* See LOCAL-336 for design decisions.
+*/
+//#endregion
+//#region src/client/navigation-root.tsx
+var NAV_TRANSITION_KEY = Symbol.for("__timber_nav_transition_counter");
+function getTransitionCounter() {
+	const g = globalThis;
+	const existing = g[NAV_TRANSITION_KEY];
+	if (!existing) {
+		const created = {
+			id: 0,
+			waiters: /* @__PURE__ */ new Set()
+		};
+		g[NAV_TRANSITION_KEY] = created;
+		return created;
+	}
+	existing.waiters ??= /* @__PURE__ */ new Set();
+	return existing;
+}
+/** Bump the counter and wake everything waiting on an older transition. */
+function bumpTransitionCounter() {
+	const counter = getTransitionCounter();
+	counter.id += 1;
+	for (const wake of [...counter.waiters]) wake();
+	return counter.id;
+}
+/**
+* Invalidate all in-flight navigation transitions. Any navigateTransition()
+* call whose perform() has not yet committed will reject with AbortError
+* instead of committing its element.
+*
+* Called by the router when a render supersedes in-flight navigations
+* WITHOUT going through navigateTransition() — the cached popstate replay
+* renders via transitionRender(), which doesn't bump the counter, so a
+* stale forward navigation's setElement would otherwise pass the
+* `counter.id !== transId` guard and commit the forward page over the
+* replayed back page (TIM-1022).
+*/
+function supersedeNavigationTransitions() {
+	bumpTransitionCounter();
+}
+/**
+* Module-level flag indicating a hard (MPA) navigation is in progress.
+*
+* When true:
+* - NavigationRoot throws an unresolved thenable to suspend forever,
+*   preventing React from rendering children during page teardown
+*   (avoids "Rendered more hooks" crashes).
+* - The Navigation API handler skips interception, letting the browser
+*   perform a full page load (prevents infinite loops where
+*   window.location.href → navigate event → router.navigate → 500 →
+*   window.location.href → ...).
+*
+* Uses globalThis for singleton guarantee across chunks (same pattern
+* as NavigationContext). See design/19-client-navigation.md §"Singleton
+* Guarantee via globalThis".
+*/
+var HARD_NAV_KEY = Symbol.for("__timber_hard_navigating");
+function getHardNavStore() {
+	const g = globalThis;
+	if (!g[HARD_NAV_KEY]) g[HARD_NAV_KEY] = { value: false };
+	return g[HARD_NAV_KEY];
+}
+/**
+* Set the hard-navigating flag. Call this BEFORE setting
+* window.location.href or window.location.reload() to prevent:
+* 1. React from rendering children during page teardown
+* 2. Navigation API from intercepting the hard navigation
+*/
+function setHardNavigating(value) {
+	getHardNavStore().value = value;
+}
+//#endregion
+export { setNavigationState as a, getNavigationState as i, supersedeNavigationTransitions as n, useNavigationContext as o, NavigationProvider as r, usePendingNavigation as s, setHardNavigating as t };
+
+//# sourceMappingURL=navigation-root-B29qg0_T.js.map

package/dist/_chunks/navigation-root-B29qg0_T.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-root-B29qg0_T.js","names":[],"sources":["../../src/client/use-pending-navigation.ts","../../src/client/navigation-context.ts","../../src/client/top-loader.tsx","../../src/client/navigation-root.tsx"],"sourcesContent":["import { useSyncExternalStore } from 'react';\nimport { getRouterOrNull } from './router-ref.js';\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.js';\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.js';\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.js';\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"],"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,qBAAwE;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,mBAAmB;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,mBAAmB;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"}

package/dist/_chunks/param-value-C8TNYchQ.js

@@ -0,0 +1,66 @@
+//#region src/shared/param-value.ts
+/** The domain, for error messages. Derived, never a second hand-written list. */
+var DOMAIN = `a string, number, boolean, bigint, null, undefined, a plain object, an array, or ${[
+	"Date",
+	"Map",
+	"Set"
+].join("/")}`;
+function reject(path, was, hint) {
+	throw new Error(`[timber] Segment param "${path || "(root)"}" was coerced to ${was}, which cannot cross to the client. A param value may be ${DOMAIN}.\n  ${hint}\n  See design/41-global-params.md §"Transport".`);
+}
+function describe(value) {
+	return value.constructor?.name ?? "an object";
+}
+/**
+* Deep-clone a codec's output into the canonical form, or throw.
+*
+* `seen` accumulates every object the walk has entered, and a second encounter
+* is rejected. That is one rule for two things — a shared reference and a cycle
+* are both "this object again" — and it is what keeps the result a tree.
+*/
+function normalizeParamValue(value, path = "") {
+	return normalize(value, path, /* @__PURE__ */ new Set());
+}
+function normalize(value, path, seen) {
+	if (value === null) return null;
+	const kind = typeof value;
+	if (kind === "string" || kind === "number" || kind === "boolean" || kind === "bigint") return value;
+	if (kind === "undefined") return void 0;
+	if (kind === "function") reject(path, "a function", "Return the data it would produce, not the function.");
+	if (kind === "symbol") reject(path, "a symbol", "Return a string instead — a symbol has no wire representation.");
+	const object = value;
+	if (seen.has(object)) throw new Error(`[timber] Segment param "${path || "(root)"}" is a value that already appears elsewhere in the same param — a shared reference or a cycle. A param value is a tree: React Flight carries a repeated \`Date\` by value and a repeated object by reference, so sharing would survive for some types and not others.\n  Return separate values, or move the shared part outside the params.\n  See design/41-global-params.md §"Transport".`);
+	seen.add(object);
+	if (Array.isArray(object)) {
+		const out = [];
+		for (let index = 0; index < object.length; index++) out.push(normalize(object[index], `${path}[${index}]`, seen));
+		return out;
+	}
+	if (object instanceof Date) return new Date(object.getTime());
+	if (object instanceof Map) {
+		const out = /* @__PURE__ */ new Map();
+		for (const [key, entry] of object) out.set(normalize(key, `${path}<key>`, seen), normalize(entry, `${path}.get(${keyLabel(key)})`, seen));
+		return out;
+	}
+	if (object instanceof Set) {
+		const out = /* @__PURE__ */ new Set();
+		let index = 0;
+		for (const entry of object) out.add(normalize(entry, `${path}[${index++}]`, seen));
+		return out;
+	}
+	const prototype = Object.getPrototypeOf(object);
+	if (prototype !== null && prototype !== Object.prototype) reject(path, `a ${describe(object)} instance`, "Return a plain object with the fields you need.");
+	const out = Object.create(null);
+	for (const key of Object.keys(object)) {
+		if (key === "__proto__") continue;
+		out[key] = normalize(object[key], path ? `${path}.${key}` : key, seen);
+	}
+	return out;
+}
+function keyLabel(key) {
+	return typeof key === "string" ? JSON.stringify(key) : String(key);
+}
+//#endregion
+export { normalizeParamValue as t };
+
+//# sourceMappingURL=param-value-C8TNYchQ.js.map

package/dist/_chunks/param-value-C8TNYchQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-value-C8TNYchQ.js","names":[],"sources":["../../src/shared/param-value.ts"],"sourcesContent":["/**\n * The canonical form of a segment param value.\n *\n * `getSegmentParams()` on the server and `useSegmentParams()` on the client\n * must return the same value — same prototype, same own properties. This\n * module is how that is guaranteed, and the mechanism matters:\n *\n * **Both sides are images of one normalizer.** A codec's output is deep-cloned\n * into a closed canonical domain at coercion time, and *that clone* is what the\n * server returns and what goes on the wire. Server and client agree by\n * construction, because neither holds the codec's original.\n *\n * That replaces predicting what React Flight would do to an arbitrary value.\n * Prediction is what the previous design attempted and it cannot be finished:\n * the question \"will Flight's decode output be observably identical to this\n * input?\" ranges over every way a JS object can carry state that is not in its\n * serialization — own keys, enumerability, symbols, holes, accessors,\n * subclassing, exotic objects — and a `Proxy` defeats it outright, since a\n * lying `getPrototypeOf` trap makes any static check unsound. Twelve review\n * findings on PR #992 were each one more case of that set, and the set does\n * not close.\n *\n * Normalizing closes it. The only remaining question is whether Flight\n * round-trips the normalizer's *output range* — a finite domain we defined,\n * covered by `tests/e2e/segment-params.test.ts` against the real serializer.\n *\n * ## The domain\n *\n * - `undefined`, `null`, `string`, `number`, `boolean`, `bigint`\n * - null-prototype objects, own enumerable string keys only\n * - dense arrays\n * - `Date`, `Map`, `Set` — rebuilt, never the codec's instance\n *\n * ...and it is a **tree**: no value appears twice, and nothing is cyclic.\n * That is not a simplification, it is the last prediction being removed.\n * Flight encodes a `Date` by value at each occurrence but tracks plain objects\n * for reference dedup, so preserving aliasing would carry it across for some\n * types and drop it for others — and knowing which is exactly the kind of\n * guess this design exists to stop making (codex, PR #992). A tree has no\n * sharing to preserve or lose, so what Flight does about it is unobservable.\n *\n * Anything else throws, naming the param and what it was. Note what is *not*\n * a rejection: a `Date` subclass normalizes to a `Date`, a decorated array to\n * a plain one, a sparse array to a dense one, a getter to the value it\n * returned. Those used to be twelve separate checks. They are not divergences\n * any more, because the normalization happens once and both sides see its\n * result — so they need no checks at all.\n *\n * Own properties that Flight would drop (non-enumerable, symbol-keyed) are\n * dropped here instead, symmetrically. Prototype pollution is handled by the\n * same pass: `__proto__` is never copied, and every object is\n * `Object.create(null)` (design/13-security.md #36b/#36c, TIM-873).\n *\n * ## The prototype flip\n *\n * Flight refuses to serialize a null-prototype object, so the canonical form\n * cannot go on the wire as-is. `toPlainRecord` and `toNullProtoRecord` flip\n * the prototype on the way out and back. They are exact inverses and both\n * total, because they only ever see canonical values — there is nothing to\n * validate and no shape to special-case.\n *\n * See design/41-global-params.md §\"Transport\".\n */\n\n/** Types the canonical form rebuilds rather than rejects. */\nconst REBUILT = ['Date', 'Map', 'Set'] as const;\n\n/** The domain, for error messages. Derived, never a second hand-written list. */\nconst DOMAIN = `a string, number, boolean, bigint, null, undefined, a plain object, an array, or ${REBUILT.join('/')}`;\n\nfunction reject(path: string, was: string, hint: string): never {\n  throw new Error(\n    `[timber] Segment param \"${path || '(root)'}\" was coerced to ${was}, which cannot ` +\n      `cross to the client. A param value may be ${DOMAIN}.\\n` +\n      `  ${hint}\\n` +\n      `  See design/41-global-params.md §\"Transport\".`\n  );\n}\n\nfunction describe(value: object): string {\n  return (value as { constructor?: { name?: string } }).constructor?.name ?? 'an object';\n}\n\n/**\n * Deep-clone a codec's output into the canonical form, or throw.\n *\n * `seen` accumulates every object the walk has entered, and a second encounter\n * is rejected. That is one rule for two things — a shared reference and a cycle\n * are both \"this object again\" — and it is what keeps the result a tree.\n */\nexport function normalizeParamValue(value: unknown, path = ''): unknown {\n  return normalize(value, path, new Set());\n}\n\nfunction normalize(value: unknown, path: string, seen: Set<object>): unknown {\n  if (value === null) return null;\n\n  const kind = typeof value;\n  if (kind === 'string' || kind === 'number' || kind === 'boolean' || kind === 'bigint') {\n    return value;\n  }\n  if (kind === 'undefined') return undefined;\n  if (kind === 'function') {\n    reject(path, 'a function', 'Return the data it would produce, not the function.');\n  }\n  if (kind === 'symbol') {\n    reject(path, 'a symbol', 'Return a string instead — a symbol has no wire representation.');\n  }\n\n  const object = value as object;\n  if (seen.has(object)) {\n    throw new Error(\n      `[timber] Segment param \"${path || '(root)'}\" is a value that already appears ` +\n        `elsewhere in the same param — a shared reference or a cycle. A param value is a ` +\n        `tree: React Flight carries a repeated \\`Date\\` by value and a repeated object by ` +\n        `reference, so sharing would survive for some types and not others.\\n` +\n        `  Return separate values, or move the shared part outside the params.\\n` +\n        `  See design/41-global-params.md §\"Transport\".`\n    );\n  }\n  seen.add(object);\n\n  if (Array.isArray(object)) {\n    // Read by index, so holes become `undefined` — on both sides, which is\n    // the point. A subclass and any own properties are left behind for the\n    // same reason: the clone is a plain, dense array either way.\n    const out: unknown[] = [];\n    for (let index = 0; index < object.length; index++) {\n      out.push(normalize((object as unknown[])[index], `${path}[${index}]`, seen));\n    }\n    return out;\n  }\n\n  if (object instanceof Date) {\n    // A fresh Date, so a subclass or an attached property cannot travel half\n    // way and be dropped by the wire.\n    return new Date(object.getTime());\n  }\n\n  if (object instanceof Map) {\n    const out = new Map<unknown, unknown>();\n    for (const [key, entry] of object) {\n      out.set(\n        normalize(key, `${path}<key>`, seen),\n        normalize(entry, `${path}.get(${keyLabel(key)})`, seen)\n      );\n    }\n    return out;\n  }\n\n  if (object instanceof Set) {\n    const out = new Set<unknown>();\n    let index = 0;\n    for (const entry of object) out.add(normalize(entry, `${path}[${index++}]`, seen));\n    return out;\n  }\n\n  // Everything else is judged by its prototype. A `Proxy` can lie here, and\n  // that is fine: whatever it answers, the clone below reads through it once\n  // and both sides see the same snapshot.\n  const prototype = Object.getPrototypeOf(object);\n  if (prototype !== null && prototype !== Object.prototype) {\n    reject(\n      path,\n      `a ${describe(object)} instance`,\n      'Return a plain object with the fields you need.'\n    );\n  }\n\n  // Own *enumerable string* keys only — the rest is what Flight would drop,\n  // so dropping it here keeps the two sides identical. `__proto__` is skipped\n  // rather than copied: it has a language-level setter that would change the\n  // prototype chain of the copy (TIM-655, TIM-855, TIM-873).\n  const out: Record<string, unknown> = Object.create(null);\n  for (const key of Object.keys(object)) {\n    if (key === '__proto__') continue;\n    out[key] = normalize(\n      (object as Record<string, unknown>)[key],\n      path ? `${path}.${key}` : key,\n      seen\n    );\n  }\n  return out;\n}\n\nfunction keyLabel(key: unknown): string {\n  return typeof key === 'string' ? JSON.stringify(key) : String(key);\n}\n\n// ─── Prototype flip ──────────────────────────────────────────────\n\n/**\n * Canonical form → wire form. React Flight rejects a null prototype\n * (\"Classes or null prototypes are not supported\"), so objects cross as plain\n * ones and are restored on arrival.\n */\nexport function toPlainRecord<T>(value: T): T {\n  return reproto(value, {}) as T;\n}\n\n/** Wire form → canonical form. The exact inverse of `toPlainRecord`. */\nexport function toNullProtoRecord<T>(value: T): T {\n  return reproto(value, null) as T;\n}\n\n/**\n * Rebuild a canonical value with objects on `proto`.\n *\n * Total by construction: its input is always canonical, so the cases are the\n * domain and nothing else. No validation, no shape it might not have seen, and\n * no cycle to guard — a canonical value is a tree. That is what moving the\n * checking to `normalizeParamValue` bought.\n */\nfunction reproto(value: unknown, proto: object | null): unknown {\n  if (value === null || typeof value !== 'object') return value;\n\n  const object = value as object;\n\n  // A Date carries no nested values, so it crosses as itself.\n  if (object instanceof Date) return object;\n\n  if (Array.isArray(object)) {\n    return (object as unknown[]).map((item) => reproto(item, proto));\n  }\n\n  if (object instanceof Map) {\n    const out = new Map<unknown, unknown>();\n    for (const [key, entry] of object) out.set(reproto(key, proto), reproto(entry, proto));\n    return out;\n  }\n\n  if (object instanceof Set) {\n    const out = new Set<unknown>();\n    for (const entry of object) out.add(reproto(entry, proto));\n    return out;\n  }\n\n  const out: Record<string, unknown> = proto === null ? Object.create(null) : {};\n  for (const key of Object.keys(object)) {\n    if (key === '__proto__') continue;\n    out[key] = reproto((object as Record<string, unknown>)[key], proto);\n  }\n  return out;\n}\n"],"mappings":";;AAoEA,IAAM,SAAS,oFAAoF;CAHlF;CAAQ;CAAO;AAGmE,CAAA,CAAQ,KAAK,GAAG;AAEnH,SAAS,OAAO,MAAc,KAAa,MAAqB;CAC9D,MAAM,IAAI,MACR,2BAA2B,QAAQ,SAAS,mBAAmB,IAAI,2DACpB,OAAO,OAC/C,KAAK,iDAEd;AACF;AAEA,SAAS,SAAS,OAAuB;CACvC,OAAQ,MAA8C,aAAa,QAAQ;AAC7E;;;;;;;;AASA,SAAgB,oBAAoB,OAAgB,OAAO,IAAa;CACtE,OAAO,UAAU,OAAO,sBAAM,IAAI,IAAI,CAAC;AACzC;AAEA,SAAS,UAAU,OAAgB,MAAc,MAA4B;CAC3E,IAAI,UAAU,MAAM,OAAO;CAE3B,MAAM,OAAO,OAAO;CACpB,IAAI,SAAS,YAAY,SAAS,YAAY,SAAS,aAAa,SAAS,UAC3E,OAAO;CAET,IAAI,SAAS,aAAa,OAAO,KAAA;CACjC,IAAI,SAAS,YACX,OAAO,MAAM,cAAc,qDAAqD;CAElF,IAAI,SAAS,UACX,OAAO,MAAM,YAAY,gEAAgE;CAG3F,MAAM,SAAS;CACf,IAAI,KAAK,IAAI,MAAM,GACjB,MAAM,IAAI,MACR,2BAA2B,QAAQ,SAAS,6XAM9C;CAEF,KAAK,IAAI,MAAM;CAEf,IAAI,MAAM,QAAQ,MAAM,GAAG;EAIzB,MAAM,MAAiB,CAAC;EACxB,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,QAAQ,SACzC,IAAI,KAAK,UAAW,OAAqB,QAAQ,GAAG,KAAK,GAAG,MAAM,IAAI,IAAI,CAAC;EAE7E,OAAO;CACT;CAEA,IAAI,kBAAkB,MAGpB,OAAO,IAAI,KAAK,OAAO,QAAQ,CAAC;CAGlC,IAAI,kBAAkB,KAAK;EACzB,MAAM,sBAAM,IAAI,IAAsB;EACtC,KAAK,MAAM,CAAC,KAAK,UAAU,QACzB,IAAI,IACF,UAAU,KAAK,GAAG,KAAK,QAAQ,IAAI,GACnC,UAAU,OAAO,GAAG,KAAK,OAAO,SAAS,GAAG,EAAE,IAAI,IAAI,CACxD;EAEF,OAAO;CACT;CAEA,IAAI,kBAAkB,KAAK;EACzB,MAAM,sBAAM,IAAI,IAAa;EAC7B,IAAI,QAAQ;EACZ,KAAK,MAAM,SAAS,QAAQ,IAAI,IAAI,UAAU,OAAO,GAAG,KAAK,GAAG,QAAQ,IAAI,IAAI,CAAC;EACjF,OAAO;CACT;CAKA,MAAM,YAAY,OAAO,eAAe,MAAM;CAC9C,IAAI,cAAc,QAAQ,cAAc,OAAO,WAC7C,OACE,MACA,KAAK,SAAS,MAAM,EAAE,YACtB,iDACF;CAOF,MAAM,MAA+B,OAAO,OAAO,IAAI;CACvD,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;EACrC,IAAI,QAAQ,aAAa;EACzB,IAAI,OAAO,UACR,OAAmC,MACpC,OAAO,GAAG,KAAK,GAAG,QAAQ,KAC1B,IACF;CACF;CACA,OAAO;AACT;AAEA,SAAS,SAAS,KAAsB;CACtC,OAAO,OAAO,QAAQ,WAAW,KAAK,UAAU,GAAG,IAAI,OAAO,GAAG;AACnE"}

package/dist/_chunks/{plugin-context---kTF5v8.js → plugin-context-DEGLSJs3.js}

@@ -182,6 +182,7 @@ function createPluginContext(config, root) {
 		appDir: join(projectRoot, "app"),
 		root: projectRoot,
 		dev: false,
+		base: "/",
 		buildManifest: null,
 		deploymentId: null,
 		timer: createStartupTimer(),
@@ -312,4 +313,4 @@ function mergeFileConfig(inline, fileConfig) {
 //#endregion
 export { resolveAppDir as a, createNoopTimer as c, plugin_context_exports as i, loadTimberConfigFile as n, resolveBuildDir as o, mergeFileConfig as r, resolveClientJavascript as s, createPluginContext as t };
 
-//# sourceMappingURL=plugin-context---kTF5v8.js.map
+//# sourceMappingURL=plugin-context-DEGLSJs3.js.map

package/dist/_chunks/plugin-context-DEGLSJs3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-context-DEGLSJs3.js","names":[],"sources":["../../src/utils/startup-timer.ts","../../src/plugin-context.ts"],"sourcesContent":["/**\n * Startup timer — records named phases with their durations.\n *\n * Used by the plugin system to instrument cold start and report a\n * timing breakdown in dev mode. Zero overhead in production (disabled).\n *\n * See design/18-build-system.md, TIM-155.\n */\n\nimport { performance } from 'node:perf_hooks';\n\nexport interface PhaseRecord {\n  name: string;\n  startMs: number;\n  durationMs: number;\n}\n\nexport interface StartupTimer {\n  /** Mark the beginning of a named phase. */\n  start(phase: string): void;\n  /** Mark the end of a named phase. Returns duration in ms. */\n  end(phase: string): number;\n  /** Get all completed phase records, ordered by start time. */\n  getPhases(): PhaseRecord[];\n  /** Total elapsed time from first start() to last end(). */\n  totalMs(): number;\n  /** Format a human-readable summary string. */\n  formatSummary(): string;\n}\n\n/**\n * Create a startup timer that records phase durations.\n */\nexport function createStartupTimer(): StartupTimer {\n  const pending = new Map<string, number>();\n  const phases: PhaseRecord[] = [];\n\n  return {\n    start(phase: string): void {\n      pending.set(phase, performance.now());\n    },\n\n    end(phase: string): number {\n      const startMs = pending.get(phase);\n      if (startMs === undefined) {\n        return 0;\n      }\n      pending.delete(phase);\n      const durationMs = performance.now() - startMs;\n      phases.push({ name: phase, startMs, durationMs });\n      return durationMs;\n    },\n\n    getPhases(): PhaseRecord[] {\n      return [...phases].sort((a, b) => a.startMs - b.startMs);\n    },\n\n    totalMs(): number {\n      if (phases.length === 0) return 0;\n      const sorted = this.getPhases();\n      const first = sorted[0];\n      const last = sorted[sorted.length - 1];\n      return last.startMs + last.durationMs - first.startMs;\n    },\n\n    formatSummary(): string {\n      const sorted = this.getPhases();\n      if (sorted.length === 0) return 'No phases recorded.';\n\n      const lines = sorted.map((p) => {\n        const ms = p.durationMs.toFixed(1);\n        return `  ${p.name.padEnd(30)} ${ms.padStart(8)}ms`;\n      });\n\n      const total = this.totalMs().toFixed(1);\n      lines.push(`  ${'total'.padEnd(30)} ${total.padStart(8)}ms`);\n\n      return ['[timber] startup timing:', ...lines].join('\\n');\n    },\n  };\n}\n\n/**\n * No-op timer for production builds — all methods are empty.\n */\nexport function createNoopTimer(): StartupTimer {\n  return {\n    start() {},\n    end() {\n      return 0;\n    },\n    getPhases() {\n      return [];\n    },\n    totalMs() {\n      return 0;\n    },\n    formatSummary() {\n      return '';\n    },\n  };\n}\n","/**\n * Plugin context — internal types and helpers for timber sub-plugins.\n *\n * These are NOT part of the user-facing API. They are consumed by\n * sub-plugins (routing, entries, shims, etc.) via relative imports.\n * The root entry point (index.ts) does not re-export them.\n *\n * Design doc: 18-build-system.md §\"Shared Plugin Context\"\n */\n\nimport { existsSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { createRequire } from 'node:module';\nimport { parseAst } from 'vite';\nimport type { RouteTree } from './routing/types';\nimport type { BuildManifest } from './server/build-manifest';\nimport type { CaptureSummary } from './server/prebuilt-builder';\nimport type { StartupTimer } from './utils/startup-timer';\nimport { createStartupTimer } from './utils/startup-timer';\nimport type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';\nimport type { RscManifest } from './plugins/static-build.js';\nimport type { HoldingServer } from './dev-tools/holding-server.js';\nimport type { ProgramNode } from './plugins/callsite-ast.js';\n\n// Re-export for sub-plugin convenience — they import from plugin-context.ts\nexport type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';\n\n// ── Client JavaScript config ─────────────────────────────────────────────\n\n/** Fully resolved client JavaScript configuration (no optionals). */\nexport interface ResolvedClientJavascript {\n  disabled: boolean;\n  enableHMRInDev: boolean;\n}\n\n/**\n * Resolve `clientJavascript` into a fully resolved config.\n */\nexport function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {\n  if (config.clientJavascript !== undefined) {\n    if (typeof config.clientJavascript === 'boolean') {\n      return {\n        disabled: !config.clientJavascript,\n        enableHMRInDev: !config.clientJavascript,\n      };\n    }\n    return {\n      disabled: config.clientJavascript.disabled,\n      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,\n    };\n  }\n  return { disabled: false, enableHMRInDev: false };\n}\n\n// ── Plugin Context ────────────────────────────────────────────────────────\n\n/**\n * Shared context object passed to all sub-plugins via closure.\n *\n * Sub-plugins communicate through this context — not through Vite's\n * plugin API or global state.\n * See design/18-build-system.md §\"Shared Plugin Context\".\n */\nexport interface PluginContext {\n  config: TimberUserConfig;\n  /** Resolved client JavaScript configuration */\n  clientJavascript: ResolvedClientJavascript;\n  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */\n  routeTree: RouteTree | null;\n  /** Absolute path to the app/ directory */\n  appDir: string;\n  /** Absolute path to the project root */\n  root: string;\n  /** Whether the dev server is running (set by timber-root-sync in configResolved) */\n  dev: boolean;\n  /**\n   * Vite's resolved `base` (set by timber-root-sync in configResolved).\n   * Always has a trailing slash; `'/'` unless the app is deployed under a\n   * sub-path. Every URL the framework emits — assets, fonts, RSC payloads —\n   * carries this prefix. This is the single copy: sub-plugins read it here\n   * rather than capturing `config.base` in their own configResolved.\n   *\n   * **Availability:** written by timber-root-sync, which has no `enforce`, so\n   * it is populated from `buildStart`/`load`/`generateBundle`/`configureServer`\n   * onward — but NOT during the `configResolved` of an `enforce: 'pre'`\n   * plugin, which Vite runs first. A pre plugin that needs the base inside\n   * its own `configResolved` must read `config.base` there (timber-fonts\n   * does). See TIM-1261.\n   */\n  base: string;\n  /** CSS build manifest (populated by adapter after client build, null in dev) */\n  buildManifest: BuildManifest | null;\n  /** Per-build deployment ID for version skew detection (null in dev) */\n  deploymentId: string | null;\n  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */\n  timer: StartupTimer;\n  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */\n  holdingServer?: HoldingServer | null;\n  /**\n   * Resolved absolute path to the build output directory.\n   *\n   * Defaults to `<root>/.timber/dist`. Can be overridden via\n   * `timber.config.ts` `buildDir` or Vite's `build.outDir`.\n   * Timber config takes precedence when both are set.\n   *\n   * Used by adapter-build and cli preview.\n   */\n  buildDir: string;\n  /**\n   * Per-route client reference keys captured during the RSC build.\n   * Maps absolute route file paths to the set of client reference\n   * hash keys they transitively import. Used by adapter-build to\n   * populate per-route modulepreload entries from clientReferenceDeps.\n   */\n  routeClientRefKeys?: Map<string, Set<string>>;\n  /**\n   * Static request-dependency verdict per segment entry file, keyed by the\n   * absolute `filePath` the route scanner produced. Computed once by\n   * `timber-request-dep`'s RSC `buildEnd` and serialized into\n   * `buildManifest.requestDep` by `timber-build-manifest` (build only — dev\n   * answers the same question through the `Symbol.for('timber:request-dep')`\n   * bridge instead).\n   *\n   * `undefined` and `{}` are different states and the difference is the whole\n   * of TIM-1300: an empty object means the analysis ran and found no segments,\n   * `undefined` means it never ran, and the runtime cannot tell them apart —\n   * every key is absent either way, so every segment falls to the conservative\n   * `true` and nothing is ever skipped. The build fails loudly on `undefined`\n   * rather than shipping that silently.\n   */\n  requestDepMap?: Record<string, boolean>;\n  /**\n   * Maps absolute module IDs of client references in non-facade RSC\n   * chunks to the absolute paths of their consuming facade modules.\n   * Built during the RSC `generateBundle` phase by timber-chunks,\n   * consumed by `clientChunkGroup` to reclassify `shared:` modules\n   * that are only used by a single route boundary.\n   * See design/27-chunking-strategy.md, TIM-1107.\n   */\n  sharedModuleFacades?: Map<string, string[]>;\n  /**\n   * Module ID → prebuilt component IDs declared in it. Recorded by the\n   * timber-prebuilt transform (RSC environment, production builds only),\n   * consumed by the RSC `generateBundle` module-graph walk that computes\n   * `routePrebuiltComponents`. See design/44-render-at-build-time.md.\n   */\n  prebuiltModuleComponents?: Map<string, string[]>;\n  /**\n   * Module ID → mapping of variable name to component ID for the prebuilt\n   * components declared in that module. Used at `generateBundle` time to\n   * trace imports from other modules back to specific component IDs.\n   */\n  prebuiltBindingNames?: Map<string, Map<string, string>>;\n  /**\n   * Component ID → distinct static call-site prop objects captured from\n   * JSX usage sites during the transform and generateBundle phases.\n   * Consumed by the post-build capture pass to render with actual props\n   * instead of empty `{}`. See design/44 §Props Derivation.\n   */\n  prebuiltCallSiteProps?: Map<string, Record<string, unknown>[]>;\n  /**\n   * Route file path (page or layout, absolute) → prebuilt component IDs\n   * transitively reachable from it. Computed during RSC `generateBundle`,\n   * consumed by the post-build capture pass (TIM-1119) to decide which\n   * components to render under which route's param combos.\n   */\n  routePrebuiltComponents?: Map<string, string[]>;\n  /**\n   * Page file paths that were desugared from `export const prerender` by\n   * timber-prerender-sugar. The prebuilt transform uses this to verify\n   * the generated `cache.component(...)` call was picked up.\n   */\n  prerenderSugarPages?: Set<string>;\n  /**\n   * Component ID → built chunk file name for prebuilt-declaring modules\n   * that are only reachable via dynamic imports (import.meta.glob, lazy\n   * routes). The capture pass imports these chunks to trigger\n   * cache.component() registration before rendering. Populated during\n   * RSC generateBundle alongside routePrebuiltComponents.\n   */\n  prebuiltLazyChunks?: Map<string, string>;\n  /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */\n  captureSummary?: CaptureSummary;\n  /**\n   * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar\n   * transforms. Collapses both cross-plugin and cross-environment duplicate\n   * parses: identical code hits, rewritten code misses (correct because Vite\n   * transforms chain — a rewrite produces different code). Bounded LRU (32\n   * entries) so it doesn't hold programs for the whole build.\n   *\n   * Consumers MUST treat the returned ProgramNode as read-only — they collect\n   * ranges and rewrite CODE via MagicString; the AST itself is never mutated.\n   */\n  parseCached?: ParseMemo;\n  /**\n   * Content-Type mappings for extensionless static API route outputs.\n   * Populated during static generation, consumed by adapter-build to\n   * write per-path Content-Type rules in _headers. See TIM-1241.\n   */\n  staticContentTypes?: Record<string, string>;\n  /**\n   * RSC flight payload manifest mapping unhashed → hashed URLs.\n   * Populated during static generation, consumed by adapters to set\n   * immutable cache headers for `_rsc/` files. See TIM-1254.\n   */\n  rscManifest?: RscManifest;\n}\n\n// ── AST parse memo ───────────────────────────────────────────────────────\n\nconst PARSE_MEMO_CAPACITY = 32;\n\n/**\n * Content-keyed LRU memo for `parseAst`. Transforms for the same module run\n * back-to-back across plugins and environments, so a tiny window captures the\n * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.\n */\nexport class ParseMemo {\n  private cache = new Map<string, ProgramNode>();\n\n  /**\n   * Parse code, returning a cached ProgramNode if the same code was parsed\n   * before. The returned AST MUST NOT be mutated — it may be shared across\n   * multiple consumers.\n   */\n  parse(code: string): ProgramNode {\n    const existing = this.cache.get(code);\n    if (existing) {\n      // LRU refresh: move to end\n      this.cache.delete(code);\n      this.cache.set(code, existing);\n      return existing;\n    }\n    const program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;\n    if (this.cache.size >= PARSE_MEMO_CAPACITY) {\n      // Evict oldest (first inserted)\n      const firstKey = this.cache.keys().next().value!;\n      this.cache.delete(firstKey);\n    }\n    this.cache.set(code, program);\n    return program;\n  }\n\n  get size(): number {\n    return this.cache.size;\n  }\n}\n\n// ── App directory resolution ──────────────────────────────────────────────\n\n/**\n * Resolve the app directory. Checks (in order):\n * 1. Explicit `configAppDir` from timber.config.ts\n * 2. `<root>/app`\n * 3. `<root>/src/app`\n *\n * Throws if none exist.\n */\nexport function resolveAppDir(root: string, configAppDir?: string): string {\n  if (configAppDir) {\n    const explicit = join(root, configAppDir);\n    if (!existsSync(explicit)) {\n      throw new Error(`[timber] Configured appDir \"${configAppDir}\" does not exist at ${explicit}`);\n    }\n    return explicit;\n  }\n\n  const rootApp = join(root, 'app');\n  if (existsSync(rootApp)) return rootApp;\n\n  const srcApp = join(root, 'src', 'app');\n  if (existsSync(srcApp)) return srcApp;\n\n  throw new Error(\n    `[timber] Could not find app directory. Expected \"app/\" or \"src/app/\" in ${root}. ` +\n      `You can set appDir in timber.config.ts to specify a custom location.`\n  );\n}\n\n// ── Plugin context factory ────────────────────────────────────────────────\n\nexport function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {\n  const projectRoot = root ?? process.cwd();\n  const resolvedConfig: TimberUserConfig = { ...config };\n  return {\n    config: resolvedConfig,\n    clientJavascript: resolveClientJavascript(resolvedConfig),\n    routeTree: null,\n    appDir: join(projectRoot, 'app'),\n    root: projectRoot,\n    dev: false,\n    base: '/',\n    buildManifest: null,\n    deploymentId: null,\n    timer: createStartupTimer(),\n    holdingServer: null,\n    buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),\n    parseCached: new ParseMemo(),\n  };\n}\n\n// ── Build directory resolution ────────────────────────────────────────────\n\n/** Default build output directory (relative to root). */\nexport const DEFAULT_BUILD_DIR = join('.timber', 'dist');\n\n/**\n * Resolve the build output directory.\n *\n * Priority:\n * 1. Explicit `timberBuildDir` from timber.config.ts\n * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')\n * 3. Default: `.timber/dist`\n *\n * Returns an absolute path.\n */\nexport function resolveBuildDir(\n  root: string,\n  timberBuildDir?: string,\n  viteBuildOutDir?: string\n): string {\n  if (timberBuildDir) {\n    return resolve(root, timberBuildDir);\n  }\n  if (viteBuildOutDir && viteBuildOutDir !== 'dist') {\n    return resolve(root, viteBuildOutDir);\n  }\n  return join(root, DEFAULT_BUILD_DIR);\n}\n\n// ── Config file loading ───────────────────────────────────────────────────\n\n/**\n * Map known timber.config load failures to actionable hints (TIM-1040).\n * Returns null when the error has no known remedy beyond its own message.\n *\n * Known failure modes of loading timber.config.ts via native require():\n * - Node < 22.18 has no default type stripping → ERR_UNKNOWN_FILE_EXTENSION\n * - Non-erasable TS syntax (enums, namespaces, parameter properties)\n *   → ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX / ERR_INVALID_TYPESCRIPT_SYNTAX\n * - ESM syntax in a `\"type\": \"commonjs\"` package → the stripped .ts is\n *   parsed as CJS and throws SyntaxError: \"Unexpected token 'export'\"\n *   (export statements) or \"Cannot use import statement outside a\n *   module\" (import statements)\n */\nexport function configLoadHint(configName: string, err: unknown): string | null {\n  const code = (err as NodeJS.ErrnoException | null)?.code;\n  const isTs = configName.endsWith('.ts');\n\n  if (isTs && code === 'ERR_UNKNOWN_FILE_EXTENSION') {\n    return (\n      'Loading a TypeScript config requires Node.js 22.18+ (built-in type stripping). ' +\n      'Upgrade Node.js or rewrite the config as timber.config.js.'\n    );\n  }\n  if (code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX' || code === 'ERR_INVALID_TYPESCRIPT_SYNTAX') {\n    return (\n      'Node.js loads the config with type stripping, which only supports erasable TypeScript syntax — ' +\n      'replace enums, namespaces, and constructor parameter properties with plain objects and types.'\n    );\n  }\n  if (\n    isTs &&\n    err instanceof SyntaxError &&\n    /Unexpected token '(export|import)'|Cannot use import statement outside a module/.test(\n      err.message\n    )\n  ) {\n    return (\n      'The config uses ESM syntax but Node.js parsed it as CommonJS — ' +\n      'set \"type\": \"module\" in package.json, or use module.exports instead of export default.'\n    );\n  }\n  return null;\n}\n\n/**\n * Load timber.config.ts (or .js, .mjs) from the project root.\n * Returns the config object or null if no config file is found.\n * Throws a descriptive error naming the file when a config file exists\n * but fails to load — a broken config must fail loudly, never silently\n * degrade (see TIM-1066). Known failure modes get an actionable hint\n * appended (see configLoadHint, TIM-1040).\n *\n * Uses require() — Node 22.12+ can require() ESM modules, and Node\n * 22.18+ strips types from .ts files by default (hence the engines\n * field requiring >=22.18.0). This keeps timber() synchronous — no\n * async config loading needed.\n * This is the single config loader — dev, build, and preview all use it.\n */\nexport function loadTimberConfigFile(root: string): TimberUserConfig | null {\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n  const req = createRequire(join(root, 'package.json'));\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      try {\n        const mod = req(configPath);\n        return (mod.default ?? mod) as TimberUserConfig;\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        const hint = configLoadHint(name, err);\n        throw new Error(\n          `[timber] Failed to load ${configPath}: ${message}${hint ? `\\n${hint}` : ''}`,\n          { cause: err }\n        );\n      }\n    }\n  }\n  return null;\n}\n\n/**\n * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)\n * and warn the user. The `output` key is excluded because it defaults to 'server'\n * in createPluginContext and would always appear as an inline key.\n *\n * Returns the list of conflicting key names (for testing).\n */\nexport function warnConfigConflicts(\n  inline: TimberUserConfig,\n  fileConfig: TimberUserConfig\n): string[] {\n  const conflicts: string[] = [];\n  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {\n    if (key in inline && inline[key] !== undefined) {\n      conflicts.push(key);\n    }\n  }\n  if (conflicts.length > 0) {\n    console.warn(\n      `[timber] Config conflict: ${conflicts.map((k) => `\"${k}\"`).join(', ')} set in both ` +\n        `vite.config.ts (inline) and timber.config.ts. ` +\n        `Move all config to timber.config.ts to avoid confusion. ` +\n        `The inline value from vite.config.ts will be used.`\n    );\n  }\n  return conflicts;\n}\n\n/**\n * Drop own keys whose value is `undefined` so they don't clobber file\n * config during spread merging. `timber({ buildDir: process.env.BUILD_DIR })`\n * with the var unset must not erase the timber.config.ts value.\n */\nfunction stripUndefined<T extends object>(obj: T): T {\n  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as T;\n}\n\n/**\n * Merge file-based config (timber.config.ts) with inline config (vite.config.ts).\n * Inline config takes precedence — file config only fills in missing fields.\n * Inline keys explicitly set to `undefined` are treated as absent, matching\n * the `!== undefined` check in warnConfigConflicts.\n */\nexport function mergeFileConfig(\n  inline: TimberUserConfig,\n  fileConfig: TimberUserConfig\n): TimberUserConfig {\n  warnConfigConflicts(inline, fileConfig);\n  const definedInline = stripUndefined(inline);\n\n  return {\n    ...fileConfig,\n    ...definedInline,\n    ...(fileConfig.limits && definedInline.limits\n      ? { limits: { ...fileConfig.limits, ...stripUndefined(definedInline.limits) } }\n      : {}),\n    ...(fileConfig.dev && definedInline.dev\n      ? { dev: { ...fileConfig.dev, ...stripUndefined(definedInline.dev) } }\n      : {}),\n    ...(fileConfig.mdx && definedInline.mdx\n      ? { mdx: { ...fileConfig.mdx, ...stripUndefined(definedInline.mdx) } }\n      : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/_chunks/{router-ref-CtmF-aPv.js → router-ref-DuYuV_0Q.js}

@@ -1,4 +1,4 @@
-import { o as _setGlobalRouter, u as globalRouter } from "./ssr-data-BOWsq18U.js";
+import { p as globalRouter, s as _setGlobalRouter } from "./ssr-data-14MXm7Pj.js";
 //#region src/client/router-ref.ts
 /**
 * Set the global router instance. Called once during bootstrap.
@@ -25,4 +25,4 @@ function getRouterOrNull() {
 //#endregion
 export { getRouterOrNull as n, setGlobalRouter as r, getRouter as t };
 
-//# sourceMappingURL=router-ref-CtmF-aPv.js.map
+//# sourceMappingURL=router-ref-DuYuV_0Q.js.map

package/dist/_chunks/router-ref-DuYuV_0Q.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-ref-DuYuV_0Q.js","names":[],"sources":["../../src/client/router-ref.ts"],"sourcesContent":["// Global router reference — shared between browser-entry and client hooks.\n//\n// Delegates to client/state.ts for the actual module-level variable.\n// This ensures singleton semantics regardless of import path — all\n// callers converge on the same state.ts instance via the barrel.\n//\n// See design/18-build-system.md §\"Module Singleton Strategy\"\n\nimport type { RouterInstance } from './router-types.js';\nimport { globalRouter, _setGlobalRouter } from './state.js';\n\n/**\n * Set the global router instance. Called once during bootstrap.\n */\nexport function setGlobalRouter(router: RouterInstance): void {\n  _setGlobalRouter(router);\n}\n\n/**\n * Get the global router instance. Throws if called before bootstrap.\n * Used by client-side hooks (usePendingNavigation, etc.)\n */\nexport function getRouter(): RouterInstance {\n  if (!globalRouter) {\n    throw new Error('[timber] Router not initialized. getRouter() was called before bootstrap().');\n  }\n  return globalRouter;\n}\n\n/**\n * Get the global router instance or null if not yet initialized.\n * Used by useRouter() methods to avoid silent failures — callers\n * can log a meaningful warning instead of silently no-oping.\n */\nexport function getRouterOrNull(): RouterInstance | null {\n  return globalRouter;\n}\n\n/**\n * Reset the global router to null. Used only in tests to isolate\n * module-level state between test cases.\n * @internal\n */\nexport function resetGlobalRouter(): void {\n  _setGlobalRouter(null);\n}\n"],"mappings":";;;;;AAcA,SAAgB,gBAAgB,QAA8B;CAC5D,iBAAiB,MAAM;AACzB;;;;;AAMA,SAAgB,YAA4B;CAC1C,IAAI,CAAC,cACH,MAAM,IAAI,MAAM,6EAA6E;CAE/F,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAyC;CACvD,OAAO;AACT"}