@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/client/ssr-data.d.ts

@@ -1,17 +1,20 @@
 /**
  * SSR Data — per-request state for client hooks during server-side rendering.
  *
- * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),
- * so the RSC environment's request-context ALS is not visible to SSR modules.
- * This module provides getter/setter functions that ssr-entry.ts uses to
- * populate per-request data for React's render.
- *
- * Request isolation: On the server, ssr-entry.ts registers an ALS-backed
- * provider via registerSsrDataProvider(). getSsrData() reads from the ALS
- * store, ensuring correct per-request data even when Suspense boundaries
- * resolve asynchronously across concurrent requests. The module-level
- * setSsrData/clearSsrData functions are kept as a fallback for tests
- * and environments without ALS.
+ * `useCookie()` and `<Link preserveSearchParams>` have no React context to
+ * read their request values from during SSR, so the SSR entry hands them
+ * the request's cookies and search string through this module.
+ * `useSearchParams()` reads NavigationContext and uses getSsrData() only to
+ * detect that it is rendering on the server. Route
+ * params do not travel here — client components read them from
+ * `ParamsContext`, decoded from the payload root.
+ *
+ * Request isolation: ssr-entry.ts registers an ALS-backed provider via
+ * registerSsrDataProvider(), so getSsrData() reads the current request's
+ * store even when Suspense boundaries resolve asynchronously across
+ * concurrent requests. There is no module-level fallback: outside an SSR
+ * render (in the browser, or before the provider is registered) there is no
+ * request, and getSsrData() returns undefined.
  *
  * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only
  * APIs, as it's imported by 'use client' hooks that are bundled for the browser.
@@ -22,54 +25,27 @@
  * See design/18-build-system.md §"Singleton State Registry"
  */
 export interface SsrData {
-    /** The request's URL pathname (e.g. '/dashboard/settings') */
-    pathname: string;
-    /** The request's search params as a plain record */
-    searchParams: Record<string, string>;
-    /** The request's cookies as name→value pairs */
-    cookies: Map<string, string>;
-    /** The request's route params (e.g. { id: '123' }) */
-    params: Record<string, string | string[]>;
     /**
-     * Mutable reference to NavContext for error boundary → RSC communication.
-     * When TimberErrorBoundary catches a DenySignal, it sets
-     * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry
-     * from promoting the denial to page-level. See LOCAL-298.
+     * The request's raw app-visible query string (`''` or `?…`), matching what
+     * `window.location.search` will hold after hydration. The raw string is
+     * the only representation carried here: it preserves repeated keys
+     * (`?tag=a&tag=b`), which a collapsed `Record<string, string>` cannot
+     * (TIM-1428). Parse with `new URLSearchParams(search)` where needed.
      */
-    _navContext?: {
-        _denyHandledByBoundary?: boolean;
-    };
+    search: string;
+    /** The request's cookies as name→value pairs */
+    cookies: Map<string, string>;
 }
 /**
- * Register an ALS-backed SSR data provider. Called once at module load
- * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.
- *
- * When registered, getSsrData() reads from the provider (ALS store)
- * instead of module-level state, ensuring correct isolation for
- * concurrent requests with streaming Suspense.
+ * Register the SSR data provider. Called once at module load by
+ * ssr-entry.ts to wire up per-request data via AsyncLocalStorage; tests
+ * register their own provider (and `undefined` to reset).
  */
-export declare function registerSsrDataProvider(provider: () => SsrData | undefined): void;
-/**
- * Set the SSR data for the current request via module-level state.
- *
- * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.
- * This function is retained for tests and as a fallback.
- */
-export declare function setSsrData(data: SsrData): void;
-/**
- * Clear the SSR data after rendering completes.
- *
- * In production, ALS scope handles cleanup automatically.
- * This function is retained for tests and as a fallback.
- */
-export declare function clearSsrData(): void;
+export declare function registerSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void;
 /**
  * Read the current request's SSR data. Returns undefined when called
  * outside an SSR render (i.e. on the client after hydration).
  *
- * Prefers the ALS-backed provider when registered (server-side),
- * falling back to module-level state (tests, legacy).
- *
  * Used by client hooks' server snapshot functions.
  */
 export declare function getSsrData(): SsrData | undefined;

package/dist/client/ssr-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-data.d.ts","sourceRoot":"","sources":["../../src/client/ssr-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,MAAM,WAAW,OAAO;IACtB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,gDAAgD;IAChD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,WAAW,CAAC,EAAE;QAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACpD;AAkBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,OAAO,GAAG,SAAS,GAAG,IAAI,CAEjF;AAMD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,OAAO,GAAG,SAAS,CAKhD"}
+{"version":3,"file":"ssr-data.d.ts","sourceRoot":"","sources":["../../src/client/ssr-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,MAAM,WAAW,OAAO;IACtB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAkBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,GAAG,IAAI,CAE/F;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,OAAO,GAAG,SAAS,CAEhD"}

package/dist/client/stale-client.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Stale Client — knowing when this bundle has been superseded.
+ *
+ * Layer 1 of version skew handling (see design/33-version-skew.md) is
+ * proactive: the server compares `X-Timber-Deployment-Id` against the current
+ * build and answers a stale client with `X-Timber-Reload: 1`. That covers
+ * every RSC navigation and every server action — as long as there is a server
+ * in the request path.
+ *
+ * This module is the reactive half, plus the state both halves feed. It
+ * recognizes the two error shapes a stale client produces on its own:
+ *
+ * 1. **Stale client references** — React's Flight client throws
+ *    "Could not find the module …" when an RSC payload names a client module
+ *    ID that isn't in this bundle's manifest.
+ * 2. **Chunk load failures** — a content-hashed chunk that no longer exists on
+ *    the CDN fails to `import()`. Every engine words this differently.
+ *
+ * It matters most for `output: 'static'`, where there is no server to send the
+ * reload header and this is the *only* skew detection that can run.
+ *
+ * **Nothing here reloads the page.** A stale client is recorded, not acted on;
+ * the router turns the next user-initiated navigation into a full document
+ * load. See design/33-version-skew.md §"Recovery on the next navigation" for
+ * why — a self-issued `location.reload()` cannot tell a recovery from a bounce
+ * between two live deployments, and mid-rollout it produces exactly that loop.
+ *
+ * See TIM-1260, TIM-1275.
+ */
+/**
+ * True when the error is React's "client reference not in this manifest"
+ * failure — the payload was produced by a build this bundle doesn't match.
+ */
+export declare function isStaleClientReference(error: unknown): boolean;
+/**
+ * True when the error is a failed dynamic import or CSS preload — the
+ * content-hashed chunk this bundle asks for is gone from the CDN.
+ */
+export declare function isChunkLoadError(error: unknown): boolean;
+/** Whether this client has been superseded by a newer deployment. */
+export declare function isClientStale(): boolean;
+/**
+ * Record that the origin has told us this client is stale — the `X-Timber-Reload`
+ * header on an RSC or action response. Authoritative, so it is not gated on
+ * anything: a dev server never sends the header in the first place.
+ */
+export declare function markClientStale(): void;
+/**
+ * Record staleness if `error` is one of the shapes a superseded bundle
+ * produces. Returns whether it did, so a caller mid-navigation can decide to
+ * hard-navigate instead of surfacing the error.
+ *
+ * Inference, unlike {@link markClientStale}, so it is gated on being a
+ * production build. This is the single place that gate lives — call sites
+ * cannot see each other, and "remember to gate the next one too" is not a
+ * guarantee.
+ */
+export declare function markStaleFromError(error: unknown): boolean;
+/**
+ * Arm the module, and register the listeners that catch stale-client errors
+ * never passing through the router: a lazily imported client component, a
+ * preloaded stylesheet, anything that rejects outside a navigation.
+ *
+ * No-op when `deploymentId` is null — that is dev. Called from the browser
+ * entry before hydration, so it precedes any render or navigation that could
+ * throw.
+ */
+export declare function initStaleClient(deploymentId: string | null): void;
+//# sourceMappingURL=stale-client.d.ts.map

package/dist/client/stale-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-client.d.ts","sourceRoot":"","sources":["../../src/client/stale-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA4CH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIxD;AAuBD,qEAAqE;AACrE,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgB1D;AAeD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAejE"}

package/dist/client/state.d.ts

@@ -3,7 +3,7 @@
  *
  * ALL mutable module-level state that must have singleton semantics across
  * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
- * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file
  * and re-export thin wrapper functions.
  *
  * Why: In Vite dev, a module is instantiated separately if reached via different
@@ -18,25 +18,17 @@
  * See design/18-build-system.md §"Module Singleton Strategy" and
  * §"Singleton State Registry".
  */
-import type { RouterInstance } from './router.js';
-import type { SsrData } from './ssr-data.js';
+import type { RouterInstance } from './router-types.ts';
+import type { SsrData } from './ssr-data.ts';
 /** The global router singleton — set once during bootstrap. */
 export declare let globalRouter: RouterInstance | null;
 export declare function _setGlobalRouter(router: RouterInstance | null): void;
 /**
- * ALS-backed SSR data provider. When registered, getSsrData() reads from
- * this function (ALS store) instead of module-level currentSsrData.
+ * ALS-backed SSR data provider, registered by the SSR entry. getSsrData()
+ * reads through it; unset in the browser.
  */
 export declare let ssrDataProvider: (() => SsrData | undefined) | undefined;
 export declare function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void;
-/** Fallback SSR data for tests and environments without ALS. */
-export declare let currentSsrData: SsrData | undefined;
-export declare function _setCurrentSsrData(data: SsrData | undefined): void;
-/** Current route params snapshot — replaced (not mutated) on each navigation. */
-export declare let currentParams: Record<string, string | string[]>;
-export declare function _setCurrentParams(params: Record<string, string | string[]>): void;
-/** Listeners notified when currentParams changes. */
-export declare const paramsListeners: Set<() => void>;
 /** Cached search string — avoids reparsing when URL hasn't changed. */
 export declare let cachedSearch: string;
 export declare let cachedSearchParams: URLSearchParams;
@@ -44,4 +36,20 @@ export declare function _setCachedSearch(search: string, params: URLSearchParams
 /** Whether the page is currently being unloaded. */
 export declare let unloading: boolean;
 export declare function _setUnloading(value: boolean): void;
+/**
+ * Whether a status page for the main route has rendered since the last
+ * navigation was prepared. Raised by `StatusPageMarker`, consumed by the
+ * navigation's commit. See navigation-commit.ts §"What a status page
+ * teaches the cache".
+ */
+export declare let statusPageRendered: boolean;
+export declare function _setStatusPageRendered(value: boolean): void;
+/**
+ * What a status page report does beyond raising the flag: registered by the
+ * router's committer so the report can clear the segment cache at once, for
+ * the commits no navigation consumes (a row arriving inside Suspense after
+ * its navigation published, a status document being hydrated).
+ */
+export declare let onStatusPageRendered: (() => void) | undefined;
+export declare function _setOnStatusPageRendered(handler: (() => void) | undefined): void;
 //# sourceMappingURL=state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/client/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,+DAA+D;AAC/D,eAAO,IAAI,YAAY,EAAE,cAAc,GAAG,IAAW,CAAC;AAEtD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAEpE;AAID;;;GAGG;AACH,eAAO,IAAI,eAAe,EAAE,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;AAEpE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,GAAG,IAAI,CAE3F;AAED,gEAAgE;AAChE,eAAO,IAAI,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;AAE/C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAElE;AAID,iFAAiF;AACjF,eAAO,IAAI,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAM,CAAC;AAEjE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEjF;AAED,qDAAqD;AACrD,eAAO,MAAM,eAAe,YAAiB,IAAI,CAAG,CAAC;AAIrD,uEAAuE;AACvE,eAAO,IAAI,YAAY,QAAK,CAAC;AAC7B,eAAO,IAAI,kBAAkB,iBAAwB,CAAC;AAEtD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAG9E;AAID,oDAAoD;AACpD,eAAO,IAAI,SAAS,SAAQ,CAAC;AAE7B,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/client/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,+DAA+D;AAC/D,eAAO,IAAI,YAAY,EAAE,cAAc,GAAG,IAAW,CAAC;AAEtD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAEpE;AAID;;;GAGG;AACH,eAAO,IAAI,eAAe,EAAE,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;AAEpE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,GAAG,IAAI,CAE3F;AAID,uEAAuE;AACvE,eAAO,IAAI,YAAY,QAAK,CAAC;AAC7B,eAAO,IAAI,kBAAkB,iBAAwB,CAAC;AAEtD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAG9E;AAID,oDAAoD;AACpD,eAAO,IAAI,SAAS,SAAQ,CAAC;AAE7B,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD;AAID;;;;;GAKG;AACH,eAAO,IAAI,kBAAkB,SAAQ,CAAC;AAEtC,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE3D;AAED;;;;;GAKG;AACH,eAAO,IAAI,oBAAoB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;AAE1D,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAEhF"}

package/dist/client/status-page-marker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one way a status page tells the router it is on screen.
+ *
+ * A status page replaces a subtree, and the segment cache must not learn a
+ * chain that never mounted (see `navigation-commit.ts` §"What a status page
+ * teaches the cache"). Status pages are produced in three places — an
+ * in-tree catch site rendering the page it owns, the server's fallback
+ * renderers, and a client boundary rendering its fallback for a Flight row —
+ * and every one of them wraps the page in this marker, so the report does
+ * not depend on which producer it was. In particular the in-tree case, the
+ * common `access.ts` deny, never involves a client boundary at all.
+ *
+ * A layout effect, on every commit that renders the marker rather than on
+ * mount only: React reuses the fiber when one status page is replaced by
+ * another at the same position, and the second one must report too. Layout
+ * effects run child-before-parent, so the report lands before the ancestor
+ * `NavigationRoot` publishes the same commit, and never for a render React
+ * discards. Idempotent, so StrictMode's double invocation and a status page
+ * re-rendering on its own state are harmless. See TIM-1495.
+ */
+import { type ReactNode } from 'react';
+export declare function StatusPageMarker({ children }: {
+    children: ReactNode;
+}): ReactNode;
+//# sourceMappingURL=status-page-marker.d.ts.map

package/dist/client/status-page-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-page-marker.d.ts","sourceRoot":"","sources":["../../src/client/status-page-marker.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGxD,wBAAgB,gBAAgB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAKjF"}

package/dist/client/top-loader.d.ts

@@ -3,11 +3,11 @@
  *
  * Shows an animated progress bar at the top of the viewport while an RSC
  * navigation is in flight. Injected automatically by the framework into
- * TransitionRoot — users never render this component directly.
+ * 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 `useNavigationPending()` directly.
+ * (`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
@@ -21,7 +21,7 @@
  * 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 §"useNavigationPending()"
+ * See design/19-client-navigation.md §"usePendingNavigation()"
  * See LOCAL-336 for design decisions.
  */
 export interface TopLoaderConfig {
@@ -31,7 +31,7 @@ export interface TopLoaderConfig {
     color?: string;
     /** Bar height in pixels. Default: 3. */
     height?: number;
-    /** Show subtle glow/shadow effect. Default: true. */
+    /** Show subtle glow/shadow effect. Default: false. */
     shadow?: boolean;
     /** Delay in ms before showing the bar. Default: 0. */
     delay?: number;
@@ -39,9 +39,10 @@ export interface TopLoaderConfig {
     zIndex?: number;
 }
 /**
- * Internal top-loader component. Injected by TransitionRoot.
+ * Internal top-loader component. Injected by NavigationRoot.
  *
- * Reads pending navigation state from PendingNavigationContext.
+ * Reads pending navigation state from the router's external store, via
+ * usePendingNavigation() — the one pending representation (TIM-1307).
  * Phase transitions are derived synchronously during render:
  *
  *   hidden → crawling:   when isPending becomes true

package/dist/client/top-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA2F7F"}
+{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA6F7F"}

package/dist/client/unload-guard.d.ts

@@ -8,6 +8,11 @@
  * unloaded so error boundaries and error handlers can suppress abort-related
  * errors during the unload window.
  *
+ * This is the single owner of "is this document going away". Anything that
+ * needs the answer imports `isPageUnloading()` — an unload flag maintained a
+ * second time somewhere else is a flag that will drift out of agreement with
+ * this one (TIM-1260).
+ *
  * Mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
  *

package/dist/client/unload-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unload-guard.d.ts","sourceRoot":"","sources":["../../src/client/unload-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}
+{"version":3,"file":"unload-guard.d.ts","sourceRoot":"","sources":["../../src/client/unload-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA2CH;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}

package/dist/client/use-cookie.d.ts

@@ -22,6 +22,18 @@ export interface ClientCookieOptions {
     secure?: boolean;
 }
 export type CookieSetter = (value: string, options?: ClientCookieOptions) => void;
+/** Parse a cookie name from document.cookie. */
+export declare function getCookieValue(name: string): string | undefined;
+/** Serialize options into a cookie string suffix. */
+export declare function serializeOptions(options?: ClientCookieOptions): string;
+/**
+ * Notify useCookie subscribers that a cookie value changed.
+ * Called by defineCookie's imperative client .set()/.delete() methods
+ * so mounted useCookie() consumers re-render.
+ *
+ * @internal — framework use only
+ */
+export declare function notifyCookieChange(name: string): void;
 /**
  * Reactive hook for reading/writing a client-side cookie.
  *

package/dist/client/use-cookie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;AA0ClF;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,GACnC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CAmChF"}
+{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;AASlF,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/D;AAED,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAkBtE;AAUD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAErD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,GACnC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CA8DhF"}

package/dist/client/use-link-status.d.ts

@@ -1,5 +1,5 @@
 export interface LinkStatus {
-    pending: boolean;
+    isPending: boolean;
 }
 /**
  * React context provided by <Link>. Holds the pending status
@@ -7,10 +7,10 @@ export interface LinkStatus {
  */
 export declare const LinkStatusContext: import("react").Context<LinkStatus>;
 /**
- * Returns `{ pending: true }` while the nearest parent `<Link>` component's
+ * Returns `{ isPending: true }` while the nearest parent `<Link>` component's
  * navigation is in flight. Must be used inside a `<Link>` component's children.
  *
- * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * Unlike `usePendingNavigation()` which is global, this hook is scoped to
  * the nearest parent `<Link>` — only the link the user clicked shows pending.
  *
  * ```tsx
@@ -18,8 +18,8 @@ export declare const LinkStatusContext: import("react").Context<LinkStatus>;
  * import { Link, useLinkStatus } from '@timber-js/app/client'
  *
  * function Hint() {
- *   const { pending } = useLinkStatus()
- *   return <span className={pending ? 'opacity-50' : ''} />
+ *   const { isPending } = useLinkStatus()
+ *   return <span className={isPending ? 'opacity-50' : ''} />
  * }
  *
  * export function NavLink({ href, children }) {

package/dist/client/use-link-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../src/client/use-link-status.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qCAAgD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}
+{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../src/client/use-link-status.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qCAAkD,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}

package/dist/client/use-pathname.d.ts

@@ -4,24 +4,26 @@
  * 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 the router's `renderTree`, 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).
  */
 export declare function usePathname(): string;
 //# sourceMappingURL=use-pathname.d.ts.map

package/dist/client/use-pathname.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAoBpC"}
+{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAUpC"}

package/dist/client/use-pending-navigation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+export declare function usePendingNavigation(): boolean;
+//# sourceMappingURL=use-pending-navigation.d.ts.map

package/dist/client/use-pending-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-pending-navigation.d.ts","sourceRoot":"","sources":["../../src/client/use-pending-navigation.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}

package/dist/client/use-query-states.d.ts

@@ -7,7 +7,7 @@
  *
  * Design doc: design/23-search-params.md §"Codec Bridge"
  */
-import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOptions } from '#/search-params/create.js';
+import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOptions } from '../search-params/define.ts';
 /**
  * Read and write typed search params from/to the URL.
  *
@@ -16,7 +16,7 @@ import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOp
  *
  * Usage:
  * ```ts
- * // Via a SearchParamsDefinition
+ * // Via a SearchParamsDefinition imported from the route's params.ts
  * const [params, setParams] = definition.useQueryStates()
  *
  * // Standalone with inline codecs
@@ -24,10 +24,16 @@ import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOp
  *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
  * })
  * ```
+ *
+ * There is deliberately no route-string form (`useQueryStates('/products')`).
+ * Importing the definition from `params.ts` is the documented way to reach
+ * another route's codecs — it needs no runtime registry lookup and so has no
+ * "not registered yet" failure mode. See design/23-search-params.md
+ * §"Client Access".
  */
-export declare function useQueryStates<T extends Record<string, unknown>>(codecsOrRoute: {
+export declare function useQueryStates<T extends Record<string, unknown>>(codecs: {
     [K in keyof T]: SearchParamCodec<T[K]>;
-} | string, _options?: QueryStatesOptions, urlKeys?: Readonly<Record<string, string>>): [T, SetParams<T>];
+}, _options?: QueryStatesOptions, urlKeys?: Readonly<Record<string, string>>): [T, SetParams<T>];
 /**
  * Create a useQueryStates binding for a SearchParamsDefinition.
  * This is used internally by SearchParamsDefinition.useQueryStates().

package/dist/client/use-query-states.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-query-states.d.ts","sourceRoot":"","sources":["../../src/client/use-query-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAoCnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,aAAa,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,MAAM,EAClE,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAyDnB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACpC,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAIrD"}
+{"version":3,"file":"use-query-states.d.ts","sourceRoot":"","sources":["../../src/client/use-query-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAkKpC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,MAAM,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,EAClD,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CA+FnB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACpC,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAIrD"}

package/dist/client/use-router.d.ts

@@ -14,23 +14,30 @@
  * 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".
  *
  * For loading UI during navigation, use:
  * - useLinkStatus()          — per-link pending indicator (inside <Link>)
- * - useNavigationPending()   — global navigation pending state
+ * - usePendingNavigation()   — global navigation pending state
  */
+/** Options for `push` and `replace`. */
+export interface NavigateOptions {
+    /** Set to false to keep the scroll position instead of scrolling to top. */
+    scroll?: boolean;
+    /**
+     * View transition types to add to this navigation, beside the router's own
+     * `navigation-forward`. See `NavigationOptions.transitionTypes` — they must
+     * go here rather than in a `startTransition` around the call.
+     */
+    transitionTypes?: readonly string[];
+}
 export interface AppRouterInstance {
     /** Navigate to a URL, pushing a new history entry */
-    push(href: string, options?: {
-        scroll?: boolean;
-    }): void;
+    push(href: string, options?: NavigateOptions): void;
     /** Navigate to a URL, replacing the current history entry */
-    replace(href: string, options?: {
-        scroll?: boolean;
-    }): void;
+    replace(href: string, options?: NavigateOptions): void;
     /** Refresh the current page (re-fetch RSC payload) */
     refresh(): void;
     /** Navigate back in history */

package/dist/client/use-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../../src/client/use-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,IAAI,iBAAiB,CA8C7C"}
+{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../../src/client/use-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACpD,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACvD,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,IAAI,iBAAiB,CAuD7C"}

package/dist/client/use-search-params.d.ts

@@ -4,23 +4,30 @@
  * Returns a read-only URLSearchParams instance reflecting the current
  * URL's query string. Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.search, provided for
- * Next.js API compatibility (libraries like nuqs import useSearchParams
- * from next/navigation).
+ * One unconditional read of NavigationContext, on every side (TIM-1425):
+ *
+ * - In the browser, the provider is updated atomically with the RSC tree
+ *   during full navigations, AND by syncShallowSearch() for shallow URL
+ *   updates (nuqs shallow: true, replaceUrl, or any external
+ *   pushState/replaceState that changes the query string). See router-init.ts.
+ * - During SSR, the wrapper chain mounts the same provider carrying the
+ *   request's RAW query string (TIM-1424), so repeated keys
+ *   (`?tag=a&tag=b`) survive — the collapsed record the ALS context holds
+ *   cannot represent them.
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
  * local copy but do NOT affect the URL — use the router or nuqs for that.
  *
- * During SSR, reads the request search params from the SSR ALS context
- * (populated by ssr-entry.ts) instead of window.location.
- *
- * All mutable state is delegated to client/state.ts for singleton guarantees.
- * See design/18-build-system.md §"Singleton State Registry"
+ * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 /**
  * Read the current URL search params.
  *
+ * Throws when no NavigationProvider is above the caller.
+ *
  * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 export declare function useSearchParams(): URLSearchParams;

package/dist/client/use-search-params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-search-params.d.ts","sourceRoot":"","sources":["../../src/client/use-search-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA+CH;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAMjD"}
+{"version":3,"file":"use-search-params.d.ts","sourceRoot":"","sources":["../../src/client/use-search-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAeH;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAoBjD"}