@caelo-cms/shared 0.10.27 → 0.10.29

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

@@ -12,6 +12,7 @@ export * from "./context.js";
 export * from "./css-gradient-scan.js";
 export * from "./css-var-scan.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 +43,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,

package/src/preview-compose.test.ts

@@ -651,3 +651,85 @@ it("preloads pinned TTF/OTF/WOFF files with their actual format", () => {
   expect(html).toContain('type="font/otf"');
   expect(html).toContain('type="font/woff"');
 });
+
+// The theme's favicon is document metadata: binding it via
+// `set_theme_asset({slot:"favicon"})` must put a `<link rel="icon">` into
+// <head> on every page, without any module carrying the tag. Before this,
+// nothing was emitted and browsers fell back to a 404ing /favicon.ico.
+describe("theme favicon in <head>", () => {
+  const layoutHtml = `<!doctype html><html><head><title>t</title></head><body><caelo-slot name="content">_</caelo-slot></body></html>`;
+  const templateHtml = `<body><caelo-slot name="content">_</caelo-slot></body>`;
+  const themeWith = (favicon: { url: string; mime: string } | null) => ({
+    tokens: {},
+    assets: {
+      logo: null,
+      logoDark: null,
+      favicon:
+        favicon === null ? null : { mediaId: "44444444-4444-4444-8444-444444444444", ...favicon },
+      socialShare: null,
+    },
+  });
+  const headOf = (html: string): string => html.slice(0, html.indexOf("</head>"));
+  const bodyOf = (html: string): string => html.slice(html.indexOf("</head>"));
+
+  it("composePageWithLayout emits <link rel=icon> with the bound media URL + mime", () => {
+    const out = composePageWithLayout({
+      templateHtml,
+      templateCss: "",
+      blocks: [],
+      layoutHtml,
+      layoutCss: "",
+      layoutBlocks: [],
+      layoutSlug: "test",
+      theme: themeWith({ url: "/_caelo/media/viu-one-favicon", mime: "image/svg+xml" }),
+    });
+    const tag = '<link rel="icon" href="/_caelo/media/viu-one-favicon" type="image/svg+xml">';
+    expect(headOf(out.html)).toContain(tag);
+    expect(bodyOf(out.html)).not.toContain('rel="icon"');
+    // Exactly once per page.
+    expect(out.html.split('rel="icon"').length - 1).toBe(1);
+  });
+
+  it("composePagePreview emits the same tag", () => {
+    const out = composePagePreview({
+      templateHtml: `<html><head></head><body><caelo-slot name="content">_</caelo-slot></body></html>`,
+      templateCss: "",
+      blocks: [],
+      theme: themeWith({ url: "/_caelo/media/fav", mime: "image/png" }),
+    });
+    expect(headOf(out.html)).toContain(
+      '<link rel="icon" href="/_caelo/media/fav" type="image/png">',
+    );
+  });
+
+  it("emits no icon link when the theme has no favicon bound, or no theme is threaded", () => {
+    const base = {
+      templateHtml,
+      templateCss: "",
+      blocks: [],
+      layoutHtml,
+      layoutCss: "",
+      layoutBlocks: [],
+      layoutSlug: "test",
+    };
+    expect(composePageWithLayout({ ...base, theme: themeWith(null) }).html).not.toContain(
+      'rel="icon"',
+    );
+    expect(composePageWithLayout(base).html).not.toContain('rel="icon"');
+  });
+
+  it("attribute-escapes the URL and mime", () => {
+    const out = composePageWithLayout({
+      templateHtml,
+      templateCss: "",
+      blocks: [],
+      layoutHtml,
+      layoutCss: "",
+      layoutBlocks: [],
+      layoutSlug: "test",
+      theme: themeWith({ url: '/x"><script>', mime: "image/png" }),
+    });
+    expect(out.html).toContain('href="/x&quot;&gt;&lt;script&gt;"');
+    expect(out.html).not.toContain('/x"><script>');
+  });
+});

package/src/preview-compose.ts

@@ -102,6 +102,12 @@ export interface ComposeStructuredSets {
 export interface ComposeThemeAsset {
   readonly mediaId: string;
   readonly url: string;
+  /**
+   * `media_assets.mime` of the bound asset — the content type of the
+   * `orig` bytes the URL serves. Carried so `<head>` metadata that
+   * declares a type (`<link rel="icon" type=…>`) states the real one.
+   */
+  readonly mime: string;
 }
 
 export interface ComposeTheme {
@@ -195,6 +201,25 @@ export function fontsHeadFragment(fonts: ComposeFonts | undefined): string | nul
   return fragment.length > 0 ? fragment : null;
 }
 
+/**
+ * Head fragment for the active theme's document-level brand metadata:
+ * `<link rel="icon">` when a favicon is bound. The favicon is page
+ * METADATA, not body content — it must sit in `<head>` on every page
+ * regardless of which layout or chrome modules the page uses, so the
+ * composer emits it from the theme binding instead of relying on a
+ * module to carry the tag. The href is the media URL as composed
+ * (`/_caelo/media/<slug>`); the static generator's media pass rewrites
+ * it to the published `/_assets/<slug>.<ext>` and copies the bytes, the
+ * same as any other media reference. Returns null when no theme is
+ * threaded or no favicon is bound (nothing to declare; browsers fall
+ * back to their own `/favicon.ico` probe exactly as before).
+ */
+function themeHeadFragment(theme: ComposeTheme | undefined): string | null {
+  const favicon = theme?.assets.favicon;
+  if (!favicon) return null;
+  return `<link rel="icon" href="${escapeAttr(favicon.url)}" type="${escapeAttr(favicon.mime)}">`;
+}
+
 export function composePagePreview(input: ComposeInput): ComposeOutput {
   // No withholding path here; rendering a withheld module would ship it
   // ungated, so refuse instead of degrading silently (CLAUDE.md §2).
@@ -251,7 +276,15 @@ export function composePagePreview(input: ComposeInput): ComposeOutput {
   const replaced = applySlotReplacements(input.templateHtml, { contentByName });
   let html = replaced.html;
 
-  // issue #150 — @font-face + preloads before everything else so the
+  // Theme brand metadata (favicon) leads the injected head block — it
+  // is document metadata, not styling, and is independent of the
+  // cascade order the style tags below depend on.
+  const themeHeadLinks = themeHeadFragment(input.theme);
+  if (themeHeadLinks !== null) {
+    html = injectBefore(html, HEAD_CLOSE_RE, themeHeadLinks);
+  }
+
+  // issue #150 — @font-face + preloads ahead of the style tags so the
   // browser discovers font URLs as early as possible.
   const fontsFragment = fontsHeadFragment(input.fonts);
   if (fontsFragment !== null) {
@@ -695,6 +728,12 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
   });
   let html = replaced.html;
 
+  // Theme brand metadata (favicon) — see composePagePreview.
+  const themeHeadLinks = themeHeadFragment(input.theme);
+  if (themeHeadLinks !== null) {
+    html = injectBefore(html, HEAD_CLOSE_RE, themeHeadLinks);
+  }
+
   // issue #150 — fonts first (URL discovery), then theme vars, then
   // aggregated CSS; source order in <head> mirrors injection order.
   const fontsFragment = fontsHeadFragment(input.fonts);

package/src/seo.test.ts

@@ -87,6 +87,14 @@ describe("renderSeoHead", () => {
     organization: {},
   };
 
+  it("#551: omits canonical, og:url and the JSON-LD url when the base URL is unset", () => {
+    const head = renderSeoHead({ ...base, canonical: null });
+    expect(head).not.toContain('rel="canonical"');
+    expect(head).not.toContain("og:url");
+    expect(head).not.toContain('"url"');
+    expect(head).toContain("<title>Welcome</title>");
+  });
+
   it("emits canonical + og:type + og:url for the simplest valid input", () => {
     const head = renderSeoHead(base);
     expect(head).toContain("<title>Welcome</title>");

package/src/seo.ts

@@ -98,6 +98,10 @@ export interface PageSeoRow {
 export interface SiteSeoSettings {
   siteBaseUrl: string;
   sitemapEnabled: boolean;
+  /** `site_defaults.site_language` — the `<html lang>` of every page no
+   *  plugin assigns its own locale to (see document-language.ts). Always
+   *  set here: the static generator refuses to build while it is NULL. */
+  siteLanguage: string;
   organization: {
     name?: string;
     url?: string;
@@ -138,7 +142,13 @@ export function resolveCanonicalUrl(args: {
 export interface SeoMetaInput {
   title: string;
   metaDescription: string;
-  canonical: string;
+  /**
+   * Absolute canonical URL, or null when the site base URL is not
+   * configured yet (#551). Only the admin preview renders with null — it
+   * omits canonical, og:url and the JSON-LD url and flags
+   * `site-base-url-unset`; the static generator refuses to build instead.
+   */
+  canonical: string | null;
   noindex: boolean;
   ogImageUrl: string | null;
   organization: SiteSeoSettings["organization"];
@@ -162,7 +172,9 @@ export function renderSeoHead(input: SeoMetaInput): string {
   if (input.metaDescription) {
     lines.push(`<meta name="description" content="${enc(input.metaDescription)}" />`);
   }
-  lines.push(`<link rel="canonical" href="${enc(input.canonical)}" />`);
+  if (input.canonical) {
+    lines.push(`<link rel="canonical" href="${enc(input.canonical)}" />`);
+  }
   if (input.noindex) {
     lines.push(`<meta name="robots" content="noindex" />`);
   }
@@ -172,7 +184,9 @@ export function renderSeoHead(input: SeoMetaInput): string {
     lines.push(`<meta property="og:description" content="${enc(input.metaDescription)}" />`);
   }
   lines.push(`<meta property="og:type" content="website" />`);
-  lines.push(`<meta property="og:url" content="${enc(input.canonical)}" />`);
+  if (input.canonical) {
+    lines.push(`<meta property="og:url" content="${enc(input.canonical)}" />`);
+  }
   if (input.ogImageUrl) {
     lines.push(`<meta property="og:image" content="${enc(input.ogImageUrl)}" />`);
   }
@@ -185,7 +199,7 @@ export function renderSeoHead(input: SeoMetaInput): string {
     "@context": "https://schema.org",
     "@type": "WebPage",
     name: input.title,
-    url: input.canonical,
+    ...(input.canonical ? { url: input.canonical } : {}),
   };
   if (input.metaDescription) ld.description = input.metaDescription;
   if (input.ogImageUrl) ld.image = input.ogImageUrl;

package/src/static-cache-policy.test.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { CONTENT_HASHED_PATH_PATTERN, isContentHashedPath } from "./static-cache-policy.js";
+
+/** Build outputs whose URL changes whenever their bytes change. */
+const HASHED_PATHS = [
+  // Lighthouse report on gcp-firebase staging (v0.10.28).
+  "/_assets/fonts/inter/29ede7bd4be32ab0.woff2",
+  "/_assets/fonts/manrope/f3a06e9b32049b82.woff2",
+  `/_assets/fonts/pinned/${"a".repeat(64)}.woff2`,
+  `/_assets/fonts/pinned/${"0".repeat(64)}.ttf`,
+  "/_caelo/plugin/consent-manager/runtime.0123456789ab.js",
+  "/_caelo/plugin/consent-manager/banner.abcdef012345.css",
+  "/_app/immutable/chunks/abc.js",
+];
+
+/** Build outputs served under a stable name — must stay short-lived. */
+const STABLE_PATHS = [
+  "/",
+  "/index.html",
+  "/about/",
+  "/about/index.html",
+  "/en/about",
+  "/robots.txt",
+  "/sitemap.xml",
+  "/routing-manifest.json",
+  "/cdn_manifest.json",
+  "/_content-types.json",
+  // Media addressed by slug: bytes can change behind the same URL.
+  "/_assets/searchviu-logo.png",
+  "/_assets/hero/w800.webp",
+  "/_assets/0b1f6c2e-9d7a-4c1e-8f3a-2b6d9e0c1a4f/orig.jpg",
+  "/_caelo/media/hero",
+  // Pinned-font license file is id-named, not hashed.
+  "/_assets/fonts/pinned/0b1f6c2e-9d7a-4c1e-8f3a-2b6d9e0c1a4f.license.txt",
+  // Look-alikes that must not slip through.
+  "/_assets/fonts/inter/not-a-hash.woff2",
+  "/_assets/fonts/inter/29ede7bd4be32ab0.woff2.html",
+  "/_caelo/plugin/consent-manager/runtime.js",
+  "/blog/_assets/fonts/inter/29ede7bd4be32ab0.woff2",
+  "/api/forms/submit",
+];
+
+describe("isContentHashedPath", () => {
+  it("matches every content-hashed build output", () => {
+    for (const p of HASHED_PATHS) expect(isContentHashedPath(p)).toBe(true);
+  });
+
+  it("rejects pages, manifests and slug-addressed media", () => {
+    for (const p of STABLE_PATHS) expect(isContentHashedPath(p)).toBe(false);
+  });
+
+  it("accepts build-dir-relative keys (no leading slash) the same way", () => {
+    expect(isContentHashedPath("_assets/fonts/inter/29ede7bd4be32ab0.woff2")).toBe(true);
+    expect(isContentHashedPath("_assets/searchviu-logo.png")).toBe(false);
+  });
+
+  it("uses only RE2-compatible syntax (Firebase Hosting + Caddy match with RE2)", () => {
+    // No lookaround, no backreferences, no named groups.
+    expect(CONTENT_HASHED_PATH_PATTERN).not.toMatch(/\(\?[=!<]/);
+    expect(CONTENT_HASHED_PATH_PATTERN).not.toMatch(/\\[1-9]/);
+    expect(CONTENT_HASHED_PATH_PATTERN.startsWith("^/")).toBe(true);
+    expect(CONTENT_HASHED_PATH_PATTERN.endsWith("$")).toBe(true);
+  });
+});

package/src/static-cache-policy.ts

@@ -0,0 +1,60 @@
+// 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: string): boolean {
+  return CONTENT_HASHED_PATH_RE.test(path.startsWith("/") ? path : `/${path}`);
+}

package/src/version.ts

@@ -22,7 +22,7 @@
  * follow standard SemVer.
  */
 
-export const CAELO_VERSION = "0.10.27";
+export const CAELO_VERSION = "0.10.29";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this