@diviops/mcp-server 1.5.11 → 1.5.12

package/dist/preset-cli/cli.js

@@ -23,8 +23,9 @@
  *   4  write / network error
  */
 import { emitButtonGroupPreset, buildPresetCreateBody, } from "./button-emitter.js";
+import { emitHeadingFontGroupPreset, buildHeadingFontPresetCreateBody, UnsupportedVariantCombinationError, } from "./heading-font-emitter.js";
 import { EvidenceGateError } from "./registry.js";
-import { applyButtonPreset, buildClientFromEnv, CredentialsMissingError, CapabilityMissingError, } from "./write-path.js";
+import { applyButtonPreset, applyHeadingFontPreset, buildClientFromEnv, CredentialsMissingError, CapabilityMissingError, } from "./write-path.js";
 export const EXIT = {
     OK: 0,
     INVALID_INPUT: 1,
@@ -39,8 +40,10 @@ const realIO = {
 const HELP = `diviops-preset — Divi 5.5.x canonical preset-emitter CLI
 
 USAGE
-  diviops-preset button [options]   Emit a divi/button group preset
-  diviops-preset --help             Show this help
+  diviops-preset button [options]         Emit a divi/button group preset
+  diviops-preset heading-font [options]   Emit a divi/font group preset for
+                                          divi/heading
+  diviops-preset --help                   Show this help
 
 MODE
   --dry-run            Compose + print canonical JSON only (DEFAULT).
@@ -72,6 +75,30 @@ button OPTIONS (all styling fields optional; emit-on-specification only)
                            .value.padding.top="0px" (hover-padding-gate
                            workaround). Off by default.
 
+heading-font OPTIONS (all styling fields optional; emit-on-specification only)
+  --name <string>          Preset display name (required).
+  --pattern <google|local> Required. Selects the verified variant:
+                             google — Pattern A: plain family + explicit
+                                      numeric weight (e.g. family "Inter",
+                                      weight "700"). Verified against
+                                      round-1a fixture.
+                             local  — Pattern B: weight-encoded family
+                                      string (e.g. family "Sora 700") with
+                                      NO --font-weight. Used for local-
+                                      hosted/EU-GDPR font flows. Verified
+                                      against round-1b fixture.
+                           Pattern A and Pattern B are distinct registry
+                           variants — there is NO default; omitting
+                           --pattern is invalid input.
+  --font-family <string>   Font family. Pattern A: plain name ("Inter").
+                           Pattern B: weight-encoded ("Sora 700").
+  --font-weight <string>   Font weight (e.g. "700"). Pattern A only —
+                           passing it with --pattern local is refused.
+  --font-color <value>     Font color. Hex literal, bare gcid-*/gvid-*
+                           token, or already-formed $variable(...)$ token.
+  --font-size <v>          Font size (e.g. "48px").
+  --font-line-height <v>   Font line-height (e.g. "1.1").
+
 EXIT CODES
   0 success   1 invalid input   2 evidence-gate refusal
   3 capability missing   4 write error
@@ -82,6 +109,14 @@ EXAMPLES
     --font-family Inter --font-weight 600 --font-color gcid-body-color
 
   diviops-preset button --name "Primary" --bg-color "#2563eb" --apply
+
+  diviops-preset heading-font --name "Heading H1" --pattern google \\
+    --font-family Inter --font-weight 700 \\
+    --font-color gcid-heading-color --font-size 48px
+
+  diviops-preset heading-font --name "Heading H1 (local)" --pattern local \\
+    --font-family "Sora 700" \\
+    --font-color gcid-heading-color --font-size 48px
 `;
 const VALUE_FLAGS = new Set([
     "--name",
@@ -100,6 +135,8 @@ const VALUE_FLAGS = new Set([
     "--font-weight",
     "--font-color",
     "--font-size",
+    "--font-line-height",
+    "--pattern",
 ]);
 /** Parse argv (after `node script`) into a structured shape. Throws on unknown flags. */
 export function parseArgs(argv) {
@@ -163,6 +200,8 @@ export class UsageError extends Error {
         this.name = "UsageError";
     }
 }
+/** Known CLI commands. The CLI rejects anything else with EXIT.INVALID_INPUT. */
+const KNOWN_COMMANDS = new Set(["button", "heading-font"]);
 /** Map parsed `button` options into the emitter input shape. */
 export function buildButtonInput(parsed) {
     const opt = (k) => {
@@ -244,6 +283,47 @@ export function buildButtonInput(parsed) {
     }
     return input;
 }
+/** Map parsed `heading-font` options into the heading-font emitter input shape. */
+export function buildHeadingFontInput(parsed) {
+    const opt = (k) => {
+        const v = parsed.options.get(k);
+        return typeof v === "string" ? v : undefined;
+    };
+    const name = opt("--name");
+    if (!name) {
+        throw new UsageError("heading-font command requires --name <string>.");
+    }
+    // --pattern is REQUIRED — Pattern A vs Pattern B are distinct registry/
+    // evidence variants and there is no safe default. An omitted --pattern
+    // is invalid input; the CLI fails BEFORE emission (no guessing).
+    const patternRaw = opt("--pattern");
+    if (patternRaw === undefined) {
+        throw new UsageError("heading-font command requires --pattern <google|local>. " +
+            "There is no default — Pattern A (google) and Pattern B (local) are distinct " +
+            "registry variants and must be selected intentionally.");
+    }
+    if (patternRaw !== "google" && patternRaw !== "local") {
+        throw new UsageError(`--pattern must be "google" or "local"; got ${JSON.stringify(patternRaw)}.`);
+    }
+    const pattern = patternRaw;
+    const input = { name, pattern };
+    const family = opt("--font-family");
+    if (family !== undefined)
+        input.family = family;
+    const weight = opt("--font-weight");
+    if (weight !== undefined)
+        input.weight = weight;
+    const color = opt("--font-color");
+    if (color !== undefined)
+        input.color = color;
+    const size = opt("--font-size");
+    if (size !== undefined)
+        input.size = size;
+    const lineHeight = opt("--font-line-height");
+    if (lineHeight !== undefined)
+        input.lineHeight = lineHeight;
+    return input;
+}
 /**
  * Run the CLI. Returns the structured exit code (does NOT call
  * `process.exit` — the thin bin wrapper does). `io` is injectable so
@@ -264,17 +344,34 @@ export async function run(argv, io = realIO, serverVersion) {
         io.out(HELP);
         return EXIT.OK;
     }
-    if (parsed.command !== "button") {
+    if (parsed.command === null || !KNOWN_COMMANDS.has(parsed.command)) {
         io.err(`Unknown command: ${parsed.command ?? "(none)"}. ` +
-            `Track 4 ships one command: "button".`);
+            `Known commands: ${[...KNOWN_COMMANDS].sort().join(", ")}.`);
         io.err("Run `diviops-preset --help` for usage.");
         return EXIT.INVALID_INPUT;
     }
     // --- compose + gate -------------------------------------------------
-    let entry;
+    // Per-command branch produces:
+    //  - `dryRunBody`: the canonical JSON to print in --dry-run mode.
+    //  - `applyFn`: a closure that issues the apply-mode write when the
+    //    capability check passes. Both branches reuse the existing write-
+    //    path plumbing (`assertStorageCapability` → `/preset/create`).
+    let dryRunBody;
+    let applyFn;
     try {
-        const input = buildButtonInput(parsed);
-        entry = emitButtonGroupPreset(input);
+        if (parsed.command === "button") {
+            const input = buildButtonInput(parsed);
+            const entry = emitButtonGroupPreset(input);
+            dryRunBody = buildPresetCreateBody(entry, { dry_run: true });
+            applyFn = (client, sv) => applyButtonPreset(client, entry, { serverVersion: sv });
+        }
+        else {
+            // heading-font
+            const input = buildHeadingFontInput(parsed);
+            const entry = emitHeadingFontGroupPreset(input);
+            dryRunBody = buildHeadingFontPresetCreateBody(entry, { dry_run: true });
+            applyFn = (client, sv) => applyHeadingFontPreset(client, entry, { serverVersion: sv });
+        }
     }
     catch (err) {
         if (err instanceof EvidenceGateError) {
@@ -286,13 +383,19 @@ export async function run(argv, io = realIO, serverVersion) {
             io.err("Run `diviops-preset --help` for usage.");
             return EXIT.INVALID_INPUT;
         }
+        if (err instanceof UnsupportedVariantCombinationError) {
+            // Distinct from EvidenceGateError: the registry IS complete for the
+            // verified variants, but the caller asked for a combination outside
+            // any verified variant. Surfaces as invalid input (exit 1).
+            io.err(err.message);
+            return EXIT.INVALID_INPUT;
+        }
         io.err(err instanceof Error ? err.message : String(err));
         return EXIT.INVALID_INPUT;
     }
     // --- dry-run --------------------------------------------------------
     if (parsed.dryRun) {
-        const body = buildPresetCreateBody(entry, { dry_run: true });
-        io.out(JSON.stringify(body, null, 2));
+        io.out(JSON.stringify(dryRunBody, null, 2));
         return EXIT.OK;
     }
     // --- apply ----------------------------------------------------------
@@ -307,7 +410,7 @@ export async function run(argv, io = realIO, serverVersion) {
                 "This is an internal error — invoke via the `diviops-preset` bin.");
             return EXIT.WRITE_ERROR;
         }
-        const result = await applyButtonPreset(client, entry, { serverVersion });
+        const result = await applyFn(client, serverVersion);
         io.out(JSON.stringify(result, null, 2));
         return EXIT.OK;
     }

package/dist/preset-cli/heading-font-emitter.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `divi/font` heading group-preset emitter — Track 5 vertical slice.
+ *
+ * Emits a byte-canonical Divi 5.5.x `type: "group"` `divi/font` preset
+ * targeting `divi/heading` at `attrs.title.decoration.font.font.desktop.value.*`,
+ * gated by the verified-attrs registry. Canonical shape:
+ * `docs/verification/canonical-preset-shapes-per-module-type-2026-05-18.md`
+ * (`divi/font` section), cross-checked against
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-18/round-1a-heading-h1-pattern-a-google.json`
+ * and `…/round-1b-heading-h1-pattern-b-local.json`.
+ *
+ * Two verified Pattern variants live in the registry — they are NOT
+ * interchangeable evidence. The caller MUST select one explicitly:
+ *
+ *  - Pattern A (Google Fonts CDN): plain family + explicit numeric weight.
+ *    Registry entry: `divi/font` with `pattern_variant: "google_fonts_pattern_a"`.
+ *    Verified evidence: round-1a fixture.
+ *  - Pattern B (local-hosted, EU-GDPR): weight encoded into the family
+ *    string ("Sora 700") and NO `weight` key at all in the preset.
+ *    Registry entry: `divi/font` with `pattern_variant: "local_hosted_pattern_b"`.
+ *    Verified evidence: round-1b fixture.
+ *
+ * Shape rules enforced here:
+ *  - Emit-on-specification only — omitted params produce NO keys.
+ *  - `attrs == styleAttrs == renderAttrs` at the route layer (the plugin's
+ *    `/preset/create` route mirrors `attrs` into all three buckets to match
+ *    VB save semantics); the CLI request body only carries `attrs`.
+ *  - Double-font nesting: `title.decoration.font.font.desktop.value.*` —
+ *    outer `font` is the decoration category, inner `font` is the attr
+ *    name within that category.
+ *  - Pattern B with an explicit `weight` is REFUSED — the verified Pattern
+ *    B capture has no `weight` key and there is no registry entry
+ *    authorizing local-hosted-with-explicit-weight.
+ */
+import { type VerifiedAttrsRegistry } from "./registry.js";
+export declare const HEADING_FONT_MODULE = "divi/heading";
+export declare const HEADING_FONT_GROUP_NAME = "divi/font";
+export declare const HEADING_FONT_GROUP_ID = "designTitleText";
+export declare const HEADING_FONT_PATTERN_FAMILY = "divi/font";
+/** The two verified pattern variants for `divi/font` on `divi/heading`. */
+export declare const HEADING_FONT_PATTERN_VARIANTS: {
+    readonly google: "google_fonts_pattern_a";
+    readonly local: "local_hosted_pattern_b";
+};
+export type HeadingFontPattern = "google" | "local";
+export interface HeadingFontEmitterInput {
+    /** Required display name for the preset. */
+    name: string;
+    /**
+     * Required pattern selector. There is no default — Pattern A and
+     * Pattern B are distinct registry/evidence variants and the caller
+     * must select intentionally.
+     */
+    pattern: HeadingFontPattern;
+    /**
+     * Font family.
+     *  - Pattern A (google): plain family name, e.g. `"Inter"`.
+     *  - Pattern B (local):  weight-encoded family name, e.g. `"Sora 700"`.
+     */
+    family?: string;
+    /**
+     * Font weight (numeric-string, e.g. `"700"`).
+     *  - Pattern A: optional; emitted when specified.
+     *  - Pattern B: PROHIBITED — passing a weight in `local` mode is a
+     *    usage error (the verified Pattern B shape has no `weight` key,
+     *    and there is no registry entry vouching for that combination).
+     */
+    weight?: string;
+    /** Font color — literal hex or bare/formed variable token. */
+    color?: string;
+    /** Font size — literal (e.g. `"48px"`) or already-formed `$variable(...)$`. */
+    size?: string;
+    /** Line height — optional, emit-on-specification only. */
+    lineHeight?: string;
+}
+/** The composed canonical preset entry shape sent to `/preset/create`. */
+export interface HeadingFontPresetEntry {
+    type: "group";
+    module_name: string;
+    group_name: string;
+    group_id: string;
+    pattern_variant: string;
+    name: string;
+    attrs: Record<string, unknown>;
+}
+/**
+ * Raised when the caller passes a combination the registry does not
+ * authorize for the current Track — distinct from `EvidenceGateError`
+ * (registry-evidence shortfall) and `UsageError` (CLI arg parse).
+ */
+export declare class UnsupportedVariantCombinationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Compose the canonical `attrs.title.decoration.font.font.desktop.value`
+ * bag from the input. Emit-on-specification: only specified sub-fields
+ * produce keys.
+ */
+export declare function composeHeadingFontAttrs(input: HeadingFontEmitterInput): Record<string, unknown>;
+/**
+ * Emit a canonical `divi/font` heading group preset.
+ *
+ * 1. Validate input shape (name, pattern, Pattern B + weight refusal).
+ * 2. Compose `attrs.title.decoration.font.font.desktop.value.*`
+ *    (emit-on-specification).
+ * 3. Gate the chosen `(divi/font, pattern_variant)` cell on `divi/heading`
+ *    against the verified-attrs registry — throws `EvidenceGateError`
+ *    when effective evidence is below `VB_PRESET_STORAGE_VERIFIED`.
+ *
+ * `styleAttrs` and `renderAttrs` are intentionally NOT part of this
+ * entry: the plugin's `/preset/create` route mirrors the single `attrs`
+ * bag into all three buckets, writing `attrs == styleAttrs == renderAttrs`
+ * to match VB save semantics — see `trait-preset.php` `preset_create`.
+ * The Round 1a/1b fixtures capture the post-write storage shape.
+ */
+export declare function emitHeadingFontGroupPreset(input: HeadingFontEmitterInput, registry?: VerifiedAttrsRegistry): HeadingFontPresetEntry;
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a heading
+ * font preset entry. Matches the body shape the `diviops_preset_create`
+ * MCP tool posts — the CLI reuses the existing route, it does not add one.
+ *
+ * `pattern_variant` is informational metadata on the in-memory entry and
+ * is NOT sent over the wire — the registry-gate decision happens
+ * client-side before the write.
+ */
+export declare function buildHeadingFontPresetCreateBody(entry: HeadingFontPresetEntry, opts?: {
+    dry_run?: boolean;
+}): Record<string, unknown>;

package/dist/preset-cli/heading-font-emitter.js

@@ -0,0 +1,166 @@
+/**
+ * `divi/font` heading group-preset emitter — Track 5 vertical slice.
+ *
+ * Emits a byte-canonical Divi 5.5.x `type: "group"` `divi/font` preset
+ * targeting `divi/heading` at `attrs.title.decoration.font.font.desktop.value.*`,
+ * gated by the verified-attrs registry. Canonical shape:
+ * `docs/verification/canonical-preset-shapes-per-module-type-2026-05-18.md`
+ * (`divi/font` section), cross-checked against
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-18/round-1a-heading-h1-pattern-a-google.json`
+ * and `…/round-1b-heading-h1-pattern-b-local.json`.
+ *
+ * Two verified Pattern variants live in the registry — they are NOT
+ * interchangeable evidence. The caller MUST select one explicitly:
+ *
+ *  - Pattern A (Google Fonts CDN): plain family + explicit numeric weight.
+ *    Registry entry: `divi/font` with `pattern_variant: "google_fonts_pattern_a"`.
+ *    Verified evidence: round-1a fixture.
+ *  - Pattern B (local-hosted, EU-GDPR): weight encoded into the family
+ *    string ("Sora 700") and NO `weight` key at all in the preset.
+ *    Registry entry: `divi/font` with `pattern_variant: "local_hosted_pattern_b"`.
+ *    Verified evidence: round-1b fixture.
+ *
+ * Shape rules enforced here:
+ *  - Emit-on-specification only — omitted params produce NO keys.
+ *  - `attrs == styleAttrs == renderAttrs` at the route layer (the plugin's
+ *    `/preset/create` route mirrors `attrs` into all three buckets to match
+ *    VB save semantics); the CLI request body only carries `attrs`.
+ *  - Double-font nesting: `title.decoration.font.font.desktop.value.*` —
+ *    outer `font` is the decoration category, inner `font` is the attr
+ *    name within that category.
+ *  - Pattern B with an explicit `weight` is REFUSED — the verified Pattern
+ *    B capture has no `weight` key and there is no registry entry
+ *    authorizing local-hosted-with-explicit-weight.
+ */
+import { loadRegistry, gateWriteAttr, } from "./registry.js";
+import { normalizeColorValue } from "./variable-token.js";
+export const HEADING_FONT_MODULE = "divi/heading";
+export const HEADING_FONT_GROUP_NAME = "divi/font";
+export const HEADING_FONT_GROUP_ID = "designTitleText";
+export const HEADING_FONT_PATTERN_FAMILY = "divi/font";
+/** The two verified pattern variants for `divi/font` on `divi/heading`. */
+export const HEADING_FONT_PATTERN_VARIANTS = {
+    google: "google_fonts_pattern_a",
+    local: "local_hosted_pattern_b",
+};
+/**
+ * Raised when the caller passes a combination the registry does not
+ * authorize for the current Track — distinct from `EvidenceGateError`
+ * (registry-evidence shortfall) and `UsageError` (CLI arg parse).
+ */
+export class UnsupportedVariantCombinationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedVariantCombinationError";
+    }
+}
+/**
+ * Compose the canonical `attrs.title.decoration.font.font.desktop.value`
+ * bag from the input. Emit-on-specification: only specified sub-fields
+ * produce keys.
+ */
+export function composeHeadingFontAttrs(input) {
+    const value = {};
+    if (input.family !== undefined)
+        value.family = input.family;
+    if (input.weight !== undefined)
+        value.weight = input.weight;
+    if (input.color !== undefined)
+        value.color = normalizeColorValue(input.color);
+    if (input.size !== undefined)
+        value.size = input.size;
+    if (input.lineHeight !== undefined)
+        value.lineHeight = input.lineHeight;
+    return {
+        title: {
+            decoration: {
+                font: {
+                    font: {
+                        desktop: {
+                            value,
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+/**
+ * Emit a canonical `divi/font` heading group preset.
+ *
+ * 1. Validate input shape (name, pattern, Pattern B + weight refusal).
+ * 2. Compose `attrs.title.decoration.font.font.desktop.value.*`
+ *    (emit-on-specification).
+ * 3. Gate the chosen `(divi/font, pattern_variant)` cell on `divi/heading`
+ *    against the verified-attrs registry — throws `EvidenceGateError`
+ *    when effective evidence is below `VB_PRESET_STORAGE_VERIFIED`.
+ *
+ * `styleAttrs` and `renderAttrs` are intentionally NOT part of this
+ * entry: the plugin's `/preset/create` route mirrors the single `attrs`
+ * bag into all three buckets, writing `attrs == styleAttrs == renderAttrs`
+ * to match VB save semantics — see `trait-preset.php` `preset_create`.
+ * The Round 1a/1b fixtures capture the post-write storage shape.
+ */
+export function emitHeadingFontGroupPreset(input, registry = loadRegistry()) {
+    if (!input.name || typeof input.name !== "string") {
+        throw new Error("Heading-font emitter requires a non-empty `name`.");
+    }
+    if (input.pattern !== "google" && input.pattern !== "local") {
+        throw new Error(`Heading-font emitter requires \`pattern\` to be "google" or "local"; got ${JSON.stringify(input.pattern)}. ` +
+            `There is no default — Pattern A (google) and Pattern B (local) are distinct registry/evidence variants.`);
+    }
+    // Pattern B + explicit weight is out-of-scope for Track 5. The verified
+    // Pattern B capture proves `weight` is absent; no registry entry
+    // currently authorizes a local-hosted-with-explicit-weight shape.
+    if (input.pattern === "local" && input.weight !== undefined) {
+        throw new UnsupportedVariantCombinationError(`Pattern B (local-hosted) does not support an explicit \`weight\` — the verified ` +
+            `Pattern B shape has no \`weight\` key, and there is no registry variant ` +
+            `authorizing local-hosted-with-explicit-weight. Encode the weight into the ` +
+            `family string instead (e.g. \`family: "Sora 700"\`). A future registry entry ` +
+            `can authorize that shape if VB evidence supports it.`);
+    }
+    const attrs = composeHeadingFontAttrs(input);
+    // Sanity check: at least one styling field was specified. An empty
+    // value bag is a usage error — there is nothing to write.
+    const value = attrs.title.decoration.font.font.desktop.value;
+    if (!value || Object.keys(value).length === 0) {
+        throw new Error("Heading-font emitter produced an empty preset — pass at least one of " +
+            "family, weight, color, size, or lineHeight.");
+    }
+    // Registry gate: variant-aware. Pattern A evidence must NOT vouch for
+    // Pattern B and vice versa — gateWriteAttr resolves by both family AND
+    // variant, so a missing/under-verified variant entry throws here.
+    const patternVariant = HEADING_FONT_PATTERN_VARIANTS[input.pattern];
+    gateWriteAttr(registry, HEADING_FONT_MODULE, HEADING_FONT_PATTERN_FAMILY, patternVariant);
+    return {
+        type: "group",
+        module_name: HEADING_FONT_MODULE,
+        group_name: HEADING_FONT_GROUP_NAME,
+        group_id: HEADING_FONT_GROUP_ID,
+        pattern_variant: patternVariant,
+        name: input.name,
+        attrs,
+    };
+}
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a heading
+ * font preset entry. Matches the body shape the `diviops_preset_create`
+ * MCP tool posts — the CLI reuses the existing route, it does not add one.
+ *
+ * `pattern_variant` is informational metadata on the in-memory entry and
+ * is NOT sent over the wire — the registry-gate decision happens
+ * client-side before the write.
+ */
+export function buildHeadingFontPresetCreateBody(entry, opts = {}) {
+    const body = {
+        module_name: entry.module_name,
+        name: entry.name,
+        attrs: entry.attrs,
+        type: entry.type,
+        group_name: entry.group_name,
+        group_id: entry.group_id,
+    };
+    if (opts.dry_run)
+        body.dry_run = true;
+    return body;
+}

package/dist/preset-cli/registry.d.ts

@@ -48,9 +48,11 @@ export interface VerifiedAttrsRegistry {
     tier2?: Tier12Entry[];
     tier3?: unknown[];
 }
-/** Resolution of a single `(module, pattern-family)` cell against the registry. */
+/** Resolution of a single `(module, pattern-family[, pattern-variant])` cell against the registry. */
 export interface EvidenceResolution {
     patternFamily: string;
+    /** The matched entry's `pattern_variant`, if any. */
+    patternVariant?: string;
     module: string;
     /** Numeric pattern-level evidence (0–5). */
     patternLevel: number;
@@ -78,17 +80,29 @@ export declare function loadRegistry(explicitPath?: string): VerifiedAttrsRegist
 /** Reset the module-level cache. Used by tests. */
 export declare function resetRegistryCache(): void;
 /**
- * Find a Tier 1 / Tier 2 entry by `pattern_family`. Tier 2 is searched
- * first (the button families live there), then Tier 1.
+ * Find a Tier 1 / Tier 2 entry by `pattern_family` and (optionally)
+ * `pattern_variant`. Tier 2 is searched first, then Tier 1.
+ *
+ * Some pattern families (e.g. `divi/font`) carry multiple entries that
+ * differ ONLY by `pattern_variant` (`google_fonts_pattern_a` vs
+ * `local_hosted_pattern_b`). When `patternVariant` is supplied, ONLY an
+ * entry whose `pattern_variant` matches exactly is returned — a Pattern-A
+ * entry must not vouch for a Pattern-B caller, and vice versa.
+ *
+ * When `patternVariant` is omitted, the legacy behavior holds: the first
+ * matching `pattern_family` is returned regardless of variant — only safe
+ * for families with a single entry. New variant-aware callers should pass
+ * the variant explicitly.
  */
-export declare function findPatternEntry(registry: VerifiedAttrsRegistry, patternFamily: string): Tier12Entry | undefined;
+export declare function findPatternEntry(registry: VerifiedAttrsRegistry, patternFamily: string, patternVariant?: string): Tier12Entry | undefined;
 /**
- * Resolve effective evidence for a `(module, pattern-family)` cell.
+ * Resolve effective evidence for a `(module, pattern-family[, pattern-variant])` cell.
  *
- * Throws if the pattern family is entirely absent from the registry —
- * that is an unrecoverable gap (the CLI must fail, not guess).
+ * Throws if the pattern family (or, when supplied, the specific variant)
+ * is entirely absent from the registry — that is an unrecoverable gap
+ * (the CLI must fail, not guess).
  */
-export declare function resolveEvidence(registry: VerifiedAttrsRegistry, module: string, patternFamily: string): EvidenceResolution;
+export declare function resolveEvidence(registry: VerifiedAttrsRegistry, module: string, patternFamily: string, patternVariant?: string): EvidenceResolution;
 /** Numeric ordering of the write-emitter threshold against a registry. */
 export declare function writeThresholdNumber(registry: VerifiedAttrsRegistry): number;
 /**
@@ -104,4 +118,4 @@ export declare class EvidenceGateError extends Error {
     readonly thresholdName: string;
     constructor(patternFamily: string, module: string, resolution: EvidenceResolution, thresholdNumber: number, thresholdName: string);
 }
-export declare function gateWriteAttr(registry: VerifiedAttrsRegistry, module: string, patternFamily: string): EvidenceResolution;
+export declare function gateWriteAttr(registry: VerifiedAttrsRegistry, module: string, patternFamily: string, patternVariant?: string): EvidenceResolution;

package/dist/preset-cli/registry.js

@@ -77,28 +77,48 @@ function levelName(registry, num) {
     return "UNVERIFIED";
 }
 /**
- * Find a Tier 1 / Tier 2 entry by `pattern_family`. Tier 2 is searched
- * first (the button families live there), then Tier 1.
+ * Find a Tier 1 / Tier 2 entry by `pattern_family` and (optionally)
+ * `pattern_variant`. Tier 2 is searched first, then Tier 1.
+ *
+ * Some pattern families (e.g. `divi/font`) carry multiple entries that
+ * differ ONLY by `pattern_variant` (`google_fonts_pattern_a` vs
+ * `local_hosted_pattern_b`). When `patternVariant` is supplied, ONLY an
+ * entry whose `pattern_variant` matches exactly is returned — a Pattern-A
+ * entry must not vouch for a Pattern-B caller, and vice versa.
+ *
+ * When `patternVariant` is omitted, the legacy behavior holds: the first
+ * matching `pattern_family` is returned regardless of variant — only safe
+ * for families with a single entry. New variant-aware callers should pass
+ * the variant explicitly.
  */
-export function findPatternEntry(registry, patternFamily) {
+export function findPatternEntry(registry, patternFamily, patternVariant) {
     const tiers = [registry.tier2 ?? [], registry.tier1 ?? []];
     for (const tier of tiers) {
-        const hit = tier.find((e) => e.pattern_family === patternFamily);
+        const hit = tier.find((e) => {
+            if (e.pattern_family !== patternFamily)
+                return false;
+            if (patternVariant !== undefined) {
+                return e.pattern_variant === patternVariant;
+            }
+            return true;
+        });
         if (hit)
             return hit;
     }
     return undefined;
 }
 /**
- * Resolve effective evidence for a `(module, pattern-family)` cell.
+ * Resolve effective evidence for a `(module, pattern-family[, pattern-variant])` cell.
  *
- * Throws if the pattern family is entirely absent from the registry —
- * that is an unrecoverable gap (the CLI must fail, not guess).
+ * Throws if the pattern family (or, when supplied, the specific variant)
+ * is entirely absent from the registry — that is an unrecoverable gap
+ * (the CLI must fail, not guess).
  */
-export function resolveEvidence(registry, module, patternFamily) {
-    const entry = findPatternEntry(registry, patternFamily);
+export function resolveEvidence(registry, module, patternFamily, patternVariant) {
+    const entry = findPatternEntry(registry, patternFamily, patternVariant);
     if (!entry) {
-        throw new Error(`Pattern family "${patternFamily}" is absent from verified-attrs.json. ` +
+        const variantSuffix = patternVariant !== undefined ? ` (variant "${patternVariant}")` : "";
+        throw new Error(`Pattern family "${patternFamily}"${variantSuffix} is absent from verified-attrs.json. ` +
             `The CLI cannot emit an unregistered attr. File this as a registry-gap backlog candidate.`);
     }
     const patternLevel = levelNumber(registry, entry.pattern_evidence_level);
@@ -113,6 +133,7 @@ export function resolveEvidence(registry, module, patternFamily) {
         "verified-attrs.json (no source field)";
     return {
         patternFamily,
+        patternVariant: entry.pattern_variant,
         module,
         patternLevel,
         patternLevelName: entry.pattern_evidence_level,
@@ -141,7 +162,10 @@ export class EvidenceGateError extends Error {
     thresholdNumber;
     thresholdName;
     constructor(patternFamily, module, resolution, thresholdNumber, thresholdName) {
-        super(`Evidence-gate refusal: attr family "${patternFamily}" on module "${module}" ` +
+        const variantTag = resolution.patternVariant !== undefined
+            ? ` variant "${resolution.patternVariant}"`
+            : "";
+        super(`Evidence-gate refusal: attr family "${patternFamily}"${variantTag} on module "${module}" ` +
             `has EFFECTIVE evidence ${resolution.effectiveLevelName} (${resolution.effectiveLevel}), ` +
             `below the write threshold ${thresholdName} (${thresholdNumber}). ` +
             (resolution.applicabilityMissing
@@ -158,8 +182,8 @@ export class EvidenceGateError extends Error {
         this.name = "EvidenceGateError";
     }
 }
-export function gateWriteAttr(registry, module, patternFamily) {
-    const resolution = resolveEvidence(registry, module, patternFamily);
+export function gateWriteAttr(registry, module, patternFamily, patternVariant) {
+    const resolution = resolveEvidence(registry, module, patternFamily, patternVariant);
     const thresholdNumber = writeThresholdNumber(registry);
     if (resolution.effectiveLevel < thresholdNumber) {
         throw new EvidenceGateError(patternFamily, module, resolution, thresholdNumber, WRITE_EMITTER_THRESHOLD_LEVEL);