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

package/src/server/sitemap-handler.ts

@@ -0,0 +1,157 @@
+/**
+ * Auto-sitemap request handler for the pipeline.
+ *
+ * Creates a handler function that intercepts `/sitemap.xml` and `/sitemap/N.xml`
+ * requests, generating sitemap XML from the route tree on-the-fly.
+ *
+ * This module bridges the pipeline (which doesn't know about route trees)
+ * with the sitemap generator (which doesn't know about HTTP).
+ *
+ * See design/16-metadata.md §"Auto-generated Sitemap"
+ */
+
+import {
+  generateSitemap,
+  hasUserSitemap,
+  type SitemapConfig,
+  type SitemapResult,
+} from './sitemap-generator.ts';
+import { loadModule } from './safe-load.ts';
+import type { SegmentNode } from '../routing/types.ts';
+
+/** Regex to match /sitemap/N.xml where N is a non-negative integer. */
+const SITEMAP_PAGE_PATTERN = /^\/sitemap\/(\d+)\.xml$/;
+
+/**
+ * Create the auto-sitemap request handler for the pipeline.
+ *
+ * Returns a function that handles `/sitemap.xml` and `/sitemap/N.xml`,
+ * or returns `null` to pass through to regular routing.
+ *
+ * Returns `undefined` if auto-sitemap is not enabled (no overhead in pipeline).
+ */
+export function createAutoSitemapHandler(
+  root: SegmentNode,
+  runtimeConfig: Record<string, unknown>
+): ((pathname: string) => Promise<Response | null>) | undefined {
+  // Check if sitemap generation is enabled
+  const sitemapConfig = runtimeConfig.sitemap as
+    | {
+        enabled?: boolean;
+        baseUrl?: string;
+        defaultChangeFrequency?: string;
+        defaultPriority?: number;
+        includeProtected?: boolean;
+      }
+    | undefined;
+
+  if (!sitemapConfig?.enabled) return undefined;
+
+  if (!sitemapConfig.baseUrl) {
+    console.warn(
+      '[timber] sitemap.enabled is true but sitemap.baseUrl is missing. Sitemap generation disabled.'
+    );
+    return undefined;
+  }
+
+  // Don't generate if user has their own sitemap at the root
+  if (hasUserSitemap(root)) return undefined;
+
+  const config: SitemapConfig = {
+    enabled: true,
+    baseUrl: sitemapConfig.baseUrl,
+    defaultChangeFrequency: sitemapConfig.defaultChangeFrequency,
+    defaultPriority: sitemapConfig.defaultPriority,
+    includeProtected: sitemapConfig.includeProtected ?? false,
+  };
+
+  // Module loader adapter — uses the safe-load helper which wraps
+  // the manifest's lazy import functions.
+  const moduleLoader = async (loader: { load: () => Promise<unknown>; filePath: string }) => {
+    return loadModule<Record<string, unknown>>(loader);
+  };
+
+  // Cache the generated result to avoid regenerating on every request.
+  // In dev, this cache is busted by file changes (the handler is recreated
+  // when the route tree changes). In production, it's generated once.
+  let cachedResult: SitemapResult | null = null;
+  let inflight: Promise<SitemapResult> | null = null;
+
+  async function getOrGenerateSitemap(): Promise<SitemapResult> {
+    if (cachedResult) return cachedResult;
+    if (!inflight) {
+      inflight = generateSitemap(root, config, moduleLoader).then(
+        (result) => {
+          cachedResult = result;
+          inflight = null;
+          return result;
+        },
+        (err) => {
+          inflight = null;
+          throw err;
+        }
+      );
+    }
+    // Every caller races against its own timeout — not just the first.
+    // Per design/06-caching.md — singleflight maps must have a timeout
+    // to prevent deadlock if generateSitemap hangs.
+    const timeout = new Promise<never>((_, reject) =>
+      setTimeout(() => {
+        inflight = null;
+        reject(new Error('[timber] sitemap generation timed out'));
+      }, 30_000)
+    );
+    return Promise.race([inflight, timeout]);
+  }
+
+  return async (pathname: string): Promise<Response | null> => {
+    // Handle /sitemap.xml
+    if (pathname === '/sitemap.xml') {
+      const result = await getOrGenerateSitemap();
+      const xml = result.type === 'single' ? result.xml : result.indexXml;
+      return new Response(xml, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'Cache-Control': 'public, max-age=14400, must-revalidate',
+        },
+      });
+    }
+
+    // Handle /sitemap/N.xml (paginated sub-sitemaps)
+    const pageMatch = SITEMAP_PAGE_PATTERN.exec(pathname);
+    if (pageMatch) {
+      const result = await getOrGenerateSitemap();
+      if (result.type === 'single') {
+        // No pagination — only page 0 is valid for a single sitemap
+        const pageIndex = parseInt(pageMatch[1], 10);
+        if (pageIndex === 0) {
+          return new Response(result.xml, {
+            status: 200,
+            headers: {
+              'Content-Type': 'application/xml; charset=utf-8',
+              'Cache-Control': 'public, max-age=14400, must-revalidate',
+            },
+          });
+        }
+        return new Response(null, { status: 404 });
+      }
+
+      const pageIndex = parseInt(pageMatch[1], 10);
+      const pageXml = result.pages.get(pageIndex);
+      if (!pageXml) {
+        return new Response(null, { status: 404 });
+      }
+      return new Response(pageXml, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'Cache-Control': 'public, max-age=14400, must-revalidate',
+        },
+      });
+    }
+
+    // Not a sitemap URL — pass through
+    return null;
+  };
+}

package/src/server/skippable-prefix.ts

@@ -0,0 +1,172 @@
+/**
+ * Skippable-prefix computation.
+ *
+ * Determines which layouts can be skipped on a partial navigation by
+ * computing a contiguous prefix of segments whose cached layouts need
+ * not re-render. Extracted from `route-element-builder.ts` to keep it
+ * under the 500-line limit (design/18-build-system.md).
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header".
+ */
+
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { RouteMatch } from './pipeline.ts';
+import { shouldSkipSegment, shouldSkipSlot, type ClientStateTree } from './state-tree-diff.ts';
+import { consumedUrlParts } from './chain-url-parts.ts';
+import { computeSlotContentKey, computeSlotKey } from '../routing/segment-keys.ts';
+import { matchUrlParts } from './tree-match.ts';
+import { slotUrlParts } from './slot-resolver.ts';
+
+/**
+ * Compute the set of segment indices whose layouts can be skipped.
+ *
+ * Three sub-rules in order:
+ *   (a) Contiguous prefix via `shouldSkipSegment` — stop at the first
+ *       non-skippable layout.
+ *   (b) If every layout landed in the prefix, remove the innermost one
+ *       as the merge point (the client needs a mounted outlet there).
+ *   (c) Cross-section guard — clear the whole set unless at least one
+ *       non-skipped layout's key is in `clientStateTree`.
+ *
+ * After the prefix is computed, `truncateSkippableForChangedSlots`
+ * removes any segment whose parallel slots changed content.
+ */
+export function computeSkippableSet(
+  segments: ManifestSegmentNode[],
+  segmentKeys: string[],
+  layoutBySegment: Map<ManifestSegmentNode, unknown>,
+  clientStateTree: ClientStateTree | null | undefined,
+  match: RouteMatch,
+  req: Request
+): Set<number> {
+  const skippableSet = new Set<number>();
+  if (!clientStateTree) return skippableSet;
+
+  // (a) Contiguous prefix via shouldSkipSegment.
+  for (let i = 0; i < segments.length; i++) {
+    const isLeaf = i === segments.length - 1;
+    const layoutComponent = layoutBySegment.get(segments[i]);
+
+    if (
+      shouldSkipSegment(
+        segmentKeys[i],
+        layoutComponent as ((...args: unknown[]) => unknown) | undefined,
+        isLeaf,
+        clientStateTree
+      )
+    ) {
+      skippableSet.add(i);
+    } else if (layoutComponent) {
+      break;
+    }
+  }
+
+  // (b) Ensure there's a merge point: if all layouts are in the prefix,
+  // keep the innermost as merge point.
+  if (skippableSet.size > 0) {
+    let mergePointIndex = -1;
+    for (let i = 0; i < segments.length; i++) {
+      if (skippableSet.has(i)) continue;
+      if (layoutBySegment.has(segments[i])) {
+        mergePointIndex = i;
+        break;
+      }
+    }
+
+    if (mergePointIndex === -1) {
+      for (let i = segments.length - 1; i >= 0; i--) {
+        if (skippableSet.has(i) && layoutBySegment.has(segments[i])) {
+          skippableSet.delete(i);
+          mergePointIndex = i;
+          break;
+        }
+      }
+    }
+
+    // (c) Cross-section guard: at least one rendered layout below the
+    // prefix must exist in the client's state tree.
+    let hasClientOutlet = false;
+    for (let j = 0; j < segments.length; j++) {
+      if (skippableSet.has(j)) continue;
+      if (layoutBySegment.has(segments[j]) && clientStateTree.has(segmentKeys[j])) {
+        hasClientOutlet = true;
+        break;
+      }
+    }
+    if (!hasClientOutlet) {
+      skippableSet.clear();
+    }
+  }
+
+  // Slot-change guard (TIM-1232).
+  if (skippableSet.size > 0) {
+    truncateSkippableForChangedSlots(
+      skippableSet,
+      segments,
+      segmentKeys,
+      match,
+      clientStateTree,
+      req
+    );
+  }
+
+  return skippableSet;
+}
+
+/**
+ * Truncate the skippable prefix when a skippable layout has slots whose
+ * content changed between the departing and destination URLs (TIM-1232).
+ *
+ * Without this, changed slots at skipped layouts are never sent to the
+ * client — the `continue` in the main loop skips slot resolution entirely.
+ * Removing the segment from the skippable set forces it to render with
+ * its slots. The prefix must stay contiguous, so all segments after the
+ * first changed-slot segment are also removed.
+ *
+ * Uses key-based diffing (TIM-1370): computes the destination content key
+ * per slot and checks if the client's advertised set contains it.
+ */
+function truncateSkippableForChangedSlots(
+  skippableSet: Set<number>,
+  segments: ManifestSegmentNode[],
+  segmentKeys: string[],
+  match: RouteMatch,
+  clientStateTree: ClientStateTree,
+  req: Request
+): void {
+  const clientSlotKeys = clientStateTree.slots ?? null;
+  const destUrl = req.url;
+
+  for (let i = 0; i < segments.length; i++) {
+    if (!skippableSet.has(i)) continue;
+    const segment = segments[i];
+    const slotEntries = Object.entries(segment.slots ?? {});
+    if (slotEntries.length === 0) continue;
+
+    const segIdx = match.segments.indexOf(segment);
+    const ownerParts = segIdx >= 0 ? consumedUrlParts(match.segments, segIdx, match) : [];
+    const destParts = slotUrlParts(segment, match, destUrl);
+
+    for (const [slotName, slotNode] of slotEntries) {
+      const m = slotNode as ManifestSegmentNode;
+      const k = computeSlotKey(segmentKeys[i], `@${slotName}`);
+
+      // Slots with access.ts are never skip candidates (TIM-1364).
+      const destMatch = matchUrlParts(m, destParts);
+      const hasAccessInChain = !!m.access || (destMatch?.chain.some((seg) => seg.access) ?? false);
+
+      const destLeaf = destMatch?.chain[destMatch.chain.length - 1];
+      const entryFile = destLeaf?.page?.filePath ?? null;
+      const contentKey = computeSlotContentKey(k, ownerParts, entryFile, destMatch?.params ?? {});
+
+      if (
+        hasAccessInChain ||
+        m.children.some((c) => c.segmentType === 'intercepting') ||
+        !shouldSkipSlot(contentKey, clientSlotKeys)
+      ) {
+        for (let j = i; j < segments.length; j++) skippableSet.delete(j);
+        return;
+      }
+    }
+  }
+}

package/src/server/slot-interception.ts

@@ -0,0 +1,168 @@
+/**
+ * Intercepting-route resolution for parallel slots.
+ *
+ * This is the ONLY interception-aware part of the render pipeline. The normal
+ * children path — `tree-match.ts`, `route-matcher.ts` — has none, and must
+ * keep none: teaching the shared walker to match intercepting nodes would make
+ * the *main* route matcher render modals on hard navigation. Interception
+ * therefore lives here, behind one entry point the slot resolver calls when
+ * the pipeline has flagged a soft navigation.
+ *
+ * Split out of `slot-resolver.ts` when the matching rules grew (TIM-1281):
+ * anchoring, sibling priority, and the identity a marker'd directory name
+ * stands for are one subject, and slot resolution proper is another.
+ *
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+
+import type { ManifestFile, ManifestSegmentNode } from './route-matcher.ts';
+import type { SlotMatchResult } from './slot-resolver.ts';
+import {
+  groupByInterceptedAnchor,
+  interceptorProxy,
+  type InterceptorAnchorGroup,
+} from '../routing/interception.ts';
+import { matchUrlParts } from './tree-match.ts';
+import { pathnameMatchesPattern } from './pipeline-interception.ts';
+
+/**
+ * Whether an anchor group applies to this target at all.
+ *
+ * The group's base is a build-time URL *pattern* — `computeInterceptedBase`
+ * climbs `slotNode.urlPath`, which carries directory names, so a dynamic
+ * ancestor survives as `[id]`. Every pattern part stands for exactly one URL
+ * part, which makes the anchor index simply the base's length —
+ * `groupByInterceptedAnchor` derives it there, once, for both the resolver and
+ * the build-time collision validator.
+ *
+ * The one part that breaks that 1:1 correspondence is a catch-all, whose
+ * width varies per request. An interception based below one is therefore
+ * only resolvable when the catch-all happens to have consumed a single
+ * segment; deeper, the fixed index lands on the wrong part, the base check
+ * below fails, and the interception is dropped so the canonical route
+ * renders. That is the fail-safe outcome, never a wrong page — but it is a
+ * modal that silently does not open, so `validateInterceptionPlacement`
+ * rejects the shape at build time (TIM-1288). The behaviour here is what
+ * that rule is stated against, and stays as the fail-safe if a tree ever
+ * reaches the resolver unvalidated.
+ *
+ * The base must also *match* the target's leading parts, not merely count
+ * them. A slot can hold interceptors at different marker depths, and the
+ * pipeline's rewrite gate only established that *some* rewrite matched — not
+ * this child's. Under a slot at `/gallery/albums`, a navigation to
+ * `/gallery/photo/9` is meant for `(..)photo/[id]`, but `(.)[id]` anchors one
+ * part deeper and its slice `['9']` matches, so without this check the album
+ * modal opens on a photo URL. Name-equality used to rule that out as a side
+ * effect of comparing the directory name; positional anchoring has to check
+ * it deliberately (TIM-1281).
+ *
+ * `pathnameMatchesPattern` is the pipeline's own pattern matcher, so a base
+ * accepted here is one that gate would accept too.
+ */
+function anchorApplies(
+  group: InterceptorAnchorGroup<ManifestFile>,
+  targetParts: string[]
+): boolean {
+  if (group.anchorIndex > targetParts.length) return false;
+
+  const targetPrefix =
+    group.anchorIndex === 0 ? '/' : `/${targetParts.slice(0, group.anchorIndex).join('/')}`;
+  return pathnameMatchesPattern(targetPrefix, group.base);
+}
+
+/**
+ * Find a matching intercepting route in a slot's children for the target pathname.
+ *
+ * When interception is active, the pipeline has already re-matched the source URL.
+ * Here we check the slot's intercepting children (e.g. `(.)photo/[id]`) against
+ * the target pathname to find which intercepting page to render.
+ *
+ * Two things distinguish an intercepting child from an ordinary slot child,
+ * and both used to be handled by hand here (TIM-1281):
+ *
+ * **Where its segment sits in the target.** The marker says how far above the
+ * slot owner the intercepted route lives, which makes the intercepted
+ * segment's index in the target pathname a position rather than something to
+ * search for. The old code scanned the target from the end for a part equal
+ * to the directory name, which found the wrong index whenever a *value*
+ * happened to equal that name (`/gallery/photo/photo`) and could never work
+ * at all for a dynamic intercepted segment.
+ *
+ * The index is derived from `computeInterceptedBase` — a build-time URL
+ * pattern — and NOT from the re-matched source route. That route is matched
+ * from `interceptingPrefix`, which is itself a pattern, so under a dynamic
+ * ancestor its params are literals: re-matching `/docs/[...path]` binds
+ * `path` to `['[...path]']`, and any depth read from it is the pattern's,
+ * not the URL's.
+ *
+ * A pattern part maps 1:1 onto a URL part except for a catch-all, whose
+ * width varies per request; `anchorApplies` documents what that costs.
+ *
+ * **What its segment matches.** `(.)photo` matches the literal `photo`;
+ * `(.)[id]`, `(.)img-[id].png` and `(.)[...rest]` match the way the same
+ * bracket syntax matches anywhere else. Rather than re-classify here, the
+ * node is handed to the shared walker under its `effectiveUrlSegment`
+ * identity, so priority ordering, affix stripping, catch-all collection and
+ * the terminal-leaf rule all come from `tree-match.ts` — which stays
+ * interception-unaware, as it must: teaching it to match intercepting nodes
+ * would make the *main* route matcher render modals on hard navigation.
+ *
+ * **Siblings compete, so they are walked together.** Two interceptors that
+ * anchor at the same URL index — `(.)photo/page.tsx` and `(.)[slug]/page.tsx`
+ * — are both candidates for the same part, exactly like two ordinary
+ * siblings. Matching each in its own tree and returning the first that
+ * succeeded would resolve them in manifest (filesystem) order, so
+ * `/gallery/photo` would render the dynamic modal whenever the dynamic
+ * directory happened to be enumerated first. Grouping by anchor and handing
+ * the whole group to one walk restores static > dynamic > catch-all, and
+ * gives backtracking across siblings for free.
+ *
+ * Groups are tried deepest anchor first, so a `(.)` interception — the most
+ * local one — wins over a `(...)` that reaches the same page from the root.
+ *
+ * The grouping itself is `groupByInterceptedAnchor`, shared with the build so
+ * that what is walked together is what the collision validator checked together
+ * (TIM-1310). Two interceptors of the *same* kind at one anchor — `(.)[a]`
+ * beside `(.)[b]` — would otherwise resolve by manifest order here with nothing
+ * to say so; the validator rejects them, within the limits of a probe search,
+ * because it walks this same group.
+ *
+ * The matched chain carries the real node, not the identity proxy, so tree
+ * paths keep the directory name (`/gallery/@modal/(.)photo/[id]`).
+ */
+export function findInterceptingMatch(
+  slotNode: ManifestSegmentNode,
+  targetPathname: string
+): SlotMatchResult | null {
+  const targetParts = targetPathname === '/' ? [] : targetPathname.slice(1).split('/');
+
+  // Deepest anchor first, from the grouping the build validates against.
+  for (const group of groupByInterceptedAnchor(slotNode.urlPath, slotNode.children)) {
+    if (!anchorApplies(group, targetParts)) continue;
+
+    // Proxies carry the identity the walker matches on; the map back to the
+    // real node is what the chain is rebuilt from.
+    const entries = group.interceptors.map((real) => ({ proxy: interceptorProxy(real), real }));
+    const anchorNode: ManifestSegmentNode = {
+      segmentName: '',
+      segmentType: 'static',
+      urlPath: slotNode.urlPath,
+      children: entries.map((e) => e.proxy),
+      slots: {},
+    };
+    const result = matchUrlParts(anchorNode, targetParts.slice(group.anchorIndex));
+    if (!result) continue;
+
+    // result.chain is [anchorNode, matchedProxy, ...descendants]. Drop the
+    // synthetic parent and restore the real node in the proxy's place.
+    const real = entries.find((e) => e.proxy === result.chain[1])?.real;
+    if (!real) continue;
+    const chain = [slotNode, real, ...result.chain.slice(2)];
+    const leaf = chain[chain.length - 1];
+    if (!leaf.page) continue;
+
+    return { page: leaf.page, chain, slotParams: result.params };
+  }
+
+  return null;
+}