@caelo-cms/shared 0.10.51 → 0.10.53

package/src/markup-structure.ts

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #820 — structural fingerprints of HTML, for telling "this markup is
+ * a reusable pattern that already exists elsewhere" from one-off content.
+ *
+ * Free HTML (a step chain, a comparison table, a timeline pasted into a
+ * richtext value, or minted as a one-off module per page) is cheap to
+ * write and expensive to keep: every copy is edited separately, the copies
+ * drift, and the pattern's CSS has to live in the layout where it ships on
+ * every page. The fix is to make the second copy a module. This file gives
+ * the write-time guard and the core `structure` quality check one shared
+ * notion of "the same markup":
+ *
+ * - A node's SIGNATURE is its tag plus sorted class tokens plus the
+ *   signatures of its distinct children (first-occurrence order). Text,
+ *   attribute values and repetition are ignored, so a 5-step chain and a
+ *   7-step chain with different copy are the same pattern.
+ * - A subtree QUALIFIES as a pattern when it is big enough to be a
+ *   component (MIN_PATTERN_NODES distinct nodes over MIN_PATTERN_DEPTH
+ *   levels) and carries at least one class. Prose converted from Markdown
+ *   (`<ul><li><a>`, plain tables) has no classes and never qualifies; an
+ *   authored component always has them.
+ * - SIMILARITY is the Jaccard index over parent→child edges, for near
+ *   matches that are not exact (a pattern with one extra element).
+ *
+ * The site importer's boilerplate walker (site-importer/boilerplate.ts)
+ * stays separate on purpose: it streams byte ranges, hashes text into a
+ * content signature, and its signatures are persisted and replayed
+ * (#424), so its output must stay byte-stable.
+ *
+ * Every walk is bounded (MAX_NODES) so an adversarial body cannot blow it up.
+ */
+
+import { Parser } from "htmlparser2";
+
+/** One element of parsed markup. Text is dropped; it never matters here. */
+export interface MarkupNode {
+  readonly tag: string;
+  readonly classes: readonly string[];
+  /** The `data-caelo-module-id` the composer stamps on every module root. */
+  readonly moduleId: string | null;
+  readonly children: MarkupNode[];
+  readonly parent: MarkupNode | null;
+}
+
+/** Most elements one parse keeps; the rest of the document is ignored. */
+export const MAX_NODES = 50_000;
+/** A pattern has at least this many distinct nodes… */
+export const MIN_PATTERN_NODES = 4;
+/** …spread over at least this many levels (root, child, grandchild). */
+export const MIN_PATTERN_DEPTH = 3;
+/** Jaccard similarity at or above which two patterns are "near" matches. */
+export const NEAR_MATCH_THRESHOLD = 0.8;
+
+/** Elements whose inside is not markup structure (icons, raw text). */
+const LEAF_TAGS = new Set(["svg", "math", "script", "style", "noscript", "iframe"]);
+
+/** Parse markup into a forest of element nodes. */
+export function parseMarkup(html: string): MarkupNode[] {
+  const roots: MarkupNode[] = [];
+  const stack: (MarkupNode | null)[] = [];
+  let count = 0;
+  let leafDepth = 0;
+  const parser = new Parser(
+    {
+      onopentag(name, attribs) {
+        if (leafDepth > 0 || count >= MAX_NODES) {
+          stack.push(null);
+          if (leafDepth > 0) leafDepth++;
+          return;
+        }
+        const tag = name.toLowerCase();
+        const parent = findOpen(stack);
+        const node: MarkupNode = {
+          tag,
+          classes: splitClasses(attribs.class),
+          moduleId: attribs["data-caelo-module-id"] ?? null,
+          children: [],
+          parent,
+        };
+        count++;
+        if (parent) parent.children.push(node);
+        else roots.push(node);
+        stack.push(node);
+        if (LEAF_TAGS.has(tag)) leafDepth = 1;
+      },
+      onclosetag() {
+        stack.pop();
+        if (leafDepth > 0) leafDepth--;
+      },
+    },
+    { decodeEntities: true, lowerCaseTags: true },
+  );
+  parser.write(html);
+  parser.end();
+  return roots;
+}
+
+function findOpen(stack: readonly (MarkupNode | null)[]): MarkupNode | null {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const n = stack[i];
+    if (n) return n;
+  }
+  return null;
+}
+
+function splitClasses(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return [...new Set(raw.split(/\s+/).filter((c) => c.length > 0))].sort();
+}
+
+/**
+ * Remove Mustache tags (`{{x}}`, `{{{x}}}`, `{{#s}}`, `{{/s}}`, `{{>p}}`)
+ * from a module template so it parses as the markup it renders: a section
+ * body stays once, a placeholder becomes empty.
+ */
+export function stripMustache(template: string): string {
+  return stripDelimited(stripDelimited(template, 3), 2);
+}
+
+/**
+ * Removes every `{`×n + non-`}` run + `}`×n span, leftmost first — the
+ * same result as `replace(/\{{n}[^}]*\}{n}/g, "")`, in linear time. The
+ * regex form backtracks quadratically on long `{{{{…` runs in module HTML
+ * (CodeQL js/polynomial-redos); here, when the first `}` after an opener
+ * does not start the closer, no opener before that `}` can match either
+ * (they all hit the same `}`), so the scan resumes there.
+ */
+function stripDelimited(text: string, n: number): string {
+  const opener = "{".repeat(n);
+  const closer = "}".repeat(n);
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const open = text.indexOf(opener, i);
+    if (open < 0) break;
+    const brace = text.indexOf("}", open + n);
+    if (brace < 0) break;
+    if (text.startsWith(closer, brace)) {
+      out += text.slice(i, open);
+      i = brace + n;
+    } else {
+      out += text.slice(i, brace);
+      i = brace;
+    }
+  }
+  return out + text.slice(i);
+}
+
+/** The node's key without its children: `div.card.card--wide`. */
+export function nodeKey(n: Pick<MarkupNode, "tag" | "classes">): string {
+  return n.classes.length === 0 ? n.tag : `${n.tag}.${n.classes.join(".")}`;
+}
+
+/** Structural facts about one subtree. */
+export interface SubtreeShape {
+  /** Repetition- and text-independent structural signature. */
+  readonly signature: string;
+  /** Distinct nodes after repetition collapse. */
+  readonly nodeCount: number;
+  /** Levels, the subtree root counting as 1. */
+  readonly depth: number;
+  /** Whether any node in it carries a class. */
+  readonly hasClass: boolean;
+  /** Parent→child edges, for near-match similarity. */
+  readonly edges: ReadonlySet<string>;
+}
+
+/**
+ * Compute the shapes of a subtree and all its descendants in one pass.
+ * Nested module roots are opaque: their own module owns them.
+ */
+export function shapeTree(root: MarkupNode, out = new Map<MarkupNode, SubtreeShape>()) {
+  const visit = (n: MarkupNode): SubtreeShape => {
+    const seen = new Set<string>();
+    const parts: string[] = [];
+    let nodeCount = 1;
+    let depth = 1;
+    let hasClass = n.classes.length > 0;
+    const edges = new Set<string>();
+    const key = nodeKey(n);
+    for (const c of n.children) {
+      if (c.moduleId !== null) continue;
+      const s = visit(c);
+      if (seen.has(s.signature)) continue;
+      seen.add(s.signature);
+      parts.push(s.signature);
+      nodeCount += s.nodeCount;
+      depth = Math.max(depth, s.depth + 1);
+      hasClass ||= s.hasClass;
+      edges.add(`${key}>${nodeKey(c)}`);
+      for (const e of s.edges) edges.add(e);
+    }
+    const shape: SubtreeShape = {
+      signature: parts.length === 0 ? key : `${key}(${parts.join(",")})`,
+      nodeCount,
+      depth,
+      hasClass,
+      edges,
+    };
+    out.set(n, shape);
+    return shape;
+  };
+  visit(root);
+  return out;
+}
+
+/** Whether a subtree is big and specific enough to count as a pattern. */
+export function isPattern(shape: SubtreeShape): boolean {
+  return shape.hasClass && shape.nodeCount >= MIN_PATTERN_NODES && shape.depth >= MIN_PATTERN_DEPTH;
+}
+
+/** Jaccard similarity of two shapes' edge sets, 0…1. */
+export function shapeSimilarity(a: SubtreeShape, b: SubtreeShape): number {
+  if (a.signature === b.signature) return 1;
+  let shared = 0;
+  for (const e of a.edges) if (b.edges.has(e)) shared++;
+  const union = a.edges.size + b.edges.size - shared;
+  return union === 0 ? 0 : shared / union;
+}
+
+/** A qualifying pattern found in a piece of markup. */
+export interface FoundPattern {
+  readonly node: MarkupNode;
+  readonly shape: SubtreeShape;
+}
+
+/**
+ * The outermost qualifying patterns in a forest: a pattern inside a bigger
+ * pattern is part of it and not reported on its own.
+ */
+export function outermostPatterns(roots: readonly MarkupNode[]): FoundPattern[] {
+  const found: FoundPattern[] = [];
+  const walk = (n: MarkupNode, shapes: Map<MarkupNode, SubtreeShape>) => {
+    const shape = shapes.get(n);
+    if (shape && isPattern(shape)) {
+      found.push({ node: n, shape });
+      return;
+    }
+    for (const c of n.children) if (c.moduleId === null) walk(c, shapes);
+  };
+  for (const r of roots) walk(r, shapeTree(r));
+  return found;
+}
+
+/** The shape of a whole module template (its first element), or null. */
+export function templateShape(templateHtml: string): SubtreeShape | null {
+  const root = parseMarkup(stripMustache(templateHtml))[0];
+  return root ? (shapeTree(root).get(root) ?? null) : null;
+}
+
+/**
+ * The parts of a rendered module that did NOT come from its template: the
+ * markup field values injected (richtext, text). The rendered tree is
+ * walked in step with the template tree; a rendered child that no template
+ * child can account for (same tag, template's classes all present) starts
+ * a free region. List sections still match, because every iteration of a
+ * section renders the same template child.
+ *
+ * @returns the free region roots, or null when the rendered root does not
+ * match the template root at all (a module the composer renders from
+ * other data, such as a navigation menu) — nothing can be attributed then.
+ */
+export function freeRegions(
+  rendered: MarkupNode,
+  templateRoots: readonly MarkupNode[],
+): MarkupNode[] | null {
+  const tRoot = templateRoots[0];
+  if (!tRoot || !accounts(tRoot, rendered)) return null;
+  const free: MarkupNode[] = [];
+  const walk = (r: MarkupNode, t: MarkupNode) => {
+    for (const c of r.children) {
+      if (c.moduleId !== null) continue;
+      const match = t.children.find((tc) => accounts(tc, c));
+      if (match) walk(c, match);
+      else free.push(c);
+    }
+  };
+  walk(rendered, tRoot);
+  return free;
+}
+
+function accounts(template: MarkupNode, rendered: MarkupNode): boolean {
+  return (
+    template.tag === rendered.tag && template.classes.every((k) => rendered.classes.includes(k))
+  );
+}
+
+/** Every module root (`data-caelo-module-id`) in a forest, nested ones included. */
+export function moduleRoots(roots: readonly MarkupNode[]): MarkupNode[] {
+  const out: MarkupNode[] = [];
+  const walk = (n: MarkupNode) => {
+    if (n.moduleId !== null) out.push(n);
+    for (const c of n.children) walk(c);
+  };
+  for (const r of roots) walk(r);
+  return out;
+}
+
+/** A short operator-readable name for a pattern: its root key, e.g. `div.chain`. */
+export function patternLabel(p: Pick<MarkupNode, "tag" | "classes">): string {
+  return nodeKey(p);
+}

package/src/media.ts

@@ -123,6 +123,49 @@ export function buildMediaUrl(slug: string, variant: MediaVariantTag | string):
     : `${MEDIA_URL_PREFIX}/${slug}/${variant}`;
 }
 
+/**
+ * The favicon rendition of a raster image bound to the theme's favicon
+ * slot: a square PNG, `FAVICON_VARIANT_PX` on each side. Browsers show a
+ * favicon at 16-32 CSS px (64 covers 2x screens). The `orig` of a raster
+ * favicon is often an AI-generated 1024 px PNG of 1-2 MB, and the browser
+ * fetches the `<link rel="icon">` while the page loads: under Lighthouse's
+ * throttled network that download pushed LCP from 0.9 s to 4.7 s on an
+ * otherwise perfect page (real-AI run 39038927234). Created when the
+ * favicon is bound (`themes.set_asset`), not on every upload.
+ */
+export const FAVICON_VARIANT = "icon-64";
+
+/** Edge length in px of {@link FAVICON_VARIANT}. */
+export const FAVICON_VARIANT_PX = 64;
+
+/** Raster mimes: the ones the image pipeline decodes (sharp) and resizes. */
+const RASTER_IMAGE_MIMES: ReadonlySet<string> = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/avif",
+  "image/gif",
+]);
+
+/** Whether `mime` is a raster image the pipeline can decode and resize. */
+export function isRasterImageMime(mime: string): boolean {
+  return RASTER_IMAGE_MIMES.has(mime);
+}
+
+/**
+ * The URL + content type the `<link rel="icon">` of a bound favicon uses.
+ * A raster favicon ships its {@link FAVICON_VARIANT} PNG; ICO and SVG are
+ * favicon formats already and ship as uploaded (`orig`).
+ */
+export function themeFaviconRendition(
+  slug: string,
+  mime: string,
+): { readonly url: string; readonly mime: string } {
+  return isRasterImageMime(mime)
+    ? { url: buildMediaUrl(slug, FAVICON_VARIANT), mime: "image/png" }
+    : { url: buildMediaUrl(slug, "orig"), mime };
+}
+
 /**
  * Turn a human/asset label into a URL-safe media slug: lowercase ascii,
  * kebab-case, extension + junk stripped, capped at 60 chars. NOT

package/src/preview-compose.ts

@@ -108,9 +108,10 @@ 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.
+   * Content type of the bytes the URL serves: `media_assets.mime` for the
+   * `orig` URL, `image/png` for a raster favicon's rendition (see
+   * `themeFaviconRendition`). Carried so `<head>` metadata that declares
+   * a type (`<link rel="icon" type=…>`) states the real one.
    */
   readonly mime: string;
 }
@@ -239,7 +240,8 @@ export function fontsHeadFragment(fonts: ComposeFonts | undefined): string | nul
  * 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
+ * (`/_caelo/media/<slug>/icon-64` for a raster favicon, the `orig` URL
+ * for ICO/SVG — see `themeFaviconRendition`); the static generator's media pass rewrites
  * it to the published `/_assets/<slug>.<hash>.<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

package/src/publish-live-parity.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #834 / #835 — the wording Publish live's parity refusal shares between
+ * the server that writes it (admin-core `build-parity.ts`) and the Live
+ * edit toolbar that renders it. The toolbar truncates long errors, so it
+ * recognises a parity refusal by its prefix and shows the next step
+ * ("Stage again") as its own, untruncated hint next to the button.
+ */
+
+/** Every parity refusal starts with this. */
+export const PARITY_REFUSAL_PREFIX = "Publish live stopped:";
+
+/**
+ * The next step every parity refusal ends with. Operators use the
+ * toolbar's "Stage again" button next to Publish live; the AI re-stages
+ * with its tools.
+ */
+export const RESTAGE_NEXT_STEP =
+  'Next step: Stage again (the "Stage again" button next to Publish live, or stage_changes / deploy_staging in chat), check staging, then Publish live.';
+
+/** True when `message` is a Publish-live parity refusal. */
+export function isParityRefusal(message: string): boolean {
+  return message.startsWith(PARITY_REFUSAL_PREFIX);
+}

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

@@ -1,15 +1,20 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { CONTENT_HASHED_PATH_PATTERN, isContentHashedPath } from "./static-cache-policy.js";
+import {
+  CONTENT_HASHED_PATH_PATTERN,
+  isContentHashedPath,
+  isPinnedFontSliceFile,
+} 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)}.latin.0123456789ab.woff2`,
-  `/_assets/fonts/pinned/${"0".repeat(64)}.cyrillic-ext.0123456789ab.woff2`,
+  // #793 — `<source sha256>.<axis-spec hash>.<slice>.<toolchain tag>.woff2`.
+  `/_assets/fonts/pinned/${"a".repeat(64)}.de5786ef1b56.latin.0123456789ab.woff2`,
+  `/_assets/fonts/pinned/${"0".repeat(64)}.1f23e5fa3b6d.cyrillic-ext.0123456789ab.woff2`,
   "/_caelo/plugin/consent-manager/runtime.0123456789ab.js",
   "/_caelo/plugin/consent-manager/banner.abcdef012345.css",
   "/_app/immutable/chunks/abc.js",
@@ -44,6 +49,8 @@ const STABLE_PATHS = [
   // appear, it must not be pinned in caches for a year.
   `/_assets/fonts/pinned/${"0".repeat(64)}.ttf`,
   `/_assets/fonts/pinned/${"a".repeat(64)}.latin.woff2`,
+  // Pre-#793 slice name (no axis-spec hash) — no longer emitted.
+  `/_assets/fonts/pinned/${"a".repeat(64)}.latin.0123456789ab.woff2`,
   "/_assets/fonts/inter/not-a-hash.woff2",
   "/_assets/fonts/inter/29ede7bd4be32ab0.woff2.html",
   "/_caelo/plugin/consent-manager/runtime.js",
@@ -77,3 +84,26 @@ describe("isContentHashedPath", () => {
     expect(CONTENT_HASHED_PATH_PATTERN.endsWith("$")).toBe(true);
   });
 });
+
+describe("isPinnedFontSliceFile", () => {
+  it("accepts the slice name the delivery emits (e2e-livedit run 38915969785)", () => {
+    expect(
+      isPinnedFontSliceFile(
+        "29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031.de5786ef1b56.latin.3075c73f4eb5.woff2",
+      ),
+    ).toBe(true);
+    expect(
+      isPinnedFontSliceFile(`${"b".repeat(64)}.0123456789ab.latin-ext.0123456789ab.woff2`),
+    ).toBe(true);
+  });
+
+  it("rejects the pre-#793 shape, other extensions and path segments", () => {
+    expect(isPinnedFontSliceFile(`${"b".repeat(64)}.latin.0123456789ab.woff2`)).toBe(false);
+    expect(isPinnedFontSliceFile(`${"b".repeat(64)}.0123456789ab.latin.0123456789ab.ttf`)).toBe(
+      false,
+    );
+    expect(
+      isPinnedFontSliceFile(`../${"b".repeat(64)}.0123456789ab.latin.0123456789ab.woff2`),
+    ).toBe(false);
+  });
+});

package/src/static-cache-policy.ts

@@ -17,12 +17,13 @@
  *     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>.<slice>.<12 hex>.woff2` — WOFF2
- *     unicode-range slices derived from a registry font: the sha256 of
- *     the pinned source plus the delivery-toolchain tag
- *     (`font-service/src/delivery.ts`), which together determine the
- *     bytes. (The sibling `pinned/<font-id>.license.txt` is id-named,
- *     NOT hashed.)
+ *   - `_assets/fonts/pinned/<sha256>.<12 hex>.<slice>.<12 hex>.woff2` —
+ *     WOFF2 unicode-range slices derived from a registry font: the sha256
+ *     of the pinned source, the hash of the effective axis spec (#793)
+ *     and the delivery-toolchain tag (`font-service/src/delivery.ts`),
+ *     which together determine the bytes. The file-name shape is
+ *     {@link PINNED_FONT_SLICE_FILE_PATTERN}. (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`).
@@ -41,6 +42,26 @@
  * by font id) and media under the pre-#667 bare-slug names.
  */
 
+/**
+ * Regex (source string, unanchored) for the file name of a pinned-font
+ * slice: `<source sha256>.<axis-spec hash 12>.<slice>.<toolchain tag 12>.woff2`
+ * (`apps/static-generator/src/pinned-font-delivery.ts` builds it). The
+ * ONE definition every consumer derives from — the cache policy below
+ * and the admin's preview font route. #793 added the axis-spec hash to
+ * the name; the route and this policy each kept their own copy of the
+ * old shape, so the editor preview 404'd every pinned font and the
+ * published slices lost their immutable cache lifetime. RE2-compatible.
+ */
+export const PINNED_FONT_SLICE_FILE_PATTERN =
+  "[0-9a-f]{64}\\.[0-9a-f]{12}\\.[a-z]+(?:-[a-z]+)?\\.[0-9a-f]{12}\\.woff2";
+
+const PINNED_FONT_SLICE_FILE_RE = new RegExp(`^${PINNED_FONT_SLICE_FILE_PATTERN}$`);
+
+/** True when `fileName` (no directory) is a pinned-font slice name. */
+export function isPinnedFontSliceFile(fileName: string): boolean {
+  return PINNED_FONT_SLICE_FILE_RE.test(fileName);
+}
+
 /** Long-lived policy for content-addressed files. */
 export const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 
@@ -54,8 +75,7 @@ export const HTML_CACHE_CONTROL = "public, max-age=60, stale-while-revalidate=86
  * 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}\\.woff2|_assets/fonts/pinned/[0-9a-f]{64}\\.[a-z]+(?:-[a-z]+)?\\.[0-9a-f]{12}\\.woff2|_assets/[a-z0-9][a-z0-9-]*(?:/[a-z][a-z0-9-]*)?\\.[0-9a-f]{16}\\.[a-z0-9]{2,5}|_caelo/plugin/[^/]+/[^/]+\\.[0-9a-f]{12}\\.(?:js|css))$";
+export const CONTENT_HASHED_PATH_PATTERN = `^/(?:_app/immutable/.+|_assets/fonts/[^/]+/[0-9a-f]{16}\\.woff2|_assets/fonts/pinned/${PINNED_FONT_SLICE_FILE_PATTERN}|_assets/[a-z0-9][a-z0-9-]*(?:/[a-z][a-z0-9-]*)?\\.[0-9a-f]{16}\\.[a-z0-9]{2,5}|_caelo/plugin/[^/]+/[^/]+\\.[0-9a-f]{12}\\.(?:js|css))$`;
 
 /** Hex length of the content hash in published media names (#667). */
 export const MEDIA_CONTENT_HASH_HEX_LENGTH = 16;

package/src/themes.ts

@@ -23,6 +23,7 @@
  */
 
 import { z } from "zod";
+import { FONT_AXES_EXTENSION } from "./font-axis-policy.js";
 import { isUnsafeKey } from "./safe-keys.js";
 import { UnknownTokenName } from "./themes-errors.js";
 
@@ -788,8 +789,12 @@ export function applyDtcgWrites(
       nextValue &&
       typeof nextValue === "object" &&
       (nextValue as { fontFamily?: string }).fontFamily !== oldValue?.fontFamily
-    )
+    ) {
+      // A new family unbinds the pinned face, and with it the face's axis
+      // override: it was validated against the old face's axes.
       delete extensions["caelo.font"];
+      delete extensions[FONT_AXES_EXTENSION];
+    }
     setLeafAtPath(out, path, {
       ...(Object.keys(extensions).length ? { $extensions: extensions } : {}),
       $value: nextValue,

package/src/version.ts

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