@webjsdev/server 0.8.79 → 0.8.81

package/index.d.ts

@@ -910,6 +910,47 @@ export declare function sitemap(entries: SitemapEntry[]): string;
 /** Serialize child sitemaps into a `<sitemapindex>` XML document. */
 export declare function sitemapIndex(sitemaps: SitemapIndexEntry[]): string;
 
+/** One `User-agent` group of a robots.txt (Next's `MetadataRoute.Robots` rule). */
+export interface RobotsRule {
+  userAgent?: string | string[];
+  allow?: string | string[];
+  disallow?: string | string[];
+  crawlDelay?: number;
+}
+/** A robots.txt as data (Next's `MetadataRoute.Robots`). `app/robots.ts` may return it. */
+export interface RobotsConfig {
+  /** Defaults to allowing every crawler everywhere. */
+  rules?: RobotsRule | RobotsRule[];
+  sitemap?: string | string[];
+  host?: string;
+}
+/** Serialize a robots config into robots.txt text. */
+export declare function robots(config?: RobotsConfig): string;
+
+/**
+ * The argument every metadata route (`app/sitemap.ts`, `app/robots.ts`, the
+ * image routes, ...) receives (#1564).
+ */
+export interface MetadataRouteContext {
+  request: Request;
+  url: URL;
+  /** The public origin: `SITE_URL` when set, else the request origin. No trailing slash. */
+  siteUrl: string;
+  /**
+   * Every public page as a sitemap entry: static pages, plus dynamic pages that
+   * export `generateSitemapParams()`. Pages whose static metadata says
+   * `robots: { index: false }` are left out.
+   */
+  pages(): Promise<SitemapEntry[]>;
+}
+/**
+ * What `app/sitemap.ts` may return: an array of entries (urls may be paths,
+ * resolved against `siteUrl`), an XML string, or a Response.
+ */
+export type SitemapRouteResult = SitemapEntry[] | string | Response;
+/** What `app/robots.ts` may return: a config object, text, or a Response. */
+export type RobotsRouteResult = RobotsConfig | string | Response;
+
 // ---------------------------------------------------------------------------
 // stream.js (#248): stream-action helpers (the `<webjs-stream>` HTML the
 // client `renderStream` / element applies surgically)

package/index.js

@@ -59,7 +59,7 @@ export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSess
 export { broadcast } from './src/broadcast.js';
 export { diskStore, setFileStore, getFileStore, generateKey, signedUrl, verifySignedUrl, assertSafeKey, DEFAULT_UPLOAD_DIR } from './src/file-storage.js';
 export { json, readBody } from './src/json.js';
-export { sitemap, sitemapIndex } from './src/sitemap.js';
+export { sitemap, sitemapIndex, robots } from './src/sitemap.js';
 export { stream, streamResponse, acceptsStream, STREAM_MIME } from './src/stream.js';
 export { attachWebSocket } from './src/websocket.js';
 export { getSerializer, setSerializer, defaultSerializer } from './src/serializer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.79",
+  "version": "0.8.81",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",

package/src/dev/helpers.js

@@ -585,6 +585,12 @@ function __webjsReportVisibility(send) {
   });
   globalThis.__webjsDevActivity = activity;
 }
+let __webjsFellBack = false;
+function __webjsFallBack() {
+  if (__webjsFellBack) return;
+  __webjsFellBack = true;
+  __webjsDirectEvents();
+}
 try {
   if (typeof SharedWorker !== 'undefined') {
     const w = new SharedWorker(${workerUrl});
@@ -593,13 +599,25 @@ try {
       if (m.type === 'reload') __webjsApplyReload(m.verdict);
       else if (m.type === 'webjs-error') __webjsApplyError(m.data);
     };
+    // The worker's SCRIPT can fail to load where the page itself loaded: a
+    // host that admits the page on a partitioned cookie, which Chromium does
+    // not send with a shared worker's script request from a third-party frame
+    // (a private preview embedded in a builder). That is an error event, not a
+    // throw, so without this the tab would get no reloads and no error
+    // overlay at all. Fall back to this tab's own EventSource, which the page's
+    // cookies do reach.
+    w.onerror = function () {
+      w.port.onmessage = null;
+      try { w.port.close(); } catch (_) { /* already gone */ }
+      __webjsFallBack();
+    };
     w.port.start();
-    __webjsReportVisibility(function (msg) { w.port.postMessage(msg); });
+    __webjsReportVisibility(function (msg) { if (!__webjsFellBack) w.port.postMessage(msg); });
   } else {
-    __webjsDirectEvents();
+    __webjsFallBack();
   }
 } catch (_) {
-  __webjsDirectEvents();
+  __webjsFallBack();
 }
 `;
 }

package/src/dev/serve.js

@@ -35,6 +35,7 @@ import { toUrlPath } from '../ssr/preloads.js';
 import { BUFFERED_MARKER } from '../conditional-get.js';
 import { MIME, TS_CACHE_MAX, exists, reloadClientJs, reloadWorkerJs } from './helpers.js';
 import { devImportSpecifier } from '../dev-import.js';
+import { runMetadataRoute } from '../metadata-routes.js';
 
 /**
  * Serve framework-internal static assets that depend on NEITHER the whole-app
@@ -363,20 +364,10 @@ export async function handleCore(req, ctx) {
     const meta = state.routeTable.metadataRoutes.find((r) => r.urlPath === path);
     if (meta) {
       try {
-        const mod = await import(devImportSpecifier(meta.file, dev));
-        if (mod.default) {
-          const result = await mod.default();
-          // If the function returns a Response, use it directly.
-          if (result instanceof Response) return result;
-          // If it returns a string, determine content type from the URL path.
-          const ct = path.endsWith('.xml') ? 'application/xml; charset=utf-8'
-            : path.endsWith('.txt') ? 'text/plain; charset=utf-8'
-            : path.endsWith('.json') ? 'application/json; charset=utf-8'
-            : 'application/octet-stream';
-          return new Response(typeof result === 'string' ? result : JSON.stringify(result), {
-            headers: { 'content-type': ct, 'cache-control': dev ? 'no-cache' : 'public, max-age=3600' },
-          });
-        }
+        // The route gets `{ request, url, siteUrl, pages }` and may return a
+        // Response, a string, or Next's sitemap array / robots object (#1564).
+        const res = await runMetadataRoute(meta, { req, url, path, dev, routeTable: state.routeTable });
+        if (res) return res;
       } catch (e) {
         if (reportError) reportError(e, req, 'metadata');
         if (dev) console.error(`[webjs] metadata route error (${meta.stem}):`, e);

package/src/metadata-routes.js

@@ -0,0 +1,199 @@
+/**
+ * Metadata route dispatch (`app/sitemap.ts`, `app/robots.ts`, `app/manifest.ts`,
+ * the image routes) and the page listing a sitemap is built from (#1564).
+ *
+ * A metadata route's default export is called with a context:
+ *
+ *   { request, url, siteUrl, pages }
+ *
+ * - `siteUrl` is the app's public origin: `SITE_URL` when set, else the
+ *   request origin (forwarded headers applied). A sitemap must list absolute
+ *   URLs, and only the request knows the host when no site URL is configured.
+ * - `pages()` lists every public page as sitemap entries (see `listPages`).
+ *
+ * Return values: a `Response` is sent as is; a string is sent with a content
+ * type picked from the URL; an ARRAY from `sitemap` is serialized with
+ * `sitemap()` (relative URLs resolved against `siteUrl`); an OBJECT from
+ * `robots` is serialized with `robots()`; any other object is JSON. The last
+ * two are Next's `MetadataRoute.Sitemap` / `MetadataRoute.Robots` shapes, so
+ * code written the Next way works unchanged.
+ */
+import { sitemap as sitemapXml, robots as robotsTxt } from './sitemap.js';
+import { isUrlSegment } from './router.js';
+import { devImportSpecifier } from './dev-import.js';
+import { siteUrlFromEnv } from './ssr/seo.js';
+import { basePath } from './importmap.js';
+import { withBasePath } from './base-path.js';
+
+/**
+ * @typedef {{ url: string, lastModified?: string | Date, changeFrequency?: string, priority?: number }} PageEntry
+ */
+
+/**
+ * Whether a page's static metadata chain (layouts, then the page; the deepest
+ * `robots` wins, matching the metadata merge) asks search engines not to index.
+ * Only the static `metadata` export is read: `generateMetadata` may depend on
+ * the request (a session, a record), which a sitemap request does not carry.
+ * @param {string[]} files
+ * @param {boolean} dev
+ */
+async function isNoindex(files, dev) {
+  /** @type {unknown} */
+  let robots;
+  for (const file of files) {
+    try {
+      const mod = await import(devImportSpecifier(file, dev));
+      if (mod.metadata && typeof mod.metadata === 'object' && mod.metadata.robots !== undefined) {
+        robots = mod.metadata.robots;
+      }
+    } catch {
+      // A module that fails to load is reported when the page renders.
+    }
+  }
+  if (typeof robots === 'string') return /\bnoindex\b|\bnone\b/i.test(robots);
+  if (robots && typeof robots === 'object') return /** @type {any} */ (robots).index === false;
+  return false;
+}
+
+/**
+ * Fill a dynamic route's segments from one params object, or null when a
+ * param is missing.
+ * @param {string[]} segs URL segments (groups and private folders removed)
+ * @param {Record<string, unknown>} params
+ */
+function fillSegments(segs, params) {
+  const out = [];
+  for (const seg of segs) {
+    const optional = seg.startsWith('[[...') && seg.endsWith(']]');
+    const rest = !optional && seg.startsWith('[...') && seg.endsWith(']');
+    if (optional || rest) {
+      const name = optional ? seg.slice(5, -2) : seg.slice(4, -1);
+      const v = params[name];
+      const parts = Array.isArray(v) ? v.map(String) : v == null || v === '' ? [] : [String(v)];
+      if (!parts.length && rest) return null;
+      out.push(...parts.map(encodeURIComponent));
+    } else if (seg.startsWith('[') && seg.endsWith(']')) {
+      const v = params[seg.slice(1, -1)];
+      if (v == null || v === '') return null;
+      out.push(encodeURIComponent(String(v)));
+    } else {
+      out.push(seg);
+    }
+  }
+  return '/' + out.join('/');
+}
+
+/**
+ * List the app's public pages as sitemap entries.
+ *
+ * - Every static page route, with route groups and private folders removed.
+ * - A dynamic route only when its page exports `generateSitemapParams()`,
+ *   returning params objects (`[{ slug: 'a' }]`) or entries carrying them
+ *   (`[{ params: { slug: 'a' }, lastModified }]`), typically from a query.
+ * - Skipped: a page whose static metadata chain says `robots: { index: false }`
+ *   (or a `noindex` string), and parallel-route slots (`@x`) / interception
+ *   folders (`(.)x`), which are not addressable pages on their own.
+ *
+ * @param {{ pages: Array<{ file: string, routeDir: string, metadataFiles: string[] }> }} routeTable
+ * @param {{ siteUrl: string, dev: boolean }} opts
+ * @returns {Promise<PageEntry[]>}
+ */
+export async function listPages(routeTable, { siteUrl, dev }) {
+  const bp = basePath();
+  const abs = (/** @type {string} */ path) => siteUrl + withBasePath(path, bp);
+  /** @type {PageEntry[]} */
+  const out = [];
+  const seen = new Set();
+  const push = (/** @type {PageEntry} */ e) => {
+    if (seen.has(e.url)) return;
+    seen.add(e.url);
+    out.push(e);
+  };
+  for (const page of routeTable.pages) {
+    const dirSegs = page.routeDir === '.' ? [] : page.routeDir.split('/');
+    if (dirSegs.some((s) => s.startsWith('@') || /^\(\.+\)/.test(s))) continue;
+    if (await isNoindex(page.metadataFiles || [page.file], dev)) continue;
+    const segs = dirSegs.filter(isUrlSegment);
+    if (!segs.some((s) => s.startsWith('['))) {
+      push({ url: abs(segs.length ? '/' + segs.join('/') : '/') });
+      continue;
+    }
+    let mod;
+    try {
+      mod = await import(devImportSpecifier(page.file, dev));
+    } catch {
+      continue;
+    }
+    if (typeof mod.generateSitemapParams !== 'function') continue;
+    const list = await mod.generateSitemapParams();
+    for (const item of Array.isArray(list) ? list : []) {
+      if (!item || typeof item !== 'object') continue;
+      const entry = item.params && typeof item.params === 'object' ? item : { params: item };
+      const path = fillSegments(segs, entry.params);
+      if (!path) continue;
+      /** @type {PageEntry} */
+      const e = { url: abs(path) };
+      if (entry.lastModified) e.lastModified = entry.lastModified;
+      if (entry.changeFrequency) e.changeFrequency = entry.changeFrequency;
+      if (typeof entry.priority === 'number') e.priority = entry.priority;
+      push(e);
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve each entry's url against the site URL (an author may return paths).
+ * @param {unknown[]} entries
+ * @param {string} siteUrl
+ */
+function absoluteEntries(entries, siteUrl) {
+  return entries.map((e) => {
+    if (!e || typeof e !== 'object' || typeof (/** @type {any} */ (e).url) !== 'string') return e;
+    const url = /** @type {any} */ (e).url;
+    if (/^https?:\/\//i.test(url)) return e;
+    try {
+      return { ...e, url: new URL(url, siteUrl + '/').toString() };
+    } catch {
+      return e;
+    }
+  });
+}
+
+/**
+ * Run a metadata route and turn its return value into a Response.
+ * @param {{ stem: string, file: string, urlPath: string }} meta
+ * @param {{ req: Request, url: URL, path: string, dev: boolean, routeTable: any }} opts
+ * @returns {Promise<Response | null>} null when the module has no default export
+ */
+export async function runMetadataRoute(meta, { req, url, path, dev, routeTable }) {
+  const mod = await import(devImportSpecifier(meta.file, dev));
+  if (typeof mod.default !== 'function') return null;
+  const siteUrl = siteUrlFromEnv() || url.origin;
+  const ctx = {
+    request: req,
+    url,
+    siteUrl,
+    pages: () => listPages(routeTable, { siteUrl, dev }),
+  };
+  const result = await mod.default(ctx);
+  if (result instanceof Response) return result;
+  const cacheControl = dev ? 'no-cache' : 'public, max-age=3600';
+  if (meta.stem === 'sitemap' && Array.isArray(result)) {
+    return new Response(sitemapXml(/** @type {any} */ (absoluteEntries(result, siteUrl))), {
+      headers: { 'content-type': 'application/xml; charset=utf-8', 'cache-control': cacheControl },
+    });
+  }
+  if (meta.stem === 'robots' && result && typeof result === 'object') {
+    return new Response(robotsTxt(/** @type {any} */ (result)), {
+      headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': cacheControl },
+    });
+  }
+  const ct = path.endsWith('.xml') ? 'application/xml; charset=utf-8'
+    : path.endsWith('.txt') ? 'text/plain; charset=utf-8'
+    : path.endsWith('.json') ? 'application/json; charset=utf-8'
+    : 'application/octet-stream';
+  return new Response(typeof result === 'string' ? result : JSON.stringify(result), {
+    headers: { 'content-type': ct, 'cache-control': cacheControl },
+  });
+}

package/src/router.js

@@ -157,7 +157,10 @@ export async function buildRouteTable(appDir) {
     } else if (METADATA_STEMS.has(stem) && (dir === '.' || dir.split('/').every(s => !s.startsWith('[')))) {
       // Metadata route: sitemap.ts, robots.ts, icon.ts, etc.
       // Only at root or static segments (no dynamic params in metadata routes).
-      const urlPath = METADATA_URL_MAP[stem] || `/${stem}`;
+      // A nested route answers under its own segment (`app/blog/opengraph-image.ts`
+      // -> `/blog/opengraph-image`, #1564); route groups add no URL segment.
+      const prefix = dir === '.' ? '' : '/' + dir.split('/').filter(isUrlSegment).join('/');
+      const urlPath = (prefix === '/' ? '' : prefix) + (METADATA_URL_MAP[stem] || `/${stem}`);
       metadataRoutes.push({ stem, file, urlPath });
     } else if (stem === 'route') {
       // route.js / route.ts can live anywhere under app/ (matches NextJs).
@@ -227,7 +230,7 @@ function chainOf(routeDir) {
 }
 
 /** @param {string} seg */
-function isUrlSegment(seg) {
+export function isUrlSegment(seg) {
   if (seg.startsWith('(') && seg.endsWith(')')) return false; // route group
   if (seg.startsWith('_')) return false; // private
   return true;

package/src/sitemap.js

@@ -159,3 +159,52 @@ export function sitemapIndex(sitemaps) {
     '</sitemapindex>\n'
   );
 }
+
+/**
+ * One `User-agent` group for {@link robots}.
+ * @typedef {object} RobotsRule
+ * @property {string | string[]} [userAgent] Defaults to `*`.
+ * @property {string | string[]} [allow]
+ * @property {string | string[]} [disallow]
+ * @property {number} [crawlDelay]
+ */
+
+/**
+ * The Next.js `MetadataRoute.Robots` shape.
+ * @typedef {object} RobotsConfig
+ * @property {RobotsRule | RobotsRule[]} [rules] Defaults to allow everything.
+ * @property {string | string[]} [sitemap] Absolute sitemap URL(s).
+ * @property {string} [host]
+ */
+
+/** @param {unknown} v @returns {string[]} */
+const listOf = (v) => (Array.isArray(v) ? v : v == null ? [] : [v])
+  .map((x) => String(x).replace(/[\r\n]/g, ''))
+  .filter((x) => x !== '');
+
+/**
+ * Serialize a robots config into robots.txt text (#1564). An `app/robots.ts`
+ * may return this object directly; the server runs it through here. Newlines
+ * are stripped from every value so a data-derived path cannot inject a rule.
+ * @param {RobotsConfig} [config]
+ * @returns {string}
+ */
+export function robots(config = {}) {
+  const rules = config.rules == null ? [{ userAgent: '*', allow: '/' }]
+    : Array.isArray(config.rules) ? config.rules : [config.rules];
+  const blocks = [];
+  for (const rule of rules) {
+    if (!rule || typeof rule !== 'object') continue;
+    const agents = listOf(rule.userAgent);
+    const lines = (agents.length ? agents : ['*']).map((a) => `User-agent: ${a}`);
+    for (const a of listOf(rule.allow)) lines.push(`Allow: ${a}`);
+    for (const d of listOf(rule.disallow)) lines.push(`Disallow: ${d}`);
+    if (typeof rule.crawlDelay === 'number' && rule.crawlDelay >= 0) lines.push(`Crawl-delay: ${rule.crawlDelay}`);
+    blocks.push(lines.join('\n'));
+  }
+  const tail = [];
+  for (const h of listOf(config.host)) tail.push(`Host: ${h}`);
+  for (const s of listOf(config.sitemap)) tail.push(`Sitemap: ${s}`);
+  if (tail.length) blocks.push(tail.join('\n'));
+  return blocks.join('\n\n') + '\n';
+}

package/src/ssr/head.js

@@ -8,6 +8,7 @@ import { publicEnvShim } from './env-shim.js';
 import { clientRouterEnabled } from './client-router-flag.js';
 import { embedScriptTag } from '../dev-embed.js';
 import { devReloadState } from '../dev-reload-state.js';
+import { openGraphPairs, twitterPairs, setMetadataImageRoutes } from './seo.js';
 
 // Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
 // Set at boot and on each route rebuild from the route table, the same shape
@@ -32,6 +33,9 @@ export function setMetadataIconRoutes(metadataRoutes) {
   const stems = new Set();
   for (const r of metadataRoutes || []) if (r && r.stem) stems.add(r.stem);
   _metadataIconRoutes = { icon: stems.has('icon'), apple: stems.has('apple-icon') };
+  // The share-image routes (#1564) are recorded from the same table so one
+  // call keeps both in step on boot and on every rebuild.
+  setMetadataImageRoutes(metadataRoutes);
 }
 
 /**
@@ -348,7 +352,8 @@ export function wrapHead(opts) {
   // value looks like a relative URL (no scheme, no `//` prefix), resolve
   // it. Otherwise return as-is. Used by og:image, twitter:image,
   // alternates.canonical / languages / media.
-  const base = typeof m.metadataBase === 'string' ? m.metadataBase : '';
+  const base = m.metadataBase instanceof URL ? m.metadataBase.toString()
+    : typeof m.metadataBase === 'string' ? m.metadataBase : '';
   /** @param {unknown} v */
   const absUrl = (v) => {
     const s = String(v);
@@ -556,10 +561,11 @@ export function wrapHead(opts) {
     }
   }
 
+  // Open Graph: both the Next shape (`images` array / objects, camelCase
+  // `siteName`, article fields) and the raw `og:<key>` shape (#1564).
   if (m.openGraph && typeof m.openGraph === 'object') {
-    for (const [k, v] of Object.entries(m.openGraph)) {
-      const out = k === 'image' || k === 'url' ? absUrl(v) : String(v);
-      metaTags.push(`<meta property="og:${escapeAttr(k)}" content="${escapeAttr(out)}">`);
+    for (const [prop, value] of openGraphPairs(m.openGraph, absUrl)) {
+      metaTags.push(`<meta property="${escapeAttr(prop)}" content="${escapeAttr(value)}">`);
     }
   }
 
@@ -567,9 +573,8 @@ export function wrapHead(opts) {
   // but won't upgrade to summary_large_image without an explicit
   // twitter:card entry.
   if (m.twitter && typeof m.twitter === 'object') {
-    for (const [k, v] of Object.entries(m.twitter)) {
-      const out = k === 'image' ? absUrl(v) : String(v);
-      metaTags.push(`<meta name="twitter:${escapeAttr(k)}" content="${escapeAttr(out)}">`);
+    for (const [name, value] of twitterPairs(m.twitter, absUrl)) {
+      metaTags.push(`<meta name="${escapeAttr(name)}" content="${escapeAttr(value)}">`);
     }
   }
 

package/src/ssr/render.js

@@ -18,6 +18,7 @@ import {
   cachedHtmlResponse, getNonce, htmlResponse, streamingHtmlResponse,
 } from './responses.js';
 import { devImportSpecifier } from '../dev-import.js';
+import { applySeoDefaults } from './seo.js';
 
 
 /**
@@ -192,7 +193,11 @@ async function collectMetadata(route, ctx, dev) {
       // ignore: metadata collection never fails the request
     }
   }
-  return meta;
+  try {
+    return applySeoDefaults(meta, { url: String(ctx.url) });
+  } catch {
+    return meta;
+  }
 }
 
 /**

package/src/ssr/seo.js

@@ -0,0 +1,268 @@
+/**
+ * Search and share defaults for page metadata (#1564).
+ *
+ * `applySeoDefaults()` runs once per page render, after the layout + page
+ * metadata has been merged, and fills in the tags every public page should
+ * carry when the author did not set them:
+ *
+ *   - `metadataBase` from the `SITE_URL` env var (the app's public origin), so
+ *     relative canonical / og:image / og:url values become absolute;
+ *   - a canonical URL (site URL + pathname, no query) when a site URL is known;
+ *   - `og:title` / `og:description` from `title` / `description`, `og:type`
+ *     `website`, `og:url` from the canonical;
+ *   - `og:image` / `twitter:image` from an `opengraph-image` / `twitter-image`
+ *     metadata route (the nearest one above the page), Next's behaviour;
+ *   - `twitter:card` (`summary_large_image` when there is an image).
+ *
+ * Every default yields to an explicit value, and `alternates.canonical: null`
+ * opts a page out of the canonical. The canonical NEVER falls back to the
+ * request origin: the forwarded host is client-influenced (see forwarded.js),
+ * so only a configured site URL is trusted to name the public address.
+ *
+ * Defaults are added only when the page has something to say (a title, a
+ * description, an image or a site URL), so an app with no metadata renders the
+ * same head it always did.
+ */
+import { basePath } from '../importmap.js';
+import { withBasePath } from '../base-path.js';
+
+/**
+ * The `opengraph-image` / `twitter-image` metadata routes, as
+ * `{ prefix, urlPath }` (prefix = the URL segment the route sits in). Set at
+ * boot and on every route rebuild, beside the icon routes in head.js.
+ * @type {{ og: Array<{ prefix: string, urlPath: string }>, tw: Array<{ prefix: string, urlPath: string }> }}
+ */
+let _imageRoutes = { og: [], tw: [] };
+
+/**
+ * Record the image metadata routes the app defines.
+ * @param {Iterable<{ stem: string, urlPath: string }> | null | undefined} metadataRoutes
+ */
+export function setMetadataImageRoutes(metadataRoutes) {
+  /** @type {typeof _imageRoutes} */
+  const next = { og: [], tw: [] };
+  for (const r of metadataRoutes || []) {
+    if (!r || !r.urlPath) continue;
+    const list = r.stem === 'opengraph-image' ? next.og : r.stem === 'twitter-image' ? next.tw : null;
+    if (!list) continue;
+    const prefix = r.urlPath.slice(0, r.urlPath.lastIndexOf('/')) || '/';
+    list.push({ prefix, urlPath: r.urlPath });
+  }
+  // Deepest first, so the nearest route above a page wins.
+  next.og.sort((a, b) => b.prefix.length - a.prefix.length);
+  next.tw.sort((a, b) => b.prefix.length - a.prefix.length);
+  _imageRoutes = next;
+}
+
+/**
+ * The nearest image route whose segment contains `pathname`.
+ * @param {Array<{ prefix: string, urlPath: string }>} list
+ * @param {string} pathname
+ */
+function nearestImageRoute(list, pathname) {
+  for (const r of list) {
+    if (r.prefix === '/' || pathname === r.prefix || pathname.startsWith(r.prefix + '/')) {
+      return withBasePath(r.urlPath, basePath());
+    }
+  }
+  return null;
+}
+
+/**
+ * The configured public origin of the app: `SITE_URL`, trimmed of a trailing
+ * slash, or '' when unset or not an http(s) URL.
+ * @returns {string}
+ */
+export function siteUrlFromEnv() {
+  const raw = typeof process !== 'undefined' && process.env ? process.env.SITE_URL : '';
+  if (!raw) return '';
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return '';
+    return u.toString().replace(/\/$/, '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * `metadataBase` as a string (Next allows a URL object), or ''.
+ * @param {unknown} v
+ */
+function baseString(v) {
+  if (v instanceof URL) return v.toString();
+  if (typeof v === 'string') return v;
+  return '';
+}
+
+/** @param {unknown} v */
+const hasImage = (v) => v != null && v !== '' && !(Array.isArray(v) && v.length === 0);
+
+/**
+ * Fill in search and share defaults on merged page metadata. Pure apart from
+ * reading `SITE_URL` and the recorded image routes; never throws.
+ *
+ * @param {Record<string, any>} meta merged metadata (not mutated)
+ * @param {{ url: string }} ctx the page render context (`url` is the request URL)
+ * @returns {Record<string, any>}
+ */
+export function applySeoDefaults(meta, ctx) {
+  /** @type {Record<string, any>} */
+  const m = { ...meta };
+  let pathname = '/';
+  try {
+    pathname = new URL(ctx.url).pathname;
+  } catch {
+    // keep '/'
+  }
+
+  const base = baseString(m.metadataBase) || siteUrlFromEnv();
+  if (base) m.metadataBase = base;
+  else delete m.metadataBase;
+
+  // Canonical: explicit wins, `null` opts out, else site URL + pathname.
+  const alternates = m.alternates && typeof m.alternates === 'object' ? { ...m.alternates } : null;
+  if (alternates && alternates.canonical === null) {
+    delete alternates.canonical;
+    m.alternates = alternates;
+  } else if (base && (!alternates || alternates.canonical === undefined)) {
+    m.alternates = { ...(alternates || {}), canonical: withBasePath(pathname, basePath()) };
+  }
+  const canonical = m.alternates && m.alternates.canonical;
+
+  const title = typeof m.title === 'string' ? m.title : '';
+  const description = typeof m.description === 'string' ? m.description : '';
+  const ogImageRoute = nearestImageRoute(_imageRoutes.og, pathname);
+  const twImageRoute = nearestImageRoute(_imageRoutes.tw, pathname);
+
+  const og = m.openGraph && typeof m.openGraph === 'object' ? { ...m.openGraph } : null;
+  const tw = m.twitter && typeof m.twitter === 'object' ? { ...m.twitter } : null;
+  const ogHasImage = og && (hasImage(og.images) || hasImage(og.image));
+  const twHasImage = tw && (hasImage(tw.images) || hasImage(tw.image));
+  const worthIt = title || description || base || og || tw || ogImageRoute || twImageRoute;
+  if (!worthIt) return m;
+
+  const o = og || {};
+  if (o.title == null && title) o.title = title;
+  if (o.description == null && description) o.description = description;
+  if (o.url == null && canonical) o.url = canonical;
+  if (o.type == null) o.type = 'website';
+  if (!ogHasImage && ogImageRoute) o.images = [ogImageRoute];
+  m.openGraph = o;
+
+  const t = tw || {};
+  // Without a twitter image, X reads og:image on its own; only the card type
+  // needs saying, so the larger preview is used.
+  if (!twHasImage && twImageRoute) t.images = [twImageRoute];
+  if (t.card == null) {
+    const anyImage = hasImage(t.images) || hasImage(t.image) || hasImage(o.images) || hasImage(o.image);
+    t.card = anyImage ? 'summary_large_image' : 'summary';
+  }
+  m.twitter = t;
+  return m;
+}
+
+/** camelCase -> snake_case for an Open Graph property (`siteName` -> `site_name`). */
+const snake = (/** @type {string} */ k) => k.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase());
+
+/** Open Graph article fields Next exposes in camelCase, emitted as `article:*`. */
+const ARTICLE_KEYS = /** @type {Record<string, string>} */ ({
+  publishedTime: 'article:published_time',
+  modifiedTime: 'article:modified_time',
+  expirationTime: 'article:expiration_time',
+  authors: 'article:author',
+  section: 'article:section',
+  tags: 'article:tag',
+});
+
+/** Media keys and the property they emit. */
+const OG_MEDIA = /** @type {Record<string, string>} */ ({
+  images: 'og:image', image: 'og:image',
+  videos: 'og:video', video: 'og:video',
+  audio: 'og:audio',
+});
+
+/**
+ * Turn `metadata.openGraph` into `[property, value]` pairs. Accepts both the
+ * Next shape (`images` as a string, URL, object or array, camelCase keys,
+ * article fields) and the raw `og:<key>` shape (`image`, `site_name`,
+ * `'image:width'`).
+ *
+ * @param {Record<string, any>} og
+ * @param {(u: unknown) => string} absUrl
+ * @returns {Array<[string, string]>}
+ */
+export function openGraphPairs(og, absUrl) {
+  /** @type {Array<[string, string]>} */
+  const out = [];
+  for (const [k, v] of Object.entries(og)) {
+    if (v == null || v === false || v === '') continue;
+    if (OG_MEDIA[k]) {
+      mediaPairs(out, OG_MEDIA[k], v, absUrl);
+    } else if (ARTICLE_KEYS[k]) {
+      for (const item of Array.isArray(v) ? v : [v]) out.push([ARTICLE_KEYS[k], item instanceof Date ? item.toISOString() : String(item)]);
+    } else if (k === 'url') {
+      out.push(['og:url', absUrl(v)]);
+    } else if (Array.isArray(v)) {
+      for (const item of v) out.push(['og:' + snake(k), String(item)]);
+    } else if (typeof v !== 'object' || v instanceof URL) {
+      out.push(['og:' + snake(k), String(v)]);
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {Array<[string, string]>} out
+ * @param {string} prop e.g. `og:image` / `twitter:image`
+ * @param {unknown} v string | URL | { url, width, height, alt, type, secureUrl } | array of those
+ * @param {(u: unknown) => string} absUrl
+ */
+function mediaPairs(out, prop, v, absUrl) {
+  for (const item of Array.isArray(v) ? v : [v]) {
+    if (item == null || item === '') continue;
+    if (typeof item === 'string' || item instanceof URL) {
+      out.push([prop, absUrl(item)]);
+      continue;
+    }
+    if (typeof item !== 'object') continue;
+    const rec = /** @type {Record<string, unknown>} */ (item);
+    if (!rec.url) continue;
+    out.push([prop, absUrl(rec.url)]);
+    for (const [ik, iv] of Object.entries(rec)) {
+      if (ik === 'url' || iv == null || iv === '') continue;
+      const sub = ik === 'secureUrl' ? 'secure_url' : snake(ik);
+      out.push([`${prop}:${sub}`, sub === 'secure_url' ? absUrl(iv) : String(iv)]);
+    }
+  }
+}
+
+/**
+ * Turn `metadata.twitter` into `[name, value]` pairs (`images` -> repeated
+ * `twitter:image` + `twitter:image:alt`, `siteId` -> `twitter:site:id`).
+ *
+ * @param {Record<string, any>} tw
+ * @param {(u: unknown) => string} absUrl
+ * @returns {Array<[string, string]>}
+ */
+export function twitterPairs(tw, absUrl) {
+  /** @type {Array<[string, string]>} */
+  const out = [];
+  for (const [k, v] of Object.entries(tw)) {
+    if (v == null || v === false || v === '') continue;
+    if (k === 'images' || k === 'image') {
+      for (const item of Array.isArray(v) ? v : [v]) {
+        if (typeof item === 'string' || item instanceof URL) out.push(['twitter:image', absUrl(item)]);
+        else if (item && typeof item === 'object' && item.url) {
+          out.push(['twitter:image', absUrl(item.url)]);
+          if (item.alt) out.push(['twitter:image:alt', String(item.alt)]);
+        }
+      }
+    } else if (k === 'siteId' || k === 'creatorId') {
+      out.push([`twitter:${k.slice(0, -2)}:id`, String(v)]);
+    } else if (typeof v !== 'object') {
+      out.push(['twitter:' + k, String(v)]);
+    }
+  }
+  return out;
+}