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

package/src/server/slot-resolver.ts

@@ -33,7 +33,7 @@ import { extractUrlParts, consumedPartsThroughSegment } from './chain-url-parts.
 import { findInterceptingMatch } from './slot-interception.js';
 import { SegmentOutlet } from '../client/segment-outlet.js';
 import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
-import { computeSlotKey } from '../routing/segment-keys.js';
+import { computeSlotKey, computeSlotContentKey } from '../routing/segment-keys.js';
 import { isStaticRequestDependent } from './request-dep.js';
 
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
@@ -86,8 +86,7 @@ export async function resolveSlotElement(
   match: RouteMatch,
   h: CreateElementFn,
   interception?: InterceptionContext,
-  parentTreePath?: string,
-  accessVerdicts?: SlotAccessVerdict[]
+  parentTreePath?: string
 ): Promise<React.ReactElement | null> {
   // When interception is active, try to match intercepting children in this
   // slot against the target pathname. If an intercepting child matches, render
@@ -176,13 +175,7 @@ export async function resolveSlotElement(
       // intermediate slot segments (everything between slot root and leaf).
       // Process innermost-first, same order as route-element-builder.ts
       // handles main segments. The slot root (index 0) is handled below.
-      element = await wrapWithIntermediateSegments(
-        slotMatch.chain,
-        element,
-        h,
-        accessVerdicts,
-        scope
-      );
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h, scope);
 
       // Wrap with slot root's layout — INSIDE the access gate, so the layout
       // server component never executes when access.ts denies. See TIM-1074.
@@ -195,7 +188,7 @@ export async function resolveSlotElement(
       // On denial: denied.tsx → default.tsx → null (graceful degradation),
       // rendered WITHOUT the denied slot's own layout.
       // See design/04-authorization.md §"Slot-Level Auth".
-      element = await wrapWithAccessGate(slotNode, element, h, accessVerdicts, scope);
+      element = await wrapWithAccessGate(slotNode, element, h, scope);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
@@ -277,7 +270,6 @@ async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
   h: CreateElementFn,
-  accessVerdicts?: SlotAccessVerdict[],
   scope?: SlotParamScope
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
@@ -288,7 +280,7 @@ async function wrapWithIntermediateSegments(
       errorBoundaryComponent: TimberErrorBoundary,
     });
     element = await wrapWithLayout(seg, element, h, scope);
-    element = await wrapWithAccessGate(seg, element, h, accessVerdicts, scope);
+    element = await wrapWithAccessGate(seg, element, h, scope);
   }
   return element;
 }
@@ -361,7 +353,6 @@ async function wrapWithAccessGate(
   slotNode: ManifestSegmentNode,
   element: React.ReactElement,
   h: CreateElementFn,
-  accessVerdicts?: SlotAccessVerdict[],
   scope?: SlotParamScope
 ): Promise<React.ReactElement> {
   if (!slotNode.access) return element;
@@ -382,16 +373,6 @@ async function wrapWithAccessGate(
 
   const defaultFallback = await renderDefaultFallback(slotNode, h);
 
-  // Look up pre-computed verdict from eager evaluation. Only replay
-  // denial/redirect verdicts — 'pass' verdicts must NOT be replayed
-  // because the access function may warm React.cache (e.g., requireUser())
-  // for layout/page dedup, and replaying 'pass' skips the cache-warming
-  // call. 'error' verdicts are also excluded — the gate must re-run
-  // accessFn so the error reaches the slot's error boundary.
-  const preVerdict = accessVerdicts?.find(
-    (v) => v.node === slotNode && v.verdict !== 'pass' && v.verdict !== 'error'
-  );
-
   return h(SlotAccessGate, {
     accessFn,
     DeniedComponent,
@@ -399,7 +380,6 @@ async function wrapWithAccessGate(
     createElement: h,
     defaultFallback,
     children: element,
-    verdict: preVerdict?.verdict,
   });
 }
 
@@ -496,74 +476,6 @@ function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMa
   return { page: leaf.page, chain: result.chain, slotParams: result.params };
 }
 
-// ─── Slot Access Evaluation ─────────────────────────────────────────────────
-
-/** Result of eagerly evaluating one segment's access.ts. */
-export interface SlotAccessVerdict {
-  node: ManifestSegmentNode;
-  /**
-   * 'pass' — access allowed.
-   * DenySignal/RedirectSignal — access denied, replayed in SlotAccessGate.
-   * 'error' — unknown error. Forces full render. No verdict passed to
-   *   SlotAccessGate, so it calls accessFn during render and the error
-   *   reaches the slot's error boundary.
-   */
-  verdict: 'pass' | 'error' | DenySignal | RedirectSignal;
-}
-
-/**
- * Eagerly evaluate the access chain for a slot (root + intermediate segments).
- *
- * Runs each access.ts top-down (outermost first). If any denies, the chain
- * stops (shallowest failure wins, matching segment access semantics).
- *
- * Verdicts are stored for replay in SlotAccessGate / wrapWithIntermediateSegments
- * so access.ts is called exactly once per request.
- */
-async function evaluateSlotAccessChain(
-  slotRoot: ManifestSegmentNode,
-  chain: ManifestSegmentNode[],
-  scope?: SlotParamScope
-): Promise<SlotAccessVerdict[]> {
-  // Collect all nodes with access.ts: slot root + intermediate chain segments
-  const nodesWithAccess: ManifestSegmentNode[] = [];
-  if (slotRoot.access) nodesWithAccess.push(slotRoot);
-  for (let i = 1; i < chain.length; i++) {
-    if (chain[i].access) nodesWithAccess.push(chain[i]);
-  }
-
-  if (nodesWithAccess.length === 0) return [];
-
-  const results: SlotAccessVerdict[] = [];
-  for (const node of nodesWithAccess) {
-    const accessFn = await loadComponent(node.access!);
-    if (!accessFn) {
-      results.push({ node, verdict: 'pass' });
-      continue;
-    }
-    try {
-      await (scope ? scope(() => accessFn()) : accessFn());
-      results.push({ node, verdict: 'pass' });
-    } catch (e) {
-      if (e instanceof DenySignal) {
-        results.push({ node, verdict: e });
-        break; // shallowest failure wins
-      }
-      if (e instanceof RedirectSignal) {
-        results.push({ node, verdict: e });
-        break;
-      }
-      // Unknown error — record as 'error' to force full render (blocks
-      // canSkip via accessBlocked). No verdict is passed to SlotAccessGate
-      // (wrapWithAccessGate filters 'error' out), so the gate calls
-      // accessFn during render and the error reaches the error boundary.
-      results.push({ node, verdict: 'error' });
-      break;
-    }
-  }
-  return results;
-}
-
 // ─── Slot Caching ──────────────────────────────────────────────────────────
 
 export interface SlotSkipEntry {
@@ -579,6 +491,12 @@ export interface SlotSkipEntry {
   denied: boolean;
   /** Whether the slot was skipped (content not rendered, client keeps cached). */
   skipped?: boolean;
+  /**
+   * Content key encoding owner parts + slot name + entry file + slot params.
+   * Sent to the client via X-Timber-Segments; the client advertises it back
+   * so the server can decide skips by key membership (TIM-1370).
+   */
+  contentKey: string;
 }
 
 /**
@@ -643,6 +561,88 @@ export function publishSlotSegmentParams(
   }
 }
 
+/**
+ * Emit slot metadata for a layout whose rendering was SKIPPED.
+ *
+ * Skipped layouts never reach `resolveSlotProps`, but the client rebuilds
+ * its segment tree from each navigation's X-Timber-Segments response. If
+ * skipped slots are absent, the client loses their contentKeys and can't
+ * advertise them on the next navigation — breaking key-based slot skipping.
+ *
+ * This computes contentKey and isRequestDependent for each slot without
+ * rendering anything, using the same derivation as `resolveSlotProps`.
+ */
+export function emitSlotInfoForSkippedLayout(
+  segment: ManifestSegmentNode,
+  segmentId: string,
+  match: RouteMatch,
+  destinationUrl: string,
+  slotSkipInfo: SlotSkipEntry[]
+): void {
+  const slotEntries = Object.entries(segment.slots ?? {});
+  if (slotEntries.length === 0) return;
+
+  const destinationParts = slotUrlParts(segment, match, destinationUrl);
+  const ownerParts = consumedPartsThroughSegment(segment, match);
+
+  for (const [slotName, slotNode] of slotEntries) {
+    const slotManifest = slotNode as ManifestSegmentNode;
+    const slotKey = computeSlotKey(segmentId, `@${slotName}`);
+    const destMatch = matchUrlParts(slotManifest, destinationParts);
+
+    const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+    const entryFile = destLeaf?.page?.filePath ?? null;
+    const contentKey = computeSlotContentKey(
+      slotKey,
+      ownerParts,
+      entryFile,
+      destMatch?.params ?? {}
+    );
+
+    const hasAccessInChain =
+      !!slotManifest.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
+
+    let slotRequestDep = hasAccessInChain;
+    if (!slotRequestDep) {
+      const hasRenderedPage = destMatch && destLeaf?.page;
+      if (hasRenderedPage) {
+        if (
+          slotManifest.layout?.filePath &&
+          isStaticRequestDependent(slotManifest.layout.filePath)
+        ) {
+          slotRequestDep = true;
+        }
+        if (!slotRequestDep) {
+          for (const seg of destMatch.chain) {
+            if (seg.layout?.filePath && isStaticRequestDependent(seg.layout.filePath)) {
+              slotRequestDep = true;
+              break;
+            }
+          }
+        }
+        if (!slotRequestDep && destLeaf?.page?.filePath) {
+          slotRequestDep = isStaticRequestDependent(destLeaf.page.filePath);
+        }
+      } else {
+        const defaultFile = slotManifest.default?.filePath;
+        if (!defaultFile) {
+          slotRequestDep = true;
+        } else {
+          slotRequestDep = isStaticRequestDependent(defaultFile);
+        }
+      }
+    }
+
+    slotSkipInfo.push({
+      slotKey,
+      parentSegmentId: segmentId,
+      isRequestDependent: slotRequestDep,
+      denied: false,
+      contentKey,
+    });
+  }
+}
+
 interface ResolveSlotPropsArgs {
   segment: ManifestSegmentNode;
   segmentId: string;
@@ -650,7 +650,6 @@ interface ResolveSlotPropsArgs {
   h: CreateElementFn;
   interception?: InterceptionContext;
   parentTreePath: string;
-  departingUrl: string | null;
   destinationUrl: string;
   clientStateTree: ClientStateTree | null;
   slotSkipInfo: SlotSkipEntry[];
@@ -658,9 +657,16 @@ interface ResolveSlotPropsArgs {
 
 /**
  * Resolve all parallel route slots for a layout, wrapping each in a
- * SegmentOutlet for client-side caching. Slots whose matched content
- * hasn't changed between the departing and destination URLs are rendered
- * with `skip=true` so the client keeps its cached content.
+ * SegmentOutlet for client-side caching. Slots whose content key matches
+ * one the client advertised are rendered with `skip=true` so the client
+ * keeps its cached content.
+ *
+ * The skip decision is key-based (TIM-1370): the server computes a content
+ * key per slot from the owning segment's URL parts, the slot name, the
+ * matched entry file, and the slot's own params. The client advertises
+ * the keys it has cached; the server checks membership. This replaces
+ * the previous approach of reconstructing the client's state from a
+ * departing URL.
  */
 export async function resolveSlotProps({
   segment,
@@ -669,7 +675,6 @@ export async function resolveSlotProps({
   h,
   interception,
   parentTreePath,
-  departingUrl,
   destinationUrl,
   clientStateTree,
   slotSkipInfo,
@@ -678,106 +683,51 @@ export async function resolveSlotProps({
   const slotEntries = Object.entries(segment.slots ?? {});
   if (slotEntries.length === 0) return slotProps;
 
-  // Parse URLs to extract pathnames for slot skip comparison.
-  // The departing URL (X-Timber-URL) is an untrusted request header —
-  // catch parse failures and fall back to no-cache (full render).
-  const destParsed = new URL(destinationUrl, 'http://localhost');
-  let depParsed: URL | null = null;
-  if (departingUrl) {
-    try {
-      depParsed = new URL(departingUrl, 'http://localhost');
-    } catch {
-      // Malformed departing URL — disable slot skipping for this request
-    }
-  }
-  const destinationPathname = destParsed.pathname;
-  const departingPathname = depParsed?.pathname ?? null;
-
-  const sliceAt = consumedPartsThroughSegment(segment, match).length;
-
-  function splitPathname(pathname: string): string[] {
-    return pathname === '/' ? [] : pathname.slice(1).split('/');
-  }
-
-  const destinationAll = splitPathname(destinationPathname);
-  const departingAll = departingPathname ? splitPathname(departingPathname) : null;
   const destinationParts = slotUrlParts(segment, match, destinationUrl);
-  const departingParts = departingAll ? departingAll.slice(sliceAt) : null;
-  const clientSlots = clientStateTree?.slots ?? null;
-
-  // Check if parent segment's URL parts changed (e.g., /users/1 → /users/2).
-  let parentParamsChanged = false;
-  if (departingAll) {
-    const depParent = departingAll.slice(0, sliceAt);
-    const destParent = destinationAll.slice(0, sliceAt);
-    parentParamsChanged =
-      depParent.length !== destParent.length || depParent.some((p, i) => p !== destParent[i]);
-  }
+  const clientSlotKeys = clientStateTree?.slots ?? null;
+
+  // Owner URL parts — the URL values consumed through this segment.
+  // These are part of the content key because the slot's page may read
+  // parent params (e.g., via getSegmentParams).
+  const ownerParts = consumedPartsThroughSegment(segment, match);
 
   for (const [slotName, slotNode] of slotEntries) {
     const slotManifest = slotNode as ManifestSegmentNode;
     const slotKey = computeSlotKey(segmentId, `@${slotName}`);
 
     // Match the slot's sub-tree against the destination URL parts.
-    // Used for both the skip decision and eager access evaluation.
     const destMatch = matchUrlParts(slotManifest, destinationParts);
 
-    // Seed slot params BEFORE eager access evaluation so that access.ts
-    // files calling getSegmentParams() see the slot's own coerced params,
-    // not the main route's. This is the same seeding that resolveSlotElement
-    // does, but we need it here for the eager path.
-    let eagerScope: SlotParamScope | undefined;
-    if (destMatch) {
-      const coerced = coerceSlotParams(destMatch.chain, destMatch.params);
-      const fullSlotPath = computeSlotSegmentPath(destMatch.chain, parentTreePath);
-      if (fullSlotPath && Object.keys(coerced).length > 0) {
-        setSlotParams(fullSlotPath, coerced);
-      }
-      // The eager path calls access.ts outside the React tree, so the render
-      // scope in resolveSlotElement cannot cover it. Without this, the same
-      // access.ts would read the main route's params when the slot is a skip
-      // candidate and the slot's own params when it is not.
-      eagerScope = (fn) => runWithSlotSegmentParams(fullSlotPath, coerced, fn);
-    }
+    // Compute the content key for this slot at the destination URL.
+    const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+    const entryFile = destLeaf?.page?.filePath ?? null;
+    const contentKey = computeSlotContentKey(
+      slotKey,
+      ownerParts,
+      entryFile,
+      destMatch?.params ?? {}
+    );
 
-    // Check non-access skip conditions first. If any of these fail,
-    // the slot can't be skipped regardless of access — no need to run
-    // the eager access evaluation (which would double-run access.ts
-    // since the in-tree gate also calls it during render).
+    // Auth-bearing slots are inherently request-dependent — their content
+    // changes based on user state. Skipping them would require eager
+    // evaluation of access.ts outside React.cache scope, causing double
+    // execution (TIM-1364). Instead, exclude them from skip candidates
+    // entirely and let SlotAccessGate handle access during render.
+    // The client filters these out via isRequestDependent, so their keys
+    // are never advertised — but checking here is defense-in-depth.
+    const hasAccessInChain =
+      !!slotManifest.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
     const hasInterceptingChildren = slotManifest.children.some(
       (c) => c.segmentType === 'intercepting'
     );
-    const isSkipCandidate =
+    const canSkip =
       !interception &&
       !hasInterceptingChildren &&
-      !parentParamsChanged &&
-      departingParts !== null &&
-      shouldSkipSlot({
-        slotKey,
-        clientSlots,
-        slotNode: slotManifest,
-        departingUrlParts: departingParts,
-        destinationUrlParts: destinationParts,
-      });
-
-    // Eagerly evaluate the slot's access chain only for skip candidates.
-    // This serves two purposes:
-    // 1. Satisfies security principle #3 (auth always runs) for skipped slots
-    // 2. Determines whether access denied (denied slots must not be skipped)
-    //
-    // Non-skip-candidate slots skip eager evaluation — their access.ts
-    // runs during render via SlotAccessGate (normal path). Per design doc:
-    // "No access check for default.tsx" (destMatch null = unmatched slot).
-    const chainVerdicts =
-      isSkipCandidate && destMatch
-        ? await evaluateSlotAccessChain(slotManifest, destMatch.chain, eagerScope)
-        : [];
-    const accessBlocked = chainVerdicts.some((v) => v.verdict !== 'pass');
-    const canSkip = isSkipCandidate && !accessBlocked;
+      !hasAccessInChain &&
+      shouldSkipSlot(contentKey, clientSlotKeys);
 
     if (canSkip) {
-      // Access already ran eagerly (all verdicts 'pass') — principle #3 satisfied.
-      // No gate wrapper needed.
+      // No access.ts in this slot's chain (excluded above), so no gate needed.
       slotProps[slotName] = h(SegmentOutlet, {
         segmentPath: slotKey,
         skip: true,
@@ -789,6 +739,7 @@ export async function resolveSlotProps({
         isRequestDependent: false,
         denied: false,
         skipped: true,
+        contentKey,
       });
     } else {
       const resolvedElement = await resolveSlotElement(
@@ -796,8 +747,7 @@ export async function resolveSlotProps({
         match,
         h,
         interception,
-        parentTreePath,
-        chainVerdicts
+        parentTreePath
       );
       slotProps[slotName] = h(SegmentOutlet, {
         segmentPath: slotKey,
@@ -806,10 +756,13 @@ export async function resolveSlotProps({
       // Static analysis: check if any file in the slot's RENDERED tree
       // is request-dependent. Only check layouts when destMatch exists —
       // unmatched slots render default.tsx directly without layouts.
-      let slotRequestDep = false;
-      const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+      // Slots with access.ts are inherently request-dependent — their
+      // content varies with user state (TIM-1364).
+      let slotRequestDep = hasAccessInChain;
       const hasRenderedPage = destMatch && destLeaf?.page;
-      if (interception) {
+      if (slotRequestDep) {
+        // Already marked — skip static analysis
+      } else if (interception) {
         // `destMatch` walks the slot's ordinary children against the
         // destination URL; the interception resolver renders an intercepting
         // child instead, which that walk never sees. So the files analyzed
@@ -854,7 +807,8 @@ export async function resolveSlotProps({
         slotKey,
         parentSegmentId: segmentId,
         isRequestDependent: slotRequestDep,
-        denied: accessBlocked,
+        denied: false,
+        contentKey,
       });
     }
   }

package/src/server/state-tree-diff.ts

@@ -15,8 +15,6 @@
  */
 
 import { swallow } from './logger.js';
-import { matchUrlParts } from './tree-match.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
 
 // ─── State Tree Parsing ──────────────────────────────────────────
 
@@ -112,72 +110,23 @@ export function shouldSkipSegment(
 
 // ─── Slot Skip Decision ─────────────────────────────────────────
 
-interface ShouldSkipSlotArgs {
-  slotKey: string;
-  clientSlots: Set<string> | null;
-  slotNode: ManifestSegmentNode;
-  departingUrlParts: string[];
-  destinationUrlParts: string[];
-}
-
 /**
  * Determine whether a parallel route slot can be skipped.
  *
- * A slot is skipped when ALL of:
- * 1. The client has this slot cached (slotKey is in clientSlots)
- * 2. The slot's matched page is the SAME for both the departing and
- *    destination URLs (same page file + same extracted params)
+ * A slot is skipped when the destination content key — computed from the
+ * owning segment's URL parts, the slot name, the matched entry file, and
+ * the slot's extracted params — is in the set of keys the client advertised.
  *
- * The comparison uses matchUrlParts to find what each URL would match
- * in the slot's sub-tree, then compares the matched page file and params.
+ * This replaced URL-based departing/destination diffing in TIM-1370.
+ * The previous approach reconstructed the client's state by re-matching a
+ * departing URL against each slot's sub-tree, which was a recurring bug
+ * source because the reconstruction could drift from the client's actual
+ * mounted state. The key-based approach is a single set-membership check.
  *
  * This is a performance optimization only, NOT a security boundary.
  * Slot access.ts always runs via SlotAccessGate regardless.
  */
-export function shouldSkipSlot({
-  slotKey,
-  clientSlots,
-  slotNode,
-  departingUrlParts,
-  destinationUrlParts,
-}: ShouldSkipSlotArgs): boolean {
-  if (!clientSlots) return false;
-  if (!clientSlots.has(slotKey)) return false;
-
-  const departingMatch = matchUrlParts(slotNode, departingUrlParts);
-  const destinationMatch = matchUrlParts(slotNode, destinationUrlParts);
-
-  // Both null (no match) — slot shows default.tsx in both cases
-  if (!departingMatch && !destinationMatch) return true;
-  // One null, one not — match changed
-  if (!departingMatch || !destinationMatch) return false;
-
-  const departingLeaf = departingMatch.chain[departingMatch.chain.length - 1];
-  const destinationLeaf = destinationMatch.chain[destinationMatch.chain.length - 1];
-
-  // Both must have a page, and the page file must be the same
-  if (!departingLeaf.page || !destinationLeaf.page) {
-    return !departingLeaf.page && !destinationLeaf.page;
-  }
-  if (departingLeaf.page.filePath !== destinationLeaf.page.filePath) return false;
-
-  // Compare extracted params — if any differ, the slot content may change
-  return paramsEqual(departingMatch.params, destinationMatch.params);
-}
-
-function paramsEqual(
-  a: Record<string, string | string[]>,
-  b: Record<string, string | string[]>
-): boolean {
-  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
-  for (const key of keys) {
-    const va = a[key];
-    const vb = b[key];
-    if (Array.isArray(va) && Array.isArray(vb)) {
-      if (va.length !== vb.length || va.some((v, i) => v !== vb[i])) return false;
-    } else if (va !== vb) {
-      return false;
-    }
-  }
-  return true;
+export function shouldSkipSlot(contentKey: string, clientSlotKeys: Set<string> | null): boolean {
+  if (!clientSlotKeys) return false;
+  return clientSlotKeys.has(contentKey);
 }

package/src/server/tree-builder.ts

@@ -138,16 +138,6 @@ export interface SlotAccessGateProps {
   createElement: CreateElement;
   defaultFallback: ReactNode;
   children: ReactNode;
-  /**
-   * Pre-computed verdict from eager access evaluation. When provided,
-   * SlotAccessGate replays it synchronously instead of re-calling accessFn.
-   * 'pass' → render children. DenySignal → graceful degradation.
-   * undefined → call accessFn during render (backward compat, error re-run).
-   */
-  verdict?:
-    | 'pass'
-    | import('./primitives.js').DenySignal
-    | import('./primitives.js').RedirectSignal;
 }
 
 // ─── Tree Builder ────────────────────────────────────────────────────────────

package/src/shared/segment-info.ts

@@ -39,6 +39,13 @@ export interface SegmentInfo {
   denied?: boolean;
   /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
   skipped?: boolean;
+  /**
+   * Content key for slot entries — encodes owner parts, slot name, matched
+   * entry file, and slot params. The client stores and advertises this key;
+   * the server computes the destination key and checks membership.
+   * Replaces URL-based departing/destination diffing (TIM-1370).
+   */
+  contentKey?: string;
 }
 
 /**

package/dist/_chunks/use-query-states-BbU5Ge1V.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-query-states-BbU5Ge1V.js","names":[],"sources":["../../src/search-params/parse-total.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * parseTotal — invoke a codec over the FULL raw domain.\n *\n * `SearchParamCodec.parse` is documented to be total over\n * `string | string[] | undefined`, because that is exactly what a URL\n * hands it: a param can be absent (`undefined`) or repeated (`string[]`).\n * Timber's own codecs and the Standard Schema bridges honour that.\n *\n * nuqs parsers do not. Their `parse` expects a **present scalar string** —\n * nuqs checks presence itself before ever calling it — so `parseAsBoolean`\n * and `parseAsIsoDate` threw a render-phase 500 on an absent param and\n * `parseAsString` returned an array on a repeated one (TIM-1350).\n *\n * nuqs ships the missing adapter: every parser builder exposes\n * `parseServerSide(value: string | string[] | undefined)`, which maps\n * absent → `null` (or the parser's `withDefault` value), takes the FIRST\n * entry of a repeated param (matching `URLSearchParams.get()`), and wraps\n * the inner `parse` so a throw becomes `null`. That is precisely timber's\n * domain, so we call it in preference to `parse` rather than hand-rolling\n * a second normalization that could disagree with the client hook.\n *\n * Feature detection, not an instanceof check: any codec MAY publish\n * `parseServerSide` to declare \"this is my total entry point\" — it is an\n * optional member of `SearchParamCodec` — and a codec that does not is\n * assumed already total and called through `parse`. Timber codecs and\n * schema bridges take the second branch untouched; several of them rely on\n * `parse(undefined)` to produce their default.\n *\n * **Search params only.** Segment params (`server/param-coercion.ts`) call\n * `codec.parse` directly and must keep doing so: their domain is a value\n * the router matched, never absent, and a codec that REJECTS one is how a\n * route produces a 404. Routing a rejection through nuqs's `safeParse`\n * would turn that 404 into a silent `null` param. The two domains differ\n * in what \"no value\" means, not just in plumbing. Cookies are a third\n * domain (`cookies/define-cookie.ts`) and are likewise untouched.\n *\n * `parseServerSide` carries a `@deprecated` tag in nuqs (it steers users to\n * loaders, which timber does not use). It remains public, typed and\n * exercised; `tests/nuqs-codec-boundary.test.ts` asserts totality for every\n * parser through timber's own API, so a nuqs release that drops it fails\n * loudly rather than silently reinstating the 500s.\n *\n * Design doc: design/23-search-params.md §\"nuqs parsers, made total\"\n */\n\nimport type { Codec } from '../codec.js';\n\n/**\n * A codec that publishes a total entry point over the raw URL domain.\n *\n * The return is `T`, not `T | null`: this is the entry point timber calls,\n * so whatever it answers IS the field's type. A `null` for an absent param\n * belongs in `T` — a bare nuqs parser is a codec of `string | null`, and\n * `parseAsInteger.withDefault(1)` is a codec of `number`, because nuqs\n * narrows its own `parseServerSide` return to `NonNullable<T>`. Declaring\n * `T | null` here would let a codec annotated `SearchParamCodec<string>`\n * hand back `null` under a non-nullable type (TIM-1350 review).\n */\nexport interface TotalCodec<T> {\n  parseServerSide(value: string | string[] | undefined): T;\n}\n\nfunction hasParseServerSide<T>(codec: Codec<T>): codec is Codec<T> & TotalCodec<T> {\n  return typeof (codec as Partial<TotalCodec<T>>).parseServerSide === 'function';\n}\n\n/**\n * Parse a raw URL value through a codec, using the codec's total entry\n * point when it publishes one.\n *\n * Returns `T`, from both branches. A `null` for an absent param is part of\n * the codec's own `T` — see TotalCodec above — so this signature does not\n * widen it, and a caller that must handle \"no value\" (`withDefault`) sees\n * it because `T` carries it.\n */\nexport function parseTotal<T>(codec: Codec<T>, raw: string | string[] | undefined): T {\n  return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { MultiParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { parseTotal } from '../search-params/parse-total.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n// nuqs's parser contract conflates values timber codecs distinguish:\n// parse() returning null means \"unparseable, substitute defaultValue\",\n// and undefined entries are skipped entirely. Timber codecs can\n// legitimately produce both — bare z.string() yields undefined for absent\n// params (implicit optionality), and a codec may map a present value to\n// null. Wrap those two values in sentinels across the nuqs boundary and\n// unwrap them before handing values back to the caller, so the client\n// hook returns exactly what server-side parse() returns.\n// Unique object references compared by identity — a codec can never\n// produce these from URL input, so user-controlled strings cannot collide\n// with them (unlike string sentinels), and unlike Symbols they survive\n// nuqs's internal string coercion without throwing.\nconst NULL_SENTINEL: object = { timberSentinel: 'null' };\nconst UNDEFINED_SENTINEL: object = { timberSentinel: 'undefined' };\n\nfunction wrapNuqsValue(value: unknown): unknown {\n  if (value === null) return NULL_SENTINEL;\n  if (value === undefined) return UNDEFINED_SENTINEL;\n  return value;\n}\n\nfunction unwrapNuqsValue(value: unknown): unknown {\n  if (value === NULL_SENTINEL) return null;\n  if (value === UNDEFINED_SENTINEL) return undefined;\n  return value;\n}\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n *\n * The defaultValue is computed eagerly, through `parseTotal` — the same\n * entry point server-side `parse()` uses, so the hook and the server agree\n * on what an absent param means (a bare nuqs parser answers `null`, not\n * `undefined`; TIM-1350). Codecs are documented to return a default rather\n * than throw, but a throwing codec must not crash every component that\n * mounts the hook — treat its default as undefined and let its error\n * surface from server-side parse() instead.\n *\n * A `null` absent-value is NOT registered as the nuqs default. nuqs\n * already represents an absent key as `null`, so the hook reads the same\n * value either way — but registering it makes `clearOnDefault` fire on\n * `setParams({ q: null })` and delete the key before the bridged\n * `serialize` runs. For a codec that encodes `null` as a real query value\n * (`serialize(null) === 'none'`), that silently disagrees with\n * `buildSearchParams({ q: null })`, which writes it. Same reasoning as\n * `getDefaultSerialized` on the server: a codec with no value for an\n * absent param has no default to register.\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): MultiParser<T> & { defaultValue: T } {\n  let absent: unknown;\n  try {\n    absent = parseTotal(codec, undefined);\n  } catch {\n    absent = undefined;\n  }\n\n  const parser = {\n    // `multi`, so nuqs reads the key with `searchParams.getAll()` and hands\n    // us EVERY value. A single parser reads `.get()` — the first value only\n    // — which is not the domain a timber codec is defined over. The server\n    // parses `?tags=a&tags=b` as `['a','b']`; a single parser made the hook\n    // answer `['a']` for the same URL, under a declared `string[]` that\n    // admitted no such disagreement (TIM-1352). Scalar codecs are unaffected:\n    // they receive the array and take `value[0]`, exactly as they do on the\n    // server, so first-value-wins is preserved through the same code path\n    // rather than through nuqs's reader.\n    //\n    // nuqs never calls this with an empty array — `isAbsentFromUrl` treats\n    // `[]` as absent and answers `defaultValue` directly — which is what\n    // keeps the absent case agreeing with the server's `undefined`.\n    //\n    // Reading every value is only half of it: the values must arrive in the\n    // SAME SHAPE the server would have produced, or the divergence just\n    // moves. `normalizeRaw` (search-params/define.ts) collapses a\n    // single-valued key to a bare string and keeps an array only for a\n    // repeated one, so this mirrors that rule exactly. Handing a codec\n    // `['3']` where the server hands it `'3'` breaks every codec whose\n    // `parse` is written for the scalar case — which is most hand-written\n    // ones, contract or no contract.\n    type: 'multi' as const,\n    // Through parseTotal, not codec.parse. nuqs's own `.withDefault(d)`\n    // overrides ONLY `parseServerSide`, so `parseAsInteger.withDefault(1)`\n    // on `?page=abc` returned 1 from the server and null from the hook —\n    // a divergence the declared non-nullable `number` did not admit.\n    parse: (v: readonly string[]) =>\n      wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),\n    serialize: (v: unknown) => {\n      const value = unwrapNuqsValue(v);\n      // Delegate null to the codec — some codecs encode null as a real\n      // query value. undefined has no encoding; nuqs requires a string.\n      //\n      // ONE element, always. A multi parser may return several — nuqs\n      // appends one key per entry — but `Codec.serialize` returns a single\n      // string by construction, so timber cannot emit repeated keys here\n      // any more than `buildSearchParams` can. Widening that protocol is\n      // TIM-1353. Wrapping the same string keeps the URL the hook writes\n      // byte-identical to the one `buildSearchParams` writes.\n      return [value === undefined ? '' : (codec.serialize(value as T) ?? '')];\n    },\n    eq: (a: unknown, b: unknown) => {\n      if (a === b) return true;\n      try {\n        return (\n          codec.serialize(unwrapNuqsValue(a) as T) === codec.serialize(unwrapNuqsValue(b) as T)\n        );\n      } catch {\n        return false;\n      }\n    },\n  } as MultiParser<T> & { defaultValue: T };\n\n  if (absent !== null) parser.defaultValue = wrapNuqsValue(absent) as T;\n  return parser;\n}\n\n/**\n * Collect `withUrlKey` aliases off a codec map.\n *\n * `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map\n * alone is enough to reconstruct the aliases — `defineSearchParams` builds its\n * own `urlKeys` from exactly this property.\n */\nfunction deriveUrlKeys(codecs: Record<string, SearchParamCodec<unknown>>): Record<string, string> {\n  const result: Record<string, string> = {};\n  for (const key of Object.keys(codecs)) {\n    const alias = codecs[key]?.urlKey;\n    if (alias) result[key] = alias;\n  }\n  return result;\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, MultiParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: MultiParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition imported from the route's params.ts\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n *\n * There is deliberately no route-string form (`useQueryStates('/products')`).\n * Importing the definition from `params.ts` is the documented way to reach\n * another route's codecs — it needs no runtime registry lookup and so has no\n * \"not registered yet\" failure mode. See design/23-search-params.md\n * §\"Client Access\".\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> },\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  const bridged = bridgeCodecs(codecs);\n\n  // Forward hook-level options (shallow, scroll, history) to nuqs.\n  // These become the default for all setter calls from this hook instance.\n  // Per-call options in setParams(values, opts) override these defaults.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;\n  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;\n  if (_options?.history !== undefined) nuqsOptions.history = _options.history;\n  // `withUrlKey` attaches the alias to the codec itself — that is the design's\n  // \"URL keys travel with codecs\" principle — so the aliases are derivable\n  // here and must be, for the inline codec-map form: nobody passes `urlKeys`\n  // on that path, and without this an aliased bundle silently read and wrote\n  // the property name instead of the alias. `bindUseQueryStates` still passes\n  // the definition's precomputed map, which wins on conflict; it is built from\n  // these same codecs, so the two agree by construction rather than by luck.\n  const resolvedUrlKeys = { ...deriveUrlKeys(codecs), ...urlKeys };\n  if (Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Unwrap the null/undefined sentinels the bridge injected (see Codec\n  // Bridge above) so callers see exactly what server-side parse() returns.\n  // Copy-on-write preserves the identity of nuqs's memoized values object\n  // when nothing needs unwrapping.\n  let normalized = values;\n  for (const key of Object.keys(bridged)) {\n    const value = normalized[key];\n    if (value === NULL_SENTINEL || value === UNDEFINED_SENTINEL) {\n      if (normalized === values) normalized = { ...values };\n      normalized[key] = unwrapNuqsValue(value);\n    }\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // nuqs's update loop skips undefined entries and treats null as a\n    // key deletion before serialize runs. Timber semantics:\n    //   - setParams({ q: undefined }) must clear ?q= (absent = undefined),\n    //     so explicit undefined maps to a null deletion.\n    //   - setParams({ q: null }) clears the key only when the codec encodes\n    //     null as \"omit\" (serialize(null) === null). If the codec encodes\n    //     null as a real query value, forward the sentinel so the bridged\n    //     serialize writes it — matching definition.serialize({ q: null }).\n    let forwarded: Record<string, unknown> = partial;\n    for (const key of Object.keys(partial)) {\n      const value = partial[key as keyof T];\n      if (value === undefined) {\n        if (forwarded === partial) forwarded = { ...partial };\n        forwarded[key] = null;\n      } else if (value === null) {\n        let encoded: string | null = null;\n        try {\n          encoded = codecs[key as keyof T]?.serialize(null as T[keyof T]) ?? null;\n        } catch {\n          // Codec can't serialize null — treat as a deletion.\n        }\n        if (encoded !== null) {\n          if (forwarded === partial) forwarded = { ...partial };\n          forwarded[key] = NULL_SENTINEL;\n        }\n      }\n    }\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(forwarded as any, nuqsSetOptions);\n  };\n\n  return [normalized as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":"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"}