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

package/src/server/skippable-prefix.ts

@@ -0,0 +1,92 @@
+/**
+ * Skippable-prefix truncation.
+ *
+ * Extracted from `route-element-builder.ts`, which was over the 500-line limit
+ * (design/18-build-system.md). This is a self-contained question — "may this
+ * segment's layout still be skipped, given what its slots would render?" — with
+ * no dependency on element construction.
+ */
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { RouteMatch } from './pipeline.js';
+import { shouldSkipSlot, type ClientStateTree } from './state-tree-diff.js';
+import { consumedUrlParts } from './chain-url-parts.js';
+import { computeSlotKey } from '../routing/segment-keys.js';
+
+/**
+ * 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.
+ */
+export function truncateSkippableForChangedSlots(
+  skippableSet: Set<number>,
+  segments: ManifestSegmentNode[],
+  segmentKeys: string[],
+  match: RouteMatch,
+  clientStateTree: ClientStateTree,
+  req: Request
+): void {
+  const departingUrl = req.headers.get('X-Timber-URL');
+  let depParsed: URL | null = null;
+  if (departingUrl) {
+    try {
+      depParsed = new URL(departingUrl, 'http://localhost');
+    } catch {
+      skippableSet.clear();
+      return;
+    }
+  }
+  const destPathname = new URL(req.url, 'http://localhost').pathname;
+  const depPathname = depParsed?.pathname ?? null;
+  const split = (p: string) => (p === '/' ? [] : p.slice(1).split('/'));
+  const destAll = split(destPathname);
+  const depAll = depPathname ? split(depPathname) : null;
+  const clientSlots = clientStateTree.slots ?? null;
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+
+  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);
+    // The root consumes no URL part, and a climbing interception marker
+    // removes owner segments from the target — `consumedUrlParts` handles both,
+    // and is the same derivation slot matching and layout depth use.
+    const sliceAt = segIdx >= 0 ? consumedUrlParts(match.segments, segIdx, match).length : 0;
+    const destParts = destAll.slice(sliceAt);
+    const depParts = depAll ? depAll.slice(sliceAt) : null;
+    let parentChanged = false;
+    if (depAll) {
+      const dp = depAll.slice(0, sliceAt),
+        dd = destAll.slice(0, sliceAt);
+      parentChanged = dp.length !== dd.length || dp.some((p, j) => p !== dd[j]);
+    }
+
+    for (const [slotName, slotNode] of slotEntries) {
+      const m = slotNode as ManifestSegmentNode;
+      const k = computeSlotKey(segmentKeys[i], `@${slotName}`);
+      if (
+        m.children.some((c) => c.segmentType === 'intercepting') ||
+        parentChanged ||
+        depParts === null ||
+        !shouldSkipSlot({
+          slotKey: k,
+          clientSlots,
+          slotNode: m,
+          departingUrlParts: depParts,
+          destinationUrlParts: destParts,
+        })
+      ) {
+        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.js';
+import type { SlotMatchResult } from './slot-resolver.js';
+import {
+  groupByInterceptedAnchor,
+  interceptorProxy,
+  type InterceptorAnchorGroup,
+} from '../routing/interception.js';
+import { matchUrlParts } from './tree-match.js';
+import { pathnameMatchesPattern } from './pipeline-interception.js';
+
+/**
+ * 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;
+}