@timber-js/app 0.1.23 → 0.1.25

package/src/server/metadata-social.ts

@@ -0,0 +1,184 @@
+/**
+ * Social metadata rendering — Open Graph and Twitter Card meta tags.
+ *
+ * Extracted from metadata-render.ts to keep files under 500 lines.
+ *
+ * See design/16-metadata.md
+ */
+
+import type { Metadata } from './types.js';
+import type { HeadElement } from './metadata.js';
+
+/**
+ * Render Open Graph metadata into head element descriptors.
+ *
+ * Handles og:title, og:description, og:image (with dimensions/alt),
+ * og:video, og:audio, og:article:author, and other OG properties.
+ */
+export function renderOpenGraph(og: NonNullable<Metadata['openGraph']>, elements: HeadElement[]): void {
+  const simpleProps: Array<[string, string | undefined]> = [
+    ['og:title', og.title],
+    ['og:description', og.description],
+    ['og:url', og.url],
+    ['og:site_name', og.siteName],
+    ['og:locale', og.locale],
+    ['og:type', og.type],
+    ['og:article:published_time', og.publishedTime],
+    ['og:article:modified_time', og.modifiedTime],
+  ];
+
+  for (const [property, content] of simpleProps) {
+    if (content) {
+      elements.push({ tag: 'meta', attrs: { property, content } });
+    }
+  }
+
+  // Images — normalize single object to array for uniform handling
+  if (og.images) {
+    if (typeof og.images === 'string') {
+      elements.push({ tag: 'meta', attrs: { property: 'og:image', content: og.images } });
+    } else {
+      const imgList = Array.isArray(og.images) ? og.images : [og.images];
+      for (const img of imgList) {
+        elements.push({ tag: 'meta', attrs: { property: 'og:image', content: img.url } });
+        if (img.width) {
+          elements.push({
+            tag: 'meta',
+            attrs: { property: 'og:image:width', content: String(img.width) },
+          });
+        }
+        if (img.height) {
+          elements.push({
+            tag: 'meta',
+            attrs: { property: 'og:image:height', content: String(img.height) },
+          });
+        }
+        if (img.alt) {
+          elements.push({ tag: 'meta', attrs: { property: 'og:image:alt', content: img.alt } });
+        }
+      }
+    }
+  }
+
+  // Videos
+  if (og.videos) {
+    for (const video of og.videos) {
+      elements.push({ tag: 'meta', attrs: { property: 'og:video', content: video.url } });
+    }
+  }
+
+  // Audio
+  if (og.audio) {
+    for (const audio of og.audio) {
+      elements.push({ tag: 'meta', attrs: { property: 'og:audio', content: audio.url } });
+    }
+  }
+
+  // Authors
+  if (og.authors) {
+    for (const author of og.authors) {
+      elements.push({
+        tag: 'meta',
+        attrs: { property: 'og:article:author', content: author },
+      });
+    }
+  }
+}
+
+/**
+ * Render Twitter Card metadata into head element descriptors.
+ *
+ * Handles twitter:card, twitter:site, twitter:title, twitter:image,
+ * twitter:player, and twitter:app (per-platform name/id/url).
+ */
+export function renderTwitter(tw: NonNullable<Metadata['twitter']>, elements: HeadElement[]): void {
+  const simpleProps: Array<[string, string | undefined]> = [
+    ['twitter:card', tw.card],
+    ['twitter:site', tw.site],
+    ['twitter:site:id', tw.siteId],
+    ['twitter:title', tw.title],
+    ['twitter:description', tw.description],
+    ['twitter:creator', tw.creator],
+    ['twitter:creator:id', tw.creatorId],
+  ];
+
+  for (const [name, content] of simpleProps) {
+    if (content) {
+      elements.push({ tag: 'meta', attrs: { name, content } });
+    }
+  }
+
+  // Images — normalize single object to array for uniform handling
+  if (tw.images) {
+    if (typeof tw.images === 'string') {
+      elements.push({ tag: 'meta', attrs: { name: 'twitter:image', content: tw.images } });
+    } else {
+      const imgList = Array.isArray(tw.images) ? tw.images : [tw.images];
+      for (const img of imgList) {
+        const url = typeof img === 'string' ? img : img.url;
+        elements.push({ tag: 'meta', attrs: { name: 'twitter:image', content: url } });
+      }
+    }
+  }
+
+  // Player card fields
+  if (tw.players) {
+    for (const player of tw.players) {
+      elements.push({ tag: 'meta', attrs: { name: 'twitter:player', content: player.playerUrl } });
+      if (player.width) {
+        elements.push({
+          tag: 'meta',
+          attrs: { name: 'twitter:player:width', content: String(player.width) },
+        });
+      }
+      if (player.height) {
+        elements.push({
+          tag: 'meta',
+          attrs: { name: 'twitter:player:height', content: String(player.height) },
+        });
+      }
+      if (player.streamUrl) {
+        elements.push({
+          tag: 'meta',
+          attrs: { name: 'twitter:player:stream', content: player.streamUrl },
+        });
+      }
+    }
+  }
+
+  // App card fields — 3 platforms × 3 attributes (name, id, url)
+  if (tw.app) {
+    const platforms: Array<[keyof NonNullable<typeof tw.app.id>, string]> = [
+      ['iPhone', 'iphone'],
+      ['iPad', 'ipad'],
+      ['googlePlay', 'googleplay'],
+    ];
+
+    // App name is shared across platforms but the spec uses per-platform names.
+    // Emit for each platform that has an ID.
+    if (tw.app.name) {
+      for (const [key, tag] of platforms) {
+        if (tw.app.id?.[key]) {
+          elements.push({
+            tag: 'meta',
+            attrs: { name: `twitter:app:name:${tag}`, content: tw.app.name },
+          });
+        }
+      }
+    }
+
+    for (const [key, tag] of platforms) {
+      const id = tw.app.id?.[key];
+      if (id) {
+        elements.push({ tag: 'meta', attrs: { name: `twitter:app:id:${tag}`, content: id } });
+      }
+    }
+
+    for (const [key, tag] of platforms) {
+      const url = tw.app.url?.[key];
+      if (url) {
+        elements.push({ tag: 'meta', attrs: { name: `twitter:app:url:${tag}`, content: url } });
+      }
+    }
+  }
+}

package/src/server/pipeline-interception.ts

@@ -0,0 +1,76 @@
+/**
+ * Interception route matching for the request pipeline.
+ *
+ * Matches target URLs against interception rewrites to support the
+ * modal route pattern (soft navigation intercepts).
+ *
+ * Extracted from pipeline.ts to keep files under 500 lines.
+ *
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+
+/** Result of a successful interception match. */
+export interface InterceptionMatchResult {
+  /** The pathname to re-match (the source/intercepting route's parent). */
+  sourcePathname: string;
+}
+
+/**
+ * Check if an intercepting route applies for this soft navigation.
+ *
+ * Matches the target pathname against interception rewrites, constrained
+ * by the source URL (X-Timber-URL header — where the user navigates FROM).
+ *
+ * Returns the source pathname to re-match if interception applies, or null.
+ */
+export function findInterceptionMatch(
+  targetPathname: string,
+  sourceUrl: string,
+  rewrites: import('#/routing/interception.js').InterceptionRewrite[]
+): InterceptionMatchResult | null {
+  for (const rewrite of rewrites) {
+    // Check if the source URL starts with the intercepting prefix
+    if (!sourceUrl.startsWith(rewrite.interceptingPrefix)) continue;
+
+    // Check if the target URL matches the intercepted pattern.
+    // Dynamic segments in the pattern match any single URL segment.
+    if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) {
+      return { sourcePathname: rewrite.interceptingPrefix };
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a pathname matches a URL pattern with dynamic segments.
+ *
+ * Supports [param] (single segment) and [...param] (one or more segments).
+ * Static segments must match exactly.
+ */
+export function pathnameMatchesPattern(pathname: string, pattern: string): boolean {
+  const pathParts = pathname === '/' ? [] : pathname.slice(1).split('/');
+  const patternParts = pattern === '/' ? [] : pattern.slice(1).split('/');
+
+  let pi = 0;
+  for (let i = 0; i < patternParts.length; i++) {
+    const segment = patternParts[i];
+
+    // Catch-all: [...param] or [[...param]] — matches rest of URL
+    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
+      return pi < pathParts.length || segment.startsWith('[[...');
+    }
+
+    // Dynamic: [param] — matches any single segment
+    if (segment.startsWith('[') && segment.endsWith(']')) {
+      if (pi >= pathParts.length) return false;
+      pi++;
+      continue;
+    }
+
+    // Static — must match exactly
+    if (pi >= pathParts.length || pathParts[pi] !== segment) return false;
+    pi++;
+  }
+
+  return pi === pathParts.length;
+}

package/src/server/pipeline-metadata.ts

@@ -0,0 +1,90 @@
+/**
+ * Metadata route helpers for the request pipeline.
+ *
+ * Handles serving static metadata files and serializing sitemap responses.
+ * Extracted from pipeline.ts to keep files under 500 lines.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Content types that are text-based and should include charset=utf-8.
+ * Binary formats (images) should not include charset.
+ */
+const TEXT_CONTENT_TYPES = new Set([
+  'application/xml',
+  'text/plain',
+  'application/json',
+  'application/manifest+json',
+  'image/svg+xml',
+]);
+
+/**
+ * Serve a static metadata file by reading it from disk.
+ *
+ * Static metadata route files (.xml, .txt, .json, .png, .ico, .svg, etc.)
+ * are served as-is with the appropriate Content-Type header.
+ * Text files include charset=utf-8; binary files do not.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+export async function serveStaticMetadataFile(
+  metaMatch: import('./route-matcher.js').MetadataRouteMatch
+): Promise<Response> {
+  const { contentType, file } = metaMatch;
+  const isText = TEXT_CONTENT_TYPES.has(contentType);
+
+  const body = await readFile(file.filePath);
+
+  const headers: Record<string, string> = {
+    'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
+    'Content-Length': String(body.byteLength),
+  };
+
+  return new Response(body, { status: 200, headers });
+}
+
+/**
+ * Serialize a sitemap array to XML.
+ * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
+ */
+export function serializeSitemap(
+  entries: Array<{
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: string;
+    priority?: number;
+  }>
+): string {
+  const urls = entries
+    .map((e) => {
+      let xml = `  <url>\n    <loc>${escapeXml(e.url)}</loc>`;
+      if (e.lastModified) {
+        const date = e.lastModified instanceof Date ? e.lastModified.toISOString() : e.lastModified;
+        xml += `\n    <lastmod>${escapeXml(date)}</lastmod>`;
+      }
+      if (e.changeFrequency) {
+        xml += `\n    <changefreq>${escapeXml(e.changeFrequency)}</changefreq>`;
+      }
+      if (e.priority !== undefined) {
+        xml += `\n    <priority>${e.priority}</priority>`;
+      }
+      xml += '\n  </url>';
+      return xml;
+    })
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`;
+}
+
+/** Escape special XML characters. */
+export function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/src/server/pipeline.ts

@@ -11,7 +11,6 @@
  * and design/17-logging.md §"Production Logging"
  */
 
-import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonicalize.js';
 import { runProxy, type ProxyExport } from './proxy.js';
 import { runMiddleware, type MiddlewareFn } from './middleware-runner.js';
@@ -47,6 +46,8 @@ import {
 } from './logger.js';
 import { callOnRequestError } from './instrumentation.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
+import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
+import { findInterceptionMatch } from './pipeline-interception.js';
 import type { MiddlewareContext } from './types.js';
 import type { SegmentNode } from '#/routing/types.js';
 
@@ -511,72 +512,7 @@ async function fireOnRequestError(
   );
 }
 
-// ─── Interception Matching ────────────────────────────────────────────────
 
-interface InterceptionMatchResult {
-  /** The pathname to re-match (the source/intercepting route's parent). */
-  sourcePathname: string;
-}
-
-/**
- * Check if an intercepting route applies for this soft navigation.
- *
- * Matches the target pathname against interception rewrites, constrained
- * by the source URL (X-Timber-URL header — where the user navigates FROM).
- *
- * Returns the source pathname to re-match if interception applies, or null.
- */
-function findInterceptionMatch(
-  targetPathname: string,
-  sourceUrl: string,
-  rewrites: import('#/routing/interception.js').InterceptionRewrite[]
-): InterceptionMatchResult | null {
-  for (const rewrite of rewrites) {
-    // Check if the source URL starts with the intercepting prefix
-    if (!sourceUrl.startsWith(rewrite.interceptingPrefix)) continue;
-
-    // Check if the target URL matches the intercepted pattern.
-    // Dynamic segments in the pattern match any single URL segment.
-    if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) {
-      return { sourcePathname: rewrite.interceptingPrefix };
-    }
-  }
-  return null;
-}
-
-/**
- * Check if a pathname matches a URL pattern with dynamic segments.
- *
- * Supports [param] (single segment) and [...param] (one or more segments).
- * Static segments must match exactly.
- */
-function pathnameMatchesPattern(pathname: string, pattern: string): boolean {
-  const pathParts = pathname === '/' ? [] : pathname.slice(1).split('/');
-  const patternParts = pattern === '/' ? [] : pattern.slice(1).split('/');
-
-  let pi = 0;
-  for (let i = 0; i < patternParts.length; i++) {
-    const segment = patternParts[i];
-
-    // Catch-all: [...param] or [[...param]] — matches rest of URL
-    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
-      return pi < pathParts.length || segment.startsWith('[[...');
-    }
-
-    // Dynamic: [param] — matches any single segment
-    if (segment.startsWith('[') && segment.endsWith(']')) {
-      if (pi >= pathParts.length) return false;
-      pi++;
-      continue;
-    }
-
-    // Static — must match exactly
-    if (pi >= pathParts.length || pathParts[pi] !== segment) return false;
-    pi++;
-  }
-
-  return pi === pathParts.length;
-}
 
 // ─── Cookie Helpers ──────────────────────────────────────────────────────
 
@@ -620,86 +556,4 @@ function ensureMutableResponse(response: Response): Response {
   }
 }
 
-// ─── Metadata Route Helpers ──────────────────────────────────────────────
 
-/**
- * Serialize a sitemap array to XML.
- * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
- */
-function serializeSitemap(
-  entries: Array<{
-    url: string;
-    lastModified?: string | Date;
-    changeFrequency?: string;
-    priority?: number;
-  }>
-): string {
-  const urls = entries
-    .map((e) => {
-      let xml = `  <url>\n    <loc>${escapeXml(e.url)}</loc>`;
-      if (e.lastModified) {
-        const date = e.lastModified instanceof Date ? e.lastModified.toISOString() : e.lastModified;
-        xml += `\n    <lastmod>${escapeXml(date)}</lastmod>`;
-      }
-      if (e.changeFrequency) {
-        xml += `\n    <changefreq>${escapeXml(e.changeFrequency)}</changefreq>`;
-      }
-      if (e.priority !== undefined) {
-        xml += `\n    <priority>${e.priority}</priority>`;
-      }
-      xml += '\n  </url>';
-      return xml;
-    })
-    .join('\n');
-
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`;
-}
-
-/** Escape special XML characters. */
-function escapeXml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;');
-}
-
-// ─── Static Metadata File Serving ────────────────────────────────────────
-
-/**
- * Content types that are text-based and should include charset=utf-8.
- * Binary formats (images) should not include charset.
- */
-const TEXT_CONTENT_TYPES = new Set([
-  'application/xml',
-  'text/plain',
-  'application/json',
-  'application/manifest+json',
-  'image/svg+xml',
-]);
-
-/**
- * Serve a static metadata file by reading it from disk.
- *
- * Static metadata route files (.xml, .txt, .json, .png, .ico, .svg, etc.)
- * are served as-is with the appropriate Content-Type header.
- * Text files include charset=utf-8; binary files do not.
- *
- * See design/16-metadata.md §"Metadata Routes"
- */
-async function serveStaticMetadataFile(
-  metaMatch: import('./route-matcher.js').MetadataRouteMatch
-): Promise<Response> {
-  const { contentType, file } = metaMatch;
-  const isText = TEXT_CONTENT_TYPES.has(contentType);
-
-  const body = await readFile(file.filePath);
-
-  const headers: Record<string, string> = {
-    'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
-    'Content-Length': String(body.byteLength),
-  };
-
-  return new Response(body, { status: 200, headers });
-}