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

package/src/search-params/define.ts

@@ -14,35 +14,12 @@ import { useQueryStates as clientUseQueryStates } from '../client/use-query-stat
 import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 import type { Codec } from '../codec.js';
-
-// Server-only reference for .get() — avoids pulling server ALS into client bundles.
-// In client environments, .get() throws before reaching this code path.
-//
-// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup
-// (called from request-context.ts module initialization). It must NOT use
-// dynamic `await import()` at call time because the async microtask from the
-// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
-// breaking getSearchParams() in parallel slot pages. See TIM-523.
-let _getSearchParamsFn: (() => URLSearchParams) | undefined;
-
-/**
- * Register the getSearchParams function. Called once at module load time
- * from request-context.ts to avoid dynamic import at call time.
- * @internal
- */
-export function _setGetSearchParamsFn(fn: () => URLSearchParams): void {
-  _getSearchParamsFn = fn;
-}
-
-function getSearchParamsFromAls(): URLSearchParams {
-  if (!_getSearchParamsFn) {
-    throw new Error(
-      '[timber] searchParams.get() is only available on the server. ' +
-        'Use searchParams.useQueryStates() on the client.'
-    );
-  }
-  return _getSearchParamsFn();
-}
+// Server-only reference for .get() — avoids pulling server ALS into client
+// bundles. In client environments, .get() throws before reaching this code
+// path. The slot lives in its own leaf module so that `request-context.ts`
+// can register the getter without importing this file, which would drag
+// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.
+import { getSearchParamsFromAls } from '../shared/als-slots.js';
 
 // ---------------------------------------------------------------------------
 // Types

package/src/segment-params/define.ts

@@ -16,33 +16,10 @@
 import type { Codec } from '../codec.js';
 import { type StandardSchemaV1, resolveCodecOrSchema } from '../schema-bridge.js';
 import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
-
-// ---------------------------------------------------------------------------
-// Server-only ALS reference for .get()
-// ---------------------------------------------------------------------------
-
-// Same pattern as search-params: eagerly registered at server startup
-// to avoid dynamic imports that lose ALS context. See TIM-523.
-let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
-
-/**
- * Register the getSegmentParams function. Called once at module load time
- * from request-context.ts to avoid dynamic import at call time.
- * @internal
- */
-export function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {
-  _getSegmentParamsFn = fn;
-}
-
-function getSegmentParamsFromAls(): Record<string, string | string[]> {
-  if (!_getSegmentParamsFn) {
-    throw new Error(
-      '[timber] segmentParams.get() is only available on the server. ' +
-        'Use segmentParams.useSegmentParams() on the client.'
-    );
-  }
-  return _getSegmentParamsFn();
-}
+// Server-only ALS reference for .get(), eagerly registered at server startup
+// from a leaf module so this file stays out of the server graph. Same slot
+// mechanism as search-params. See shared/als-slots.ts, TIM-523, TIM-1298.
+import { getSegmentParamsFromAls } from '../shared/als-slots.js';
 
 // ---------------------------------------------------------------------------
 // Types

package/src/server/action-handler.ts

@@ -296,7 +296,9 @@ async function handleRscAction(
     // serialized together so React Flight handles both in one stream.
     payload = {
       _action: result.actionResult,
-      _tree: result.revalidation.element,
+      // The payload root, not a bare tree: it carries the revalidated
+      // route's params too, and the client publishes them (TIM-1297).
+      _tree: result.revalidation.payload,
     };
     headers['X-Timber-Revalidation'] = '1';
     // Metadata (<title>/<meta>/<link>) now rides the revalidation element

package/src/server/actions.ts

@@ -20,10 +20,13 @@ import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
 // ─── Types ───────────────────────────────────────────────────────────────
 
-/** Result of rendering a revalidation — element tree before RSC serialization. */
+/** Result of rendering a revalidation — payload root before RSC serialization. */
 export interface RevalidationResult {
-  /** React element tree (pre-serialization — passed to renderToReadableStream). */
-  element: unknown;
+  /**
+   * The payload root — tree plus the params it rendered with, exactly as an
+   * ordinary route payload. The client splits it in `applyRevalidation`.
+   */
+  payload: unknown;
 }
 
 /** Renderer function that builds a React element tree for a given path. */

package/src/server/als-registry.ts

@@ -32,6 +32,7 @@
  */
 
 import '#server-only-guard';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
@@ -113,7 +114,7 @@ export interface RequestContextStore {
    *
    * See design/07-routing.md §"Parallel Slot Params"
    */
-  slotParamsMap?: Map<string, Record<string, string | string[]>>;
+  slotParams?: SlotParamsRecord;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */

package/src/server/build-manifest.ts

@@ -49,13 +49,26 @@ export interface BuildManifest {
   requestDep?: Record<string, boolean>;
 }
 
-/** Empty build manifest used in dev mode. */
+/**
+ * Empty build manifest used in dev mode, and the single source of truth for
+ * what an empty manifest contains.
+ *
+ * `virtual:timber-build-manifest` serializes this constant into its generated
+ * source rather than restating it — one literal for the dev module, one for the
+ * production module's `globalThis.__TIMBER_BUILD_MANIFEST__ ?? …` fallback.
+ * They were three hand-written objects that had already drifted: this one and
+ * the dev literal were missing `requestDep` while the production fallback had
+ * it, so a reader who grepped the built bundle for `requestDep` found the one
+ * copy that mentioned it and read the fallback as the shipped map (TIM-1300).
+ * A field added here now reaches every copy.
+ */
 export const EMPTY_BUILD_MANIFEST: BuildManifest = {
   css: {},
   js: {},
   modulepreload: {},
   fonts: {},
   metadataRouteHashes: {},
+  requestDep: {},
 };
 
 /** Segment shape expected by collectRouteCss (matches ManifestSegmentNode). */

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

@@ -0,0 +1,163 @@
+/**
+ * How much of the URL a matched segment chain has consumed.
+ *
+ * One question — "which URL parts had been consumed by the time segment `i`
+ * rendered?" — asked by four things that must all agree:
+ *
+ * - 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.
+ *
+ * They were four separate `extractUrlParts(...).length` calls. That was fine
+ * while the answer was a plain walk, and stopped being fine when interception
+ * gave it a second term (TIM-1280): the fix landed on the layout depth alone
+ * and the other three kept the old walk, so a layout and the slots beside it
+ * disagreed about how deep they were. Hence one function, in its own module,
+ * rather than a helper on the side of whichever caller was fixed first.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { RouteMatch } from './pipeline.js';
+import { effectiveUrlSegment } from '../routing/segment-classify.js';
+import { computeInterceptedBase } from '../routing/interception.js';
+
+/**
+ * Extract raw URL path parts from a segment chain.
+ *
+ * Each dynamic segment consumed one URL part (its param value). Static
+ * segments consumed their own name. Groups are transparent. Catch-all segments
+ * consumed multiple parts (their param value is `string[]`).
+ *
+ * The root segment is named '' and consumes nothing, so it is skipped here
+ * rather than by each caller — callers that pass a chain including the root
+ * (interception anchoring, slot-skip slicing) would otherwise have to remember
+ * to filter it, and one that forgot would push an empty part and shift every
+ * subsequent index by one.
+ *
+ * Uses rawSegmentParams (pre-coercion) to get actual URL strings. Values are
+ * coerced to `String()` defensively in case a codec leaked a non-string value
+ * into the params map.
+ *
+ * Each node is read through `effectiveUrlSegment`, so an intercepting
+ * directory contributes the URL part it intercepts (`(.)item` → `item`,
+ * `(.)[id]` → the bound value). A children-path interception puts such a node
+ * in the *main* chain, and reading it directly would classify it as neither
+ * static nor param-bearing — it would contribute nothing, and every part after
+ * it would shift by one.
+ */
+export function extractUrlParts(
+  segments: ManifestSegmentNode[],
+  mainParams: Record<string, string | string[]>
+): string[] {
+  const parts: string[] = [];
+  for (const node of segments) {
+    const seg = effectiveUrlSegment(node);
+    // The root's *directory* name is empty; read it off the node, since an
+    // intercepting node's effective name is the one it intercepts.
+    if (seg.segmentType === 'group') continue;
+    if (node.segmentName === '') continue;
+    if (seg.segmentType === 'static') {
+      parts.push(seg.segmentName);
+    } else if (seg.paramName) {
+      const value = mainParams[seg.paramName];
+      if (Array.isArray(value)) {
+        parts.push(...value.map(String));
+      } else if (value !== undefined) {
+        // Reconstruct the original URL part for affixed segments.
+        // The param value is the stripped middle (e.g. "123" for [id].png
+        // matching "123.png"), so we re-attach prefix/suffix so that slot
+        // matching through matchUrlParts sees the original part.
+        const prefix = seg.paramPrefix ?? '';
+        const suffix = seg.paramSuffix ?? '';
+        parts.push(prefix + String(value) + suffix);
+      }
+    }
+  }
+  return parts;
+}
+
+/**
+ * Where a children-path interception sits in the target pathname, or null when
+ * the chain contains none.
+ *
+ * `anchor` is the intercepted base's length — the URL index the intercepting
+ * node occupies — from the same `computeInterceptedBase` that rewrite
+ * generation and the slot resolver both go through, so the three cannot
+ * disagree about which part a marker points at.
+ */
+function interceptionAnchor(
+  segments: ManifestSegmentNode[]
+): { index: number; anchor: number } | null {
+  const index = segments.findIndex((s) => s.segmentType === 'intercepting');
+  if (index <= 0) return null;
+
+  const owner = segments[index - 1];
+  const base = computeInterceptedBase(owner.urlPath, segments[index].interceptionMarker ?? '(.)');
+  return { index, anchor: base === '/' ? 0 : base.slice(1).split('/').length };
+}
+
+/**
+ * The URL parts the chain has consumed through `index`, inclusive.
+ *
+ * For an ordinary chain this is just the walk. Two things make it more than
+ * that, and both are cases where a node stands for a different number of URL
+ * parts than itself:
+ *
+ * - A **catch-all** consumes as many parts as the request supplies, which the
+ *   walk already handles (its param value is an array).
+ * - An **interception with a climbing marker** intercepts a URL that starts
+ *   *above* its owner, so the owner's own URL segment — and any static
+ *   ancestor between the intercepted base and the owner — is not in the target
+ *   at all. `feed/(..)photo/[id]` at `/photo/42` still has `feed` in the
+ *   chain, and counting it puts everything after it off by one.
+ *
+ * So everything above the interception clamps to the anchor, and everything
+ * from it down counts forward from there. The owner chain is param-free by
+ * build-time rule and the intercepted base is a prefix of the owner's
+ * `urlPath`, so the target's leading `anchor` parts *are* the owner chain's
+ * leading `anchor` parts — which is what makes the clamped prefix real values
+ * rather than placeholders. For `(.)` the base is the owner's own path, so the
+ * clamp is a no-op and this reduces to the plain walk.
+ */
+export function consumedUrlParts(
+  segments: ManifestSegmentNode[],
+  index: number,
+  match: RouteMatch
+): string[] {
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const partsThrough = (from: number, to: number) =>
+    extractUrlParts(segments.slice(from, to + 1), rawParams);
+
+  const interception = interceptionAnchor(segments);
+  if (!interception) return partsThrough(0, index);
+
+  const targetPrefix = partsThrough(0, interception.index - 1).slice(0, interception.anchor);
+
+  if (index < interception.index) {
+    // Above the interception: an ancestor is never deeper than the anchor.
+    return targetPrefix.slice(0, Math.min(partsThrough(0, index).length, interception.anchor));
+  }
+  // At or below it: the intercepting subtree's parts ARE the target's.
+  return [...targetPrefix, ...partsThrough(interception.index, index)];
+}
+
+/**
+ * The index in `match.segments` of a segment, or -1.
+ *
+ * Split out so the three slot call sites and the layout-depth one derive their
+ * slice point identically — `indexOf` plus `consumedUrlParts` — instead of
+ * each inlining the pair.
+ */
+export function consumedPartsThroughSegment(
+  segment: ManifestSegmentNode,
+  match: RouteMatch
+): string[] {
+  const index = match.segments.indexOf(segment);
+  if (index < 0) return [];
+  return consumedUrlParts(match.segments as ManifestSegmentNode[], index, match);
+}

package/src/server/children-interception.ts

@@ -0,0 +1,115 @@
+/**
+ * Children-path interception — the sibling layout swap (TIM-1280).
+ *
+ * The second shape interception has. An intercepting directory that is a
+ * direct child of an ordinary segment or route group renders *in place of*
+ * `children` for that directory's own layout chain:
+ *
+ * ```
+ * app/(landing)/layout.tsx
+ * app/(landing)/[artistSlug]/[year]/[month]/[day]/page.tsx      ← hard nav
+ * app/(browse)/layout.tsx
+ * app/(browse)/(...)[artistSlug]/[year]/[month]/[day]/page.tsx  ← soft nav from (browse)
+ * ```
+ *
+ * There is no overlay, no slot, and no `default.tsx`. Nothing is re-matched
+ * either — and that is the point. The modal shape re-matches
+ * `interceptingPrefix`, a URL, and route groups contribute nothing to a URL,
+ * so an owner like `app/(browse)/` serializes to "/" and re-matching it
+ * resolves through whichever group owns the canonical page. This resolver
+ * addresses the owner by **tree path** instead, which never collapses.
+ *
+ * The result is an ordinary `RouteMatch` whose chain runs
+ * `[…owner ancestors, interceptingNode, …its matched descendants]`. Every
+ * consumer downstream — `tree-builder.ts`, the element builder, access gates,
+ * middleware — sees a segment chain and needs to know nothing about
+ * interception. That is why this feature adds no rendering path: the chain
+ * *is* the feature.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+
+import type { RouteMatch } from './pipeline.js';
+import { collectMiddlewareChain, type ManifestSegmentNode } from './route-matcher.js';
+import { findInterceptingMatch } from './slot-interception.js';
+import { treePathNames } from '../routing/segment-keys.js';
+
+/**
+ * Resolve a children-path interception to a complete route match.
+ *
+ * `interceptingScope` is the rewrite's own build-time field — the tree path of
+ * the directory that owns the interception. The pipeline has already
+ * established that the client's rendered tree passes through it; this
+ * translates it into the chain to render.
+ *
+ * Returns null when the scope names no directory in this manifest, or when no
+ * intercepting child of that directory matches the target. Both are fail-safe:
+ * the caller keeps the canonical target match, so the page the user gets is
+ * the one a hard navigation would have produced.
+ */
+export type InterceptedRouteMatcher = (
+  targetPathname: string,
+  interceptingScope: string
+) => RouteMatch | null;
+
+/** Build a children-path interception resolver over a runtime manifest. */
+export function createInterceptedRouteMatcher(root: ManifestSegmentNode): InterceptedRouteMatcher {
+  return (targetPathname, interceptingScope) => {
+    const ancestors = findChainByTreePath(root, interceptingScope);
+    if (!ancestors) return null;
+
+    const owner = ancestors[ancestors.length - 1];
+    // The same resolver the slot path uses. It takes an arbitrary node, buckets
+    // its intercepting children by the URL index their marker anchors them to,
+    // and walks each bucket with the shared tree walker — so marker depth,
+    // static-before-dynamic sibling ordering and catch-all handling are one
+    // implementation across both shapes rather than two that must agree.
+    const result = findInterceptingMatch(owner, targetPathname);
+    if (!result) return null;
+
+    // `result.chain` is [owner, interceptingNode, …descendants]; splice the
+    // owner's own ancestry in front of it to get a root-anchored chain.
+    const segments = [...ancestors, ...result.chain.slice(1)];
+
+    return {
+      segments,
+      // Every segment above the intercepting node is static or a route group —
+      // `validateInterceptionPlacement` rejects a dynamic one at build time,
+      // precisely because the intercepted URL carries no value to bind it
+      // with. So the intercepting subtree's params are the whole record.
+      segmentParams: result.slotParams,
+      middlewareChain: collectMiddlewareChain(segments),
+    };
+  };
+}
+
+/**
+ * Find the chain from the root to the segment with this tree path.
+ *
+ * Tree paths are `computeSegmentTreePaths` — the directory path with slots
+ * elided — so this walks `children` only, which is also exactly the set of
+ * positions a children-path interception can own: an intercepting directory
+ * inside a slot subtree is rejected at build time unless it is a direct slot
+ * child, and that shape is the modal one.
+ *
+ * Sibling directories cannot share a name, so a tree path names at most one
+ * node and the walk needs no tie-break. This is the property `urlPath` and
+ * `computeSegmentKeys` both lack — see the note on `computeSegmentTreePaths`.
+ */
+function findChainByTreePath(
+  root: ManifestSegmentNode,
+  treePath: string
+): ManifestSegmentNode[] | null {
+  const names = treePathNames(treePath);
+  const chain: ManifestSegmentNode[] = [root];
+  let node = root;
+
+  for (const name of names) {
+    const next = node.children.find((child) => child.segmentName === name);
+    if (!next) return null;
+    chain.push(next);
+    node = next;
+  }
+
+  return chain;
+}

package/src/server/default-status-page.ts

@@ -0,0 +1,127 @@
+/**
+ * Framework default status page — the terminal fallback of the deny chain.
+ *
+ * design/10-error-handling.md §"Fallback Chain" ends every 4xx/5xx chain in a
+ * "framework default page". Before TIM-1258 that terminal did not exist: an app
+ * with no `404.tsx` / `4xx.tsx` / `error.tsx` got `Response(null, { status })` —
+ * a correct status code with an empty body. Browsers render that as a blank
+ * page, and static generation had nothing to write to `404.html`.
+ *
+ * This page is a plain HTML string rather than a React component on purpose:
+ * it is the *last* fallback, so it must not depend on the RSC → SSR pipeline
+ * (the machinery that may already have failed by the time we get here), and it
+ * must be renderable from the static build where no render environment exists.
+ * One builder is the single source of truth for both surfaces.
+ *
+ * Security: the page interpolates nothing but the status code, and the code is
+ * clamped to a plain integer before it reaches the markup. No request URL, no
+ * error message, no stack — see design/13-security.md principle 4.
+ */
+
+/**
+ * Canonical reason phrases (RFC 9110 §15) for the statuses an app is likely to
+ * `deny()` with. Anything else falls back to a generic category phrase — the
+ * phrase is decoration, never a place to echo caller-supplied text.
+ */
+const REASON_PHRASES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  413: 'Content Too Large',
+  415: 'Unsupported Media Type',
+  418: "I'm a Teapot",
+  422: 'Unprocessable Content',
+  429: 'Too Many Requests',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+};
+
+/** HTML content type used for every framework default page response. */
+export const DEFAULT_STATUS_PAGE_CONTENT_TYPE = 'text/html; charset=utf-8';
+
+/**
+ * Coerce a status into something safe to put in markup.
+ *
+ * `DenySignal.status` is typed `number` but nothing validates it at
+ * construction, and JS callers can hand us anything. Rather than escaping a
+ * value that should never have been a string, collapse non-integers to 500 —
+ * the page is decoration for a status already on the wire.
+ */
+function displayStatus(status: number): number {
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? status : 500;
+}
+
+/** Human-readable phrase for a status code. Never caller-supplied text. */
+export function statusReasonPhrase(status: number): string {
+  const code = displayStatus(status);
+  if (REASON_PHRASES[code]) return REASON_PHRASES[code];
+  return code >= 500 ? 'Server Error' : 'Request Error';
+}
+
+/**
+ * Build the framework default page for a status code as a full HTML document.
+ *
+ * The document is self-contained: no scripts, no external resources, no client
+ * JavaScript. It renders identically in `server` mode, in `static` mode's
+ * generated `404.html`, and with `clientJavascript: false`.
+ */
+export function defaultStatusPageHtml(status: number): string {
+  const code = displayStatus(status);
+  const phrase = statusReasonPhrase(code);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${code} ${phrase}</title>
+<style>
+:root { color-scheme: light dark; --fg: #1a1a1a; --muted: #6b6b76; --bg: #ffffff; }
+@media (prefers-color-scheme: dark) { :root { --fg: #ededf1; --muted: #9b9baa; --bg: #111114; } }
+html, body { height: 100%; margin: 0; }
+body {
+  display: flex; align-items: center; justify-content: center;
+  background: var(--bg); color: var(--fg);
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  text-align: center; padding: 2rem;
+}
+h1 { font-size: 3rem; font-weight: 600; margin: 0; letter-spacing: -0.02em; }
+p { margin: 0.5rem 0 0; color: var(--muted); font-size: 1rem; }
+</style>
+</head>
+<body>
+<main>
+<h1>${code}</h1>
+<p>${phrase}</p>
+</main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Build the framework default page as an HTTP `Response`.
+ *
+ * `responseHeaders` carries whatever middleware/proxy already set (cookies,
+ * cache directives); the content type is overwritten because the body is
+ * always HTML regardless of what the route would have produced.
+ *
+ * The body is unconditional. HEAD is not this function's problem: the pipeline
+ * strips HEAD bodies at its single exit for every response shape, so a
+ * `method` parameter here would be one renderer's private copy of a rule that
+ * now holds framework-wide (TIM-1324).
+ */
+export function defaultStatusPageResponse(status: number, responseHeaders: Headers): Response {
+  responseHeaders.set('content-type', DEFAULT_STATUS_PAGE_CONTENT_TYPE);
+  return new Response(defaultStatusPageHtml(status), { status, headers: responseHeaders });
+}