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

package/dist/cache/singleflight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACzE;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAGzC;CACF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAkD3E"}
+{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxE,oEAAoE;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;CAChD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAGzC;CACF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAqD3E"}

package/dist/cli.js

@@ -136,7 +136,7 @@ async function runPreview(options, _deps) {
 * `--project` names the tsconfig handed to tsgo.
 */
 async function runCheck(options, _deps) {
-	const { checkRoutes, runTypeCheck } = await import("./_chunks/cli-check-BVthpfLS.js");
+	const { checkRoutes, runTypeCheck } = await import("./_chunks/cli-check-dVDi1GQz.js");
 	const { root } = await checkRoutes({ viteConfigFile: options.config }, _deps);
 	await runTypeCheck({
 		root,
@@ -152,7 +152,7 @@ async function runCheck(options, _deps) {
 async function runSchema(args) {
 	const subcommand = args[0];
 	if (subcommand !== "sync") throw new Error(`Unknown schema subcommand: ${subcommand ?? "(none)"}. Usage: timber schema sync`);
-	const { runSchemaSync, defaultCodecForSegment } = await import("./_chunks/cli-schema-sync-3Wutm8pH.js").then((n) => n.t);
+	const { runSchemaSync, defaultCodecForSegment } = await import("./_chunks/cli-schema-sync-DTy_-Msq.js").then((n) => n.t);
 	const result = runSchemaSync(process.cwd());
 	if (result.filesystemSegments.length === 0) {
 		console.log("[timber] No dynamic segments found in app/.");

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

@@ -1,9 +1,10 @@
 /**
- * Hydration — pre-hydration sequence and React root creation.
+ * Hydration — pre-hydration sequence and hydrating the React root.
  *
  * Handles two paths:
- * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
- * 2. No RSC payload: deferred root creation via installDeferredNavigation
+ * 1. RSC payload available: hydrate the router's React root with the payload
+ * 2. No RSC payload: nothing — the root is created by the first render
+ *    (client/react-root.ts)
  *
  * Pre-hydration ordering contract (MUST execute in this order):
  *   1. initRouter()          — creates the global router so useRouter()
@@ -20,15 +21,16 @@
  *
  * See design/19-client-navigation.md §"NavigationContext"
  */
-import type { TopLoaderConfig } from '../top-loader.tsx';
+import type { ReactRootHost } from '../react-root.ts';
 import type { RscStreamResult } from './rsc-stream.ts';
+import type { RouterInitResult } from './router-init.ts';
 interface HydrateOptions {
     /** RSC stream result (null if no inlined payload) */
     rscResult: RscStreamResult | null;
-    /** Runtime config from virtual:timber-config */
-    config: {
-        topLoader?: TopLoaderConfig;
-    };
+    /** The router's React root — the one every navigation renders through. */
+    reactRoot: ReactRootHost;
+    /** The router's wrapper chain — see `RouterInitResult.renderTree`. */
+    renderTree: RouterInitResult['renderTree'];
 }
 /**
  * Run the pre-hydration sequence: set navigation state from the address bar.
@@ -43,15 +45,19 @@ interface HydrateOptions {
  */
 export declare function runPreHydration(): void;
 /**
- * Hydrate the React tree or set up deferred root creation.
+ * Hydrate the React tree when an RSC payload is available.
  *
- * When an RSC payload is available, wraps it with NavigationProvider +
- * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
- * document.
+ * Wraps the payload with the router's chain (NavigationProvider,
+ * TimberNuqsAdapter, the slot content cache, ...) and hydrates the router's
+ * React root with it, on the document.
  *
- * When no RSC payload is available (JS-only client), sets up deferred
- * navigation so the first client navigation creates the React root.
+ * When no RSC payload is available (JS-only client) there is nothing to
+ * hydrate and nothing to do: the root must not be created at bootstrap —
+ * `createRoot(document).render()` would take React ownership of the entire
+ * document and blank the SSR HTML — so the router's first render, i.e. the
+ * first navigation or revalidation, creates it with the tree it renders
+ * (`createReactRoot`, TIM-600 / TIM-580).
  */
-export declare function hydrateApp({ rscResult, config }: HydrateOptions): void;
+export declare function hydrateApp({ rscResult, reactRoot, renderTree }: HydrateOptions): void;
 export {};
 //# sourceMappingURL=hydrate.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAeH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,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"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAwCzD,UAAU,cAAc;IACtB,qDAAqD;IACrD,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,0EAA0E;IAC1E,SAAS,EAAE,aAAa,CAAC;IACzB,sEAAsE;IACtE,UAAU,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAKtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,cAAc,GAAG,IAAI,CAmCrF"}

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

@@ -7,7 +7,7 @@
  *   action-dispatch.ts  — server action callServer callback
  *   rsc-stream.ts       — __timber_f chunk handling + ReadableStream
  *   router-init.ts      — createRouter + Navigation API setup
- *   hydrate.ts          — pre-hydration sequence + hydrateRoot/createRoot
+ *   hydrate.ts          — pre-hydration sequence + hydrating the root
  *   post-hydration.ts   — history stack, segment cache, popstate, scroll
  *   hmr.ts              — dev-only HMR + error forwarding
  *   scroll.ts           — getScrollY helper
@@ -16,9 +16,10 @@
  *
  *   1. setupServerActions()      — register callServer (independent)
  *   2. createRscPayloadStream()  — decode inlined RSC payload
- *   3. createTimberRouter()      — create router + Navigation API
+ *   3. createReactRoot() +       — the root host the router renders through,
+ *      createTimberRouter()        then the router + Navigation API
  *   4. runPreHydration()         — set params + navigation state
- *   5. hydrateApp()              — hydrateRoot or deferred createRoot
+ *   5. hydrateApp()              — hydrate the root (no-op without a payload)
  *   6. setupPostHydration()      — history stack, popstate, scroll
  *   7. setupHmr()                — dev-only HMR wiring
  *   8. timber-ready signal       — E2E test readiness indicator

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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

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;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"}
+{"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;AAGjE,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

@@ -8,8 +8,16 @@
  */
 import { type ParamsSource } from '../../shared/payload-root.ts';
 import type { RouterInstance } from '#client-internal';
+import type { NavigationState } from '#client-internal';
+import type { NavigationRender } from '../navigation-root.tsx';
 import { type NavigationApiController } from '../navigation-api.ts';
 export interface RouterInitOptions {
+    /**
+     * The router's React root (`createReactRoot().render`). Every path that puts
+     * a page on screen renders through it — it is the synchronous transition
+     * around `root.render`, and the `publish` it takes runs on React's commit.
+     */
+    render: NavigationRender;
     initialElement?: unknown;
     /** The params the hydration payload published, beside `initialElement`. */
     initialParams?: ParamsSource;
@@ -18,6 +26,14 @@ export interface RouterInitOptions {
 export interface RouterInitResult {
     router: RouterInstance;
     navApiController: NavigationApiController | null;
+    /**
+     * The client's wrapper chain around a tree — the one every navigation
+     * renders through. Hydration builds its root with this too, so the
+     * hydrated tree and the first navigated tree cannot differ in shape
+     * (a type present on one and absent on the other remounts everything
+     * below it) and share the router's slot content cache.
+     */
+    renderTree: (tree: unknown, navState: NavigationState, params: ParamsSource) => React.ReactElement;
 }
 /**
  * Create and register the global timber router.
@@ -26,5 +42,5 @@ export interface RouterInitResult {
  * the initial render (methods lazily resolve the router at invocation,
  * not render time, but initRouter must still run first).
  */
-export declare function createTimberRouter(options?: RouterInitOptions): RouterInitResult;
+export declare function createTimberRouter(options: RouterInitOptions): RouterInitResult;
 //# sourceMappingURL=router-init.d.ts.map

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,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"}
+{"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;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAQxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAK9B,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,EAAE,gBAAgB,CAAC;IACzB,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;IACjD;;;;;;OAMG;IACH,UAAU,EAAE,CACV,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,YAAY,KACjB,KAAK,CAAC,YAAY,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAgU/E"}

package/dist/client/error-boundary.js

@@ -1,4 +1,4 @@
 "use client";
 "use client";
-import { t as TimberErrorBoundary } from "../_chunks/error-boundary-D-lkwyaD.js";
+import { t as TimberErrorBoundary } from "../_chunks/error-boundary-BvRCCmbN.js";
 export { TimberErrorBoundary };

package/dist/client/global-context.d.ts

@@ -0,0 +1,15 @@
+/**
+ * createGlobalContext — a React context with a process-wide singleton identity.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate a module across
+ * chunks (browser-entry graph + client-reference graph). With ESM output,
+ * each chunk gets its own module scope — a bare createContext at module
+ * level would create separate instances per chunk. globalThis guarantees a
+ * single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+import React from 'react';
+export declare function createGlobalContext<T>(key: string, defaultValue: T): React.Context<T>;
+//# sourceMappingURL=global-context.d.ts.map

package/dist/client/global-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-context.d.ts","sourceRoot":"","sources":["../../src/client/global-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAarF"}

package/dist/client/index.js

@@ -1,13 +1,15 @@
 "use client";
 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 getSsrData } from "../_chunks/ssr-data-Ya2HJPFp.js";
-import { n as getRouterOrNull } from "../_chunks/router-ref-BzqbPwYC.js";
-import { n as useSegmentContext } from "../_chunks/segment-context-CjOlyB8Y.js";
+import { c as stripRscCacheKey } from "../_chunks/rsc-cache-key-ClUiXQnK.js";
+import { a as mergePreservedSearchParams, i as validateNavigationHref, n as isInternalHref, o as resolveSegmentParams } from "../_chunks/href-validation-BIrxavIy.js";
+import { n as getSsrData } from "../_chunks/ssr-data-BQGhTPAK.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-8gr8qsxN.js";
+import "../_chunks/param-value-C8TNYchQ.js";
+import { n as useSegmentContext } from "../_chunks/segment-context-D9_89u34.js";
 import { t as getLinkCodec } from "../_chunks/codec-registry-oOUxugz3.js";
-import { l as useNavigationContext, r as useSegmentParams, u as usePendingNavigation } from "../_chunks/use-segment-params-DzTBpkvj.js";
+import { a as useNavigationContext, o as usePendingNavigation } from "../_chunks/navigation-root-B00jjGd5.js";
 import { n as useQueryStates } from "../_chunks/use-query-states-I3JMng6J.js";
-import { createContext, startTransition, useActionState as useActionState$1, useContext, useRef, useState, useTransition } from "react";
+import React, { createContext, startTransition, useActionState as useActionState$1, useContext, useRef, useState, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -44,20 +46,35 @@ function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
 //#endregion
+//#region src/client/location-search.ts
+/**
+* The app-visible search string from the address bar.
+*
+* Mirrors what `appVisibleSearch()` does on the server: strips key-shaped
+* `_rsc` values so the client and server agree on search state regardless
+* of whether the document URL itself carries a payload cache key (a user
+* pasting/sharing an RSC payload URL). Non-key-shaped `_rsc` values — an
+* application legitimately owning that name — survive, using the same
+* `isRscCacheKeyShape` predicate the server uses.
+*/
+function locationSearch() {
+	return stripRscCacheKey(window.location.search);
+}
+//#endregion
 //#region src/client/link.tsx
 var LINK_PENDING = { isPending: true };
 var LINK_IDLE = { isPending: false };
 /**
 * Read the current URL's search string without requiring a React hook.
-* On the client, reads window.location.search. During SSR, reads from
-* the request context (getSsrData). Returns empty string if unavailable.
+* On the client, reads window.location.search. During SSR, reads the raw
+* query string from the request context (getSsrData) — the same `''` or
+* `?…` shape, preserving repeated keys (`?tag=a&tag=b`) so the
+* server-rendered href matches what the hydrated client rebuilds from the
+* address bar (TIM-1428). Returns empty string if unavailable.
 */
 function getCurrentSearch() {
-	if (typeof window !== "undefined") return window.location.search;
-	const data = getSsrData();
-	if (!data) return "";
-	const str = new URLSearchParams(data.searchParams).toString();
-	return str ? `?${str}` : "";
+	if (typeof window !== "undefined") return locationSearch();
+	return getSsrData()?.search ?? "";
 }
 /**
 * Interpolate dynamic segments in a route pattern with actual values.
@@ -253,10 +270,10 @@ var Link = function LinkImpl(props) {
 		if (!router) return;
 		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
 		const resolved = new URL(navHref, window.location.href);
-		if (resolved.pathname === window.location.pathname && resolved.search === window.location.search && resolved.hash) return;
+		if (resolved.pathname === window.location.pathname && stripRscCacheKey(resolved.search) === locationSearch() && resolved.hash) return;
 		event.preventDefault();
 		const shouldScroll = scroll !== false;
-		const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
+		const absoluteHref = resolved.pathname + stripRscCacheKey(resolved.search) + resolved.hash;
 		const seq = ++clickSeq.current;
 		const settle = () => {
 			if (clickSeq.current === seq) startTransition(() => setIsPending(false));
@@ -273,7 +290,7 @@ var Link = function LinkImpl(props) {
 		if (router) {
 			const prefetchHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
 			const resolved = new URL(prefetchHref, window.location.href);
-			router.prefetch(resolved.pathname + resolved.search);
+			router.prefetch(resolved.pathname + stripRscCacheKey(resolved.search));
 		}
 	} : userOnMouseEnter;
 	return /* @__PURE__ */ jsx("a", {
@@ -382,34 +399,31 @@ function useRouter() {
 * Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
 * Updates when client-side navigation changes the URL.
 *
-* On the client, reads from NavigationContext which is updated atomically
-* with the RSC tree render. This replaces the previous useSyncExternalStore
-* approach which only subscribed to popstate events — meaning usePathname()
-* did NOT re-render on forward navigation (pushState). The context approach
-* fixes this: pathname updates in the same render pass as the new tree.
+* One unconditional read of NavigationContext, on every side (TIM-1425):
 *
-* During SSR, reads the request pathname from the SSR ALS context
-* (populated by ssr-entry.ts) instead of window.location.
+* - In the browser, the provider wraps the RSC payload in renderRoot(), so
+*   the pathname updates in the same render pass as the new tree.
+* - During SSR, the wrapper chain mounts the same provider with the request's
+*   pathname (TIM-1424), so this is the identical code path — no ALS read,
+*   no fallback tiers.
+* - In the RSC environment, this module is never evaluated — the shims plugin
+*   resolves next/navigation to navigation-rsc.ts, which has a throwing stub
+*   (TIM-1420).
+* - Called outside a component entirely, React itself throws its
+*   invalid-hook-call error — loud, not guessed-at from window.location.
 *
 * Compatible with Next.js's `usePathname()` from `next/navigation`.
 */
 /**
 * Read the current URL pathname.
 *
-* On the client, reads from NavigationContext (provided by
-* NavigationProvider in renderRoot). During SSR, reads from the
-* ALS-backed SSR data context. Falls back to window.location.pathname
-* when called outside a React component (e.g., in tests).
+* Throws when no NavigationProvider is above the caller (a component rendered
+* outside the timber app — in tests, render inside the timber providers).
 */
 function usePathname() {
-	try {
-		const navContext = useNavigationContext();
-		if (navContext !== null) return navContext.pathname;
-	} catch {}
-	const ssrData = getSsrData();
-	if (ssrData) return ssrData.pathname ?? "/";
-	if (typeof window !== "undefined") return window.location.pathname;
-	return "/";
+	const nav = useNavigationContext();
+	if (nav === null) throw new Error("[timber] usePathname() was called outside the timber app tree (no NavigationProvider found). In tests, render the component inside the timber providers.");
+	return nav.pathname;
 }
 //#endregion
 //#region src/client/navigation-api.ts
@@ -641,6 +655,95 @@ function deriveFormErrors(result) {
 	};
 }
 //#endregion
+//#region src/client/params-context.ts
+/**
+* Segment params context — the one channel params use to reach the browser.
+*
+* Params ride the RSC payload's root row as a sibling of the tree
+* (`{ tree, params, slotParams }`), rather than in four side channels that
+* raced to seed them: a response header, an inline script, and two build-time
+* manifest fields all previously carried the same record, each with its own
+* `JSON.stringify` (TIM-1294).
+*
+* Riding the payload is what makes them *typed*. `defineSchema` takes any
+* `Codec<T>`, so a coerced param is whatever the codec returned — a `Date`, a
+* `bigint` — and `JSON.stringify` either flattened it to a string or threw
+* mid-response. React Flight carries those values natively, so the client
+* reads the value the server produced instead of a lossy copy of it. See
+* design/41-global-params.md §"Transport".
+*
+* **The client owns the provider.** There is exactly one `ParamsProvider` in
+* the browser's tree, rendered by `PayloadRoot` above the point where a
+* partial navigation splices the new payload into the retained tree. It has to
+* be there and it has to be alone: a provider *inside* the payload lands below
+* the retained region, whose own root is the departing route's provider, so
+* every reader in a skipped layout resolves to the departing record and no
+* amount of wrapping above it helps (TIM-1297).
+*
+* Ordering still holds without a bootstrap contract, for the same reason it
+* did when the provider was in the tree: a provider renders before its own
+* descendants by construction, so `useSegmentParams()` is correct during
+* hydration without anything having to run before `hydrateRoot()`.
+*/
+/**
+* SINGLETON GUARANTEE: globalThis + `Symbol.for`, the same pattern as
+* `NavigationContext` and `SegmentUpdateContext`.
+*
+* The RSC client bundler can duplicate a module across chunks, and with ESM
+* output each chunk gets its own module scope — so a bare `createContext` at
+* module level yields one context per chunk. This module is now reached from
+* *both* graphs: `PayloadRoot` is imported by the browser entry, while
+* `useParamsContext()` arrives through the client-reference graph with the
+* app's own components. A duplicate would put the provider on instance A and
+* every reader on instance B, so `useContext` returns `null` and every
+* `useSegmentParams()` call throws the outside-the-timber-app-tree error
+* even though the provider is mounted (the module-snapshot fallback it once
+* silently landed on was deleted in TIM-1425).
+*
+* This module was the one client context without the guard — harmless while
+* the provider travelled inside the payload, in the same graph as its readers,
+* and load-bearing the moment the client started rendering it (TIM-1297).
+*
+* The React APIs are reached through the namespace rather than named imports,
+* for the same reason `segment-update-context.ts` and `navigation-context.ts`
+* do it: React's `react-server` export provides neither `createContext` nor
+* `useContext`, and a *named* ESM import of a missing export fails at module
+* instantiation — before any feature check could run. This module is reachable
+* from every entry a Server Component imports, so the named form crashed
+* those entries outright (codex, PR #992; originally reproduced against
+* `@timber-js/app/segment-params`, an entry point since deleted by TIM-1342 —
+* the hazard is unchanged for the entries that remain).
+*
+* See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+*/
+var PARAMS_CTX_KEY = Symbol.for("__timber_params_ctx");
+function getOrCreateContext() {
+	const store = globalThis;
+	const existing = store[PARAMS_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext !== "function") return;
+	const ctx = React.createContext(null);
+	store[PARAMS_CTX_KEY] = ctx;
+	return ctx;
+}
+var ParamsContext = getOrCreateContext();
+/**
+* Read the params provided by the tree. Returns null only when no provider
+* is above the caller — a component rendered outside a timber route. During
+* SSR the wrapper chain mounts `PayloadRoot` too (TIM-1424), so both sides
+* resolve through this context.
+*/
+function useParamsContext() {
+	return React.useContext(ParamsContext);
+}
+//#endregion
+//#region src/client/use-segment-params.ts
+function useSegmentParams(segmentPath) {
+	const paramsContext = useParamsContext();
+	if (paramsContext === null) throw new Error("[timber] useSegmentParams() was called outside the timber app tree (no params provider found). In tests, render the component inside the timber providers.");
+	return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
+}
+//#endregion
 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