@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/server/metadata-collector.ts

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ *
+ * MetadataCollector is synchronous: it starts dynamic metadata() calls
+ * without awaiting and pushes the promise into the entries array, then
+ * returns children immediately. This lets React descend into the page
+ * subtree while metadata I/O runs concurrently (TIM-1367). A sibling
+ * MetadataSettle component awaits the promise so errors surface at the
+ * collector's tree position (caught by that segment's error boundary).
+ *
+ * MetadataHead is async: it awaits all entry promises before merging.
+ * Ordering is guaranteed by tree position — ancestor collectors push
+ * before MetadataHead renders.
+ *
+ * AccessGate denial prevents MetadataCollector from rendering, so
+ * metadata() never starts for denied segments (TIM-1027).
+ *
+ * See TIM-1363, TIM-1367, design/16-metadata.md.
+ */
+
+import { createElement, Fragment } from 'react';
+import type { ReactNode } from 'react';
+
+import { requestContextAls } from './als-registry.ts';
+import type { Metadata } from './types.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { withSpan } from './tracing.ts';
+import { resolveMetadata, renderMetadataToElements, headElementsToReact } from './metadata.ts';
+import type { SegmentMetadataEntry } from './metadata.ts';
+import { collectMetadataRouteHeadElements } from './metadata-routes.ts';
+
+// ─── Request-scoped metadata entry store ────────────────────────────────
+
+/**
+ * Internal entry type that supports deferred (promise) metadata for
+ * concurrent resolution (TIM-1367). Dynamic metadata pushes a promise;
+ * static metadata pushes the resolved object directly.
+ */
+interface DeferredMetadataEntry {
+  metadata: Metadata | Promise<Metadata | null>;
+  isPage: boolean;
+}
+
+function getDeferredMetadataEntries(): DeferredMetadataEntry[] {
+  const store = requestContextAls.getStore();
+  if (!store) return [];
+  store._metadataEntries ??= [];
+  return store._metadataEntries as DeferredMetadataEntry[];
+}
+
+// ─── MetadataSettle ─────────────────────────────────────────────────────
+
+interface MetadataSettleProps {
+  promise: Promise<Metadata | null>;
+}
+
+/**
+ * Tiny async server component rendered as a sibling of the collector's
+ * children. Its sole job is error ownership: awaiting the metadata
+ * promise so that rejections surface at THIS tree position (caught by
+ * the owning segment's error boundary, not MetadataHead's).
+ */
+async function MetadataSettle(props: MetadataSettleProps): Promise<ReactNode> {
+  await props.promise;
+  return null;
+}
+
+// ─── MetadataCollector ──────────────────────────────────────────────────
+
+export interface MetadataCollectorProps {
+  metadataExport: Metadata | (() => Promise<Metadata>);
+  segmentName: string;
+  isPage: boolean;
+  children: ReactNode;
+}
+
+/**
+ * Synchronous 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 starts for denied segments (TIM-1027).
+ *
+ * Static metadata objects are pushed synchronously (no side effects).
+ * Dynamic metadata functions are started (not awaited) and pushed as
+ * promises — React descends into children immediately while the I/O
+ * runs concurrently (TIM-1367). A sibling MetadataSettle component
+ * awaits the promise for error ownership.
+ */
+export function MetadataCollector(props: MetadataCollectorProps): ReactNode {
+  const { metadataExport, segmentName, isPage, children } = props;
+
+  if (typeof metadataExport === 'function') {
+    const promise = withSpan('timber.metadata', { 'timber.segment': segmentName }, () =>
+      (metadataExport as () => Promise<Metadata>)()
+    ).then((v) => v ?? null);
+    // Suppress unhandled rejection — MetadataSettle and MetadataHead
+    // both attach handlers, but a fast-rejecting promise can fire
+    // Node's unhandledRejection before they do.
+    promise.catch(() => {});
+
+    getDeferredMetadataEntries().push({ metadata: promise, isPage });
+
+    return createElement(Fragment, null, children, createElement(MetadataSettle, { promise }));
+  }
+
+  getDeferredMetadataEntries().push({ metadata: metadataExport, isPage });
+  return children;
+}
+
+// ─── MetadataHead ───────────────────────────────────────────────────────
+
+export interface MetadataHeadProps {
+  segments: ManifestSegmentNode[];
+  requestUrl: string;
+  metadataRouteHashes?: Record<string, string>;
+}
+
+/**
+ * Async server component that awaits all deferred metadata promises,
+ * merges entries, auto-links metadata routes, and renders Float-
+ * hoisted head elements.
+ *
+ * Rendered as a SIBLING of the page element (not a wrapper) so React
+ * processes both concurrently — the page starts rendering immediately
+ * while MetadataHead awaits metadata promises. Both resolve before
+ * onShellReady (they're outside Suspense), but they overlap. Float
+ * hoists the head elements to <head> regardless of tree position.
+ *
+ * Ordering is guaranteed by tree position: every MetadataCollector
+ * is an ancestor of the Fragment containing MetadataHead, so its
+ * synchronous push into the entries array happens-before MetadataHead
+ * executes.
+ *
+ * See TIM-1367 for the concurrent resolution design.
+ */
+export async function MetadataHead(props: MetadataHeadProps): Promise<ReactNode> {
+  const { segments, requestUrl, metadataRouteHashes } = props;
+  const deferredEntries = getDeferredMetadataEntries();
+
+  // Resolve all deferred metadata concurrently. Rejected entries are
+  // dropped — their errors are surfaced by MetadataSettle at the
+  // owning segment's error boundary, not here.
+  const settled = await Promise.allSettled(
+    deferredEntries.map((e) =>
+      e.metadata instanceof Promise ? e.metadata : Promise.resolve(e.metadata)
+    )
+  );
+  const entries: SegmentMetadataEntry[] = [];
+  for (let i = 0; i < settled.length; i++) {
+    const s = settled[i];
+    if (s.status === 'fulfilled' && s.value) {
+      entries.push({ metadata: s.value, isPage: deferredEntries[i].isPage });
+    }
+  }
+
+  const resolved = resolveMetadata(entries);
+  const headElements = renderMetadataToElements(resolved);
+
+  const autoLinked = collectMetadataRouteHeadElements(
+    segments,
+    Infinity,
+    resolved,
+    new URL(requestUrl),
+    metadataRouteHashes
+  );
+  headElements.push(...autoLinked);
+
+  return headElementsToReact(headElements);
+}

package/src/server/metadata-platform.ts

@@ -6,8 +6,8 @@
  * See design/16-metadata.md
  */
 
-import type { Metadata } from './types.js';
-import type { HeadElement } from './metadata.js';
+import type { Metadata } from './types.ts';
+import type { HeadElement } from './metadata.ts';
 
 /**
  * Render icon link elements (favicon, shortcut, apple-touch-icon, custom).

package/src/server/metadata-render.ts

@@ -6,9 +6,9 @@
  * See design/16-metadata.md
  */
 
-import type { Metadata } from './types.js';
-import type { HeadElement } from './metadata.js';
-import { renderOpenGraph, renderTwitter } from './metadata-social.js';
+import type { Metadata } from './types.ts';
+import type { HeadElement } from './metadata.ts';
+import { renderOpenGraph, renderTwitter } from './metadata-social.ts';
 import {
   renderIcons,
   renderAlternates,
@@ -16,7 +16,7 @@ import {
   renderAppleWebApp,
   renderAppLinks,
   renderItunes,
-} from './metadata-platform.js';
+} from './metadata-platform.ts';
 
 // ─── Render to Elements ──────────────────────────────────────────────────────
 
@@ -78,14 +78,36 @@ export function renderMetadataToElements(metadata: Metadata): HeadElement[] {
     }
   }
 
-  // Open Graph
+  // Open Graph — inherit title/description from top-level when not set explicitly
   if (metadata.openGraph) {
-    renderOpenGraph(metadata.openGraph, elements);
+    const og = { ...metadata.openGraph };
+    if (og.title === undefined && typeof metadata.title === 'string') {
+      og.title = metadata.title;
+    }
+    if (og.description === undefined && metadata.description) {
+      og.description = metadata.description;
+    }
+    renderOpenGraph(og, elements);
   }
 
-  // Twitter
+  // Twitter — inherit title/description from openGraph or top-level when not set
   if (metadata.twitter) {
-    renderTwitter(metadata.twitter, elements);
+    const tw = { ...metadata.twitter };
+    if (tw.title === undefined) {
+      tw.title =
+        metadata.openGraph?.title !== undefined
+          ? metadata.openGraph.title
+          : typeof metadata.title === 'string'
+            ? metadata.title
+            : undefined;
+    }
+    if (tw.description === undefined) {
+      tw.description =
+        metadata.openGraph?.description !== undefined
+          ? metadata.openGraph.description
+          : metadata.description;
+    }
+    renderTwitter(tw, elements);
   }
 
   // Icons

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.ts';
+import type { Metadata } from './types.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+
 // ─── 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-social.ts

@@ -6,8 +6,8 @@
  * See design/16-metadata.md
  */
 
-import type { Metadata } from './types.js';
-import type { HeadElement } from './metadata.js';
+import type { Metadata } from './types.ts';
+import type { HeadElement } from './metadata.ts';
 
 /**
  * Render Open Graph metadata into head element descriptors.

package/src/server/metadata.ts

@@ -12,11 +12,32 @@
  * See design/16-metadata.md
  */
 
-import type { Metadata } from './types.js';
+import { createElement, Fragment } from 'react';
+import type { Metadata } from './types.ts';
 
 // 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';
+export { renderMetadataToElements } from './metadata-render.ts';
+
+/**
+ * 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 ───────────────────────────────────────────────────────────────────
 

package/src/server/middleware-runner.ts

@@ -1,14 +1,14 @@
 /**
- * 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"
  */
 
-import type { MiddlewareContext } from './types.js';
+import type { MiddlewareContext } from './types.ts';
 
 /** Signature of a middleware.ts default export. */
 export type MiddlewareFn = (ctx: MiddlewareContext) => Response | void | Promise<Response | void>;
@@ -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;
+}