@mesofact/runtime 0.8.29

package/src/adapters/sqlite.ts

@@ -0,0 +1,182 @@
+// `sqlite` adapter — read-only KeyValueSource over a local SQLite file (or a
+// Litestream / LiteFS replica). Emits `sqlite:<source>:<table>:<id>` (row) and
+// `sqlite:<source>:<table>` (table-wide) tags into the ambient trackCtx, honors
+// per-call `.noTrack()` / `.timeout(ms)`, 100 ms default timeout.
+//
+// See `.yah/docs/architecture/mesofact.md` §"Adapter API surface", §"Adapter
+// read-set provenance" (tag taxonomy), and §"Cache-key composition" (the
+// proxy folds the file mtime into the cache key — generation is computed
+// proxy-side from the source path, not here).
+
+import { BaseSource, type KeyValueSource } from "../source.js";
+import { SourceQueryError, SourceTimeoutError, SourceUnavailableError } from "../errors.js";
+
+const DEFAULT_TIMEOUT_MS = 100;
+
+// Minimal slice of `bun:sqlite` we depend on. Declared locally so the published
+// contract package keeps `types: ["node"]` (no Bun globals leak into the types
+// an outside TS consumer sees). The real `Database` is reached via a runtime
+// dynamic import below; this is only its read surface.
+export interface SqliteRunner {
+  // Run `sql` with positional `params` and return every row as a plain object.
+  all(sql: string, params: unknown[]): unknown[];
+  close?(): void;
+}
+
+export type SqliteConfig = {
+  // Logical source name from `mesofact.config.toml` (e.g. "project_db"). Used as
+  // the registry key, the `sqlite:<name>:...` tag prefix, and surfaced in errors.
+  name: string;
+  // Filesystem path to the SQLite database. Opened read-only and lazily on the
+  // first read so registration never touches disk.
+  path: string;
+  // Test seam — inject a runner to observe queries without a real DB file.
+  // Defaults to opening `path` via `bun:sqlite`.
+  runner?: SqliteRunner;
+};
+
+export class SqliteAdapter extends BaseSource implements KeyValueSource {
+  readonly path: string;
+  private runner: SqliteRunner | null;
+  private opening: Promise<SqliteRunner> | null = null;
+
+  constructor(config: SqliteConfig) {
+    super(config.name);
+    this.path = config.path;
+    this.runner = config.runner ?? null;
+  }
+
+  async get<T>(table: string, id: string): Promise<T | null> {
+    const { track, timeout_ms } = this.consumeOverrides(DEFAULT_TIMEOUT_MS);
+    this.emitTag(`sqlite:${this.name}:${table}:${id}`, track);
+    const rows = await this.run(
+      `SELECT * FROM ${quoteIdent(table)} WHERE id = ? LIMIT 1`,
+      [id],
+      timeout_ms,
+    );
+    return (rows[0] as T | undefined) ?? null;
+  }
+
+  async query<T>(sql: string, params: unknown[] = []): Promise<T[]> {
+    const { track, timeout_ms } = this.consumeOverrides(DEFAULT_TIMEOUT_MS);
+    // Tag every table the query reads. When no table can be extracted (CTEs,
+    // exotic SQL), fall back to a source-wide tag so invalidation stays
+    // conservative — over-purging is recoverable; a missed tag is stale-forever.
+    const tables = extractTables(sql);
+    if (tables.length === 0) {
+      this.emitTag(`sqlite:${this.name}`, track);
+    } else {
+      for (const table of tables) this.emitTag(`sqlite:${this.name}:${table}`, track);
+    }
+    return (await this.run(sql, params, timeout_ms)) as T[];
+  }
+
+  private async run(sql: string, params: unknown[], timeout_ms: number): Promise<unknown[]> {
+    const exec = (async () => {
+      const runner = await this.ensureRunner();
+      try {
+        return runner.all(sql, params);
+      } catch (err) {
+        throw new SourceQueryError(this.name, sqliteMessage(sql, err), { cause: err });
+      }
+    })();
+    return this.race(exec, timeout_ms);
+  }
+
+  private async ensureRunner(): Promise<SqliteRunner> {
+    if (this.runner) return this.runner;
+    if (!this.opening) {
+      this.opening = openBunSqlite(this.path)
+        .then((r) => (this.runner = r))
+        .catch((err) => {
+          this.opening = null;
+          throw new SourceUnavailableError(this.name, { cause: err });
+        });
+    }
+    return this.opening;
+  }
+
+  private async race<T>(call: Promise<T>, timeout_ms: number): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race<T>([
+        call,
+        new Promise<T>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new SourceTimeoutError(this.name, timeout_ms)),
+            timeout_ms,
+          );
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+}
+
+function sqliteMessage(sql: string, err: unknown): string {
+  const head = sql.length > 80 ? `${sql.slice(0, 77)}...` : sql;
+  return `sqlite query failed (${head}): ${err instanceof Error ? err.message : String(err)}`;
+}
+
+// Quote a table identifier so a table named like a keyword (or containing a
+// dot) can't break the generated SQL. Table names come from server-side render
+// code, not request input, so this is defensive rather than an injection guard;
+// `id` and `query` params are always bound, never interpolated.
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+// Pull table names out of a SELECT for table-wide tag emission. A regex over
+// `FROM`/`JOIN` clauses — same pragmatic posture as the build's regex source
+// inference and the r2 list-XML parser. Misses are absorbed by the source-wide
+// fallback in `query`.
+function extractTables(sql: string): string[] {
+  const out = new Set<string>();
+  for (const m of sql.matchAll(/\b(?:from|join)\s+["'`]?([A-Za-z_][\w$]*)/gi)) {
+    out.add(m[1]!);
+  }
+  return [...out];
+}
+
+// Reach `bun:sqlite` at runtime without making it a static import — the
+// published runtime types stay Bun-free, and a non-Bun consumer that never
+// calls a sqlite source never resolves the module. The `as string` defeats
+// tsc's static module resolution (dynamic specifier → Promise<any>); the cast
+// to the constructor shape restores type-safety on the result.
+type BunStatement = { all(...params: unknown[]): unknown[] };
+type BunDatabase = { query(sql: string): BunStatement; close(): void };
+
+async function openBunSqlite(path: string): Promise<SqliteRunner> {
+  const mod = (await import("bun:sqlite" as string)) as {
+    Database: new (filename: string, options?: { readonly?: boolean }) => BunDatabase;
+  };
+  const db = new mod.Database(path, { readonly: true });
+  return {
+    all: (sql, params) => db.query(sql).all(...params),
+    close: () => db.close(),
+  };
+}
+
+// Per-process registry, mirroring the r2 adapter. `registerSourcesFromConfig`
+// populates it from `[sources.*]` of `kind = "sqlite"`; render code looks up by
+// name via `sqlite(name)`.
+const registry = new Map<string, SqliteAdapter>();
+
+export function registerSqlite(adapter: SqliteAdapter): void {
+  registry.set(adapter.name, adapter);
+}
+
+export function clearSqliteRegistry(): void {
+  registry.clear();
+}
+
+export function sqlite(name: string): KeyValueSource {
+  const adapter = registry.get(name);
+  if (!adapter) {
+    throw new Error(
+      `sqlite source not registered: ${name} (declare it in mesofact.config.toml under [sources.${name}])`,
+    );
+  }
+  return adapter;
+}

package/src/config.ts

@@ -0,0 +1,213 @@
+// `mesofact.config.toml` parser. Yubaba writes this file atomically and
+// SIGHUPs the proxy + Bun pool on change; mesofact reads it on boot to
+// instantiate adapters. Credentials come in via env vars (yubaba injects);
+// the config carries only the env var *names*, never the secrets themselves.
+//
+// See `.yah/docs/architecture/mesofact.md` §"Yubaba owns config and credentials".
+
+import { readFileSync } from "node:fs";
+import { parse as parseToml } from "smol-toml";
+import { R2Adapter, registerR2 } from "./adapters/r2.js";
+import { SqliteAdapter, registerSqlite } from "./adapters/sqlite.js";
+import type { SourceScope } from "./validate.js";
+
+export type R2SourceConfig = {
+  kind: "r2";
+  scope: SourceScope;
+  bucket: string;
+  // Env var name resolved at register-time. R2's endpoint is account-scoped
+  // (`https://<account_id>.r2.cloudflarestorage.com`), so yubaba injects it
+  // rather than us guessing.
+  endpoint_env: string;
+  // Env var names for credentials. Defaults are the AWS-standard names so a
+  // simple deployment can omit them.
+  access_key_id_env?: string;
+  secret_access_key_env?: string;
+};
+
+export type SqliteSourceConfig = {
+  kind: "sqlite";
+  scope: SourceScope;
+  // Filesystem path to the database file. For `scope = "global"` it's a literal
+  // path; the design templates `{project_id}` for scoped sources, deferred until
+  // the first scoped SSR dogfood (no credentials — sqlite is a local file).
+  path: string;
+};
+
+// Future kinds (pg, rpc) extend this union as their adapters land.
+export type SourceConfig = R2SourceConfig | SqliteSourceConfig;
+
+// Build-time knobs (R490-F4). `public_dir` names the workload-relative dir
+// whose files are copied verbatim into `dist/html/` and listed in the
+// manifest's `static_assets`. Default "public"; a missing dir is fine (no
+// assets emitted).
+export type BuildConfig = {
+  public_dir?: string;
+};
+
+export type MesofactConfig = {
+  sources: Record<string, SourceConfig>;
+  build?: BuildConfig;
+};
+
+export function loadConfig(path: string): MesofactConfig {
+  return parseConfig(readFileSync(path, "utf8"));
+}
+
+export function parseConfig(toml: string): MesofactConfig {
+  const raw = parseToml(toml) as unknown;
+  if (!isPlainObject(raw)) {
+    throw new ConfigError("config must be a TOML object at top level");
+  }
+  const build = parseBuild(raw.build);
+  const sourcesRaw = raw.sources;
+  if (sourcesRaw === undefined) return { sources: {}, ...(build ? { build } : {}) };
+  if (!isPlainObject(sourcesRaw)) {
+    throw new ConfigError("[sources] must be a table");
+  }
+  const sources: Record<string, SourceConfig> = {};
+  for (const [name, body] of Object.entries(sourcesRaw)) {
+    sources[name] = parseSource(name, body);
+  }
+  return { sources, ...(build ? { build } : {}) };
+}
+
+function parseBuild(raw: unknown): BuildConfig | undefined {
+  if (raw === undefined) return undefined;
+  if (!isPlainObject(raw)) {
+    throw new ConfigError("[build] must be a table");
+  }
+  const out: BuildConfig = {};
+  if (raw.public_dir !== undefined) {
+    if (typeof raw.public_dir !== "string" || raw.public_dir.length === 0) {
+      throw new ConfigError("[build] public_dir must be a non-empty string");
+    }
+    out.public_dir = raw.public_dir;
+  }
+  return out;
+}
+
+function parseSource(name: string, body: unknown): SourceConfig {
+  if (!isPlainObject(body)) {
+    throw new ConfigError(`[sources.${name}] must be a table`);
+  }
+  const kind = body.kind;
+  const scope = parseScope(name, body.scope);
+  if (kind === "r2") return parseR2(name, body, scope);
+  if (kind === "sqlite") return parseSqlite(name, body, scope);
+  // P4 shipped r2; P9 adds sqlite. pg/rpc widen this union later.
+  throw new ConfigError(
+    `[sources.${name}] unsupported kind: ${JSON.stringify(kind)} (supported: "r2", "sqlite")`,
+  );
+}
+
+function parseScope(name: string, raw: unknown): SourceScope {
+  const scope = raw ?? "global";
+  if (scope !== "global" && scope !== "project" && scope !== "user") {
+    throw new ConfigError(
+      `[sources.${name}] invalid scope: ${JSON.stringify(scope)} (expected "global" | "project" | "user")`,
+    );
+  }
+  return scope;
+}
+
+function parseR2(name: string, body: Record<string, unknown>, scope: SourceScope): R2SourceConfig {
+  const bucket = body.bucket;
+  if (typeof bucket !== "string" || bucket === "") {
+    throw new ConfigError(`[sources.${name}] missing or empty \`bucket\` (string)`);
+  }
+  const endpoint_env = body.endpoint_env;
+  if (typeof endpoint_env !== "string" || endpoint_env === "") {
+    throw new ConfigError(`[sources.${name}] missing or empty \`endpoint_env\` (string)`);
+  }
+  const access_key_id_env = optionalString(body.access_key_id_env, name, "access_key_id_env");
+  const secret_access_key_env = optionalString(body.secret_access_key_env, name, "secret_access_key_env");
+  return {
+    kind: "r2",
+    scope,
+    bucket,
+    endpoint_env,
+    ...(access_key_id_env !== undefined ? { access_key_id_env } : {}),
+    ...(secret_access_key_env !== undefined ? { secret_access_key_env } : {}),
+  };
+}
+
+function parseSqlite(
+  name: string,
+  body: Record<string, unknown>,
+  scope: SourceScope,
+): SqliteSourceConfig {
+  const path = body.path;
+  if (typeof path !== "string" || path === "") {
+    throw new ConfigError(`[sources.${name}] missing or empty \`path\` (string)`);
+  }
+  return { kind: "sqlite", scope, path };
+}
+
+function optionalString(value: unknown, source: string, field: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value === "") {
+    throw new ConfigError(`[sources.${source}] \`${field}\` must be a non-empty string`);
+  }
+  return value;
+}
+
+// Resolve credentials from env and register an R2Adapter for each r2 source.
+// Returns the resolved adapter names so callers can verify a known set landed.
+export function registerSourcesFromConfig(
+  config: MesofactConfig,
+  env: Record<string, string | undefined> = process.env,
+): string[] {
+  const registered: string[] = [];
+  for (const [name, src] of Object.entries(config.sources)) {
+    if (src.kind === "r2") {
+      const endpoint = requireEnv(env, src.endpoint_env, name, "endpoint_env");
+      const accessKeyId = requireEnv(
+        env,
+        src.access_key_id_env ?? "AWS_ACCESS_KEY_ID",
+        name,
+        "access_key_id_env",
+      );
+      const secretAccessKey = requireEnv(
+        env,
+        src.secret_access_key_env ?? "AWS_SECRET_ACCESS_KEY",
+        name,
+        "secret_access_key_env",
+      );
+      registerR2(new R2Adapter({ name, bucket: src.bucket, endpoint, accessKeyId, secretAccessKey }));
+      registered.push(name);
+    } else if (src.kind === "sqlite") {
+      // No credentials — sqlite is a local file. The DB opens lazily on first
+      // read, so registration never touches disk.
+      registerSqlite(new SqliteAdapter({ name, path: src.path }));
+      registered.push(name);
+    }
+  }
+  return registered;
+}
+
+function requireEnv(
+  env: Record<string, string | undefined>,
+  varName: string,
+  source: string,
+  field: string,
+): string {
+  const v = env[varName];
+  if (v === undefined || v === "") {
+    throw new ConfigError(
+      `[sources.${source}] env var \`${varName}\` (from ${field}) is unset or empty`,
+    );
+  }
+  return v;
+}
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}

package/src/contract.ts

@@ -0,0 +1,82 @@
+// Render contract — the single seam between mesofact and any frontend.
+// See `.yah/docs/architecture/mesofact.md` §"The shared seam: one render
+// contract" and §"Request context — what Rust pre-resolves".
+
+import type { Head } from "./head.js";
+
+export type Region = string;
+
+export type User = {
+  id: string;
+  attrs: Record<string, unknown>;
+};
+
+export type Project = {
+  id: string;
+  home_region: Region;
+  generation: string;
+};
+
+export type RenderRequest = {
+  url: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+
+  // Proxy-resolved before render is invoked. Routes declare which of these
+  // they require in the manifest; the proxy returns 401/404/redirect when a
+  // required field can't resolve (render is never called).
+  user?: User;
+  project?: Project;
+  region?: Region;
+
+  // Per-deployment escape hatch for route-specific Rust middleware
+  // (feature flags, A/B bucket). Not type-checked across the proxy↔render
+  // boundary.
+  ctx?: Record<string, unknown>;
+
+  // Build-time data artifacts declared in the route's `data_inputs`.
+  // Keys are the artifact paths (relative to project root); values are parsed
+  // JSON. Populated only for mode="static" during prerender; absent at runtime.
+  data?: Record<string, unknown>;
+};
+
+export type CachePolicy = {
+  ttl: number;
+  tags?: readonly string[];
+};
+
+// Mode 3 only. The render only ships `initial_state` — the build owns the
+// resolved (content-hashed) entry `script` + `code_split` chunks and writes
+// them into the manifest's `hydration`. A render MAY set `script` as a logical
+// hint, but the manifest's build-derived value is what the shell references.
+//
+// The build serializes `initial_state` into a
+// `<script id="__MESOFACT_STATE__" type="application/json">` tag in the shell
+// HTML. The six-line client snippet that consumes it:
+//
+//   import { hydrateRoot } from "react-dom/client";          // or any framework
+//   const el = document.getElementById("__MESOFACT_STATE__");
+//   const initialState = el ? JSON.parse(el.textContent ?? "null") : null;
+//   hydrateRoot(document.getElementById("root")!, <App initial={initialState} />);
+//
+// mesofact ships no runtime helper — the snippet lives in the client entry the
+// route declares via `client_entrypoint` and the build bundles to `hydrate/`.
+export type Hydration = {
+  script?: string;
+  initial_state?: unknown;
+};
+
+export type RenderResult = {
+  html: string;
+  headers?: Record<string, string>;
+  cache: CachePolicy;
+  hydration?: Hydration;
+  // Typed <head> contract (W270 §4). Woven into the document head by the
+  // prerenderer / SSG dispatch; the framework owns all escaping. Optional —
+  // a render that manages its own <head> can omit it.
+  head?: Head;
+};
+
+export type RenderFn = (req: RenderRequest) => Promise<RenderResult>;

package/src/errors.ts

@@ -0,0 +1,52 @@
+// Typed errors adapters throw. Render functions can catch and return
+// fallback HTML, or rethrow to let mesofact decide (stale-on-error / 503).
+// See `.yah/docs/architecture/mesofact.md` §"Adapter API surface".
+
+export class SourceError extends Error {
+  readonly source: string;
+  readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    source: string,
+    retryable: boolean,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options as ErrorOptions | undefined);
+    this.name = new.target.name;
+    this.source = source;
+    this.retryable = retryable;
+  }
+}
+
+export class SourceUnavailableError extends SourceError {
+  constructor(source: string, options?: { cause?: unknown }) {
+    super(`source unavailable: ${source}`, source, true, options);
+  }
+}
+
+export class SourceTimeoutError extends SourceError {
+  readonly timeout_ms: number;
+
+  constructor(source: string, timeout_ms: number, options?: { cause?: unknown }) {
+    super(`source timeout after ${timeout_ms}ms: ${source}`, source, true, options);
+    this.timeout_ms = timeout_ms;
+  }
+}
+
+export class SourceQueryError extends SourceError {
+  constructor(source: string, message: string, options?: { cause?: unknown }) {
+    super(`source query error (${source}): ${message}`, source, false, options);
+  }
+}
+
+export class RowNotFoundError extends SourceError {
+  readonly table: string;
+  readonly id: string;
+
+  constructor(source: string, table: string, id: string) {
+    super(`row not found: ${source}.${table}[${id}]`, source, false);
+    this.table = table;
+    this.id = id;
+  }
+}

package/src/head.ts

@@ -0,0 +1,130 @@
+// Typed <head> contract (W270 §4). A render MAY return a `head` value on its
+// RenderResult; the prerenderer / SSG dispatch weaves it into the document
+// head at the same seam as the hydration tags. Consumers return structured
+// data — they never hand-assemble head markup or escape it themselves.
+//
+// Escaping lives HERE, one audited implementation, same posture as
+// `escapeJsonForScriptTag` (hydration.ts): all interpolated values are HTML-
+// escaped, attribute values additionally escape the quote that closes the
+// attribute. Meta keys (`og:title`, `twitter:card`, …) are framework-owned
+// literals and are never interpolated from consumer data.
+//
+// Also ported byte-for-byte into the deno_core SSG runtime shim at
+// `crates/mesofact-ssr/js/runtime_shim.js` — keep the two in lockstep so both
+// pipelines emit the same head bytes (same rule as the hydration helpers).
+
+export type OpenGraph = {
+  title?: string;
+  description?: string;
+  // og:type — e.g. "website" | "article". Framework passes it through as-is
+  // (value is escaped like any other content).
+  type?: string;
+  url?: string;
+  image?: string;
+  siteName?: string;
+};
+
+export type TwitterCard = {
+  // twitter:card — e.g. "summary" | "summary_large_image".
+  card?: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  site?: string;
+  creator?: string;
+};
+
+// A generic <link>. `rel` + `href` are the only universally-required
+// attributes; both are attribute-escaped. Richer link attrs (sizes, type)
+// can be folded in later without breaking this shape.
+export type HeadLink = {
+  rel: string;
+  href: string;
+};
+
+export type Head = {
+  title?: string;
+  description?: string;
+  // Emitted as <link rel="canonical" href="…">.
+  canonical?: string;
+  og?: OpenGraph;
+  twitter?: TwitterCard;
+  // When true, emits <meta name="robots" content="noindex">. Instance-
+  // addressed (deferred) pages set this; enumerable static routes that set it
+  // are also dropped from the manifest-derived sitemap.
+  noindex?: boolean;
+  links?: readonly HeadLink[];
+};
+
+// Escape a value destined for HTML text content (`<title>…`): the three
+// characters that can open a tag / entity. `&` first so we never double-encode
+// the escapes we introduce.
+function escapeHtmlText(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// Escape a value destined for a double-quoted attribute: text escaping plus
+// the closing quote.
+function escapeHtmlAttr(value: string): string {
+  return escapeHtmlText(value).replace(/"/g, "&quot;");
+}
+
+// key is a framework-owned literal (og:title, twitter:card, …); only content
+// is consumer-supplied, so only content is escaped.
+function metaTag(attr: "name" | "property", key: string, content: string): string {
+  return `<meta ${attr}="${key}" content="${escapeHtmlAttr(content)}">`;
+}
+
+// Render a Head into the concatenated head-tag markup (no wrapping <head>).
+// Order is stable and deterministic so prerendered bytes are reproducible.
+export function renderHead(head: Head): string {
+  const tags: string[] = [];
+
+  if (head.title !== undefined) tags.push(`<title>${escapeHtmlText(head.title)}</title>`);
+  if (head.description !== undefined) tags.push(metaTag("name", "description", head.description));
+  if (head.canonical !== undefined) {
+    tags.push(`<link rel="canonical" href="${escapeHtmlAttr(head.canonical)}">`);
+  }
+  if (head.noindex) tags.push(`<meta name="robots" content="noindex">`);
+
+  const og = head.og;
+  if (og) {
+    if (og.title !== undefined) tags.push(metaTag("property", "og:title", og.title));
+    if (og.description !== undefined) {
+      tags.push(metaTag("property", "og:description", og.description));
+    }
+    if (og.type !== undefined) tags.push(metaTag("property", "og:type", og.type));
+    if (og.url !== undefined) tags.push(metaTag("property", "og:url", og.url));
+    if (og.image !== undefined) tags.push(metaTag("property", "og:image", og.image));
+    if (og.siteName !== undefined) tags.push(metaTag("property", "og:site_name", og.siteName));
+  }
+
+  const tw = head.twitter;
+  if (tw) {
+    if (tw.card !== undefined) tags.push(metaTag("name", "twitter:card", tw.card));
+    if (tw.title !== undefined) tags.push(metaTag("name", "twitter:title", tw.title));
+    if (tw.description !== undefined) {
+      tags.push(metaTag("name", "twitter:description", tw.description));
+    }
+    if (tw.image !== undefined) tags.push(metaTag("name", "twitter:image", tw.image));
+    if (tw.site !== undefined) tags.push(metaTag("name", "twitter:site", tw.site));
+    if (tw.creator !== undefined) tags.push(metaTag("name", "twitter:creator", tw.creator));
+  }
+
+  for (const link of head.links ?? []) {
+    tags.push(`<link rel="${escapeHtmlAttr(link.rel)}" href="${escapeHtmlAttr(link.href)}">`);
+  }
+
+  return tags.join("");
+}
+
+// Weave a Head into a rendered document: inject the head markup immediately
+// before the last </head> (case-insensitive). A document without one gets the
+// markup prepended. A head that renders to nothing leaves the html untouched.
+export function weaveHead(html: string, head: Head): string {
+  const markup = renderHead(head);
+  if (markup === "") return html;
+  const idx = html.toLowerCase().lastIndexOf("</head>");
+  if (idx === -1) return markup + html;
+  return html.slice(0, idx) + markup + html.slice(idx);
+}