design-constraint-validator 2.0.1 → 2.1.0

package/core/dtcg.js

@@ -0,0 +1,88 @@
+/**
+ * DTCG 2025.10 stable-spec value normalization.
+ *
+ * The stable spec (2025-10-28) made color and dimension tokens **structured
+ * objects** rather than CSS strings — e.g. Figma's native export emits
+ *   { "colorSpace": "srgb", "components": [0.53, 0.53, 0.53], "alpha": 1, "hex": "#888888" }
+ * and
+ *   { "value": 16, "unit": "px" }.
+ *
+ * The engine and constraint plugins (WCAG, threshold, monotonic) consume the
+ * legacy string/number forms. We normalize structured values to those forms in
+ * ONE place — the flatten boundary — so `core/color.ts`'s verified math stays
+ * untouched and string aliases (`"{dot.path}"`) keep flowing through unchanged.
+ *
+ * Non-sRGB color spaces are deliberately NOT coerced into sRGB math: we refuse
+ * to treat e.g. display-p3 components as sRGB (that would silently corrupt
+ * contrast). Without a `hex` fallback they normalize to a sentinel string that
+ * the color parser rejects, producing an explicit "Unparseable color(s)"
+ * warning naming the color space — never a wrong-but-silent ratio.
+ */
+function toByte(c) {
+    return Math.max(0, Math.min(255, Math.round(c * 255)));
+}
+function srgbComponentsToCss(c) {
+    if (!Array.isArray(c.components) || c.components.length < 3)
+        return null;
+    const [r, g, b] = c.components;
+    if (![r, g, b].every((n) => typeof n === 'number' && Number.isFinite(n)))
+        return null;
+    const a = typeof c.alpha === 'number' ? c.alpha : 1;
+    const R = toByte(r);
+    const G = toByte(g);
+    const B = toByte(b);
+    if (a >= 1) {
+        const hx = (n) => n.toString(16).padStart(2, '0');
+        return `#${hx(R)}${hx(G)}${hx(B)}`;
+    }
+    return `rgba(${R}, ${G}, ${B}, ${a})`;
+}
+function normalizeColor(v) {
+    // Prefer the spec's `hex` convenience field when present (works for any space).
+    if (typeof v.hex === 'string' && v.hex.trim())
+        return v.hex.trim();
+    // Only gamma-encoded sRGB components map 1:1 to the existing color math.
+    if ((v.colorSpace ?? '').toLowerCase() === 'srgb') {
+        const css = srgbComponentsToCss(v);
+        if (css)
+            return css;
+    }
+    // Unsupported space with no hex fallback → sentinel the parser rejects.
+    return `<unsupported colorSpace: ${v.colorSpace ?? 'unknown'}>`;
+}
+function normalizeDimension(v) {
+    if (typeof v.value !== 'number' || !Number.isFinite(v.value)) {
+        return '<invalid dimension>';
+    }
+    const unit = typeof v.unit === 'string' && v.unit ? v.unit : 'px';
+    return `${v.value}${unit}`;
+}
+function isColorObject(obj, type) {
+    return ((type ?? '').toLowerCase() === 'color' ||
+        'colorSpace' in obj ||
+        'components' in obj ||
+        'hex' in obj);
+}
+function isDimensionObject(obj, type) {
+    return (type ?? '').toLowerCase() === 'dimension' || ('value' in obj && 'unit' in obj);
+}
+/**
+ * Normalize a raw DTCG `$value` to the string/number form the engine expects.
+ * Strings (including `"{alias}"` references) and numbers pass through untouched.
+ * Structured objects are converted; unrecognized objects (composite types such
+ * as typography/shadow — out of scope) become a non-crashing sentinel string.
+ */
+export function normalizeDtcgValue(raw, type) {
+    if (typeof raw === 'string' || typeof raw === 'number')
+        return raw;
+    if (raw && typeof raw === 'object') {
+        const obj = raw;
+        if (isColorObject(obj, type))
+            return normalizeColor(obj);
+        if (isDimensionObject(obj, type))
+            return normalizeDimension(obj);
+        return `<unsupported $value: ${(type ?? 'object').toLowerCase()}>`;
+    }
+    // null / undefined / boolean — return an empty string so nothing downstream crashes.
+    return '';
+}

package/core/dtcg.ts

@@ -0,0 +1,102 @@
+/**
+ * DTCG 2025.10 stable-spec value normalization.
+ *
+ * The stable spec (2025-10-28) made color and dimension tokens **structured
+ * objects** rather than CSS strings — e.g. Figma's native export emits
+ *   { "colorSpace": "srgb", "components": [0.53, 0.53, 0.53], "alpha": 1, "hex": "#888888" }
+ * and
+ *   { "value": 16, "unit": "px" }.
+ *
+ * The engine and constraint plugins (WCAG, threshold, monotonic) consume the
+ * legacy string/number forms. We normalize structured values to those forms in
+ * ONE place — the flatten boundary — so `core/color.ts`'s verified math stays
+ * untouched and string aliases (`"{dot.path}"`) keep flowing through unchanged.
+ *
+ * Non-sRGB color spaces are deliberately NOT coerced into sRGB math: we refuse
+ * to treat e.g. display-p3 components as sRGB (that would silently corrupt
+ * contrast). Without a `hex` fallback they normalize to a sentinel string that
+ * the color parser rejects, producing an explicit "Unparseable color(s)"
+ * warning naming the color space — never a wrong-but-silent ratio.
+ */
+
+export type DtcgColorValue = {
+  colorSpace?: string;
+  components?: number[];
+  alpha?: number;
+  hex?: string;
+};
+
+export type DtcgDimensionValue = {
+  value?: number;
+  unit?: string;
+};
+
+function toByte(c: number): number {
+  return Math.max(0, Math.min(255, Math.round(c * 255)));
+}
+
+function srgbComponentsToCss(c: DtcgColorValue): string | null {
+  if (!Array.isArray(c.components) || c.components.length < 3) return null;
+  const [r, g, b] = c.components;
+  if (![r, g, b].every((n) => typeof n === 'number' && Number.isFinite(n))) return null;
+  const a = typeof c.alpha === 'number' ? c.alpha : 1;
+  const R = toByte(r);
+  const G = toByte(g);
+  const B = toByte(b);
+  if (a >= 1) {
+    const hx = (n: number) => n.toString(16).padStart(2, '0');
+    return `#${hx(R)}${hx(G)}${hx(B)}`;
+  }
+  return `rgba(${R}, ${G}, ${B}, ${a})`;
+}
+
+function normalizeColor(v: DtcgColorValue): string {
+  // Prefer the spec's `hex` convenience field when present (works for any space).
+  if (typeof v.hex === 'string' && v.hex.trim()) return v.hex.trim();
+  // Only gamma-encoded sRGB components map 1:1 to the existing color math.
+  if ((v.colorSpace ?? '').toLowerCase() === 'srgb') {
+    const css = srgbComponentsToCss(v);
+    if (css) return css;
+  }
+  // Unsupported space with no hex fallback → sentinel the parser rejects.
+  return `<unsupported colorSpace: ${v.colorSpace ?? 'unknown'}>`;
+}
+
+function normalizeDimension(v: DtcgDimensionValue): string {
+  if (typeof v.value !== 'number' || !Number.isFinite(v.value)) {
+    return '<invalid dimension>';
+  }
+  const unit = typeof v.unit === 'string' && v.unit ? v.unit : 'px';
+  return `${v.value}${unit}`;
+}
+
+function isColorObject(obj: Record<string, unknown>, type?: string): boolean {
+  return (
+    (type ?? '').toLowerCase() === 'color' ||
+    'colorSpace' in obj ||
+    'components' in obj ||
+    'hex' in obj
+  );
+}
+
+function isDimensionObject(obj: Record<string, unknown>, type?: string): boolean {
+  return (type ?? '').toLowerCase() === 'dimension' || ('value' in obj && 'unit' in obj);
+}
+
+/**
+ * Normalize a raw DTCG `$value` to the string/number form the engine expects.
+ * Strings (including `"{alias}"` references) and numbers pass through untouched.
+ * Structured objects are converted; unrecognized objects (composite types such
+ * as typography/shadow — out of scope) become a non-crashing sentinel string.
+ */
+export function normalizeDtcgValue(raw: unknown, type?: string): string | number {
+  if (typeof raw === 'string' || typeof raw === 'number') return raw;
+  if (raw && typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>;
+    if (isColorObject(obj, type)) return normalizeColor(obj as DtcgColorValue);
+    if (isDimensionObject(obj, type)) return normalizeDimension(obj as DtcgDimensionValue);
+    return `<unsupported $value: ${(type ?? 'object').toLowerCase()}>`;
+  }
+  // null / undefined / boolean — return an empty string so nothing downstream crashes.
+  return '';
+}

package/core/engine.d.ts

@@ -26,6 +26,12 @@ export type ConstraintIssue = {
      * this captures that reference edge.
      */
     involvedEdges?: Array<[TokenId, TokenId]>;
+    /**
+     * Structured, rule-specific data for JSON consumers.
+     * For example, WCAG contrast issues can expose actual/required ratios here
+     * without forcing callers to parse human-readable messages.
+     */
+    metadata?: Record<string, unknown>;
 };
 /**
  * Constraint plugin interface.

package/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAE5B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IACxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAElC;;;;;;;OAOG;IACH,SAAS,IAAI,OAAO,EAAE;IAItB;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC;IAI5C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAatC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IAIjC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAE5B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IACxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAElC;;;;;;;OAOG;IACH,SAAS,IAAI,OAAO,EAAE;IAItB;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC;IAI5C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAatC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IAIjC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}

package/core/engine.ts

@@ -29,6 +29,13 @@ export type ConstraintIssue = {
    * this captures that reference edge.
    */
   involvedEdges?: Array<[TokenId, TokenId]>;
+
+  /**
+   * Structured, rule-specific data for JSON consumers.
+   * For example, WCAG contrast issues can expose actual/required ratios here
+   * without forcing callers to parse human-readable messages.
+   */
+  metadata?: Record<string, unknown>;
 };
 
 /**

package/core/flatten.d.ts

@@ -1,15 +1,17 @@
 export type TokenId = string;
 export type TokenValue = string | number;
+export type DtcgStructuredValue = Record<string, unknown>;
 export type TokenNode = {
     $type?: string;
-    $value?: TokenValue;
-    [k: string]: TokenNode | string | number | undefined;
+    $value?: TokenValue | DtcgStructuredValue;
+    $extensions?: DtcgStructuredValue;
+    [k: string]: TokenNode | string | number | DtcgStructuredValue | undefined;
 };
 export type FlatToken = {
     id: TokenId;
     type: string;
     value: TokenValue;
-    raw: TokenValue;
+    raw: TokenValue | DtcgStructuredValue;
     refs: TokenId[];
 };
 export type FlattenResult = {

package/core/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["flatten.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAIF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CA4F5D"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["flatten.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAGzC,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAAC;IAC1C,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;CAC5E,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,UAAU,GAAG,mBAAmB,CAAC;IACtC,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAKF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CA4G5D"}

package/core/flatten.js

@@ -1,4 +1,6 @@
-const REF_RE = /\{([a-z0-9.-]+)\}/gi;
+import { normalizeDtcgValue } from "./dtcg.js";
+const REF_RE = /\{([a-z0-9_.-]+)\}/gi;
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 export function flattenTokens(root) {
     const flat = {};
     const edges = [];
@@ -8,13 +10,17 @@ export function flattenTokens(root) {
             return;
         if (Object.prototype.hasOwnProperty.call(node, '$value')) {
             const id = path.join('.');
-            const raw = node.$value;
-            if (raw === undefined)
+            if (node.$value === undefined)
                 return; // Skip tokens without values
+            // Normalize DTCG 2025.10 structured color/dimension objects to the
+            // string/number form the engine + plugins expect (strings, incl. aliases,
+            // pass through unchanged). Keeps the color math in core/color.ts untouched.
+            const raw = node.$value;
+            const normalized = normalizeDtcgValue(raw, node.$type);
             const refs = [];
             // Find all references in the value
-            if (typeof raw === 'string') {
-                const matches = raw.matchAll(REF_RE);
+            if (typeof normalized === 'string') {
+                const matches = normalized.matchAll(REF_RE);
                 for (const match of matches) {
                     refs.push(match[1]);
                 }
@@ -22,7 +28,7 @@ export function flattenTokens(root) {
             flat[id] = {
                 id,
                 type: String(node.$type ?? 'unknown'),
-                value: raw,
+                value: normalized,
                 raw,
                 refs
             };
@@ -44,7 +50,7 @@ export function flattenTokens(root) {
     // Second pass: resolve references iteratively
     let changed = true;
     let iterations = 0;
-    const maxIterations = Object.keys(flat).length * 2; // Safety limit
+    const maxIterations = Object.keys(flat).length * 2 + 1; // Safety limit (never 0)
     while (changed && iterations < maxIterations) {
         changed = false;
         iterations++;
@@ -63,7 +69,7 @@ export function flattenTokens(root) {
                         break;
                     }
                     // Replace the reference with the resolved value
-                    const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
+                    const refPattern = new RegExp(`\\{${escapeRegExp(refId)}\\}`, 'g');
                     newValue = newValue.replace(refPattern, String(refToken.value));
                 }
                 if (fullyResolved && newValue !== token.value) {
@@ -73,8 +79,16 @@ export function flattenTokens(root) {
             }
         }
     }
-    if (iterations >= maxIterations) {
-        throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
+    // A token still carrying an unresolved "{ref}" placeholder after the fixpoint
+    // means a genuine cycle (a -> b -> a) or a self-reference. An empty or
+    // fully-literal token set resolves cleanly and must never trip this guard —
+    // the old `iterations >= maxIterations` check threw a bogus "circular
+    // reference" error whenever no tokens were found (maxIterations === 0).
+    const unresolved = Object.values(flat).filter((t) => typeof t.value === 'string' && t.value.includes('{'));
+    if (unresolved.length > 0) {
+        throw new Error(`Token resolution exceeded maximum iterations - possible circular reference (unresolved: ${unresolved
+            .map((t) => t.id)
+            .join(', ')})`);
     }
     return { flat, edges };
 }

package/core/flatten.ts

@@ -1,16 +1,22 @@
+import { normalizeDtcgValue } from "./dtcg.js";
+
 export type TokenId = string; // e.g. "color.palette.brand.600"
 export type TokenValue = string | number;
-export type TokenNode = { 
-  $type?: string; 
-  $value?: TokenValue; 
-  [k: string]: TokenNode | string | number | undefined;
+// $value may also be a DTCG 2025.10 structured object (color / dimension); it is
+// normalized to a TokenValue at ingestion. See normalizeDtcgValue.
+export type DtcgStructuredValue = Record<string, unknown>;
+export type TokenNode = {
+  $type?: string;
+  $value?: TokenValue | DtcgStructuredValue;
+  $extensions?: DtcgStructuredValue; // spec passthrough — preserved, never interpreted
+  [k: string]: TokenNode | string | number | DtcgStructuredValue | undefined;
 };
 
 export type FlatToken = {
   id: TokenId;
   type: string;
   value: TokenValue;       // resolved (if ref)
-  raw: TokenValue;         // original $value
+  raw: TokenValue | DtcgStructuredValue; // original $value
   refs: TokenId[];         // referenced token IDs found in raw
 };
 
@@ -19,7 +25,8 @@ export type FlattenResult = {
   edges: Array<[from: TokenId, to: TokenId]>; // from ref -> to dependent
 };
 
-const REF_RE = /\{([a-z0-9.-]+)\}/gi;
+const REF_RE = /\{([a-z0-9_.-]+)\}/gi;
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 export function flattenTokens(root: TokenNode): FlattenResult {
   const flat: Record<TokenId, FlatToken> = {};
@@ -31,14 +38,18 @@ export function flattenTokens(root: TokenNode): FlattenResult {
     
     if (Object.prototype.hasOwnProperty.call(node, '$value')) {
       const id = path.join('.');
+      if (node.$value === undefined) return; // Skip tokens without values
+      // Normalize DTCG 2025.10 structured color/dimension objects to the
+      // string/number form the engine + plugins expect (strings, incl. aliases,
+      // pass through unchanged). Keeps the color math in core/color.ts untouched.
       const raw = node.$value;
-      if (raw === undefined) return; // Skip tokens without values
-      
+      const normalized = normalizeDtcgValue(raw, node.$type);
+
       const refs: TokenId[] = [];
       
       // Find all references in the value
-      if (typeof raw === 'string') {
-        const matches = raw.matchAll(REF_RE);
+      if (typeof normalized === 'string') {
+        const matches = normalized.matchAll(REF_RE);
         for (const match of matches) {
           refs.push(match[1]);
         }
@@ -47,7 +58,7 @@ export function flattenTokens(root: TokenNode): FlattenResult {
       flat[id] = { 
         id, 
         type: String(node.$type ?? 'unknown'), 
-        value: raw,
+        value: normalized,
         raw, 
         refs 
       };
@@ -72,8 +83,8 @@ export function flattenTokens(root: TokenNode): FlattenResult {
   // Second pass: resolve references iteratively
   let changed = true;
   let iterations = 0;
-  const maxIterations = Object.keys(flat).length * 2; // Safety limit
-  
+  const maxIterations = Object.keys(flat).length * 2 + 1; // Safety limit (never 0)
+
   while (changed && iterations < maxIterations) {
     changed = false;
     iterations++;
@@ -96,7 +107,7 @@ export function flattenTokens(root: TokenNode): FlattenResult {
           }
           
           // Replace the reference with the resolved value
-          const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
+          const refPattern = new RegExp(`\\{${escapeRegExp(refId)}\\}`, 'g');
           newValue = newValue.replace(refPattern, String(refToken.value));
         }
         
@@ -108,8 +119,20 @@ export function flattenTokens(root: TokenNode): FlattenResult {
     }
   }
   
-  if (iterations >= maxIterations) {
-    throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
+  // A token still carrying an unresolved "{ref}" placeholder after the fixpoint
+  // means a genuine cycle (a -> b -> a) or a self-reference. An empty or
+  // fully-literal token set resolves cleanly and must never trip this guard —
+  // the old `iterations >= maxIterations` check threw a bogus "circular
+  // reference" error whenever no tokens were found (maxIterations === 0).
+  const unresolved = Object.values(flat).filter(
+    (t) => typeof t.value === 'string' && t.value.includes('{'),
+  );
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Token resolution exceeded maximum iterations - possible circular reference (unresolved: ${unresolved
+        .map((t) => t.id)
+        .join(', ')})`,
+    );
   }
 
   return { flat, edges };

package/core/image-export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-export.d.ts","sourceRoot":"","sources":["image-export.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AACrC,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzC,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EAAe,6BAA6B;AAC7D,OAAO,EAAE,MAAM,EAAiB,wBAAwB;AACxD,GAAG,EAAE,QAAQ,EAAmB,gBAAgB;AAChD,QAAQ,EAAE,QAAQ,GACjB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAoBhC"}
+{"version":3,"file":"image-export.d.ts","sourceRoot":"","sources":["image-export.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AACrC,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzC,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EAAe,6BAA6B;AAC7D,OAAO,EAAE,MAAM,EAAiB,wBAAwB;AACxD,GAAG,EAAE,QAAQ,EAAmB,gBAAgB;AAChD,QAAQ,EAAE,QAAQ,GACjB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAoBhC"}

package/core/image-export.js

@@ -5,13 +5,16 @@ import { spawnSync } from "node:child_process";
 function which(cmd) {
     const paths = (process.env.PATH || "").split(path.delimiter);
     for (const p of paths) {
-        const full = path.join(p, cmd + (process.platform === "win32" ? ".cmd" : ""));
-        try {
-            fs.accessSync(full, fs.constants.X_OK);
-            return full;
-        }
-        catch {
-            // File not accessible, continue to next path
+        const names = process.platform === "win32" ? [cmd + ".cmd", cmd + ".exe", cmd] : [cmd];
+        for (const name of names) {
+            const full = path.join(p, name);
+            try {
+                fs.accessSync(full, fs.constants.X_OK);
+                return full;
+            }
+            catch {
+                // File not accessible, continue to next path
+            }
         }
     }
     return null;

package/core/image-export.ts

@@ -6,12 +6,15 @@ import { spawnSync } from "node:child_process";
 function which(cmd: string): string | null {
   const paths = (process.env.PATH || "").split(path.delimiter);
   for (const p of paths) {
-    const full = path.join(p, cmd + (process.platform === "win32" ? ".cmd" : ""));
-    try { 
-      fs.accessSync(full, fs.constants.X_OK); 
-      return full; 
-    } catch {
-      // File not accessible, continue to next path
+    const names = process.platform === "win32" ? [cmd + ".cmd", cmd + ".exe", cmd] : [cmd];
+    for (const name of names) {
+      const full = path.join(p, name);
+      try {
+        fs.accessSync(full, fs.constants.X_OK);
+        return full;
+      } catch {
+        // File not accessible, continue to next path
+      }
     }
   }
   return null;

package/core/index.d.ts

@@ -7,4 +7,6 @@
 export type { TokenId, TokenValue } from "./flatten.js";
 export type { ConstraintIssue, ConstraintPlugin, Graph } from "./engine.js";
 export { Engine } from "./engine.js";
+export { validate } from "../cli/validate-api.js";
+export type { ValidateInput, ValidateResult } from "../cli/validate-api.js";
 //# sourceMappingURL=index.d.ts.map

package/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAKrC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/core/index.js

@@ -5,3 +5,7 @@
  * See engine.ts for full implementation with Phase 3C enhancements.
  */
 export { Engine } from "./engine.js";
+// Programmatic convenience API (validate tokens against constraints in one call).
+// Implemented in the CLI layer atop the shared registry; surfaced here as the
+// package's public entry point.
+export { validate } from "../cli/validate-api.js";

package/core/index.ts

@@ -8,3 +8,9 @@
 export type { TokenId, TokenValue } from "./flatten.js";
 export type { ConstraintIssue, ConstraintPlugin, Graph } from "./engine.js";
 export { Engine } from "./engine.js";
+
+// Programmatic convenience API (validate tokens against constraints in one call).
+// Implemented in the CLI layer atop the shared registry; surfaced here as the
+// package's public entry point.
+export { validate } from "../cli/validate-api.js";
+export type { ValidateInput, ValidateResult } from "../cli/validate-api.js";

package/core/why.d.ts

@@ -2,7 +2,7 @@ import type { FlatToken } from "./flatten.js";
 export type WhyReport = {
     id: string;
     value: string | number | undefined;
-    raw?: string | number;
+    raw?: unknown;
     refs?: string[];
     provenance: "base" | "theme" | "override" | "unknown";
     dependsOn: string[];

package/core/why.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAQxF;AAED,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,EAC7B,MAAM,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAO,GACpF,SAAS,CAkCX"}
+{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAQxF;AAED,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,EAC7B,MAAM,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAO,GACpF,SAAS,CAkCX"}

package/core/why.ts

@@ -3,7 +3,7 @@ import type { FlatToken } from "./flatten.js";
 export type WhyReport = {
   id: string;
   value: string | number | undefined;
-  raw?: string | number;
+  raw?: unknown;
   refs?: string[];
   provenance: "base" | "theme" | "override" | "unknown";
   dependsOn: string[];     // immediate refs (parents)