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

package/dist/client/browser-entry/hydrate.d.ts

@@ -6,13 +6,17 @@
  * 2. No RSC payload: deferred root creation via installDeferredNavigation
  *
  * Pre-hydration ordering contract (MUST execute in this order):
- *   1. initRouter()        — creates the global router so useRouter()
- *                            works during render
- *   2. setCurrentParams()  — populates params snapshot so
- *      + setNavigationState()  useSegmentParams() and usePathname()
- *                            return correct values during hydration
- *   3. hydrateRoot()       — synchronously executes component render
- *                            functions that depend on steps 1-2
+ *   1. initRouter()          — creates the global router so useRouter()
+ *                              works during render
+ *   2. setNavigationState()  — populates pathname/search so usePathname()
+ *                              returns correct values during hydration
+ *   3. hydrateRoot()         — synchronously executes component render
+ *                              functions that depend on steps 1-2
+ *
+ * Params are not part of this sequence. They arrive on the payload root and
+ * are published by `PayloadRoot` at the top of the tree, so
+ * `useSegmentParams()` is correct during hydration without anything having to
+ * run before it (TIM-1294, TIM-1297).
  *
  * See design/19-client-navigation.md §"NavigationContext"
  */
@@ -27,8 +31,15 @@ interface HydrateOptions {
     };
 }
 /**
- * Run the pre-hydration sequence: read server-embedded params and
- * set navigation state. Must be called AFTER initRouter().
+ * Run the pre-hydration sequence: set navigation state from the address bar.
+ * Must be called AFTER initRouter().
+ *
+ * Params are no longer seeded here. They used to arrive on two inline scripts
+ * that had to execute before `hydrateRoot()`, because hydration synchronously
+ * renders components that read them. They now ride the payload root, and the
+ * provider that publishes them renders before its own descendants — so the
+ * ordering the step existed to guarantee is now a property of the tree rather
+ * than of the bootstrap sequence (TIM-1294, TIM-1297).
  */
 export declare function runPreHydration(): void;
 /**

package/dist/client/browser-entry/hydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwCvD,UAAU,cAAc;IACtB,qDAAqD;IACrD,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,gDAAgD;IAChD,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAiBtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CAyEtE"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAeH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwCvD,UAAU,cAAc;IACtB,qDAAqD;IACrD,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,gDAAgD;IAChD,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAKtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CAoFtE"}

package/dist/client/browser-entry/index.d.ts

@@ -25,5 +25,5 @@
  *
  * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
  */
-import 'virtual:timber-search-params-registry';
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/client/browser-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH,OAAO,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/client/browser-entry/post-hydration.d.ts

@@ -12,15 +12,18 @@
  */
 import type { RouterInstance } from '#client-internal';
 import type { NavigationApiController } from '../navigation-api.js';
+import type { ParamsSource } from '../../shared/payload-root.js';
 interface PostHydrationOptions {
     router: RouterInstance;
     navApiController: NavigationApiController | null;
     /** Decoded RSC element from initial SSR (null if no RSC payload) */
     initialElement: unknown;
+    /** The params that payload published, from the same decode. */
+    initialParams: ParamsSource;
 }
 /**
  * Wire up post-hydration event handlers and state.
  */
-export declare function setupPostHydration({ router, navApiController, initialElement, }: PostHydrationOptions): void;
+export declare function setupPostHydration({ router, navApiController, initialElement, initialParams, }: PostHydrationOptions): void;
 export {};
 //# sourceMappingURL=post-hydration.d.ts.map

package/dist/client/browser-entry/post-hydration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-hydration.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/post-hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,UAAU,oBAAoB;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACjD,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,gBAAgB,EAChB,cAAc,GACf,EAAE,oBAAoB,GAAG,IAAI,CAwF7B"}
+{"version":3,"file":"post-hydration.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/post-hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,UAAU,oBAAoB;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACjD,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,aAAa,EAAE,YAAY,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,gBAAgB,EAChB,cAAc,EACd,aAAa,GACd,EAAE,oBAAoB,GAAG,IAAI,CAqF7B"}

package/dist/client/browser-entry/router-init.d.ts

@@ -6,10 +6,13 @@
  *
  * See design/19-client-navigation.md §"Navigation API Integration"
  */
+import { type ParamsSource } from '../../shared/payload-root.js';
 import type { RouterInstance } from '#client-internal';
 import { type NavigationApiController } from '../navigation-api.js';
 export interface RouterInitOptions {
     initialElement?: unknown;
+    /** The params the hydration payload published, beside `initialElement`. */
+    initialParams?: ParamsSource;
     clientSegmentCache?: boolean;
 }
 export interface RouterInitResult {

package/dist/client/browser-entry/router-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router-init.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/router-init.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUnE,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CA+OhF"}
+{"version":3,"file":"router-init.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/router-init.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEtF,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUnE,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CAmShF"}

package/dist/client/browser-entry/rsc-stream.d.ts

@@ -10,9 +10,17 @@
  *
  * See design/18-build-system.md §"Entry Files"
  */
+import { type PublishedParams } from '../../shared/payload-root.js';
 export interface RscStreamResult {
     /** The decoded RSC element (thenable/lazy — resolved by React during render) */
     element: unknown;
+    /**
+     * The params the same payload published beside that tree. A promise: the
+     * inlined Flight stream is still arriving when this runs, and hydration must
+     * not wait for it. `PayloadRoot` suspends on it at the position React was
+     * going to suspend on `element` anyway (TIM-1297).
+     */
+    params: Promise<PublishedParams>;
 }
 /**
  * Create the RSC payload stream from server-inlined `__timber_f` chunks.

package/dist/client/browser-entry/rsc-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc-stream.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/rsc-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,GAAG,IAAI,CA+H/D"}
+{"version":3,"file":"rsc-stream.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/rsc-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAItF,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,GAAG,IAAI,CAgI/D"}

package/dist/client/error-boundary.d.ts

@@ -38,6 +38,12 @@ export interface TimberErrorBoundaryProps {
      * graceful degradation — they must NOT change the HTTP status code.
      */
     isSlotBoundary?: boolean;
+    /**
+     * Segment key of the segment that declared this boundary. Only meaningful
+     * against a deny digest carrying an `ownerKey`. See the decline rule in
+     * `render()` and TIM-1356.
+     */
+    segmentKey?: string;
     children: ReactNode;
 }
 interface TimberErrorBoundaryState {
@@ -47,6 +53,7 @@ interface TimberErrorBoundaryState {
 export declare class TimberErrorBoundary extends Component<TimberErrorBoundaryProps, TimberErrorBoundaryState> {
     constructor(props: TimberErrorBoundaryProps);
     static getDerivedStateFromError(error: Error): TimberErrorBoundaryState;
+    componentDidCatch(error: Error): void;
     componentDidUpdate(prevProps: TimberErrorBoundaryProps): void;
     /** Reset the error state so children re-render. */
     private reset;

package/dist/client/error-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../src/client/error-boundary.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA8CjE,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,SAAS,CAAC;IACtD;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAkBD,qBAAa,mBAAoB,SAAQ,SAAS,CAChD,wBAAwB,EACxB,wBAAwB,CACzB;IACC,YAAY,KAAK,EAAE,wBAAwB,EAG1C;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,wBAAwB,CAUtE;IAED,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAO5D;IAED,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAEX;IAEF,MAAM,IAAI,SAAS,CA2IlB;CACF"}
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../src/client/error-boundary.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA4CjE,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,SAAS,CAAC;IACtD;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAkBD,qBAAa,mBAAoB,SAAQ,SAAS,CAChD,wBAAwB,EACxB,wBAAwB,CACzB;IACC,YAAY,KAAK,EAAE,wBAAwB,EAG1C;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,wBAAwB,CAUtE;IAED,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAWpC;IAED,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAO5D;IAED,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAEX;IAEF,MAAM,IAAI,SAAS,CAuKlB;CACF"}

package/dist/client/error-boundary.js

@@ -1,165 +1,4 @@
 "use client";
 "use client";
-import { n as getSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
-import { n as getRouterOrNull } from "../_chunks/router-ref-CtmF-aPv.js";
-import { Component, createElement } from "react";
-//#region src/client/error-boundary.tsx
-/**
-* Framework-injected React error boundary.
-*
-* Catches errors thrown by children and renders a fallback component
-* with the appropriate props based on error type:
-*   - DenySignal (4xx) → { status, dangerouslyPassData }
-*   - RenderError (5xx) → { error, digest, reset }
-*   - Unhandled error → { error, digest: null, reset }
-*
-* The `status` prop controls which errors this boundary catches:
-*   - Specific code (e.g. 403) → only that status
-*   - Category (400) → any 4xx
-*   - Category (500) → any 5xx
-*   - Omitted → catches everything (error.tsx behavior)
-*
-* See design/10-error-handling.md §"Status-Code Files"
-*/
-var _isUnloading = false;
-if (typeof window !== "undefined") {
-	window.addEventListener("beforeunload", () => {
-		_isUnloading = true;
-	});
-	window.addEventListener("pagehide", () => {
-		_isUnloading = true;
-	});
-}
-var _handledRedirects = /* @__PURE__ */ new WeakSet();
-var _pendingRedirectLocation = null;
-var TimberErrorBoundary = class extends Component {
-	constructor(props) {
-		super(props);
-		this.state = {
-			hasError: false,
-			error: null
-		};
-	}
-	static getDerivedStateFromError(error) {
-		if (_isUnloading) return {
-			hasError: false,
-			error: null
-		};
-		return {
-			hasError: true,
-			error
-		};
-	}
-	componentDidUpdate(prevProps) {
-		if (this.state.hasError && prevProps.children !== this.props.children) this.setState({
-			hasError: false,
-			error: null
-		});
-	}
-	/** Reset the error state so children re-render. */
-	reset = () => {
-		this.setState({
-			hasError: false,
-			error: null
-		});
-	};
-	render() {
-		if (!this.state.hasError || !this.state.error) return this.props.children;
-		const error = this.state.error;
-		const parsed = parseDigest(error);
-		if (parsed?.type === "redirect") {
-			if (typeof window === "undefined") throw error;
-			if (!(_handledRedirects.has(error) || _pendingRedirectLocation === parsed.location)) {
-				_handledRedirects.add(error);
-				const router = getRouterOrNull();
-				if (router) {
-					_pendingRedirectLocation = parsed.location;
-					queueMicrotask(() => {
-						router.navigate(parsed.location, { replace: true }).catch(() => {
-							window.location.href = parsed.location;
-						}).finally(() => {
-							_pendingRedirectLocation = null;
-						});
-					});
-				} else window.location.href = parsed.location;
-			}
-			return null;
-		}
-		if (this.props.status != null) {
-			const errorStatus = getErrorStatus(parsed, error);
-			if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) throw error;
-		}
-		if (parsed?.type === "deny") {
-			if (this.props.fallbackElement == null || this.props.isSlotBoundary) {
-				const ssrData = getSsrData();
-				if (ssrData?._navContext) {
-					ssrData._navContext._denyHandledByBoundary = true;
-					if (!this.props.isSlotBoundary) ssrData._navContext.statusCode = parsed.status;
-				}
-			}
-		}
-		if (this.props.fallbackElement != null) return this.props.fallbackElement;
-		if (parsed?.type === "deny") {
-			if (this.props.status != null) return createElement(this.props.fallbackComponent, {
-				status: parsed.status,
-				dangerouslyPassData: parsed.data
-			});
-			return createElement(this.props.fallbackComponent, {
-				error,
-				digest: null,
-				reset: this.reset,
-				status: parsed.status,
-				dangerouslyPassData: parsed.data
-			});
-		}
-		const digest = parsed?.type === "render-error" ? {
-			code: parsed.code,
-			data: parsed.data
-		} : null;
-		return createElement(this.props.fallbackComponent, {
-			error,
-			digest,
-			reset: this.reset
-		});
-	}
-};
-/**
-* Parse the structured digest from the error.
-* React sets `error.digest` from the string returned by RSC's onError.
-*/
-function parseDigest(error) {
-	const raw = error.digest;
-	if (typeof raw !== "string") return null;
-	try {
-		const parsed = JSON.parse(raw);
-		if (parsed && typeof parsed === "object" && typeof parsed.type === "string") return parsed;
-	} catch (e) {
-		console.debug("[timber] error digest is not valid JSON:", e instanceof Error ? e.message : e);
-	}
-	return null;
-}
-/**
-* Extract the HTTP status code from a parsed digest or error message.
-* Falls back to message pattern matching for errors without a digest.
-*/
-function getErrorStatus(parsed, error) {
-	if (parsed?.type === "deny") return parsed.status;
-	if (parsed?.type === "render-error") return parsed.status;
-	if (parsed?.type === "redirect") return parsed.status;
-	const match = error.message.match(/^Access denied with status (\d+)$/);
-	if (match) return parseInt(match[1], 10);
-	return 500;
-}
-/**
-* Check whether an error's status matches the boundary's status filter.
-* Category markers (400, 500) match any status in that range.
-*/
-function statusMatches(boundaryStatus, errorStatus) {
-	if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;
-	if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;
-	return boundaryStatus === errorStatus;
-}
-//#endregion
+import { t as TimberErrorBoundary } from "../_chunks/error-boundary-D-ODYX41.js";
 export { TimberErrorBoundary };
-
-//# sourceMappingURL=error-boundary.js.map

package/dist/client/history.d.ts

@@ -1,14 +1,21 @@
-import type { SegmentInfo } from './segment-cache';
+import type { ParamsSource } from '../shared/payload-root.js';
+import type { SegmentInfo } from '../shared/segment-info.js';
 export interface HistoryEntry {
     /** The complete segment tree payload at the time of navigation */
     payload: unknown;
     /**
-     * Route params for this page (for useSegmentParams). Every entry that can
-     * be replayed must carry them — the initial SSR entry gets them from the
-     * server-embedded __timber_params, navigation entries from X-Timber-Params,
-     * and revalidation overwrites preserve the current state (TIM-1037).
+     * The params that payload published. Replaying the tree republishes them,
+     * because the client owns the provider now and reads it from here
+     * (TIM-1297).
+     *
+     * Stored beside the tree but never *produced* beside it: both come out of
+     * one `splitPayloadRoot` on one decoded root and travel together through
+     * `prepareNavigation`, the only producer of an entry. That is the property
+     * that matters — when they were derived from separate channels, a replay
+     * could restore one route's tree with another route's params (TIM-1037,
+     * TIM-1285).
      */
-    params?: Record<string, string | string[]> | null;
+    params: ParamsSource;
     /**
      * Segment metadata for this page's route. Restored into the segment cache
      * on popstate cached replay so the next forward navigation computes a

package/dist/client/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/client/history.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAClD;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CACpC;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmC;IAElD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAE3C;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEzC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExB;CACF"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/client/history.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAI7D,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CACpC;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmC;IAElD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAE3C;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEzC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExB;CACF"}

package/dist/client/index.d.ts

@@ -16,5 +16,6 @@ export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selec
 export { useActionState, useFormAction } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 export { useSegmentParams } from './use-segment-params';
+export { useQueryStates } from './use-query-states';
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC/F,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AA4CpF,MAAM,WAAW,YAAY;CAG5B;AACD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAOxD,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC/F,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AA4CpF,MAAM,WAAW,YAAY;CAG5B;AACD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAKvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAYxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpD,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/client/index.js

@@ -1,14 +1,13 @@
 "use client";
-import { n as classifyUrlSegment } from "../_chunks/segment-classify-Byy425ng.js";
-import { t as getSearchParamsDefinition } from "../_chunks/registry-DbJPKoBp.js";
-import { n as getSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
-import { n as useSegmentParams, o as useNavigationContext } from "../_chunks/use-segment-params-D1CzlgBo.js";
+import { n as classifyUrlSegment } from "../_chunks/segment-classify-C539Pa2O.js";
 import { a as mergePreservedSearchParams, i as validateNavigationHref, n as isInternalHref } from "../_chunks/href-validation-CMc5JRls.js";
-import { n as getRouterOrNull } from "../_chunks/router-ref-CtmF-aPv.js";
-import { n as useSegmentContext } from "../_chunks/segment-context-ZDnXDkbz.js";
+import { n as getSsrData } from "../_chunks/ssr-data-14MXm7Pj.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-DuYuV_0Q.js";
+import { n as useSegmentContext } from "../_chunks/segment-context-CjOlyB8Y.js";
 import { t as getLinkCodec } from "../_chunks/codec-registry-oOUxugz3.js";
-import { r as usePendingNavigation } from "../_chunks/navigation-root-bUDZLw74.js";
-import { createContext, useActionState as useActionState$1, useContext, useTransition } from "react";
+import { l as useNavigationContext, r as useSegmentParams, u as usePendingNavigation } from "../_chunks/use-segment-params-C4r4BD9T.js";
+import { n as useQueryStates } from "../_chunks/use-query-states-BbU5Ge1V.js";
+import { createContext, useActionState as useActionState$1, useContext, useRef, useState, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -142,44 +141,39 @@ function interpolateParams(pattern, params) {
 *
 * Handles:
 * - params interpolation into route patterns
-* - searchParams serialization via SearchParamsDefinition
+* - searchParams serialization (see the two shapes documented above)
 * - Validation that searchParams and inline query strings are exclusive
 */
 /**
-* Runtime discriminator: treat `searchParams` as the legacy wrapped shape
-* only when it literally has a `definition` key. Everything else is the
-* flat `Partial<T>` values shape (TIM-830).
+* Tolerate a leading '?'. `buildSearchParams()` never emits one, but callers
+* hand-rolling a query string reasonably might, and silently producing
+* `?%3Fa=b` for it would be a worse failure than accepting both.
 */
-function isWrappedSearchParamsProp(sp) {
-	return "definition" in sp;
+function stripLeadingQuestionMark(qs) {
+	return qs.startsWith("?") ? qs.slice(1) : qs;
+}
+/**
+* Escape-hatch serialization for a plain object: String()-coerce every
+* value, append arrays as repeated keys, skip null/undefined.
+*
+* Deliberately codec-free and alias-free — see the shape docs above.
+*/
+function coerceToQueryString(values) {
+	const usp = new URLSearchParams();
+	for (const [key, val] of Object.entries(values)) {
+		if (val === void 0 || val === null) continue;
+		if (Array.isArray(val)) for (const item of val) usp.append(key, String(item));
+		else usp.set(key, String(val));
+	}
+	return usp.toString();
 }
 function resolveHref(href, params, searchParams) {
 	let resolvedPath = href;
 	if (params) resolvedPath = interpolateParams(href, params);
 	if (searchParams) {
 		if (resolvedPath.includes("?")) throw new Error("<Link> received both a searchParams prop and a query string in href. These are mutually exclusive — use one or the other.");
-		let definition;
-		let values;
-		if (isWrappedSearchParamsProp(searchParams)) {
-			definition = searchParams.definition;
-			values = searchParams.values;
-		} else {
-			definition = getSearchParamsDefinition(href);
-			values = searchParams;
-		}
-		if (definition) {
-			const qs = definition.serialize(values);
-			if (qs) resolvedPath = `${resolvedPath}?${qs}`;
-		} else {
-			const usp = new URLSearchParams();
-			for (const [key, val] of Object.entries(values)) {
-				if (val === void 0 || val === null) continue;
-				if (Array.isArray(val)) for (const item of val) usp.append(key, String(item));
-				else usp.set(key, String(val));
-			}
-			const qs = usp.toString();
-			if (qs) resolvedPath = `${resolvedPath}?${qs}`;
-		}
+		const qs = typeof searchParams === "string" ? stripLeadingQuestionMark(searchParams) : coerceToQueryString(searchParams);
+		if (qs) resolvedPath = `${resolvedPath}?${qs}`;
 	}
 	return resolvedPath;
 }
@@ -237,7 +231,8 @@ var Link = function LinkImpl(props) {
 		params: segmentParams,
 		searchParams
 	});
-	const [isPending, startTransition] = useTransition();
+	const [isPending, setIsPending] = useState(false);
+	const clickSeq = useRef(0);
 	const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 	const internal = isInternalHref(baseHref);
 	const resolvedHref = preserveSearchParams && internal ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
@@ -262,8 +257,14 @@ var Link = function LinkImpl(props) {
 		event.preventDefault();
 		const shouldScroll = scroll !== false;
 		const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
-		startTransition(async () => {
-			await router.navigate(absoluteHref, { scroll: shouldScroll });
+		const seq = ++clickSeq.current;
+		const settle = () => {
+			if (clickSeq.current === seq) setIsPending(false);
+		};
+		setIsPending(true);
+		router.navigate(absoluteHref, { scroll: shouldScroll }).then(settle, (error) => {
+			settle();
+			throw error;
 		});
 	} : userOnClick;
 	const handleMouseEnter = internal && prefetch ? (event) => {
@@ -304,7 +305,7 @@ var Link = function LinkImpl(props) {
 * In timber, navigation calls reactRoot.render() which is a root-level
 * render — startTransition has no effect on root renders.
 *
-* Navigation state (params, pathname) is delivered atomically via
+* Navigation state (pathname, search) is delivered atomically via
 * NavigationContext embedded in the element tree passed to
 * reactRoot.render(). See design/19-client-navigation.md §"NavigationContext".
 *
@@ -640,6 +641,6 @@ function deriveFormErrors(result) {
 	};
 }
 //#endregion
-export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, replaceUrl, resolveHref, useActionState, useFormAction, useLinkStatus, usePathname, usePendingNavigation, useRouter, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateNavigationHref as validateLinkHref };
+export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, replaceUrl, resolveHref, useActionState, useFormAction, useLinkStatus, usePathname, usePendingNavigation, useQueryStates, useRouter, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateNavigationHref as validateLinkHref };
 
 //# sourceMappingURL=index.js.map