@diviops/mcp-server 1.5.13 → 1.5.16

package/dist/preset-cli/button-emitter.js

@@ -1,5 +1,5 @@
 /**
- * `divi/button` group-preset emitter — Track 4 vertical slice.
+ * `divi/button` group-preset emitter.
  *
  * Emits a byte-canonical Divi 5.5.x `type: "group"` button preset at
  * `attrs.button.decoration.{background, border, font}`, gated by the

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

@@ -1,9 +1,10 @@
 /**
- * `diviops-preset` — standalone preset-emitter CLI (Track 4 scaffold).
+ * `diviops-preset` — standalone preset-emitter CLI.
  *
  * Emits byte-canonical Divi 5.5.x preset JSON, gated by the verified-attrs
- * registry and routed through the existing storage-path contract. Track 4
- * ships one emitter: `divi/button` group presets.
+ * registry and routed through the existing storage-path contract. The
+ * initial slice shipped the `divi/button` group emitter; subsequent slices
+ * added the heading/font, color, and spacing emitters.
  *
  * Usage:
  *   diviops-preset button [options]      Emit a divi/button group preset
@@ -25,6 +26,7 @@
 import { type ButtonEmitterInput } from "./button-emitter.js";
 import { type HeadingFontEmitterInput } from "./heading-font-emitter.js";
 import { type TextBodyFontEmitterInput } from "./text-body-font-emitter.js";
+import { type SpacingEmitterInput } from "./spacing-emitter.js";
 export declare const EXIT: {
     readonly OK: 0;
     readonly INVALID_INPUT: 1;
@@ -56,6 +58,8 @@ export declare function buildButtonInput(parsed: ParsedArgs): ButtonEmitterInput
 export declare function buildHeadingFontInput(parsed: ParsedArgs): HeadingFontEmitterInput;
 /** Map parsed `text-body-font` options into the text-body-font emitter input shape. */
 export declare function buildTextBodyFontInput(parsed: ParsedArgs): TextBodyFontEmitterInput;
+/** Map parsed `spacing` options into the spacing emitter input shape. */
+export declare function buildSpacingInput(parsed: ParsedArgs): SpacingEmitterInput;
 /**
  * Run the CLI. Returns the structured exit code (does NOT call
  * `process.exit` — the thin bin wrapper does). `io` is injectable so

package/dist/preset-cli/cli.js

@@ -1,9 +1,10 @@
 /**
- * `diviops-preset` — standalone preset-emitter CLI (Track 4 scaffold).
+ * `diviops-preset` — standalone preset-emitter CLI.
  *
  * Emits byte-canonical Divi 5.5.x preset JSON, gated by the verified-attrs
- * registry and routed through the existing storage-path contract. Track 4
- * ships one emitter: `divi/button` group presets.
+ * registry and routed through the existing storage-path contract. The
+ * initial slice shipped the `divi/button` group emitter; subsequent slices
+ * added the heading/font, color, and spacing emitters.
  *
  * Usage:
  *   diviops-preset button [options]      Emit a divi/button group preset
@@ -25,8 +26,9 @@
 import { emitButtonGroupPreset, buildPresetCreateBody, } from "./button-emitter.js";
 import { emitHeadingFontGroupPreset, buildHeadingFontPresetCreateBody, UnsupportedVariantCombinationError, } from "./heading-font-emitter.js";
 import { emitTextBodyFontGroupPreset, buildTextBodyFontPresetCreateBody, } from "./text-body-font-emitter.js";
+import { emitSpacingGroupPreset, buildSpacingPresetCreateBody, } from "./spacing-emitter.js";
 import { EvidenceGateError } from "./registry.js";
-import { applyButtonPreset, applyHeadingFontPreset, applyTextBodyFontPreset, buildClientFromEnv, CredentialsMissingError, CapabilityMissingError, } from "./write-path.js";
+import { applyButtonPreset, applyHeadingFontPreset, applyTextBodyFontPreset, applySpacingPreset, buildClientFromEnv, CredentialsMissingError, CapabilityMissingError, } from "./write-path.js";
 export const EXIT = {
     OK: 0,
     INVALID_INPUT: 1,
@@ -46,6 +48,8 @@ USAGE
                                             divi/heading
   diviops-preset text-body-font [options]   Emit a divi/font-body group preset
                                             for divi/text (Pattern A only)
+  diviops-preset spacing [options]          Emit a divi/spacing group preset
+                                            (currently divi/section only)
   diviops-preset --help                     Show this help
 
 MODE
@@ -123,6 +127,38 @@ text-body-font OPTIONS (all styling fields optional; emit-on-specification only)
   --font-size <v>          Font size (e.g. "16px").
   --font-line-height <v>   Font line-height (e.g. "1.5").
 
+spacing OPTIONS (sparse-emit per axis; paired sync flags per axis)
+  --name <string>          Preset display name (required).
+  --module <name>          Required. Currently only divi/section is wired
+                           (the canonical capture verified only the
+                           divi/section cell). Other modules (divi/heading,
+                           divi/text, divi/button, etc.) resolve to the
+                           registry gate and are refused with
+                           EvidenceGateError — promoting them requires a
+                           canonical-capture change plus a follow-up
+                           implementation/docs change (NOT a free dispatch-
+                           clear via the gate alone).
+  --padding-top <v>        Desktop padding corners. Pass any subset; only
+  --padding-right <v>      passed corners emit (sparse-emit per axis). v1
+  --padding-bottom <v>     accepts literal CSS lengths only (px / rem /
+  --padding-left <v>       em / % / vw / vh) — $variable(...) / gvid-*
+                           tokens are refused (deferred until canonical
+                           variable-token capture lands).
+  --margin-top <v>         Desktop margin corners. Same shape rules as
+  --margin-right <v>       padding; padding and margin are independent —
+  --margin-bottom <v>      passing only padding flags omits the margin bag
+  --margin-left <v>        from the output, and vice versa.
+  --padding-sync-vertical <on|off>
+                           Explicit padding sync flag (default "off").
+                           Both syncVertical AND syncHorizontal always
+  --padding-sync-horizontal <on|off>
+                           emit as paired siblings when the padding axis
+                           has any touched corner.
+  --margin-sync-vertical <on|off>
+                           Explicit margin sync flag (default "off").
+  --margin-sync-horizontal <on|off>
+                           Same paired-siblings rule as padding.
+
 EXIT CODES
   0 success   1 invalid input   2 evidence-gate refusal
   3 capability missing   4 write error
@@ -145,6 +181,9 @@ EXAMPLES
   diviops-preset text-body-font --name "Body Text" --pattern google \\
     --font-family Inter --font-weight 400 \\
     --font-color gcid-body-color --font-size 16px
+
+  diviops-preset spacing --name "Section Rhythm" --module divi/section \\
+    --padding-top 80px --padding-bottom 80px --margin-bottom 40px
 `;
 const VALUE_FLAGS = new Set([
     "--name",
@@ -165,6 +204,19 @@ const VALUE_FLAGS = new Set([
     "--font-size",
     "--font-line-height",
     "--pattern",
+    "--module",
+    "--padding-top",
+    "--padding-right",
+    "--padding-bottom",
+    "--padding-left",
+    "--margin-top",
+    "--margin-right",
+    "--margin-bottom",
+    "--margin-left",
+    "--padding-sync-vertical",
+    "--padding-sync-horizontal",
+    "--margin-sync-vertical",
+    "--margin-sync-horizontal",
 ]);
 /** Parse argv (after `node script`) into a structured shape. Throws on unknown flags. */
 export function parseArgs(argv) {
@@ -229,7 +281,12 @@ export class UsageError extends Error {
     }
 }
 /** Known CLI commands. The CLI rejects anything else with EXIT.INVALID_INPUT. */
-const KNOWN_COMMANDS = new Set(["button", "heading-font", "text-body-font"]);
+const KNOWN_COMMANDS = new Set([
+    "button",
+    "heading-font",
+    "text-body-font",
+    "spacing",
+]);
 /** Map parsed `button` options into the emitter input shape. */
 export function buildButtonInput(parsed) {
     const opt = (k) => {
@@ -394,6 +451,67 @@ export function buildTextBodyFontInput(parsed) {
         input.lineHeight = lineHeight;
     return input;
 }
+/** Parse an optional `on|off` flag value; throw a usage error otherwise. */
+function parseOnOff(raw, flag) {
+    if (raw === undefined)
+        return undefined;
+    if (raw !== "on" && raw !== "off") {
+        throw new UsageError(`${flag} must be "on" or "off"; got ${JSON.stringify(raw)}.`);
+    }
+    return raw;
+}
+/** Map parsed `spacing` options into the spacing emitter input shape. */
+export function buildSpacingInput(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("spacing command requires --name <string>.");
+    }
+    const module = opt("--module");
+    if (!module) {
+        throw new UsageError("spacing command requires --module <name>. Currently only " +
+            "divi/section is wired; other modules are refused by the registry " +
+            "gate (heading/text/button cells are SCHEMA_OBSERVED).");
+    }
+    const input = { name, module };
+    // Sparse-emit at parse time too: only attach an axis bag when at least
+    // one corner OR a sync flag was passed. (Sync-flag-only input lands on
+    // the emitter's per-axis sync-without-corner refusal.) Padding and
+    // margin follow the identical shape rule, so the per-axis collection
+    // is hoisted into a single helper.
+    const buildAxis = (prefix) => {
+        const bag = {};
+        const t = opt(`--${prefix}-top`);
+        if (t !== undefined)
+            bag.top = t;
+        const r = opt(`--${prefix}-right`);
+        if (r !== undefined)
+            bag.right = r;
+        const b = opt(`--${prefix}-bottom`);
+        if (b !== undefined)
+            bag.bottom = b;
+        const l = opt(`--${prefix}-left`);
+        if (l !== undefined)
+            bag.left = l;
+        const sv = parseOnOff(opt(`--${prefix}-sync-vertical`), `--${prefix}-sync-vertical`);
+        if (sv !== undefined)
+            bag.syncVertical = sv;
+        const sh = parseOnOff(opt(`--${prefix}-sync-horizontal`), `--${prefix}-sync-horizontal`);
+        if (sh !== undefined)
+            bag.syncHorizontal = sh;
+        return Object.keys(bag).length > 0 ? bag : undefined;
+    };
+    const padding = buildAxis("padding");
+    if (padding)
+        input.padding = padding;
+    const margin = buildAxis("margin");
+    if (margin)
+        input.margin = margin;
+    return input;
+}
 /**
  * Run the CLI. Returns the structured exit code (does NOT call
  * `process.exit` — the thin bin wrapper does). `io` is injectable so
@@ -449,6 +567,14 @@ export async function run(argv, io = realIO, serverVersion) {
             dryRunBody = buildTextBodyFontPresetCreateBody(entry, { dry_run: true });
             applyFn = (client, sv) => applyTextBodyFontPreset(client, entry, { serverVersion: sv });
         }
+        else if (parsed.command === "spacing") {
+            // spacing (divi/section only — other modules land on the registry
+            // gate in emitSpacingGroupPreset and surface as EvidenceGateError).
+            const input = buildSpacingInput(parsed);
+            const entry = emitSpacingGroupPreset(input);
+            dryRunBody = buildSpacingPresetCreateBody(entry, { dry_run: true });
+            applyFn = (client, sv) => applySpacingPreset(client, entry, { serverVersion: sv });
+        }
         else {
             // Defensive: a new entry in KNOWN_COMMANDS without a dispatch
             // branch here would silently break dry-run/apply. parseArgs

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

@@ -1,5 +1,5 @@
 /**
- * `divi/font` heading group-preset emitter — Track 5 vertical slice.
+ * `divi/font` heading group-preset emitter.
  *
  * Emits a byte-canonical Divi 5.5.x `type: "group"` `divi/font` preset
  * targeting `divi/heading` at `attrs.title.decoration.font.font.desktop.value.*`,

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

@@ -1,5 +1,5 @@
 /**
- * `divi/font` heading group-preset emitter — Track 5 vertical slice.
+ * `divi/font` heading group-preset emitter.
  *
  * Emits a byte-canonical Divi 5.5.x `type: "group"` `divi/font` preset
  * targeting `divi/heading` at `attrs.title.decoration.font.font.desktop.value.*`,
@@ -109,8 +109,8 @@ export function emitHeadingFontGroupPreset(input, registry = loadRegistry()) {
         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
+    // Pattern B + explicit weight is out-of-scope for the current emitter. 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 ` +

package/dist/preset-cli/spacing-emitter.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `divi/spacing` section group-preset emitter.
+ *
+ * Emits a byte-canonical Divi 5.6.0 `type: "group"` `divi/spacing` preset
+ * targeting `divi/section` at
+ * `attrs.module.decoration.spacing.desktop.value.{padding|margin}.*`,
+ * gated by the verified-attrs registry. Canonical shape captured under
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-23/round-5-spacing-section.json`.
+ *
+ * Scope: `divi/section` ONLY. Heading / text / button spacing cells remain
+ * `SCHEMA_OBSERVED` and resolve to `EvidenceGateError` here per
+ * `feedback_preset_map_per_module` (no cross-module shape carry-over).
+ *
+ * Shape rules enforced here (brief §4):
+ *  - Sparse-emit per axis — only user-touched corners appear under
+ *    `padding`/`margin`. Untouched corners are absent (not present-as-empty,
+ *    not present-as-null).
+ *  - Paired sync flags per axis — any spacing touch on an axis emits BOTH
+ *    `syncVertical` AND `syncHorizontal` as siblings. Default `"off"` on
+ *    both unless the caller explicitly toggled them.
+ *  - Padding and margin are INDEPENDENT bags — passing only padding flags
+ *    omits the margin bag entirely, and vice versa.
+ *  - `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`. The
+ *    canonical capture fixture documents the post-write storage shape — do
+ *    NOT add `styleAttrs` / `renderAttrs` keys to the emitter output.
+ *  - `groupId: "designSpacing"` — the Composable Settings panel id, NOT a
+ *    dotted attr path (the prior schema-inferred `module.decoration.spacing`
+ *    note was a misread, now corrected).
+ *  - `primaryAttrName: "module"` for section spacing.
+ *  - Variable tokens (`$variable(...)` / bare `gvid-*`) in length flags are
+ *    REFUSED — the canonical capture exercised literal CSS lengths only;
+ *    variable-token shape needs its own capture before this emitter writes
+ *    it.
+ */
+import { type VerifiedAttrsRegistry } from "./registry.js";
+export declare const SPACING_GROUP_NAME = "divi/spacing";
+export declare const SPACING_GROUP_ID = "designSpacing";
+export declare const SPACING_PRIMARY_ATTR_NAME = "module";
+export declare const SPACING_PATTERN_FAMILY = "divi/spacing";
+/**
+ * The single currently-supported module cell. The `--module` flag accepts
+ * any string and routes through the registry gate (so the surface stays
+ * stable when heading/text/button cells eventually promote), but only
+ * `divi/section` is wired with fixtures + tests + canonical shape today.
+ *
+ * Promoting another module is NOT a free dispatch-clear via the registry
+ * gate — each new cell needs a canonical-capture change landing first AND
+ * a follow-up implementation/docs change.
+ */
+export declare const SPACING_SUPPORTED_MODULES: readonly ["divi/section"];
+export type SpacingCornerInput = {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+    syncVertical?: "on" | "off";
+    syncHorizontal?: "on" | "off";
+};
+export interface SpacingEmitterInput {
+    /** Required display name for the preset. */
+    name: string;
+    /**
+     * Required module selector. Forward-compat-shaped; only `divi/section` is
+     * wired today, everything else lands on `EvidenceGateError` via the
+     * registry gate (or a SCHEMA_OBSERVED cell evidence-gate refusal).
+     */
+    module: string;
+    /** Desktop padding corner-and-sync bag. */
+    padding?: SpacingCornerInput;
+    /** Desktop margin corner-and-sync bag. */
+    margin?: SpacingCornerInput;
+}
+/** The composed canonical preset entry shape sent to `/preset/create`. */
+export interface SpacingPresetEntry {
+    type: "group";
+    module_name: string;
+    group_name: string;
+    group_id: string;
+    primary_attr_name: string;
+    name: string;
+    attrs: Record<string, unknown>;
+}
+/**
+ * Compose the canonical
+ * `attrs.module.decoration.spacing.desktop.value.{padding|margin}` bag.
+ * Sparse-emit per axis; padding and margin are independent.
+ *
+ * Returns BOTH the full `attrs` tree (what the emitter ships) AND the
+ * inner `value` bag — the caller does empty-preset validation against
+ * `value` without re-walking the nested attrs tree (no `as any` deep
+ * casts).
+ */
+export declare function composeSpacingAttrs(input: SpacingEmitterInput): {
+    attrs: Record<string, unknown>;
+    value: Record<string, unknown>;
+};
+/**
+ * Emit a canonical `divi/spacing` section group preset.
+ *
+ * 1. Validate input shape (name, module, at least one corner across either
+ *    axis).
+ * 2. Reject variable-token values in any length flag (deferred until a
+ *    canonical capture lands).
+ * 3. Compose sparse-emit `attrs.module.decoration.spacing.desktop.value.*`
+ *    with paired sync flags.
+ * 4. Gate `(divi/spacing, <module>)` 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 at write time. The canonical capture fixture documents
+ * the post-write storage shape (which is why both `attrs` and `styleAttrs`
+ * appear there byte-identical); the CLI emits the request shape only.
+ */
+export declare function emitSpacingGroupPreset(input: SpacingEmitterInput, registry?: VerifiedAttrsRegistry): SpacingPresetEntry;
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a spacing
+ * preset entry. Matches the body shape the `diviops_preset_create` MCP
+ * tool posts — the CLI reuses the existing route, it does not add one.
+ *
+ * `primary_attr_name` IS sent on the wire (the plugin's `/preset/create`
+ * route accepts it as an optional snake_case param and stores it as
+ * `primaryAttrName` in the preset). The button / font / color emitters
+ * omit it because their preset types do not carry it; the divi/spacing
+ * cell does, per the canonical capture's load-bearing finding #2.
+ */
+export declare function buildSpacingPresetCreateBody(entry: SpacingPresetEntry, opts?: {
+    dry_run?: boolean;
+}): Record<string, unknown>;

package/dist/preset-cli/spacing-emitter.js

@@ -0,0 +1,276 @@
+/**
+ * `divi/spacing` section group-preset emitter.
+ *
+ * Emits a byte-canonical Divi 5.6.0 `type: "group"` `divi/spacing` preset
+ * targeting `divi/section` at
+ * `attrs.module.decoration.spacing.desktop.value.{padding|margin}.*`,
+ * gated by the verified-attrs registry. Canonical shape captured under
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-23/round-5-spacing-section.json`.
+ *
+ * Scope: `divi/section` ONLY. Heading / text / button spacing cells remain
+ * `SCHEMA_OBSERVED` and resolve to `EvidenceGateError` here per
+ * `feedback_preset_map_per_module` (no cross-module shape carry-over).
+ *
+ * Shape rules enforced here (brief §4):
+ *  - Sparse-emit per axis — only user-touched corners appear under
+ *    `padding`/`margin`. Untouched corners are absent (not present-as-empty,
+ *    not present-as-null).
+ *  - Paired sync flags per axis — any spacing touch on an axis emits BOTH
+ *    `syncVertical` AND `syncHorizontal` as siblings. Default `"off"` on
+ *    both unless the caller explicitly toggled them.
+ *  - Padding and margin are INDEPENDENT bags — passing only padding flags
+ *    omits the margin bag entirely, and vice versa.
+ *  - `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`. The
+ *    canonical capture fixture documents the post-write storage shape — do
+ *    NOT add `styleAttrs` / `renderAttrs` keys to the emitter output.
+ *  - `groupId: "designSpacing"` — the Composable Settings panel id, NOT a
+ *    dotted attr path (the prior schema-inferred `module.decoration.spacing`
+ *    note was a misread, now corrected).
+ *  - `primaryAttrName: "module"` for section spacing.
+ *  - Variable tokens (`$variable(...)` / bare `gvid-*`) in length flags are
+ *    REFUSED — the canonical capture exercised literal CSS lengths only;
+ *    variable-token shape needs its own capture before this emitter writes
+ *    it.
+ */
+import { loadRegistry, gateWriteAttr, } from "./registry.js";
+export const SPACING_GROUP_NAME = "divi/spacing";
+export const SPACING_GROUP_ID = "designSpacing";
+export const SPACING_PRIMARY_ATTR_NAME = "module";
+export const SPACING_PATTERN_FAMILY = "divi/spacing";
+/**
+ * The single currently-supported module cell. The `--module` flag accepts
+ * any string and routes through the registry gate (so the surface stays
+ * stable when heading/text/button cells eventually promote), but only
+ * `divi/section` is wired with fixtures + tests + canonical shape today.
+ *
+ * Promoting another module is NOT a free dispatch-clear via the registry
+ * gate — each new cell needs a canonical-capture change landing first AND
+ * a follow-up implementation/docs change.
+ */
+export const SPACING_SUPPORTED_MODULES = ["divi/section"];
+/** Detect bare `gvid-*` / `gcid-*` variable token names. */
+const BARE_VARIABLE_TOKEN_RE = /^(gvid|gcid)-/;
+/**
+ * Positive validator for CSS length values. Accepts only the v1 unit set
+ * from the brief: integer or decimal numbers (including a leading minus
+ * sign and bare `0`) followed by `px`, `rem`, `em`, `%`, `vw`, or `vh`.
+ * The canonical capture exercised literal values only — variable tokens,
+ * `var(...)`, `calc(...)`, and free-form strings like `banana` are all
+ * refused before emission. Adding any new unit requires a brief update
+ * (canonical-capture re-test if the unit changes server-side rendering).
+ */
+const LITERAL_CSS_LENGTH_RE = /^-?(?:\d+\.?\d*|\.\d+)(?:px|rem|em|%|vw|vh)$/;
+/**
+ * Validate that `value` is a literal CSS length and not a deferred-shape
+ * token. The check runs on EVERY length flag before the emission path.
+ *
+ * Three refusal paths:
+ *  1. `$variable(...)` token — deferred shape, needs its own capture.
+ *  2. Bare `gvid-*` / `gcid-*` token name — same deferred shape.
+ *  3. Anything else that does NOT match the v1 literal CSS length grammar
+ *     (`px`, `rem`, `em`, `%`, `vw`, `vh`). Catches `banana`, `var(--x)`,
+ *     `calc(8px + 2vw)`, etc. — none of which the canonical capture verified.
+ *
+ * The variable-token branches fire BEFORE the generic literal check so
+ * the operator gets the precise "variable-token support deferred" hint
+ * rather than the generic "not a literal CSS length" message.
+ */
+function assertLiteralLength(value, flagLabel) {
+    // Trim before pattern-matching so leading / trailing whitespace can't
+    // bypass any prefix check (e.g. " gvid-space-1"). The raw value
+    // appears in the error message so the operator sees exactly what was
+    // passed.
+    const trimmed = value.trim();
+    if (trimmed.startsWith("$variable(")) {
+        throw new Error(`${flagLabel} value ${JSON.stringify(value)} is a $variable() token. ` +
+            `Variable-token support deferred — pending canonical capture. ` +
+            `Canonical capture exercised literal CSS length values only (px / rem / em / % / vw / vh).`);
+    }
+    if (BARE_VARIABLE_TOKEN_RE.test(trimmed)) {
+        throw new Error(`${flagLabel} value ${JSON.stringify(value)} is a bare ${trimmed.split("-")[0]}-* variable token. ` +
+            `Variable-token support deferred — pending canonical capture. ` +
+            `Canonical capture exercised literal CSS length values only (px / rem / em / % / vw / vh).`);
+    }
+    if (!LITERAL_CSS_LENGTH_RE.test(trimmed)) {
+        throw new Error(`${flagLabel} value ${JSON.stringify(value)} is not a literal CSS length. ` +
+            `v1 accepts only \`<number><unit>\` where unit is one of px / rem / em / % / vw / vh ` +
+            `(e.g. "40px", "1.5rem", "100%"). The canonical capture exercised literal ` +
+            `values only; broader value grammars (var(...), calc(...), etc.) need their own capture.`);
+    }
+}
+/**
+ * Compose a single axis bag (padding or margin) from a corner input.
+ *
+ * Returns `undefined` when the axis input is entirely absent (the axis is
+ * absent from the emitted attrs — sparse-emit at axis level). When ANY
+ * corner is passed, both sync flags are emitted as paired siblings
+ * (default `"off"` on each side unless the caller explicitly toggled
+ * them).
+ *
+ * Sync-flag-only input on an axis with no touched corner is REFUSED with
+ * an explicit error — silently no-op'ing a passed sync flag would be a
+ * surprising footgun. If the caller wants to toggle sync, they must also
+ * pass at least one corner on the same axis to anchor it.
+ */
+function composeAxis(input, flagPrefix) {
+    if (!input)
+        return undefined;
+    const corners = ["top", "right", "bottom", "left"].filter((c) => input[c] !== undefined);
+    if (corners.length === 0) {
+        // Sync flag passed without any corner on the same axis → explicit
+        // refusal. The paired sync flags only have meaning anchored to at
+        // least one corner; emitting them alone would silently drop them.
+        if (input.syncVertical !== undefined ||
+            input.syncHorizontal !== undefined) {
+            throw new Error(`--${flagPrefix}-sync-vertical / --${flagPrefix}-sync-horizontal require at ` +
+                `least one --${flagPrefix}-{top,right,bottom,left} corner on the same axis. ` +
+                `Sync flags are paired-sibling metadata anchored to corners; emitting them ` +
+                `alone would silently no-op.`);
+        }
+        return undefined;
+    }
+    const bag = {};
+    for (const c of corners) {
+        const v = input[c];
+        if (typeof v !== "string" || v.length === 0) {
+            throw new Error(`--${flagPrefix}-${c} requires a non-empty CSS length value.`);
+        }
+        assertLiteralLength(v, `--${flagPrefix}-${c}`);
+        bag[c] = v;
+    }
+    bag.syncVertical = input.syncVertical ?? "off";
+    bag.syncHorizontal = input.syncHorizontal ?? "off";
+    return bag;
+}
+/**
+ * Compose the canonical
+ * `attrs.module.decoration.spacing.desktop.value.{padding|margin}` bag.
+ * Sparse-emit per axis; padding and margin are independent.
+ *
+ * Returns BOTH the full `attrs` tree (what the emitter ships) AND the
+ * inner `value` bag — the caller does empty-preset validation against
+ * `value` without re-walking the nested attrs tree (no `as any` deep
+ * casts).
+ */
+export function composeSpacingAttrs(input) {
+    const padding = composeAxis(input.padding, "padding");
+    const margin = composeAxis(input.margin, "margin");
+    const value = {};
+    if (padding)
+        value.padding = padding;
+    if (margin)
+        value.margin = margin;
+    const attrs = {
+        [SPACING_PRIMARY_ATTR_NAME]: {
+            decoration: {
+                spacing: {
+                    desktop: {
+                        value,
+                    },
+                },
+            },
+        },
+    };
+    return { attrs, value };
+}
+/**
+ * Emit a canonical `divi/spacing` section group preset.
+ *
+ * 1. Validate input shape (name, module, at least one corner across either
+ *    axis).
+ * 2. Reject variable-token values in any length flag (deferred until a
+ *    canonical capture lands).
+ * 3. Compose sparse-emit `attrs.module.decoration.spacing.desktop.value.*`
+ *    with paired sync flags.
+ * 4. Gate `(divi/spacing, <module>)` 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 at write time. The canonical capture fixture documents
+ * the post-write storage shape (which is why both `attrs` and `styleAttrs`
+ * appear there byte-identical); the CLI emits the request shape only.
+ */
+export function emitSpacingGroupPreset(input, registry = loadRegistry()) {
+    if (!input.name || typeof input.name !== "string") {
+        throw new Error("spacing emitter requires a non-empty `name`.");
+    }
+    if (!input.module || typeof input.module !== "string") {
+        throw new Error("spacing emitter requires `module` — currently only `divi/section` is " +
+            "wired (other module cells are SCHEMA_OBSERVED in the registry; " +
+            "promoting them requires a canonical-capture change + a follow-up " +
+            "implementation/docs change).");
+    }
+    const { attrs, value } = composeSpacingAttrs(input);
+    // Empty-input rejection: at least one corner across either axis MUST be
+    // specified. An empty value bag is a usage error — there is nothing to
+    // write, and the resulting preset would be the empty-shell VB authoring
+    // footgun documented in the canonical capture.
+    if (Object.keys(value).length === 0) {
+        throw new Error("spacing emitter produced an empty preset — pass at least one " +
+            "padding or margin corner (--padding-top, --margin-bottom, etc.).");
+    }
+    // Registry gate: dispatches off `(divi/spacing, <module>)`. Cells below
+    // VB_PRESET_STORAGE_VERIFIED (currently divi/heading, divi/text,
+    // divi/button — all SCHEMA_OBSERVED) throw EvidenceGateError natively
+    // here. Unknown modules with no applicability cell resolve to
+    // UNVERIFIED (0) and also throw.
+    gateWriteAttr(registry, input.module, SPACING_PATTERN_FAMILY);
+    // Implementation-supported-modules guard: even if a future registry-only
+    // PR promotes another cell to VB_PRESET_STORAGE_VERIFIED, this emitter
+    // must NOT silently start emitting it — heading/text/button cells need
+    // their own per-module wrapper (the section cell uses `module.*`, but a
+    // heading-spacing capture might surface `title.*` or a different
+    // primaryAttrName). Per `feedback_preset_map_per_module`, never assume
+    // cross-module shape carry-over. Promoting another module requires
+    // adding it to `SPACING_SUPPORTED_MODULES` alongside the fixture +
+    // tests + README updates that prove the per-module shape.
+    if (!SPACING_SUPPORTED_MODULES.includes(input.module)) {
+        throw new Error(`spacing emitter does not yet implement module "${input.module}". ` +
+            `Registry evidence cleared the cell, but the per-module wrapper + ` +
+            `attr shape have not been verified against a canonical capture ` +
+            `(this emitter hard-codes the divi/section wrapper "module" and ` +
+            `primaryAttrName "module"). Supported modules: ` +
+            `${SPACING_SUPPORTED_MODULES.join(", ")}. Adding a new module ` +
+            `requires a canonical-capture change landing first AND ` +
+            `a follow-up implementation change extending this constant alongside ` +
+            `fixtures + tests + README updates.`);
+    }
+    return {
+        type: "group",
+        module_name: input.module,
+        group_name: SPACING_GROUP_NAME,
+        group_id: SPACING_GROUP_ID,
+        primary_attr_name: SPACING_PRIMARY_ATTR_NAME,
+        name: input.name,
+        attrs,
+    };
+}
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a spacing
+ * preset entry. Matches the body shape the `diviops_preset_create` MCP
+ * tool posts — the CLI reuses the existing route, it does not add one.
+ *
+ * `primary_attr_name` IS sent on the wire (the plugin's `/preset/create`
+ * route accepts it as an optional snake_case param and stores it as
+ * `primaryAttrName` in the preset). The button / font / color emitters
+ * omit it because their preset types do not carry it; the divi/spacing
+ * cell does, per the canonical capture's load-bearing finding #2.
+ */
+export function buildSpacingPresetCreateBody(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,
+        primary_attr_name: entry.primary_attr_name,
+    };
+    if (opts.dry_run)
+        body.dry_run = true;
+    return body;
+}