@flextudio/scenario 0.1.0

package/contract-data/schema/v1/design-system/materialize.mjs

@@ -0,0 +1,1435 @@
+// design-system/materialize.mjs
+// ─────────────────────────────────────────────────────────────────────────────
+// `design` 키 expander.
+//
+// LLM 이 raw control 안에 short-form `design` 객체를 넣으면, 이 모듈이
+// 엔진 style objects (FontStyle / Width / Height / Padding / Margin /
+// BgStyle / BorderStyle / DisplayStyle / ContentStyle / UseFixedSize) 로
+// 풀어준다.
+//
+// 핵심 규칙 (Flextudio MCP design abstraction §):
+//   1. design 안의 모든 색상은 tokens.json 의 slot 이름만 허용 — raw escape
+//      (`var(--colorXxx)` / `#hex` / `rgb(...)`) 는 거부. 일관성 강제.
+//   2. typography 는 role 토큰만 (`body-large` / `title-medium` ...). FontWeight
+//      override 없음.
+//   3. design 키 자체는 raw 와 공존 가능. 같은 leaf 가 겹치면 **design 우선**.
+//      design 이 건드리지 않는 raw leaf 는 그대로 보존.
+//   4. sourceMap 산출 — validator 가 raw path 의 에러를 design path 로 역매핑
+//      하여 LLM 에게 자기가 적은 키 이름으로 피드백할 수 있도록.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOKENS = JSON.parse(readFileSync(join(__dirname, "tokens.json"), "utf8"));
+
+// surface 프리셋 (variant → design 키 묶음). Group 전용 매크로. SSOT: tokens.json#/surface.
+const SURFACE = TOKENS.surface;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 정적 enum (작아서 tokens.json 에 안 둠 — 단순 alias)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const FONT_ALIGN = { start: "flex-start", center: "center", end: "flex-end" };
+
+const DISPLAY_ALIGN = {
+  left: "Left",
+  center: "Center",
+  right: "Right",
+  between: "Between",
+};
+const DISPLAY_VALIGN = { top: "Top", center: "Center", bottom: "Bottom" };
+// flexbox 어휘 alias — 모델이 CSS flex 정렬 vocab(start/end/flex-start/flex-end)을
+// 습관적으로 쓰는 케이스를 canonical 토큰으로 결정적 정규화. lookup 전에만 적용하고
+// 정본 맵(DISPLAY_ALIGN/DISPLAY_VALIGN)은 순수 유지.
+//  - 수직(valign): start→top / end→bottom.  수평(align): start→left / end→right.
+const VALIGN_ALIAS = { start: "top", "flex-start": "top", end: "bottom", "flex-end": "bottom" };
+const ALIGN_ALIAS = { start: "left", "flex-start": "left", end: "right", "flex-end": "right" };
+// DESIGN.md §DisplayStyle: justify=between → flexBoxType="space", 그 외 "align".
+const FLEX_BOX_TYPE = {
+  left: "align",
+  center: "align",
+  right: "align",
+  between: "space",
+};
+
+const KNOWN_KEYS = new Set([
+  "font",
+  "color",
+  "align",
+  "w",
+  "h",
+  "p",
+  "m",
+  "bg",
+  "border",
+  "radius",
+  "elevation",
+  "flex",
+  "caption",
+  "abs",
+  "opacity",
+  "itemBg",
+  "tabHeader",
+  "fixed",
+  "surface",
+]);
+
+// caption 전용 typography role enum — small text 5종.
+const CAPTION_TEXT_ROLES = new Set([
+  "body-large",
+  "body-medium",
+  "body-small",
+  "caption",
+  "micro",
+]);
+
+const BORDER_TYPE_ENUM = new Set(["solid", "dashed", "dotted"]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 에러 헬퍼
+// ─────────────────────────────────────────────────────────────────────────────
+
+function pushErr(errors, path, message, hint) {
+  const e = { kind: "design", path, message };
+  if (hint) e.hint = hint;
+  errors.push(e);
+}
+
+function resolveSlot(map, key, slotKind, path, errors) {
+  if (typeof key !== "string") {
+    pushErr(errors, path, `${slotKind} must be a string slot name (got ${typeof key})`);
+    return null;
+  }
+  if (!Object.hasOwn(map, key)) {
+    pushErr(
+      errors,
+      path,
+      `unknown ${slotKind} slot '${key}'`,
+      `available: ${Object.keys(map).join(", ")}`,
+    );
+    return null;
+  }
+  return map[key];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Width / Height parser
+//   "full" / "text" / "NNpx" / "NN%" / "NNvh" / "NNvw"
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SIZE_RE = /^(\d+(?:\.\d+)?)(px|%|vh|vw)$/;
+
+function parseSize(v, path, errors) {
+  if (v === "full") {
+    return { SizeValue: "100", SizeUnit: "%", MatchText: false };
+  }
+  if (v === "text") {
+    return { MatchText: true, SizeValue: "", SizeUnit: "text" };
+  }
+  if (typeof v !== "string") {
+    pushErr(
+      errors,
+      path,
+      `size must be 'full' / 'text' / 'NNpx' / 'NN%' (got ${typeof v})`,
+    );
+    return null;
+  }
+  const m = SIZE_RE.exec(v);
+  if (!m) {
+    pushErr(
+      errors,
+      path,
+      `invalid size '${v}' — use 'full', 'text', or '<number><px|%|vh|vw>'`,
+    );
+    return null;
+  }
+  return { SizeValue: m[1], SizeUnit: m[2], MatchText: false };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Padding / Margin parser
+//   string shorthand: "16" | "16 20" | "16 20 8" | "16 20 8 4" (CSS order TRBL)
+//   object:           { t, r, b, l } — 누락 사이드는 "" (엔진 default)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const INT_RE = /^\d+$/;
+const SPACING_OBJ_KEYS = new Set(["t", "r", "b", "l"]);
+
+function parseSpacingShorthand(s, path, errors) {
+  const parts = s.trim().split(/\s+/);
+  if (parts.length === 0 || parts.length > 4) {
+    pushErr(
+      errors,
+      path,
+      `spacing '${s}' must have 1–4 values (CSS shorthand)`,
+    );
+    return null;
+  }
+  for (const p of parts) {
+    if (!INT_RE.test(p)) {
+      pushErr(
+        errors,
+        path,
+        `spacing '${s}' contains non-integer '${p}' — only non-negative integers allowed`,
+      );
+      return null;
+    }
+  }
+  let t, r, b, l;
+  if (parts.length === 1) {
+    t = r = b = l = parts[0];
+  } else if (parts.length === 2) {
+    t = b = parts[0];
+    r = l = parts[1];
+  } else if (parts.length === 3) {
+    t = parts[0];
+    r = l = parts[1];
+    b = parts[2];
+  } else {
+    [t, r, b, l] = parts;
+  }
+  return { t, r, b, l };
+}
+
+function parseSpacing(v, path, errors) {
+  let sides;
+  if (typeof v === "string") {
+    sides = parseSpacingShorthand(v, path, errors);
+  } else if (v && typeof v === "object" && !Array.isArray(v)) {
+    for (const k of Object.keys(v)) {
+      if (!SPACING_OBJ_KEYS.has(k)) {
+        pushErr(
+          errors,
+          `${path}.${k}`,
+          `unknown spacing key '${k}' — allowed: t / r / b / l`,
+        );
+        return null;
+      }
+    }
+    const pick = (val, key) => {
+      if (val == null) return "";
+      const s = String(val);
+      if (!INT_RE.test(s)) {
+        pushErr(
+          errors,
+          `${path}.${key}`,
+          `spacing '${s}' must be a non-negative integer`,
+        );
+        return null;
+      }
+      return s;
+    };
+    const t = pick(v.t, "t");
+    const r = pick(v.r, "r");
+    const b = pick(v.b, "b");
+    const l = pick(v.l, "l");
+    if (t == null || r == null || b == null || l == null) return null;
+    sides = { t, r, b, l };
+  } else {
+    pushErr(
+      errors,
+      path,
+      `spacing must be CSS-shorthand string or { t, r, b, l } object (got ${
+        Array.isArray(v) ? "array" : typeof v
+      })`,
+    );
+    return null;
+  }
+  if (sides == null) return null;
+  return {
+    UseEach: true,
+    UseAuto: true,
+    All: "",
+    Top: sides.t,
+    Right: sides.r,
+    Btm: sides.b,
+    Left: sides.l,
+    SizeUnit: "px",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// flex layout parser  (DisplayStyle — Group 전용 의도)
+//   { dir: "row"|"column"|"wrap",                  // required
+//     gap?: <int>|<intString>|{ row?, col? },      // single value → 양축 동일
+//     align?: "left"|"center"|"right"|"between",   // DisplayAlign (메인 축)
+//     valign?: "top"|"center"|"bottom"             // DisplayVerticalAlign (크로스 축) }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const FLEX_KEYS = new Set(["dir", "gap", "align", "valign"]);
+const FLEX_DIRS = new Set(["row", "column", "wrap"]);
+const GAP_OBJ_KEYS = new Set(["row", "col"]);
+
+function parseFlex(v, path, errors) {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    pushErr(
+      errors,
+      path,
+      `flex must be an object { dir, gap?, align?, valign? }`,
+    );
+    return null;
+  }
+  for (const k of Object.keys(v)) {
+    if (!FLEX_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown flex key '${k}' — allowed: dir / gap / align / valign`,
+      );
+      return null;
+    }
+  }
+  if (v.dir == null) {
+    pushErr(
+      errors,
+      `${path}.dir`,
+      `flex.dir is required — use 'row' / 'column' / 'wrap'`,
+    );
+    return null;
+  }
+  if (!FLEX_DIRS.has(v.dir)) {
+    pushErr(
+      errors,
+      `${path}.dir`,
+      `unknown dir '${v.dir}' — use 'row' / 'column' / 'wrap'`,
+    );
+    return null;
+  }
+
+  const ds = {
+    UseDisplay: true,
+    DisplayType: "Flex",
+    FlexDirection: v.dir,
+  };
+
+  if (v.align != null) {
+    const alignKey = ALIGN_ALIAS[v.align] ?? v.align;
+    const da = DISPLAY_ALIGN[alignKey];
+    if (da == null) {
+      pushErr(
+        errors,
+        `${path}.align`,
+        `unknown align '${v.align}' — use left / center / right / between`,
+      );
+      return null;
+    }
+    ds.DisplayAlign = da;
+    ds.flexBoxType = FLEX_BOX_TYPE[alignKey];
+  }
+
+  if (v.valign != null) {
+    const valignKey = VALIGN_ALIAS[v.valign] ?? v.valign;
+    const dva = DISPLAY_VALIGN[valignKey];
+    if (dva == null) {
+      pushErr(
+        errors,
+        `${path}.valign`,
+        `unknown valign '${v.valign}' — use top / center / bottom`,
+      );
+      return null;
+    }
+    ds.DisplayVerticalAlign = dva;
+  }
+
+  if (v.gap != null) {
+    let rowVal, colVal;
+    if (typeof v.gap === "number" || typeof v.gap === "string") {
+      const g = String(v.gap);
+      if (!INT_RE.test(g)) {
+        pushErr(
+          errors,
+          `${path}.gap`,
+          `gap '${g}' must be a non-negative integer`,
+        );
+        return null;
+      }
+      rowVal = g;
+      colVal = g;
+    } else if (typeof v.gap === "object" && !Array.isArray(v.gap)) {
+      for (const k of Object.keys(v.gap)) {
+        if (!GAP_OBJ_KEYS.has(k)) {
+          pushErr(
+            errors,
+            `${path}.gap.${k}`,
+            `unknown gap key '${k}' — allowed: row / col`,
+          );
+          return null;
+        }
+      }
+      const pick = (val, key) => {
+        if (val == null) return null;
+        const s = String(val);
+        if (!INT_RE.test(s)) {
+          pushErr(
+            errors,
+            `${path}.gap.${key}`,
+            `gap.${key} '${s}' must be a non-negative integer`,
+          );
+          return undefined; // sentinel for failure
+        }
+        return s;
+      };
+      rowVal = pick(v.gap.row, "row");
+      colVal = pick(v.gap.col, "col");
+      if (rowVal === undefined || colVal === undefined) return null;
+    } else {
+      pushErr(
+        errors,
+        `${path}.gap`,
+        `gap must be a non-negative integer or { row?, col? } object`,
+      );
+      return null;
+    }
+    if (rowVal != null) {
+      ds.rowGapValue = rowVal;
+      ds.rowGapUnit = "px";
+    }
+    if (colVal != null) {
+      ds.columnGapValue = colVal;
+      ds.columnGapUnit = "px";
+    }
+  }
+
+  return ds;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// border object parser  (객체 form — shorthand 와 별개 경로)
+//   { color: <slot>, type?: solid|dashed|dotted, size? | sides?: { t,r,b,l } }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BORDER_OBJ_KEYS = new Set(["color", "type", "size", "sides"]);
+const SIDE_OBJ_KEYS = new Set(["t", "r", "b", "l"]);
+
+function pickIntString(val, errors, path) {
+  if (val == null) return "";
+  const s = String(val);
+  if (!INT_RE.test(s)) {
+    pushErr(errors, path, `must be a non-negative integer (got '${s}')`);
+    return undefined; // sentinel for failure
+  }
+  return s;
+}
+
+function parseBorderObject(v, path, errors, sourceMap) {
+  for (const k of Object.keys(v)) {
+    if (!BORDER_OBJ_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown border key '${k}' — allowed: color / type / size / sides`,
+      );
+      return null;
+    }
+  }
+  if (v.color == null) {
+    pushErr(errors, path, `border object must have 'color'`);
+    return null;
+  }
+  const color = resolveSlot(
+    TOKENS.color,
+    v.color,
+    "border color",
+    `${path}.color`,
+    errors,
+  );
+  if (color == null) return null;
+
+  if (v.size != null && v.sides != null) {
+    pushErr(
+      errors,
+      path,
+      `border 'size' and 'sides' are mutually exclusive — pick one`,
+    );
+    return null;
+  }
+
+  const out = {
+    Useborder: true,
+    BorderColor: color,
+    BorderType: "solid",
+  };
+  sourceMap["BorderStyle.BorderColor"] = `${path}.color`;
+
+  if (v.type != null) {
+    if (!BORDER_TYPE_ENUM.has(v.type)) {
+      pushErr(
+        errors,
+        `${path}.type`,
+        `unknown border type '${v.type}' — use solid / dashed / dotted`,
+      );
+      return null;
+    }
+    out.BorderType = v.type;
+    sourceMap["BorderStyle.BorderType"] = `${path}.type`;
+  }
+
+  if (v.sides != null) {
+    if (typeof v.sides !== "object" || Array.isArray(v.sides)) {
+      pushErr(
+        errors,
+        `${path}.sides`,
+        `sides must be { t?, r?, b?, l? } object`,
+      );
+      return null;
+    }
+    for (const k of Object.keys(v.sides)) {
+      if (!SIDE_OBJ_KEYS.has(k)) {
+        pushErr(
+          errors,
+          `${path}.sides.${k}`,
+          `unknown side key '${k}' — allowed: t / r / b / l`,
+        );
+        return null;
+      }
+    }
+    const t = pickIntString(v.sides.t, errors, `${path}.sides.t`);
+    const r = pickIntString(v.sides.r, errors, `${path}.sides.r`);
+    const b = pickIntString(v.sides.b, errors, `${path}.sides.b`);
+    const l = pickIntString(v.sides.l, errors, `${path}.sides.l`);
+    if (t === undefined || r === undefined || b === undefined || l === undefined) {
+      return null;
+    }
+    out.SizeSet = "Each";
+    out.BorderSize = "";
+    out.Top = t;
+    out.Right = r;
+    out.Bottom = b;
+    out.Left = l;
+    if (v.sides.t != null) sourceMap["BorderStyle.Top"] = `${path}.sides.t`;
+    if (v.sides.r != null) sourceMap["BorderStyle.Right"] = `${path}.sides.r`;
+    if (v.sides.b != null) sourceMap["BorderStyle.Bottom"] = `${path}.sides.b`;
+    if (v.sides.l != null) sourceMap["BorderStyle.Left"] = `${path}.sides.l`;
+  } else {
+    out.SizeSet = "All";
+    if (v.size != null) {
+      const s = pickIntString(v.size, errors, `${path}.size`);
+      if (s === undefined) return null;
+      out.BorderSize = s;
+      sourceMap["BorderStyle.BorderSize"] = `${path}.size`;
+    } else {
+      out.BorderSize = 1;
+    }
+  }
+
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// radius object parser  (객체 form — per-corner)
+//   { tl?, tr?, br?, bl? }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CORNER_OBJ_KEYS = new Set(["tl", "tr", "br", "bl"]);
+
+function parseRadiusObject(v, path, errors, sourceMap) {
+  for (const k of Object.keys(v)) {
+    if (!CORNER_OBJ_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown radius key '${k}' — allowed: tl / tr / br / bl`,
+      );
+      return null;
+    }
+  }
+  const tl = pickIntString(v.tl, errors, `${path}.tl`);
+  const tr = pickIntString(v.tr, errors, `${path}.tr`);
+  const br = pickIntString(v.br, errors, `${path}.br`);
+  const bl = pickIntString(v.bl, errors, `${path}.bl`);
+  if (tl === undefined || tr === undefined || br === undefined || bl === undefined) {
+    return null;
+  }
+  if (v.tl != null) sourceMap["BorderStyle.RadiusTopLeft"] = `${path}.tl`;
+  if (v.tr != null) sourceMap["BorderStyle.RadiusTopRight"] = `${path}.tr`;
+  if (v.br != null) sourceMap["BorderStyle.RadiusBottomRight"] = `${path}.br`;
+  if (v.bl != null) sourceMap["BorderStyle.RadiusBottomLeft"] = `${path}.bl`;
+  return {
+    BorderRadius: "",
+    RadiusSet: "Each",
+    RadiusTopLeft: tl,
+    RadiusTopRight: tr,
+    RadiusBottomLeft: bl,
+    RadiusBottomRight: br,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// caption parser  (CaptionStyle)
+//   { font?: 5 roles, color? }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CAPTION_OBJ_KEYS = new Set(["text", "font", "color", "pos", "align"]);
+const CAPTION_POS_MAP = { left: "Left", top: "Top" };
+
+function parseCaption(v, path, errors, sourceMap) {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    pushErr(
+      errors,
+      path,
+      `caption must be an object { text?, font?, color?, pos?, align? }`,
+    );
+    return null;
+  }
+  for (const k of Object.keys(v)) {
+    if (!CAPTION_OBJ_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown caption key '${k}' — allowed: text / font / color / pos / align`,
+      );
+      return null;
+    }
+  }
+  const out = { UseDesign: true };
+  if (v.font != null) {
+    if (!CAPTION_TEXT_ROLES.has(v.font)) {
+      pushErr(
+        errors,
+        `${path}.font`,
+        `unknown caption typography role '${v.font}'`,
+        `caption supports: ${[...CAPTION_TEXT_ROLES].join(", ")}`,
+      );
+      return null;
+    }
+    const role = TOKENS.typography[v.font];
+    out.FontSize = role.FontSize;
+    out.FontWeight = role.FontWeight;
+    sourceMap["CaptionStyle.FontSize"] = `${path}.font`;
+    sourceMap["CaptionStyle.FontWeight"] = `${path}.font`;
+  }
+  if (v.color != null) {
+    const c = resolveSlot(
+      TOKENS.color,
+      v.color,
+      "caption color",
+      `${path}.color`,
+      errors,
+    );
+    if (c == null) return null;
+    out.FontColor = c;
+    sourceMap["CaptionStyle.FontColor"] = `${path}.color`;
+  }
+  if (v.pos != null) {
+    const cp = CAPTION_POS_MAP[v.pos];
+    if (cp == null) {
+      pushErr(
+        errors,
+        `${path}.pos`,
+        `unknown caption pos '${v.pos}' — use 'left' / 'top'`,
+      );
+      return null;
+    }
+    out.CaptionPosition = cp;
+    sourceMap["CaptionStyle.CaptionPosition"] = `${path}.pos`;
+  }
+  if (v.align != null) {
+    const fa = FONT_ALIGN[v.align];
+    if (fa == null) {
+      pushErr(
+        errors,
+        `${path}.align`,
+        `unknown caption align '${v.align}' — use 'start' / 'center' / 'end'`,
+      );
+      return null;
+    }
+    out.FontAlign = fa;
+    sourceMap["CaptionStyle.FontAlign"] = `${path}.align`;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// abs parser  (UseAbsoluteLayout + AbsolutePosition)
+//   { t?, r?, b?, l? } — spacing 패턴과 동일 (단 string shorthand 는 받지 않음)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function parseAbs(v, path, errors) {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    pushErr(errors, path, `abs must be { t?, r?, b?, l? } object`);
+    return null;
+  }
+  for (const k of Object.keys(v)) {
+    if (!SPACING_OBJ_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown abs key '${k}' — allowed: t / r / b / l`,
+      );
+      return null;
+    }
+  }
+  const t = pickIntString(v.t, errors, `${path}.t`);
+  const r = pickIntString(v.r, errors, `${path}.r`);
+  const b = pickIntString(v.b, errors, `${path}.b`);
+  const l = pickIntString(v.l, errors, `${path}.l`);
+  if (t === undefined || r === undefined || b === undefined || l === undefined) {
+    return null;
+  }
+  return {
+    UseEach: true,
+    UseAuto: true,
+    All: "",
+    Top: t,
+    Right: r,
+    Btm: b,
+    Left: l,
+    SizeUnit: "px",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// opacity parser
+//   <int 0..100>  →  UseOpacity:true + OpacityValue:"<n>"
+// ─────────────────────────────────────────────────────────────────────────────
+
+function parseOpacity(v, path, errors) {
+  if (typeof v !== "number" || !Number.isInteger(v)) {
+    pushErr(
+      errors,
+      path,
+      `opacity must be an integer 0..100 (got ${typeof v})`,
+    );
+    return null;
+  }
+  if (v < 0 || v > 100) {
+    pushErr(errors, path, `opacity out of range — must be 0..100 (got ${v})`);
+    return null;
+  }
+  return String(v);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// arrange parser  (Tab 헤더 컨테이너 안에서만 의미)
+//   { type?: match|equal|fixed, align?: left|center|right|between }
+//   → ArrangeItemsStyle: { UseArrangeItems, ArrangeItemsType, ArrangeItemsAlign }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ARRANGE_KEYS = new Set(["type", "align"]);
+const ARRANGE_TYPE_MAP = {
+  match: "MatchText",
+  equal: "EqualDistribution",
+  fixed: "Fixed",
+};
+const ARRANGE_ALIGN_MAP = {
+  left: "Left",
+  center: "Center",
+  right: "Right",
+  between: "Between",
+};
+
+function parseArrange(v, path, errors) {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    pushErr(errors, path, `arrange must be { type?, align? } object`);
+    return null;
+  }
+  for (const k of Object.keys(v)) {
+    if (!ARRANGE_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown arrange key '${k}' — allowed: type / align`,
+      );
+      return null;
+    }
+  }
+  const out = { UseArrangeItems: true };
+  if (v.type != null) {
+    const t = ARRANGE_TYPE_MAP[v.type];
+    if (t == null) {
+      pushErr(
+        errors,
+        `${path}.type`,
+        `unknown arrange type '${v.type}' — use match / equal / fixed`,
+      );
+      return null;
+    }
+    out.ArrangeItemsType = t;
+  }
+  if (v.align != null) {
+    const a = ARRANGE_ALIGN_MAP[v.align];
+    if (a == null) {
+      pushErr(
+        errors,
+        `${path}.align`,
+        `unknown arrange align '${v.align}' — use left / center / right / between`,
+      );
+      return null;
+    }
+    out.ArrangeItemsAlign = a;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// tabHeader parser  (Tab 컨트롤 4중 헤더 스타일)
+//
+// design.tabHeader: {
+//   container?:         { arrange?, p?, m?, border?, radius?, bg? }
+//   selectedContainer?: 동일
+//   item?:              { font?, color?, align?, p?, m?, border?, radius?, bg? }
+//   selectedItem?:      동일
+// }
+//
+// → raw {
+//   TabHeader: { ArrangeItemsStyle?, Padding?, Margin?, BorderStyle?, BgStyle? }
+//   SelectTabHeader: 동일
+//   TabHeaderItem: { FontStyle?, Padding?, Margin?, BorderStyle?, BgStyle? }
+//   SelectTabHeaderItem: 동일
+// }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const TAB_HEADER_SUB_BLOCKS = [
+  "container",
+  "selectedContainer",
+  "item",
+  "selectedItem",
+];
+const TAB_HEADER_BLOCK_TO_RAW = {
+  container: "TabHeader",
+  selectedContainer: "SelectTabHeader",
+  item: "TabHeaderItem",
+  selectedItem: "SelectTabHeaderItem",
+};
+const TAB_HEADER_CONTAINER_KEYS = new Set([
+  "arrange",
+  "p",
+  "m",
+  "border",
+  "radius",
+  "bg",
+]);
+const TAB_HEADER_ITEM_KEYS = new Set([
+  "font",
+  "color",
+  "align",
+  "p",
+  "m",
+  "border",
+  "radius",
+  "bg",
+]);
+
+function parseTabHeaderBlock(v, designPath, errors, opts) {
+  // opts: { kind: "container" | "item" }
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    pushErr(
+      errors,
+      designPath,
+      `tabHeader.${opts.kind} must be a plain object`,
+    );
+    return null;
+  }
+  const allowed =
+    opts.kind === "item" ? TAB_HEADER_ITEM_KEYS : TAB_HEADER_CONTAINER_KEYS;
+  for (const k of Object.keys(v)) {
+    if (!allowed.has(k)) {
+      pushErr(
+        errors,
+        `${designPath}.${k}`,
+        `unknown tabHeader.${opts.kind} key '${k}'`,
+        `allowed: ${[...allowed].join(" / ")}`,
+      );
+      return null;
+    }
+  }
+
+  // arrange 분리 — materializeDesign 의 KNOWN_KEYS 에 없으므로 사전 strip.
+  const { arrange, ...subDesign } = v;
+
+  // 부분집합 design 객체에 대해 materializeDesign 재귀 호출 — 기존 parser 재활용.
+  const {
+    raw: subRaw,
+    sourceMap: subMap,
+    errors: subErrors,
+  } = materializeDesign(subDesign, designPath);
+  if (subErrors.length > 0) errors.push(...subErrors);
+
+  if (opts.kind === "container" && arrange !== undefined) {
+    const ais = parseArrange(arrange, `${designPath}.arrange`, errors);
+    if (ais != null) {
+      subRaw.ArrangeItemsStyle = ais;
+      subMap["ArrangeItemsStyle"] = `${designPath}.arrange`;
+    }
+  }
+
+  return { block: subRaw, subMap };
+}
+
+function parseTabHeader(v, designPath, errors, sourceMap) {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    pushErr(
+      errors,
+      designPath,
+      `tabHeader must be an object { container?, selectedContainer?, item?, selectedItem? }`,
+    );
+    return null;
+  }
+  for (const k of Object.keys(v)) {
+    if (!TAB_HEADER_SUB_BLOCKS.includes(k)) {
+      pushErr(
+        errors,
+        `${designPath}.${k}`,
+        `unknown tabHeader key '${k}'`,
+        `allowed: ${TAB_HEADER_SUB_BLOCKS.join(" / ")}`,
+      );
+      return null;
+    }
+  }
+
+  const out = {};
+  for (const subKey of TAB_HEADER_SUB_BLOCKS) {
+    if (v[subKey] == null) continue;
+    const subPath = `${designPath}.${subKey}`;
+    const isItem = subKey === "item" || subKey === "selectedItem";
+    const result = parseTabHeaderBlock(v[subKey], subPath, errors, {
+      kind: isItem ? "item" : "container",
+    });
+    if (result == null || Object.keys(result.block).length === 0) continue;
+    const rawKey = TAB_HEADER_BLOCK_TO_RAW[subKey];
+    out[rawKey] = result.block;
+    // sub block 의 sourceMap leaf path 를 rawKey prefix 로 등록
+    for (const [leafPath, designSource] of Object.entries(result.subMap)) {
+      sourceMap[`${rawKey}.${leafPath}`] = designSource;
+    }
+    // 도메인 fallback
+    if (!Object.hasOwn(sourceMap, rawKey)) sourceMap[rawKey] = subPath;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 핵심 entry: design 객체 → { raw style fields, sourceMap, errors }
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * design 객체를 raw style 필드로 변환.
+ *
+ * @param design  사용자가 적은 design 객체.
+ * @param path    에러 메시지용 path prefix (default "$.design").
+ * @returns { raw, sourceMap, errors }
+ *   - raw       : control 에 머지될 style 필드들 (FontStyle, Width, ... 등).
+ *   - sourceMap : raw leaf path → design leaf path (역매핑용).
+ *   - errors    : 검증 실패 항목. raw 는 부분 결과로도 반환.
+ */
+export function materializeDesign(design, path = "$.design") {
+  const errors = [];
+  const raw = {};
+  const sourceMap = {};
+
+  if (design == null || typeof design !== "object" || Array.isArray(design)) {
+    pushErr(
+      errors,
+      path,
+      `design must be a plain object (got ${
+        design == null ? "null" : Array.isArray(design) ? "array" : typeof design
+      })`,
+    );
+    return { raw, sourceMap, errors };
+  }
+
+  // unknown key 검사
+  for (const k of Object.keys(design)) {
+    if (!KNOWN_KEYS.has(k)) {
+      pushErr(
+        errors,
+        `${path}.${k}`,
+        `unknown design key '${k}'`,
+        `allowed: ${[...KNOWN_KEYS].join(" / ")}`,
+      );
+    }
+  }
+
+  // ── surface 프리셋 확장 (Group 전용 매크로) ──────────────────────────────
+  // surface 는 bg/border/radius/elevation 의 고정 조합으로 풀린다. 프리셋이
+  // baseline 이고, 작성자가 같은 키를 명시하면 override (CSS shorthand 의미).
+  // 확장 결과는 기존 키 경로로 처리되므로 별도 parser/sourceMap 불필요.
+  // Group 한정 가드는 applyDesign 에서 (node type 을 알아야 하므로).
+  if (design.surface != null) {
+    if (!Object.hasOwn(SURFACE, design.surface)) {
+      pushErr(
+        errors,
+        `${path}.surface`,
+        `unknown surface preset '${design.surface}'`,
+        `available: ${Object.keys(SURFACE).join(", ")}`,
+      );
+      const { surface: _s, ...rest } = design;
+      design = rest;
+    } else {
+      const { surface: _s, ...rest } = design;
+      design = { ...SURFACE[design.surface], ...rest };
+    }
+  }
+
+  // ── FontStyle (font / color / align) ────────────────────────────────────
+  let font = null;
+  if (design.font != null) {
+    const role = resolveSlot(
+      TOKENS.typography,
+      design.font,
+      "typography role",
+      `${path}.font`,
+      errors,
+    );
+    if (role != null) {
+      font ??= { UseFont: true };
+      font.FontSize = role.FontSize;
+      font.FontWeight = role.FontWeight;
+      sourceMap["FontStyle.FontSize"] = `${path}.font`;
+      sourceMap["FontStyle.FontWeight"] = `${path}.font`;
+    }
+  }
+  if (design.color != null) {
+    const c = resolveSlot(
+      TOKENS.color,
+      design.color,
+      "text color",
+      `${path}.color`,
+      errors,
+    );
+    if (c != null) {
+      font ??= { UseFont: true };
+      font.FontColor = c;
+      sourceMap["FontStyle.FontColor"] = `${path}.color`;
+    }
+  }
+  if (design.align != null) {
+    const fa = FONT_ALIGN[design.align];
+    if (fa == null) {
+      pushErr(
+        errors,
+        `${path}.align`,
+        `unknown align '${design.align}' — use start / center / end`,
+      );
+    } else {
+      font ??= { UseFont: true };
+      font.FontAlign = fa;
+      sourceMap["FontStyle.FontAlign"] = `${path}.align`;
+    }
+  }
+  if (font != null) raw.FontStyle = font;
+
+  // ── Width / Height ──────────────────────────────────────────────────────
+  if (design.w != null) {
+    const w = parseSize(design.w, `${path}.w`, errors);
+    if (w != null) {
+      raw.Width = w;
+      sourceMap["Width"] = `${path}.w`;
+    }
+  }
+  if (design.h != null) {
+    const h = parseSize(design.h, `${path}.h`, errors);
+    if (h != null) {
+      // top caption 자동 보정 — 엔진은 Height 를 (caption 포함) 총 시각 예산으로
+      // 처리하므로 top caption 이 붙으면 입력 본체가 ~24px 만큼 압축된다. 작성자가
+      // `design.h` 를 본체 높이로 의도해도 결과는 줄어든 본체로 보임 — 그래서 caption
+      // pos:'top' (또는 pos 생략 = top default) 이면 Height 에 24px 를 자동 가산해
+      // 본체가 의도한 높이를 유지하도록 한다. 'px' 단위에서만 적용 — '%'/'vh'/'vw' 등은
+      // 의미가 모호하고 'text'/'full' 은 SizeValue 가산 자체가 의미 없음.
+      const cap = design.caption;
+      const topCaption =
+        cap != null && typeof cap === "object" &&
+        (cap.pos == null || cap.pos === "top");
+      if (topCaption && h.SizeUnit === "px") {
+        const n = Number(h.SizeValue);
+        if (Number.isFinite(n)) h.SizeValue = String(n + 24);
+      }
+      raw.Height = h;
+      sourceMap["Height"] = `${path}.h`;
+    }
+  }
+
+  // ── Padding / Margin ────────────────────────────────────────────────────
+  if (design.p != null) {
+    const p = parseSpacing(design.p, `${path}.p`, errors);
+    if (p != null) {
+      raw.Padding = p;
+      sourceMap["Padding"] = `${path}.p`;
+    }
+  }
+  if (design.m != null) {
+    const m = parseSpacing(design.m, `${path}.m`, errors);
+    if (m != null) {
+      raw.Margin = m;
+      sourceMap["Margin"] = `${path}.m`;
+    }
+  }
+
+  // ── BgStyle ─────────────────────────────────────────────────────────────
+  if (design.bg != null) {
+    const c = resolveSlot(
+      TOKENS.color,
+      design.bg,
+      "bg color",
+      `${path}.bg`,
+      errors,
+    );
+    if (c != null) {
+      raw.BgStyle = {
+        UseBackground: true,
+        BgColor: c,
+        UseImage: false,
+        Image: {},
+      };
+      sourceMap["BgStyle.BgColor"] = `${path}.bg`;
+    }
+  }
+
+  // ── BorderStyle (border / radius) ───────────────────────────────────────
+  const hasBorder = design.border != null;
+  const hasRadius = design.radius != null;
+  if (hasBorder || hasRadius) {
+    let bs = {};
+    if (hasBorder) {
+      if (design.border === false || design.border === "none") {
+        bs.Useborder = false;
+      } else if (typeof design.border === "string") {
+        // shorthand: color slot only
+        const c = resolveSlot(
+          TOKENS.color,
+          design.border,
+          "border color",
+          `${path}.border`,
+          errors,
+        );
+        if (c != null) {
+          bs.Useborder = true;
+          bs.BorderColor = c;
+          bs.BorderSize = 1;
+          bs.BorderType = "solid";
+          bs.SizeSet = "All";
+          sourceMap["BorderStyle.BorderColor"] = `${path}.border`;
+        }
+      } else if (
+        typeof design.border === "object" &&
+        !Array.isArray(design.border)
+      ) {
+        const bObj = parseBorderObject(
+          design.border,
+          `${path}.border`,
+          errors,
+          sourceMap,
+        );
+        if (bObj != null) bs = { ...bs, ...bObj };
+      } else {
+        pushErr(
+          errors,
+          `${path}.border`,
+          `border must be a color slot, false, 'none', or an object { color, type?, size? | sides? }`,
+        );
+      }
+    }
+    if (hasRadius) {
+      if (typeof design.radius === "string") {
+        const r = design.radius;
+        if (!INT_RE.test(r)) {
+          pushErr(
+            errors,
+            `${path}.radius`,
+            `radius must be a non-negative integer string (e.g. "16", "9999"; got '${r}')`,
+          );
+        } else {
+          bs.BorderRadius = r;
+          bs.RadiusSet = r === "9999" ? "None" : "All";
+          if (bs.Useborder == null) bs.Useborder = true;
+          sourceMap["BorderStyle.BorderRadius"] = `${path}.radius`;
+        }
+      } else if (
+        typeof design.radius === "object" &&
+        design.radius !== null &&
+        !Array.isArray(design.radius)
+      ) {
+        const rObj = parseRadiusObject(
+          design.radius,
+          `${path}.radius`,
+          errors,
+          sourceMap,
+        );
+        if (rObj != null) {
+          bs = { ...bs, ...rObj };
+          if (bs.Useborder == null) bs.Useborder = true;
+        }
+      } else {
+        pushErr(
+          errors,
+          `${path}.radius`,
+          `radius must be a non-negative integer string or { tl?, tr?, br?, bl? } object (got ${typeof design.radius})`,
+        );
+      }
+    }
+    if (Object.keys(bs).length > 0) raw.BorderStyle = bs;
+  }
+
+  // ── ContentStyle (elevation — shadow preset only) ───────────────────────
+  if (design.elevation != null) {
+    const cs = resolveSlot(
+      TOKENS.elevation,
+      design.elevation,
+      "elevation",
+      `${path}.elevation`,
+      errors,
+    );
+    if (cs != null) {
+      raw.ContentStyle = cs;
+      sourceMap["ContentStyle"] = `${path}.elevation`;
+    }
+  }
+
+  // ── DisplayStyle (flex) ─────────────────────────────────────────────────
+  if (design.flex != null) {
+    const ds = parseFlex(design.flex, `${path}.flex`, errors);
+    if (ds != null) {
+      raw.DisplayStyle = ds;
+      sourceMap["DisplayStyle"] = `${path}.flex`;
+    }
+  }
+
+  // ── CaptionStyle (+ 루트 Caption 내용) ──────────────────────────────────
+  if (design.caption != null) {
+    const cs = parseCaption(
+      design.caption,
+      `${path}.caption`,
+      errors,
+      sourceMap,
+    );
+    if (cs != null) raw.CaptionStyle = cs;
+    // caption.text → 루트 Caption (사용자 보이는 라벨 내용). CaptionStyle(스타일)
+    // 와 별개 필드. design 키 중 유일하게 content 를 담는 슬롯 (캡션 한정 예외).
+    const cap = design.caption;
+    if (
+      cap != null && typeof cap === "object" && !Array.isArray(cap) &&
+      cap.text != null
+    ) {
+      if (typeof cap.text !== "string") {
+        pushErr(
+          errors,
+          `${path}.caption.text`,
+          `caption.text must be a string (got ${typeof cap.text})`,
+        );
+      } else {
+        raw.Caption = cap.text;
+        sourceMap["Caption"] = `${path}.caption.text`;
+      }
+    }
+  }
+
+  // ── AbsolutePosition + UseAbsoluteLayout ────────────────────────────────
+  if (design.abs != null) {
+    const ap = parseAbs(design.abs, `${path}.abs`, errors);
+    if (ap != null) {
+      raw.UseAbsoluteLayout = true;
+      raw.AbsolutePosition = ap;
+      sourceMap["AbsolutePosition"] = `${path}.abs`;
+      sourceMap["UseAbsoluteLayout"] = `${path}.abs`;
+      if (design.abs.t != null) {
+        sourceMap["AbsolutePosition.Top"] = `${path}.abs.t`;
+      }
+      if (design.abs.r != null) {
+        sourceMap["AbsolutePosition.Right"] = `${path}.abs.r`;
+      }
+      if (design.abs.b != null) {
+        sourceMap["AbsolutePosition.Btm"] = `${path}.abs.b`;
+      }
+      if (design.abs.l != null) {
+        sourceMap["AbsolutePosition.Left"] = `${path}.abs.l`;
+      }
+    }
+  }
+
+  // ── UseOpacity + OpacityValue ───────────────────────────────────────────
+  if (design.opacity != null) {
+    const ov = parseOpacity(design.opacity, `${path}.opacity`, errors);
+    if (ov != null) {
+      raw.UseOpacity = true;
+      raw.OpacityValue = ov;
+      sourceMap["UseOpacity"] = `${path}.opacity`;
+      sourceMap["OpacityValue"] = `${path}.opacity`;
+    }
+  }
+
+  // ── ItemBgStyle (CheckBox / RadioBox 항목 기본 배경) ────────────────────
+  if (design.itemBg != null) {
+    const c = resolveSlot(
+      TOKENS.color,
+      design.itemBg,
+      "itemBg color",
+      `${path}.itemBg`,
+      errors,
+    );
+    if (c != null) {
+      raw.ItemBgStyle = {
+        UseBackground: true,
+        BgColor: c,
+        UseImage: false,
+        Image: {},
+      };
+      sourceMap["ItemBgStyle.BgColor"] = `${path}.itemBg`;
+    }
+  }
+
+  // ── TabHeader / SelectTabHeader / TabHeaderItem / SelectTabHeaderItem ───
+  if (design.tabHeader != null) {
+    const th = parseTabHeader(
+      design.tabHeader,
+      `${path}.tabHeader`,
+      errors,
+      sourceMap,
+    );
+    if (th != null) {
+      for (const [rawKey, val] of Object.entries(th)) {
+        raw[rawKey] = val;
+      }
+    }
+  }
+
+  // ── UseFixedSize ────────────────────────────────────────────────────────
+  if (design.fixed != null) {
+    if (typeof design.fixed !== "boolean") {
+      pushErr(
+        errors,
+        `${path}.fixed`,
+        `fixed must be boolean (got ${typeof design.fixed})`,
+      );
+    } else {
+      raw.UseFixedSize = design.fixed;
+      sourceMap["UseFixedSize"] = `${path}.fixed`;
+    }
+  }
+
+  // ── Domain-level fallback entries ───────────────────────────────────────
+  // FontStyle / BgStyle / BorderStyle / CaptionStyle 는 design 키가 leaf
+  // 단위로 매핑되지만, materializer 가 같이 emit 하는 파생 leaf (UseFont /
+  // UseBackground / Useborder / SizeSet / UseDesign 등) 는 leaf 매핑이 없다.
+  // 이런 leaf 의 Ajv 에러가 들어왔을 때 error-mapping 의 부모 fallback 이
+  // 도메인 단위로 잡을 수 있도록, 도메인 레벨 엔트리를 함께 둔다.
+  //
+  // Width / Height / Padding / Margin / DisplayStyle / ContentStyle /
+  // AbsolutePosition / UseAbsoluteLayout / UseOpacity / OpacityValue /
+  // UseFixedSize 는 위에서 이미 도메인 레벨 키로 매핑됐으므로 추가 불필요.
+  if (raw.FontStyle != null && !Object.hasOwn(sourceMap, "FontStyle")) {
+    sourceMap["FontStyle"] = path;
+  }
+  if (raw.BgStyle != null && !Object.hasOwn(sourceMap, "BgStyle")) {
+    sourceMap["BgStyle"] = path;
+  }
+  if (raw.BorderStyle != null && !Object.hasOwn(sourceMap, "BorderStyle")) {
+    sourceMap["BorderStyle"] = path;
+  }
+  if (raw.CaptionStyle != null && !Object.hasOwn(sourceMap, "CaptionStyle")) {
+    sourceMap["CaptionStyle"] = `${path}.caption`;
+  }
+  if (raw.ItemBgStyle != null && !Object.hasOwn(sourceMap, "ItemBgStyle")) {
+    sourceMap["ItemBgStyle"] = `${path}.itemBg`;
+  }
+
+  return { raw, sourceMap, errors };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// applyDesign — control 노드에서 design 키를 expand 하고 raw 와 머지.
+//
+// 머지 규칙: leaf 단위. design 이 쓴 leaf 는 raw 의 같은 leaf 를 덮어쓰고,
+// design 이 안 건드린 leaf 는 raw 그대로 보존. style 객체가 통째로 design 에서만
+// 나온 경우엔 그 객체가 그대로 들어감.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Group 기본 Width — w 미지정 시 content-sized(text). MatchText 는 boolean
+// (style-objects.schema.json). design 키 유무와 무관하게 모든 Group 에 적용.
+const GROUP_DEFAULT_WIDTH = Object.freeze({
+  MatchText: true,
+  SizeValue: "",
+  SizeUnit: "text",
+});
+
+/**
+ * @param control control 객체 (design 키 가질 수 있음).
+ * @param path    부모 경로 (에러용; default "$").
+ * @returns { control, sourceMap, errors }
+ */
+export function applyDesign(control, path = "$") {
+  if (control == null || typeof control !== "object" || Array.isArray(control)) {
+    return { control, sourceMap: {}, errors: [] };
+  }
+  // design 키 없는 노드 — Group 이고 Width 가 없으면 기본 Width 만 주입 후 반환.
+  // (raw Group 도 Width 없이 렌더되지 않도록. 패턴 산출 Group 은 makeGroup 이
+  //  이미 Width 100% 를 세팅하므로 이 가드를 건너뛴다.)
+  if (control.design == null) {
+    if (control.ContentsType === "Group" && control.Width == null) {
+      return {
+        control: { ...control, Width: { ...GROUP_DEFAULT_WIDTH } },
+        sourceMap: {},
+        errors: [],
+      };
+    }
+    return { control, sourceMap: {}, errors: [] };
+  }
+
+  const designPath = `${path}.design`;
+  const preErrors = [];
+
+  // flex 는 Group 전용 — Group 이 아닌 컨테이너 (Control 등) 에서는 거부.
+  // 잘못된 DisplayStyle 이 emit 되지 않도록 input 에서 flex 키를 strip.
+  let designInput = control.design;
+  const isGroup = control.ContentsType === "Group";
+  if (designInput.flex != null && !isGroup) {
+    pushErr(
+      preErrors,
+      `${designPath}.flex`,
+      `flex is allowed only on Groups (ContentsType:'Group') — controls do not compose children`,
+      `wrap children in a Group, or remove the flex key`,
+    );
+    const { flex: _f, ...rest } = designInput;
+    designInput = rest;
+  }
+
+  // surface 프리셋도 Group 전용 — Paper 는 컨테이너 개념. Control 에서는 거부.
+  if (designInput.surface != null && !isGroup) {
+    pushErr(
+      preErrors,
+      `${designPath}.surface`,
+      `surface preset is allowed only on Groups (ContentsType:'Group') — it styles a container surface`,
+      `wrap content in a Group, or use bg/border/radius/elevation directly on the control`,
+    );
+    const { surface: _s, ...rest } = designInput;
+    designInput = rest;
+  }
+
+  const { raw, sourceMap, errors } = materializeDesign(designInput, designPath);
+  if (preErrors.length > 0) errors.unshift(...preErrors);
+
+  const { design: _omit, ...rest } = control;
+  const out = { ...rest };
+
+  for (const [domain, designVal] of Object.entries(raw)) {
+    const rawVal = out[domain];
+    if (
+      rawVal != null &&
+      typeof rawVal === "object" &&
+      typeof designVal === "object" &&
+      !Array.isArray(rawVal) &&
+      !Array.isArray(designVal)
+    ) {
+      out[domain] = { ...rawVal, ...designVal };
+    } else {
+      out[domain] = designVal;
+    }
+  }
+
+  // Group 기본 Width — design.w 미지정 & 기존 raw Width 없음이면 content-sized(text)
+  // 기본 메타를 삽입 (디자인 키 있는 Group 경로; 디자인 키 없는 Group 은 위 early-return).
+  if (isGroup && out.Width == null) {
+    out.Width = { ...GROUP_DEFAULT_WIDTH };
+  }
+
+  return { control: out, sourceMap, errors };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// introspection (테스트 / 디버깅 / get_design_grammar tool 용)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const designTokens = Object.freeze(TOKENS);
+export const designKnownKeys = Object.freeze([...KNOWN_KEYS]);