@opentf/web 0.5.0 → 0.6.0

package/runtime/hydrate.js

@@ -0,0 +1,121 @@
+// Hydration primitives (Phase 2 — see docs/HYDRATION.md). The client *adopts* the
+// server-rendered DOM instead of rebuilding it: it claims existing nodes and wires
+// reactivity (bindText/bindAttr/events from dom.js) onto them. There is no separate
+// "hydrate" binding logic — those helpers already operate on existing nodes; the only
+// new work is *node acquisition*, which is what this module provides.
+//
+// Acquisition is a **cursor walk** (the decided approach, like Solid): the Hydrate
+// codegen emits claim calls in the exact order the SSG backend emitted nodes, so a
+// cursor over a parent's childNodes lines up 1:1 with the template. The server output
+// carries no inter-element whitespace (ssg.rs concatenates with no padding), so the
+// re-parsed DOM has text nodes only where the template does — the walk stays aligned.
+//
+// Markers (only where structure is variable): a dynamic text hole is delimited by
+// `<!--$-->value<!--/-->` so it is findable even when the value is empty or adjacent
+// to static text (which the HTML parser would otherwise merge into one text node).
+// Static structure carries no markers and is claimed by position.
+
+/** Comment markers bounding a dynamic text hole in server HTML. */
+export const HOLE_START = "$";
+export const HOLE_END = "/";
+
+const ELEMENT = 1;
+const TEXT = 3;
+const COMMENT = 8;
+
+/** Thrown when the server DOM doesn't match the template at a claim site. The
+ * component boundary catches this and recovers by rebuilding via CSR (never silent;
+ * see docs/HYDRATION.md §3.5). */
+export class HydrationMismatch extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HydrationMismatch";
+  }
+}
+
+// ── the hydration flag ────────────────────────────────────────────────────────
+// True during the initial hydration pass. A component's connectedCallback reads it
+// to decide whether to *adopt* its server children or *build* a fresh subtree — the
+// custom-element-as-island coordination (docs/HYDRATION.md §3.4).
+let _hydrating = false;
+
+/** Is the client mid-hydration right now? */
+export function isHydrating() {
+  return _hydrating;
+}
+
+/** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe). */
+export function runHydration(fn) {
+  const prev = _hydrating;
+  _hydrating = true;
+  try {
+    return fn();
+  } finally {
+    _hydrating = prev;
+  }
+}
+
+// ── the cursor ────────────────────────────────────────────────────────────────
+
+/** A walker over `parent`'s children, positioned at the next node to claim. */
+export function cursor(parent) {
+  return { node: parent.firstChild };
+}
+
+/** Advance past the next node without claiming it (a static text node between
+ * dynamic siblings), returning it. */
+export function skipNode(cur) {
+  const n = cur.node;
+  cur.node = n ? n.nextSibling : null;
+  return n;
+}
+
+/**
+ * Claim the next node as an element, optionally asserting its tag, and advance the
+ * cursor past it. Returns the element so the caller can claim its children with a
+ * fresh `cursor(el)`. A wrong/absent node throws {@link HydrationMismatch}.
+ */
+export function claimElement(cur, tag) {
+  const el = cur.node;
+  if (!el || el.nodeType !== ELEMENT || (tag && el.tagName.toLowerCase() !== tag.toLowerCase())) {
+    throw new HydrationMismatch(`expected <${tag ?? "element"}>, found ${describe(el)}`);
+  }
+  cur.node = el.nextSibling;
+  return el;
+}
+
+/**
+ * Claim a dynamic text hole delimited by `<!--$-->…<!--/-->`, returning the text node
+ * to bind onto (created empty when the server rendered no value), and advance the
+ * cursor past the closing marker. Wire reactivity with `bindText(node, fn)` from
+ * dom.js — the binding logic is shared with CSR; only the node is adopted, not built.
+ */
+export function claimText(cur) {
+  const start = cur.node;
+  if (!start || start.nodeType !== COMMENT || start.data !== HOLE_START) {
+    throw new HydrationMismatch(`expected a text-hole marker, found ${describe(start)}`);
+  }
+  let node = start.nextSibling;
+  let textNode = null;
+  while (node && !(node.nodeType === COMMENT && node.data === HOLE_END)) {
+    if (node.nodeType === TEXT && !textNode) textNode = node;
+    node = node.nextSibling;
+  }
+  const end = node; // the `<!--/-->` marker (or null if the markup is malformed)
+  if (!textNode) {
+    // Empty hole (`<!--$--><!--/-->`): synthesize the anchor bindText will write into.
+    textNode = document.createTextNode("");
+    (start.parentNode || document).insertBefore(textNode, end);
+  }
+  cur.node = end ? end.nextSibling : null;
+  return textNode;
+}
+
+/** A short human description of a node for mismatch messages. */
+function describe(node) {
+  if (!node) return "nothing";
+  if (node.nodeType === ELEMENT) return `<${node.tagName.toLowerCase()}>`;
+  if (node.nodeType === TEXT) return `text "${(node.data || "").slice(0, 20)}"`;
+  if (node.nodeType === COMMENT) return `comment <!--${node.data}-->`;
+  return `node(${node.nodeType})`;
+}

package/runtime/index.js

@@ -1,16 +1,22 @@
 // Built-in custom elements self-register on import. They're used in JSX as *tags*
-// (`<Portal>` → `web-portal`), so their bindings are never referenced and a plain
+// (`<Portal>` → `web-internal-portal`), so their bindings are never referenced and a plain
 // re-export would be tree-shaken away (the element never registers). Bare imports
 // force the registration side effect to be retained.
 import "./context.js";
 import "./error-boundary.js";
 import "./portal.js";
+import "./raw-html.js";
+import "./code-block.js";
 
 export * from "./dom.js";
 export * from "./events.js";
 export * from "./mount.js";
+export * from "./hydrate.js";
 export * from "./lifecycle.js";
 export * from "./router.js";
 export * from "./context.js";
 export * from "./error-boundary.js";
 export * from "./portal.js";
+export * from "./raw-html.js";
+export * from "./code-block.js";
+export * from "./clipboard.js";

package/runtime/portal.js

@@ -3,7 +3,7 @@
 //
 //   <Portal to="#toast-root"> … </Portal>   // selector, element, or default body
 //
-// `<Portal>` compiles to this built-in `web-portal` element (capitalized name →
+// `<Portal>` compiles to this built-in `web-internal-portal` element (capitalized name →
 // tag, like <ContextProvider>) — no compiler changes. At connect it moves its
 // light-DOM children to the target; on disconnect it removes them so their
 // custom-element disconnect + effect cleanups run (the part userland leaks).
@@ -52,8 +52,8 @@ export class PortalElement extends HTMLElement {
 }
 
 // Exported so `import { Portal } from "@opentf/web"` resolves; the import side
-// effect registers the element (JSX uses the `web-portal` tag).
+// effect registers the element (JSX uses the `web-internal-portal` tag).
 export const Portal = PortalElement;
-if (typeof customElements !== "undefined" && !customElements.get("web-portal")) {
-  customElements.define("web-portal", PortalElement);
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-portal")) {
+  customElements.define("web-internal-portal", PortalElement);
 }

package/runtime/raw-html.js

@@ -0,0 +1,33 @@
+//! RawHtml — render a trusted HTML string as light-DOM content.
+//
+//   <RawHtml html={"<pre>…</pre>"} />   // compiles to the built-in `web-internal-raw-html`
+//
+// Used by the MDX front-end for build-time syntax-highlighted code blocks: the
+// highlighted markup is static (no reactivity), so the element just assigns its
+// `html` property to `innerHTML`. The string is treated as trusted — it comes from
+// the compiler, not user input. SSG renders the string inline (server/builtins.js).
+
+export class RawHtmlElement extends HTMLElement {
+  set html(v) {
+    this._html = v;
+    if (this.isConnected) this.innerHTML = v == null ? "" : String(v);
+  }
+  get html() {
+    return this._html;
+  }
+
+  connectedCallback() {
+    // Apply once on connect (the property is set before append during CSR build).
+    if (this._html != null && !this._applied) {
+      this.innerHTML = String(this._html);
+      this._applied = true;
+    }
+  }
+}
+
+// Exported so `import { RawHtml } from "@opentf/web"` resolves; the import side
+// effect registers the element (JSX uses the `web-internal-raw-html` tag).
+export const RawHtml = RawHtmlElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-raw-html")) {
+  customElements.define("web-internal-raw-html", RawHtmlElement);
+}

package/runtime/router.js

@@ -19,15 +19,102 @@ import { runCleanup, runMount } from "./mount.js";
 
 const isBrowser = typeof window !== "undefined";
 
+/**
+ * Drop a trailing slash (except for the root "/") so `router.pathname` matches the
+ * no-trailing-slash route table and nav paths regardless of how the URL was entered —
+ * a static host serves `/docs/x/`, a Pagefind result links to `/docs/x/`, etc. Without
+ * this, `/docs/x/` wouldn't match the `/docs/x` nav entry and the breadcrumb / active
+ * sidebar link / TOC would silently blank out.
+ */
+const normalizePath = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
 const state = {
-  pathname: signal(isBrowser ? window.location.pathname : "/"),
+  pathname: signal(isBrowser ? normalizePath(window.location.pathname) : "/"),
   searchParams: signal(new URLSearchParams(isBrowser ? window.location.search : "")),
   params: signal({}),
+  locale: signal(null),
 };
 
 export const routes = { pages: {}, layouts: {}, notFound: null };
 let guard = null;
 let rootEl = null;
+
+// Navigation mode (docs/HYDRATION.md §7): "spa" (default) lets the client router
+// intercept same-origin `<Link>` clicks for reload-free nav; "mpa" leaves every
+// navigation to the browser (full page load), with each page hydrating its own first
+// paint. MPA is always the substrate — this only toggles the SPA enhancement on top.
+let navMode = "spa";
+
+/** Whether the client router should intercept link clicks (SPA) vs. let the browser
+ *  do a full navigation (MPA). Read by `<Link>`. */
+export function shouldInterceptNav() {
+  return navMode === "spa";
+}
+
+// i18n: path-prefix locale routing (docs/I18N.md). The route table stays
+// locale-agnostic; a leading non-default locale segment is stripped before
+// matching and recorded as `router.locale`. `prefix_except_default`: the default
+// locale is served at the bare path, others are prefixed (`/fr/about`).
+let i18nConfig = null;
+
+/** Register the app's locales (called by `mountApp({ i18n })`). */
+export function configureI18n(cfg) {
+  if (!cfg || !Array.isArray(cfg.locales) || cfg.locales.length === 0) {
+    i18nConfig = null;
+    return;
+  }
+  const defaultLocale = cfg.defaultLocale ?? cfg.locales[0];
+  i18nConfig = {
+    locales: cfg.locales,
+    defaultLocale,
+    nonDefault: new Set(cfg.locales.filter((l) => l !== defaultLocale)),
+  };
+  state.locale.value = defaultLocale;
+}
+
+/** The configured locales + default, or null when i18n isn't enabled. */
+export function i18nLocales() {
+  return i18nConfig && { locales: i18nConfig.locales, defaultLocale: i18nConfig.defaultLocale };
+}
+
+/**
+ * Split a leading non-default locale segment off `pathname`, returning the active
+ * `locale` and the locale-agnostic `path` to match against the route table. When
+ * i18n is off, or the first segment isn't a configured non-default locale, the
+ * path passes through unchanged with the default (or null) locale.
+ */
+export function resolveLocale(pathname) {
+  const def = i18nConfig ? i18nConfig.defaultLocale : null;
+  if (!i18nConfig) return { locale: def, path: pathname };
+  const m = (pathname || "/").match(/^\/([^/]+)(\/.*|)$/);
+  if (m && i18nConfig.nonDefault.has(m[1])) return { locale: m[1], path: m[2] || "/" };
+  return { locale: def, path: pathname };
+}
+
+/**
+ * Prefix `path` with `locale` (bare for the default locale). Any locale already on
+ * `path` is replaced. Used by `<Link>` and programmatic navigation to keep links
+ * in the active locale. Pass-through when i18n is off.
+ */
+export function localizePath(path, locale = state.locale.value) {
+  if (!i18nConfig) return path;
+  // Strip ANY existing locale prefix (default included, unlike `resolveLocale`
+  // which keeps the canonical default bare) so a link can be re-pointed cleanly.
+  const m = (path || "/").match(/^\/([^/]+)(\/.*|)$/);
+  const bare = m && i18nConfig.locales.includes(m[1]) ? m[2] || "/" : path;
+  if (!locale || locale === i18nConfig.defaultLocale) return bare;
+  return bare === "/" ? `/${locale}` : `/${locale}${bare}`;
+}
+
+/**
+ * Set the active locale directly, without navigating. The reactive `router.locale`
+ * updates and any `t()`/formatter bindings re-render fine-grained. Intended for
+ * previews, tests, and programmatic control — in a routed app the locale is derived
+ * from the URL prefix (docs/I18N.md §2), so navigation is the normal path.
+ */
+export function setLocale(locale) {
+  state.locale.value = locale;
+}
 let currentNodes = [];
 
 /** Reactive router facade — getters read signal values (tracked in effects). */
@@ -44,6 +131,9 @@ export const router = {
   get params() {
     return state.params.value;
   },
+  get locale() {
+    return state.locale.value;
+  },
   push: (path) => navigate(path),
   replace: (path) => navigate(path, true),
 };
@@ -52,7 +142,7 @@ export const router = {
 function routeFromPath(filePath) {
   const r = filePath
     .replace(/^.*\/app/, "")
-    .replace(/\/(page|layout|404)\.(jsx|tsx)$/, "");
+    .replace(/\/(page|layout|404)\.(jsx|tsx|mdx|md)$/, "");
   return r === "" ? "/" : r;
 }
 
@@ -115,14 +205,20 @@ export async function buildRouteNode(match, query = {}) {
  * so a page reading `router.pathname`/`params`/`query` resolves to the route being
  * pre-rendered. The client uses `navigate` instead.
  */
-export function setRouteState({ pathname = "/", search = "", params = {} } = {}) {
-  state.pathname.value = pathname;
+export function setRouteState({ pathname = "/", search = "", params = {}, locale } = {}) {
+  state.pathname.value = normalizePath(pathname);
   state.searchParams.value = new URLSearchParams(search);
   state.params.value = params;
+  state.locale.value = locale !== undefined ? locale : resolveLocale(pathname).locale;
 }
 
-/** Match `pathname` against the registered routes, resolving `[param]` segments. */
+/**
+ * Match `pathname` against the registered routes, resolving `[param]` segments. A
+ * leading non-default locale segment is stripped first (the route table is
+ * locale-agnostic; see `resolveLocale`).
+ */
 export function matchRoute(pathname) {
+  pathname = resolveLocale(pathname).path;
   for (const route in routes.pages) {
     const pattern = route
       .replace(/\[\.\.\.([^\]]+)\]/g, "(?<$1>.+)")
@@ -143,7 +239,7 @@ export function matchRoute(pathname) {
  * Navigate to `path`. Runs an optional route guard, swaps the rendered page
  * (tearing down the previous one's lifecycle), and updates window.history.
  */
-export async function navigate(path, replace = false, isPop = false) {
+export async function navigate(path, replace = false, isPop = false, hydrate = false) {
   if (!path || !rootEl) return;
   const url = new URL(path, window.location.origin);
 
@@ -177,15 +273,38 @@ export async function navigate(path, replace = false, isPop = false) {
     matchRoute(url.pathname) ||
     (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
 
-  state.pathname.value = url.pathname;
+  state.pathname.value = normalizePath(url.pathname);
   state.searchParams.value = url.searchParams;
   state.params.value = match ? match.params : {};
+  state.locale.value = resolveLocale(url.pathname).locale;
 
   if (!isPop) {
     if (replace) window.history.replaceState({}, "", path);
     else window.history.pushState({}, "", path);
   }
 
+  // First paint over server-rendered DOM: *adopt* it (hydrate) instead of rebuilding,
+  // when the route module exposes a `hydrate` adopt factory (compiled with the hydrate
+  // target). Only leaf routes (no layout chain) hydrate so far — `{children}`-slot
+  // adoption is a later phase — so anything else falls through to a clean CSR build. A
+  // hydration mismatch is reported (never silent) and also falls through to a rebuild.
+  if (hydrate && match) {
+    try {
+      const mod = typeof match.entry === "function" ? await match.entry() : match.entry;
+      if (mod && typeof mod.hydrate === "function" && layoutChain(match.route).length === 0) {
+        const query = Object.fromEntries(url.searchParams);
+        const node = mod.hydrate(rootEl, { params: match.params, query });
+        currentNodes = [node];
+        runMount(node);
+        clearError({ phase: "route" });
+        return;
+      }
+    } catch (e) {
+      reportError(e, { phase: "hydrate", path: url.pathname });
+      // fall through to a clean CSR build below
+    }
+  }
+
   // Resolve (and lazily load) the page + its layout chain before tearing down the
   // current view, so a slow/failed import doesn't leave a blank page.
   let nodes = null;
@@ -210,6 +329,13 @@ export async function navigate(path, replace = false, isPop = false) {
     for (const n of nodes) runMount(n); // run onMount for page + every layout
     currentNodes = nodes;
     clearError({ phase: "route" }); // a good render dismisses a prior error overlay
+    // A forward navigation lands at the top of the new page (or at the targeted
+    // anchor); back/forward (`isPop`) keeps the browser's restored scroll position.
+    if (!isPop && isBrowser) {
+      const anchor = url.hash ? document.getElementById(decodeURIComponent(url.hash.slice(1))) : null;
+      if (anchor) anchor.scrollIntoView();
+      else window.scrollTo(0, 0);
+    }
   } else {
     rootEl.innerHTML = "<h1>404 — Not Found</h1>";
     currentNodes = [];
@@ -224,12 +350,18 @@ export async function navigate(path, replace = false, isPop = false) {
  * @param {Object} opts.pages  `{ path: module }` route map (from the dev server).
  * @param {Element} [opts.target]  the app root (defaults to `#app`).
  * @param {Function} [opts.guard]  optional `(to, tools) => …` route guard.
+ * @param {"spa"|"mpa"} [opts.nav]  navigation mode (default "spa"); "mpa" disables
+ *   client-side link interception so every navigation is a full page load.
  */
-export function mountApp({ pages, target, guard: g } = {}) {
+export function mountApp({ pages, target, guard: g, i18n, nav } = {}) {
   rootEl = target || (isBrowser ? document.getElementById("app") : null);
+  navMode = nav === "mpa" ? "mpa" : "spa";
+  if (i18n) configureI18n(i18n);
   if (pages) registerRoutes(pages);
   guard = g || null;
-  if (isBrowser) {
+  // In MPA mode the browser owns navigation (full loads push real history entries),
+  // so there is no client-side history to react to — only wire popstate for SPA.
+  if (isBrowser && navMode === "spa") {
     window.addEventListener("popstate", () =>
       navigate(
         window.location.pathname + window.location.search + window.location.hash,
@@ -238,7 +370,21 @@ export function mountApp({ pages, target, guard: g } = {}) {
       ),
     );
   }
-  navigate(window.location.pathname + window.location.search + window.location.hash, true, true);
+  // Hydrate the first paint when the server stamped `data-otfw-hydrate` on the root and
+  // left rendered markup in it; otherwise this is a plain CSR mount (build into #app).
+  const hydrate = !!(
+    isBrowser &&
+    rootEl &&
+    rootEl.firstChild &&
+    typeof rootEl.hasAttribute === "function" &&
+    rootEl.hasAttribute("data-otfw-hydrate")
+  );
+  return navigate(
+    window.location.pathname + window.location.search + window.location.hash,
+    true,
+    true,
+    hydrate,
+  );
 }
 
 // `<Link>` is a pure JSX component (packages/web/components/Link.jsx), compiled by

package/server/builtins.js

@@ -6,6 +6,11 @@ import { defineSSG } from "./ssg-runtime.js";
 
 // (web-link is provided by the compiled components/Link.jsx, not hand-written.)
 // Passthrough: their effect is structural/client-side; SSG renders children inline.
-defineSSG("web-context-provider", (_props, children) => children);
-defineSSG("web-portal", (_props, children) => children);
-defineSSG("web-error-boundary", (_props, children) => children);
+defineSSG("web-internal-context-provider", (_props, children) => children);
+defineSSG("web-internal-portal", (_props, children) => children);
+defineSSG("web-internal-error-boundary", (_props, children) => children);
+// RawHtml: emit the trusted HTML string inline (MDX highlighted code blocks).
+defineSSG("web-internal-raw-html", (props) => (props && props.html != null ? String(props.html) : ""));
+// CodeFence: same inline HTML as RawHtml; the copy button wires up on the client
+// when the element upgrades (SSG output is static, the behavior is CSR-only).
+defineSSG("web-internal-code-block", (props) => (props && props.html != null ? String(props.html) : ""));

package/server/head.js

@@ -0,0 +1,191 @@
+//! SEO head resolution + rendering for SSG (ARCHITECTURE.md §6, SPEC §9).
+//! Runs in plain Bun/Node at build time and returns the inner HTML of `<head>`.
+//!
+//! Pages/layouts declare metadata with a Next-style plain-data API:
+//!   export const metadata = { title, description, canonical, openGraph, twitter,
+//!                             robots, jsonLd, meta: [...], links: [...] };
+//!   export function generateMetadata({ params, query }) { return { ... }; }
+//! Both are read off the eager-imported module namespace (the SSG route entries
+//! ARE the namespaces — see runtime/router.js), so no compiler change is needed.
+
+import { layoutChain } from "../runtime/router.js";
+import { escapeAttr, escapeHtml } from "./ssg-runtime.js";
+
+// Sub-objects that merge one level deep (rather than wholesale replace) so a page
+// can override `openGraph.image` without dropping a layout's `openGraph.siteName`.
+const SUBOBJECTS = ["openGraph", "twitter", "robots"];
+
+/** Read a route entry's static `metadata` (namespace or its default export). */
+function staticMeta(entry) {
+  if (!entry || typeof entry === "function") return null;
+  return entry.metadata || (entry.default && entry.default.metadata) || null;
+}
+
+/** Invoke a route entry's `generateMetadata({ params, query })` if it exports one. */
+async function dynamicMeta(entry, params, query) {
+  if (!entry || typeof entry === "function") return null;
+  const gen = entry.generateMetadata || (entry.default && entry.default.generateMetadata);
+  return typeof gen === "function" ? (await gen({ params, query })) || null : null;
+}
+
+/** Merge `add` over `base`, deep-merging the known sub-objects. */
+function mergeMeta(base, add) {
+  if (!add) return base;
+  const out = { ...base };
+  for (const k in add) {
+    const v = add[k];
+    if (v == null) continue;
+    if (SUBOBJECTS.includes(k) && isPlainObject(v) && isPlainObject(base[k])) {
+      out[k] = { ...base[k], ...v };
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Resolve the effective metadata for a route by merging, least- to most-specific:
+ * each layout's static then dynamic metadata (root → leaf), then the page's static
+ * then dynamic metadata. The most specific (page `generateMetadata`) wins.
+ */
+export async function resolveMetadata({ route, entry, params = {}, query = {} } = {}) {
+  let meta = {};
+  for (const layout of layoutChain(route)) {
+    meta = mergeMeta(meta, staticMeta(layout));
+    meta = mergeMeta(meta, await dynamicMeta(layout, params, query));
+  }
+  meta = mergeMeta(meta, staticMeta(entry));
+  meta = mergeMeta(meta, await dynamicMeta(entry, params, query));
+  return meta;
+}
+
+/** Resolve a possibly-relative URL against `baseUrl` (absolute URLs pass through). */
+function absUrl(baseUrl, p) {
+  if (!p) return "";
+  if (/^https?:\/\//i.test(p)) return p;
+  if (!baseUrl) return p; // no site origin configured → emit relative
+  return baseUrl.replace(/\/+$/, "") + (p.startsWith("/") ? p : `/${p}`);
+}
+
+/**
+ * Resolve a `title` (string or `{ absolute }`) against an optional `template`
+ * containing `%s`. A plain string is wrapped by the template; `{ absolute }` (or a
+ * template without `%s`) is used verbatim. Returns null when there is no title.
+ */
+function resolveTitle(title, template) {
+  if (title != null && typeof title === "object") {
+    return title.absolute != null ? String(title.absolute) : null;
+  }
+  if (title == null) return null;
+  const s = String(title);
+  return template && template.includes("%s") ? template.replace("%s", s) : s;
+}
+
+/** `<meta name|property="key" content="value">` (omitted when value is null). */
+function metaTag(kind, key, content) {
+  if (content == null || content === "") return "";
+  return `<meta ${kind}="${escapeAttr(key)}" content="${escapeAttr(content)}">`;
+}
+
+/** Normalize `robots` (string passthrough, or `{ index, follow, ... }` flags). */
+function robotsContent(r) {
+  if (r == null) return "";
+  if (typeof r === "string") return r;
+  const parts = [];
+  if (r.index === false) parts.push("noindex");
+  else if (r.index === true) parts.push("index");
+  if (r.follow === false) parts.push("nofollow");
+  else if (r.follow === true) parts.push("follow");
+  for (const flag of ["noarchive", "nosnippet", "noimageindex", "notranslate"]) {
+    if (r[flag]) parts.push(flag);
+  }
+  return parts.join(", ");
+}
+
+// Escape `</script>` / `<` so a JSON-LD payload can't break out of the script tag.
+function jsonLdSafe(s) {
+  return String(s).replace(/</g, "\\u003c");
+}
+
+/**
+ * Render the resolved `meta` to the inner HTML of `<head>` for the route at `path`.
+ * `baseUrl` (site origin) makes canonical / og:url / image URLs absolute when set.
+ */
+export function renderHead(meta = {}, { path = "/", baseUrl = "" } = {}) {
+  const tags = [];
+  const push = (s) => s && tags.push(s);
+
+  // Resolve the display title. `title` is a string (wrapped by an inherited
+  // `titleTemplate` like "%s — OTF Web") or `{ absolute }` to bypass the template —
+  // so a layout can brand every child page while the homepage keeps a bespoke title.
+  const title = resolveTitle(meta.title, meta.titleTemplate);
+  const description = meta.description;
+  if (title != null) push(`<title>${escapeHtml(title)}</title>`);
+  push(metaTag("name", "description", description));
+
+  const canonical = absUrl(baseUrl, meta.canonical ?? path);
+  if (canonical) push(`<link rel="canonical" href="${escapeAttr(canonical)}">`);
+
+  push(metaTag("name", "robots", robotsContent(meta.robots)));
+
+  // Open Graph (falls back to the top-level title/description).
+  const og = isPlainObject(meta.openGraph) ? meta.openGraph : {};
+  const ogImage = og.image ? absUrl(baseUrl, og.image) : "";
+  push(metaTag("property", "og:title", og.title ?? title));
+  push(metaTag("property", "og:description", og.description ?? description));
+  push(metaTag("property", "og:type", og.type ?? "website"));
+  push(metaTag("property", "og:url", og.url ? absUrl(baseUrl, og.url) : canonical));
+  push(metaTag("property", "og:image", ogImage));
+  push(metaTag("property", "og:site_name", og.siteName));
+
+  // Twitter Card (falls back to Open Graph / top-level values).
+  const tw = isPlainObject(meta.twitter) ? meta.twitter : {};
+  const twImage = tw.image ? absUrl(baseUrl, tw.image) : ogImage;
+  push(metaTag("name", "twitter:card", tw.card ?? (twImage ? "summary_large_image" : "summary")));
+  push(metaTag("name", "twitter:title", tw.title ?? og.title ?? title));
+  push(metaTag("name", "twitter:description", tw.description ?? og.description ?? description));
+  push(metaTag("name", "twitter:image", twImage));
+
+  // Arbitrary extra tags (escape hatch for anything not modeled above).
+  for (const m of Array.isArray(meta.meta) ? meta.meta : []) {
+    const kind = m.name ? "name" : m.property ? "property" : m.httpEquiv ? "http-equiv" : null;
+    if (kind) push(metaTag(kind, m.name ?? m.property ?? m.httpEquiv, m.content));
+  }
+  for (const l of Array.isArray(meta.links) ? meta.links : []) {
+    const rel = l.rel ? ` rel="${escapeAttr(l.rel)}"` : "";
+    const href = l.href ? ` href="${escapeAttr(absUrl(baseUrl, l.href))}"` : "";
+    const extra = l.hreflang ? ` hreflang="${escapeAttr(l.hreflang)}"` : "";
+    if (rel || href) push(`<link${rel}${href}${extra}>`);
+  }
+
+  // Structured data (JSON-LD) for rich results.
+  if (meta.jsonLd != null) {
+    const json = typeof meta.jsonLd === "string" ? meta.jsonLd : JSON.stringify(meta.jsonLd);
+    push(`<script type="application/ld+json">${jsonLdSafe(json)}</script>`);
+  }
+
+  return tags.join("\n");
+}
+
+/**
+ * Build `rel="alternate" hreflang` link descriptors for a locale-agnostic
+ * `routePath` (e.g. `/about`) across all configured locales — for the toolchain to
+ * pass through `metadata.links` so `renderHead` emits them (docs/I18N.md §6). The
+ * default locale also gets `x-default`. `localize(path, locale)` is the router's
+ * `localizePath` (kept as a param so this stays free of a router import here).
+ */
+export function localeAlternateLinks(routePath, { locales, defaultLocale } = {}, localize) {
+  if (!Array.isArray(locales) || locales.length === 0 || typeof localize !== "function") return [];
+  const links = locales.map((locale) => ({
+    rel: "alternate",
+    hreflang: locale,
+    href: localize(routePath, locale),
+  }));
+  links.push({ rel: "alternate", hreflang: "x-default", href: localize(routePath, defaultLocale) });
+  return links;
+}

package/server/index.js

@@ -3,5 +3,6 @@
 // import). Imported as "@opentf/web/server".
 
 export * from "./ssg-runtime.js";
+export * from "./head.js";
 export * from "./render.js";
 import "./builtins.js";