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

package/src/search-params/define.ts

@@ -21,6 +21,7 @@ import type { Codec } from '../codec.js';
 // `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.
 import { getSearchParamsFromAls } from '../shared/als-slots.js';
 import { parseTotal } from './parse-total.js';
+import { serializedEqual } from './serialize-equal.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -45,7 +46,19 @@ import { parseTotal } from './parse-total.js';
  * by defineSearchParams and wrapped via fromSchema; those ARE total
  * through `parse` and are called that way.
  */
-export interface SearchParamCodec<T> extends Codec<T> {
+export interface SearchParamCodec<T> extends Omit<Codec<T>, 'serialize'> {
+  /**
+   * Typed value → URL string(s). Return `null` to omit/clear.
+   *
+   * A codec MAY return `string[]` to emit repeated keys (`?tag=a&tag=b`).
+   * `buildSearchParams` appends one `key=value` entry per array element;
+   * the nuqs bridge forwards the array to nuqs, which does the same.
+   * Codecs that always produce a single value return a plain string.
+   *
+   * Wider than `Codec<T>.serialize` (`string | null`) because search params
+   * have a repeated-key concept that cookies and segment params do not.
+   */
+  serialize(value: T): string | string[] | null;
   /** Optional URL key alias, set by withUrlKey(). */
   urlKey?: string;
   /**
@@ -136,7 +149,7 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
   useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
 
   /** Extend with additional codecs or Standard Schema objects. */
-  extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
+  extend<U extends Record<string, SearchParamField>>(
     codecs: U
   ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;
 
@@ -235,8 +248,27 @@ export type InferField<V> = V extends {
         : T | undefined
       : never;
 
-/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */
-export type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;
+/**
+ * A codec whose total entry point is `parseServerSide`, even when `parse`
+ * has a narrower signature. nuqs multi parsers (`parseAsNativeArrayOf`) have
+ * `parse(value: readonly string[])` — too narrow for `SearchParamCodec`'s
+ * `parse(string | string[] | undefined)` — but their `parseServerSide`
+ * covers the full domain. Timber never calls `parse` directly on these;
+ * `parseTotal` always reaches `parseServerSide` first (TIM-1355).
+ */
+export interface TotalSearchParamCodec<T> {
+  parseServerSide(value: string | string[] | undefined): T;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parse(...args: any[]): any;
+  serialize(value: T): string | string[] | null;
+  urlKey?: string;
+}
+
+/** Acceptable field value for defineSearchParams: a codec, a total codec, or a Standard Schema. */
+export type SearchParamField<T = unknown> =
+  | SearchParamCodec<T>
+  | TotalSearchParamCodec<T>
+  | StandardSchemaV1<T>;
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -291,7 +323,7 @@ function normalizeRaw(
  * which for a nuqs parser is `T | null` while its `serialize` declares
  * `T`. Widening to `unknown` states that honestly instead of casting.
  */
-function getDefaultSerialized(codec: SearchParamCodec<unknown>): string | null {
+function getDefaultSerialized(codec: SearchParamCodec<unknown>): string | string[] | null {
   try {
     const absent = parseTotal(codec, undefined);
     return absent === null || absent === undefined ? null : codec.serialize(absent);
@@ -305,6 +337,12 @@ function getDefaultSerialized(codec: SearchParamCodec<unknown>): string | null {
 /**
  * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema
  * objects and wraps them with fromSchema. Reads .urlKey from codecs.
+ *
+ * The returned codec is typed as `SearchParamCodec<unknown>` because the
+ * codec map uses that type. At runtime, the value may be a `Codec<T>` from
+ * `fromSchema` (whose serialize returns `string | null`) or a nuqs parser
+ * (whose serialize returns `string | string[] | null`). Both are safe
+ * because `buildSearchParams` handles the union.
  */
 function resolveField(
   fieldName: string,
@@ -312,7 +350,8 @@ function resolveField(
 ): { codec: SearchParamCodec<unknown>; urlKey?: string } {
   // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)
   if (isCodec(value)) {
-    return { codec: value, urlKey: value.urlKey };
+    const urlKey = (value as SearchParamCodec<unknown>).urlKey;
+    return { codec: value as SearchParamCodec<unknown>, urlKey };
   }
 
   // Auto-detect Standard Schema. Schemas that reject undefined input and
@@ -320,7 +359,7 @@ function resolveField(
   // for absent params, and InferField widens the output type to
   // T | undefined. design/23-search-params.md §"Implicit Optionality"
   if (isStandardSchema(value)) {
-    return { codec: fromSchema(value) };
+    return { codec: fromSchema(value) as SearchParamCodec<unknown> };
   }
 
   throw new Error(
@@ -443,7 +482,7 @@ function buildDefinition<T extends Record<string, unknown>>(
   urlKeys: Record<string, string>
 ): SearchParamsDefinition<T> {
   // Pre-compute default serialized values for omission check
-  const defaultSerialized: Record<string, string | null> = {};
+  const defaultSerialized: Record<string, string | string[] | null> = {};
   for (const key of Object.keys(codecMap)) {
     defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);
   }
@@ -497,13 +536,33 @@ function buildDefinition<T extends Record<string, unknown>>(
     for (const prop of Object.keys(codecMap)) {
       if (!(prop in values)) continue;
       const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;
-      const serialized = codec.serialize(values[prop as keyof T] as unknown);
 
-      // Omit if serialized value matches the default
-      if (serialized === defaultSerialized[prop]) continue;
-      if (serialized === null) continue;
+      // TIM-1354: serialize may not be total over null — nuqs parsers like
+      // parseAsIsoDate throw TypeError on null (null.toISOString()). Catch
+      // TypeError and omit, matching what setParams does on the client.
+      // Only TypeError — a deliberate throw (redirect(), notFound()) from a
+      // codec's serialize must propagate, not be silently swallowed.
+      let serialized: string | string[] | null;
+      try {
+        serialized = codec.serialize(values[prop as keyof T] as unknown);
+      } catch (error) {
+        if (error instanceof TypeError) continue;
+        throw error;
+      }
 
-      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
+      if (serialized === null) continue;
+      // Omit if serialized value matches the default
+      if (serializedEqual(serialized, defaultSerialized[prop])) continue;
+
+      // TIM-1353: string[] → repeated keys (?tag=a&tag=b)
+      const urlKey = encodeURIComponent(getUrlKey(prop));
+      if (Array.isArray(serialized)) {
+        for (const entry of serialized) {
+          parts.push(`${urlKey}=${encodeURIComponent(entry)}`);
+        }
+      } else {
+        parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);
+      }
     }
 
     return parts.join('&');
@@ -516,7 +575,7 @@ function buildDefinition<T extends Record<string, unknown>>(
   }
 
   // ---- extend ----
-  function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
+  function extend<U extends Record<string, SearchParamField>>(
     newCodecs: U
   ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {
     type Combined = T & { [K in keyof U]: InferField<U[K]> };

package/src/search-params/index.ts

@@ -7,6 +7,7 @@
 export type {
   SearchParamCodec,
   SearchParamCodecWithUrlKey,
+  TotalSearchParamCodec,
   InferCodec,
   InferField,
   CodecMap,

package/src/search-params/parse-total.ts

@@ -43,12 +43,23 @@
  * Design doc: design/23-search-params.md §"nuqs parsers, made total"
  */
 
-import type { Codec } from '../codec.js';
+/**
+ * Minimal interface for anything `parseTotal` can dispatch. Only `parse` is
+ * required; `parseServerSide` is the optional total entry point. `serialize`
+ * is deliberately absent — `parseTotal` never calls it, and requiring it
+ * would prevent `SearchParamCodec<T>` (whose serialize returns `string |
+ * string[] | null`) from being passed where `Codec<T>` (whose serialize
+ * returns `string | null`) is expected.
+ */
+export interface ParseableCodec<T> {
+  parse(value: string | string[] | undefined): T;
+  parseServerSide?(value: string | string[] | undefined): T;
+}
 
 /**
  * A codec that publishes a total entry point over the raw URL domain.
  *
- * The return is `T`, not `T | null`: this is the entry point timber calls,
+ * The return is `T`, not `T | null`. This is the entry point timber calls,
  * so whatever it answers IS the field's type. A `null` for an absent param
  * belongs in `T` — a bare nuqs parser is a codec of `string | null`, and
  * `parseAsInteger.withDefault(1)` is a codec of `number`, because nuqs
@@ -60,7 +71,9 @@ export interface TotalCodec<T> {
   parseServerSide(value: string | string[] | undefined): T;
 }
 
-function hasParseServerSide<T>(codec: Codec<T>): codec is Codec<T> & TotalCodec<T> {
+function hasParseServerSide<T>(
+  codec: ParseableCodec<T>
+): codec is ParseableCodec<T> & TotalCodec<T> {
   return typeof (codec as Partial<TotalCodec<T>>).parseServerSide === 'function';
 }
 
@@ -73,6 +86,6 @@ function hasParseServerSide<T>(codec: Codec<T>): codec is Codec<T> & TotalCodec<
  * widen it, and a caller that must handle "no value" (`withDefault`) sees
  * it because `T` carries it.
  */
-export function parseTotal<T>(codec: Codec<T>, raw: string | string[] | undefined): T {
+export function parseTotal<T>(codec: ParseableCodec<T>, raw: string | string[] | undefined): T {
   return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);
 }

package/src/search-params/serialize-equal.ts

@@ -0,0 +1,14 @@
+/**
+ * Compare two serialize results for equality. Needed because `string[]`
+ * from repeated-key codecs does not compare by reference.
+ *
+ * Shared between define.ts (buildSearchParams default-omission) and
+ * use-query-states.ts (bridgeCodec eq). One source of truth.
+ */
+export function serializedEqual(a: string | string[] | null, b: string | string[] | null): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+  }
+  return false;
+}

package/src/search-params/wrappers.ts

@@ -75,7 +75,7 @@ export function withDefault<T>(
       const result = parseTotal(codec, value);
       return result === null || result === undefined ? defaultValue : result;
     },
-    serialize(value: NonNullable<T>): string | null {
+    serialize(value: NonNullable<T>): string | string[] | null {
       return codec.serialize(value);
     },
   };

package/src/server/access-gate.tsx

@@ -144,35 +144,8 @@ async function accessGateFallback(
  * slot doesn't make architectural sense.
  */
 export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactNode> {
-  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children, verdict } =
-    props;
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
-  // Fast path: replay pre-computed verdict from eager evaluation in resolveSlotProps.
-  if (verdict !== undefined) {
-    if (verdict === 'pass') return children;
-    if (verdict instanceof DenySignal) {
-      return (
-        buildDeniedFallback(DeniedComponent, slotName, verdict.data, createElement) ??
-        defaultFallback ??
-        null
-      );
-    }
-    // RedirectSignal: treat as deny in production (same as existing behavior)
-    if (isDebug()) {
-      console.error(
-        '[timber] redirect() is not allowed in slot access.ts. ' +
-          'Slots use deny() for graceful degradation — denied.tsx → default.tsx → null. ' +
-          "If you need to redirect, move the logic to the parent segment's access.ts."
-      );
-    }
-    return (
-      buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
-      defaultFallback ??
-      null
-    );
-  }
-
-  // Fallback path: call accessFn during render (no pre-computed verdict).
   try {
     await accessFn();
   } catch (error: unknown) {

package/src/server/chain-url-parts.ts

@@ -7,9 +7,8 @@
  * - the layout depth handed to `SegmentProvider` (`route-element-builder.ts`),
  *   which `useSelectedLayoutSegment(s)` indexes the live pathname with;
  * - `slotUrlParts`, which slices the destination pathname for slot matching;
- * - `resolveSlotProps`, which slices the *departing* pathname the same way to
- *   decide whether a slot can be skipped;
- * - `skippable-prefix.ts`, which does the same for the contiguous skip prefix.
+ * - `resolveSlotProps` and `skippable-prefix.ts`, which derive content keys
+ *   for slot skip decisions (TIM-1370).
  *
  * They were four separate `extractUrlParts(...).length` calls. That was fine
  * while the answer was a plain walk, and stopped being fine when interception

package/src/server/route-element-builder.ts

@@ -28,7 +28,12 @@ import { requestContextAls } from './als-registry.js';
 import { PageDenyBoundary, buildDenyPageChain, handleCaughtDeny } from './deny-boundary.js';
 import type { DenyPageEntry } from './deny-boundary.js';
 import { LAYOUT_CHILDREN_SLOT } from './prebuilt/slots.js';
-import { resolveSlotProps, publishSlotSegmentParams, type SlotSkipEntry } from './slot-resolver.js';
+import {
+  resolveSlotProps,
+  publishSlotSegmentParams,
+  emitSlotInfoForSkippedLayout,
+  type SlotSkipEntry,
+} from './slot-resolver.js';
 import { consumedUrlParts } from './chain-url-parts.js';
 import { withPublishedParams } from './publish-params.js';
 import type { RscPayloadRoot } from '../shared/payload-root.js';
@@ -547,30 +552,9 @@ export async function buildRouteElement(
 
   let outermostSegmentProvider: React.ReactElement | null = null;
 
-  // Slot caching: the departing URL (X-Timber-URL header) and the
-  // destination URL (request URL) are compared to determine which
-  // slots' content has changed.
-  //
-  // Pathnames only. The client sends `X-Timber-URL` as a pathname
-  // (`client/router.ts` takes `.pathname` on both branches) and
-  // `slot-resolver.ts` reads `.pathname` from both sides, so search
-  // params take no part in the skip decision.
-  //
-  // Nothing here can tell whether a slot's content depends on the query.
-  // What is supposed to make that safe lives elsewhere: a slot whose server
-  // render varies with the query must reach it through a request accessor
-  // (page components are built with no props), which the request-dep analysis
-  // is meant to catch — and that analysis is incomplete for accessors reached
-  // through indirection, so this is currently a real staleness hole. See
-  // TIM-1291 and design/19-client-navigation.md. A slot whose *client* subtree
-  // varies with the query reads useSearchParams(), which re-renders from
-  // NavigationContext whether or not the slot was skipped; that half is
-  // unconditional.
-  //
-  // Do not add search to the comparison by sending the full departing URL:
-  // the header is hashed into the public `_rsc` cache key (TIM-1268),
-  // and a digest does not anonymize a guessable query string.
-  const departingUrl = req.headers.get('X-Timber-URL');
+  // Slot caching uses key-based diffing (TIM-1370). The server computes a
+  // content key per slot and the client advertises keys for cached slots.
+  // The skip decision is a set-membership check — no departing URL needed.
   const destinationUrl = req.url;
   const slotSkipInfo: SlotSkipEntry[] = [];
 
@@ -592,6 +576,11 @@ export async function buildRouteElement(
       // because an unchanged slot is what made this layout skippable.
       publishSlotSegmentParams(segment, match, destinationUrl, segmentTreePaths[i]);
 
+      // Emit slot metadata so the client's segment tree retains contentKeys
+      // for slots of skipped layouts. Without this, the client rebuilds its
+      // tree from the response and loses slot keys it can't advertise next time.
+      emitSlotInfoForSkippedLayout(segment, segmentKeys[i], match, destinationUrl, slotSkipInfo);
+
       // No error boundaries are wrapped for a skipped segment — the `continue`
       // below returns before that walk. A deny addressed to this segment
       // therefore finds no boundary in the payload, and since TIM-1356 the
@@ -705,7 +694,6 @@ export async function buildRouteElement(
         h,
         interception,
         parentTreePath,
-        departingUrl,
         destinationUrl,
         clientStateTree: clientStateTree as ClientStateTree | null,
         slotSkipInfo,

package/src/server/rsc-entry/helpers.ts

@@ -248,6 +248,7 @@ export function buildSegmentInfo(
         isRequestDependent: slot.isRequestDependent,
         slot: true,
         parentSegment: slot.parentSegmentId,
+        contentKey: slot.contentKey,
       };
       if (slot.skipped) entry.skipped = true;
       if (slot.denied) entry.denied = true;

package/src/server/skippable-prefix.ts

@@ -11,7 +11,9 @@ import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
 import { consumedUrlParts } from './chain-url-parts.js';
-import { computeSlotKey } from '../routing/segment-keys.js';
+import { computeSlotContentKey, computeSlotKey } from '../routing/segment-keys.js';
+import { matchUrlParts } from './tree-match.js';
+import { slotUrlParts } from './slot-resolver.js';
 
 /**
  * Truncate the skippable prefix when a skippable layout has slots whose
@@ -22,6 +24,9 @@ import { computeSlotKey } from '../routing/segment-keys.js';
  * Removing the segment from the skippable set forces it to render with
  * its slots. The prefix must stay contiguous, so all segments after the
  * first changed-slot segment are also removed.
+ *
+ * Uses key-based diffing (TIM-1370): computes the destination content key
+ * per slot and checks if the client's advertised set contains it.
  */
 export function truncateSkippableForChangedSlots(
   skippableSet: Set<number>,
@@ -31,23 +36,8 @@ export function truncateSkippableForChangedSlots(
   clientStateTree: ClientStateTree,
   req: Request
 ): void {
-  const departingUrl = req.headers.get('X-Timber-URL');
-  let depParsed: URL | null = null;
-  if (departingUrl) {
-    try {
-      depParsed = new URL(departingUrl, 'http://localhost');
-    } catch {
-      skippableSet.clear();
-      return;
-    }
-  }
-  const destPathname = new URL(req.url, 'http://localhost').pathname;
-  const depPathname = depParsed?.pathname ?? null;
-  const split = (p: string) => (p === '/' ? [] : p.slice(1).split('/'));
-  const destAll = split(destPathname);
-  const depAll = depPathname ? split(depPathname) : null;
-  const clientSlots = clientStateTree.slots ?? null;
-  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const clientSlotKeys = clientStateTree.slots ?? null;
+  const destUrl = req.url;
 
   for (let i = 0; i < segments.length; i++) {
     if (!skippableSet.has(i)) continue;
@@ -56,33 +46,25 @@ export function truncateSkippableForChangedSlots(
     if (slotEntries.length === 0) continue;
 
     const segIdx = match.segments.indexOf(segment);
-    // The root consumes no URL part, and a climbing interception marker
-    // removes owner segments from the target — `consumedUrlParts` handles both,
-    // and is the same derivation slot matching and layout depth use.
-    const sliceAt = segIdx >= 0 ? consumedUrlParts(match.segments, segIdx, match).length : 0;
-    const destParts = destAll.slice(sliceAt);
-    const depParts = depAll ? depAll.slice(sliceAt) : null;
-    let parentChanged = false;
-    if (depAll) {
-      const dp = depAll.slice(0, sliceAt),
-        dd = destAll.slice(0, sliceAt);
-      parentChanged = dp.length !== dd.length || dp.some((p, j) => p !== dd[j]);
-    }
+    const ownerParts = segIdx >= 0 ? consumedUrlParts(match.segments, segIdx, match) : [];
+    const destParts = slotUrlParts(segment, match, destUrl);
 
     for (const [slotName, slotNode] of slotEntries) {
       const m = slotNode as ManifestSegmentNode;
       const k = computeSlotKey(segmentKeys[i], `@${slotName}`);
+
+      // Slots with access.ts are never skip candidates (TIM-1364).
+      const destMatch = matchUrlParts(m, destParts);
+      const hasAccessInChain = !!m.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
+
+      const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+      const entryFile = destLeaf?.page?.filePath ?? null;
+      const contentKey = computeSlotContentKey(k, ownerParts, entryFile, destMatch?.params ?? {});
+
       if (
+        hasAccessInChain ||
         m.children.some((c) => c.segmentType === 'intercepting') ||
-        parentChanged ||
-        depParts === null ||
-        !shouldSkipSlot({
-          slotKey: k,
-          clientSlots,
-          slotNode: m,
-          departingUrlParts: depParts,
-          destinationUrlParts: destParts,
-        })
+        !shouldSkipSlot(contentKey, clientSlotKeys)
       ) {
         for (let j = i; j < segments.length; j++) skippableSet.delete(j);
         return;