npm - @timber-js/app - Versions diffs - 0.1.0 → 0.1.2 - Mend

@timber-js/app 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

package/dist/index.js +5 -2
package/dist/index.js.map +1 -1
package/dist/plugins/entries.d.ts.map +1 -1
package/package.json +43 -58
package/src/adapters/cloudflare.ts +325 -0
package/src/adapters/nitro.ts +366 -0
package/src/adapters/types.ts +63 -0
package/src/cache/index.ts +91 -0
package/src/cache/redis-handler.ts +91 -0
package/src/cache/register-cached-function.ts +99 -0
package/src/cache/singleflight.ts +26 -0
package/src/cache/stable-stringify.ts +21 -0
package/src/cache/timber-cache.ts +116 -0
package/src/cli.ts +201 -0
package/src/client/browser-entry.ts +663 -0
package/src/client/error-boundary.tsx +209 -0
package/src/client/form.tsx +200 -0
package/src/client/head.ts +61 -0
package/src/client/history.ts +46 -0
package/src/client/index.ts +60 -0
package/src/client/link-navigate-interceptor.tsx +62 -0
package/src/client/link-status-provider.tsx +40 -0
package/src/client/link.tsx +310 -0
package/src/client/nuqs-adapter.tsx +117 -0
package/src/client/router-ref.ts +25 -0
package/src/client/router.ts +563 -0
package/src/client/segment-cache.ts +194 -0
package/src/client/segment-context.ts +57 -0
package/src/client/ssr-data.ts +95 -0
package/src/client/types.ts +4 -0
package/src/client/unload-guard.ts +34 -0
package/src/client/use-cookie.ts +122 -0
package/src/client/use-link-status.ts +46 -0
package/src/client/use-navigation-pending.ts +47 -0
package/src/client/use-params.ts +71 -0
package/src/client/use-pathname.ts +43 -0
package/src/client/use-query-states.ts +133 -0
package/src/client/use-router.ts +77 -0
package/src/client/use-search-params.ts +74 -0
package/src/client/use-selected-layout-segment.ts +110 -0
package/src/content/index.ts +13 -0
package/src/cookies/define-cookie.ts +137 -0
package/src/cookies/index.ts +9 -0
package/src/fonts/ast.ts +359 -0
package/src/fonts/css.ts +68 -0
package/src/fonts/fallbacks.ts +248 -0
package/src/fonts/google.ts +332 -0
package/src/fonts/local.ts +177 -0
package/src/fonts/types.ts +88 -0
package/src/index.ts +413 -0
package/src/plugins/adapter-build.ts +118 -0
package/src/plugins/build-manifest.ts +323 -0
package/src/plugins/build-report.ts +353 -0
package/src/plugins/cache-transform.ts +199 -0
package/src/plugins/chunks.ts +90 -0
package/src/plugins/content.ts +136 -0
package/src/plugins/dev-error-overlay.ts +230 -0
package/src/plugins/dev-logs.ts +280 -0
package/src/plugins/dev-server.ts +389 -0
package/src/plugins/dynamic-transform.ts +161 -0
package/src/plugins/entries.ts +207 -0
package/src/plugins/fonts.ts +581 -0
package/src/plugins/mdx.ts +179 -0
package/src/plugins/react-prod.ts +56 -0
package/src/plugins/routing.ts +419 -0
package/src/plugins/server-action-exports.ts +220 -0
package/src/plugins/server-bundle.ts +113 -0
package/src/plugins/shims.ts +168 -0
package/src/plugins/static-build.ts +207 -0
package/src/routing/codegen.ts +396 -0
package/src/routing/index.ts +14 -0
package/src/routing/interception.ts +173 -0
package/src/routing/scanner.ts +487 -0
package/src/routing/status-file-lint.ts +114 -0
package/src/routing/types.ts +100 -0
package/src/search-params/analyze.ts +192 -0
package/src/search-params/codecs.ts +153 -0
package/src/search-params/create.ts +314 -0
package/src/search-params/index.ts +23 -0
package/src/search-params/registry.ts +31 -0
package/src/server/access-gate.tsx +142 -0
package/src/server/action-client.ts +473 -0
package/src/server/action-handler.ts +325 -0
package/src/server/actions.ts +236 -0
package/src/server/asset-headers.ts +81 -0
package/src/server/body-limits.ts +102 -0
package/src/server/build-manifest.ts +234 -0
package/src/server/canonicalize.ts +90 -0
package/src/server/client-module-map.ts +58 -0
package/src/server/csrf.ts +79 -0
package/src/server/deny-renderer.ts +302 -0
package/src/server/dev-logger.ts +419 -0
package/src/server/dev-span-processor.ts +78 -0
package/src/server/dev-warnings.ts +282 -0
package/src/server/early-hints-sender.ts +55 -0
package/src/server/early-hints.ts +142 -0
package/src/server/error-boundary-wrapper.ts +69 -0
package/src/server/error-formatter.ts +184 -0
package/src/server/flush.ts +182 -0
package/src/server/form-data.ts +176 -0
package/src/server/form-flash.ts +93 -0
package/src/server/html-injectors.ts +445 -0
package/src/server/index.ts +222 -0
package/src/server/instrumentation.ts +136 -0
package/src/server/logger.ts +145 -0
package/src/server/manifest-status-resolver.ts +215 -0
package/src/server/metadata-render.ts +527 -0
package/src/server/metadata-routes.ts +189 -0
package/src/server/metadata.ts +263 -0
package/src/server/middleware-runner.ts +32 -0
package/src/server/nuqs-ssr-provider.tsx +63 -0
package/src/server/pipeline.ts +555 -0
package/src/server/prerender.ts +139 -0
package/src/server/primitives.ts +264 -0
package/src/server/proxy.ts +43 -0
package/src/server/request-context.ts +554 -0
package/src/server/route-element-builder.ts +395 -0
package/src/server/route-handler.ts +153 -0
package/src/server/route-matcher.ts +316 -0
package/src/server/rsc-entry/api-handler.ts +112 -0
package/src/server/rsc-entry/error-renderer.ts +177 -0
package/src/server/rsc-entry/helpers.ts +147 -0
package/src/server/rsc-entry/index.ts +688 -0
package/src/server/rsc-entry/ssr-bridge.ts +18 -0
package/src/server/slot-resolver.ts +359 -0
package/src/server/ssr-entry.ts +161 -0
package/src/server/ssr-render.ts +200 -0
package/src/server/status-code-resolver.ts +282 -0
package/src/server/tracing.ts +281 -0
package/src/server/tree-builder.ts +354 -0
package/src/server/types.ts +150 -0
package/src/shims/font-google.ts +67 -0
package/src/shims/headers.ts +11 -0
package/src/shims/image.ts +48 -0
package/src/shims/link.ts +9 -0
package/src/shims/navigation-client.ts +52 -0
package/src/shims/navigation.ts +31 -0
package/src/shims/server-only-noop.js +5 -0
package/src/utils/directive-parser.ts +529 -0
package/src/utils/format.ts +10 -0
package/src/utils/startup-timer.ts +102 -0

package/src/server/metadata-render.ts ADDED Viewed

@@ -0,0 +1,527 @@
+/**
+ * Metadata rendering — converts resolved Metadata into HeadElement descriptors.
+ *
+ * Extracted from metadata.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 to Elements ──────────────────────────────────────────────────────
+/**
+ * Convert resolved metadata into an array of head element descriptors.
+ *
+ * Each descriptor has a `tag` ('title', 'meta', 'link') and either
+ * `content` (for <title>) or `attrs` (for <meta>/<link>).
+ *
+ * The framework's MetadataResolver component consumes these descriptors
+ * and renders them into the <head>.
+ */
+export function renderMetadataToElements(metadata: Metadata): HeadElement[] {
+  const elements: HeadElement[] = [];
+  // Title
+  if (typeof metadata.title === 'string') {
+    elements.push({ tag: 'title', content: metadata.title });
+  }
+  // Simple string meta tags
+  const simpleMetaProps: Array<[string, string | undefined]> = [
+    ['description', metadata.description],
+    ['generator', metadata.generator],
+    ['application-name', metadata.applicationName],
+    ['referrer', metadata.referrer],
+    ['category', metadata.category],
+    ['creator', metadata.creator],
+    ['publisher', metadata.publisher],
+  ];
+  for (const [name, content] of simpleMetaProps) {
+    if (content) {
+      elements.push({ tag: 'meta', attrs: { name, content } });
+    }
+  }
+  // Keywords (array or string)
+  if (metadata.keywords) {
+    const content = Array.isArray(metadata.keywords)
+      ? metadata.keywords.join(', ')
+      : metadata.keywords;
+    elements.push({ tag: 'meta', attrs: { name: 'keywords', content } });
+  }
+  // Robots
+  if (metadata.robots) {
+    const content =
+      typeof metadata.robots === 'string' ? metadata.robots : renderRobotsObject(metadata.robots);
+    elements.push({ tag: 'meta', attrs: { name: 'robots', content } });
+    // googleBot as separate tag
+    if (typeof metadata.robots === 'object' && metadata.robots.googleBot) {
+      const gbContent =
+        typeof metadata.robots.googleBot === 'string'
+          ? metadata.robots.googleBot
+          : renderRobotsObject(metadata.robots.googleBot);
+      elements.push({ tag: 'meta', attrs: { name: 'googlebot', content: gbContent } });
+    }
+  }
+  // Open Graph
+  if (metadata.openGraph) {
+    renderOpenGraph(metadata.openGraph, elements);
+  }
+  // Twitter
+  if (metadata.twitter) {
+    renderTwitter(metadata.twitter, elements);
+  }
+  // Icons
+  if (metadata.icons) {
+    renderIcons(metadata.icons, elements);
+  }
+  // Manifest
+  if (metadata.manifest) {
+    elements.push({ tag: 'link', attrs: { rel: 'manifest', href: metadata.manifest } });
+  }
+  // Alternates
+  if (metadata.alternates) {
+    renderAlternates(metadata.alternates, elements);
+  }
+  // Verification
+  if (metadata.verification) {
+    renderVerification(metadata.verification, elements);
+  }
+  // Format detection
+  if (metadata.formatDetection) {
+    const parts: string[] = [];
+    if (metadata.formatDetection.telephone === false) parts.push('telephone=no');
+    if (metadata.formatDetection.email === false) parts.push('email=no');
+    if (metadata.formatDetection.address === false) parts.push('address=no');
+    if (parts.length > 0) {
+      elements.push({
+        tag: 'meta',
+        attrs: { name: 'format-detection', content: parts.join(', ') },
+      });
+    }
+  }
+  // Authors
+  if (metadata.authors) {
+    const authorList = Array.isArray(metadata.authors) ? metadata.authors : [metadata.authors];
+    for (const author of authorList) {
+      if (author.name) {
+        elements.push({ tag: 'meta', attrs: { name: 'author', content: author.name } });
+      }
+      if (author.url) {
+        elements.push({ tag: 'link', attrs: { rel: 'author', href: author.url } });
+      }
+    }
+  }
+  // Apple Web App
+  if (metadata.appleWebApp) {
+    renderAppleWebApp(metadata.appleWebApp, elements);
+  }
+  // App Links (al:*)
+  if (metadata.appLinks) {
+    renderAppLinks(metadata.appLinks, elements);
+  }
+  // iTunes
+  if (metadata.itunes) {
+    renderItunes(metadata.itunes, elements);
+  }
+  // Other (custom meta tags)
+  if (metadata.other) {
+    for (const [name, value] of Object.entries(metadata.other)) {
+      const content = Array.isArray(value) ? value.join(', ') : value;
+      elements.push({ tag: 'meta', attrs: { name, content } });
+    }
+  }
+  return elements;
+}
+// ─── Rendering Helpers ───────────────────────────────────────────────────────
+function renderRobotsObject(robots: Record<string, unknown>): string {
+  const parts: string[] = [];
+  if (robots.index === true) parts.push('index');
+  if (robots.index === false) parts.push('noindex');
+  if (robots.follow === true) parts.push('follow');
+  if (robots.follow === false) parts.push('nofollow');
+  return parts.join(', ');
+}
+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 },
+      });
+    }
+  }
+}
+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 } });
+      }
+    }
+  }
+}
+function renderIcons(icons: NonNullable<Metadata['icons']>, elements: HeadElement[]): void {
+  // Icon
+  if (icons.icon) {
+    if (typeof icons.icon === 'string') {
+      elements.push({ tag: 'link', attrs: { rel: 'icon', href: icons.icon } });
+    } else if (Array.isArray(icons.icon)) {
+      for (const icon of icons.icon) {
+        const attrs: Record<string, string> = { rel: 'icon', href: icon.url };
+        if (icon.sizes) attrs.sizes = icon.sizes;
+        if (icon.type) attrs.type = icon.type;
+        elements.push({ tag: 'link', attrs });
+      }
+    }
+  }
+  // Shortcut
+  if (icons.shortcut) {
+    const urls = Array.isArray(icons.shortcut) ? icons.shortcut : [icons.shortcut];
+    for (const url of urls) {
+      elements.push({ tag: 'link', attrs: { rel: 'shortcut icon', href: url } });
+    }
+  }
+  // Apple
+  if (icons.apple) {
+    if (typeof icons.apple === 'string') {
+      elements.push({ tag: 'link', attrs: { rel: 'apple-touch-icon', href: icons.apple } });
+    } else if (Array.isArray(icons.apple)) {
+      for (const icon of icons.apple) {
+        const attrs: Record<string, string> = { rel: 'apple-touch-icon', href: icon.url };
+        if (icon.sizes) attrs.sizes = icon.sizes;
+        elements.push({ tag: 'link', attrs });
+      }
+    }
+  }
+  // Other
+  if (icons.other) {
+    for (const icon of icons.other) {
+      const attrs: Record<string, string> = { rel: icon.rel, href: icon.url };
+      if (icon.sizes) attrs.sizes = icon.sizes;
+      if (icon.type) attrs.type = icon.type;
+      elements.push({ tag: 'link', attrs });
+    }
+  }
+}
+function renderAlternates(
+  alternates: NonNullable<Metadata['alternates']>,
+  elements: HeadElement[]
+): void {
+  if (alternates.canonical) {
+    elements.push({ tag: 'link', attrs: { rel: 'canonical', href: alternates.canonical } });
+  }
+  if (alternates.languages) {
+    for (const [lang, href] of Object.entries(alternates.languages)) {
+      elements.push({
+        tag: 'link',
+        attrs: { rel: 'alternate', hreflang: lang, href },
+      });
+    }
+  }
+  if (alternates.media) {
+    for (const [media, href] of Object.entries(alternates.media)) {
+      elements.push({
+        tag: 'link',
+        attrs: { rel: 'alternate', media, href },
+      });
+    }
+  }
+  if (alternates.types) {
+    for (const [type, href] of Object.entries(alternates.types)) {
+      elements.push({
+        tag: 'link',
+        attrs: { rel: 'alternate', type, href },
+      });
+    }
+  }
+}
+function renderVerification(
+  verification: NonNullable<Metadata['verification']>,
+  elements: HeadElement[]
+): void {
+  const verificationProps: Array<[string, string | undefined]> = [
+    ['google-site-verification', verification.google],
+    ['y_key', verification.yahoo],
+    ['yandex-verification', verification.yandex],
+  ];
+  for (const [name, content] of verificationProps) {
+    if (content) {
+      elements.push({ tag: 'meta', attrs: { name, content } });
+    }
+  }
+  if (verification.other) {
+    for (const [name, value] of Object.entries(verification.other)) {
+      const content = Array.isArray(value) ? value.join(', ') : value;
+      elements.push({ tag: 'meta', attrs: { name, content } });
+    }
+  }
+}
+function renderAppleWebApp(
+  appleWebApp: NonNullable<Metadata['appleWebApp']>,
+  elements: HeadElement[]
+): void {
+  if (appleWebApp.capable) {
+    elements.push({
+      tag: 'meta',
+      attrs: { name: 'apple-mobile-web-app-capable', content: 'yes' },
+    });
+  }
+  if (appleWebApp.title) {
+    elements.push({
+      tag: 'meta',
+      attrs: { name: 'apple-mobile-web-app-title', content: appleWebApp.title },
+    });
+  }
+  if (appleWebApp.statusBarStyle) {
+    elements.push({
+      tag: 'meta',
+      attrs: {
+        name: 'apple-mobile-web-app-status-bar-style',
+        content: appleWebApp.statusBarStyle,
+      },
+    });
+  }
+  if (appleWebApp.startupImage) {
+    const images = Array.isArray(appleWebApp.startupImage)
+      ? appleWebApp.startupImage
+      : [{ url: appleWebApp.startupImage }];
+    for (const img of images) {
+      const url = typeof img === 'string' ? img : img.url;
+      const attrs: Record<string, string> = { rel: 'apple-touch-startup-image', href: url };
+      if (typeof img === 'object' && img.media) {
+        attrs.media = img.media;
+      }
+      elements.push({ tag: 'link', attrs });
+    }
+  }
+}
+function renderAppLinks(
+  appLinks: NonNullable<Metadata['appLinks']>,
+  elements: HeadElement[]
+): void {
+  const platformEntries: Array<[string, Array<Record<string, unknown>> | undefined]> = [
+    ['ios', appLinks.ios],
+    ['android', appLinks.android],
+    ['windows', appLinks.windows],
+    ['windows_phone', appLinks.windowsPhone],
+    ['windows_universal', appLinks.windowsUniversal],
+  ];
+  for (const [platform, entries] of platformEntries) {
+    if (!entries) continue;
+    for (const entry of entries) {
+      for (const [key, value] of Object.entries(entry)) {
+        if (value !== undefined && value !== null) {
+          elements.push({
+            tag: 'meta',
+            attrs: { property: `al:${platform}:${key}`, content: String(value) },
+          });
+        }
+      }
+    }
+  }
+  if (appLinks.web) {
+    if (appLinks.web.url) {
+      elements.push({
+        tag: 'meta',
+        attrs: { property: 'al:web:url', content: appLinks.web.url },
+      });
+    }
+    if (appLinks.web.shouldFallback !== undefined) {
+      elements.push({
+        tag: 'meta',
+        attrs: {
+          property: 'al:web:should_fallback',
+          content: appLinks.web.shouldFallback ? 'true' : 'false',
+        },
+      });
+    }
+  }
+}
+function renderItunes(itunes: NonNullable<Metadata['itunes']>, elements: HeadElement[]): void {
+  const parts = [`app-id=${itunes.appId}`];
+  if (itunes.affiliateData) parts.push(`affiliate-data=${itunes.affiliateData}`);
+  if (itunes.appArgument) parts.push(`app-argument=${itunes.appArgument}`);
+  elements.push({
+    tag: 'meta',
+    attrs: { name: 'apple-itunes-app', content: parts.join(', ') },
+  });
+}

package/src/server/metadata-routes.ts ADDED Viewed

@@ -0,0 +1,189 @@
+/**
+ * Metadata route classification for timber.js.
+ *
+ * Metadata routes are file-based endpoints that generate well-known URLs for
+ * crawlers and browsers (sitemap.xml, robots.txt, OG images, etc.).
+ *
+ * These routes run through proxy.ts but NOT through middleware.ts or access.ts —
+ * they are public endpoints by nature.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+// ─── Types ───────────────────────────────────────────────────────────────────
+/** Classification of a metadata route file. */
+export interface MetadataRouteInfo {
+  /** The metadata route type. */
+  type: MetadataRouteType;
+  /** The content type to serve this route with. */
+  contentType: string;
+  /** Whether this route can appear in nested segments (not just app root). */
+  nestable: boolean;
+}
+export type MetadataRouteType =
+  | 'sitemap'
+  | 'robots'
+  | 'manifest'
+  | 'favicon'
+  | 'icon'
+  | 'opengraph-image'
+  | 'twitter-image'
+  | 'apple-icon';
+// ─── Convention Table ────────────────────────────────────────────────────────
+/**
+ * All recognized metadata route file conventions.
+ *
+ * Each entry maps a base file name (without extension) to its route info.
+ * The extensions determine whether the file is static or dynamic.
+ *
+ * Static extensions: .xml, .txt, .json, .png, .jpg, .ico, .svg
+ * Dynamic extensions: .ts, .tsx
+ */
+export const METADATA_ROUTE_CONVENTIONS: Record<
+  string,
+  {
+    type: MetadataRouteType;
+    contentType: string;
+    nestable: boolean;
+    staticExtensions: string[];
+    dynamicExtensions: string[];
+    /** The URL path this file serves at (relative to segment). */
+    servePath: string;
+  }
+> = {
+  'sitemap': {
+    type: 'sitemap',
+    contentType: 'application/xml',
+    nestable: true,
+    staticExtensions: ['xml'],
+    dynamicExtensions: ['ts'],
+    servePath: 'sitemap.xml',
+  },
+  'robots': {
+    type: 'robots',
+    contentType: 'text/plain',
+    nestable: false,
+    staticExtensions: ['txt'],
+    dynamicExtensions: ['ts'],
+    servePath: 'robots.txt',
+  },
+  'manifest': {
+    type: 'manifest',
+    contentType: 'application/manifest+json',
+    nestable: false,
+    staticExtensions: ['json'],
+    dynamicExtensions: ['ts'],
+    servePath: 'manifest.webmanifest',
+  },
+  'favicon': {
+    type: 'favicon',
+    contentType: 'image/x-icon',
+    nestable: false,
+    staticExtensions: ['ico'],
+    dynamicExtensions: [],
+    servePath: 'favicon.ico',
+  },
+  'icon': {
+    type: 'icon',
+    contentType: 'image/*',
+    nestable: true,
+    staticExtensions: ['png', 'jpg', 'svg'],
+    dynamicExtensions: ['ts', 'tsx'],
+    servePath: 'icon',
+  },
+  'opengraph-image': {
+    type: 'opengraph-image',
+    contentType: 'image/*',
+    nestable: true,
+    staticExtensions: ['png', 'jpg'],
+    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/*',
+    nestable: true,
+    staticExtensions: ['png'],
+    dynamicExtensions: ['ts', 'tsx'],
+    servePath: 'apple-icon',
+  },
+};
+// ─── Classification ──────────────────────────────────────────────────────────
+/**
+ * Classify a file name as a metadata route, or return null if it's not one.
+ *
+ * @param fileName - The full file name including extension (e.g. "sitemap.xml", "icon.tsx")
+ * @returns Classification info, or null if not a metadata route
+ */
+export function classifyMetadataRoute(fileName: string): MetadataRouteInfo | null {
+  const dotIndex = fileName.lastIndexOf('.');
+  if (dotIndex === -1) return null;
+  const baseName = fileName.slice(0, dotIndex);
+  const ext = fileName.slice(dotIndex + 1);
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return null;
+  const isStatic = convention.staticExtensions.includes(ext);
+  const isDynamic = convention.dynamicExtensions.includes(ext);
+  if (!isStatic && !isDynamic) return null;
+  return {
+    type: convention.type,
+    contentType: convention.contentType,
+    nestable: convention.nestable,
+  };
+}
+/**
+ * Get the serve path for a metadata route type.
+ *
+ * @param type - The metadata route type
+ * @returns The URL path fragment this route serves at
+ */
+export function getMetadataRouteServePath(type: MetadataRouteType): string {
+  for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {
+    if (convention.type === type) return convention.servePath;
+  }
+  throw new Error(`[timber] Unknown metadata route type: ${type}`);
+}
+/**
+ * Get the auto-link tags to inject into <head> for metadata route files
+ * discovered in a segment.
+ *
+ * @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
+ */
+export function getMetadataRouteAutoLink(
+  type: MetadataRouteType,
+  href: string
+): { rel: string; href: string; type?: string } | null {
+  switch (type) {
+    case 'icon':
+      return { rel: 'icon', href };
+    case 'apple-icon':
+      return { rel: 'apple-touch-icon', href };
+    case 'manifest':
+      return { rel: 'manifest', href };
+    default:
+      return null;
+  }
+}