@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/server/metadata-collector.ts

@@ -0,0 +1,115 @@
+/**
+ * Render-time metadata resolution components.
+ *
+ * MetadataCollector runs below AccessGate for each segment, collecting
+ * metadata entries into a request-scoped array. MetadataHead runs at
+ * the page level, merging all collected entries and rendering Float-
+ * hoisted head elements.
+ *
+ * This structural approach replaces the eager pre-render metadata
+ * resolution: a denied segment's AccessGate prevents MetadataCollector
+ * from rendering, so metadata() never executes for denied segments.
+ * No `firstDeniedIndex` bookkeeping needed.
+ *
+ * See TIM-1363, design/16-metadata.md.
+ */
+
+import { createElement, Fragment } from 'react';
+import type { ReactNode } from 'react';
+
+import { requestContextAls } from './als-registry.js';
+import type { Metadata } from './types.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { withSpan } from './tracing.js';
+import { resolveMetadata, renderMetadataToElements, headElementsToReact } from './metadata.js';
+import type { SegmentMetadataEntry } from './metadata.js';
+import { collectMetadataRouteHeadElements } from './metadata-routes.js';
+
+// ─── Request-scoped metadata entry store ────────────────────────────────
+
+function getMetadataEntries(): SegmentMetadataEntry[] {
+  const store = requestContextAls.getStore();
+  if (!store) return [];
+  store._metadataEntries ??= [];
+  return store._metadataEntries;
+}
+
+// ─── MetadataCollector ──────────────────────────────────────────────────
+
+export interface MetadataCollectorProps {
+  metadataExport: Metadata | (() => Promise<Metadata>);
+  segmentName: string;
+  isPage: boolean;
+  onSettled?: () => void;
+  children: ReactNode;
+}
+
+/**
+ * Async server component that collects one segment's metadata during
+ * render. Placed between AccessGate and the layout/page. When
+ * AccessGate denies, this component never renders, so dynamic
+ * metadata() never executes for denied segments (TIM-1027).
+ *
+ * Static metadata objects are pushed synchronously (no side effects).
+ * Dynamic metadata functions are awaited with OTEL tracing.
+ */
+export async function MetadataCollector(props: MetadataCollectorProps): Promise<ReactNode> {
+  const { metadataExport, segmentName, isPage, onSettled, children } = props;
+
+  try {
+    let metadata: Metadata | null = null;
+    if (typeof metadataExport === 'function') {
+      metadata =
+        (await withSpan('timber.metadata', { 'timber.segment': segmentName }, () =>
+          (metadataExport as () => Promise<Metadata>)()
+        )) ?? null;
+    } else {
+      metadata = metadataExport;
+    }
+
+    if (metadata) {
+      getMetadataEntries().push({ metadata, isPage });
+    }
+
+    return children;
+  } finally {
+    onSettled?.();
+  }
+}
+
+// ─── MetadataHead ───────────────────────────────────────────────────────
+
+export interface MetadataHeadProps {
+  segments: ManifestSegmentNode[];
+  requestUrl: string;
+  metadataRouteHashes?: Record<string, string>;
+  children: ReactNode;
+}
+
+/**
+ * Server component at the page level. Reads all metadata entries
+ * collected by MetadataCollector components above it, merges them,
+ * auto-links metadata routes, and renders Float-hoisted head elements.
+ *
+ * Placed as a sibling of the page element inside a Fragment so the
+ * Float elements are always at the page segment level (re-rendered
+ * on every SPA navigation, never skipped by segment tree diffing).
+ */
+export function MetadataHead(props: MetadataHeadProps): ReactNode {
+  const { segments, requestUrl, metadataRouteHashes, children } = props;
+  const entries = getMetadataEntries();
+  const resolved = resolveMetadata(entries);
+  const headElements = renderMetadataToElements(resolved);
+
+  const autoLinked = collectMetadataRouteHeadElements(
+    segments,
+    Infinity,
+    resolved,
+    new URL(requestUrl),
+    metadataRouteHashes
+  );
+  headElements.push(...autoLinked);
+
+  const metadataElement = headElementsToReact(headElements);
+  return createElement(Fragment, null, metadataElement, children);
+}

package/src/server/metadata-routes.ts

@@ -10,6 +10,11 @@
  * See design/16-metadata.md §"Metadata Routes"
  */
 
+import { randomUUID } from 'node:crypto';
+import type { HeadElement } from './metadata.js';
+import type { Metadata } from './types.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 /** Classification of a metadata route file. */
@@ -29,7 +34,6 @@ export type MetadataRouteType =
   | 'favicon'
   | 'icon'
   | 'opengraph-image'
-  | 'twitter-image'
   | 'apple-icon';
 
 // ─── Convention Table ────────────────────────────────────────────────────────
@@ -51,8 +55,18 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     nestable: boolean;
     staticExtensions: string[];
     dynamicExtensions: string[];
-    /** The URL path this file serves at (relative to segment). */
+    /**
+     * The URL path basename this file serves at (relative to segment).
+     * For image routes, the full serve path includes an extension via
+     * `resolveServePathForFile()`.
+     */
     servePath: string;
+    /**
+     * When set, image routes append `.{serveExtension}` to the serve path.
+     * Dynamic handlers (`.ts`/`.tsx`) use this as the default. Static files
+     * use their own extension instead. Non-image routes leave this undefined.
+     */
+    serveExtension?: string;
   }
 > = {
   'sitemap': {
@@ -84,7 +98,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     contentType: 'image/x-icon',
     nestable: false,
     staticExtensions: ['ico'],
-    dynamicExtensions: [],
+    dynamicExtensions: ['ts', 'tsx'],
     servePath: 'favicon.ico',
   },
   'icon': {
@@ -94,6 +108,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     staticExtensions: ['png', 'jpg', 'svg'],
     dynamicExtensions: ['ts', 'tsx'],
     servePath: 'icon',
+    serveExtension: 'png',
   },
   'opengraph-image': {
     type: 'opengraph-image',
@@ -102,15 +117,9 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     staticExtensions: ['png', 'jpg'],
     dynamicExtensions: ['ts', 'tsx'],
     servePath: 'opengraph-image',
+    serveExtension: 'png',
   },
-  '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/*',
@@ -118,6 +127,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     staticExtensions: ['png'],
     dynamicExtensions: ['ts', 'tsx'],
     servePath: 'apple-icon',
+    serveExtension: 'png',
   },
 };
 
@@ -213,38 +223,209 @@ export function classifyMetadataRoute(fileName: string): MetadataRouteInfo | nul
 }
 
 /**
- * Get the serve path for a metadata route type.
+ * Resolve the serve path for a metadata route file.
  *
- * @param type - The metadata route type
- * @returns The URL path fragment this route serves at
+ * For image routes (icon, opengraph-image, apple-icon), the serve path includes
+ * a file extension so CDNs cache correctly:
+ * - Dynamic handlers (.ts/.tsx) use the convention's `serveExtension` (default: .png)
+ * - Static files use their own extension (e.g., icon.svg → icon.svg)
+ *
+ * Non-image routes return the convention's `servePath` as-is (already includes
+ * extension: sitemap.xml, robots.txt, etc.).
+ */
+export function resolveServePathForFile(baseName: string, filePath: string): string {
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return baseName;
+
+  if (!convention.serveExtension) return convention.servePath;
+
+  const ext = filePath.slice(filePath.lastIndexOf('.') + 1);
+  if (convention.staticExtensions.includes(ext)) {
+    return `${convention.servePath}.${ext}`;
+  }
+  return `${convention.servePath}.${convention.serveExtension}`;
+}
+
+/**
+ * Get the default serve path for a metadata route type (using default extension
+ * for image routes). Used for auto-link generation when only the type is known.
  */
 export function getMetadataRouteServePath(type: MetadataRouteType): string {
   for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {
-    if (convention.type === type) return convention.servePath;
+    if (convention.type === type) {
+      if (convention.serveExtension) {
+        return `${convention.servePath}.${convention.serveExtension}`;
+      }
+      return convention.servePath;
+    }
   }
   throw new Error(`[timber] Unknown metadata route type: ${type}`);
 }
 
+/**
+ * All possible serve path segments for metadata routes (includes extension
+ * variants for image routes).
+ */
+const METADATA_SERVE_PATHS = new Set<string>();
+for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {
+  if (convention.serveExtension) {
+    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {
+      METADATA_SERVE_PATHS.add(`${convention.servePath}.${ext}`);
+    }
+  } else {
+    METADATA_SERVE_PATHS.add(convention.servePath);
+  }
+}
+
+export function isMetadataRouteServePath(pathname: string): boolean {
+  let lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+  const qIdx = lastSegment.indexOf('?');
+  let query = '';
+  if (qIdx !== -1) {
+    query = lastSegment.slice(qIdx + 1);
+    lastSegment = lastSegment.slice(0, qIdx);
+  }
+  if (!METADATA_SERVE_PATHS.has(lastSegment)) return false;
+  // Vite module requests (e.g., /src/icon.svg?import) use special query params.
+  // These are source assets, not metadata routes.
+  if (/(?:^|&)(?:import|url|raw|worker|inline)(?:&|$)/.test(query)) return false;
+  return true;
+}
+
+/** 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 [];
+  }
+}
+
+// ─── Auto-Linking ──────────────────────────────────────────────────────────
+
+// 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;
+}
+
+/**
+ * Collect auto-linked head elements from metadata route files in the segment chain.
+ *
+ * Walks each segment's metadataRoutes, resolves serve paths and URLs, and
+ * emits HeadElement descriptors for <link> and <meta> tags that React Float
+ * hoists into <head>.
+ *
+ * See design/16-metadata.md §"Auto-Linking"
+ */
+export function collectMetadataRouteHeadElements(
+  segments: ManifestSegmentNode[],
+  firstDeniedIndex: number,
+  resolvedMetadata: Metadata,
+  requestUrl: URL,
+  metadataRouteHashes?: Record<string, string>
+): HeadElement[] {
+  const elements: HeadElement[] = [];
+  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);
+  const hasUserTwitterImage = Boolean(resolvedMetadata.twitter?.images);
+  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 (let si = 0; si < segments.length; si++) {
+    const segment = segments[si];
+    if (!segment.metadataRoutes) continue;
+    if (si >= firstDeniedIndex) continue;
+    for (const baseName of Object.keys(segment.metadataRoutes)) {
+      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+      if (!convention) continue;
+      if (!convention.nestable && segment.urlPath !== '/') continue;
+      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;
+      const resolvedPrefix = convention.nestable
+        ? requestPathname === '/'
+          ? ''
+          : requestPathname
+        : '';
+      const metaFile = segment.metadataRoutes[baseName];
+      const fileServePath = metaFile?.filePath
+        ? resolveServePathForFile(baseName, metaFile.filePath)
+        : convention.serveExtension
+          ? `${convention.servePath}.${convention.serveExtension}`
+          : convention.servePath;
+      let href = `${resolvedPrefix}/${fileServePath}`;
+      if (convention.type === 'opengraph-image') {
+        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;
+        const cacheBust = fileHash ?? getDevNonce();
+        href = `${href}?${cacheBust}`;
+      }
+      if (ogBase && convention.type === 'opengraph-image') {
+        href = new URL(href, ogBase).toString();
+      }
+      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {
+        if (
+          hasUserTwitterImage &&
+          autoLink.tag === 'meta' &&
+          'name' in autoLink &&
+          autoLink.name === 'twitter:image'
+        )
+          continue;
+        if (autoLink.tag === 'link') {
+          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
+          if (autoLink.type) attrs.type = autoLink.type;
+          elements.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;
+          elements.push({ tag: 'meta', attrs });
+        }
+      }
+    }
   }
+  return elements;
 }

package/src/server/metadata.ts

@@ -12,12 +12,33 @@
  * See design/16-metadata.md
  */
 
+import { createElement, Fragment } from 'react';
 import type { Metadata } from './types.js';
 
 // Re-export renderMetadataToElements from the rendering module so existing
 // consumers (route-element-builder, tests) can keep importing from here.
 export { renderMetadataToElements } from './metadata-render.js';
 
+/**
+ * Convert HeadElement descriptors to React elements for Float hoisting.
+ *
+ * React 19 Float hoists <title>, <meta>, and <link> rendered anywhere in
+ * the tree into <head> during SSR, and manages them in document.head
+ * during client-side rendering.
+ */
+export function headElementsToReact(elements: HeadElement[]): React.ReactElement {
+  const children: React.ReactElement[] = [];
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (el.tag === 'title' && el.content !== undefined) {
+      children.push(createElement('title', { key: `t${i}` }, el.content));
+    } else if (el.attrs) {
+      children.push(createElement(el.tag, { key: `h${i}`, ...el.attrs }));
+    }
+  }
+  return createElement(Fragment, null, ...children);
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 /** A single metadata entry from a layout or page module. */

package/src/server/middleware-runner.ts

@@ -1,9 +1,9 @@
 /**
- * Middleware runner — executes a route's middleware.ts before rendering.
+ * Middleware runner — executes a route's middleware.ts chain before rendering.
  *
- * Only the leaf route's middleware runs. There is no middleware chain.
- * Middleware does NOT have next() — it either short-circuits with a Response
- * or returns void to continue to access checks + render.
+ * All middleware.ts files in the segment chain run, root to leaf (top-down).
+ * The first middleware that returns a Response short-circuits the chain.
+ * There is no next() — each middleware is independent.
  *
  * See design/07-routing.md §"middleware.ts"
  */
@@ -30,3 +30,30 @@ export async function runMiddleware(
   }
   return undefined;
 }
+
+/**
+ * Run all middleware functions in the segment chain, root to leaf.
+ *
+ * Execution is top-down: root middleware runs first, leaf middleware runs last.
+ * All middleware share the same MiddlewareContext — a parent that sets
+ * ctx.requestHeaders makes it visible to child middleware and downstream components.
+ *
+ * Short-circuits on the first middleware that returns a Response.
+ * Remaining middleware in the chain do not execute.
+ *
+ * @param chain - Middleware functions ordered root-to-leaf
+ * @param ctx - Shared middleware context
+ * @returns A Response if any middleware short-circuited, or undefined to continue
+ */
+export async function runMiddlewareChain(
+  chain: MiddlewareFn[],
+  ctx: MiddlewareContext
+): Promise<Response | undefined> {
+  for (const fn of chain) {
+    const result = await fn(ctx);
+    if (result instanceof Response) {
+      return result;
+    }
+  }
+  return undefined;
+}