@caelo-cms/shared 0.10.28 → 0.10.30

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

@@ -2,6 +2,7 @@
 
 import { describe, expect, it } from "bun:test";
 import {
+  checkPublicSiteBaseUrl,
   injectSeoIntoHead,
   renderSeoHead,
   resolveCanonicalUrl,
@@ -9,6 +10,7 @@ import {
   seoOptimizeInputSchema,
   seoSetInputSchema,
   siteDefaultsSetSeoInputSchema,
+  siteSeoProposalInputSchema,
 } from "./seo.js";
 
 describe("resolveCanonicalUrl", () => {
@@ -18,6 +20,8 @@ describe("resolveCanonicalUrl", () => {
         siteBaseUrl: "https://example.com",
         pagePath: "/anything",
         override: "https://canonical.example.com/x",
+        pageUrlStyle: "directory",
+        host: "de.example.com",
       }),
     ).toBe("https://canonical.example.com/x");
   });
@@ -28,6 +32,7 @@ describe("resolveCanonicalUrl", () => {
         siteBaseUrl: "https://example.com",
         pagePath: "/",
         override: null,
+        pageUrlStyle: "directory",
       }),
     ).toBe("https://example.com/");
   });
@@ -38,10 +43,42 @@ describe("resolveCanonicalUrl", () => {
         siteBaseUrl: "https://example.com/",
         pagePath: "/about",
         override: null,
+        pageUrlStyle: "directory",
       }),
     ).toBe("https://example.com/about/");
   });
 
+  describe("#590 — composed host (host-strategy locales)", () => {
+    for (const [style, expected] of [
+      ["directory", "https://de.example.com/preise/"],
+      ["no-extension", "https://de.example.com/preise"],
+    ] as const) {
+      it(`swaps the host, keeps the base scheme and the ${style} slash rule`, () => {
+        expect(
+          resolveCanonicalUrl({
+            siteBaseUrl: "https://example.com/",
+            pagePath: "/preise",
+            override: null,
+            pageUrlStyle: style,
+            host: "de.example.com",
+          }),
+        ).toBe(expected);
+      });
+    }
+
+    it("a null host keeps the site base host", () => {
+      expect(
+        resolveCanonicalUrl({
+          siteBaseUrl: "https://example.com",
+          pagePath: "/",
+          override: null,
+          pageUrlStyle: "no-extension",
+          host: null,
+        }),
+      ).toBe("https://example.com/");
+    });
+  });
+
   describe("v0.2.85 — pageUrlStyle='no-extension'", () => {
     it("omits the trailing slash for non-home pages", () => {
       expect(
@@ -65,12 +102,13 @@ describe("resolveCanonicalUrl", () => {
       ).toBe("https://example.com/");
     });
 
-    it("default style preserves pre-v0.2.85 trailing-slash behavior", () => {
+    it("'directory' keeps the trailing slash for non-home pages", () => {
       expect(
         resolveCanonicalUrl({
           siteBaseUrl: "https://example.com",
           pagePath: "/about",
           override: null,
+          pageUrlStyle: "directory",
         }),
       ).toBe("https://example.com/about/");
     });
@@ -87,6 +125,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>");
@@ -192,3 +238,101 @@ describe("schemas", () => {
     expect(r.success).toBe(false);
   });
 });
+
+describe("siteSeoProposalInputSchema", () => {
+  it("accepts any single field", () => {
+    expect(siteSeoProposalInputSchema.safeParse({ siteBaseUrl: "https://a.example" }).success).toBe(
+      true,
+    );
+    expect(siteSeoProposalInputSchema.safeParse({ sitemapEnabled: false }).success).toBe(true);
+    expect(
+      siteSeoProposalInputSchema.safeParse({ organizationJson: { name: "Acme" } }).success,
+    ).toBe(true);
+  });
+
+  it("rejects an empty proposal with a message naming the fields", () => {
+    const r = siteSeoProposalInputSchema.safeParse({});
+    expect(r.success).toBe(false);
+    expect(JSON.stringify(r.error?.issues)).toContain("siteBaseUrl");
+  });
+
+  it("rejects unknown keys at the top level and inside organizationJson", () => {
+    expect(siteSeoProposalInputSchema.safeParse({ sitemapEnabled: true, x: 1 }).success).toBe(
+      false,
+    );
+    expect(
+      siteSeoProposalInputSchema.safeParse({ organizationJson: { name: "A", script: "<x>" } })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("checkPublicSiteBaseUrl", () => {
+  it("normalises a valid https URL to its origin", () => {
+    expect(checkPublicSiteBaseUrl("https://www.Example.com/", "gcp")).toEqual({
+      ok: true,
+      url: "https://www.example.com",
+    });
+    expect(checkPublicSiteBaseUrl(" https://example.com:8443 ", undefined)).toEqual({
+      ok: true,
+      url: "https://example.com:8443",
+    });
+  });
+
+  it("rejects a path, query or fragment and names the origin to use instead", () => {
+    for (const raw of [
+      "https://example.com/blog",
+      "https://example.com/?a=1",
+      "https://example.com/#top",
+    ]) {
+      const r = checkPublicSiteBaseUrl(raw, "aws");
+      expect(r.ok).toBe(false);
+      if (!r.ok) expect(r.message).toContain("use https://example.com");
+    }
+  });
+
+  it("rejects non-URLs and credentials", () => {
+    expect(checkPublicSiteBaseUrl("example.com", "gcp").ok).toBe(false);
+    expect(checkPublicSiteBaseUrl("https://u:p@example.com", "gcp").ok).toBe(false);
+  });
+
+  it("requires https for public hosts on every provider", () => {
+    expect(checkPublicSiteBaseUrl("http://example.com", "gcp").ok).toBe(false);
+    expect(checkPublicSiteBaseUrl("http://example.com", "self-hosted").ok).toBe(false);
+    expect(checkPublicSiteBaseUrl("ftp://example.com", undefined).ok).toBe(false);
+  });
+
+  it("rejects loopback hosts on cloud providers", () => {
+    for (const provider of ["gcp", "gcp-firebase", "aws", "azure"]) {
+      for (const raw of [
+        "https://localhost",
+        "http://localhost:8082",
+        "https://127.0.0.1",
+        "https://[::1]",
+        "https://app.localhost",
+      ]) {
+        const r = checkPublicSiteBaseUrl(raw, provider);
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.message).toContain("public domain");
+      }
+    }
+  });
+
+  it("allows http://localhost on a self-hosted install (local dev)", () => {
+    expect(checkPublicSiteBaseUrl("http://localhost:8082", undefined)).toEqual({
+      ok: true,
+      url: "http://localhost:8082",
+    });
+    expect(checkPublicSiteBaseUrl("http://127.0.0.1:8082", "self-hosted").ok).toBe(true);
+  });
+
+  it("rejects wildcard bind addresses on every provider, self-hosted included", () => {
+    for (const provider of [undefined, "self-hosted", "gcp"]) {
+      for (const raw of ["http://0.0.0.0:8082", "https://0.0.0.0", "http://[::]:8082"]) {
+        const r = checkPublicSiteBaseUrl(raw, provider);
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.message).toContain("bind address");
+      }
+    }
+  });
+});

package/src/seo.ts

@@ -61,6 +61,16 @@ export const seoOptimizeInputSchema = z
   .strict();
 export type SeoOptimizeInput = z.infer<typeof seoOptimizeInputSchema>;
 
+/** Organization JSON-LD fields — structured only, never raw markup (CLAUDE.md §2). */
+const organizationJsonSchema = z
+  .object({
+    name: z.string().max(256).optional(),
+    url: z.string().max(2048).optional(),
+    logo: z.string().max(2048).optional(),
+    sameAs: z.array(z.string().max(2048)).max(20).optional(),
+  })
+  .strict();
+
 export const siteDefaultsSetSeoInputSchema = z
   .object({
     siteBaseUrl: z
@@ -69,19 +79,101 @@ export const siteDefaultsSetSeoInputSchema = z
       .max(2048)
       .url("siteBaseUrl must be an absolute URL (https://example.com)"),
     sitemapEnabled: z.boolean(),
-    organizationJson: z
-      .object({
-        name: z.string().max(256).optional(),
-        url: z.string().max(2048).optional(),
-        logo: z.string().max(2048).optional(),
-        sameAs: z.array(z.string().max(2048)).max(20).optional(),
-      })
-      .strict()
-      .default({}),
+    organizationJson: organizationJsonSchema.default({}),
   })
   .strict();
 export type SiteDefaultsSetSeoInput = z.infer<typeof siteDefaultsSetSeoInputSchema>;
 
+/**
+ * Input of `site_defaults.propose_set_seo` — the AI's path to the site SEO
+ * settings (CLAUDE.md §11.A). Every field is optional so the AI changes only
+ * what the operator asked for; an omitted field keeps its stored value when
+ * the Owner approves. `organizationJson` replaces the whole object.
+ */
+export const siteSeoProposalInputSchema = z
+  .object({
+    siteBaseUrl: z.string().min(1).max(2048).optional(),
+    sitemapEnabled: z.boolean().optional(),
+    organizationJson: organizationJsonSchema.optional(),
+  })
+  .strict()
+  .refine(
+    (v) =>
+      v.siteBaseUrl !== undefined ||
+      v.sitemapEnabled !== undefined ||
+      v.organizationJson !== undefined,
+    "pass at least one of `siteBaseUrl`, `sitemapEnabled`, `organizationJson`",
+  );
+export type SiteSeoProposalInput = z.infer<typeof siteSeoProposalInputSchema>;
+
+/** Result of {@link checkPublicSiteBaseUrl}. */
+export type PublicSiteBaseUrlCheck = { ok: true; url: string } | { ok: false; message: string };
+
+const LOOPBACK_HOST = /^(localhost|.+\.localhost|127(\.\d{1,3}){3}|\[::1\])$/i;
+
+/** Wildcard bind addresses: a server listens on them, no browser can visit them. */
+const WILDCARD_HOST = /^(0\.0\.0\.0|\[::\])$/;
+
+/**
+ * Validate a public site base URL and normalise it to its origin
+ * (`https://example.com`, no trailing slash).
+ *
+ * Every canonical, og:url, JSON-LD url, hreflang target and sitemap entry is
+ * `<base><path>`, so the base must be exactly the origin visitors reach: no
+ * path, query, fragment or credentials. On a cloud install (`provider` is a
+ * `CAELO_PROVIDER` other than self-hosted) it must be https and not a
+ * loopback host — a localhost base there ships unreachable canonicals to
+ * production. A self-hosted install may use `http://localhost:<port>`, the
+ * documented local-dev value; any other host still needs https.
+ *
+ * @param provider - `CAELO_PROVIDER` of the install; `undefined`/`""`/`"self-hosted"` = self-hosted.
+ */
+export function checkPublicSiteBaseUrl(
+  raw: string,
+  provider: string | undefined,
+): PublicSiteBaseUrlCheck {
+  let u: URL;
+  try {
+    u = new URL(raw.trim());
+  } catch {
+    return {
+      ok: false,
+      message: `"${raw}" is not an absolute URL — pass the public origin, e.g. https://www.example.com`,
+    };
+  }
+  const origin = `${u.protocol}//${u.host}`;
+  if (u.username || u.password) {
+    return { ok: false, message: "the site URL must not contain credentials" };
+  }
+  if ((u.pathname !== "/" && u.pathname !== "") || u.search || u.hash) {
+    return {
+      ok: false,
+      message: `the site URL must be the origin only, without path, query or fragment — use ${origin}`,
+    };
+  }
+  if (WILDCARD_HOST.test(u.hostname)) {
+    return {
+      ok: false,
+      message: `${u.hostname} is a bind address, not an address visitors can open — use the public domain (e.g. https://www.example.com) or, on a local self-hosted install, http://localhost:<port>`,
+    };
+  }
+  const selfHosted = !provider || provider === "self-hosted";
+  const loopback = LOOPBACK_HOST.test(u.hostname);
+  if (loopback && !selfHosted) {
+    return {
+      ok: false,
+      message: `${origin} is a local address; on this ${provider} install the site URL must be the public domain visitors use (e.g. https://www.example.com)`,
+    };
+  }
+  if (u.protocol !== "https:" && !(selfHosted && loopback && u.protocol === "http:")) {
+    return {
+      ok: false,
+      message: `the site URL must use https (got ${u.protocol.replace(":", "")}) — use https://${u.host}`,
+    };
+  }
+  return { ok: true, url: origin };
+}
+
 export interface PageSeoRow {
   pageId: string;
   metaDescription: string;
@@ -98,6 +190,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;
@@ -107,12 +203,27 @@ export interface SiteSeoSettings {
 }
 
 /**
- * Resolve the canonical URL for a page. If `pages_seo.canonical_url`
- * is set it wins; otherwise `<siteBaseUrl><pagePath>` — where
- * `pagePath` is the COMPOSED public path from `pages.current_path`
- * (#390: the URL composition point materializes prefixes, slug
- * formats, and the home designation into that one column; canonical
- * simply follows it).
+ * How a deploy target serves pages (`deploy_targets.page_url_style`):
+ * 'directory' emits `<path>/index.html` and serves `/<path>/`;
+ * 'no-extension' emits a bare `<path>` file and serves `/<path>`.
+ */
+export const PAGE_URL_STYLES = ["directory", "no-extension"] as const;
+export type PageUrlStyle = (typeof PAGE_URL_STYLES)[number];
+
+/**
+ * THE public page URL builder (#590). Every absolute page URL Caelo
+ * emits — canonical, og:url, JSON-LD url, sitemap `<loc>`,
+ * hreflang/x-default targets, language-switcher links — comes from
+ * here, so they are byte-identical by construction. Two builders
+ * drifting apart is what shipped `/en/about` as hreflang next to an
+ * `/en/about/` canonical.
+ *
+ * `pages_seo.canonical_url` (`override`) wins when set. Otherwise the
+ * URL is `<scheme>//<host><path>`: the path is the COMPOSED public path
+ * from `pages.current_path` (#390), its trailing slash follows the
+ * serving target's {@link PageUrlStyle}, the host is the URL composition
+ * point's `host` slot (a host-strategy locale) or else the site base
+ * URL's, and the scheme always comes from the base URL.
  */
 export function resolveCanonicalUrl(args: {
   siteBaseUrl: string;
@@ -120,25 +231,33 @@ export function resolveCanonicalUrl(args: {
    *  "/" for the site root. */
   pagePath: string;
   override: string | null;
-  /**
-   * v0.2.85 — page emission style. 'directory' (default) → URLs end
-   * in `/…/`; 'no-extension' → no trailing slash, matching what the
-   * bucket serves when pages are emitted as bare files.
-   */
-  pageUrlStyle?: "directory" | "no-extension";
+  /** The serving deploy target's page emission style. Required — a
+   *  defaulted style is how the preview drifted from the build. */
+  pageUrlStyle: PageUrlStyle;
+  /** Host from the URL composition point's `host` slot (e.g.
+   *  `de.example.com`); null/absent → the site base URL's host. */
+  host?: string | null;
 }): string {
   if (args.override && args.override.length > 0) return args.override;
-  const base = args.siteBaseUrl.endsWith("/") ? args.siteBaseUrl.slice(0, -1) : args.siteBaseUrl;
+  const siteBase = args.siteBaseUrl.endsWith("/")
+    ? args.siteBaseUrl.slice(0, -1)
+    : args.siteBaseUrl;
+  const base = args.host ? `${new URL(siteBase).protocol}//${args.host}` : siteBase;
   const trimmed = trimSlashes(args.pagePath);
   if (trimmed.length === 0) return `${base}/`;
-  const style = args.pageUrlStyle ?? "directory";
-  return style === "no-extension" ? `${base}/${trimmed}` : `${base}/${trimmed}/`;
+  return args.pageUrlStyle === "no-extension" ? `${base}/${trimmed}` : `${base}/${trimmed}/`;
 }
 
 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 +281,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 +293,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 +308,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);
+  });
+});