@opentf/web 0.5.0 → 0.7.0

package/runtime/router.js

@@ -15,19 +15,107 @@
 
 import { clearError, reportError } from "../core/errors.js";
 import { signal } from "../core/signals.js";
+import { beginHydration, cursor, endHydration } from "./hydrate.js";
 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 +132,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 +143,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;
 }
 
@@ -110,19 +201,74 @@ export async function buildRouteNode(match, query = {}) {
   return { node, nodes };
 }
 
+/**
+ * Adopt a matched route's server-rendered DOM (docs/HYDRATION.md §3.4, 2.1c) — the hydrate
+ * analogue of {@link buildRouteNode}. One cursor threads the whole layout chain: the
+ * outermost layout adopts at the container, and each layout hands that cursor to the next at
+ * its `{children}` slot (`props.children` is a thunk that claims the nested route's subtree
+ * and advances the cursor), down to the page. Returns `{ nodes }` (page → … → root) for
+ * lifecycle, or `null` if the page or any layout isn't adoptable (no `hydrateAt` export) — the
+ * caller then falls back to a clean CSR build. A thrown `HydrationMismatch` propagates up,
+ * disposing each layer's partial wiring on the way (each `hydrateAt` has its own guard).
+ */
+export async function hydrateRouteNode(match, query, rootEl) {
+  const props = { params: match.params, query };
+  const pageMod = await resolveModule(match.entry);
+  if (!pageMod || typeof pageMod.hydrateAt !== "function") return null;
+  const chain = layoutChain(match.route);
+  const layoutMods = [];
+  for (const entry of chain) {
+    const m = await resolveModule(entry);
+    if (!m || typeof m.hydrateAt !== "function") return null; // whole chain must be adoptable
+    layoutMods.push(m);
+  }
+
+  // Compose the adopt thunks innermost-first: the page, then each layout wrapping it. Each
+  // thunk pushes its claimed root node, so `nodes` ends up page → … → outermost (the inner
+  // thunk runs — and pushes — during the outer layout's walk, before the outer pushes).
+  const nodes = [];
+  let thunk = (c) => {
+    const n = pageMod.hydrateAt(c, props);
+    nodes.push(n);
+    return n;
+  };
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const layout = layoutMods[i];
+    const inner = thunk;
+    thunk = (c) => {
+      const n = layout.hydrateAt(c, { ...props, children: inner });
+      nodes.push(n);
+      return n;
+    };
+  }
+  thunk(cursor(rootEl)); // outermost adopts at the container; the chain threads inward
+  return { nodes };
+}
+
+/** Resolve a route entry (lazy loader or module namespace) to its module. */
+async function resolveModule(entry) {
+  return typeof entry === "function" ? await entry() : entry;
+}
+
 /**
  * Set the reactive route state directly (no history/render). Used by server render
  * 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 +289,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 +323,48 @@ 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 `hydrateAt` adopt factory (compiled with the hydrate
+  // target). `hydrateRouteNode` threads one cursor through the whole layout chain (2.1c);
+  // a route whose page or any layout isn't adoptable returns null → clean CSR build. A
+  // hydration mismatch is reported (never silent) and also falls through to a rebuild.
+  //
+  // The hydration flag must be live *before* the route modules are imported: route chunks
+  // are code-split, so `customElements.define` — and the synchronous upgrade of every
+  // server-rendered `<web-*>` host — happens during those imports, before the factories
+  // run. Those upgrading components read `isHydrating()` to adopt their server DOM rather
+  // than build (docs/HYDRATION.md §3.4). `endHydration()` in `finally` makes every
+  // subsequent client navigation build fresh; the CSR fallback below then runs with the
+  // flag cleared, so a rebuilt host builds instead of trying to re-adopt.
+  if (hydrate && match) {
+    beginHydration();
+    try {
+      const query = Object.fromEntries(url.searchParams);
+      const adopted = await hydrateRouteNode(match, query, rootEl);
+      if (adopted) {
+        currentNodes = adopted.nodes;
+        for (const n of adopted.nodes) runMount(n); // onMount for page + every layout
+        clearError({ phase: "route" });
+        return;
+      }
+    } catch (e) {
+      reportError(e, { phase: "hydrate", path: url.pathname });
+      // fall through to a clean CSR build below
+    } finally {
+      endHydration();
+    }
+  }
+
   // 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 +389,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 +410,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 +430,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";

package/server/render.js

@@ -14,22 +14,34 @@ import {
   routes,
   setRouteState,
 } from "../runtime/router.js";
+import { resolveMetadata } from "./head.js";
+import { beginHydrationCollect, endHydrationCollect } from "./ssg-runtime.js";
 
 /**
- * Render `pathname` to an HTML string (the markup for inside `#app`). Falls back
- * to the registered `404` page for an unmatched path; returns `null` if there's
- * no match and no 404.
+ * Render `pathname` to `{ html, metadata, status, hydration }`: the markup for inside
+ * `#app`, the resolved SEO metadata (for the `<head>`), an HTTP `status` (200 when the
+ * path matched a real route, 404 when it fell back to the registered 404 page — the SSR
+ * server uses it; SSG ignores it), and `hydration` — the JSON island-props payload the
+ * toolchain embeds so the client resumes from rich data (`""` when nothing needs it).
+ * `params` (from `getStaticPaths`) override the matched route's params for dynamic
+ * routes. Returns `null` if there's no match and no 404 page.
  */
-export async function renderToString(pathname, search = "") {
+export async function renderRoute(pathname, params = null, search = "") {
+  const real = matchRoute(pathname);
   const match =
-    matchRoute(pathname) ||
-    (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
+    real || (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
   if (!match) return null;
+  if (params) match.params = params;
 
   // Let a page reading `router.params`/`pathname`/`query` resolve to this route.
   setRouteState({ pathname, search, params: match.params });
 
-  const props = { params: match.params, query: Object.fromEntries(new URLSearchParams(search)) };
+  const query = Object.fromEntries(new URLSearchParams(search));
+  const props = { params: match.params, query };
+
+  // Collect each island's rich props while the tree renders (ssgComponent records them
+  // and stamps `data-h` ids), then serialize the payload for the shell.
+  beginHydrationCollect();
   let html = (await resolveFactory(match.entry))(props);
 
   // Wrap with layouts, most-specific inward to root outermost.
@@ -38,7 +50,21 @@ export async function renderToString(pathname, search = "") {
     const layout = await resolveFactory(chain[i]);
     html = layout({ ...props, children: html });
   }
-  return html;
+  const hydration = endHydrationCollect();
+
+  const metadata = await resolveMetadata({
+    route: match.route,
+    entry: match.entry,
+    params: match.params,
+    query,
+  });
+  return { html, metadata, status: real ? 200 : 404, hydration };
+}
+
+/** Back-compat / convenience: render just the `#app` markup for `pathname`. */
+export async function renderToString(pathname, search = "") {
+  const result = await renderRoute(pathname, null, search);
+  return result ? result.html : null;
 }
 
 /** Substitute `[param]` / `[...rest]` in a route with concrete values. */
@@ -49,16 +75,18 @@ function fillRoute(route, params) {
 }
 
 /**
- * Enumerate the concrete paths to pre-render. Static routes are taken as-is;
- * dynamic routes (`[param]`) are expanded via the page module's optional
- * `getStaticPaths()` (returning `[{ params }]`), else collected as `skipped`.
+ * Enumerate the concrete paths to pre-render as `{ path, params }`. Static routes
+ * are taken as-is (`params: {}`); dynamic routes (`[param]`) are expanded via the
+ * page module's optional `getStaticPaths()` (returning `[{ params }]`), carrying the
+ * params forward so the renderer/`generateMetadata` see them. Dynamic routes without
+ * `getStaticPaths` are collected as `skipped`.
  */
 export async function collectRoutePaths() {
   const paths = [];
   const skipped = [];
   for (const route in routes.pages) {
     if (!route.includes("[")) {
-      paths.push(route);
+      paths.push({ path: route, params: {} });
       continue;
     }
     const ns = routes.pages[route];
@@ -66,7 +94,8 @@ export async function collectRoutePaths() {
       ns && (ns.getStaticPaths || (ns.default && ns.default.getStaticPaths));
     if (typeof getStaticPaths === "function") {
       for (const entry of (await getStaticPaths()) || []) {
-        paths.push(fillRoute(route, entry.params || entry));
+        const params = entry.params || entry;
+        paths.push({ path: fillRoute(route, params), params });
       }
     } else {
       skipped.push(route);