@timber-js/app 0.2.0-alpha.121 → 0.2.0-alpha.123

package/src/segment-params/define.ts

@@ -20,6 +20,7 @@ import {
   isStandardSchema,
   isCodec,
 } from '../schema-bridge.js';
+import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
 
 // ---------------------------------------------------------------------------
 // Server-only ALS reference for .get()
@@ -28,28 +29,6 @@ import {
 // 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;
-let _useSegmentParamsHook: (() => Record<string, string | string[]>) | undefined;
-
-/**
- * Register the client useSegmentParams hook.
- * Called by client entry at module load time to avoid require() at call time.
- * @internal
- */
-export function _registerUseSegmentParams(hook: () => Record<string, string | string[]>): void {
-  _useSegmentParamsHook = hook;
-}
-
-// Self-register on the client when the barrel hasn't been imported yet.
-// Handles the edge case where a client component imports only from params.ts
-// without importing anything from @timber-js/app/client (which runs the
-// registration). The dynamic import resolves before React hydration in Vite.
-if (typeof window !== 'undefined' && !_useSegmentParamsHook) {
-  import('../client/use-segment-params.js').then((mod) => {
-    if (!_useSegmentParamsHook) {
-      _useSegmentParamsHook = mod.useSegmentParams;
-    }
-  });
-}
 
 /**
  * Register the getSegmentParams function. Called once at module load time
@@ -311,13 +290,7 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
   // Client hook that reads typed params from the navigation context.
   // Delegates to the existing useSegmentParams hook from use-segment-params.ts.
   function useSegmentParams(): T {
-    if (!_useSegmentParamsHook) {
-      throw new Error(
-        '[timber] segmentParams.useSegmentParams() requires @timber-js/app/client to be loaded. ' +
-          'This hook can only be used in client components.'
-      );
-    }
-    const raw = _useSegmentParamsHook();
+    const raw = clientUseSegmentParams();
     // Params are already coerced by the server pipeline before being sent
     // to the client — return as-is. Re-parsing would break non-idempotent
     // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.

package/src/server/actions.ts

@@ -60,21 +60,11 @@ export interface ActionHandlerResult {
 // (the previous module-level global was vulnerable to cross-request pollution).
 
 /**
- * Set the revalidation state for the current action execution.
- * @internal — kept for test compatibility; prefer executeAction() which uses ALS.
+ * Run `fn` inside a revalidation ALS scope.
+ * @internal — for tests that call revalidatePath/Tag directly without executeAction().
  */
-export function _setRevalidationState(state: RevalidationState): void {
-  // Enter ALS scope — this is only used by tests that call revalidatePath/Tag
-  // directly without going through executeAction().
-  revalidationAls.enterWith(state);
-}
-
-/**
- * Clear the revalidation state after action execution.
- * @internal — kept for test compatibility.
- */
-export function _clearRevalidationState(): void {
-  revalidationAls.enterWith(undefined as unknown as RevalidationState);
+export function _runWithRevalidationState<T>(state: RevalidationState, fn: () => T): T {
+  return revalidationAls.run(state, fn);
 }
 
 /**

package/src/server/build-manifest.ts

@@ -35,6 +35,12 @@ 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>;
 }
 
 /** Empty build manifest used in dev mode. */
@@ -43,6 +49,7 @@ export const EMPTY_BUILD_MANIFEST: BuildManifest = {
   js: {},
   modulepreload: {},
   fonts: {},
+  metadataRouteHashes: {},
 };
 
 /** Segment shape expected by collectRouteCss (matches ManifestSegmentNode). */

package/src/server/internal.ts

@@ -114,7 +114,13 @@ export {
   getMetadataRouteAutoLink,
   METADATA_ROUTE_CONVENTIONS,
 } from './metadata-routes.js';
-export type { MetadataRouteInfo, MetadataRouteType } from './metadata-routes.js';
+export type {
+  MetadataRouteInfo,
+  MetadataRouteType,
+  AutoLinkTag,
+  AutoLinkLink,
+  AutoLinkMeta,
+} from './metadata-routes.js';
 
 // ── Server Actions (pipeline internals) ──────────────────────────────────
 export { executeAction, buildNoJsResponse, isRscActionRequest } from './actions.js';

package/src/server/metadata-routes.ts

@@ -29,7 +29,6 @@ export type MetadataRouteType =
   | 'favicon'
   | 'icon'
   | 'opengraph-image'
-  | 'twitter-image'
   | 'apple-icon';
 
 // ─── Convention Table ────────────────────────────────────────────────────────
@@ -84,7 +83,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     contentType: 'image/x-icon',
     nestable: false,
     staticExtensions: ['ico'],
-    dynamicExtensions: [],
+    dynamicExtensions: ['ts', 'tsx'],
     servePath: 'favicon.ico',
   },
   'icon': {
@@ -103,14 +102,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     dynamicExtensions: ['ts', 'tsx'],
     servePath: 'opengraph-image',
   },
-  'twitter-image': {
-    type: 'twitter-image',
-    contentType: 'image/*',
-    nestable: true,
-    staticExtensions: ['png', 'jpg'],
-    dynamicExtensions: ['ts', 'tsx'],
-    servePath: 'twitter-image',
-  },
+
   'apple-icon': {
     type: 'apple-icon',
     contentType: 'image/*',
@@ -225,26 +217,59 @@ export function getMetadataRouteServePath(type: MetadataRouteType): string {
   throw new Error(`[timber] Unknown metadata route type: ${type}`);
 }
 
+const METADATA_SERVE_PATHS = new Set(
+  Object.values(METADATA_ROUTE_CONVENTIONS).map((c) => c.servePath)
+);
+
+export function isMetadataRouteServePath(pathname: string): boolean {
+  const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+  return METADATA_SERVE_PATHS.has(lastSegment);
+}
+
+/** A <link> auto-link tag. */
+export interface AutoLinkLink {
+  tag: 'link';
+  rel: string;
+  href: string;
+  type?: string;
+}
+
+/** A <meta> auto-link tag. */
+export interface AutoLinkMeta {
+  tag: 'meta';
+  property?: string;
+  name?: string;
+  content: string;
+}
+
+export type AutoLinkTag = AutoLinkLink | AutoLinkMeta;
+
 /**
  * Get the auto-link tags to inject into <head> for metadata route files
  * discovered in a segment.
  *
+ * Returns link tags for icon/apple-icon/manifest, and meta tags for
+ * opengraph-image (emits both og:image and twitter:image). Returns null
+ * for types that don't auto-link (favicon, sitemap, robots).
+ *
  * @param type - The metadata route type
  * @param href - The resolved URL path to the metadata route
- * @returns An object with tag/attrs for the <head>, or null if no auto-link
+ * @returns Tag descriptor(s) for the <head>, or null if no auto-link
  */
-export function getMetadataRouteAutoLink(
-  type: MetadataRouteType,
-  href: string
-): { rel: string; href: string; type?: string } | null {
+export function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {
   switch (type) {
     case 'icon':
-      return { rel: 'icon', href };
+      return [{ tag: 'link', rel: 'icon', href }];
     case 'apple-icon':
-      return { rel: 'apple-touch-icon', href };
+      return [{ tag: 'link', rel: 'apple-touch-icon', href }];
     case 'manifest':
-      return { rel: 'manifest', href };
+      return [{ tag: 'link', rel: 'manifest', href }];
+    case 'opengraph-image':
+      return [
+        { tag: 'meta', property: 'og:image', content: href },
+        { tag: 'meta', name: 'twitter:image', content: href },
+      ];
     default:
-      return null;
+      return [];
   }
 }

package/src/server/pipeline-phases.ts

@@ -232,6 +232,7 @@ export async function handleRequest(
           return await serveStaticMetadataFile(metaMatch);
         }
 
+        setSegmentParams(metaMatch.segmentParams);
         const mod = await loadModule<{ default?: MetadataHandler }>(metaMatch.file);
         if (typeof mod.default !== 'function') {
           if (isDebug()) {
@@ -247,6 +248,13 @@ export async function handleRequest(
         // outer Server-Timing writer can append without hitting an
         // immutable header bag (e.g. user returns Response.redirect()).
         if (handlerResult instanceof Response) {
+          if (method === 'HEAD') {
+            return new Response(null, {
+              status: handlerResult.status,
+              statusText: handlerResult.statusText,
+              headers: new Headers(handlerResult.headers),
+            });
+          }
           return cloneWithMutableHeaders(handlerResult);
         }
         // Otherwise, serialize based on content type. The type discriminator

package/src/server/request-context.ts

@@ -23,10 +23,6 @@ import { isDebug } from './debug.js';
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
 
-// No fallback needed — we use enterWith() instead of run() to ensure
-// the ALS context persists for the entire request lifecycle including
-// async stream consumption by React's renderToReadableStream.
-
 // ─── Public API ───────────────────────────────────────────────────────────
 
 /**

package/src/server/route-element-builder.ts

@@ -17,14 +17,22 @@
  */
 
 import { createElement } from 'react';
+import { randomUUID } from 'node:crypto';
 
 import { withSpan } from './tracing.js';
 import type { RouteMatch } from './pipeline.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import type { HeadElement as MetadataHeadElement } from './metadata.js';
 import type { Metadata } from './types.js';
 import { METADATA_ROUTE_CONVENTIONS, getMetadataRouteAutoLink } from './metadata-routes.js';
+
+// In dev mode, use a per-startup nonce for metadata route cache busting
+// instead of per-file content hashes (avoids rehashing on every request).
+let _devNonce: string | undefined;
+function getDevNonce(): string {
+  _devNonce ??= randomUUID().slice(0, 8);
+  return _devNonce;
+}
 import { DenySignal, RedirectSignal } from './primitives.js';
 import { AccessGate } from './access-gate.js';
 import {
@@ -215,7 +223,8 @@ export async function buildRouteElement(
   req: Request,
   match: RouteMatch,
   interception?: InterceptionContext,
-  clientStateTree?: Set<string> | null
+  clientStateTree?: Set<string> | null,
+  metadataRouteHashes?: Record<string, string>
 ): Promise<RouteElementResult> {
   const segments = match.segments;
 
@@ -309,8 +318,20 @@ export async function buildRouteElement(
   const resolvedMetadata = resolveMetadata(metadataEntries);
   const headElements = renderMetadataToElements(resolvedMetadata);
 
-  // Auto-link metadata route files (icon, apple-icon, manifest) from segments.
+  // Auto-link metadata route files (icon, apple-icon, manifest, opengraph-image).
+  // opengraph-image emits both og:image and twitter:image (no separate twitter-image convention).
+  // Skip OG auto-linking when the user already declared images in metadata.
   // See design/16-metadata.md §"Auto-Linking"
+  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);
+  const requestUrl = new URL(req.url);
+  const requestPathname = requestUrl.pathname;
+  // In dev mode, use the request origin so OG URLs resolve to localhost.
+  // In production, use metadataBase (the canonical domain).
+  const ogBase =
+    process.env.NODE_ENV !== 'production'
+      ? new URL(requestUrl.origin)
+      : resolvedMetadata.metadataBase;
+
   for (const segment of segments) {
     if (!segment.metadataRoutes) continue;
     for (const baseName of Object.keys(segment.metadataRoutes)) {
@@ -318,14 +339,39 @@ export async function buildRouteElement(
       if (!convention) continue;
       // Non-nestable routes only auto-link from root
       if (!convention.nestable && segment.urlPath !== '/') continue;
-      // Build the href: segment urlPath + serve path
-      const prefix = segment.urlPath === '/' ? '' : segment.urlPath;
-      const href = `${prefix}/${convention.servePath}`;
-      const autoLink = getMetadataRouteAutoLink(convention.type, href);
-      if (autoLink) {
-        const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
-        if (autoLink.type) attrs.type = autoLink.type;
-        headElements.push({ tag: 'link', attrs } as MetadataHeadElement);
+      // Skip auto-linking if user already declared the image in metadata
+      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;
+      // Build the href using the actual request path (not the pattern with [param]).
+      // For nestable routes, the metadata route sits under the same resolved path
+      // as the page. For root-only routes, use '/'.
+      const resolvedPrefix = convention.nestable
+        ? requestPathname === '/'
+          ? ''
+          : requestPathname
+        : '';
+      let href = `${resolvedPrefix}/${convention.servePath}`;
+      // Append cache-bust query param for image metadata routes
+      if (convention.type === 'opengraph-image') {
+        const metaFile = segment.metadataRoutes[baseName];
+        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;
+        const cacheBust = fileHash ?? getDevNonce();
+        href = `${href}?${cacheBust}`;
+      }
+      // Resolve to absolute URL for og:image/twitter:image (social crawlers need full URLs)
+      if (ogBase && convention.type === 'opengraph-image') {
+        href = new URL(href, ogBase).toString();
+      }
+      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {
+        if (autoLink.tag === 'link') {
+          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
+          if (autoLink.type) attrs.type = autoLink.type;
+          headElements.push({ tag: 'link', attrs });
+        } else {
+          const attrs: Record<string, string> = { content: autoLink.content };
+          if (autoLink.property) attrs.property = autoLink.property;
+          if (autoLink.name) attrs.name = autoLink.name;
+          headElements.push({ tag: 'meta', attrs });
+        }
       }
     }
   }

package/src/server/route-matcher.ts

@@ -121,73 +121,105 @@ export interface MetadataRouteMatch {
    * that should be served from disk rather than executed as a handler.
    */
   isStatic: boolean;
+  /** Extracted segment params from dynamic segments in the URL prefix. */
+  segmentParams: Record<string, string | string[]>;
+}
+
+// Reverse lookup: serve path → convention base name
+const SERVE_PATH_TO_CONVENTION = new Map<string, string>();
+for (const [baseName, convention] of Object.entries(METADATA_ROUTE_CONVENTIONS)) {
+  SERVE_PATH_TO_CONVENTION.set(convention.servePath, baseName);
 }
 
 /**
  * Create a metadata route matcher from a manifest.
  *
- * Walks the segment tree and builds a map from serve paths to handler modules.
- * Metadata routes are matched by exact pathname (e.g., /sitemap.xml, /blog/sitemap.xml).
+ * Uses dynamic tree matching to resolve metadata routes, supporting
+ * dynamic segments like /docs/[slug]/opengraph-image.
  *
  * See design/16-metadata.md §"Metadata Routes"
  */
 export function createMetadataRouteMatcher(
   manifest: ManifestRoot
 ): (pathname: string) => MetadataRouteMatch | null {
-  // Build a static lookup map: pathname → match info
-  const routeMap = new Map<string, MetadataRouteMatch>();
-  collectMetadataRoutes(manifest.root, routeMap);
+  return (pathname: string) => matchMetadataPathname(manifest.root, pathname);
+}
+
+/**
+ * Match a pathname against metadata routes in the segment tree.
+ *
+ * Checks if the last URL part is a known metadata route serve path,
+ * then walks the tree to find the segment that owns the route.
+ */
+function matchMetadataPathname(
+  root: ManifestSegmentNode,
+  pathname: string
+): MetadataRouteMatch | null {
+  const parts = pathname === '/' ? [] : pathname.slice(1).split('/');
+  if (parts.length === 0) return null;
+
+  const lastPart = parts[parts.length - 1];
+  const baseName = SERVE_PATH_TO_CONVENTION.get(lastPart);
+  if (!baseName) return null;
+
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return null;
+
+  // The prefix parts identify which segment owns this metadata route.
+  // For root-level routes (e.g. /sitemap.xml), prefix is empty → root segment.
+  const prefixParts = parts.slice(0, -1);
+
+  let segment: ManifestSegmentNode;
+  let params: Record<string, string | string[]>;
+
+  if (prefixParts.length === 0) {
+    segment = root;
+    params = {};
+  } else {
+    const result = matchUrlParts(root, prefixParts, { requireTerminal: false });
+    if (!result) return null;
+    segment = result.chain[result.chain.length - 1];
+    params = result.params;
+  }
+
+  // Non-nestable routes (robots, manifest, favicon) only serve from root
+  if (!convention.nestable && segment !== root) return null;
 
-  return (pathname: string) => routeMap.get(pathname) ?? null;
+  const file = findMetadataRouteInSegment(segment, baseName);
+  if (!file) return null;
+
+  const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
+  const isStatic = isStaticMetadataExtension(baseName, ext);
+  const contentType = isStatic
+    ? resolveStaticContentType(convention.contentType, ext)
+    : convention.contentType;
+
+  return {
+    type: convention.type,
+    contentType,
+    file,
+    segment,
+    isStatic,
+    segmentParams: params,
+  };
 }
 
 /**
- * Recursively collect metadata routes from the segment tree into a lookup map.
+ * Find a metadata route file in a segment, including transparent group children.
+ * Groups don't add URL depth, so their metadata routes are reachable at the parent's path.
  */
-function collectMetadataRoutes(
+function findMetadataRouteInSegment(
   node: ManifestSegmentNode,
-  map: Map<string, MetadataRouteMatch>
-): void {
-  if (node.metadataRoutes) {
-    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
-      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
-      if (!convention) continue;
-
-      // Non-nestable routes (robots, manifest, favicon) only serve from root
-      if (!convention.nestable && node.urlPath !== '/') continue;
-
-      // Build the serve pathname: segment urlPath + serve path
-      const prefix = node.urlPath === '/' ? '' : node.urlPath;
-      const pathname = `${prefix}/${convention.servePath}`;
-
-      // Determine if this is a static file based on its extension.
-      // Static files (.xml, .txt, .png, .ico, etc.) are served from disk.
-      // Dynamic files (.ts, .tsx) export a handler function.
-      const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
-      const isStatic = isStaticMetadataExtension(baseName, ext);
-
-      // Resolve generic content types (e.g. image/*) to concrete MIME types
-      // based on the file extension for static files.
-      const contentType = isStatic
-        ? resolveStaticContentType(convention.contentType, ext)
-        : convention.contentType;
-
-      map.set(pathname, {
-        type: convention.type,
-        contentType,
-        file,
-        segment: node,
-        isStatic,
-      });
-    }
+  baseName: string
+): ManifestFile | null {
+  if (node.metadataRoutes?.[baseName]) {
+    return node.metadataRoutes[baseName];
   }
-
   for (const child of node.children) {
-    collectMetadataRoutes(child, map);
-  }
-
-  // Also check inside group segments (they're transparent for URL paths)
-  for (const slotNode of Object.values(node.slots)) {
-    collectMetadataRoutes(slotNode, map);
+    if (child.segmentType === 'group') {
+      const found = findMetadataRouteInSegment(child, baseName);
+      if (found) return found;
+    }
   }
+  return null;
 }

package/src/server/rsc-entry/index.ts

@@ -444,7 +444,13 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // AccessGate → getSegmentParams() throws because segmentParams
       // is never set. See TIM-667.
       setSegmentParams(revalidateMatch.segmentParams);
-      const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
+      const routeResult = await buildRouteElement(
+        revalidateReq,
+        revalidateMatch,
+        undefined,
+        null,
+        (buildManifest as BuildManifest).metadataRouteHashes
+      );
       return {
         element: routeResult.element,
         headElements: routeResult.headElements,

package/src/server/rsc-entry/render-route.ts

@@ -108,7 +108,13 @@ export async function renderRoute(
   let routeResult;
   const _buildStart = performance.now();
   try {
-    routeResult = await buildRouteElement(req, match, interception, clientStateTree);
+    routeResult = await buildRouteElement(
+      req,
+      match,
+      interception,
+      clientStateTree,
+      buildManifest.metadataRouteHashes
+    );
   } catch (error) {
     // Param coercion failed — render the custom 404 page (status files / not-found).
     // Previously returned a bare Response(null, { status: 404 }) which bypassed

package/src/server/ssr-entry.ts

@@ -18,6 +18,12 @@ import config from 'virtual:timber-config';
 // during SSR can serialize flat `Partial<T>` values via registry lookup.
 // @ts-expect-error — virtual module provided by timber-routing plugin
 import 'virtual:timber-search-params-registry';
+// TIM-949: Populate the codec registry so server-rendered <Link> components
+// use codec.serialize() instead of String() fallback for URL interpolation.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import schemaCodecs from 'virtual:timber-schema';
+import { setLinkCodecs } from '../params/codec-registry.js';
+setLinkCodecs(schemaCodecs);
 import {
   createFromReadableStream,
   createFromNodeStream,

package/src/server/tree-match.ts

@@ -27,6 +27,15 @@ export interface TreeMatchResult<TFile> {
   params: Record<string, string | string[]>;
 }
 
+export interface TreeMatchOptions {
+  /**
+   * When true (default), only match if the leaf node has a page or route
+   * handler. Set to false for metadata route matching, where we just need
+   * to find the owning segment regardless of whether it has a page.
+   */
+  requireTerminal?: boolean;
+}
+
 /**
  * Match URL path parts against a segment tree.
  *
@@ -34,9 +43,9 @@ export interface TreeMatchResult<TFile> {
  * ordering globally across group boundaries. Returns the matched
  * segment chain and collected params, or null if no route matches.
  *
- * A match requires a terminal node (one with `page` or `route`) at
- * the leaf. Catch-all and optional-catch-all segments only match if
- * they are terminal.
+ * By default, a match requires a terminal node (one with `page` or
+ * `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+ * any segment (used by metadata route matching).
  *
  * @param root  The root segment node to start matching from.
  * @param parts URL path parts (e.g. ['blog', 'hello-world']).
@@ -44,12 +53,14 @@ export interface TreeMatchResult<TFile> {
  */
 export function matchUrlParts<TFile>(
   root: SegmentNode<TFile>,
-  parts: string[]
+  parts: string[],
+  options?: TreeMatchOptions
 ): TreeMatchResult<TFile> | null {
   const chain: SegmentNode<TFile>[] = [];
   const params: Record<string, string | string[]> = {};
+  const requireTerminal = options?.requireTerminal ?? true;
 
-  if (matchNode(root, parts, 0, chain, params)) {
+  if (matchNode(root, parts, 0, chain, params, requireTerminal)) {
     return { chain, params };
   }
   return null;
@@ -107,19 +118,20 @@ function matchNode<TFile>(
   parts: string[],
   index: number,
   chain: SegmentNode<TFile>[],
-  params: Record<string, string | string[]>
+  params: Record<string, string | string[]>,
+  requireTerminal: boolean
 ): boolean {
   chain.push(node);
 
-  // All parts consumed — check if this node is terminal
+  // All parts consumed — check if this node is terminal (or any node if !requireTerminal)
   if (index >= parts.length) {
-    if (isTerminal(node)) return true;
+    if (!requireTerminal || isTerminal(node)) return true;
 
     // Groups don't consume URL segments, so a group child's page can
     // match at the same URL depth. Recurse into groups transparently.
     for (const child of node.children) {
       if (child.segmentType === 'group') {
-        if (matchNode(child, parts, index, chain, params)) {
+        if (matchNode(child, parts, index, chain, params, requireTerminal)) {
           return true;
         }
       }
@@ -149,7 +161,7 @@ function matchNode<TFile>(
   for (const { child, groupChain } of effective) {
     if (child.segmentType === 'static' && child.segmentName === part) {
       chain.push(...groupChain);
-      if (matchNode(child, parts, index + 1, chain, params)) {
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
         return true;
       }
       chain.length -= groupChain.length;
@@ -162,7 +174,7 @@ function matchNode<TFile>(
       chain.push(...groupChain);
       const prev = params[child.paramName];
       params[child.paramName] = part;
-      if (matchNode(child, parts, index + 1, chain, params)) {
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
         return true;
       }
       // Backtrack

package/src/server/types.ts

@@ -176,7 +176,7 @@ export namespace MetadataRoute {
  * This is a structural union — the pipeline dispatches on the shape at
  * request time (see `pipeline-phases.ts`):
  *   - `Response` → returned as-is (e.g. `ImageResponse`, `Response.redirect()`).
- *     Used by `icon.tsx`, `opengraph-image.tsx`, `twitter-image.tsx`,
+ *     Used by `icon.tsx`, `opengraph-image.tsx`,
  *     `apple-icon.tsx`.
  *   - `string` → written as the response body verbatim. Used by `robots.ts`
  *     and by any handler that wants to emit a pre-serialized payload.
@@ -192,7 +192,7 @@ export type MetadataResult = Response | string | MetadataRoute.Sitemap | Metadat
 /**
  * Default export signature for a dynamic metadata route file
  * (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.tsx`,
- * `opengraph-image.tsx`, `twitter-image.tsx`, `apple-icon.tsx`).
+ * `opengraph-image.tsx`, `apple-icon.tsx`).
  *
  * Parameterize `TResult` to narrow the return type for a specific route:
  *