@caelo-cms/shared 0.10.28 → 0.10.30

package/dist/static-cache-policy.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Cache-Control policy for the published static site — the single
+ * source of truth every static publisher (GCS object metadata,
+ * Firebase Hosting version headers, self-hosted Caddy) derives from.
+ *
+ * The rule: only a URL whose bytes can never change may be cached
+ * forever. That holds exactly when the URL itself changes whenever the
+ * content does, i.e. the file name carries a content hash. Everything
+ * else (pages, robots.txt, sitemap.xml, manifests, media served by its
+ * stable slug under `_assets/<slug>…`) must stay short-lived or
+ * revalidating so a publish shows up promptly.
+ *
+ * Content-hashed paths the static generator emits today:
+ *
+ *   - `_assets/fonts/<family-slug>/<16 hex>.woff2` — self-hosted
+ *     Google Fonts faces; the name is a hash of the upstream face URL,
+ *     which Google versions per file (a changed face gets a new URL,
+ *     hence a new name).
+ *   - `_assets/fonts/pinned/<sha256>.<ttf|otf|woff|woff2>` — library
+ *     fonts pinned by the sha256 of their bytes. (The sibling
+ *     `pinned/<font-id>.license.txt` is id-named, NOT hashed.)
+ *   - `_caelo/plugin/<slug>/<stem>.<12 hex>.<js|css>` — plugin client
+ *     assets, sha256 of the content in the name
+ *     (`plugin-host/src/client-assets.ts`).
+ *   - `_app/immutable/**` — Vite's hashed-output convention, kept for
+ *     builds that ship SvelteKit-style bundles.
+ *
+ * NOT content-hashed (deliberately excluded): media under
+ * `_assets/<slug>.<ext>` / `_assets/<slug>/<variant>.<ext>` — the slug is
+ * stable while the operator can replace the bytes behind it.
+ */
+/** Long-lived policy for content-addressed files. */
+export const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** Short, background-revalidated policy for pages (HTML documents). */
+export const HTML_CACHE_CONTROL = "public, max-age=60, stale-while-revalidate=86400";
+/**
+ * Regex (source string) matching every content-hashed URL path. It is
+ * matched against a site-absolute path ("/_assets/…") and uses only the
+ * syntax shared by ECMAScript and RE2 (no lookaround, no backrefs), so
+ * the same string can be handed to Firebase Hosting's `regex` header
+ * matcher and Caddy's `path_regexp` (both RE2) and to `RegExp` here.
+ */
+export const CONTENT_HASHED_PATH_PATTERN = "^/(?:_app/immutable/.+|_assets/fonts/[^/]+/[0-9a-f]{16,64}\\.(?:woff2|woff|ttf|otf)|_caelo/plugin/[^/]+/[^/]+\\.[0-9a-f]{12}\\.(?:js|css))$";
+const CONTENT_HASHED_PATH_RE = new RegExp(CONTENT_HASHED_PATH_PATTERN);
+/**
+ * True when `path` names a content-addressed build output. Accepts a
+ * build-dir-relative key (`_assets/fonts/inter/ab….woff2`, as the GCS
+ * publisher sees it) or a site-absolute URL path (`/_assets/…`).
+ */
+export function isContentHashedPath(path) {
+    return CONTENT_HASHED_PATH_RE.test(path.startsWith("/") ? path : `/${path}`);
+}
+//# sourceMappingURL=static-cache-policy.js.map

package/dist/static-cache-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-cache-policy.js","sourceRoot":"","sources":["../src/static-cache-policy.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAAG,qCAAqC,CAAC;AAE7E,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,kDAAkD,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GACtC,6IAA6I,CAAC;AAEhJ,MAAM,sBAAsB,GAAG,IAAI,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AAC/E,CAAC"}

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.10.28";
+export declare const CAELO_VERSION = "0.10.30";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.10.28";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.10.28";
+export declare const CALEO_VERSION = "0.10.30";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.10.28";
+export const CAELO_VERSION = "0.10.30";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.10.28",
+  "version": "0.10.30",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/ai-tools.ts

@@ -756,6 +756,7 @@ export const findMediaToolInput = z
         "image/avif",
         "image/gif",
         "image/svg+xml",
+        "image/x-icon",
         "application/pdf",
         "video/mp4",
       ])

package/src/database-url.test.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { databasePasswordVar, databaseUrlFromEnv, withDatabasePassword } from "./database-url.js";
+
+describe("databasePasswordVar", () => {
+  it("pairs each URL var with its _PASSWORD var", () => {
+    expect(databasePasswordVar("ADMIN_DATABASE_URL")).toBe("ADMIN_DATABASE_PASSWORD");
+    expect(databasePasswordVar("PUBLIC_ADMIN_DATABASE_URL")).toBe("PUBLIC_ADMIN_DATABASE_PASSWORD");
+    expect(databasePasswordVar("PUBLIC_DATABASE_URL")).toBe("PUBLIC_DATABASE_PASSWORD");
+  });
+
+  it("rejects a name that is not a URL var", () => {
+    expect(() => databasePasswordVar("ADMIN_DATABASE")).toThrow(/_URL/);
+  });
+});
+
+describe("withDatabasePassword", () => {
+  it("injects the password into a password-less URL, keeping host, db and params", () => {
+    expect(
+      withDatabasePassword(
+        "postgresql://admin_role@10.20.0.3:5432/cms_admin?sslmode=require",
+        "0123abcd",
+      ),
+    ).toBe("postgresql://admin_role:0123abcd@10.20.0.3:5432/cms_admin?sslmode=require");
+  });
+
+  it("keeps literal percent signs in the password (p%40ss stays p%40ss, p%ss stays valid)", () => {
+    for (const password of ["p%40ss", "p%ss", "100%"]) {
+      const parsed = new URL(withDatabasePassword("postgres://u@h:5432/d", password));
+      expect(decodeURIComponent(parsed.password)).toBe(password);
+    }
+  });
+
+  it("percent-encodes reserved characters so the URL stays parseable", () => {
+    const url = withDatabasePassword("postgres://u@h:5432/d", "p@ss/w:rd#?");
+    const parsed = new URL(url);
+    expect(decodeURIComponent(parsed.password)).toBe("p@ss/w:rd#?");
+    expect(parsed.host).toBe("h:5432");
+    expect(parsed.pathname).toBe("/d");
+  });
+
+  it("refuses a URL that already carries a password", () => {
+    expect(() => withDatabasePassword("postgres://u:old@h/d", "new")).toThrow(/already carries/);
+  });
+
+  it("refuses a URL without a user and a malformed URL", () => {
+    expect(() => withDatabasePassword("postgres://h/d", "p")).toThrow(/no user/);
+    expect(() => withDatabasePassword("not a url", "p")).toThrow(/not a valid URL/);
+  });
+
+  it("never echoes the password in its errors", () => {
+    try {
+      withDatabasePassword("postgres://u:old@h/d", "top-secret-value");
+    } catch (e) {
+      expect(String(e)).not.toContain("top-secret-value");
+      expect(String(e)).not.toContain("old");
+    }
+  });
+});
+
+describe("databaseUrlFromEnv", () => {
+  it("returns an inline-password URL unchanged (self-hosted compose, CI, .env)", () => {
+    const env = { ADMIN_DATABASE_URL: "postgres://admin_role:dev@localhost:5432/cms_admin" };
+    expect(databaseUrlFromEnv(["ADMIN_DATABASE_URL"], env)).toBe(env.ADMIN_DATABASE_URL);
+  });
+
+  it("composes the URL from the plain URL var + its secret-mounted password var (cloud)", () => {
+    const env = {
+      ADMIN_DATABASE_URL: "postgresql://admin_role@10.20.0.3:5432/cms_admin?sslmode=require",
+      ADMIN_DATABASE_PASSWORD: "s3cret",
+    };
+    expect(databaseUrlFromEnv(["ADMIN_DATABASE_URL"], env)).toBe(
+      "postgresql://admin_role:s3cret@10.20.0.3:5432/cms_admin?sslmode=require",
+    );
+  });
+
+  it("uses the password var that belongs to the URL var it picked", () => {
+    const env = {
+      PUBLIC_DATABASE_URL: "postgresql://public_role@h:5432/cms_public",
+      PUBLIC_DATABASE_PASSWORD: "pub",
+      // Not consulted: it pairs with PUBLIC_ADMIN_DATABASE_URL, which is unset.
+      PUBLIC_ADMIN_DATABASE_PASSWORD: "adm",
+    };
+    expect(databaseUrlFromEnv(["PUBLIC_ADMIN_DATABASE_URL", "PUBLIC_DATABASE_URL"], env)).toBe(
+      "postgresql://public_role:pub@h:5432/cms_public",
+    );
+  });
+
+  it("prefers the first URL var that is set", () => {
+    const env = {
+      PUBLIC_ADMIN_DATABASE_URL: "postgresql://admin_role@h:5432/cms_public",
+      PUBLIC_ADMIN_DATABASE_PASSWORD: "adm",
+      PUBLIC_DATABASE_URL: "postgresql://public_role@h:5432/cms_public",
+    };
+    expect(databaseUrlFromEnv(["PUBLIC_ADMIN_DATABASE_URL", "PUBLIC_DATABASE_URL"], env)).toBe(
+      "postgresql://admin_role:adm@h:5432/cms_public",
+    );
+  });
+
+  it("is undefined when no URL var is set", () => {
+    expect(databaseUrlFromEnv(["ADMIN_DATABASE_URL"], { ADMIN_DATABASE_PASSWORD: "x" })).toBe(
+      undefined,
+    );
+  });
+
+  it("fails loudly when both the URL and the password var carry a password", () => {
+    const env = {
+      ADMIN_DATABASE_URL: "postgres://admin_role:inline@h/cms_admin",
+      ADMIN_DATABASE_PASSWORD: "mounted",
+    };
+    expect(() => databaseUrlFromEnv(["ADMIN_DATABASE_URL"], env)).toThrow(
+      /ADMIN_DATABASE_URL \(with ADMIN_DATABASE_PASSWORD\) already carries a password/,
+    );
+  });
+});

package/src/database-url.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Database connection URLs as every Caelo process reads them from its
+ * environment.
+ *
+ * A URL var (`ADMIN_DATABASE_URL`, `PUBLIC_ADMIN_DATABASE_URL`,
+ * `PUBLIC_DATABASE_URL`) may carry its password inline — the shape the
+ * self-hosted compose stack, CI and `.env` use — or leave it out and have
+ * the password come from a companion `<NAME>_PASSWORD` var
+ * (`ADMIN_DATABASE_URL` → `ADMIN_DATABASE_PASSWORD`). Cloud installs use the
+ * second shape: the URL (host, role, database) is a plain env var, the
+ * password is a Secret Manager reference, so the password never shows up in
+ * the service's configuration or its revision history.
+ *
+ * Pure module — no I/O.
+ */
+
+/** The `<NAME>_PASSWORD` var that pairs with a `<NAME>_URL` var. */
+export function databasePasswordVar(urlVar: string): string {
+  if (!urlVar.endsWith("_URL")) {
+    throw new Error(`database URL var must end in _URL, got ${urlVar}`);
+  }
+  return `${urlVar.slice(0, -"_URL".length)}_PASSWORD`;
+}
+
+/**
+ * Inject `password` into a password-less connection URL. Refuses a URL that
+ * already carries one: two sources for the same credential is a
+ * misconfiguration, and silently preferring either would hide it.
+ *
+ * @example
+ *   withDatabasePassword("postgresql://admin_role@10.0.0.3:5432/cms_admin", "s3cr3t")
+ *   // → "postgresql://admin_role:s3cr3t@10.0.0.3:5432/cms_admin"
+ */
+export function withDatabasePassword(
+  url: string,
+  password: string,
+  label = "database URL",
+): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`${label} is not a valid URL`);
+  }
+  if (parsed.password) {
+    throw new Error(
+      `${label} already carries a password and a separate password is set too — keep one`,
+    );
+  }
+  if (!parsed.username) {
+    throw new Error(`${label} names no user to attach the password to`);
+  }
+  // Encode first: the URL setter leaves a literal `%` alone, so `p%40ss`
+  // would decode to `p@ss` and `p%ss` would be an invalid escape. Postgres
+  // clients decode the userinfo again.
+  parsed.password = encodeURIComponent(password);
+  return parsed.toString();
+}
+
+/**
+ * The connection URL from the first of `urlVars` that is set, with its
+ * companion `_PASSWORD` var applied when that is set. `undefined` when none
+ * of `urlVars` is set, so callers keep their own "X is required" errors.
+ *
+ * @param urlVars URL var names in order of preference, e.g.
+ *   `["PUBLIC_ADMIN_DATABASE_URL", "PUBLIC_DATABASE_URL"]`.
+ * @param env The environment to read (defaults to `process.env`).
+ */
+export function databaseUrlFromEnv(
+  urlVars: readonly string[],
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string | undefined {
+  for (const urlVar of urlVars) {
+    const url = env[urlVar];
+    if (!url) continue;
+    const passwordVar = databasePasswordVar(urlVar);
+    const password = env[passwordVar];
+    return password ? withDatabasePassword(url, password, `${urlVar} (with ${passwordVar})`) : url;
+  }
+  return undefined;
+}

package/src/design-draft-shell.test.ts

@@ -21,7 +21,11 @@ const TOKENS = {
 const THEME: ComposeTheme = {
   tokens: TOKENS,
   assets: {
-    logo: { mediaId: "11111111-1111-4111-8111-111111111111", url: "/_caelo/media/logo/orig" },
+    logo: {
+      mediaId: "11111111-1111-4111-8111-111111111111",
+      url: "/_caelo/media/logo/orig",
+      mime: "image/png",
+    },
     logoDark: null,
     favicon: null,
     socialShare: null,

package/src/document-language.test.ts

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  applyDocumentLanguage,
+  languageTagSchema,
+  resolveDocumentLanguage,
+} from "./document-language.js";
+
+describe("applyDocumentLanguage", () => {
+  // Regression: every composed page started with a bare `<html>`, so
+  // Lighthouse flagged html-has-lang on the whole site.
+  it("adds lang to a bare <html>", () => {
+    expect(applyDocumentLanguage("<!doctype html><html><head></head></html>", "en")).toBe(
+      '<!doctype html><html lang="en"><head></head></html>',
+    );
+  });
+
+  it("replaces a layout-authored lang (quoted, single-quoted, unquoted, bare)", () => {
+    for (const tag of [
+      '<html lang="xx">',
+      "<html lang='xx'>",
+      "<html lang=xx>",
+      "<html lang>",
+      '<html LANG="xx">',
+    ]) {
+      expect(applyDocumentLanguage(`${tag}<head></head>`, "de")).toBe(
+        '<html lang="de"><head></head>',
+      );
+    }
+  });
+
+  it("keeps other attributes, including xml:lang and `>` inside quoted values", () => {
+    expect(
+      applyDocumentLanguage(
+        '<html class="dark" data-x="a>b" xml:lang="xx" lang="xx" dir="ltr"><head></head>',
+        "pt-BR",
+      ),
+    ).toBe('<html lang="pt-BR" class="dark" data-x="a>b" xml:lang="xx" dir="ltr"><head></head>');
+  });
+
+  it("only touches the first <html> start tag, never look-alikes", () => {
+    const html = '<html-widget lang="xx"></html-widget><html><body><html></body></html>';
+    expect(applyDocumentLanguage(html, "en")).toBe(
+      '<html-widget lang="xx"></html-widget><html lang="en"><body><html></body></html>',
+    );
+  });
+
+  it("inserts an <html> start tag after the doctype when the layout omits it", () => {
+    expect(applyDocumentLanguage("<!DOCTYPE html>\n<head></head><body></body>", "en")).toBe(
+      '<!DOCTYPE html><html lang="en">\n<head></head><body></body>',
+    );
+    expect(applyDocumentLanguage("<head></head><body></body>", "en")).toBe(
+      '<html lang="en"><head></head><body></body>',
+    );
+  });
+
+  it("keeps data-lang and self-closing slashes, drops every lang", () => {
+    expect(applyDocumentLanguage('<html data-lang="x" lang=a\tlang="b" />', "en")).toBe(
+      '<html lang="en" data-lang="x" />',
+    );
+  });
+
+  // Regression (CodeQL js/polynomial-redos): the attribute strip was a
+  // global `\s+lang…` regex that backtracked quadratically over long
+  // whitespace runs in layout HTML.
+  it("stays linear on long whitespace runs", () => {
+    const ws = "\t".repeat(200_000);
+    const started = performance.now();
+    expect(applyDocumentLanguage(`<html${ws}x${ws}>`, "en")).toBe(`<html lang="en"${ws}x${ws}>`);
+    expect(applyDocumentLanguage(`<html${ws}`, "en")).toBe(`<html lang="en"><html${ws}`);
+    expect(performance.now() - started).toBeLessThan(1000);
+  });
+
+  // Migration 0232: an unconfigured site language renders no `lang`
+  // rather than a substituted one.
+  it("with no language, strips a layout-authored lang and adds none", () => {
+    expect(applyDocumentLanguage('<html lang="en" class="x"><head></head>', null)).toBe(
+      '<html class="x"><head></head>',
+    );
+    expect(applyDocumentLanguage("<!doctype html><head></head>", null)).toBe(
+      "<!doctype html><head></head>",
+    );
+  });
+
+  it("escapes the value", () => {
+    expect(applyDocumentLanguage("<html>", 'a"b')).toBe('<html lang="a&quot;b">');
+  });
+});
+
+describe("resolveDocumentLanguage", () => {
+  it("prefers the plugin-contributed per-page language", () => {
+    expect(resolveDocumentLanguage({ contributed: "de", siteLanguage: "en" })).toBe("de");
+  });
+
+  it("uses the stored site language when no plugin assigns one", () => {
+    expect(resolveDocumentLanguage({ contributed: undefined, siteLanguage: "fr" })).toBe("fr");
+  });
+
+  it("returns null when neither a plugin nor the site sets a language — never 'en'", () => {
+    expect(resolveDocumentLanguage({ contributed: undefined, siteLanguage: null })).toBeNull();
+    expect(resolveDocumentLanguage({ contributed: "de", siteLanguage: null })).toBe("de");
+  });
+});
+
+describe("languageTagSchema", () => {
+  it("accepts BCP 47 shaped tags", () => {
+    for (const tag of ["en", "de", "pt-BR", "zh-Hant-TW", "es-419", "gsw"]) {
+      expect(languageTagSchema.safeParse(tag).success).toBe(true);
+    }
+  });
+
+  it("rejects malformed tags", () => {
+    for (const tag of ["", "e", "en_US", "en-", "-en", 'en" onload="x', "x".repeat(36)]) {
+      expect(languageTagSchema.safeParse(tag).success).toBe(false);
+    }
+  });
+});

package/src/document-language.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The document language — the `lang` attribute on `<html>`.
+ *
+ * Screen readers pick their pronunciation from it and search engines
+ * use it to classify the page, so every page Caelo renders must carry
+ * one. Like `<title>` and the rest of the SEO head, it is a structured
+ * value owned by core, never something a layout author hand-writes:
+ * the composed page always carries the value core resolved, replacing
+ * whatever `lang` the layout HTML happened to contain.
+ *
+ * Where the value comes from (resolved identically by the admin
+ * preview and the static generator):
+ *   1. the per-page language a plugin contributes through the head
+ *      contribution point (the `international-site` plugin knows each
+ *      page's locale — core does not, since epic #380), else
+ *   2. the site's stored language (`site_defaults.site_language`, set
+ *      by the AI via `set_site_identity` or by the Owner at /security/seo).
+ * The stored language has no default (migration 0232, CLAUDE.md §2): NULL
+ * means nobody chose one yet. Nothing here substitutes a language for it —
+ * the preview renders `<html>` without `lang` and flags
+ * `site-language-unset`, and the static generator refuses to build.
+ */
+
+import { z } from "zod";
+
+/**
+ * A BCP 47 language tag as accepted for `<html lang>`: a 2–8 letter
+ * primary subtag followed by optional alphanumeric subtags (`en`,
+ * `de-AT`, `zh-Hant-TW`). Deliberately structural rather than a full
+ * registry check — the same shape the `site_defaults.site_language`
+ * CHECK constraint enforces.
+ */
+export const languageTagSchema = z
+  .string()
+  .max(35)
+  .regex(
+    /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/,
+    "must be a BCP 47 language tag such as `en`, `de` or `pt-BR`",
+  );
+
+/**
+ * Pick the language for one page: a plugin-contributed per-page value
+ * wins over the site's stored language. Exported so preview and build
+ * resolve through the same expression.
+ *
+ * @returns `null` when no plugin assigns one and the site language is not
+ *   configured — the caller surfaces that state, never a guessed tag.
+ */
+export function resolveDocumentLanguage(args: {
+  readonly contributed: string | undefined;
+  readonly siteLanguage: string | null;
+}): string | null {
+  return args.contributed ?? args.siteLanguage;
+}
+
+// The `<html` start-tag opener; the lookahead keeps look-alikes such as
+// `<html-widget>` out. Fixed-width, so matching is linear.
+const HTML_TAG_OPENER_RE = /<html(?=[\s>/])/i;
+const DOCTYPE_RE = /^\s*<!doctype[^>]*>/i;
+// HTML's ASCII whitespace (the tokenizer's attribute separators).
+const HTML_WS = new Set(["\t", "\n", "\f", "\r", " "]);
+
+/**
+ * Scan the attributes of the start tag beginning at `from` (just past
+ * `<html`) and return them with every `lang` attribute removed, plus the
+ * index just past the closing `>`. `null` when the tag never closes.
+ *
+ * A single forward pass over the tag, character by character: layout
+ * HTML is AI- or operator-authored input, and a backtracking regex over
+ * it (`\s+lang…` with a global flag) is polynomial on long whitespace
+ * runs (CodeQL js/polynomial-redos). Quoted values may contain `>`.
+ * `xml:lang` and `data-lang` are different attribute names and survive.
+ */
+function stripLangAttributes(
+  html: string,
+  from: number,
+): { readonly attrs: string; readonly end: number } | null {
+  const n = html.length;
+  let i = from;
+  let attrs = "";
+  while (i < n) {
+    const segmentStart = i;
+    while (i < n && HTML_WS.has(html[i] as string)) i++;
+    if (i >= n) return null;
+    if (html[i] === ">") return { attrs: attrs + html.slice(segmentStart, i), end: i + 1 };
+    const nameStart = i;
+    // An attribute name runs to whitespace, `=`, `>` or `/`; a stray `=`
+    // or `/` is consumed as a one-character name so the scan always moves.
+    i++;
+    while (i < n && !HTML_WS.has(html[i] as string) && !"=>/".includes(html[i] as string)) i++;
+    const name = html.slice(nameStart, i).toLowerCase();
+    const afterName = i;
+    while (i < n && HTML_WS.has(html[i] as string)) i++;
+    if (html[i] === "=") {
+      i++;
+      while (i < n && HTML_WS.has(html[i] as string)) i++;
+      const quote = html[i];
+      if (quote === '"' || quote === "'") {
+        const close = html.indexOf(quote, i + 1);
+        if (close === -1) return null;
+        i = close + 1;
+      } else {
+        while (i < n && !HTML_WS.has(html[i] as string) && html[i] !== ">") i++;
+      }
+    } else {
+      // No value: the whitespace belongs to the next attribute.
+      i = afterName;
+    }
+    if (name !== "lang") attrs += html.slice(segmentStart, i);
+  }
+  return null;
+}
+
+function escapeAttr(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+/**
+ * Set `lang` on the document's `<html>` start tag, replacing any value
+ * the layout carried. A layout with no `<html>` start tag (the tag is
+ * optional in HTML) gets one inserted right after the doctype, which
+ * parses to the same document with the language attached. An `<html`
+ * start tag that never closes is malformed and treated as absent.
+ *
+ * `lang: null` (no language configured) removes every layout-authored
+ * `lang` and adds none: core owns the value, so a hand-written one must
+ * not pass for a configured language.
+ */
+export function applyDocumentLanguage(html: string, lang: string | null): string {
+  const attr = lang === null ? "" : ` lang="${escapeAttr(lang)}"`;
+  const open = HTML_TAG_OPENER_RE.exec(html);
+  const tag = open ? stripLangAttributes(html, open.index + "<html".length) : null;
+  if (open && tag) {
+    return `${html.slice(0, open.index)}<html${attr}${tag.attrs}>${html.slice(tag.end)}`;
+  }
+  if (lang === null) return html;
+  const doctype = DOCTYPE_RE.exec(html);
+  const at = doctype ? doctype[0].length : 0;
+  return `${html.slice(0, at)}<html${attr}>${html.slice(at)}`;
+}

package/src/index.ts

@@ -11,7 +11,9 @@ export * from "./content.js";
 export * from "./context.js";
 export * from "./css-gradient-scan.js";
 export * from "./css-var-scan.js";
+export * from "./database-url.js";
 export * from "./design-draft-shell.js";
+export * from "./document-language.js";
 export * from "./font-assets.js";
 export * from "./fonts.js";
 export * from "./genesis.js";
@@ -42,6 +44,7 @@ export * from "./safe-keys.js";
 export * from "./seo.js";
 export * from "./skills.js";
 export * from "./snapshots.js";
+export * from "./static-cache-policy.js";
 export * from "./strip-cdata.js";
 export * from "./structured-sets.js";
 export * from "./subagents.js";

package/src/media.test.ts

@@ -68,6 +68,14 @@ describe("media size caps + allowlist", () => {
     }
   });
 
+  it("allows .ico under the single canonical image/x-icon, capped at 1 MiB", () => {
+    const allowed: readonly string[] = MEDIA_ALLOWED_MIMES;
+    expect(allowed).toContain("image/x-icon");
+    // The IANA alias is normalised on the way in, never stored.
+    expect(allowed).not.toContain("image/vnd.microsoft.icon");
+    expect(MEDIA_SIZE_CAPS["image/x-icon"]).toBe(1024 * 1024);
+  });
+
   it("variant widths cover the non-orig tags only", () => {
     for (const t of MEDIA_VARIANT_TAGS) {
       if (t === "orig") continue;

package/src/media.ts

@@ -26,6 +26,13 @@ export const MEDIA_ALLOWED_MIMES = [
   "image/avif",
   "image/gif",
   "image/svg+xml",
+  // Favicons (.ico). `image/x-icon` is the one canonical stored value:
+  // it is what the upload sniffer (file-type) reports, what browsers send
+  // and what MDN's `<link rel="icon" type>` examples use. The IANA name
+  // `image/vnd.microsoft.icon` is normalised to it on the way in (see
+  // `normalizeAssetMime` in admin-core) and never stored. Stored as-is
+  // (no derived variants) — the ICO container carries its own sizes.
+  "image/x-icon",
   "application/pdf",
   "video/mp4",
   // issue #249 — webfonts. Migrated sites reference their own font
@@ -47,6 +54,7 @@ export const MEDIA_SIZE_CAPS: Record<MediaMime, number> = {
   "image/avif": 10 * 1024 * 1024,
   "image/gif": 8 * 1024 * 1024,
   "image/svg+xml": 1 * 1024 * 1024,
+  "image/x-icon": 1 * 1024 * 1024,
   "application/pdf": 20 * 1024 * 1024,
   "video/mp4": 50 * 1024 * 1024,
   "font/woff2": 5 * 1024 * 1024,