@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/build-manifest.ts

@@ -35,14 +35,40 @@ export interface BuildManifest {
   modulepreload: Record<string, string[]>;
   /** Map from input file path to font assets used by that module. */
   fonts: Record<string, ManifestFontEntry[]>;
+  /**
+   * Cache-busting hashes for metadata route files (opengraph-image, etc.).
+   * Map from file path (relative to project root) to short content hash.
+   * In dev mode this is empty — a startup nonce is used instead.
+   */
+  metadataRouteHashes?: Record<string, string>;
+  /**
+   * Static request-dependency map from the Vite plugin's module-graph analysis.
+   * Map from segment entry file path to whether it's request-dependent.
+   * Used by buildSegmentInfo() for X-Timber-Segments in production.
+   */
+  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). */
@@ -85,22 +111,15 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
+  // Emit only <link rel="stylesheet"> — no preload tags. CSS preloading
+  // is handled by 103 Early Hints (Link header) which fires before the
+  // HTML stream. Float also emits `<link rel="stylesheet" data-precedence>`
+  // at the top of <head> during Fizz rendering — the browser discovers
+  // CSS from that tag. A <link rel="preload"> here would arrive *after*
+  // Float's stylesheet tag and trigger "Preload was ignored" warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
-/**
- * Generate a Link header value for CSS preload hints.
- *
- * Cloudflare CDN automatically converts Link headers with rel=preload
- * into 103 Early Hints responses. This avoids platform-specific 103
- * sending code.
- *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
- */
-export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
-}
-
 // ─── Font utilities ──────────────────────────────────────────────────────
 
 /**
@@ -148,44 +167,8 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
     .join('');
 }
 
-/**
- * Generate Link header values for font preload hints.
- *
- * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
- *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
- */
-export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
-}
-
 // ─── JS chunk utilities ──────────────────────────────────────────────────
 
-/**
- * Collect JS chunk URLs for a matched route's segment chain.
- *
- * Walks segments root → leaf, collecting the JS chunk for each layout
- * and page. Deduplicates while preserving order.
- */
-export function collectRouteJs(segments: SegmentWithFiles[], manifest: BuildManifest): string[] {
-  const seen = new Set<string>();
-  const result: string[] = [];
-
-  for (const segment of segments) {
-    for (const file of [segment.layout, segment.page]) {
-      if (!file) continue;
-      const jsUrl = manifest.js[file.filePath];
-      if (!jsUrl) continue;
-      if (!seen.has(jsUrl)) {
-        seen.add(jsUrl);
-        result.push(jsUrl);
-      }
-    }
-  }
-
-  return result;
-}
-
 /**
  * Collect modulepreload URLs for a matched route's segment chain.
  *
@@ -225,10 +208,3 @@ export function collectRouteModulepreloads(
 export function buildModulepreloadTags(urls: string[]): string {
   return urls.map((url) => `<link rel="modulepreload" href="${url}">`).join('');
 }
-
-/**
- * Generate a <script type="module"> tag for a JS entry point.
- */
-export function buildEntryScriptTag(url: string): string {
-  return `<script type="module" src="${url}"></script>`;
-}

package/src/server/canonicalize.ts

@@ -13,11 +13,14 @@ export type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; s
 /**
  * Encoded separators that produce a 400 rejection.
  * %2f (/) and %5c (\) cause path-confusion attacks.
+ *
+ * Shared between the runtime canonicalizer and the build-time route scanner
+ * to ensure both enforce identical security rules. See design/13-security.md.
  */
-const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
+export const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
 
-/** Null byte — rejected. */
-const NULL_BYTE_RE = /%00/i;
+/** Null byte — rejected. Shared with the route scanner. */
+export const NULL_BYTE_RE = /%00/i;
 
 /**
  * Canonicalize a URL pathname.

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` 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
+ * 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.ts';
+import type { RouteMatch } from './pipeline.ts';
+import type { CoercedParams } from '../shared/param-value.ts';
+import { effectiveUrlSegment } from '../routing/segment-classify.ts';
+import { computeInterceptedBase } from '../routing/interception.ts';
+
+/**
+ * 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: CoercedParams
+): 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 — `route-element-builder.ts`, 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.ts';
+import { collectMiddlewareChain, type ManifestSegmentNode } from './route-matcher.ts';
+import { findInterceptingMatch } from './slot-interception.ts';
+import { treePathNames } from '../routing/segment-keys.ts';
+
+/**
+ * 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/coalesce-tick.ts

@@ -0,0 +1,75 @@
+/**
+ * Single-shot `setImmediate` coalescing primitive.
+ *
+ * Multiple synchronous `schedule()` calls within one event-loop tick
+ * result in exactly one `flush` invocation at the end of that tick.
+ * No recursive scheduling, no busy-wait, no polling loop.
+ *
+ * Both `createBufferedTransformStream` (Web) and
+ * `createNodeBufferedTransform` (Node) use this helper so the invariant
+ * — and this comment — live in one place.
+ *
+ * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
+ * cycle — no recursive scheduling, no busy-wait. See design/02
+ * §"No Polling".
+ */
+
+export interface TickCoalescer {
+  /**
+   * Request a flush at the end of the current tick. If a flush is already
+   * scheduled, this is a no-op. Returns the pending promise (or undefined
+   * if the flush already fired and no new one has been scheduled).
+   */
+  schedule(): void;
+
+  /**
+   * The pending flush promise, if any. Callers (e.g. `flush()` in a
+   * TransformStream) can `await` this to wait for the scheduled flush
+   * to complete before closing the stream.
+   */
+  readonly pending: Promise<void> | undefined;
+
+  /**
+   * Cancel any pending scheduled flush and invoke the flush callback
+   * synchronously. Used by Node `Transform.flush()` which needs to
+   * drain the buffer immediately before calling back.
+   */
+  flushSync(): void;
+}
+
+/**
+ * Create a tick coalescer that calls `onFlush` at most once per tick.
+ */
+export function createTickCoalescer(onFlush: () => void): TickCoalescer {
+  let pending: Promise<void> | undefined;
+  let immediateHandle: ReturnType<typeof setImmediate> | null = null;
+
+  function doFlush(): void {
+    immediateHandle = null;
+    pending = undefined;
+    onFlush();
+  }
+
+  return {
+    schedule() {
+      if (immediateHandle !== null) return;
+      pending = new Promise<void>((resolve) => {
+        immediateHandle = setImmediate(() => {
+          doFlush();
+          resolve();
+        });
+      });
+    },
+
+    get pending() {
+      return pending;
+    },
+
+    flushSync() {
+      if (immediateHandle !== null) {
+        clearImmediate(immediateHandle);
+        doFlush();
+      }
+    },
+  };
+}

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.ts';
 
 // ─── 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',
@@ -160,15 +168,42 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable, pipeline } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const compressionStream = new CompressionStream('gzip');
-  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
-  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
-  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+
+  // pipeline() instead of bare pipe(): pipe() does not forward source errors,
+  // so an erroring body (streaming route handler, dropped upstream fetch)
+  // would emit an unhandled 'error' event and crash the process. pipeline()
+  // destroys gzip on source error — the returned web stream rejects — and
+  // tears down nodeInput when the consumer cancels the web stream, which
+  // cancels the source body via fromWeb. The error reaches the consumer
+  // through the web stream; the callback only marks it handled at the Node
+  // layer.
+  pipeline(nodeInput, gzip, () => {});
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }