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

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

@@ -0,0 +1,233 @@
+import { n as getRouterOrNull } from "./router-ref-8gr8qsxN.js";
+import { createContext, createElement, useContext, 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, the wrapper chain mounts this same provider with the
+* request's pathname and raw search string (TIM-1424), so the hooks
+* resolve through the identical code path on both sides. Per-request
+* isolation is by construction — the value is part of the request's
+* element tree.
+*
+* This module is `'use client'` and is never evaluated in the RSC
+* environment. The shims plugin resolves next/navigation to
+* navigation-rsc.ts in RSC, which has throwing stubs (TIM-1420).
+*
+* 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"
+*/
+/**
+* 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.
+*
+* This module is `'use client'` so it is never evaluated in the RSC
+* environment — `createContext` and `useContext` are always available.
+* The shims plugin resolves next/navigation to navigation-rsc.ts in RSC,
+* which has throwing stubs for the hooks (TIM-1420).
+*
+* 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;
+	const ctx = createContext(null);
+	globalThis[NAV_CTX_KEY] = ctx;
+	return ctx;
+}
+/**
+* Read the navigation context. Returns null only when no provider is above
+* the caller — a component rendered outside the timber app.
+*
+* Internal — used by usePathname() and useSearchParams().
+*/
+function useNavigationContext() {
+	return useContext(getOrCreateContext());
+}
+/**
+* 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 }) {
+	return createElement(getOrCreateContext().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
+/**
+* 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 { useNavigationContext as a, setNavigationState as i, NavigationProvider as n, usePendingNavigation as o, getNavigationState as r, setHardNavigating as t };
+
+//# sourceMappingURL=navigation-root-B00jjGd5.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-root-B00jjGd5.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.ts';\n\nfunction subscribe(onStoreChange: () => void): () => void {\n  const router = getRouterOrNull();\n  if (!router) return () => {};\n  return router.onPendingChange(onStoreChange);\n}\n\nfunction getSnapshot(): boolean {\n  const router = getRouterOrNull();\n  return router ? router.isPending() : false;\n}\n\nconst getServerSnapshot = getSnapshot;\n\n/**\n * Returns true while an RSC navigation is in flight.\n *\n * Reads from the router's external pending store via useSyncExternalStore.\n * Only components that call this hook re-render when pending state\n * changes — no full-tree re-render.\n *\n * ```tsx\n * 'use client'\n * import { usePendingNavigation } from '@timber-js/app/client'\n *\n * export function NavBar() {\n *   const isPending = usePendingNavigation()\n *   return (\n *     <nav className={isPending ? 'opacity-50' : ''}>\n *       <Link href=\"/dashboard\">Dashboard</Link>\n *     </nav>\n *   )\n * }\n * ```\n */\nexport function usePendingNavigation(): boolean {\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n","'use client';\n\n/**\n * NavigationContext — React context for navigation state.\n *\n * Holds the current pathname and search, updated atomically with the RSC\n * tree on each navigation. This replaces the previous useSyncExternalStore\n * approach for usePathname() and useSearchParams(), which suffered from a\n * timing gap: the new tree could commit before the external store\n * re-renders fired, causing a frame where both old and new active states\n * were visible simultaneously.\n *\n * Segment params are NOT here — see the note on NavigationState below.\n *\n * By wrapping the RSC payload element in NavigationProvider inside\n * renderRoot(), the context value and the element tree are passed to\n * reactRoot.render() in the same call — atomic by construction.\n * All consumers (usePathname, useSearchParams) see the new values in the\n * same render pass as the new tree.\n *\n * During SSR, the wrapper chain mounts this same provider with the\n * request's pathname and raw search string (TIM-1424), so the hooks\n * resolve through the identical code path on both sides. Per-request\n * isolation is by construction — the value is part of the request's\n * element tree.\n *\n * This module is `'use client'` and is never evaluated in the RSC\n * environment. The shims plugin resolves next/navigation to\n * navigation-rsc.ts in RSC, which has throwing stubs (TIM-1420).\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 { createContext, useContext, createElement, type ReactNode } from 'react';\nimport type { SlotParamsRecord } from '../shared/slot-params.ts';\n\n// ---------------------------------------------------------------------------\n// Context type\n// ---------------------------------------------------------------------------\n\n/**\n * What the browser knows about the current location.\n *\n * Params are deliberately absent: they are a property of the tree the server\n * rendered, not of the address bar, and they now travel inside the payload as\n * the payload root. Keeping a copy here meant the router had to thread\n * the record from a response header into context on every path — navigation,\n * traversal, prefetch, revalidation — and each of those was a place to drop it\n * (TIM-1294).\n */\nexport interface NavigationState {\n  pathname: string;\n  search: string;\n}\n\n// ---------------------------------------------------------------------------\n// Lazy context initialization\n// ---------------------------------------------------------------------------\n\n/**\n * 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 * This module is `'use client'` so it is never evaluated in the RSC\n * environment — `createContext` and `useContext` are always available.\n * The shims plugin resolves next/navigation to navigation-rsc.ts in RSC,\n * which has throwing stubs for the hooks (TIM-1420).\n *\n * See design/27-chunking-strategy.md §\"Singleton Safety\"\n */\n\nconst NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');\n\nfunction getOrCreateContext(): import('react').Context<NavigationState | null> {\n  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as\n    | import('react').Context<NavigationState | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  const ctx = createContext<NavigationState | null>(null);\n  (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;\n  return ctx;\n}\n\n/**\n * Read the navigation context. Returns null only when no provider is above\n * the caller — a component rendered outside the timber app.\n *\n * Internal — used by usePathname() and useSearchParams().\n */\nexport function useNavigationContext(): NavigationState | null {\n  return useContext(getOrCreateContext());\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): import('react').ReactElement {\n  return createElement(getOrCreateContext().Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Module-level state for renderRoot to read\n// ---------------------------------------------------------------------------\n\n/**\n * Navigation state communicated between the router and renderRoot.\n *\n * The router calls setNavigationState() before renderRoot(). The\n * renderRoot callback reads via getNavigationState() to create the\n * NavigationProvider with the correct params/pathname.\n *\n * This is NOT used by hooks directly — hooks read from React context.\n *\n * Stored on globalThis (like the context instances above) because the\n * router lives in one chunk while renderRoot lives in another. Module-\n * level variables would be separate per chunk.\n */\nconst NAV_STATE_KEY = Symbol.for('__timber_nav_state');\n\nfunction _getNavStateStore(): { current: NavigationState } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_STATE_KEY]) {\n    g[NAV_STATE_KEY] = { current: { pathname: '/', search: '' } };\n  }\n  return g[NAV_STATE_KEY] as { current: NavigationState };\n}\n\nexport function setNavigationState(state: NavigationState): void {\n  _getNavStateStore().current = state;\n}\n\nexport function getNavigationState(): NavigationState {\n  return _getNavStateStore().current;\n}\n\n// ---------------------------------------------------------------------------\n// Pending navigation state lives in the router, not here\n// ---------------------------------------------------------------------------\n\n/**\n * There was a second React context here — `PendingNavigationContext`, holding\n * the in-flight navigation URL, provided by `NavigationRoot` out of a\n * `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone\n * (TIM-1307).\n *\n * Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and\n * `TopLoader` both subscribe to the router's external pending store via\n * `useSyncExternalStore`: sync priority, immune to transition entanglement,\n * and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).\n * The context was a parallel representation of the same fact that no consumer\n * ever migrated to, and one that could not even agree with the store — a\n * navigation superseded by a cached popstate replay left its URL set until the\n * next full navigation, because the staleness guard skipped the clear and no\n * other path touched it.\n *\n * One representation, and it is the router's. See\n * design/19-client-navigation.md §\"How Pending State Works\".\n */\n","/**\n * TopLoader — Built-in progress bar for client navigations.\n *\n * Shows an animated progress bar at the top of the viewport while an RSC\n * navigation is in flight. Injected automatically by the framework into\n * NavigationRoot — users never render this component directly.\n *\n * Configuration is via timber.config.ts `topLoader` key. Enabled by default.\n * Users who want a fully custom progress indicator disable the built-in one\n * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.\n *\n * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%\n * width over ~30s using ease-out timing. When navigation completes, the bar\n * snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).\n *\n * Phase transitions are derived synchronously during render (React's\n * getDerivedStateFromProps pattern) — no useEffect needed for state tracking.\n * The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.\n *\n * When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar\n * stays invisible during the delay period. If navigation finishes before the\n * delay, the bar was never visible so the finish transition is also invisible.\n *\n * See design/19-client-navigation.md §\"usePendingNavigation()\"\n * See LOCAL-336 for design decisions.\n */\n\n'use client';\n\nimport { useState, createElement } from 'react';\nimport { usePendingNavigation } from './use-pending-navigation.ts';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface TopLoaderConfig {\n  /** Whether the top-loader is enabled. Default: true. */\n  enabled?: boolean;\n  /** Bar color. Default: '#2299DD'. */\n  color?: string;\n  /** Bar height in pixels. Default: 3. */\n  height?: number;\n  /** Show subtle glow/shadow effect. Default: false. */\n  shadow?: boolean;\n  /** Delay in ms before showing the bar. Default: 0. */\n  delay?: number;\n  /** CSS z-index. Default: 1600. */\n  zIndex?: number;\n}\n\n// ─── Defaults ────────────────────────────────────────────────────\n\nconst DEFAULT_COLOR = '#2299DD';\nconst DEFAULT_HEIGHT = 3;\nconst DEFAULT_SHADOW = false;\nconst DEFAULT_DELAY = 0;\nconst DEFAULT_Z_INDEX = 1600;\n\n// ─── Keyframes ───────────────────────────────────────────────────\n\n// Unique keyframes name to avoid collisions with user styles.\nconst CRAWL_KEYFRAMES = '__timber_top_loader_crawl';\nconst APPEAR_KEYFRAMES = '__timber_top_loader_appear';\nconst FINISH_KEYFRAMES = '__timber_top_loader_finish';\n\n// Track whether the @keyframes rules have been injected into the document.\nlet keyframesInjected = false;\n\n/**\n * Inject the @keyframes rules into the document head once.\n * Called during render (idempotent). Uses a <style> tag so the\n * animations are available for inline-styled elements.\n */\nfunction ensureKeyframes(): void {\n  if (keyframesInjected) return;\n  if (typeof document === 'undefined') return;\n\n  const style = document.createElement('style');\n  style.textContent = `\n@keyframes ${CRAWL_KEYFRAMES} {\n  0% { width: 0%; }\n  100% { width: 90%; }\n}\n@keyframes ${APPEAR_KEYFRAMES} {\n  from { opacity: 0; }\n  to { opacity: 1; }\n}\n@keyframes ${FINISH_KEYFRAMES} {\n  0% { width: 90%; opacity: 1; }\n  50% { width: 100%; opacity: 1; }\n  100% { width: 100%; opacity: 0; }\n}\n`;\n  document.head.appendChild(style);\n  keyframesInjected = true;\n}\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Internal top-loader component. Injected by NavigationRoot.\n *\n * Reads pending navigation state from the router's external store, via\n * usePendingNavigation() — the one pending representation (TIM-1307).\n * Phase transitions are derived synchronously during render:\n *\n *   hidden → crawling:   when isPending becomes true\n *   crawling → finishing: when isPending becomes false\n *   finishing → hidden:   when CSS transition ends (onTransitionEnd)\n *   finishing → crawling: when isPending becomes true again\n *\n * No useEffect — all state changes are either derived during render\n * (getDerivedStateFromProps pattern) or triggered by DOM events.\n */\nexport function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {\n  // Read pending state from the router's external store via\n  // useSyncExternalStore (inside usePendingNavigation). Only this\n  // component re-renders when pending changes — no full-tree re-render.\n  const isPending = usePendingNavigation();\n\n  const color = config?.color ?? DEFAULT_COLOR;\n  const height = config?.height ?? DEFAULT_HEIGHT;\n  const shadow = config?.shadow ?? DEFAULT_SHADOW;\n  const delay = config?.delay ?? DEFAULT_DELAY;\n  const zIndex = config?.zIndex ?? DEFAULT_Z_INDEX;\n\n  const [phase, setPhase] = useState<'hidden' | 'crawling' | 'finishing'>('hidden');\n\n  // ─── Synchronous phase derivation (getDerivedStateFromProps) ──\n  // React allows setState during render if the value changes — it\n  // immediately re-renders with the updated state before committing.\n\n  if (isPending && (phase === 'hidden' || phase === 'finishing')) {\n    setPhase('crawling');\n  }\n  if (!isPending && phase === 'crawling') {\n    setPhase('finishing');\n  }\n\n  // Inject keyframes on first visible render (idempotent)\n  if (phase !== 'hidden') {\n    ensureKeyframes();\n  }\n\n  if (phase === 'hidden') return null;\n\n  // ─── Styles ──────────────────────────────────────────────────\n\n  const containerStyle: React.CSSProperties = {\n    position: 'fixed',\n    top: 0,\n    left: 0,\n    width: '100%',\n    height: `${height}px`,\n    zIndex,\n    pointerEvents: 'none',\n  };\n\n  const barStyle: React.CSSProperties = {\n    height: '100%',\n    backgroundColor: color,\n    ...(phase === 'crawling'\n      ? {\n          // Crawl from 0% to 90% over 30s. When delay > 0, both the crawl\n          // and a visibility animation are delayed — the bar stays at width 0%\n          // and opacity 0 during the delay, then appears and starts crawling.\n          // With delay 0, the appear animation is instant (0s duration, no delay).\n          animation: [\n            `${CRAWL_KEYFRAMES} 30s ease-out ${delay}ms forwards`,\n            `${APPEAR_KEYFRAMES} 0s ${delay}ms both`,\n          ].join(', '),\n        }\n      : {\n          // Finishing: fill to 100% then fade out via a keyframe animation.\n          // We use a keyframe instead of a CSS transition because the\n          // animation-to-transition handoff is unreliable — the browser\n          // may not capture the animated width as the transition's \"from\"\n          // value when both the animation removal and transition are\n          // applied in the same render frame.\n          animation: `${FINISH_KEYFRAMES} 400ms ease forwards`,\n        }),\n    ...(shadow\n      ? {\n          boxShadow: `0 0 10px ${color}, 0 0 5px ${color}`,\n        }\n      : {}),\n  };\n\n  // Clean up the finishing phase when the finish animation completes.\n  const handleAnimationEnd =\n    phase === 'finishing'\n      ? (e: React.AnimationEvent) => {\n          if (e.animationName === FINISH_KEYFRAMES) {\n            setPhase('hidden');\n          }\n        }\n      : undefined;\n\n  return createElement(\n    'div',\n    {\n      'style': containerStyle,\n      'aria-hidden': 'true',\n      'data-timber-top-loader': '',\n    },\n    createElement('div', { style: barStyle, onAnimationEnd: handleAnimationEnd })\n  );\n}\n","/**\n * NavigationRoot — the component the router renders the page through.\n *\n * It is stateless. The router owns the displayed tree and drives React with\n * `root.render(<NavigationRoot rendered={{ element, publish }} />)` inside a\n * synchronous `startTransition` (see `client/react-root.ts`). A transition\n * update keeps the committed tree on screen while the incoming one resolves,\n * instead of replacing it with a Suspense fallback — the reason this\n * component exists (TIM-1306).\n *\n * It used to hold the tree in `useState` and register `setState` closures\n * into module globals during render so the router could reach into it, with a\n * second set of stand-in closures for the window before a root existed\n * (TIM-600). Inverting that — router calls React, not the reverse — deleted\n * all of it (TIM-1431). Next.js's `use-action-queue.ts` says it wants this\n * shape and cannot have it because it must decode Flight during render;\n * timber decodes in `router-pipeline.ts`, so nothing stands in the way.\n *\n * What this component does own is **the commit-time publish**: a navigation's\n * state (segment cache, address bar, history stack, pathname) is published\n * from a layout effect keyed on the tree object, so the event that puts a\n * route on screen is the event that makes it current (TIM-1301). Props work\n * for that exactly as state did.\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 { createElement, Fragment, useLayoutEffect, useRef, type ReactNode } from 'react';\nimport { TopLoader, type TopLoaderConfig } from './top-loader.tsx';\n\n// ─── Rendered Tree ──────────────────────────────────────────────\n\n/**\n * The tree the router has handed to React, 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. Every `render` builds a\n * fresh one, which is what keys that effect: a tree is published once, however\n * many times React re-runs the effect for it.\n */\nexport interface RenderedTree {\n  element: ReactNode;\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. Runs when React commits\n   * `element`, never before (TIM-1301). Null for a render that has nothing to\n   * publish on commit (hydration, the shallow search re-wrap).\n   */\n  publish: (() => void) | null;\n}\n\n/**\n * Hand a tree to React in a transition. `publish` runs when React commits it.\n *\n * Every path that puts a page on screen goes through one of these — a\n * navigation, a revalidation, a popstate replay, a shallow search re-wrap —\n * and it is always a synchronous `startTransition` around `root.render`.\n * The production one is `createReactRoot().render`.\n */\nexport type NavigationRender = (element: ReactNode, publish: (() => void) | null) => void;\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// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Root component the router renders the page through.\n *\n * Renders the TopLoader alongside the tree it is given. Neither adds a DOM\n * element on the hydration path, so the tree matches the server HTML.\n *\n * Rendered only by `createReactRoot` (client/react-root.ts): hydration passes\n * `{ element, publish: null }`, and every later render is a synchronous\n * `startTransition(() => root.render(...))` with a fresh `rendered` object.\n */\nexport function NavigationRoot({\n  rendered,\n  topLoaderConfig,\n}: {\n  rendered: RenderedTree;\n  topLoaderConfig?: TopLoaderConfig;\n}): ReactNode {\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, StrictMode's\n  // double-invoke — must be a 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  // ─── 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 useRef and\n  // useLayoutEffect above). React requires the same hooks to run on every\n  // render. If we threw before hooks, React would see 0 hooks on the\n  // re-render vs 2 on the initial render — triggering the exact \"Rendered\n  // 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"],"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC+CA,IAAM,cAAc,OAAO,IAAI,kBAAkB;AAEjD,SAAS,qBAAsE;CAC7E,MAAM,WAAY,WAAuC;CAGzD,IAAI,aAAa,KAAA,GAAW,OAAO;CACnC,MAAM,MAAM,cAAsC,IAAI;CACtD,WAAwC,eAAe;CACvD,OAAO;AACT;;;;;;;AAQA,SAAgB,uBAA+C;CAC7D,OAAO,WAAW,mBAAmB,CAAC;AACxC;;;;;;;AAiBA,SAAgB,mBAAmB,EACjC,OACA,YACwD;CACxD,OAAO,cAAc,mBAAmB,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;AACzE;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AErEA,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/{segment-context-CjOlyB8Y.js → param-value-C8TNYchQ.js}

@@ -1,4 +1,3 @@
-import { createContext, createElement, useContext, useMemo } from "react";
 //#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 ${[
@@ -62,36 +61,6 @@ function keyLabel(key) {
 	return typeof key === "string" ? JSON.stringify(key) : String(key);
 }
 //#endregion
-//#region src/client/segment-context.ts
-/**
-* Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.
-*
-* Each layout in the segment tree is wrapped with a SegmentProvider that stores
-* the URL segments from root to the current layout level. The hooks read this
-* context to determine which child segments are active below the calling layout.
-*
-* The context value is intentionally minimal: just the segment path array and
-* parallel route keys. No internal cache details are exposed.
-*
-* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
-*/
-var SegmentContext = createContext(null);
-/** Read the segment context. Returns null if no provider is above this component. */
-function useSegmentContext() {
-	return useContext(SegmentContext);
-}
-/**
-* Wraps each layout to provide segment position context.
-* Injected by rsc-entry.ts during element tree construction.
-*/
-function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }) {
-	const value = useMemo(() => ({
-		segments,
-		parallelRouteKeys
-	}), [segments.join("/"), parallelRouteKeys.join(",")]);
-	return createElement(SegmentContext.Provider, { value }, children);
-}
-//#endregion
-export { useSegmentContext as n, normalizeParamValue as r, SegmentProvider as t };
+export { normalizeParamValue as t };
 
-//# sourceMappingURL=segment-context-CjOlyB8Y.js.map
+//# 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// ─── Post-coercion param types ──────────────────────────────────────────\n\n/**\n * A single segment param value after codec coercion and normalization.\n *\n * Before coercion, every param is `string | string[]` (the raw URL part).\n * After `app/schema.ts` codecs run, a param can be any value in the\n * `normalizeParamValue` domain below. This type replaces the previous\n * `string | string[]` declaration, which was a lie whenever a codec\n * produced a non-string value (TIM-1347).\n *\n * The typed accessor `getSegmentParams(SEGMENT_PATH)` resolves through\n * the schema and returns the exact type the codec declares. This type\n * covers the untyped/no-argument form and internal plumbing.\n */\nexport type CoercedParamValue =\n  | string\n  | number\n  | boolean\n  | bigint\n  | null\n  | undefined\n  | Date\n  | Map<CoercedParamValue, CoercedParamValue>\n  | Set<CoercedParamValue>\n  | CoercedParamValue[]\n  | { [key: string]: CoercedParamValue };\n\n/**\n * A record of coerced segment params, keyed by param name.\n *\n * This is the post-coercion type for `segmentParams` throughout the\n * framework. Before coercion (route matcher output, `rawSegmentParams`),\n * the type is `Record<string, string | string[]>`.\n */\nexport type CoercedParams = Record<string, CoercedParamValue>;\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 = ''): CoercedParamValue {\n  return normalize(value, path, new Set());\n}\n\nfunction normalize(value: unknown, path: string, seen: Set<object>): CoercedParamValue {\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 as string | number | boolean | bigint;\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: CoercedParamValue[] = [];\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<CoercedParamValue, CoercedParamValue>();\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<CoercedParamValue>();\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, CoercedParamValue> = 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":";;AAyGA,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,IAAuB;CAChF,OAAO,UAAU,OAAO,sBAAM,IAAI,IAAI,CAAC;AACzC;AAEA,SAAS,UAAU,OAAgB,MAAc,MAAsC;CACrF,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,MAA2B,CAAC;EAClC,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,IAA0C;EAC1D,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,IAAuB;EACvC,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,MAAyC,OAAO,OAAO,IAAI;CACjE,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/{poison-scan-BAxfTT5L.js → poison-scan-BoDLgbix.js}

@@ -1,5 +1,5 @@
 import { n as INFERRED_RULES, t as EXPLICIT_MARKERS } from "./poison-rules-DoEhbqaY.js";
-import { o as langForFile } from "./chains-h7EO-u3n.js";
+import { o as langForFile } from "./chains-CZG7E5zg.js";
 import { parseAst } from "vite";
 //#region src/analyze/poison-scan.ts
 /**
@@ -98,4 +98,4 @@ function poisoningsFor(kind, pending, signals) {
 //#endregion
 export { importSignals as n, poisoningsFor as r, collectImportSpecifiers as t };
 
-//# sourceMappingURL=poison-scan-BAxfTT5L.js.map
+//# sourceMappingURL=poison-scan-BoDLgbix.js.map

package/dist/_chunks/{poison-scan-BAxfTT5L.js.map → poison-scan-BoDLgbix.js.map}

@@ -1 +1 @@
-{"version":3,"file":"poison-scan-BAxfTT5L.js","names":[],"sources":["../../src/analyze/poison-scan.ts"],"sourcesContent":["/**\n * poison-scan — report-only poisoning detection for `timber graph`.\n *\n * Matches a module's static import specifiers against the shared rule\n * lists in poison-rules.ts (the single source of truth — design/47 §3)\n * and reports a poisoning only when the implied exclusivity CONFLICTS\n * with where the module actually runs: a server-only signal in a\n * client-reachable module, or a client-only signal in a server-reachable\n * one. A `node:fs` import in a file only the RSC environment loads is\n * working code, not a finding.\n *\n * Scope: import-specifier signals only (explicit markers + the inferred\n * rules' `matchesImport`). The inferred browser-global identifier rules\n * need shadow-safe allowlisted-position AST matching and are a separate\n * ticket — reporting them from a text scan would flag legitimate code.\n *\n * Design docs: 47-module-environment-tooling.md §3.\n */\n\nimport { parseAst } from 'vite';\nimport { EXPLICIT_MARKERS, INFERRED_RULES } from './poison-rules.ts';\nimport { langForFile, type ModuleKind } from './classify.ts';\n\n/** One poisoning finding on a module, in the JSON-contract shape. */\nexport interface Poisoning {\n  /** Rule id — an inferred rule's id, or the explicit marker specifier. */\n  rule: string;\n  /** The import specifier that matched. */\n  specifier: string;\n  /** Which exclusivity the signal implies for the containing module. */\n  implies: 'server-only' | 'client-only';\n  /** Human-readable description for reporter output. */\n  description: string;\n}\n\n/** File extensions the specifier scan can parse. */\nconst PARSEABLE_EXTENSIONS = /\\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;\n\n/**\n * A NON-EMPTY specifier list where every entry is type-only. Empty or\n * absent lists return false — a bare `import 'pkg'` is a side-effect\n * import and very much runs.\n */\nfunction isAllSpecifiersTypeOnly(\n  specifiers: Array<{ importKind?: string; exportKind?: string }> | undefined\n): boolean {\n  if (!specifiers || specifiers.length === 0) return false;\n  return specifiers.every((s) => s.importKind === 'type' || s.exportKind === 'type');\n}\n\n/**\n * Collect every static import/export source and string-literal dynamic\n * import from a module's original source. Sources that fail to parse\n * (or are not JS/TS at all) return [] — no specifiers is a safe\n * default for a report-only scan.\n */\nexport function collectImportSpecifiers(code: string, file: string): string[] {\n  if (!PARSEABLE_EXTENSIONS.test(file)) return [];\n  let program;\n  try {\n    // Language from the extension, never forced tsx — see langForFile.\n    program = parseAst(code, { lang: langForFile(file) });\n  } catch {\n    return [];\n  }\n  const specifiers: string[] = [];\n  const visit = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      for (const child of node) visit(child);\n      return;\n    }\n    if (typeof node !== 'object' || node === null) return;\n    const record = node as Record<string, unknown> & {\n      type?: string;\n      importKind?: string;\n      exportKind?: string;\n      specifiers?: Array<{ importKind?: string; exportKind?: string }>;\n    };\n    if (\n      (record.type === 'ImportDeclaration' ||\n        record.type === 'ExportNamedDeclaration' ||\n        record.type === 'ExportAllDeclaration') &&\n      // Type-only imports/exports are erased at runtime — `import type\n      // { Stats } from 'node:fs'` in client code is working code, and\n      // flagging it would be a false positive in a report-only scan.\n      // Covers both the declaration-level form (`import type {…}`,\n      // importKind on the declaration) and the inline form\n      // (`import { type Stats }`, where the declaration stays 'value'\n      // and each SPECIFIER carries the kind) — a declaration whose\n      // specifiers are all type-only is erased just the same.\n      record.importKind !== 'type' &&\n      record.exportKind !== 'type' &&\n      !isAllSpecifiersTypeOnly(record.specifiers) &&\n      typeof (record.source as { value?: unknown } | null)?.value === 'string'\n    ) {\n      specifiers.push((record.source as { value: string }).value);\n    } else if (\n      record.type === 'ImportExpression' &&\n      (record.source as { type?: string; value?: unknown })?.type === 'Literal' &&\n      typeof (record.source as { value?: unknown }).value === 'string'\n    ) {\n      specifiers.push((record.source as { value: string }).value);\n    }\n    for (const key of Object.keys(record)) {\n      if (key === 'type') continue;\n      visit(record[key]);\n    }\n  };\n  visit(program.body);\n  return specifiers;\n}\n\n/** Exclusivity signals a module's import specifiers carry. */\nexport function importSignals(specifiers: string[]): Poisoning[] {\n  const signals: Poisoning[] = [];\n  for (const specifier of specifiers) {\n    for (const marker of EXPLICIT_MARKERS) {\n      if (specifier === marker.specifier) {\n        signals.push({\n          rule: marker.specifier,\n          specifier,\n          implies: marker.specifier === 'server-only' ? 'server-only' : 'client-only',\n          description: `imports the ${marker.specifier} poison-pill marker`,\n        });\n      }\n    }\n    for (const rule of INFERRED_RULES) {\n      if (rule.matchesImport?.(specifier)) {\n        signals.push({\n          rule: rule.id,\n          specifier,\n          implies: rule.implies,\n          description: rule.description,\n        });\n      }\n    }\n  }\n  return signals;\n}\n\n/**\n * Filter a module's signals down to actual conflicts with its\n * classification. Environment reach follows the taxonomy: boundary /\n * client-internal / shared modules run client-side; server / shared /\n * server-action modules run server-side. Pending (provisional) modules\n * run nowhere confirmed, so nothing conflicts yet.\n */\nexport function poisoningsFor(\n  kind: ModuleKind,\n  pending: boolean,\n  signals: Poisoning[]\n): Poisoning[] {\n  if (pending || signals.length === 0) return [];\n  const clientReachable =\n    kind === 'client-boundary' || kind === 'client-internal' || kind === 'shared';\n  const serverReachable = kind === 'server' || kind === 'shared' || kind === 'server-action';\n  return signals.filter(\n    (signal) =>\n      (signal.implies === 'server-only' && clientReachable) ||\n      (signal.implies === 'client-only' && serverReachable)\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,uBAAuB;;;;;;AAO7B,SAAS,wBACP,YACS;CACT,IAAI,CAAC,cAAc,WAAW,WAAW,GAAG,OAAO;CACnD,OAAO,WAAW,OAAO,MAAM,EAAE,eAAe,UAAU,EAAE,eAAe,MAAM;AACnF;;;;;;;AAQA,SAAgB,wBAAwB,MAAc,MAAwB;CAC5E,IAAI,CAAC,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC;CAC9C,IAAI;CACJ,IAAI;EAEF,UAAU,SAAS,MAAM,EAAE,MAAM,YAAY,IAAI,EAAE,CAAC;CACtD,QAAQ;EACN,OAAO,CAAC;CACV;CACA,MAAM,aAAuB,CAAC;CAC9B,MAAM,SAAS,SAAwB;EACrC,IAAI,MAAM,QAAQ,IAAI,GAAG;GACvB,KAAK,MAAM,SAAS,MAAM,MAAM,KAAK;GACrC;EACF;EACA,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM;EAC/C,MAAM,SAAS;EAMf,KACG,OAAO,SAAS,uBACf,OAAO,SAAS,4BAChB,OAAO,SAAS,2BASlB,OAAO,eAAe,UACtB,OAAO,eAAe,UACtB,CAAC,wBAAwB,OAAO,UAAU,KAC1C,OAAQ,OAAO,QAAuC,UAAU,UAEhE,WAAW,KAAM,OAAO,OAA6B,KAAK;OACrD,IACL,OAAO,SAAS,sBACf,OAAO,QAA+C,SAAS,aAChE,OAAQ,OAAO,OAA+B,UAAU,UAExD,WAAW,KAAM,OAAO,OAA6B,KAAK;EAE5D,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;GACrC,IAAI,QAAQ,QAAQ;GACpB,MAAM,OAAO,IAAI;EACnB;CACF;CACA,MAAM,QAAQ,IAAI;CAClB,OAAO;AACT;;AAGA,SAAgB,cAAc,YAAmC;CAC/D,MAAM,UAAuB,CAAC;CAC9B,KAAK,MAAM,aAAa,YAAY;EAClC,KAAK,MAAM,UAAU,kBACnB,IAAI,cAAc,OAAO,WACvB,QAAQ,KAAK;GACX,MAAM,OAAO;GACb;GACA,SAAS,OAAO,cAAc,gBAAgB,gBAAgB;GAC9D,aAAa,eAAe,OAAO,UAAU;EAC/C,CAAC;EAGL,KAAK,MAAM,QAAQ,gBACjB,IAAI,KAAK,gBAAgB,SAAS,GAChC,QAAQ,KAAK;GACX,MAAM,KAAK;GACX;GACA,SAAS,KAAK;GACd,aAAa,KAAK;EACpB,CAAC;CAGP;CACA,OAAO;AACT;;;;;;;;AASA,SAAgB,cACd,MACA,SACA,SACa;CACb,IAAI,WAAW,QAAQ,WAAW,GAAG,OAAO,CAAC;CAC7C,MAAM,kBACJ,SAAS,qBAAqB,SAAS,qBAAqB,SAAS;CACvE,MAAM,kBAAkB,SAAS,YAAY,SAAS,YAAY,SAAS;CAC3E,OAAO,QAAQ,QACZ,WACE,OAAO,YAAY,iBAAiB,mBACpC,OAAO,YAAY,iBAAiB,eACzC;AACF"}
+{"version":3,"file":"poison-scan-BoDLgbix.js","names":[],"sources":["../../src/analyze/poison-scan.ts"],"sourcesContent":["/**\n * poison-scan — report-only poisoning detection for `timber graph`.\n *\n * Matches a module's static import specifiers against the shared rule\n * lists in poison-rules.ts (the single source of truth — design/47 §3)\n * and reports a poisoning only when the implied exclusivity CONFLICTS\n * with where the module actually runs: a server-only signal in a\n * client-reachable module, or a client-only signal in a server-reachable\n * one. A `node:fs` import in a file only the RSC environment loads is\n * working code, not a finding.\n *\n * Scope: import-specifier signals only (explicit markers + the inferred\n * rules' `matchesImport`). The inferred browser-global identifier rules\n * need shadow-safe allowlisted-position AST matching and are a separate\n * ticket — reporting them from a text scan would flag legitimate code.\n *\n * Design docs: 47-module-environment-tooling.md §3.\n */\n\nimport { parseAst } from 'vite';\nimport { EXPLICIT_MARKERS, INFERRED_RULES } from './poison-rules.ts';\nimport { langForFile, type ModuleKind } from './classify.ts';\n\n/** One poisoning finding on a module, in the JSON-contract shape. */\nexport interface Poisoning {\n  /** Rule id — an inferred rule's id, or the explicit marker specifier. */\n  rule: string;\n  /** The import specifier that matched. */\n  specifier: string;\n  /** Which exclusivity the signal implies for the containing module. */\n  implies: 'server-only' | 'client-only';\n  /** Human-readable description for reporter output. */\n  description: string;\n}\n\n/** File extensions the specifier scan can parse. */\nconst PARSEABLE_EXTENSIONS = /\\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;\n\n/**\n * A NON-EMPTY specifier list where every entry is type-only. Empty or\n * absent lists return false — a bare `import 'pkg'` is a side-effect\n * import and very much runs.\n */\nfunction isAllSpecifiersTypeOnly(\n  specifiers: Array<{ importKind?: string; exportKind?: string }> | undefined\n): boolean {\n  if (!specifiers || specifiers.length === 0) return false;\n  return specifiers.every((s) => s.importKind === 'type' || s.exportKind === 'type');\n}\n\n/**\n * Collect every static import/export source and string-literal dynamic\n * import from a module's original source. Sources that fail to parse\n * (or are not JS/TS at all) return [] — no specifiers is a safe\n * default for a report-only scan.\n */\nexport function collectImportSpecifiers(code: string, file: string): string[] {\n  if (!PARSEABLE_EXTENSIONS.test(file)) return [];\n  let program;\n  try {\n    // Language from the extension, never forced tsx — see langForFile.\n    program = parseAst(code, { lang: langForFile(file) });\n  } catch {\n    return [];\n  }\n  const specifiers: string[] = [];\n  const visit = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      for (const child of node) visit(child);\n      return;\n    }\n    if (typeof node !== 'object' || node === null) return;\n    const record = node as Record<string, unknown> & {\n      type?: string;\n      importKind?: string;\n      exportKind?: string;\n      specifiers?: Array<{ importKind?: string; exportKind?: string }>;\n    };\n    if (\n      (record.type === 'ImportDeclaration' ||\n        record.type === 'ExportNamedDeclaration' ||\n        record.type === 'ExportAllDeclaration') &&\n      // Type-only imports/exports are erased at runtime — `import type\n      // { Stats } from 'node:fs'` in client code is working code, and\n      // flagging it would be a false positive in a report-only scan.\n      // Covers both the declaration-level form (`import type {…}`,\n      // importKind on the declaration) and the inline form\n      // (`import { type Stats }`, where the declaration stays 'value'\n      // and each SPECIFIER carries the kind) — a declaration whose\n      // specifiers are all type-only is erased just the same.\n      record.importKind !== 'type' &&\n      record.exportKind !== 'type' &&\n      !isAllSpecifiersTypeOnly(record.specifiers) &&\n      typeof (record.source as { value?: unknown } | null)?.value === 'string'\n    ) {\n      specifiers.push((record.source as { value: string }).value);\n    } else if (\n      record.type === 'ImportExpression' &&\n      (record.source as { type?: string; value?: unknown })?.type === 'Literal' &&\n      typeof (record.source as { value?: unknown }).value === 'string'\n    ) {\n      specifiers.push((record.source as { value: string }).value);\n    }\n    for (const key of Object.keys(record)) {\n      if (key === 'type') continue;\n      visit(record[key]);\n    }\n  };\n  visit(program.body);\n  return specifiers;\n}\n\n/** Exclusivity signals a module's import specifiers carry. */\nexport function importSignals(specifiers: string[]): Poisoning[] {\n  const signals: Poisoning[] = [];\n  for (const specifier of specifiers) {\n    for (const marker of EXPLICIT_MARKERS) {\n      if (specifier === marker.specifier) {\n        signals.push({\n          rule: marker.specifier,\n          specifier,\n          implies: marker.specifier === 'server-only' ? 'server-only' : 'client-only',\n          description: `imports the ${marker.specifier} poison-pill marker`,\n        });\n      }\n    }\n    for (const rule of INFERRED_RULES) {\n      if (rule.matchesImport?.(specifier)) {\n        signals.push({\n          rule: rule.id,\n          specifier,\n          implies: rule.implies,\n          description: rule.description,\n        });\n      }\n    }\n  }\n  return signals;\n}\n\n/**\n * Filter a module's signals down to actual conflicts with its\n * classification. Environment reach follows the taxonomy: boundary /\n * client-internal / shared modules run client-side; server / shared /\n * server-action modules run server-side. Pending (provisional) modules\n * run nowhere confirmed, so nothing conflicts yet.\n */\nexport function poisoningsFor(\n  kind: ModuleKind,\n  pending: boolean,\n  signals: Poisoning[]\n): Poisoning[] {\n  if (pending || signals.length === 0) return [];\n  const clientReachable =\n    kind === 'client-boundary' || kind === 'client-internal' || kind === 'shared';\n  const serverReachable = kind === 'server' || kind === 'shared' || kind === 'server-action';\n  return signals.filter(\n    (signal) =>\n      (signal.implies === 'server-only' && clientReachable) ||\n      (signal.implies === 'client-only' && serverReachable)\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,uBAAuB;;;;;;AAO7B,SAAS,wBACP,YACS;CACT,IAAI,CAAC,cAAc,WAAW,WAAW,GAAG,OAAO;CACnD,OAAO,WAAW,OAAO,MAAM,EAAE,eAAe,UAAU,EAAE,eAAe,MAAM;AACnF;;;;;;;AAQA,SAAgB,wBAAwB,MAAc,MAAwB;CAC5E,IAAI,CAAC,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC;CAC9C,IAAI;CACJ,IAAI;EAEF,UAAU,SAAS,MAAM,EAAE,MAAM,YAAY,IAAI,EAAE,CAAC;CACtD,QAAQ;EACN,OAAO,CAAC;CACV;CACA,MAAM,aAAuB,CAAC;CAC9B,MAAM,SAAS,SAAwB;EACrC,IAAI,MAAM,QAAQ,IAAI,GAAG;GACvB,KAAK,MAAM,SAAS,MAAM,MAAM,KAAK;GACrC;EACF;EACA,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM;EAC/C,MAAM,SAAS;EAMf,KACG,OAAO,SAAS,uBACf,OAAO,SAAS,4BAChB,OAAO,SAAS,2BASlB,OAAO,eAAe,UACtB,OAAO,eAAe,UACtB,CAAC,wBAAwB,OAAO,UAAU,KAC1C,OAAQ,OAAO,QAAuC,UAAU,UAEhE,WAAW,KAAM,OAAO,OAA6B,KAAK;OACrD,IACL,OAAO,SAAS,sBACf,OAAO,QAA+C,SAAS,aAChE,OAAQ,OAAO,OAA+B,UAAU,UAExD,WAAW,KAAM,OAAO,OAA6B,KAAK;EAE5D,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;GACrC,IAAI,QAAQ,QAAQ;GACpB,MAAM,OAAO,IAAI;EACnB;CACF;CACA,MAAM,QAAQ,IAAI;CAClB,OAAO;AACT;;AAGA,SAAgB,cAAc,YAAmC;CAC/D,MAAM,UAAuB,CAAC;CAC9B,KAAK,MAAM,aAAa,YAAY;EAClC,KAAK,MAAM,UAAU,kBACnB,IAAI,cAAc,OAAO,WACvB,QAAQ,KAAK;GACX,MAAM,OAAO;GACb;GACA,SAAS,OAAO,cAAc,gBAAgB,gBAAgB;GAC9D,aAAa,eAAe,OAAO,UAAU;EAC/C,CAAC;EAGL,KAAK,MAAM,QAAQ,gBACjB,IAAI,KAAK,gBAAgB,SAAS,GAChC,QAAQ,KAAK;GACX,MAAM,KAAK;GACX;GACA,SAAS,KAAK;GACd,aAAa,KAAK;EACpB,CAAC;CAGP;CACA,OAAO;AACT;;;;;;;;AASA,SAAgB,cACd,MACA,SACA,SACa;CACb,IAAI,WAAW,QAAQ,WAAW,GAAG,OAAO,CAAC;CAC7C,MAAM,kBACJ,SAAS,qBAAqB,SAAS,qBAAqB,SAAS;CACvE,MAAM,kBAAkB,SAAS,YAAY,SAAS,YAAY,SAAS;CAC3E,OAAO,QAAQ,QACZ,WACE,OAAO,YAAY,iBAAiB,mBACpC,OAAO,YAAY,iBAAiB,eACzC;AACF"}

package/dist/_chunks/{router-ref-BzqbPwYC.js → router-ref-8gr8qsxN.js}

@@ -1,4 +1,4 @@
-import { p as globalRouter, s as _setGlobalRouter } from "./ssr-data-Ya2HJPFp.js";
+import { a as _setGlobalRouter, l as globalRouter } from "./ssr-data-BQGhTPAK.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-BzqbPwYC.js.map
+//# sourceMappingURL=router-ref-8gr8qsxN.js.map

package/dist/_chunks/{router-ref-BzqbPwYC.js.map → router-ref-8gr8qsxN.js.map}

@@ -1 +1 @@
-{"version":3,"file":"router-ref-BzqbPwYC.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.ts';\nimport { globalRouter, _setGlobalRouter } from './state.ts';\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"}
+{"version":3,"file":"router-ref-8gr8qsxN.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.ts';\nimport { globalRouter, _setGlobalRouter } from './state.ts';\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"}

package/dist/_chunks/{rsc-cache-key-DD0fl_-s.js → rsc-cache-key-ClUiXQnK.js}

@@ -238,6 +238,6 @@ function recordLookup(headers) {
 	return (name) => lowered[name.toLowerCase()];
 }
 //#endregion
-export { randomRscCacheKey as a, isRscCacheKeyShape as i, RSC_KEY_PARAM as n, recordLookup as o, appVisibleSearch as r, rscCacheKey as s, RSC_KEY_HEADERS as t };
+export { randomRscCacheKey as a, stripRscCacheKey as c, isRscCacheKeyShape as i, RSC_KEY_PARAM as n, recordLookup as o, appVisibleSearch as r, rscCacheKey as s, RSC_KEY_HEADERS as t };
 
-//# sourceMappingURL=rsc-cache-key-DD0fl_-s.js.map
+//# sourceMappingURL=rsc-cache-key-ClUiXQnK.js.map

package/dist/_chunks/{rsc-cache-key-DD0fl_-s.js.map → rsc-cache-key-ClUiXQnK.js.map}

@@ -1 +1 @@
-{"version":3,"file":"rsc-cache-key-DD0fl_-s.js","names":[],"sources":["../../src/shared/rsc-cache-key.ts"],"sourcesContent":["/**\n * The `_rsc` payload cache key — derived identically on both sides.\n *\n * The client puts this in the payload URL so the document and its Flight\n * payload occupy different cache keys (TIM-1268). The server recomputes it\n * from the received headers so a request cannot claim one client's key while\n * sending another client's headers — see `server/rsc-cache-key-guard.ts`.\n * Both sides must agree exactly, which is why the derivation lives here and\n * not in either one.\n *\n * Isomorphic: no server or client imports. The browser bundle audit\n * (`tests/client-bundle-audit.test.ts`) enforces the client half of that.\n *\n * See design/19-client-navigation.md §\"The `_rsc` cache key\".\n */\n\n/**\n * Digest length in hex characters. 128 bits: the origin guard compares a\n * caller-supplied key against a recomputed one, so the relevant bound is a\n * birthday attack (an attacker who can influence a victim's `X-Timber-URL`\n * gets to search both sides), not second preimage. 64 bits would fall to\n * ~2^32 work; 128 puts it at 2^64.\n */\nconst KEY_HEX_LENGTH = 32;\n\n/**\n * Marks a value as a framework-issued key, and versions the derivation.\n *\n * Without it, an application value that happened to be 32 lowercase hex — an\n * MD5, a token — is indistinguishable from a forged claim: both are \"the\n * right shape, the wrong digest\", and no information in the value separates\n * them. So the exemption cannot key on shape alone.\n *\n * The prefix resolves that because it is anchored to the address the\n * victim's own client uses. A payload lives at `?_rsc=1.<digest>`, so\n * anything aimed at that cache entry must carry the prefix and therefore\n * gets validated; anything without it cannot be addressing a payload URL at\n * all, and is exempt as application data. An attacker cannot both hit the\n * victim's cache key and dodge the check.\n *\n * The version component also gives the derivation a migration path: the\n * client and the origin must agree byte for byte, so a future change to the\n * canonical form can be rolled out by bumping this instead of a flag day.\n */\nconst KEY_PREFIX = '1.';\n\n/**\n * The request headers that vary an RSC payload response, in canonical\n * casing — this list is also emitted verbatim as the response's `Vary`\n * tokens (`server/pipeline.ts`), since \"what varies the response\" is one\n * question with one answer, not two lists that happen to agree.\n *\n * This list is the contract, and it is enforced rather than trusted:\n * `tests/rsc-cache-key.test.ts` asserts that the header names\n * `buildRscHeaders()` can emit are exactly this set. A header added to the\n * request without being added here fails that test, because a varying input\n * outside the key is precisely the cache-poisoning hazard the key exists to\n * close.\n *\n * **No credentials, session identifiers, or user-supplied content may be\n * added.** Every value here is hashed into a URL, and URLs are logged by\n * proxies, CDNs, and origin access logs. `fnv1aHash` is a cache-key hash,\n * not a KDF — a low-entropy secret would be recoverable by brute force.\n * Authentication travels on cookies, which never enter the key.\n */\nexport const RSC_KEY_HEADERS = [\n  'Accept',\n  'X-Timber-State-Tree',\n  'X-Timber-URL',\n  'X-Timber-Deployment-Id',\n] as const;\n\n/**\n * Whether a value could be a key this module produced.\n *\n * `_rsc` is not a reserved parameter name — an application may already use\n * it for its own search state, including for a value that happens to look\n * like a digest. Anything without the `KEY_PREFIX` is therefore application\n * data, not a claim on a payload cache key, and the origin guard leaves it\n * alone rather than penalizing the response.\n *\n * Derived from `KEY_PREFIX` and `KEY_HEX_LENGTH` rather than spelled again,\n * so the shape cannot drift from the digest that has to satisfy it.\n *\n * Ignoring a malformed value costs no protection: clients only ever send\n * well-formed keys, so a URL bearing a malformed one is an address no\n * legitimate request will ever ask for, and nothing can be poisoned at an\n * address nobody reads.\n */\nexport function isRscCacheKeyShape(value: string): boolean {\n  if (!value.startsWith(KEY_PREFIX)) return false;\n  const digest = value.slice(KEY_PREFIX.length);\n  return digest.length === KEY_HEX_LENGTH && /^[0-9a-f]+$/.test(digest);\n}\n\n/**\n * The query parameter carrying the payload cache key.\n *\n * Spelled here rather than at each of the four places that read or write it\n * — the client that appends it, the origin guard that validates it, and the\n * strip below — because it is a wire contract between two independent\n * implementations, exactly like the digest itself.\n */\nexport const RSC_KEY_PARAM = '_rsc';\n\n// ─── Keeping the key out of application state ────────────────────────────\n\n/**\n * Decode one raw `name` or `value` the way `URLSearchParams` does:\n * `application/x-www-form-urlencoded`, so `+` is a space.\n *\n * Malformed percent-escapes throw in `decodeURIComponent`. `URLSearchParams`\n * leaves those bytes as-is rather than throwing, and so do we — a pair we\n * cannot decode is by definition not the framework's, so it is kept.\n */\nfunction formDecode(raw: string): string {\n  try {\n    return decodeURIComponent(raw.replace(/\\+/g, ' '));\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Remove framework-issued `_rsc` values from a raw query string.\n *\n * Only values matching `isRscCacheKeyShape` are removed. `_rsc` is not a\n * reserved name (see that function), so `/search?_rsc=foo` is application\n * state and survives — the same exemption the origin guard applies, derived\n * from the same predicate so the two cannot disagree about what \"ours\"\n * means.\n *\n * Operates on the raw string rather than round-tripping through\n * `URLSearchParams`, so every surviving pair keeps its original bytes.\n * Re-serializing would rewrite `?b` as `?b=` and `?a=%7E` as `?a=~` on RSC\n * navigations only, which is the same class of inconsistency this function\n * exists to remove.\n *\n * Matching decodes the name, because `?%5Frsc=<key>` is a `_rsc` parameter\n * as far as `URLSearchParams` is concerned — the same reasoning as the\n * guard's fast path.\n *\n * @param search - `url.search`, with or without the leading `?`.\n * @returns The query string including a leading `?`, or `''` if empty.\n */\nexport function stripRscCacheKey(search: string): string {\n  const query = search.startsWith('?') ? search.slice(1) : search;\n  if (query === '') return '';\n  const kept = query.split('&').filter((pair) => {\n    const eq = pair.indexOf('=');\n    if (formDecode(eq === -1 ? pair : pair.slice(0, eq)) !== RSC_KEY_PARAM) return true;\n    return !isRscCacheKeyShape(eq === -1 ? '' : formDecode(pair.slice(eq + 1)));\n  });\n  const result = kept.join('&');\n  return result === '' ? '' : `?${result}`;\n}\n\n/** A request's search state as application code should see it. */\nexport interface AppVisibleSearch {\n  /** Parsed params, with the framework's cache key removed. */\n  params: URLSearchParams;\n  /** The matching raw query string — `''` or `?…`. */\n  search: string;\n}\n\n/**\n * The search state application code sees, for any request URL.\n *\n * The `_rsc` key rides on the payload URL of every RSC navigation and on no\n * other request, so reading search params straight off `req.url` makes the\n * same page observe different search state depending on whether it was\n * reached by a full load or a client navigation — and lets the cache key\n * leak into whatever the page builds from it: a canonical URL, a pagination\n * link, an analytics payload (TIM-1272).\n *\n * Every application-facing derivation of search state goes through here.\n * `params` and `search` are returned together, from one strip, because they\n * are two views of one answer and were previously two expressions that had\n * to agree.\n *\n * The raw request URL is deliberately untouched: `server/rsc-cache-key-guard.ts`\n * still reads the parameter from `req.url` to bind the key to the request.\n */\nexport function appVisibleSearch(url: URL): AppVisibleSearch {\n  const search = stripRscCacheKey(url.search);\n  return { params: new URLSearchParams(search), search };\n}\n\n/**\n * Reads a header value by name. Must be case-insensitive — `Headers.get()`\n * already is, and `recordLookup` below makes a plain record so.\n */\nexport type HeaderLookup = (name: string) => string | null | undefined;\n\n/**\n * Compute the `_rsc` cache key for a request.\n *\n * Absent headers are omitted rather than sent as empty, so \"header missing\"\n * and \"header present but empty\" produce different keys.\n *\n * Values are length-prefixed rather than delimiter-separated. Any delimiter\n * can be forged by a value that contains it: with a `\\0` separator, an\n * `accept` of `a\\nx-timber-url\\0b` serializes identically to an `accept` of\n * `a` alongside an `x-timber-url` of `b`, which would let one header claim\n * another's key. HTTP forbids control characters in header values and both\n * `fetch()` and the server runtime reject them, so this is defense in depth\n * — but a length prefix is unambiguous for *any* content, which is a\n * property worth having in a function whose whole job is to be agreed on by\n * two independent implementations.\n *\n * SHA-256, truncated to 128 bits. A fast non-cryptographic hash is the\n * obvious choice for a cache key and is the wrong one here: the origin\n * *compares* this value against a recomputed one, which makes it a check.\n * FNV-1a — used for timber's other cache keys — is a multiply-xor over a\n * fixed field, so an attacker controlling a few bytes of any input (their\n * own `X-Timber-URL`, say) can solve for a chosen digest rather than search\n * for one, and forge a key belonging to somebody else.\n *\n * Returns `null` when no digest is available — `crypto.subtle` is absent in\n * non-secure browsing contexts (plain `http://` on a LAN address). Callers\n * must treat that as \"no key\", never as \"key matches\": the client omits the\n * parameter and the server refuses to share-cache. That returns those\n * clients to the pre-TIM-1268 posture, where `Vary` alone separates HTML\n * from Flight — acceptable, because a non-secure origin has no shared-CDN\n * caching story to protect in the first place.\n */\nexport async function rscCacheKey(lookup: HeaderLookup): Promise<string | null> {\n  const subtle = globalThis.crypto?.subtle;\n  if (!subtle) return null;\n  let canonical = '';\n  for (const name of RSC_KEY_HEADERS) {\n    const value = lookup(name);\n    if (value == null) continue;\n    // Lowercased in the canonical form so the two implementations cannot\n    // disagree over the casing of the constant they share.\n    canonical += `${name.toLowerCase()}:${value.length}:${value}`;\n  }\n  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(canonical));\n  let hex = '';\n  for (const byte of new Uint8Array(digest, 0, KEY_HEX_LENGTH / 2)) {\n    hex += byte.toString(16).padStart(2, '0');\n  }\n  return KEY_PREFIX + hex;\n}\n\n/**\n * An unverifiable stand-in key, for the one case where the digest cannot be\n * computed: `crypto.subtle` is absent in non-secure browsing contexts.\n * `crypto.getRandomValues` is not gated that way, so it is available exactly\n * where the digest is not.\n *\n * Carries `KEY_PREFIX` like any other key, so the origin reads it as a claim\n * it cannot verify — and refuses to share-cache the response — rather than\n * exempting it as application data. Lives here so the prefix has one home.\n */\nexport function randomRscCacheKey(): string {\n  const bytes = new Uint8Array(KEY_HEX_LENGTH / 2);\n  globalThis.crypto.getRandomValues(bytes);\n  return KEY_PREFIX + [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');\n}\n\n/** Build a case-insensitive lookup over a plain header record. */\nexport function recordLookup(headers: Record<string, string>): HeaderLookup {\n  const lowered: Record<string, string> = {};\n  for (const name of Object.keys(headers)) {\n    lowered[name.toLowerCase()] = headers[name];\n  }\n  return (name) => lowered[name.toLowerCase()];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;AAqBvB,IAAM,aAAa;;;;;;;;;;;;;;;;;;;;AAqBnB,IAAa,kBAAkB;CAC7B;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,mBAAmB,OAAwB;CACzD,IAAI,CAAC,MAAM,WAAW,UAAU,GAAG,OAAO;CAC1C,MAAM,SAAS,MAAM,MAAM,CAAiB;CAC5C,OAAO,OAAO,WAAW,kBAAkB,cAAc,KAAK,MAAM;AACtE;;;;;;;;;AAUA,IAAa,gBAAgB;;;;;;;;;AAY7B,SAAS,WAAW,KAAqB;CACvC,IAAI;EACF,OAAO,mBAAmB,IAAI,QAAQ,OAAO,GAAG,CAAC;CACnD,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,iBAAiB,QAAwB;CACvD,MAAM,QAAQ,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI;CACzD,IAAI,UAAU,IAAI,OAAO;CAMzB,MAAM,SALO,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,SAAS;EAC7C,MAAM,KAAK,KAAK,QAAQ,GAAG;EAC3B,IAAI,WAAW,OAAO,KAAK,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC,MAAA,QAAqB,OAAO;EAC/E,OAAO,CAAC,mBAAmB,OAAO,KAAK,KAAK,WAAW,KAAK,MAAM,KAAK,CAAC,CAAC,CAAC;CAC5E,CACe,CAAA,CAAK,KAAK,GAAG;CAC5B,OAAO,WAAW,KAAK,KAAK,IAAI;AAClC;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBAAiB,KAA4B;CAC3D,MAAM,SAAS,iBAAiB,IAAI,MAAM;CAC1C,OAAO;EAAE,QAAQ,IAAI,gBAAgB,MAAM;EAAG;CAAO;AACvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,eAAsB,YAAY,QAA8C;CAC9E,MAAM,SAAS,WAAW,QAAQ;CAClC,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,YAAY;CAChB,KAAK,MAAM,QAAQ,iBAAiB;EAClC,MAAM,QAAQ,OAAO,IAAI;EACzB,IAAI,SAAS,MAAM;EAGnB,aAAa,GAAG,KAAK,YAAY,EAAE,GAAG,MAAM,OAAO,GAAG;CACxD;CACA,MAAM,SAAS,MAAM,OAAO,OAAO,WAAW,IAAI,YAAY,CAAC,CAAC,OAAO,SAAS,CAAC;CACjF,IAAI,MAAM;CACV,KAAK,MAAM,QAAQ,IAAI,WAAW,QAAQ,GAAG,iBAAiB,CAAC,GAC7D,OAAO,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CAE1C,OAAO,aAAa;AACtB;;;;;;;;;;;AAYA,SAAgB,oBAA4B;CAC1C,MAAM,QAAQ,IAAI,WAAW,iBAAiB,CAAC;CAC/C,WAAW,OAAO,gBAAgB,KAAK;CACvC,OAAO,aAAa,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;AACpF;;AAGA,SAAgB,aAAa,SAA+C;CAC1E,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,QAAQ,OAAO,KAAK,OAAO,GACpC,QAAQ,KAAK,YAAY,KAAK,QAAQ;CAExC,QAAQ,SAAS,QAAQ,KAAK,YAAY;AAC5C"}
+{"version":3,"file":"rsc-cache-key-ClUiXQnK.js","names":[],"sources":["../../src/shared/rsc-cache-key.ts"],"sourcesContent":["/**\n * The `_rsc` payload cache key — derived identically on both sides.\n *\n * The client puts this in the payload URL so the document and its Flight\n * payload occupy different cache keys (TIM-1268). The server recomputes it\n * from the received headers so a request cannot claim one client's key while\n * sending another client's headers — see `server/rsc-cache-key-guard.ts`.\n * Both sides must agree exactly, which is why the derivation lives here and\n * not in either one.\n *\n * Isomorphic: no server or client imports. The browser bundle audit\n * (`tests/client-bundle-audit.test.ts`) enforces the client half of that.\n *\n * See design/19-client-navigation.md §\"The `_rsc` cache key\".\n */\n\n/**\n * Digest length in hex characters. 128 bits: the origin guard compares a\n * caller-supplied key against a recomputed one, so the relevant bound is a\n * birthday attack (an attacker who can influence a victim's `X-Timber-URL`\n * gets to search both sides), not second preimage. 64 bits would fall to\n * ~2^32 work; 128 puts it at 2^64.\n */\nconst KEY_HEX_LENGTH = 32;\n\n/**\n * Marks a value as a framework-issued key, and versions the derivation.\n *\n * Without it, an application value that happened to be 32 lowercase hex — an\n * MD5, a token — is indistinguishable from a forged claim: both are \"the\n * right shape, the wrong digest\", and no information in the value separates\n * them. So the exemption cannot key on shape alone.\n *\n * The prefix resolves that because it is anchored to the address the\n * victim's own client uses. A payload lives at `?_rsc=1.<digest>`, so\n * anything aimed at that cache entry must carry the prefix and therefore\n * gets validated; anything without it cannot be addressing a payload URL at\n * all, and is exempt as application data. An attacker cannot both hit the\n * victim's cache key and dodge the check.\n *\n * The version component also gives the derivation a migration path: the\n * client and the origin must agree byte for byte, so a future change to the\n * canonical form can be rolled out by bumping this instead of a flag day.\n */\nconst KEY_PREFIX = '1.';\n\n/**\n * The request headers that vary an RSC payload response, in canonical\n * casing — this list is also emitted verbatim as the response's `Vary`\n * tokens (`server/pipeline.ts`), since \"what varies the response\" is one\n * question with one answer, not two lists that happen to agree.\n *\n * This list is the contract, and it is enforced rather than trusted:\n * `tests/rsc-cache-key.test.ts` asserts that the header names\n * `buildRscHeaders()` can emit are exactly this set. A header added to the\n * request without being added here fails that test, because a varying input\n * outside the key is precisely the cache-poisoning hazard the key exists to\n * close.\n *\n * **No credentials, session identifiers, or user-supplied content may be\n * added.** Every value here is hashed into a URL, and URLs are logged by\n * proxies, CDNs, and origin access logs. `fnv1aHash` is a cache-key hash,\n * not a KDF — a low-entropy secret would be recoverable by brute force.\n * Authentication travels on cookies, which never enter the key.\n */\nexport const RSC_KEY_HEADERS = [\n  'Accept',\n  'X-Timber-State-Tree',\n  'X-Timber-URL',\n  'X-Timber-Deployment-Id',\n] as const;\n\n/**\n * Whether a value could be a key this module produced.\n *\n * `_rsc` is not a reserved parameter name — an application may already use\n * it for its own search state, including for a value that happens to look\n * like a digest. Anything without the `KEY_PREFIX` is therefore application\n * data, not a claim on a payload cache key, and the origin guard leaves it\n * alone rather than penalizing the response.\n *\n * Derived from `KEY_PREFIX` and `KEY_HEX_LENGTH` rather than spelled again,\n * so the shape cannot drift from the digest that has to satisfy it.\n *\n * Ignoring a malformed value costs no protection: clients only ever send\n * well-formed keys, so a URL bearing a malformed one is an address no\n * legitimate request will ever ask for, and nothing can be poisoned at an\n * address nobody reads.\n */\nexport function isRscCacheKeyShape(value: string): boolean {\n  if (!value.startsWith(KEY_PREFIX)) return false;\n  const digest = value.slice(KEY_PREFIX.length);\n  return digest.length === KEY_HEX_LENGTH && /^[0-9a-f]+$/.test(digest);\n}\n\n/**\n * The query parameter carrying the payload cache key.\n *\n * Spelled here rather than at each of the four places that read or write it\n * — the client that appends it, the origin guard that validates it, and the\n * strip below — because it is a wire contract between two independent\n * implementations, exactly like the digest itself.\n */\nexport const RSC_KEY_PARAM = '_rsc';\n\n// ─── Keeping the key out of application state ────────────────────────────\n\n/**\n * Decode one raw `name` or `value` the way `URLSearchParams` does:\n * `application/x-www-form-urlencoded`, so `+` is a space.\n *\n * Malformed percent-escapes throw in `decodeURIComponent`. `URLSearchParams`\n * leaves those bytes as-is rather than throwing, and so do we — a pair we\n * cannot decode is by definition not the framework's, so it is kept.\n */\nfunction formDecode(raw: string): string {\n  try {\n    return decodeURIComponent(raw.replace(/\\+/g, ' '));\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Remove framework-issued `_rsc` values from a raw query string.\n *\n * Only values matching `isRscCacheKeyShape` are removed. `_rsc` is not a\n * reserved name (see that function), so `/search?_rsc=foo` is application\n * state and survives — the same exemption the origin guard applies, derived\n * from the same predicate so the two cannot disagree about what \"ours\"\n * means.\n *\n * Operates on the raw string rather than round-tripping through\n * `URLSearchParams`, so every surviving pair keeps its original bytes.\n * Re-serializing would rewrite `?b` as `?b=` and `?a=%7E` as `?a=~` on RSC\n * navigations only, which is the same class of inconsistency this function\n * exists to remove.\n *\n * Matching decodes the name, because `?%5Frsc=<key>` is a `_rsc` parameter\n * as far as `URLSearchParams` is concerned — the same reasoning as the\n * guard's fast path.\n *\n * @param search - `url.search`, with or without the leading `?`.\n * @returns The query string including a leading `?`, or `''` if empty.\n */\nexport function stripRscCacheKey(search: string): string {\n  const query = search.startsWith('?') ? search.slice(1) : search;\n  if (query === '') return '';\n  const kept = query.split('&').filter((pair) => {\n    const eq = pair.indexOf('=');\n    if (formDecode(eq === -1 ? pair : pair.slice(0, eq)) !== RSC_KEY_PARAM) return true;\n    return !isRscCacheKeyShape(eq === -1 ? '' : formDecode(pair.slice(eq + 1)));\n  });\n  const result = kept.join('&');\n  return result === '' ? '' : `?${result}`;\n}\n\n/** A request's search state as application code should see it. */\nexport interface AppVisibleSearch {\n  /** Parsed params, with the framework's cache key removed. */\n  params: URLSearchParams;\n  /** The matching raw query string — `''` or `?…`. */\n  search: string;\n}\n\n/**\n * The search state application code sees, for any request URL.\n *\n * The `_rsc` key rides on the payload URL of every RSC navigation and on no\n * other request, so reading search params straight off `req.url` makes the\n * same page observe different search state depending on whether it was\n * reached by a full load or a client navigation — and lets the cache key\n * leak into whatever the page builds from it: a canonical URL, a pagination\n * link, an analytics payload (TIM-1272).\n *\n * Every application-facing derivation of search state goes through here.\n * `params` and `search` are returned together, from one strip, because they\n * are two views of one answer and were previously two expressions that had\n * to agree.\n *\n * The raw request URL is deliberately untouched: `server/rsc-cache-key-guard.ts`\n * still reads the parameter from `req.url` to bind the key to the request.\n */\nexport function appVisibleSearch(url: URL): AppVisibleSearch {\n  const search = stripRscCacheKey(url.search);\n  return { params: new URLSearchParams(search), search };\n}\n\n/**\n * Reads a header value by name. Must be case-insensitive — `Headers.get()`\n * already is, and `recordLookup` below makes a plain record so.\n */\nexport type HeaderLookup = (name: string) => string | null | undefined;\n\n/**\n * Compute the `_rsc` cache key for a request.\n *\n * Absent headers are omitted rather than sent as empty, so \"header missing\"\n * and \"header present but empty\" produce different keys.\n *\n * Values are length-prefixed rather than delimiter-separated. Any delimiter\n * can be forged by a value that contains it: with a `\\0` separator, an\n * `accept` of `a\\nx-timber-url\\0b` serializes identically to an `accept` of\n * `a` alongside an `x-timber-url` of `b`, which would let one header claim\n * another's key. HTTP forbids control characters in header values and both\n * `fetch()` and the server runtime reject them, so this is defense in depth\n * — but a length prefix is unambiguous for *any* content, which is a\n * property worth having in a function whose whole job is to be agreed on by\n * two independent implementations.\n *\n * SHA-256, truncated to 128 bits. A fast non-cryptographic hash is the\n * obvious choice for a cache key and is the wrong one here: the origin\n * *compares* this value against a recomputed one, which makes it a check.\n * FNV-1a — used for timber's other cache keys — is a multiply-xor over a\n * fixed field, so an attacker controlling a few bytes of any input (their\n * own `X-Timber-URL`, say) can solve for a chosen digest rather than search\n * for one, and forge a key belonging to somebody else.\n *\n * Returns `null` when no digest is available — `crypto.subtle` is absent in\n * non-secure browsing contexts (plain `http://` on a LAN address). Callers\n * must treat that as \"no key\", never as \"key matches\": the client omits the\n * parameter and the server refuses to share-cache. That returns those\n * clients to the pre-TIM-1268 posture, where `Vary` alone separates HTML\n * from Flight — acceptable, because a non-secure origin has no shared-CDN\n * caching story to protect in the first place.\n */\nexport async function rscCacheKey(lookup: HeaderLookup): Promise<string | null> {\n  const subtle = globalThis.crypto?.subtle;\n  if (!subtle) return null;\n  let canonical = '';\n  for (const name of RSC_KEY_HEADERS) {\n    const value = lookup(name);\n    if (value == null) continue;\n    // Lowercased in the canonical form so the two implementations cannot\n    // disagree over the casing of the constant they share.\n    canonical += `${name.toLowerCase()}:${value.length}:${value}`;\n  }\n  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(canonical));\n  let hex = '';\n  for (const byte of new Uint8Array(digest, 0, KEY_HEX_LENGTH / 2)) {\n    hex += byte.toString(16).padStart(2, '0');\n  }\n  return KEY_PREFIX + hex;\n}\n\n/**\n * An unverifiable stand-in key, for the one case where the digest cannot be\n * computed: `crypto.subtle` is absent in non-secure browsing contexts.\n * `crypto.getRandomValues` is not gated that way, so it is available exactly\n * where the digest is not.\n *\n * Carries `KEY_PREFIX` like any other key, so the origin reads it as a claim\n * it cannot verify — and refuses to share-cache the response — rather than\n * exempting it as application data. Lives here so the prefix has one home.\n */\nexport function randomRscCacheKey(): string {\n  const bytes = new Uint8Array(KEY_HEX_LENGTH / 2);\n  globalThis.crypto.getRandomValues(bytes);\n  return KEY_PREFIX + [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');\n}\n\n/** Build a case-insensitive lookup over a plain header record. */\nexport function recordLookup(headers: Record<string, string>): HeaderLookup {\n  const lowered: Record<string, string> = {};\n  for (const name of Object.keys(headers)) {\n    lowered[name.toLowerCase()] = headers[name];\n  }\n  return (name) => lowered[name.toLowerCase()];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;AAqBvB,IAAM,aAAa;;;;;;;;;;;;;;;;;;;;AAqBnB,IAAa,kBAAkB;CAC7B;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,mBAAmB,OAAwB;CACzD,IAAI,CAAC,MAAM,WAAW,UAAU,GAAG,OAAO;CAC1C,MAAM,SAAS,MAAM,MAAM,CAAiB;CAC5C,OAAO,OAAO,WAAW,kBAAkB,cAAc,KAAK,MAAM;AACtE;;;;;;;;;AAUA,IAAa,gBAAgB;;;;;;;;;AAY7B,SAAS,WAAW,KAAqB;CACvC,IAAI;EACF,OAAO,mBAAmB,IAAI,QAAQ,OAAO,GAAG,CAAC;CACnD,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,iBAAiB,QAAwB;CACvD,MAAM,QAAQ,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI;CACzD,IAAI,UAAU,IAAI,OAAO;CAMzB,MAAM,SALO,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,SAAS;EAC7C,MAAM,KAAK,KAAK,QAAQ,GAAG;EAC3B,IAAI,WAAW,OAAO,KAAK,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC,MAAA,QAAqB,OAAO;EAC/E,OAAO,CAAC,mBAAmB,OAAO,KAAK,KAAK,WAAW,KAAK,MAAM,KAAK,CAAC,CAAC,CAAC;CAC5E,CACe,CAAA,CAAK,KAAK,GAAG;CAC5B,OAAO,WAAW,KAAK,KAAK,IAAI;AAClC;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBAAiB,KAA4B;CAC3D,MAAM,SAAS,iBAAiB,IAAI,MAAM;CAC1C,OAAO;EAAE,QAAQ,IAAI,gBAAgB,MAAM;EAAG;CAAO;AACvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,eAAsB,YAAY,QAA8C;CAC9E,MAAM,SAAS,WAAW,QAAQ;CAClC,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,YAAY;CAChB,KAAK,MAAM,QAAQ,iBAAiB;EAClC,MAAM,QAAQ,OAAO,IAAI;EACzB,IAAI,SAAS,MAAM;EAGnB,aAAa,GAAG,KAAK,YAAY,EAAE,GAAG,MAAM,OAAO,GAAG;CACxD;CACA,MAAM,SAAS,MAAM,OAAO,OAAO,WAAW,IAAI,YAAY,CAAC,CAAC,OAAO,SAAS,CAAC;CACjF,IAAI,MAAM;CACV,KAAK,MAAM,QAAQ,IAAI,WAAW,QAAQ,GAAG,iBAAiB,CAAC,GAC7D,OAAO,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CAE1C,OAAO,aAAa;AACtB;;;;;;;;;;;AAYA,SAAgB,oBAA4B;CAC1C,MAAM,QAAQ,IAAI,WAAW,iBAAiB,CAAC;CAC/C,WAAW,OAAO,gBAAgB,KAAK;CACvC,OAAO,aAAa,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;AACpF;;AAGA,SAAgB,aAAa,SAA+C;CAC1E,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,QAAQ,OAAO,KAAK,OAAO,GACpC,QAAQ,KAAK,YAAY,KAAK,QAAQ;CAExC,QAAQ,SAAS,QAAQ,KAAK,YAAY;AAC5C"}