@timber-js/app 0.2.0-alpha.170 → 0.2.0-alpha.172

package/src/client/segment-cache.ts

@@ -23,10 +23,20 @@ export interface SegmentNode {
   segment: string;
   /** The RSC flight payload for this segment (opaque to the cache) */
   payload: unknown;
-  /** Whether the segment is async (async layouts always re-render on navigation) */
-  isAsync: boolean;
+  /**
+   * Whether the segment/slot is request-dependent (calls getHeaders,
+   * getSearchParams, cookies, etc.). Request-dependent segments always
+   * re-render on navigation. For segments, this is still based on the
+   * AsyncFunction heuristic (to be replaced separately). For slots,
+   * this is taint-tracked via ALS.
+   */
+  isRequestDependent: boolean;
   /** Child segments keyed by segment path */
   children: Map<string, SegmentNode>;
+  /** Parallel route slots keyed by slot path (e.g., "/@sidebar") */
+  slots?: Map<string, SegmentNode>;
+  /** Whether this slot's access.ts denied on its last render. */
+  denied?: boolean;
 }
 
 /**
@@ -35,6 +45,7 @@ export interface SegmentNode {
  */
 export interface StateTree {
   segments: string[];
+  slots?: string[];
 }
 
 // ─── Segment Cache ───────────────────────────────────────────────
@@ -79,10 +90,16 @@ export class SegmentCache {
    */
   serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
+    const slots: string[] = [];
     if (this.root) {
       collectSyncSegments(this.root, segments, mergeableFilter);
+      collectSyncSlots(this.root, slots);
+    }
+    const tree: StateTree = { segments };
+    if (slots.length > 0) {
+      tree.slots = slots;
     }
-    return { segments };
+    return tree;
   }
 }
 
@@ -92,7 +109,7 @@ function collectSyncSegments(
   out: string[],
   mergeableFilter?: Set<string>
 ): void {
-  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {
+  if (!node.isRequestDependent && (!mergeableFilter || mergeableFilter.has(node.segment))) {
     out.push(node.segment);
   }
   for (const child of node.children.values()) {
@@ -100,6 +117,22 @@ function collectSyncSegments(
   }
 }
 
+/** Recursively collect cacheable slot paths from the tree */
+function collectSyncSlots(node: SegmentNode, out: string[]): void {
+  if (node.slots) {
+    for (const slot of node.slots.values()) {
+      // Exclude request-dependent slots (they must re-render every nav)
+      // and denied slots (their cached content is denial fallback, not real content)
+      if (!slot.isRequestDependent && !slot.denied) {
+        out.push(slot.segment);
+      }
+    }
+  }
+  for (const child of node.children.values()) {
+    collectSyncSlots(child, out);
+  }
+}
+
 // ─── Segment Tree Builder ────────────────────────────────────────
 
 /**
@@ -110,7 +143,13 @@ export interface SegmentInfo {
   path: string;
   /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
   segmentId?: string;
-  isAsync: boolean;
+  isRequestDependent: boolean;
+  /** True for parallel route slot entries. Slots are keyed by their slot path (e.g., "/@sidebar"). */
+  slot?: boolean;
+  /** Parent segment path for slot entries. Used to attach the slot to the correct SegmentNode. */
+  parentSegment?: string;
+  /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
+  denied?: boolean;
 }
 
 /**
@@ -128,21 +167,34 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   // Need at least a root segment to build a tree
   if (segments.length === 0) return undefined;
 
-  // All entries are layout segments — the server filters out layoutless
-  // segments (including the page leaf) in buildSegmentInfo. Cache every
-  // entry; pages are never sent.
+  // Separate slot entries from segment entries. Slots are attached to
+  // their parent segment node after the main chain is built.
+  const segmentEntries: SegmentInfo[] = [];
+  const slotEntries: SegmentInfo[] = [];
+  for (const info of segments) {
+    if (info.slot) {
+      slotEntries.push(info);
+    } else {
+      segmentEntries.push(info);
+    }
+  }
+
+  // Build the main segment chain.
   let root: SegmentNode | undefined;
   let parent: SegmentNode | undefined;
+  const nodeById = new Map<string, SegmentNode>();
 
-  for (const info of segments) {
+  for (const info of segmentEntries) {
     const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
       segment: id,
       payload: null,
-      isAsync: info.isAsync,
+      isRequestDependent: info.isRequestDependent,
       children: new Map(),
     };
 
+    nodeById.set(id, node);
+
     if (!root) {
       root = node;
     }
@@ -154,6 +206,27 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
     parent = node;
   }
 
+  // Attach slot entries to their parent segment nodes.
+  for (const slotInfo of slotEntries) {
+    const parentId = slotInfo.parentSegment;
+    const parentNode = parentId ? nodeById.get(parentId) : root;
+    if (!parentNode) continue;
+
+    const slotId = slotInfo.segmentId ?? slotInfo.path;
+    const slotNode: SegmentNode = {
+      segment: slotId,
+      payload: null,
+      isRequestDependent: slotInfo.isRequestDependent,
+      children: new Map(),
+      denied: slotInfo.denied,
+    };
+
+    if (!parentNode.slots) {
+      parentNode.slots = new Map();
+    }
+    parentNode.slots.set(slotId, slotNode);
+  }
+
   return root;
 }
 

package/src/client/segment-outlet.tsx

@@ -32,12 +32,21 @@ export interface SegmentOutletProps {
    * Unique identifier for this segment. For normal segments this is the
    * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
    * group name (e.g., "/(marketing)") to distinguish siblings that share
-   * the same urlPath. Must match the segmentId used in state-tree-diff.ts.
+   * the same urlPath. For slots this includes the slot name (e.g., "/@sidebar").
+   * Must match the segmentId used in state-tree-diff.ts.
    */
   segmentPath: string;
 
   /** The segment's React subtree (layout + inner content). */
   children: ReactNode;
+
+  /**
+   * When true, the outlet returns cached content instead of rendering
+   * new children. Used for skipped parallel route slots — the server
+   * sends an empty SegmentOutlet with skip=true, and the client keeps
+   * the previously cached slot content.
+   */
+  skip?: boolean;
 }
 
 /**
@@ -52,7 +61,7 @@ export interface SegmentOutletProps {
  * when the same type appears at the same tree position. The ref persists
  * across navigations because SegmentOutlet is reconciled, not remounted.
  */
-export function SegmentOutlet({ segmentPath, children }: SegmentOutletProps) {
+export function SegmentOutlet({ segmentPath, children, skip }: SegmentOutletProps) {
   const updates = useContext(SegmentUpdateContext);
   const contentRef = useRef<ReactNode>(null);
 
@@ -63,6 +72,19 @@ export function SegmentOutlet({ segmentPath, children }: SegmentOutletProps) {
     return update;
   }
 
+  // Skipped slot: keep cached content. The server sends skip=true for
+  // parallel route slots whose matched content hasn't changed. React
+  // reconciles this SegmentOutlet with the previous one at the same
+  // tree position, so the ref (cached content) is preserved.
+  if (skip) {
+    if (contentRef.current !== null) {
+      return contentRef.current;
+    }
+    // No cached content — the SegmentOutlet instance is fresh (not
+    // reconciled from a previous render). Fall through to render
+    // children (null). The slot will be fully rendered next navigation.
+  }
+
   if (contentRef.current === null) {
     contentRef.current = children;
     return children;

package/src/client/slot-context.ts

@@ -8,18 +8,20 @@
  * SlotsProvider carrying the live slot values; each outlet reads its
  * value from this context by name.
  *
- * The value is a per-instance record — the NEAREST provider wins, so two
- * instances of the same cached component on one page each resolve their
- * own children, and a slot component nested inside another slot
- * component's children reads its own provider, not the outer one.
+ * Providers MERGE per-key with their parent: an inner SlotsProvider
+ * inherits the outer's values and overrides only the keys it declares.
+ * Two sibling instances each have their own provider and resolve
+ * independently. Layouts use a reserved slot name (LAYOUT_CHILDREN_SLOT)
+ * that cannot collide with user-declared slot names (TIM-1191).
  *
- * Generalizes the ChildSegmentContext pattern (TIM-1181) from a single
- * implicit `children` hole on layouts to explicitly declared, named slot
- * props on any cached component.
+ * Generalizes the original layout children pattern (TIM-1181) from a
+ * single implicit `children` hole on layouts to explicitly declared,
+ * named slot props on any cached component. Layouts use this same
+ * context with the reserved LAYOUT_CHILDREN_SLOT key (TIM-1191).
  *
  * SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
  * can duplicate this module across chunks; globalThis guarantees a single
- * context instance. Same pattern as ChildSegmentContext.
+ * context instance.
  *
  * See design/45-cache-lifetimes.md §Slot Components.
  */

package/src/client/slot-provider.tsx

@@ -2,6 +2,11 @@
  * SlotsProvider — wraps a revived cached shell to supply live slot content
  * to the SlotOutlet holes inside it (TIM-1173).
  *
+ * Values MERGE with the nearest parent provider so that nesting a
+ * cache.component SlotsProvider inside a layout SlotsProvider preserves
+ * the layout's `children` slot while adding the component's own slots.
+ * Inner values override outer ones with the same name (spread order).
+ *
  * Tree structure per cached-component instance:
  *   SlotsProvider(values={children: <Live />})
  *     └── revived shell
@@ -12,7 +17,7 @@
 
 'use client';
 
-import { createElement, type ReactNode } from 'react';
+import { createElement, useContext, type ReactNode } from 'react';
 import { SlotContext, type SlotValues } from './slot-context.js';
 
 interface SlotsProviderProps {
@@ -21,5 +26,7 @@ interface SlotsProviderProps {
 }
 
 export function SlotsProvider({ values, children }: SlotsProviderProps) {
-  return createElement(SlotContext.Provider, { value: values }, children);
+  const parent = useContext(SlotContext);
+  const merged = parent ? { ...parent, ...values } : values;
+  return createElement(SlotContext.Provider, { value: merged }, children);
 }

package/src/fonts/google.ts

@@ -43,6 +43,28 @@ function extractNetworkErrorCode(err: unknown): string | undefined {
   return undefined;
 }
 
+const MAX_RETRIES = 3;
+const MIN_TIMEOUT_MS = 100;
+
+async function retry<T>(fn: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < MAX_RETRIES) {
+        const delay = MIN_TIMEOUT_MS * 2 ** attempt;
+        console.error(
+          `${err instanceof Error ? err.message : String(err)}\n\nRetrying ${attempt + 1}/${MAX_RETRIES}...`
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+
 /** Google Fonts CSS API v2 base URL. */
 const GOOGLE_FONTS_API = 'https://fonts.googleapis.com/css2';
 
@@ -134,28 +156,31 @@ export function buildGoogleFontsUrl(font: ExtractedFont): string {
  * We parse each block to extract the font URL, unicode-range, and subset label.
  */
 export async function fetchGoogleFontsCss(url: string): Promise<GoogleFontFace[]> {
-  let response: Response;
-  try {
-    response = await fetch(url, {
-      headers: { 'User-Agent': WOFF2_USER_AGENT },
-    });
-  } catch (err) {
-    const code = extractNetworkErrorCode(err);
-    throw new Error(
-      `[timber] Failed to fetch Google Fonts CSS from ${url}` +
-        (code ? ` (${code})` : '') +
-        `. Build requires internet access for font optimization.` +
-        ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
-    );
-  }
+  const css = await retry(async () => {
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: { 'User-Agent': WOFF2_USER_AGENT },
+      });
+    } catch (err) {
+      const code = extractNetworkErrorCode(err);
+      throw new Error(
+        `[timber] Failed to fetch Google Fonts CSS from ${url}` +
+          (code ? ` (${code})` : '') +
+          `. Build requires internet access for font optimization.` +
+          ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+      );
+    }
 
-  if (!response.ok) {
-    throw new Error(
-      `Google Fonts API returned ${response.status}: ${response.statusText} for ${url}`
-    );
-  }
+    if (!response.ok) {
+      throw new Error(
+        `Google Fonts API returned ${response.status}: ${response.statusText} for ${url}`
+      );
+    }
+
+    return response.text();
+  });
 
-  const css = await response.text();
   return parseGoogleFontsCss(css);
 }
 
@@ -238,22 +263,24 @@ export function cacheKey(face: GoogleFontFace): string {
  * Download a single font file from its URL.
  */
 export async function downloadFontFile(url: string): Promise<Buffer> {
-  let response: Response;
-  try {
-    response = await fetch(url);
-  } catch (err) {
-    const code = extractNetworkErrorCode(err);
-    throw new Error(
-      `[timber] Failed to download font file from ${url}` +
-        (code ? ` (${code})` : '') +
-        `. Build requires internet access for font optimization.` +
-        ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
-    );
-  }
-  if (!response.ok) {
-    throw new Error(`Failed to download font from ${url}: ${response.status}`);
-  }
-  return Buffer.from(await response.arrayBuffer());
+  return retry(async () => {
+    let response: Response;
+    try {
+      response = await fetch(url);
+    } catch (err) {
+      const code = extractNetworkErrorCode(err);
+      throw new Error(
+        `[timber] Failed to download font file from ${url}` +
+          (code ? ` (${code})` : '') +
+          `. Build requires internet access for font optimization.` +
+          ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to download font from ${url}: ${response.status}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+  });
 }
 
 /**

package/src/server/access-gate.tsx

@@ -124,8 +124,35 @@ async function accessGateFallback(
  * slot doesn't make architectural sense.
  */
 export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactNode> {
-  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children, verdict } =
+    props;
 
+  // Fast path: replay pre-computed verdict from eager evaluation in resolveSlotProps.
+  if (verdict !== undefined) {
+    if (verdict === 'pass') return children;
+    if (verdict instanceof DenySignal) {
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, verdict.data, createElement) ??
+        defaultFallback ??
+        null
+      );
+    }
+    // RedirectSignal: treat as deny in production (same as existing behavior)
+    if (isDebug()) {
+      console.error(
+        '[timber] redirect() is not allowed in slot access.ts. ' +
+          'Slots use deny() for graceful degradation — denied.tsx → default.tsx → null. ' +
+          "If you need to redirect, move the logic to the parent segment's access.ts."
+      );
+    }
+    return (
+      buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
+      defaultFallback ??
+      null
+    );
+  }
+
+  // Fallback path: call accessFn during render (no pre-computed verdict).
   try {
     await accessFn();
   } catch (error: unknown) {

package/src/server/als-registry.ts

@@ -140,6 +140,18 @@ export interface RequestContextStore {
    * context for render-phase errors without module-level shared state.
    */
   debugComponentsGetter?: () => DebugComponentEntry[];
+  /**
+   * Taint tracking results from render-time accessor scope tracking.
+   * Keyed by segment/slot ID, true = accessor was called during render.
+   * Populated by runInTaintScope() wrappers in TracedLayout and slot
+   * resolution; consumed by buildSegmentInfo() for X-Timber-Segments.
+   */
+  taintResults?: Map<string, boolean>;
+  /**
+   * Set to true if an accessor is called outside any taint scope.
+   * When true, all segments are marked request-dependent (safe fallback).
+   */
+  orphanTaint?: boolean;
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
@@ -149,6 +161,38 @@ export interface CookieEntry {
   options: import('./cookie-context.js').CookieOptions;
 }
 
+// ─── Taint Scope ─────────────────────────────────────────────────────────
+// Per-component accessor taint tracking. Each scope runs inside its own
+// ALS context so concurrent async components (Flight renders siblings in
+// parallel) don't corrupt each other's touched flags.
+
+export interface TaintScope {
+  touched: boolean;
+}
+
+export const taintScopeAls = getOrCreateAls<TaintScope>(Symbol.for('timber:taint-scope-als'));
+
+/**
+ * Mark that a request accessor was called in the current scope.
+ * If a taint scope is active, marks that scope. If no scope is active
+ * but a request context exists, sets the orphan taint flag (all segments
+ * become request-dependent as a safety fallback).
+ *
+ * Lives here (not request-context.ts) to avoid circular deps with
+ * cookie-context.ts which also needs to call it.
+ */
+export function markAccessorTouched(): void {
+  const scope = taintScopeAls.getStore();
+  if (scope) {
+    scope.touched = true;
+    return;
+  }
+  const store = requestContextAls.getStore();
+  if (store) {
+    store.orphanTaint = true;
+  }
+}
+
 // ─── Tracing ──────────────────────────────────────────────────────────────
 // Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md

package/src/server/cookie-context.ts

@@ -12,7 +12,11 @@
  * smuggling primitive that the encoding contract closes.
  */
 
-import { requestContextAls, type RequestContextStore } from './als-registry.js';
+import {
+  requestContextAls,
+  markAccessorTouched,
+  type RequestContextStore,
+} from './als-registry.js';
 import { isDebug } from './debug.js';
 import {
   assertValidCookieName,
@@ -62,6 +66,8 @@ export function getCookieJar(): RequestCookies {
     );
   }
 
+  markAccessorTouched();
+
   // Parse cookies lazily on first access
   if (!store.parsedCookies) {
     store.parsedCookies = parseCookieHeader(store.cookieHeader);

package/src/server/deny-renderer.ts

@@ -26,7 +26,7 @@ import { loadModule } from './safe-load.js';
 import { isMdxFilePath } from './utils/mdx-file.js';
 import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { headElementsToReact } from './route-element-builder.js';
+import { headElementsToReact } from './metadata.js';
 import { resolveStatusFile } from './status-code-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';

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. */
@@ -334,3 +339,93 @@ export function getMetadataRouteAutoLink(type: MetadataRouteType, href: string):
       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. */