@timber-js/app 0.2.0-alpha.171 → 0.2.0-alpha.172

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

@@ -14,6 +14,7 @@ import type { RouteMatch } from '../pipeline.js';
 import type { RedirectSignal } from '../primitives.js';
 import type { LayoutComponentEntry } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
+import type { SlotSkipEntry } from '../slot-resolver.js';
 
 import {
   buildRedirectResponse,
@@ -21,6 +22,7 @@ import {
   createDebugChannelSink,
   RSC_CONTENT_TYPE,
 } from './helpers.js';
+import { requestContextAls } from '../als-registry.js';
 import type { RenderSignals } from './rsc-stream.js';
 
 /**
@@ -40,7 +42,8 @@ export async function buildRscPayloadResponse(
   layoutComponents: LayoutComponentEntry[],
   match: RouteMatch,
   responseHeaders: Headers,
-  skippedSegments?: string[]
+  skippedSegments?: string[],
+  slotSkipInfo?: SlotSkipEntry[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
   // Race the first read against signal detection — if an async component
@@ -194,9 +197,19 @@ export async function buildRscPayloadResponse(
   // client rendering. No X-Timber-Head header needed. See TIM-1151.
 
   // Send segment metadata so the client can populate its segment cache
-  // for state tree diffing on subsequent navigations.
+  // for state tree diffing on subsequent navigations. On the RSC payload
+  // path, taint results are available because the shell has rendered by
+  // the time we reach this point (first chunk already read from the stream).
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const segmentInfo = buildSegmentInfo(segments, layoutComponents);
+  const store = requestContextAls.getStore();
+  const segmentInfo = buildSegmentInfo(
+    segments,
+    layoutComponents,
+    slotSkipInfo,
+    store?.taintResults,
+    store?.orphanTaint,
+    skippedSegments
+  );
   responseHeaders.set('X-Timber-Segments', JSON.stringify(segmentInfo));
 
   // Send skipped segments so the client can merge the partial RSC payload

package/src/server/rsc-entry/ssr-renderer.ts

@@ -20,6 +20,7 @@ import type { RouteMatch } from '../pipeline.js';
 import { SsrStreamError } from '../primitives.js';
 import type { LayoutComponentEntry } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
+import type { SlotSkipEntry } from '../slot-resolver.js';
 import type { NavContext } from '../ssr-bridge-types.js';
 
 import { htmlEscapeJsonString } from '../flight-scripts.js';
@@ -100,6 +101,7 @@ interface SsrRenderOptions {
   deferSuspenseFor: number;
   /** Tier 2 global-error.tsx file, if present in app/. */
   globalError?: GlobalErrorFile;
+  slotSkipInfo?: SlotSkipEntry[];
 }
 
 /**
@@ -168,7 +170,7 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   // Skipped when client JS is disabled — no client JS to consume it.
   const segmentScript = clientJsDisabled
     ? ''
-    : `<script>self.__timber_segments=${htmlEscapeJsonString(JSON.stringify(buildSegmentInfo(segments, layoutComponents)))}</script>`;
+    : `<script>self.__timber_segments=${htmlEscapeJsonString(JSON.stringify(buildSegmentInfo(segments, layoutComponents, opts.slotSkipInfo)))}</script>`;
 
   // Embed route params in HTML so useSegmentParams() works on initial hydration.
   // Without this, useSegmentParams() returns {} until the first client navigation.

package/src/server/slot-resolver.ts

@@ -29,6 +29,9 @@ import type { ManifestSegmentNode } from './route-matcher.js';
 import { setSlotParams } from './request-context.js';
 import { coerceSlotParams } from './param-coercion.js';
 import { matchUrlParts } from './tree-match.js';
+import { SegmentOutlet } from '../client/segment-outlet.js';
+import { computeSlotKey, shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
+import { runInTaintScope } from './request-context.js';
 
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
 
@@ -80,7 +83,9 @@ export async function resolveSlotElement(
   match: RouteMatch,
   h: CreateElementFn,
   interception?: InterceptionContext,
-  parentTreePath?: string
+  parentTreePath?: string,
+  accessVerdicts?: SlotAccessVerdict[],
+  taintKey?: 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
@@ -131,9 +136,11 @@ export async function resolveSlotElement(
       if (isClientReference(SlotPage)) {
         element = h(SlotPage, {});
       } else {
+        const slotTaintKey = taintKey;
         const SafeSlotPage = async (props: Record<string, unknown>) => {
+          const run = async () => (SlotPage as (props: Record<string, unknown>) => unknown)(props);
           try {
-            return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
+            return slotTaintKey ? await runInTaintScope(slotTaintKey, run) : await run();
           } catch (error) {
             // RedirectSignal must propagate — the pipeline handles redirects
             // at the top level. Swallowing it here would silently return
@@ -161,7 +168,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);
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h, accessVerdicts);
 
       // Wrap with slot root's layout — INSIDE the access gate, so the layout
       // server component never executes when access.ts denies. See TIM-1074.
@@ -174,7 +181,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);
+      element = await wrapWithAccessGate(slotNode, element, h, accessVerdicts);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -196,7 +203,9 @@ export async function resolveSlotElement(
     }
   }
 
-  // No matching page — render default.tsx fallback
+  // No matching page — render default.tsx fallback.
+  // Per design/02-rendering-pipeline.md: "No access check for default.tsx."
+  // Access verdicts from the eager evaluation are not applied here.
   return renderDefaultFallback(slotNode, h);
 }
 
@@ -221,13 +230,14 @@ export async function resolveSlotElement(
 async function wrapWithIntermediateSegments(
   chain: ManifestSegmentNode[],
   element: React.ReactElement,
-  h: CreateElementFn
+  h: CreateElementFn,
+  accessVerdicts?: SlotAccessVerdict[]
 ): Promise<React.ReactElement> {
   for (let i = chain.length - 1; i > 0; i--) {
     const seg = chain[i];
     element = await wrapSegmentWithErrorBoundaries(seg, element, h);
     element = await wrapWithLayout(seg, element, h);
-    element = await wrapWithAccessGate(seg, element, h);
+    element = await wrapWithAccessGate(seg, element, h, accessVerdicts);
   }
   return element;
 }
@@ -253,7 +263,8 @@ async function wrapWithLayout(
 async function wrapWithAccessGate(
   slotNode: ManifestSegmentNode,
   element: React.ReactElement,
-  h: CreateElementFn
+  h: CreateElementFn,
+  accessVerdicts?: SlotAccessVerdict[]
 ): Promise<React.ReactElement> {
   if (!slotNode.access) return element;
 
@@ -272,6 +283,16 @@ 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,
@@ -279,6 +300,7 @@ async function wrapWithAccessGate(
     createElement: h,
     defaultFallback,
     children: element,
+    verdict: preVerdict?.verdict,
   });
 }
 
@@ -439,3 +461,272 @@ function findInterceptingMatch(
 
   return null;
 }
+
+// ─── 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[]
+): 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 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 {
+  slotKey: string;
+  parentSegmentId: string;
+  /**
+   * Whether the slot's components called request accessors (getHeaders,
+   * getSearchParams, cookies) during their last render. Replaces the
+   * unreliable AsyncFunction heuristic — taint-tracked via ALS.
+   */
+  isRequestDependent: boolean;
+  /** Whether the slot's access.ts denied on this render. */
+  denied: boolean;
+}
+
+interface ResolveSlotPropsArgs {
+  segment: ManifestSegmentNode;
+  segmentId: string;
+  match: RouteMatch;
+  h: CreateElementFn;
+  interception?: InterceptionContext;
+  parentTreePath: string;
+  departingUrl: string | null;
+  destinationUrl: string;
+  clientStateTree: ClientStateTree | null;
+  slotSkipInfo: SlotSkipEntry[];
+}
+
+/**
+ * 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.
+ */
+export async function resolveSlotProps({
+  segment,
+  segmentId,
+  match,
+  h,
+  interception,
+  parentTreePath,
+  departingUrl,
+  destinationUrl,
+  clientStateTree,
+  slotSkipInfo,
+}: ResolveSlotPropsArgs): Promise<Record<string, unknown>> {
+  const slotProps: Record<string, unknown> = {};
+  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;
+
+  // Compute URL parts for slot skip comparison.
+  // Include the owning segment (segIdx + 1) to match findSlotMatch,
+  // which slices at parentIndex + 1. Filter out the root segment
+  // (segmentName === '') — it maps to '/' and doesn't consume a URL part.
+  const segIdx = match.segments.indexOf(segment);
+  const parentSegments =
+    segIdx >= 0 ? match.segments.slice(0, segIdx + 1).filter((s) => s.segmentName !== '') : [];
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const parentConsumedParts = extractUrlParts(parentSegments, rawParams);
+  const sliceAt = parentConsumedParts.length;
+
+  function splitPathname(pathname: string): string[] {
+    return pathname === '/' ? [] : pathname.slice(1).split('/');
+  }
+
+  const destinationAll = splitPathname(destinationPathname);
+  const departingAll = departingPathname ? splitPathname(departingPathname) : null;
+  const destinationParts = destinationAll.slice(sliceAt);
+  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]);
+  }
+
+  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.
+    if (destMatch && parentTreePath && Object.keys(destMatch.params).length > 0) {
+      const slotSuffix = destMatch.chain
+        .map((s) => s.segmentName)
+        .filter(Boolean)
+        .join('/');
+      const prefix = parentTreePath === '/' ? '' : parentTreePath;
+      const fullSlotPath = `${prefix}/${slotSuffix}`;
+      const coerced = coerceSlotParams(destMatch.chain, destMatch.params);
+      setSlotParams(fullSlotPath, coerced);
+    }
+
+    // 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).
+    const hasInterceptingChildren = slotManifest.children.some(
+      (c) => c.segmentType === 'intercepting'
+    );
+    const isSkipCandidate =
+      destMatch !== null &&
+      !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
+      ? await evaluateSlotAccessChain(slotManifest, destMatch!.chain)
+      : [];
+    const accessBlocked = chainVerdicts.some((v) => v.verdict !== 'pass');
+    const canSkip = isSkipCandidate && !accessBlocked;
+
+    if (canSkip) {
+      // Access already ran eagerly (all verdicts 'pass') — principle #3 satisfied.
+      // No gate wrapper needed.
+      slotProps[slotName] = h(SegmentOutlet, {
+        segmentPath: slotKey,
+        skip: true,
+        children: null,
+      });
+      // Skipped slots don't render, so they're not request-dependent.
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: false,
+        denied: false,
+      });
+    } else {
+      const resolvedElement = await resolveSlotElement(
+        slotManifest,
+        match,
+        h,
+        interception,
+        parentTreePath,
+        chainVerdicts,
+        slotKey
+      );
+      slotProps[slotName] = h(SegmentOutlet, {
+        segmentPath: slotKey,
+        children: resolvedElement,
+      });
+      // Conservative default: fully-rendered slots are marked as
+      // request-dependent. Element building doesn't execute server
+      // components (that happens during renderToReadableStream), so
+      // we can't observe whether the page/layout calls getHeaders()
+      // or cookies(). Marking as request-dependent means the client
+      // won't report the slot as cacheable, so it's always re-rendered.
+      // TODO(LOCAL-1127): Implement render-time taint tracking to
+      // allow skipping slots that don't actually read request context.
+      slotSkipInfo.push({
+        slotKey,
+        parentSegmentId: segmentId,
+        isRequestDependent: true,
+        denied: accessBlocked,
+      });
+    }
+  }
+
+  return slotProps;
+}

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

@@ -15,6 +15,8 @@
  */
 
 import { swallow } from './logger.js';
+import { matchUrlParts } from './tree-match.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
 
 // ─── Segment Key Computation ─────────────────────────────────────
 
@@ -59,27 +61,48 @@ export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
   return keys;
 }
 
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export function computeSlotKey(parentSegmentId: string, slotName: string): string {
+  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
+  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
+  return `${prefix}/${name}`;
+}
+
 // ─── State Tree Parsing ──────────────────────────────────────────
 
+/** Parsed client state tree with segment paths and optional slot paths. */
+export interface ClientStateTree extends Set<string> {
+  slots?: Set<string> | null;
+}
+
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
- * Returns a Set of segment paths the client has cached, or null if
+ * Returns a Set of segment paths the client has cached (with an
+ * additional `slots` property for cached slot paths), or null if
  * the header is missing, malformed, or empty. Parsing happens before
  * renderToReadableStream — not inside the React render pass.
  *
- * @returns Set of sync segment paths, or null if no valid state tree
+ * @returns ClientStateTree with segments and slots, or null if no valid state tree
  */
-export function parseClientStateTree(req: Request): Set<string> | null {
+export function parseClientStateTree(req: Request): ClientStateTree | null {
   const header = req.headers.get('X-Timber-State-Tree');
   if (!header) return null;
 
   try {
-    const parsed = JSON.parse(header) as { segments?: unknown };
+    const parsed = JSON.parse(header) as { segments?: unknown; slots?: unknown };
     if (!Array.isArray(parsed.segments) || parsed.segments.length === 0) {
       return null;
     }
-    return new Set(parsed.segments as string[]);
+    const result = new Set(parsed.segments as string[]) as ClientStateTree;
+    result.slots =
+      Array.isArray(parsed.slots) && parsed.slots.length > 0
+        ? new Set(parsed.slots as string[])
+        : null;
+    return result;
   } catch (err) {
     swallow(err, 'malformed X-Timber-State-Tree header');
     return null;
@@ -120,10 +143,83 @@ export function shouldSkipSegment(
   if (!layoutComponent) return false;
   if (isLeaf) return false;
 
-  // Async layouts always re-render — they may depend on per-request data
-  // (cookies, headers, database queries) that changes between navigations.
-  // constructor.name check: AsyncFunction.name === 'AsyncFunction'
+  // Pre-render guard: async layouts may depend on per-request data.
+  // Taint tracking (runInTaintScope) handles the post-render client-side
+  // caching decision via X-Timber-Segments. This server-side check remains
+  // conservative because taint results aren't available at element-build time.
   if (layoutComponent.constructor.name === 'AsyncFunction') return false;
 
   return true;
 }
+
+// ─── 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)
+ *
+ * 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 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;
+}

package/src/server/tree-builder.ts

@@ -180,6 +180,16 @@ 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;
 }
 
 /**

package/dist/_chunks/canonicalize-Du3o_ptW.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonicalize-Du3o_ptW.js","names":[],"sources":["../../src/server/metadata-routes.ts","../../src/server/canonicalize.ts"],"sourcesContent":["/**\n * Metadata route classification for timber.js.\n *\n * Metadata routes are file-based endpoints that generate well-known URLs for\n * crawlers and browsers (sitemap.xml, robots.txt, OG images, etc.).\n *\n * These routes run through proxy.ts but NOT through middleware.ts or access.ts —\n * they are public endpoints by nature.\n *\n * See design/16-metadata.md §\"Metadata Routes\"\n */\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Classification of a metadata route file. */\nexport interface MetadataRouteInfo {\n  /** The metadata route type. */\n  type: MetadataRouteType;\n  /** The content type to serve this route with. */\n  contentType: string;\n  /** Whether this route can appear in nested segments (not just app root). */\n  nestable: boolean;\n}\n\nexport type MetadataRouteType =\n  | 'sitemap'\n  | 'robots'\n  | 'manifest'\n  | 'favicon'\n  | 'icon'\n  | 'opengraph-image'\n  | 'apple-icon';\n\n// ─── Convention Table ────────────────────────────────────────────────────────\n\n/**\n * All recognized metadata route file conventions.\n *\n * Each entry maps a base file name (without extension) to its route info.\n * The extensions determine whether the file is static or dynamic.\n *\n * Static extensions: .xml, .txt, .json, .png, .jpg, .ico, .svg\n * Dynamic extensions: .ts, .tsx\n */\nexport const METADATA_ROUTE_CONVENTIONS: Record<\n  string,\n  {\n    type: MetadataRouteType;\n    contentType: string;\n    nestable: boolean;\n    staticExtensions: string[];\n    dynamicExtensions: string[];\n    /**\n     * The URL path basename this file serves at (relative to segment).\n     * For image routes, the full serve path includes an extension via\n     * `resolveServePathForFile()`.\n     */\n    servePath: string;\n    /**\n     * When set, image routes append `.{serveExtension}` to the serve path.\n     * Dynamic handlers (`.ts`/`.tsx`) use this as the default. Static files\n     * use their own extension instead. Non-image routes leave this undefined.\n     */\n    serveExtension?: string;\n  }\n> = {\n  'sitemap': {\n    type: 'sitemap',\n    contentType: 'application/xml',\n    nestable: true,\n    staticExtensions: ['xml'],\n    dynamicExtensions: ['ts'],\n    servePath: 'sitemap.xml',\n  },\n  'robots': {\n    type: 'robots',\n    contentType: 'text/plain',\n    nestable: false,\n    staticExtensions: ['txt'],\n    dynamicExtensions: ['ts'],\n    servePath: 'robots.txt',\n  },\n  'manifest': {\n    type: 'manifest',\n    contentType: 'application/manifest+json',\n    nestable: false,\n    staticExtensions: ['json'],\n    dynamicExtensions: ['ts'],\n    servePath: 'manifest.webmanifest',\n  },\n  'favicon': {\n    type: 'favicon',\n    contentType: 'image/x-icon',\n    nestable: false,\n    staticExtensions: ['ico'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'favicon.ico',\n  },\n  'icon': {\n    type: 'icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg', 'svg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'icon',\n    serveExtension: 'png',\n  },\n  'opengraph-image': {\n    type: 'opengraph-image',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'opengraph-image',\n    serveExtension: 'png',\n  },\n\n  'apple-icon': {\n    type: 'apple-icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'apple-icon',\n    serveExtension: 'png',\n  },\n};\n\n// ─── MIME Type Resolution ─────────────────────────────────────────────────────\n\n/**\n * Map of file extensions to MIME types for static metadata route files.\n * Used to resolve the generic `image/*` content type for static image files.\n */\nconst EXTENSION_MIME_TYPES: Record<string, string> = {\n  xml: 'application/xml',\n  txt: 'text/plain',\n  json: 'application/json',\n  ico: 'image/x-icon',\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  svg: 'image/svg+xml',\n  webp: 'image/webp',\n};\n\n/**\n * Resolve the concrete MIME type for a static metadata route file.\n *\n * For generic content types like `image/*`, this resolves to the actual\n * MIME type based on the file extension (e.g. `image/png` for `.png`).\n *\n * @param conventionContentType - The content type from the convention table (may be generic like `image/*`)\n * @param extension - The file extension without leading dot (e.g. \"png\", \"xml\")\n * @returns The resolved MIME type\n */\nexport function resolveStaticContentType(conventionContentType: string, extension: string): string {\n  if (conventionContentType.includes('*')) {\n    return EXTENSION_MIME_TYPES[extension] ?? 'application/octet-stream';\n  }\n  return conventionContentType;\n}\n\n/**\n * Check if a file extension represents a static (non-code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"xml\", \"png\", \"ts\")\n * @returns true if this is a static file, false if dynamic or unrecognized\n */\nexport function isStaticMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.staticExtensions.includes(extension);\n}\n\n/**\n * Check if a file extension represents a dynamic (code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"ts\", \"tsx\")\n * @returns true if this is a dynamic file, false if static or unrecognized\n */\nexport function isDynamicMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.dynamicExtensions.includes(extension);\n}\n\n// ─── Classification ──────────────────────────────────────────────────────────\n\n/**\n * Classify a file name as a metadata route, or return null if it's not one.\n *\n * @param fileName - The full file name including extension (e.g. \"sitemap.xml\", \"icon.tsx\")\n * @returns Classification info, or null if not a metadata route\n */\nexport function classifyMetadataRoute(fileName: string): MetadataRouteInfo | null {\n  const dotIndex = fileName.lastIndexOf('.');\n  if (dotIndex === -1) return null;\n\n  const baseName = fileName.slice(0, dotIndex);\n  const ext = fileName.slice(dotIndex + 1);\n\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return null;\n\n  const isStatic = convention.staticExtensions.includes(ext);\n  const isDynamic = convention.dynamicExtensions.includes(ext);\n\n  if (!isStatic && !isDynamic) return null;\n\n  return {\n    type: convention.type,\n    contentType: convention.contentType,\n    nestable: convention.nestable,\n  };\n}\n\n/**\n * Resolve the serve path for a metadata route file.\n *\n * For image routes (icon, opengraph-image, apple-icon), the serve path includes\n * a file extension so CDNs cache correctly:\n * - Dynamic handlers (.ts/.tsx) use the convention's `serveExtension` (default: .png)\n * - Static files use their own extension (e.g., icon.svg → icon.svg)\n *\n * Non-image routes return the convention's `servePath` as-is (already includes\n * extension: sitemap.xml, robots.txt, etc.).\n */\nexport function resolveServePathForFile(baseName: string, filePath: string): string {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return baseName;\n\n  if (!convention.serveExtension) return convention.servePath;\n\n  const ext = filePath.slice(filePath.lastIndexOf('.') + 1);\n  if (convention.staticExtensions.includes(ext)) {\n    return `${convention.servePath}.${ext}`;\n  }\n  return `${convention.servePath}.${convention.serveExtension}`;\n}\n\n/**\n * Get the default serve path for a metadata route type (using default extension\n * for image routes). Used for auto-link generation when only the type is known.\n */\nexport function getMetadataRouteServePath(type: MetadataRouteType): string {\n  for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n    if (convention.type === type) {\n      if (convention.serveExtension) {\n        return `${convention.servePath}.${convention.serveExtension}`;\n      }\n      return convention.servePath;\n    }\n  }\n  throw new Error(`[timber] Unknown metadata route type: ${type}`);\n}\n\n/**\n * All possible serve path segments for metadata routes (includes extension\n * variants for image routes).\n */\nconst METADATA_SERVE_PATHS = new Set<string>();\nfor (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n  if (convention.serveExtension) {\n    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {\n      METADATA_SERVE_PATHS.add(`${convention.servePath}.${ext}`);\n    }\n  } else {\n    METADATA_SERVE_PATHS.add(convention.servePath);\n  }\n}\n\nexport function isMetadataRouteServePath(pathname: string): boolean {\n  let lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);\n  const qIdx = lastSegment.indexOf('?');\n  let query = '';\n  if (qIdx !== -1) {\n    query = lastSegment.slice(qIdx + 1);\n    lastSegment = lastSegment.slice(0, qIdx);\n  }\n  if (!METADATA_SERVE_PATHS.has(lastSegment)) return false;\n  // Vite module requests (e.g., /src/icon.svg?import) use special query params.\n  // These are source assets, not metadata routes.\n  if (/(?:^|&)(?:import|url|raw|worker|inline)(?:&|$)/.test(query)) return false;\n  return true;\n}\n\n/** A <link> auto-link tag. */\nexport interface AutoLinkLink {\n  tag: 'link';\n  rel: string;\n  href: string;\n  type?: string;\n}\n\n/** A <meta> auto-link tag. */\nexport interface AutoLinkMeta {\n  tag: 'meta';\n  property?: string;\n  name?: string;\n  content: string;\n}\n\nexport type AutoLinkTag = AutoLinkLink | AutoLinkMeta;\n\n/**\n * Get the auto-link tags to inject into <head> for metadata route files\n * discovered in a segment.\n *\n * Returns link tags for icon/apple-icon/manifest, and meta tags for\n * opengraph-image (emits both og:image and twitter:image). Returns null\n * for types that don't auto-link (favicon, sitemap, robots).\n *\n * @param type - The metadata route type\n * @param href - The resolved URL path to the metadata route\n * @returns Tag descriptor(s) for the <head>, or null if no auto-link\n */\nexport function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {\n  switch (type) {\n    case 'icon':\n      return [{ tag: 'link', rel: 'icon', href }];\n    case 'apple-icon':\n      return [{ tag: 'link', rel: 'apple-touch-icon', href }];\n    case 'manifest':\n      return [{ tag: 'link', rel: 'manifest', href }];\n    case 'opengraph-image':\n      return [\n        { tag: 'meta', property: 'og:image', content: href },\n        { tag: 'meta', name: 'twitter:image', content: href },\n      ];\n    default:\n      return [];\n  }\n}\n","/**\n * URL canonicalization — runs once at the request boundary.\n *\n * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same\n * canonical path. No re-decoding occurs at any later stage.\n *\n * See design/07-routing.md §\"URL Canonicalization & Security\"\n */\n\n/** Result of canonicalization — either a clean path or a rejection. */\nexport type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; status: 400 };\n\n/**\n * Encoded separators that produce a 400 rejection.\n * %2f (/) and %5c (\\) cause path-confusion attacks.\n *\n * Shared between the runtime canonicalizer and the build-time route scanner\n * to ensure both enforce identical security rules. See design/13-security.md.\n */\nexport const ENCODED_SEPARATOR_RE = /%2f|%5c/i;\n\n/** Null byte — rejected. Shared with the route scanner. */\nexport const NULL_BYTE_RE = /%00/i;\n\n/**\n * Canonicalize a URL pathname.\n *\n * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)\n * 2. Single percent-decode\n * 3. Collapse // → /\n * 4. Resolve .. segments (reject if escaping root)\n * 5. Strip trailing slash (except root \"/\")\n *\n * @param rawPathname - The raw pathname from the request URL (percent-encoded)\n * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.\n */\nexport function canonicalize(rawPathname: string, stripTrailingSlash = true): CanonicalizeResult {\n  // Step 1: Reject dangerous encoded sequences BEFORE decoding.\n  // This must happen on the raw input so %252f doesn't bypass after a single decode.\n  if (ENCODED_SEPARATOR_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n  if (NULL_BYTE_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n\n  // Step 2: Single percent-decode.\n  // Double-encoded input (%2561 → %61) stays as %61 — not decoded again.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(rawPathname);\n  } catch {\n    // Malformed percent-encoding → 400\n    return { ok: false, status: 400 };\n  }\n\n  // Reject null bytes that appeared after decoding (from valid %00-like sequences\n  // that weren't caught above — belt and suspenders).\n  if (decoded.includes('\\0')) {\n    return { ok: false, status: 400 };\n  }\n\n  // Backslash is NOT a path separator — keep as literal character.\n  // But reject if it would create // after normalization (e.g., /\\evil.com).\n  // We do NOT convert \\ to / — it stays as a literal.\n\n  // Step 3: Collapse consecutive slashes.\n  let pathname = decoded.replace(/\\/\\/+/g, '/');\n\n  // Step 4: Resolve .. and . segments.\n  const segments = pathname.split('/');\n  const resolved: string[] = [];\n  for (const seg of segments) {\n    if (seg === '..') {\n      if (resolved.length <= 1) {\n        // Trying to escape root — 400\n        return { ok: false, status: 400 };\n      }\n      resolved.pop();\n    } else if (seg !== '.') {\n      resolved.push(seg);\n    }\n  }\n\n  pathname = resolved.join('/') || '/';\n\n  // Step 5: Strip trailing slash (except root \"/\").\n  if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith('/')) {\n    pathname = pathname.slice(0, -1);\n  }\n\n  return { ok: true, pathname };\n}\n"],"mappings":"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"}