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

package/dist/client/segment-cache.d.ts

@@ -1,10 +1,23 @@
+import type { PublishedParams } from '../shared/payload-root.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
 /** A prefetched RSC result with optional segment metadata. */
 export interface PrefetchResult {
     payload: unknown;
+    /**
+     * Completion of the full Flight stream, when the prefetch is still decoding.
+     * Carried through to the navigation that consumes the entry so a decode
+     * failure reaches *that* navigation's recovery rather than dying with the
+     * prefetch (TIM-1275).
+     */
+    decodePromise?: Promise<void> | null;
     /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
     segmentInfo?: SegmentInfo[] | null;
-    /** Route params from X-Timber-Params header for populating useSegmentParams(). */
-    params?: Record<string, string | string[]> | null;
+    /**
+     * The params published beside `payload`, split off the same payload root.
+     * Carried so a consumed prefetch publishes the params of the tree it is
+     * about to render, and not the ones already on screen.
+     */
+    params?: PublishedParams | Promise<PublishedParams>;
     /** Segment paths skipped by the server (for client-side merging). */
     skippedSegments?: string[] | null;
 }
@@ -15,6 +28,11 @@ export interface PrefetchResult {
 export interface SegmentNode {
     /** The segment's URL pattern (e.g., "/", "/dashboard", "/projects/[id]") */
     segment: string;
+    /**
+     * The segment's `app/` directory path, groups included (e.g. `/(browse)/feed`).
+     * Undefined for slot nodes and for servers that predate the field.
+     */
+    treePath?: string;
     /** The RSC flight payload for this segment (opaque to the cache) */
     payload: unknown;
     /**
@@ -32,14 +50,6 @@ export interface SegmentNode {
     /** Whether this slot's access.ts denied on its last render. */
     denied?: boolean;
 }
-/**
- * Serialized state tree sent via X-Timber-State-Tree header.
- * Only sync segments are included — async segments always re-render.
- */
-export interface StateTree {
-    segments: string[];
-    slots?: string[];
-}
 /**
  * Maintains the client-side segment tree representing currently mounted
  * layouts and pages. Used for navigation reconciliation — the router diffs
@@ -60,29 +70,18 @@ export declare class SegmentCache {
      * client can actually merge (i.e., segments whose cached element tree
      * contains an inner SegmentProvider the merger can splice into).
      *
+     * `treePaths` is collected UNFILTERED, unlike `segments` and `slots`. Those
+     * two answer "what may the server skip re-rendering?", so every reason a
+     * segment cannot be reused is a reason to leave it out. `treePaths` answers
+     * "what is mounted right now?" for interception scoping — a request-dependent
+     * layout is still on screen, and dropping it would silently narrow the scope
+     * the server sees and cancel a modal that should open (TIM-1282).
+     *
      * This is a performance optimization only, NOT a security boundary.
      * The server always runs all access.ts files regardless of the state tree.
      */
     serializeStateTree(mergeableFilter?: Set<string>): StateTree;
 }
-/**
- * Segment metadata from the server, sent via X-Timber-Segments header.
- * Describes a rendered segment's path and whether it's async.
- */
-export interface SegmentInfo {
-    path: string;
-    /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
-    segmentId?: string;
-    isRequestDependent: boolean;
-    /** True for parallel route slot entries. Slots are keyed by their slot path (e.g., "/@sidebar"). */
-    slot?: boolean;
-    /** Parent segment path for slot entries. Used to attach the slot to the correct SegmentNode. */
-    parentSegment?: string;
-    /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
-    denied?: boolean;
-    /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
-    skipped?: boolean;
-}
 /**
  * Build a SegmentNode tree from flat segment metadata.
  *
@@ -95,6 +94,45 @@ export interface SegmentInfo {
  * from the tree — pages are never cached across navigations.
  */
 export declare function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefined;
+/**
+ * Identifies a prefetched payload. A payload is addressed by *every* input that
+ * changes the server's answer, not by the destination alone.
+ *
+ * The server's answer for a destination depends on where the request came
+ * from — that is the whole mechanism behind intercepting routes, and it also
+ * drives slot-skip resolution. A prefetch issued from `/gallery` is a modal
+ * payload; the same URL prefetched from `/` is the full page. Keying on the
+ * destination alone let the first click after a hover be answered with
+ * whichever variant happened to be fetched (TIM-1265).
+ *
+ * `from` alone stopped being enough in TIM-1282. It is a pathname, and once
+ * interception scope comes from the rendered tree rather than the address, one
+ * pathname no longer names one source tree: `/photo/1` is the address both for
+ * a modal open over `(browse)` and for `(landing)`'s canonical page. A key
+ * without the scope hands the modal payload to the canonical page's click,
+ * which renders it without the server's scope check ever running.
+ *
+ * The two reads happen at different instants — `scope` is sampled at hover and
+ * again at click — which is why a tree that changed in between produces a
+ * *miss* and a refetch rather than a wrong hit.
+ */
+export interface PrefetchKey {
+    /** Destination URL — hash-less `pathname + search`, as navigate() fetches it. */
+    url: string;
+    /** Departing pathname — the `X-Timber-URL` the prefetch was issued with. */
+    from: string;
+    /**
+     * The rendered scope the prefetch was issued with — the `treePaths` half of
+     * `X-Timber-State-Tree`, joined. Empty when none crossed.
+     */
+    scope: string;
+}
+/**
+ * The `scope` half of a `PrefetchKey`, derived from the state tree that will
+ * actually be sent. Taking it from the header value rather than re-walking the
+ * cache is the point: the key varies by exactly what the request varies by.
+ */
+export declare function prefetchScopeOf(stateTree: StateTree | undefined): string;
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
  * 30 seconds. When a link is clicked, the prefetched payload is consumed
@@ -106,13 +144,20 @@ export declare function buildSegmentTree(segments: SegmentInfo[]): SegmentNode |
 export declare class PrefetchCache {
     private static readonly TTL_MS;
     private entries;
-    set(url: string, result: PrefetchResult): void;
-    get(url: string): PrefetchResult | undefined;
+    set(key: PrefetchKey, result: PrefetchResult): void;
+    get(key: PrefetchKey): PrefetchResult | undefined;
     /** Get and remove the entry (used when navigation consumes a prefetch) */
-    consume(url: string): PrefetchResult | undefined;
-    /** Store a negative entry — the URL is not a route (non-RSC Content-Type). */
-    setNegative(url: string): void;
+    consume(key: PrefetchKey): PrefetchResult | undefined;
+    /**
+     * Store a negative entry — the URL is not a route (non-RSC Content-Type).
+     *
+     * Keyed like every other entry even though "not a route" does not actually
+     * vary by departing URL: a source-independent negative would be a second
+     * keying rule to keep correct, and the only cost of the uniform one is a
+     * repeated fetch for a link hovered from a second page.
+     */
+    setNegative(key: PrefetchKey): void;
     /** Check if the entry is a negative cache entry (URL is not a route). */
-    isNegative(url: string): boolean;
+    isNegative(key: PrefetchKey): boolean;
 }
 //# sourceMappingURL=segment-cache.d.ts.map

package/dist/client/segment-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segment-cache.d.ts","sourceRoot":"","sources":["../../src/client/segment-cache.ts"],"names":[],"mappings":"AAKA,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAClD,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnC,kEAAkE;IAClE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACjC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA0B;IAEtC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAK5C;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAI5C;IAED,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAY3D;CACF;AAkCD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,oGAAoG;IACpG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2GAA2G;IAC3G,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8GAA8G;IAC9G,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CAiEjF;AAYD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAU;IACxC,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAK7C;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQ3C;IAED,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAM/C;IAED,8EAA8E;IAC9E,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE7B;IAED,yEAAyE;IACzE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG/B;CACF"}
+{"version":3,"file":"segment-cache.d.ts","sourceRoot":"","sources":["../../src/client/segment-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAIxE,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACrC,uFAAuF;IACvF,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACpD,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnC,kEAAkE;IAClE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACjC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAID;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA0B;IAEtC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAK5C;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAI5C;IAED,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAAkB,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAiB3D;CACF;AAgDD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CAkEjF;AAYD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAWD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAExE;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAU;IACxC,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAKlD;IAED,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,GAAG,SAAS,CAShD;IAED,0EAA0E;IAC1E,OAAO,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,GAAG,SAAS,CAMpD;IAED;;;;;;;OAOG;IACH,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAElC;IAED,yEAAyE;IACzE,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAEpC;CACF"}

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

@@ -21,6 +21,7 @@
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
  */
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 export interface SsrData {
     /** The request's URL pathname (e.g. '/dashboard/settings') */
     pathname: string;
@@ -30,6 +31,11 @@ export interface SsrData {
     cookies: Map<string, string>;
     /** The request's route params (e.g. { id: '123' }) */
     params: Record<string, string | string[]>;
+    /**
+     * Per-slot params keyed by slot tree path, absent when the request rendered
+     * no slot with params of its own (TIM-1285).
+     */
+    slotParams?: SlotParamsRecord;
     /**
      * Mutable reference to NavContext for error boundary → pipeline communication.
      *

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;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACzE;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,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;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACzE;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"}

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

@@ -18,7 +18,8 @@
  * See design/18-build-system.md §"Module Singleton Strategy" and
  * §"Singleton State Registry".
  */
-import type { RouterInstance } from './router.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
+import type { RouterInstance } from './router-types.js';
 import type { SsrData } from './ssr-data.js';
 /** The global router singleton — set once during bootstrap. */
 export declare let globalRouter: RouterInstance | null;
@@ -35,6 +36,14 @@ 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;
+/**
+ * Per-slot params snapshot, keyed by slot tree path — the module-level
+ * fallback behind `useSegmentParams(slotPath)` when no NavigationContext is
+ * mounted (tests, calls outside a component). Replaced, never mutated, on
+ * each navigation. See TIM-1285.
+ */
+export declare let currentSlotParams: SlotParamsRecord | null;
+export declare function _setCurrentSlotParams(slotParams: SlotParamsRecord | null): void;
 /** Listeners notified when currentParams changes. */
 export declare const paramsListeners: Set<() => void>;
 /** Cached search string — avoids reparsing when URL hasn't changed. */

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,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,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;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;;;;;GAKG;AACH,eAAO,IAAI,iBAAiB,EAAE,gBAAgB,GAAG,IAAW,CAAC;AAE7D,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAE/E;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"}

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

@@ -41,7 +41,8 @@ export interface TopLoaderConfig {
 /**
  * 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,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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA6F7F"}
+{"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.map

@@ -1 +1 @@
-{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,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"}
+{"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-router.d.ts

@@ -14,7 +14,7 @@
  * 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".
  *

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

@@ -18,11 +18,11 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
- * Reactivity: On the client, useParams() reads from NavigationContext
- * which is updated atomically with the RSC tree render. This replaces
- * the previous useSyncExternalStore approach that suffered from a
- * timing gap between tree render and store notification — causing
- * preserved layout components to briefly show stale active state.
+ * Reactivity: On the client, useParams() reads from ParamsContext, published
+ * by the one provider the client renders above the merge point
+ * (`PayloadRoot`). Params update atomically with the tree because they travel
+ * on the same payload root — there is no separate channel that could be
+ * seeded a render early or late (TIM-1294, TIM-1297).
  *
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
@@ -30,6 +30,7 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 import type { Routes } from '../index.js';
+import { type SlotParamsRecord } from '../shared/slot-params.js';
 /**
  * Subscribe to params changes.
  * Retained for backward compatibility with tests that verify the
@@ -58,6 +59,15 @@ export declare function getSnapshot(): Record<string, string | string[]>;
  * (ALS-backed).
  */
 export declare function setCurrentParams(params: Record<string, string | string[]>): void;
+/**
+ * Set the per-slot params snapshot in the module-level store.
+ *
+ * Paired with `setCurrentParams`: the router calls both on every navigation,
+ * including with `null` when a response carries no slot params, so a slot's
+ * params from the *previous* route cannot be read on the next one. Fill and
+ * serve are paired; so are fill and clear. See TIM-1285.
+ */
+export declare function setCurrentSlotParams(slotParams: SlotParamsRecord | null): void;
 /**
  * Notify all legacy subscribers that params have changed.
  *
@@ -73,9 +83,9 @@ export declare function notifyParamsListeners(): void;
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
- * On the client, reads from NavigationContext (provided by
- * NavigationProvider in renderRoot). This ensures params update
- * atomically with the RSC tree — no timing gap.
+ * On the client, reads from ParamsContext, published by `PayloadRoot` above
+ * everything the navigation renders. Params update atomically with the RSC
+ * tree — no timing gap.
  *
  * During SSR, reads from the ALS-backed SSR data context to ensure
  * per-request isolation across concurrent requests with streaming Suspense.

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

@@ -1 +1 @@
-{"version":3,"file":"use-segment-params.d.ts","sourceRoot":"","sources":["../../src/client/use-segment-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAS1C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,MAAM,EACrD,WAAW,EAAE,CAAC,GACb,MAAM,CAAC,CAAC,CAAC,SAAS;IAAE,aAAa,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AACxF,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}
+{"version":3,"file":"use-segment-params.d.ts","sourceRoot":"","sources":["../../src/client/use-segment-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAS1C,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAOvF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,MAAM,EACrD,WAAW,EAAE,CAAC,GACb,MAAM,CAAC,CAAC,CAAC,SAAS;IAAE,aAAa,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AACxF,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}

package/dist/cookies/index.js

@@ -1,7 +1,7 @@
 import { n as assertValidCookieName, t as require_dist } from "../_chunks/dist-BA3u1z3W.js";
+import { n as getSsrData } from "../_chunks/ssr-data-14MXm7Pj.js";
 import { a as resolveCodecOrSchema } from "../_chunks/schema-bridge-DT_Tn0Xf.js";
-import { n as getSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
-import { useSyncExternalStore } from "react";
+import * as React$1 from "react";
 import { getCookieJar } from "@timber-js/app/server";
 //#region src/client/use-cookie.ts
 /**
@@ -83,7 +83,7 @@ function useCookie(name, defaultOptions) {
 		if (ssrData) return ssrData.cookies.get(name);
 		return getCookieValue(name);
 	};
-	const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+	const value = React$1.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 	assertValidCookieName(name);
 	const setCookie = (newValue, options) => {
 		if (typeof newValue !== "string") throw new Error(`[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n  '@timber-js/app/cookies' and call its useCookie() hook instead.`);

package/dist/cookies/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/client/use-cookie.ts","../../src/cookies/define-cookie.ts","../../src/cookies/json-cookie.ts"],"sourcesContent":["/**\n * useCookie — reactive client-side cookie hook.\n *\n * Uses useSyncExternalStore for SSR-safe, reactive cookie access.\n * All components reading the same cookie name re-render on change.\n * No cross-tab sync (intentional — see design/29-cookies.md).\n *\n * See design/29-cookies.md §\"useCookie(name) Hook\"\n */\n\nimport { useSyncExternalStore } from 'react';\nimport { parseCookie, stringifySetCookie } from 'cookie';\nimport { getSsrData } from './ssr-data.js';\nimport { assertValidCookieName } from '../cookies/validation.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nexport interface ClientCookieOptions {\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Domain scope. Default: omitted (current domain). */\n  domain?: string;\n  /** Max age in seconds. */\n  maxAge?: number;\n  /** Expiration date. */\n  expires?: Date;\n  /** Cross-site policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Only send over HTTPS. Default: true in production. */\n  secure?: boolean;\n}\n\nexport type CookieSetter = (value: string, options?: ClientCookieOptions) => void;\n\n// ─── Module-Level Cookie Store ────────────────────────────────────────────\n\ntype Listener = () => void;\n\n/** Per-name subscriber sets. */\nconst listeners = new Map<string, Set<Listener>>();\n\n/** Parse a cookie name from document.cookie. */\nexport function getCookieValue(name: string): string | undefined {\n  if (typeof document === 'undefined') return undefined;\n  const cookies = parseCookie(document.cookie);\n  return cookies[name];\n}\n\n/** Serialize options into a cookie string suffix. */\nexport function serializeOptions(options?: ClientCookieOptions): string {\n  if (!options) return '; Path=/; SameSite=Lax';\n  const sameSite = options.sameSite ?? 'lax';\n  // Build a Set-Cookie string via the cookie package, then strip the\n  // `__placeholder__=` name=value prefix to get just the attributes.\n  const full = stringifySetCookie({\n    name: '__placeholder__',\n    value: '',\n    path: options.path ?? '/',\n    domain: options.domain,\n    maxAge: options.maxAge,\n    expires: options.expires,\n    sameSite,\n    secure: options.secure,\n  });\n  // Strip everything up to and including the first \"; \"\n  const idx = full.indexOf('; ');\n  return idx >= 0 ? full.slice(idx) : '';\n}\n\n/** Notify all subscribers for a given cookie name. */\nfunction notify(name: string): void {\n  const subs = listeners.get(name);\n  if (subs) {\n    for (const fn of subs) fn();\n  }\n}\n\n/**\n * Notify useCookie subscribers that a cookie value changed.\n * Called by defineCookie's imperative client .set()/.delete() methods\n * so mounted useCookie() consumers re-render.\n *\n * @internal — framework use only\n */\nexport function notifyCookieChange(name: string): void {\n  notify(name);\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────────────\n\n/**\n * Reactive hook for reading/writing a client-side cookie.\n *\n * Returns `[value, setCookie, deleteCookie]`:\n * - `value`: current cookie value (string | undefined)\n * - `setCookie`: sets the cookie and triggers re-renders\n * - `deleteCookie`: deletes the cookie and triggers re-renders\n *\n * @param name - Cookie name.\n * @param defaultOptions - Default options for setCookie calls.\n */\nexport function useCookie(\n  name: string,\n  defaultOptions?: ClientCookieOptions\n): [value: string | undefined, setCookie: CookieSetter, deleteCookie: () => void] {\n  const subscribe = (callback: Listener): (() => void) => {\n    let subs = listeners.get(name);\n    if (!subs) {\n      subs = new Set();\n      listeners.set(name, subs);\n    }\n    subs.add(callback);\n    return () => {\n      subs!.delete(callback);\n      if (subs!.size === 0) listeners.delete(name);\n    };\n  };\n\n  const getSnapshot = (): string | undefined => getCookieValue(name);\n  const getServerSnapshot = (): string | undefined => {\n    // During SSR, read the ALS-backed request cookies.\n    const ssrData = getSsrData();\n    if (ssrData) return ssrData.cookies.get(name);\n    // During client hydration there is no SSR data (it lives in the server's\n    // module graph), but React still calls getServerSnapshot. document.cookie\n    // holds the same cookies the server rendered with, so reading it here\n    // keeps the hydration render consistent with the server HTML.\n    // See design/29-cookies.md §\"SSR Hydration\".\n    return getCookieValue(name);\n  };\n\n  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n\n  // Validate the name once per hook instance — names are typically\n  // stable string literals, so this catches the bug at first render\n  // rather than on every write. Throws via `assertValidCookieName` with\n  // a precise error if the name violates RFC 7230 token rules.\n  assertValidCookieName(name);\n\n  const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {\n    if (typeof newValue !== 'string') {\n      throw new Error(\n        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\\n` +\n          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\\n` +\n          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`\n      );\n    }\n    const merged = { ...defaultOptions, ...options };\n    // Auto-encode mirrors the server's `cookies().set()` contract:\n    // values are URL-encoded on write, URL-decoded on read, so the\n    // logical bytes round-trip losslessly. See design/29-cookies.md\n    // §\"Encoding Contract\".\n    document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;\n    notify(name);\n  };\n\n  const deleteCookie = (): void => {\n    const path = defaultOptions?.path ?? '/';\n    const domain = defaultOptions?.domain;\n    let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n    if (domain) cookieStr += `; Domain=${domain}`;\n    document.cookie = cookieStr;\n    notify(name);\n  };\n\n  return [value, setCookie, deleteCookie];\n}\n","/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with sync .get(), .set(), .delete() isomorphic methods (server + client)\n * and a .useCookie() client hook.\n *\n * Environment detection is call-time: on the server, getCookieJar() is\n * used directly (ALS-backed). On the client, document.cookie helpers\n * and the useCookie hook are used. No registration pattern — imports\n * resolve via the shims plugin (client bundle gets a stub for\n * @timber-js/app/server).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected in\n * the codec option — no explicit fromSchema() wrapper needed.\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '../server/cookie-context.js';\nimport type { ClientCookieOptions } from '../client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '../codec.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\nimport { resolveCodecOrSchema } from '../schema-bridge.js';\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Type alias for the shared Codec<T> protocol.\n */\nexport type CookieCodec<T> = Codec<T>;\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T, HttpOnly extends boolean = boolean> extends CookieOptions {\n  /**\n   * Codec for parsing/serializing the cookie value.\n   * Accepts a Codec<T> or a Standard Schema object (Zod, Valibot, ArkType)\n   * which is auto-wrapped via fromSchema.\n   */\n  codec: CookieCodec<T> | StandardSchemaV1<T>;\n  /**\n   * Prevent client-side JS access. Default: true.\n   * When true (or omitted), client methods (useCookie, get/set/delete on\n   * client) are omitted from the return type and throw at runtime.\n   */\n  httpOnly?: HttpOnly;\n}\n\n/**\n * Server-only cookie definition. Returned when httpOnly is true or omitted.\n * Client methods are absent from the type — accessing them is a TS error.\n */\nexport interface ServerOnlyCookieDefinition<T> {\n  readonly name: string;\n  readonly options: CookieOptions;\n  readonly codec: CookieCodec<T>;\n\n  /** Read the typed value. Sync, isomorphic (server + client). */\n  get(): T;\n  /** Set the typed value. Sync, isomorphic (server + client). */\n  set(value: T): void;\n  /** Delete the cookie. Sync, isomorphic (server + client). */\n  delete(): void;\n}\n\n/**\n * Full cookie definition with client methods. Returned when httpOnly: false.\n */\nexport interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Direct Imports (no registration) ─────────────────────────────────────\n//\n// Server: getCookieJar is imported from @timber-js/app/server. In the client\n// bundle, the shims plugin replaces @timber-js/app/server with a stub module\n// where getCookieJar throws on call. We detect the environment at call time\n// by trying getCookieJar() — if it throws the stub error, we fall through\n// to the client path.\n//\n// Client: useCookie, getCookieValue, notifyCookieChange\n// are imported from use-cookie.ts. These are safe in all environments (no\n// node:async_hooks dependency).\n//\n// Schema: fromSchema is a pure function — safe in all environments.\n\nimport { getCookieJar } from '@timber-js/app/server';\nimport {\n  useCookie as useRawCookie,\n  notifyCookieChange,\n  getCookieValue,\n} from '../client/use-cookie.js';\n\n// ─── Environment Detection ────────────────────────────────────────────────\n\n/**\n * Try to get the server cookie jar. Returns null if we're in the client\n * environment (stub throws) or if there's no request context.\n *\n * On the server, getCookieJar() throws \"outside of a request context\" if\n * called without an ALS store — this is a real error and is re-thrown.\n * The client stub throws a different message — that's caught and returns null.\n */\nfunction tryGetServerCookieJar(): ReturnType<typeof getCookieJar> | null {\n  try {\n    return getCookieJar();\n  } catch (e) {\n    // Server-side \"no request context\" error — re-throw as a real bug.\n    if (e instanceof Error && e.message.includes('outside of a request context')) {\n      throw e;\n    }\n    // Client stub error or other — fall through to client path.\n    return null;\n  }\n}\n\n// ─── Client Cookie Helpers ────────────────────────────────────────────────\n\n/** Write a cookie via document.cookie and notify useCookie subscribers. */\nfunction setClientCookie(name: string, value: string, options?: ClientCookieOptions): void {\n  const parts: string[] = [`${name}=${encodeURIComponent(value)}`];\n  const path = options?.path ?? '/';\n  parts.push(`Path=${path}`);\n  if (options?.domain) parts.push(`Domain=${options.domain}`);\n  if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);\n  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);\n  const sameSite = options?.sameSite ?? 'lax';\n  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);\n  if (options?.secure) parts.push('Secure');\n  document.cookie = parts.join('; ');\n  notifyCookieChange(name);\n}\n\n/** Delete a cookie via document.cookie and notify useCookie subscribers. */\nfunction deleteClientCookie(name: string, options?: ClientCookieOptions): void {\n  const path = options?.path ?? '/';\n  const domain = options?.domain;\n  let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n  if (domain) cookieStr += `; Domain=${domain}`;\n  document.cookie = cookieStr;\n  notifyCookieChange(name);\n}\n\n// ─── Standard Schema Auto-Detection ───────────────────────────────────────\n\nfunction resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {\n  return resolveCodecOrSchema('codec', codecOrSchema, 'search') as CookieCodec<T>;\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { z } from 'zod/v4';\n *\n * // httpOnly: false — client methods available\n * export const themeCookie = defineCookie('theme', {\n *   codec: z.enum(['light', 'dark', 'system']).default('system'),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server or client\n * const theme = themeCookie.get();\n * themeCookie.set('dark');\n *\n * // Client hook\n * const [theme, setTheme] = themeCookie.useCookie();\n *\n * // httpOnly: true (default) — server-only, no client methods\n * export const sessionCookie = defineCookie('session', {\n *   codec: z.string(),\n * });\n * sessionCookie.get();       // works on server\n * sessionCookie.useCookie(); // TS error — httpOnly cookie\n * ```\n */\nexport function defineCookie<T, HttpOnly extends boolean = true>(\n  name: string,\n  options: DefineCookieOptions<T, HttpOnly>\n): HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T> {\n  const { codec: codecOrSchema, ...cookieOpts } = options;\n  const codec = resolveCodec(codecOrSchema);\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n  const isHttpOnly = options.httpOnly !== false; // default true\n\n  function getClientOpts(): ClientCookieOptions {\n    return {\n      path: resolvedOptions.path,\n      domain: resolvedOptions.domain,\n      maxAge: resolvedOptions.maxAge,\n      expires: resolvedOptions.expires,\n      sameSite: resolvedOptions.sameSite,\n      secure: resolvedOptions.secure,\n    };\n  }\n\n  const base: ServerOnlyCookieDefinition<T> = {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    get(): T {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        return codec.parse(serverJar.get(name));\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').get() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      const raw = getCookieValue(name);\n      return codec.parse(raw);\n    },\n\n    set(value: T): void {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          serverJar.delete(name, {\n            path: resolvedOptions.path,\n            domain: resolvedOptions.domain,\n          });\n        } else {\n          serverJar.set(name, serialized, resolvedOptions);\n        }\n        return;\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').set() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        deleteClientCookie(name, getClientOpts());\n      } else {\n        setClientCookie(name, serialized, getClientOpts());\n      }\n    },\n\n    delete(): void {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        serverJar.delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n        return;\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').delete() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      deleteClientCookie(name, getClientOpts());\n    },\n  };\n\n  if (isHttpOnly) {\n    return base as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n  }\n\n  // httpOnly: false — add useCookie client hook\n  const full: CookieDefinition<T> = {\n    ...base,\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const clientOpts = getClientOpts();\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n\n  return full as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n}\n","/**\n * jsonCookieCodec — Codec helper for storing JSON-serializable values in\n * cookies.\n *\n * The codec is intentionally minimal: `JSON.stringify` on serialize,\n * `JSON.parse` on parse. The framework handles the URL encoding /\n * decoding around it (see design/29-cookies.md §\"Encoding Contract\"):\n *\n *     defineCookie.setCookie(value)\n *       → codec.serialize: JSON.stringify       → '{\"a\":1}'\n *       → cookies().set: encodeURIComponent     → '%7B%22a%22%3A1%7D'\n *       → wire: Set-Cookie: prefs=%7B%22a%22%3A1%7D\n *\n *     defineCookie.getCookie()\n *       → wire: Cookie: prefs=%7B%22a%22%3A1%7D\n *       → parseCookieHeader: decodeURIComponent → '{\"a\":1}'\n *       → codec.parse: JSON.parse               → { a: 1 }\n *\n * The same chain works on the client: `useCookie` auto-encodes on writes\n * and auto-decodes on reads, so `jsonCookieCodec` composes with both the\n * server `defineCookie` methods and the client `useCookie` hook with no\n * environment-specific branches.\n *\n * Parsing is total: any non-JSON value (or `undefined`) returns the\n * supplied default. This matches the \"never crash on user-controlled\n * cookie input\" semantics that `fromSchema` uses for typed search params.\n *\n * ```ts\n * import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';\n *\n * interface Prefs { lang: string; fontSize: number }\n *\n * export const prefsCookie = defineCookie('prefs', {\n *   codec: jsonCookieCodec<Prefs>({ lang: 'en', fontSize: 16 }),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * await prefsCookie.setCookie({ lang: 'fr', fontSize: 18 });\n * ```\n */\n\nimport type { Codec } from '../codec.js';\n\n/**\n * Build a CookieCodec that JSON-encodes the value. The framework's\n * cookie write path then URL-encodes the JSON string into a valid\n * `cookie-octet` form, and the read path reverses both transforms.\n *\n * @param defaultValue - Returned by `parse` when the cookie is missing\n *   or the stored value cannot be JSON-parsed. Optional — if omitted,\n *   `parse` returns `undefined` on missing/malformed input.\n *\n *   The default is **deep-cloned** on every fallback return via\n *   `structuredClone`, so mutating the parsed result in one request\n *   cannot leak into later requests that fall back to the same\n *   default. This matters for long-lived server processes where a\n *   codec is defined once at module load and shared across all\n *   requests — without the clone, a user doing\n *   `const prefs = prefsCookie.get(); prefs.lang = 'fr'` on a missing\n *   cookie would mutate the module-level default and poison every\n *   later fallback. See the \"shared mutable default\" regression test\n *   in `tests/define-cookie.test.ts`.\n */\nexport function jsonCookieCodec<T>(defaultValue?: T): Codec<T> {\n  // Resolve the fallback at call time, not capture time, so every\n  // fallback return produces a fresh deep copy. structuredClone handles\n  // nested objects, arrays, dates, maps, sets — everything\n  // JSON-serializable plus more. For primitives and undefined,\n  // structuredClone is effectively a no-op.\n  const cloneDefault = (): T => {\n    if (defaultValue === undefined || defaultValue === null) {\n      return defaultValue as T;\n    }\n    // structuredClone is a Node built-in since Node 17, available in\n    // all supported runtimes.\n    return structuredClone(defaultValue);\n  };\n\n  return {\n    parse(value: string | string[] | undefined): T {\n      if (value === undefined || value === '') {\n        return cloneDefault();\n      }\n      // Cookies are single-valued by name; defensively pick the last\n      // entry if a Codec consumer somehow passes an array.\n      const raw = Array.isArray(value) ? value[value.length - 1] : value;\n      if (raw === undefined || raw === '') {\n        return cloneDefault();\n      }\n      try {\n        return JSON.parse(raw) as T;\n      } catch {\n        return cloneDefault();\n      }\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return JSON.stringify(value);\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/client/use-cookie.ts","../../src/cookies/define-cookie.ts","../../src/cookies/json-cookie.ts"],"sourcesContent":["/**\n * useCookie — reactive client-side cookie hook.\n *\n * Uses useSyncExternalStore for SSR-safe, reactive cookie access.\n * All components reading the same cookie name re-render on change.\n * No cross-tab sync (intentional — see design/29-cookies.md).\n *\n * See design/29-cookies.md §\"useCookie(name) Hook\"\n */\n\n// Namespace access, not `import { useSyncExternalStore }`. This module is\n// reachable from `@timber-js/app/cookies` — `defineCookie()` exposes both a\n// server `.get()` and a client `.useCookie()`, so the entry is isomorphic and\n// loads in the RSC environment. React's `react-server` export withholds\n// `useSyncExternalStore` exactly as it withholds `createContext`, and a *named*\n// ESM import of a missing export fails at module instantiation, before any\n// code runs. Same rule as `client/params-context.ts` (TIM-1297, TIM-1298).\nimport * as React from 'react';\nimport { parseCookie, stringifySetCookie } from 'cookie';\nimport { getSsrData } from './ssr-data.js';\nimport { assertValidCookieName } from '../cookies/validation.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nexport interface ClientCookieOptions {\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Domain scope. Default: omitted (current domain). */\n  domain?: string;\n  /** Max age in seconds. */\n  maxAge?: number;\n  /** Expiration date. */\n  expires?: Date;\n  /** Cross-site policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Only send over HTTPS. Default: true in production. */\n  secure?: boolean;\n}\n\nexport type CookieSetter = (value: string, options?: ClientCookieOptions) => void;\n\n// ─── Module-Level Cookie Store ────────────────────────────────────────────\n\ntype Listener = () => void;\n\n/** Per-name subscriber sets. */\nconst listeners = new Map<string, Set<Listener>>();\n\n/** Parse a cookie name from document.cookie. */\nexport function getCookieValue(name: string): string | undefined {\n  if (typeof document === 'undefined') return undefined;\n  const cookies = parseCookie(document.cookie);\n  return cookies[name];\n}\n\n/** Serialize options into a cookie string suffix. */\nexport function serializeOptions(options?: ClientCookieOptions): string {\n  if (!options) return '; Path=/; SameSite=Lax';\n  const sameSite = options.sameSite ?? 'lax';\n  // Build a Set-Cookie string via the cookie package, then strip the\n  // `__placeholder__=` name=value prefix to get just the attributes.\n  const full = stringifySetCookie({\n    name: '__placeholder__',\n    value: '',\n    path: options.path ?? '/',\n    domain: options.domain,\n    maxAge: options.maxAge,\n    expires: options.expires,\n    sameSite,\n    secure: options.secure,\n  });\n  // Strip everything up to and including the first \"; \"\n  const idx = full.indexOf('; ');\n  return idx >= 0 ? full.slice(idx) : '';\n}\n\n/** Notify all subscribers for a given cookie name. */\nfunction notify(name: string): void {\n  const subs = listeners.get(name);\n  if (subs) {\n    for (const fn of subs) fn();\n  }\n}\n\n/**\n * Notify useCookie subscribers that a cookie value changed.\n * Called by defineCookie's imperative client .set()/.delete() methods\n * so mounted useCookie() consumers re-render.\n *\n * @internal — framework use only\n */\nexport function notifyCookieChange(name: string): void {\n  notify(name);\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────────────\n\n/**\n * Reactive hook for reading/writing a client-side cookie.\n *\n * Returns `[value, setCookie, deleteCookie]`:\n * - `value`: current cookie value (string | undefined)\n * - `setCookie`: sets the cookie and triggers re-renders\n * - `deleteCookie`: deletes the cookie and triggers re-renders\n *\n * @param name - Cookie name.\n * @param defaultOptions - Default options for setCookie calls.\n */\nexport function useCookie(\n  name: string,\n  defaultOptions?: ClientCookieOptions\n): [value: string | undefined, setCookie: CookieSetter, deleteCookie: () => void] {\n  const subscribe = (callback: Listener): (() => void) => {\n    let subs = listeners.get(name);\n    if (!subs) {\n      subs = new Set();\n      listeners.set(name, subs);\n    }\n    subs.add(callback);\n    return () => {\n      subs!.delete(callback);\n      if (subs!.size === 0) listeners.delete(name);\n    };\n  };\n\n  const getSnapshot = (): string | undefined => getCookieValue(name);\n  const getServerSnapshot = (): string | undefined => {\n    // During SSR, read the ALS-backed request cookies.\n    const ssrData = getSsrData();\n    if (ssrData) return ssrData.cookies.get(name);\n    // During client hydration there is no SSR data (it lives in the server's\n    // module graph), but React still calls getServerSnapshot. document.cookie\n    // holds the same cookies the server rendered with, so reading it here\n    // keeps the hydration render consistent with the server HTML.\n    // See design/29-cookies.md §\"SSR Hydration\".\n    return getCookieValue(name);\n  };\n\n  const value = React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n\n  // Validate the name once per hook instance — names are typically\n  // stable string literals, so this catches the bug at first render\n  // rather than on every write. Throws via `assertValidCookieName` with\n  // a precise error if the name violates RFC 7230 token rules.\n  assertValidCookieName(name);\n\n  const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {\n    if (typeof newValue !== 'string') {\n      throw new Error(\n        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\\n` +\n          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\\n` +\n          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`\n      );\n    }\n    const merged = { ...defaultOptions, ...options };\n    // Auto-encode mirrors the server's `cookies().set()` contract:\n    // values are URL-encoded on write, URL-decoded on read, so the\n    // logical bytes round-trip losslessly. See design/29-cookies.md\n    // §\"Encoding Contract\".\n    document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;\n    notify(name);\n  };\n\n  const deleteCookie = (): void => {\n    const path = defaultOptions?.path ?? '/';\n    const domain = defaultOptions?.domain;\n    let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n    if (domain) cookieStr += `; Domain=${domain}`;\n    document.cookie = cookieStr;\n    notify(name);\n  };\n\n  return [value, setCookie, deleteCookie];\n}\n","/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with sync .get(), .set(), .delete() isomorphic methods (server + client)\n * and a .useCookie() client hook.\n *\n * Environment detection is call-time: on the server, getCookieJar() is\n * used directly (ALS-backed). On the client, document.cookie helpers\n * and the useCookie hook are used. No registration pattern — imports\n * resolve via the shims plugin (client bundle gets a stub for\n * @timber-js/app/server).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected in\n * the codec option — no explicit fromSchema() wrapper needed.\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '../server/cookie-context.js';\nimport type { ClientCookieOptions } from '../client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '../codec.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\nimport { resolveCodecOrSchema } from '../schema-bridge.js';\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Type alias for the shared Codec<T> protocol.\n */\nexport type CookieCodec<T> = Codec<T>;\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T, HttpOnly extends boolean = boolean> extends CookieOptions {\n  /**\n   * Codec for parsing/serializing the cookie value.\n   * Accepts a Codec<T> or a Standard Schema object (Zod, Valibot, ArkType)\n   * which is auto-wrapped via fromSchema.\n   */\n  codec: CookieCodec<T> | StandardSchemaV1<T>;\n  /**\n   * Prevent client-side JS access. Default: true.\n   * When true (or omitted), client methods (useCookie, get/set/delete on\n   * client) are omitted from the return type and throw at runtime.\n   */\n  httpOnly?: HttpOnly;\n}\n\n/**\n * Server-only cookie definition. Returned when httpOnly is true or omitted.\n * Client methods are absent from the type — accessing them is a TS error.\n */\nexport interface ServerOnlyCookieDefinition<T> {\n  readonly name: string;\n  readonly options: CookieOptions;\n  readonly codec: CookieCodec<T>;\n\n  /** Read the typed value. Sync, isomorphic (server + client). */\n  get(): T;\n  /** Set the typed value. Sync, isomorphic (server + client). */\n  set(value: T): void;\n  /** Delete the cookie. Sync, isomorphic (server + client). */\n  delete(): void;\n}\n\n/**\n * Full cookie definition with client methods. Returned when httpOnly: false.\n */\nexport interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Direct Imports (no registration) ─────────────────────────────────────\n//\n// Server: getCookieJar is imported from @timber-js/app/server. In the client\n// bundle, the shims plugin replaces @timber-js/app/server with a stub module\n// where getCookieJar throws on call. We detect the environment at call time\n// by trying getCookieJar() — if it throws the stub error, we fall through\n// to the client path.\n//\n// Client: useCookie, getCookieValue, notifyCookieChange\n// are imported from use-cookie.ts. These are safe in all environments (no\n// node:async_hooks dependency).\n//\n// Schema: fromSchema is a pure function — safe in all environments.\n\nimport { getCookieJar } from '@timber-js/app/server';\nimport {\n  useCookie as useRawCookie,\n  notifyCookieChange,\n  getCookieValue,\n} from '../client/use-cookie.js';\n\n// ─── Environment Detection ────────────────────────────────────────────────\n\n/**\n * Try to get the server cookie jar. Returns null if we're in the client\n * environment (stub throws) or if there's no request context.\n *\n * On the server, getCookieJar() throws \"outside of a request context\" if\n * called without an ALS store — this is a real error and is re-thrown.\n * The client stub throws a different message — that's caught and returns null.\n */\nfunction tryGetServerCookieJar(): ReturnType<typeof getCookieJar> | null {\n  try {\n    return getCookieJar();\n  } catch (e) {\n    // Server-side \"no request context\" error — re-throw as a real bug.\n    if (e instanceof Error && e.message.includes('outside of a request context')) {\n      throw e;\n    }\n    // Client stub error or other — fall through to client path.\n    return null;\n  }\n}\n\n// ─── Client Cookie Helpers ────────────────────────────────────────────────\n\n/** Write a cookie via document.cookie and notify useCookie subscribers. */\nfunction setClientCookie(name: string, value: string, options?: ClientCookieOptions): void {\n  const parts: string[] = [`${name}=${encodeURIComponent(value)}`];\n  const path = options?.path ?? '/';\n  parts.push(`Path=${path}`);\n  if (options?.domain) parts.push(`Domain=${options.domain}`);\n  if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);\n  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);\n  const sameSite = options?.sameSite ?? 'lax';\n  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);\n  if (options?.secure) parts.push('Secure');\n  document.cookie = parts.join('; ');\n  notifyCookieChange(name);\n}\n\n/** Delete a cookie via document.cookie and notify useCookie subscribers. */\nfunction deleteClientCookie(name: string, options?: ClientCookieOptions): void {\n  const path = options?.path ?? '/';\n  const domain = options?.domain;\n  let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n  if (domain) cookieStr += `; Domain=${domain}`;\n  document.cookie = cookieStr;\n  notifyCookieChange(name);\n}\n\n// ─── Standard Schema Auto-Detection ───────────────────────────────────────\n\nfunction resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {\n  return resolveCodecOrSchema('codec', codecOrSchema, 'search') as CookieCodec<T>;\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { z } from 'zod/v4';\n *\n * // httpOnly: false — client methods available\n * export const themeCookie = defineCookie('theme', {\n *   codec: z.enum(['light', 'dark', 'system']).default('system'),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server or client\n * const theme = themeCookie.get();\n * themeCookie.set('dark');\n *\n * // Client hook\n * const [theme, setTheme] = themeCookie.useCookie();\n *\n * // httpOnly: true (default) — server-only, no client methods\n * export const sessionCookie = defineCookie('session', {\n *   codec: z.string(),\n * });\n * sessionCookie.get();       // works on server\n * sessionCookie.useCookie(); // TS error — httpOnly cookie\n * ```\n */\nexport function defineCookie<T, HttpOnly extends boolean = true>(\n  name: string,\n  options: DefineCookieOptions<T, HttpOnly>\n): HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T> {\n  const { codec: codecOrSchema, ...cookieOpts } = options;\n  const codec = resolveCodec(codecOrSchema);\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n  const isHttpOnly = options.httpOnly !== false; // default true\n\n  function getClientOpts(): ClientCookieOptions {\n    return {\n      path: resolvedOptions.path,\n      domain: resolvedOptions.domain,\n      maxAge: resolvedOptions.maxAge,\n      expires: resolvedOptions.expires,\n      sameSite: resolvedOptions.sameSite,\n      secure: resolvedOptions.secure,\n    };\n  }\n\n  const base: ServerOnlyCookieDefinition<T> = {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    get(): T {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        return codec.parse(serverJar.get(name));\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').get() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      const raw = getCookieValue(name);\n      return codec.parse(raw);\n    },\n\n    set(value: T): void {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          serverJar.delete(name, {\n            path: resolvedOptions.path,\n            domain: resolvedOptions.domain,\n          });\n        } else {\n          serverJar.set(name, serialized, resolvedOptions);\n        }\n        return;\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').set() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        deleteClientCookie(name, getClientOpts());\n      } else {\n        setClientCookie(name, serialized, getClientOpts());\n      }\n    },\n\n    delete(): void {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        serverJar.delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n        return;\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').delete() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      deleteClientCookie(name, getClientOpts());\n    },\n  };\n\n  if (isHttpOnly) {\n    return base as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n  }\n\n  // httpOnly: false — add useCookie client hook\n  const full: CookieDefinition<T> = {\n    ...base,\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const clientOpts = getClientOpts();\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n\n  return full as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n}\n","/**\n * jsonCookieCodec — Codec helper for storing JSON-serializable values in\n * cookies.\n *\n * The codec is intentionally minimal: `JSON.stringify` on serialize,\n * `JSON.parse` on parse. The framework handles the URL encoding /\n * decoding around it (see design/29-cookies.md §\"Encoding Contract\"):\n *\n *     defineCookie.setCookie(value)\n *       → codec.serialize: JSON.stringify       → '{\"a\":1}'\n *       → cookies().set: encodeURIComponent     → '%7B%22a%22%3A1%7D'\n *       → wire: Set-Cookie: prefs=%7B%22a%22%3A1%7D\n *\n *     defineCookie.getCookie()\n *       → wire: Cookie: prefs=%7B%22a%22%3A1%7D\n *       → parseCookieHeader: decodeURIComponent → '{\"a\":1}'\n *       → codec.parse: JSON.parse               → { a: 1 }\n *\n * The same chain works on the client: `useCookie` auto-encodes on writes\n * and auto-decodes on reads, so `jsonCookieCodec` composes with both the\n * server `defineCookie` methods and the client `useCookie` hook with no\n * environment-specific branches.\n *\n * Parsing is total: any non-JSON value (or `undefined`) returns the\n * supplied default. This matches the \"never crash on user-controlled\n * cookie input\" semantics that `fromSchema` uses for typed search params.\n *\n * ```ts\n * import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';\n *\n * interface Prefs { lang: string; fontSize: number }\n *\n * export const prefsCookie = defineCookie('prefs', {\n *   codec: jsonCookieCodec<Prefs>({ lang: 'en', fontSize: 16 }),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * await prefsCookie.setCookie({ lang: 'fr', fontSize: 18 });\n * ```\n */\n\nimport type { Codec } from '../codec.js';\n\n/**\n * Build a CookieCodec that JSON-encodes the value. The framework's\n * cookie write path then URL-encodes the JSON string into a valid\n * `cookie-octet` form, and the read path reverses both transforms.\n *\n * @param defaultValue - Returned by `parse` when the cookie is missing\n *   or the stored value cannot be JSON-parsed. Optional — if omitted,\n *   `parse` returns `undefined` on missing/malformed input.\n *\n *   The default is **deep-cloned** on every fallback return via\n *   `structuredClone`, so mutating the parsed result in one request\n *   cannot leak into later requests that fall back to the same\n *   default. This matters for long-lived server processes where a\n *   codec is defined once at module load and shared across all\n *   requests — without the clone, a user doing\n *   `const prefs = prefsCookie.get(); prefs.lang = 'fr'` on a missing\n *   cookie would mutate the module-level default and poison every\n *   later fallback. See the \"shared mutable default\" regression test\n *   in `tests/define-cookie.test.ts`.\n */\nexport function jsonCookieCodec<T>(defaultValue?: T): Codec<T> {\n  // Resolve the fallback at call time, not capture time, so every\n  // fallback return produces a fresh deep copy. structuredClone handles\n  // nested objects, arrays, dates, maps, sets — everything\n  // JSON-serializable plus more. For primitives and undefined,\n  // structuredClone is effectively a no-op.\n  const cloneDefault = (): T => {\n    if (defaultValue === undefined || defaultValue === null) {\n      return defaultValue as T;\n    }\n    // structuredClone is a Node built-in since Node 17, available in\n    // all supported runtimes.\n    return structuredClone(defaultValue);\n  };\n\n  return {\n    parse(value: string | string[] | undefined): T {\n      if (value === undefined || value === '') {\n        return cloneDefault();\n      }\n      // Cookies are single-valued by name; defensively pick the last\n      // entry if a Codec consumer somehow passes an array.\n      const raw = Array.isArray(value) ? value[value.length - 1] : value;\n      if (raw === undefined || raw === '') {\n        return cloneDefault();\n      }\n      try {\n        return JSON.parse(raw) as T;\n      } catch {\n        return cloneDefault();\n      }\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return JSON.stringify(value);\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AA+BjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAa1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQ1D,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElG;;;;;;;;;GASG;AAEH,MAAM,WAAW,MAAM;CAAG;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE;AAgGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,YAAY,EAAE,CA6WhE;eAEc,MAAM"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AA+BjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAa1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQ1D,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElG;;;;;;;;;GASG;AAEH,MAAM,WAAW,MAAM;CAAG;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE;AAgGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAiXhE;eAEc,MAAM"}