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

package/src/search-params/wrappers.ts

@@ -15,14 +15,32 @@ import type {
   SearchParamField,
 } from './define.js';
 import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
+import { parseTotal } from './parse-total.js';
 
 // ---------------------------------------------------------------------------
 // withDefault
 // ---------------------------------------------------------------------------
 
 /**
- * Wrap a nullable codec with a default value. When the inner codec returns
- * null, the default is used instead. The output type becomes non-nullable.
+ * Wrap a nullable codec with a default value. The output type becomes
+ * non-nullable, and the wrapper is TOTAL over `string | string[] |
+ * undefined` even when the inner codec is not.
+ *
+ * The default is substituted for `null` — the documented "no value"
+ * answer — and for `undefined`, which is what an implicitly-optional
+ * Standard Schema field and a bare `parseAsString` produce for an absent
+ * param. Substituting only for `null` left a field typed non-nullable
+ * `string` holding `undefined` (TIM-1350).
+ *
+ * The inner codec is invoked through `parseTotal`, so a nuqs parser gets
+ * its own normalization (absent → null, repeated → first value, inner
+ * throw → null) before either check applies. That is what makes
+ * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT
+ * catch. A throw from a codec is a deliberate signal — `fromSchema` throws
+ * on an async schema, and an app codec may `redirect()` or `notFound()` on
+ * a value it refuses — and swallowing it would convert a loud failure into
+ * a permanently-default field. design/09 §"The SearchParamCodec Protocol":
+ * a codec that throws bubbles as a render-phase error, by design.
  *
  * Works with any codec — nuqs parsers, custom codecs, fromSchema results.
  *
@@ -34,20 +52,35 @@ import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
  * // page.parse(undefined) → 1 (not null)
  * // page.parse('5') → 5
  * ```
+ *
+ * The signature strips BOTH nullish constituents from the result, not just
+ * `null`, because the runtime substitutes for both. An implicitly-optional
+ * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it
+ * used to yield `SearchParamCodec<string | undefined>` — a field the
+ * wrapper guarantees is always present, still typed as maybe-absent.
  */
 export function withDefault<T>(
-  codec: SearchParamCodec<T | null>,
-  defaultValue: T
-): SearchParamCodec<T> {
-  return {
-    parse(value: string | string[] | undefined): T {
-      const result = codec.parse(value);
-      return result === null ? defaultValue : result;
+  codec: SearchParamCodec<T | null | undefined>,
+  defaultValue: NonNullable<T>
+): SearchParamCodec<NonNullable<T>> {
+  // A wrapper that rebuilds a codec from two methods drops everything else
+  // the codec carries. `withUrlKey` lost `parseServerSide` that way; this
+  // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`
+  // silently read `?page=` instead of `?p=`. Carry it explicitly rather
+  // than spreading: this wrapper's own `parse` IS the total entry point,
+  // and re-publishing the inner `parseServerSide` would let `parseTotal`
+  // reach past it and skip the default entirely.
+  const wrapped: SearchParamCodec<NonNullable<T>> = {
+    parse(value: string | string[] | undefined): NonNullable<T> {
+      const result = parseTotal(codec, value);
+      return result === null || result === undefined ? defaultValue : result;
     },
-    serialize(value: T): string | null {
+    serialize(value: NonNullable<T>): string | null {
       return codec.serialize(value);
     },
   };
+  if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;
+  return wrapped;
 }
 
 // ---------------------------------------------------------------------------
@@ -93,9 +126,25 @@ export function withUrlKey<F extends SearchParamField>(
     : isStandardSchema(codecOrSchema)
       ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)
       : (codecOrSchema as SearchParamCodec<T>);
-  return {
+  // Carry the total entry point, bound like the other two methods. A
+  // codec's totality lives in a THIRD property, `parseServerSide` (see
+  // parse-total.ts); picking only `parse`/`serialize` silently produced a
+  // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an
+  // absent param while the bare parser did not (TIM-1350).
+  //
+  // Bound explicitly rather than spread: a spread copies own enumerable
+  // properties only, so a class-based codec — whose `parse` and
+  // `serialize` this wrapper already reaches through the prototype —
+  // would have kept its methods and lost exactly the one that makes it
+  // total. Three properties, one rule, no dependence on how the inner
+  // codec was constructed.
+  const wrapped: SearchParamCodecWithUrlKey<T> = {
     parse: codec.parse.bind(codec),
     serialize: codec.serialize.bind(codec),
     urlKey,
   };
+  if (typeof codec.parseServerSide === 'function') {
+    wrapped.parseServerSide = codec.parseServerSide.bind(codec);
+  }
+  return wrapped;
 }

package/src/server/access-gate.tsx

@@ -18,7 +18,7 @@ import type { AccessGateProps, SlotAccessGateProps } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
 import type { DenyPageEntry } from './deny-boundary.js';
-import { renderMatchingDenyPage, setDenyStatus } from './deny-boundary.js';
+import { handleCaughtDeny, setFirstDeniedSegmentIndex } from './deny-boundary.js';
 import type { ReactNode } from 'react';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
@@ -26,50 +26,64 @@ import type { ReactNode } from 'react';
 /**
  * Framework-injected access gate for segments.
  *
- * When a pre-computed `verdict` prop is provided (from the pre-render pass
- * in route-element-builder.ts), AccessGate replays it synchronously — no
- * async, no re-execution of access.ts, immune to Suspense timing. The OTEL
- * span was already emitted during the pre-render pass.
- *
- * When no verdict is provided (backward compat with tree-builder.ts),
- * AccessGate calls accessFn directly with OTEL instrumentation.
+ * Calls accessFn during render — inside `renderToReadableStream`, sharing
+ * the same `React.cache` scope as layouts and pages. A `requireUser()`
+ * call in access.ts populates the cache; the same call in any layout is
+ * a free hit. Access executes exactly once per request. See TIM-1363.
  *
  * access.ts is a pure gate — return values are discarded. The layout below
  * gets the same data by calling the same cached functions (React.cache dedup).
+ *
+ * On denial the gate renders the matching deny page only when this segment
+ * owns it. Because the gate is wrapped OUTSIDE its own layout, that render
+ * omits the denying segment's layout — deliberate, and the one place the
+ * in-tree path diverges from `renderDenyPage`'s inclusive slice: a layout
+ * whose access.ts denied must never run and serialize protected data into
+ * the Flight stream (TIM-1074). An ancestor-owned page is hoisted instead,
+ * because the gate also sits inside every layout above it and rendering
+ * here would wrap the deny page in all of them (TIM-1356).
+ *
+ * For skipped segments (skippedSegment=true), deny pages are NOT rendered
+ * in-tree — the client's cached layout chrome would wrap them incorrectly.
+ * Instead, the deny is recorded in ALS and rethrown so the response path
+ * can return rscErrorEnvelope for a client hard-navigate.
  */
-export function AccessGate(props: AccessGateProps): ReactNode | Promise<ReactNode> {
-  const { accessFn, segmentName, verdict, denyPages, children } = props;
-
-  // Fast path: replay pre-computed verdict from the pre-render pass.
-  if (verdict !== undefined) {
-    if (verdict === 'pass') {
-      return children;
-    }
-    // Render deny page in-tree when possible (same as the fallback path).
-    if (verdict instanceof DenySignal && denyPages) {
-      const denyElement = renderMatchingDenyPage(denyPages, verdict.status, verdict.data);
-      if (denyElement) {
-        setDenyStatus(verdict.status);
-        return denyElement;
-      }
-    }
-    throw verdict;
-  }
+export function AccessGate(props: AccessGateProps): Promise<ReactNode> {
+  const {
+    accessFn,
+    segmentName,
+    segmentKey,
+    segmentIndex,
+    denyPages,
+    skippedSegment,
+    onSettled,
+    children,
+  } = props;
 
-  // Primary path: call accessFn directly during render.
-  // If denyPages is provided, catch DenySignal and render the deny page
-  // in-tree — no throw reaches React Flight, no second render pass.
-  return accessGateFallback(accessFn, segmentName, denyPages, children);
+  return accessGateFallback(
+    accessFn,
+    segmentName,
+    segmentKey,
+    segmentIndex,
+    skippedSegment ? undefined : denyPages,
+    skippedSegment,
+    onSettled,
+    children
+  );
 }
 
 /**
- * Async fallback for AccessGate when no pre-computed verdict is available.
- * Calls accessFn with OTEL instrumentation.
+ * Calls accessFn during render with OTEL instrumentation.
+ * Records the first denied segment index in ALS for post-render consumers.
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
   segmentName: AccessGateProps['segmentName'],
+  segmentKey: AccessGateProps['segmentKey'],
+  segmentIndex: AccessGateProps['segmentIndex'],
   denyPages: DenyPageEntry[] | undefined,
+  skippedSegment: boolean | undefined,
+  onSettled: (() => void) | undefined,
   children: ReactNode
 ): Promise<ReactNode> {
   try {
@@ -91,17 +105,23 @@ async function accessGateFallback(
       }
     });
   } catch (error: unknown) {
-    // Catch DenySignal and render the deny page in-tree.
-    // No throw reaches React Flight — clean stream, single render pass.
-    // RedirectSignal and other errors propagate normally.
-    if (error instanceof DenySignal && denyPages) {
-      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
-      if (denyElement) {
-        setDenyStatus(error.status);
-        return denyElement;
+    if (error instanceof DenySignal) {
+      if (segmentIndex !== undefined) {
+        setFirstDeniedSegmentIndex(segmentIndex);
+      }
+
+      if (skippedSegment) {
+        error._hardNavigate = true;
+        throw error;
+      }
+
+      if (denyPages) {
+        return handleCaughtDeny(denyPages, error, segmentKey);
       }
     }
     throw error;
+  } finally {
+    onSettled?.();
   }
 
   return children;
@@ -124,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;
-
-  // 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
-    );
-  }
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
-  // Fallback path: call accessFn during render (no pre-computed verdict).
   try {
     await accessFn();
   } catch (error: unknown) {

package/src/server/action-handler.ts

@@ -36,6 +36,7 @@ import {
 import type { FormFlashData } from './form-flash.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { logActionError } from './logger.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -55,10 +56,6 @@ export interface ActionDispatchConfig {
   sensitiveFields?: SensitiveFieldsOption;
 }
 
-// ─── Constants ────────────────────────────────────────────────────────────
-
-const RSC_CONTENT_TYPE = 'text/x-component';
-
 // ─── Detection ────────────────────────────────────────────────────────────
 
 /**

package/src/server/als-registry.ts

@@ -141,6 +141,22 @@ export interface RequestContextStore {
    * context for render-phase errors without module-level shared state.
    */
   debugComponentsGetter?: () => DebugComponentEntry[];
+  /**
+   * Index of the first segment whose AccessGate denied during render.
+   * Recorded by AccessGate when it catches a DenySignal so post-render
+   * consumers (buildSegmentInfo, X-Timber-Segments header) can bound
+   * the segment list without a pre-render access pass. Infinity when
+   * no segment denied. See TIM-1363.
+   */
+  _firstDeniedSegmentIndex?: number;
+  /**
+   * Metadata entries collected during render by MetadataCollector.
+   * Populated per-segment in tree order (root→page) during
+   * renderToReadableStream. MetadataHead reads all entries,
+   * merges them, and renders Float-hoisted head elements.
+   * See TIM-1363, design/16-metadata.md.
+   */
+  _metadataEntries?: import('./metadata.js').SegmentMetadataEntry[];
 }
 
 /** A single outgoing cookie entry in the cookie jar. */

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/compress.ts

@@ -7,6 +7,14 @@
 // this module is only used on Node.js/Bun.
 //
 // See design/25-production-deployments.md.
+//
+// This module is also emitted standalone as `_compress.mjs` by
+// `adapters/compress-module.ts`, which strips types but does not bundle. Its
+// imports must therefore be interpolated there — a new import that is not
+// fails the build with an explanatory error rather than resolving to nothing
+// on the deployed server.
+
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -21,7 +29,7 @@ export const COMPRESSIBLE_TYPES = new Set([
   'text/plain',
   'text/xml',
   'text/javascript',
-  'text/x-component',
+  RSC_CONTENT_TYPE,
   'application/json',
   'application/javascript',
   'application/xml',