design-constraint-validator 2.2.1 → 2.3.0

package/README.md

@@ -18,6 +18,10 @@
 
 This is **not** a schema linter; it's a **reasoning validator** for values and relationships.
 
+![DCV at a glance — one engine with three entry points (CLI, Library API, MCP server) over a shared validation core that flattens tokens, builds the engine, loads constraints, runs plugins, and reports errors/warnings.](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-at-a-glance.png)
+
+![DCV validation pipeline — token files → flatten & resolve → build engine → load constraints → run plugins → report results; CLI, API, and MCP all use the same flow.](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-pipeline.png)
+
 ---
 
 ## Installation
@@ -183,6 +187,8 @@ Conventional linters catch **schema** issues ("has a value, has a type").
 
 This transforms tokens from "bags of numbers" into a **formal design system**.
 
+![What DCV checks — five plugin families: WCAG contrast, monotonic order, lightness ordering, thresholds, and cross-axis rules; every plugin returns a structured issue (rule, level, message, involved tokens, metadata).](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-plugins.png)
+
 ---
 
 ## Comparison: Schema Linters vs DCV
@@ -194,6 +200,8 @@ This transforms tokens from "bags of numbers" into a **formal design system**.
 | **Purpose** | Format compliance | Design system integrity |
 | **Examples** | DTCG schema validator | WCAG checks, monotonic scales |
 
+![Mathematical Integrity for Design Systems — the DCV engine: the three core constraint types (accessibility & contrast, monotonic & lightness ordering, thresholds & cross-axis rules), one engine with three interfaces (CLI, library API, MCP server), and the difference between schema linters (format compliance) and DCV (mathematical relationships / design-system integrity).](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-overview.png)
+
 > DCV is not affiliated with Anima's `design-tokens-validator` (schema-focused).
 
 ---

package/adapters/css.d.ts

@@ -2,6 +2,20 @@ export type TokenId = string;
 export type TokenValue = string | number;
 export type VarMapper = (id: TokenId) => string | null;
 export declare const defaultVarMapper: VarMapper;
+/**
+ * A CSS custom-property value derived from a token must not break out of its
+ * declaration (TASK-035 C). `;`, `{`, `}` and comment markers can't appear in a
+ * well-formed token value, so strip them — a malformed value can otherwise
+ * inject or corrupt sibling declarations.
+ */
+export declare function sanitizeCssValue(v: string): string;
+/**
+ * Detect non-injective var mapping (TASK-035 C): `defaultVarMapper` collapses
+ * both `.` and other separators to `-`, so distinct ids like `a.b` and `a-b` map
+ * to the same `--a-b` and would silently overwrite each other in CSS/JSON/JS.
+ * Throw a clear error naming the colliding ids rather than dropping a token.
+ */
+export declare function assertNoVarCollisions(ids: Iterable<string>, resolve: (id: string) => string | null): void;
 export type ManifestRow = {
     id: string;
     canonicalVar?: string | null;

package/adapters/css.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["css.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAIzC,MAAM,MAAM,SAAS,GAAG,CAAC,EAAE,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;AAEvD,eAAO,MAAM,gBAAgB,EAAE,SAC4C,CAAC;AAG5E,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,UAAU;IAAG,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE;AAEpE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAsBxG;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,SAAS,CAIxE;AAgCD;;GAEG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EACnC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACzF,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAClC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACzF,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,OAAO,EAAE,MAAM,QAEzF"}
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["css.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAIzC,MAAM,MAAM,SAAS,GAAG,CAAC,EAAE,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;AAEvD,eAAO,MAAM,gBAAgB,EAAE,SAC4C,CAAC;AAE5E;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,IAAI,CAczG;AAGD,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,UAAU;IAAG,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE;AAEpE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAsBxG;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,SAAS,CAIxE;AAkCD;;GAEG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EACnC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACzF,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAClC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACzF,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,OAAO,EAAE,MAAM,QAEzF"}

package/adapters/css.js

@@ -1,4 +1,33 @@
 export const defaultVarMapper = (id) => `--${id.replace(/[^a-z0-9.]/gi, "-").replace(/\.+/g, "-").toLowerCase()}`;
+/**
+ * A CSS custom-property value derived from a token must not break out of its
+ * declaration (TASK-035 C). `;`, `{`, `}` and comment markers can't appear in a
+ * well-formed token value, so strip them — a malformed value can otherwise
+ * inject or corrupt sibling declarations.
+ */
+export function sanitizeCssValue(v) {
+    return v.replace(/\/\*|\*\//g, "").replace(/[;{}]/g, "").trim();
+}
+/**
+ * Detect non-injective var mapping (TASK-035 C): `defaultVarMapper` collapses
+ * both `.` and other separators to `-`, so distinct ids like `a.b` and `a-b` map
+ * to the same `--a-b` and would silently overwrite each other in CSS/JSON/JS.
+ * Throw a clear error naming the colliding ids rather than dropping a token.
+ */
+export function assertNoVarCollisions(ids, resolve) {
+    const seen = new Map();
+    for (const id of ids) {
+        const v = resolve(id);
+        if (!v)
+            continue; // intentionally unmapped
+        const prev = seen.get(v);
+        if (prev !== undefined && prev !== id) {
+            throw new Error(`Variable name collision: tokens "${prev}" and "${id}" both map to "${v}". ` +
+                `Rename one id or provide a manifest with distinct canonicalVar values.`);
+        }
+        seen.set(v, id);
+    }
+}
 ;
 /**
  * Build a mapping of token id -> {canonical, aliases} from an optional manifest.
@@ -42,11 +71,12 @@ function buildCssBlock(values, opts) {
     const decls = [];
     if (opts.manifest) {
         const mapping = buildVarMapping(Object.keys(values), opts.manifest);
+        assertNoVarCollisions(Object.keys(values), (id) => mapping.get(id)?.canonical ?? null);
         for (const [id, val] of Object.entries(values)) {
             const m = mapping.get(id);
             if (!m)
                 continue;
-            const v = String(val).trim();
+            const v = sanitizeCssValue(String(val));
             if (!v)
                 continue;
             decls.push(`${m.canonical}: ${v};`);
@@ -57,11 +87,12 @@ function buildCssBlock(values, opts) {
     }
     else {
         const mapVar = opts.mapVar ?? defaultVarMapper;
+        assertNoVarCollisions(Object.keys(values), mapVar);
         for (const [id, val] of Object.entries(values)) {
             const cssVar = mapVar(id);
             if (!cssVar)
                 continue; // skip if intentionally unmapped
-            const v = String(val).trim();
+            const v = sanitizeCssValue(String(val));
             if (v)
                 decls.push(`${cssVar}: ${v};`);
         }

package/adapters/css.ts

@@ -9,6 +9,38 @@ export type VarMapper = (id: TokenId) => string | null;
 export const defaultVarMapper: VarMapper = (id) =>
   `--${id.replace(/[^a-z0-9.]/gi, "-").replace(/\.+/g, "-").toLowerCase()}`;
 
+/**
+ * A CSS custom-property value derived from a token must not break out of its
+ * declaration (TASK-035 C). `;`, `{`, `}` and comment markers can't appear in a
+ * well-formed token value, so strip them — a malformed value can otherwise
+ * inject or corrupt sibling declarations.
+ */
+export function sanitizeCssValue(v: string): string {
+  return v.replace(/\/\*|\*\//g, "").replace(/[;{}]/g, "").trim();
+}
+
+/**
+ * Detect non-injective var mapping (TASK-035 C): `defaultVarMapper` collapses
+ * both `.` and other separators to `-`, so distinct ids like `a.b` and `a-b` map
+ * to the same `--a-b` and would silently overwrite each other in CSS/JSON/JS.
+ * Throw a clear error naming the colliding ids rather than dropping a token.
+ */
+export function assertNoVarCollisions(ids: Iterable<string>, resolve: (id: string) => string | null): void {
+  const seen = new Map<string, string>();
+  for (const id of ids) {
+    const v = resolve(id);
+    if (!v) continue; // intentionally unmapped
+    const prev = seen.get(v);
+    if (prev !== undefined && prev !== id) {
+      throw new Error(
+        `Variable name collision: tokens "${prev}" and "${id}" both map to "${v}". ` +
+        `Rename one id or provide a manifest with distinct canonicalVar values.`,
+      );
+    }
+    seen.set(v, id);
+  }
+}
+
 // Manifest driven mapping allowing canonical + legacy aliases.
 export type ManifestRow = { id: string; canonicalVar?: string | null; legacyVars?: string[] };
 
@@ -56,10 +88,11 @@ function buildCssBlock(
   const decls: string[] = [];
   if (opts.manifest) {
     const mapping = buildVarMapping(Object.keys(values), opts.manifest);
+    assertNoVarCollisions(Object.keys(values), (id) => mapping.get(id)?.canonical ?? null);
     for (const [id, val] of Object.entries(values)) {
       const m = mapping.get(id);
       if (!m) continue;
-      const v = String(val).trim();
+      const v = sanitizeCssValue(String(val));
       if (!v) continue;
       decls.push(`${m.canonical}: ${v};`);
       for (const alias of m.aliases) {
@@ -68,10 +101,11 @@ function buildCssBlock(
     }
   } else {
     const mapVar = opts.mapVar ?? defaultVarMapper;
+    assertNoVarCollisions(Object.keys(values), mapVar);
     for (const [id, val] of Object.entries(values)) {
       const cssVar = mapVar(id);
       if (!cssVar) continue; // skip if intentionally unmapped
-      const v = String(val).trim();
+      const v = sanitizeCssValue(String(val));
       if (v) decls.push(`${cssVar}: ${v};`);
     }
   }

package/adapters/js.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"js.d.ts","sourceRoot":"","sources":["js.ts"],"names":[],"mappings":"AACA,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAE/E,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,MAAM,CAUpF"}
+{"version":3,"file":"js.d.ts","sourceRoot":"","sources":["js.ts"],"names":[],"mappings":"AACA,OAAO,EAA4D,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAEtG,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,MAAM,CAYpF"}

package/adapters/js.js

@@ -1,10 +1,12 @@
 // adapters/js.ts
-import { buildVarMapping, defaultVarMapper } from './css.js';
+import { buildVarMapping, defaultVarMapper, assertNoVarCollisions } from './css.js';
 export function emitJS(values, manifest) {
     const ids = Object.keys(values).sort();
     let mapping;
     if (manifest)
         mapping = buildVarMapping(ids, manifest);
+    // Distinct ids that collapse to the same key would silently overwrite (TASK-035 C).
+    assertNoVarCollisions(ids, (id) => (mapping ? mapping.get(id).canonical : defaultVarMapper(id)));
     const lines = [];
     for (const id of ids) {
         const canonical = mapping ? mapping.get(id).canonical : defaultVarMapper(id);

package/adapters/js.ts

@@ -1,10 +1,12 @@
 // adapters/js.ts
-import { buildVarMapping, defaultVarMapper, type ManifestRow } from './css.js';
+import { buildVarMapping, defaultVarMapper, assertNoVarCollisions, type ManifestRow } from './css.js';
 
 export function emitJS(values: Record<string, any>, manifest?: ManifestRow[]): string {
   const ids = Object.keys(values).sort();
   let mapping: Map<string, { canonical: string; aliases: string[] }> | undefined;
   if (manifest) mapping = buildVarMapping(ids, manifest);
+  // Distinct ids that collapse to the same key would silently overwrite (TASK-035 C).
+  assertNoVarCollisions(ids, (id) => (mapping ? mapping.get(id)!.canonical : defaultVarMapper(id)));
   const lines: string[] = [];
   for (const id of ids) {
     const canonical = mapping ? mapping.get(id)!.canonical : defaultVarMapper(id);

package/adapters/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["json.ts"],"names":[],"mappings":"AACA,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAE/E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,MAAM,CAUtF;AAED,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;CAC7B,GAAG,MAAM,CAQT;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACnC,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,GAAG,MAAM,CAKT"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["json.ts"],"names":[],"mappings":"AACA,OAAO,EAA4D,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAEtG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,MAAM,CAYtF;AAED,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;CAC7B,GAAG,MAAM,CAQT;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACnC,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,GAAG,MAAM,CAKT"}

package/adapters/json.js

@@ -1,10 +1,12 @@
 // adapters/json.ts
-import { buildVarMapping, defaultVarMapper } from './css.js';
+import { buildVarMapping, defaultVarMapper, assertNoVarCollisions } from './css.js';
 export function emitJSON(values, manifest) {
     const ids = Object.keys(values).sort();
     let mapping;
     if (manifest)
         mapping = buildVarMapping(ids, manifest);
+    // Distinct ids that collapse to the same key would silently overwrite (TASK-035 C).
+    assertNoVarCollisions(ids, (id) => (mapping ? mapping.get(id).canonical : defaultVarMapper(id)));
     const out = {};
     for (const id of ids) {
         const canonical = mapping ? mapping.get(id).canonical : defaultVarMapper(id);

package/adapters/json.ts

@@ -1,10 +1,12 @@
 // adapters/json.ts
-import { buildVarMapping, defaultVarMapper, type ManifestRow } from './css.js';
+import { buildVarMapping, defaultVarMapper, assertNoVarCollisions, type ManifestRow } from './css.js';
 
 export function emitJSON(values: Record<string, any>, manifest?: ManifestRow[]): string {
   const ids = Object.keys(values).sort();
   let mapping: Map<string, { canonical: string; aliases: string[] }> | undefined;
   if (manifest) mapping = buildVarMapping(ids, manifest);
+  // Distinct ids that collapse to the same key would silently overwrite (TASK-035 C).
+  assertNoVarCollisions(ids, (id) => (mapping ? mapping.get(id)!.canonical : defaultVarMapper(id)));
   const out: Record<string, any> = {};
   for (const id of ids) {
     const canonical = mapping ? mapping.get(id)!.canonical : defaultVarMapper(id);

package/cli/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+D9F"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiE9F"}

package/cli/commands/build.js

@@ -1,4 +1,4 @@
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, join } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { flattenTokens } from '../../core/flatten.js';
 import { mergeTokens } from '../../core/breakpoints.js';
@@ -48,13 +48,15 @@ export async function buildCommand(options) {
             console.log(js);
             return;
         }
-        const dir = 'dist';
+        // --output is honored as the target DIRECTORY for --all-formats (TASK-035 C:
+        // it was previously ignored and dist/ hardcoded). Defaults to dist/.
+        const dir = options.output || 'dist';
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        writeFileSync('dist/tokens.css', css, 'utf8');
-        writeFileSync('dist/tokens.json', json, 'utf8');
-        writeFileSync('dist/tokens.js', js, 'utf8');
-        console.log(`Tokens written (all formats) to dist/ (css/json/js)${manifest ? ' with mapper' : ''}`);
+        writeFileSync(join(dir, 'tokens.css'), css, 'utf8');
+        writeFileSync(join(dir, 'tokens.json'), json, 'utf8');
+        writeFileSync(join(dir, 'tokens.js'), js, 'utf8');
+        console.log(`Tokens written (all formats) to ${dir}/ (css/json/js)${manifest ? ' with mapper' : ''}`);
         return;
     }
     if (format === 'css') {

package/cli/commands/build.ts

@@ -1,4 +1,4 @@
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, join } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
 import { mergeTokens } from '../../core/breakpoints.js';
@@ -47,11 +47,13 @@ export async function buildCommand(options: BuildOptions & { [k: string]: any })
       console.log(js);
       return;
     }
-    const dir = 'dist'; if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync('dist/tokens.css', css, 'utf8');
-    writeFileSync('dist/tokens.json', json, 'utf8');
-    writeFileSync('dist/tokens.js', js, 'utf8');
-    console.log(`Tokens written (all formats) to dist/ (css/json/js)${manifest ? ' with mapper' : ''}`);
+    // --output is honored as the target DIRECTORY for --all-formats (TASK-035 C:
+    // it was previously ignored and dist/ hardcoded). Defaults to dist/.
+    const dir = options.output || 'dist'; if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'tokens.css'), css, 'utf8');
+    writeFileSync(join(dir, 'tokens.json'), json, 'utf8');
+    writeFileSync(join(dir, 'tokens.js'), js, 'utf8');
+    console.log(`Tokens written (all formats) to ${dir}/ (css/json/js)${manifest ? ' with mapper' : ''}`);
     return;
   }
   if (format === 'css') {

package/cli/commands/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8BhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiKvE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8BhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4KvE"}

package/cli/commands/graph.js

@@ -86,7 +86,11 @@ export async function graphCommand(options) {
             const outDir = 'dist/graphs';
             const baseFile = `${outDir}/${name}${suffix}-hasse.${ext}`;
             try {
-                const src = `${constraintsDir}/${name}.order.json`;
+                // Mirror discoverConstraints (TASK-034/035 B): under --breakpoint use the
+                // per-bp order file when present, else fall back to the global one — so the
+                // bp-labeled Hasse output actually reflects the bp poset, not the global.
+                const bpSrc = breakpoint ? `${constraintsDir}/${name}.${breakpoint}.order.json` : undefined;
+                const src = bpSrc && existsSync(bpSrc) ? bpSrc : `${constraintsDir}/${name}.order.json`;
                 if (!existsSync(src)) {
                     console.error(`❌ Order constraint file not found: ${src}`);
                     process.exit(1);
@@ -107,8 +111,15 @@ export async function graphCommand(options) {
                 let highlight;
                 let edgeLabels;
                 if (onlyViolations || highlightViolations || labelViolations) {
-                    const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-                    const tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
+                    const { loadTokensWithBreakpoint, mergeTokens } = await import('../../core/breakpoints.js');
+                    let tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
+                    // Theme overlay affects VALUES, so violation overlays must reflect it
+                    // (TASK-025) — merge-then-flatten like build/validate. The dependency
+                    // graph itself is value-independent and intentionally unthemed.
+                    if (options.theme) {
+                        const { loadThemeTokens } = await import('./utils.js');
+                        tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
+                    }
                     const { flattenTokens } = await import('../../core/flatten.js');
                     const { Engine } = await import('../../core/engine.js');
                     const { MonotonicPlugin, parseSize } = await import('../../core/constraints/monotonic.js');

package/cli/commands/graph.ts

@@ -65,7 +65,11 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
       const ext = baseFmt === 'mermaid' ? 'mmd' : 'dot';
       const outDir = 'dist/graphs'; const baseFile = `${outDir}/${name}${suffix}-hasse.${ext}`;
       try {
-        const src = `${constraintsDir}/${name}.order.json`;
+        // Mirror discoverConstraints (TASK-034/035 B): under --breakpoint use the
+        // per-bp order file when present, else fall back to the global one — so the
+        // bp-labeled Hasse output actually reflects the bp poset, not the global.
+        const bpSrc = breakpoint ? `${constraintsDir}/${name}.${breakpoint}.order.json` : undefined;
+        const src = bpSrc && existsSync(bpSrc) ? bpSrc : `${constraintsDir}/${name}.order.json`;
         if (!existsSync(src)) { console.error(`❌ Order constraint file not found: ${src}`); process.exit(1); }
         const { order } = JSON.parse(readFileSync(src, 'utf8'));
         const { buildPoset, transitiveReduction, toMermaidHasseStyled, toDotHasseStyled, filterByPrefix, filterExcludePrefix, khopSubgraph, pickSeedsByPattern } = await import('../../core/poset.js');
@@ -76,8 +80,15 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
         if (focus) { const nodes = new Set<string>([...h.keys(), ...Array.from(h.values()).flatMap(s=>[...s])]); const seeds = pickSeedsByPattern(nodes, focus); h = khopSubgraph(h, seeds, radius); }
         let highlight: { nodes: Set<string>; edges: Set<string>; color?: string } | undefined; let edgeLabels: Map<string,string> | undefined;
         if (onlyViolations || highlightViolations || labelViolations) {
-          const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-          const tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
+          const { loadTokensWithBreakpoint, mergeTokens } = await import('../../core/breakpoints.js');
+          let tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
+          // Theme overlay affects VALUES, so violation overlays must reflect it
+          // (TASK-025) — merge-then-flatten like build/validate. The dependency
+          // graph itself is value-independent and intentionally unthemed.
+          if (options.theme) {
+            const { loadThemeTokens } = await import('./utils.js');
+            tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
+          }
           const { flattenTokens } = await import('../../core/flatten.js');
           const { Engine } = await import('../../core/engine.js');
           const { MonotonicPlugin, parseSize } = await import('../../core/constraints/monotonic.js');

package/cli/commands/patch-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patch-apply.d.ts","sourceRoot":"","sources":["patch-apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkCrD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+C9E"}
+{"version":3,"file":"patch-apply.d.ts","sourceRoot":"","sources":["patch-apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAqCrD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoD9E"}

package/cli/commands/patch-apply.js

@@ -1,7 +1,6 @@
 import { loadTokens, outputResult } from './utils.js';
 import fs from 'node:fs';
-import { flattenTokens } from '../../core/flatten.js';
-import { createHash } from 'node:crypto';
+import { computeBaseTokensHash } from '../../core/patch.js';
 function applyChange(root, id, to, type) {
     const parts = id.split('.');
     let cur = root;
@@ -10,7 +9,12 @@ function applyChange(root, id, to, type) {
         if (i === parts.length - 1) {
             if (type === 'remove') {
                 if (cur[p] && typeof cur[p] === 'object') {
-                    delete cur[p].$value; // delete leaf value
+                    delete cur[p].$value;
+                    delete cur[p].$type; // drop the now-orphaned type with the value
+                    // Remove the node entirely if nothing else remains (no dangling
+                    // type-only node left behind — TASK-035 D).
+                    if (Object.keys(cur[p]).length === 0)
+                        delete cur[p];
                 }
             }
             else {
@@ -28,30 +32,36 @@ function applyChange(root, id, to, type) {
 }
 export async function patchApplyCommand(opts) {
     const tokens = loadTokens(opts.tokens || 'tokens/tokens.example.json');
-    // Compute current base tokens hash for drift detection (same logic as buildPatch)
-    function computeBaseHash(toks) {
-        const flat = flattenTokens(JSON.parse(JSON.stringify(toks))).flat;
-        const values = {};
-        Object.keys(flat).sort().forEach(id => { values[id] = flat[id]?.value; });
-        // Keep deterministic ordering
-        const ordered = Object.keys(values).sort().reduce((acc, k) => { acc[k] = values[k]; return acc; }, {});
-        return createHash('sha256').update(JSON.stringify(ordered)).digest('hex');
-    }
-    // Parse patch
-    let patchDoc;
+    // Parse patch (friendly errors instead of a raw SyntaxError/TypeError — TASK-035 D)
+    let raw;
     if (fs.existsSync(opts.patch)) {
-        patchDoc = JSON.parse(fs.readFileSync(opts.patch, 'utf8'));
+        raw = fs.readFileSync(opts.patch, 'utf8');
     }
     else if (opts.patch.trim().startsWith('{')) {
-        patchDoc = JSON.parse(opts.patch);
+        raw = opts.patch;
     }
     else {
         throw new Error(`Patch not found: ${opts.patch}`);
     }
+    let patchDoc;
+    try {
+        patchDoc = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Patch is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Shape validation before use, so a malformed doc gives a clear message rather
+    // than "changes is not iterable" / a raw TypeError (TASK-035 D).
+    if (!patchDoc || typeof patchDoc !== 'object' || Array.isArray(patchDoc)) {
+        throw new Error('Patch document must be a JSON object.');
+    }
     if (patchDoc.version !== 1)
-        throw new Error('Unsupported patch version');
+        throw new Error(`Unsupported patch version: ${patchDoc.version}. Expected 1.`);
+    if (!Array.isArray(patchDoc.changes)) {
+        throw new Error('Patch document is missing a "changes" array.');
+    }
     if (patchDoc.baseTokensHash) {
-        const currentHash = computeBaseHash(tokens);
+        const currentHash = computeBaseTokensHash(tokens);
         if (currentHash !== patchDoc.baseTokensHash) {
             console.warn(`⚠ Base tokens hash mismatch. Patch built against ${patchDoc.baseTokensHash} but current base is ${currentHash}. Proceeding (use --dry-run to inspect first).`);
         }

package/cli/commands/patch-apply.ts

@@ -2,8 +2,7 @@ import { loadTokens, outputResult } from './utils.js';
 import type { PatchApplyOptions } from '../types.js';
 import type { TokenNode } from '../../core/flatten.js';
 import fs from 'node:fs';
-import { flattenTokens } from '../../core/flatten.js';
-import { createHash } from 'node:crypto';
+import { computeBaseTokensHash } from '../../core/patch.js';
 
 interface PatchDocumentV1 {
   version: 1;
@@ -20,7 +19,11 @@ function applyChange(root: any, id: string, to: any, type: 'modify'|'add'|'remov
     if (i === parts.length - 1) {
       if (type === 'remove') {
         if (cur[p] && typeof cur[p] === 'object') {
-          delete cur[p].$value; // delete leaf value
+          delete cur[p].$value;
+          delete cur[p].$type; // drop the now-orphaned type with the value
+          // Remove the node entirely if nothing else remains (no dangling
+          // type-only node left behind — TASK-035 D).
+          if (Object.keys(cur[p]).length === 0) delete cur[p];
         }
       } else {
         if (!cur[p] || typeof cur[p] !== 'object') cur[p] = {};
@@ -35,27 +38,32 @@ function applyChange(root: any, id: string, to: any, type: 'modify'|'add'|'remov
 
 export async function patchApplyCommand(opts: PatchApplyOptions): Promise<void> {
   const tokens: TokenNode = loadTokens(opts.tokens || 'tokens/tokens.example.json');
-  // Compute current base tokens hash for drift detection (same logic as buildPatch)
-  function computeBaseHash(toks: TokenNode): string {
-    const flat = flattenTokens(JSON.parse(JSON.stringify(toks))).flat as Record<string, any>;
-    const values: Record<string, any> = {};
-    Object.keys(flat).sort().forEach(id => { values[id] = flat[id]?.value; });
-    // Keep deterministic ordering
-    const ordered = Object.keys(values).sort().reduce((acc, k) => { acc[k] = values[k]; return acc; }, {} as Record<string, any>);
-    return createHash('sha256').update(JSON.stringify(ordered)).digest('hex');
-  }
-  // Parse patch
-  let patchDoc: PatchDocumentV1;
+  // Parse patch (friendly errors instead of a raw SyntaxError/TypeError — TASK-035 D)
+  let raw: string;
   if (fs.existsSync(opts.patch)) {
-    patchDoc = JSON.parse(fs.readFileSync(opts.patch, 'utf8'));
+    raw = fs.readFileSync(opts.patch, 'utf8');
   } else if (opts.patch.trim().startsWith('{')) {
-    patchDoc = JSON.parse(opts.patch);
+    raw = opts.patch;
   } else {
     throw new Error(`Patch not found: ${opts.patch}`);
   }
-  if (patchDoc.version !== 1) throw new Error('Unsupported patch version');
+  let patchDoc: PatchDocumentV1;
+  try {
+    patchDoc = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Patch is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  // Shape validation before use, so a malformed doc gives a clear message rather
+  // than "changes is not iterable" / a raw TypeError (TASK-035 D).
+  if (!patchDoc || typeof patchDoc !== 'object' || Array.isArray(patchDoc)) {
+    throw new Error('Patch document must be a JSON object.');
+  }
+  if (patchDoc.version !== 1) throw new Error(`Unsupported patch version: ${(patchDoc as any).version}. Expected 1.`);
+  if (!Array.isArray(patchDoc.changes)) {
+    throw new Error('Patch document is missing a "changes" array.');
+  }
   if (patchDoc.baseTokensHash) {
-    const currentHash = computeBaseHash(tokens);
+    const currentHash = computeBaseTokensHash(tokens);
     if (currentHash !== patchDoc.baseTokensHash) {
       console.warn(`⚠ Base tokens hash mismatch. Patch built against ${patchDoc.baseTokensHash} but current base is ${currentHash}. Proceeding (use --dry-run to inspect first).`);
     }

package/cli/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOnD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA4L9E"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOnD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgM9E"}

package/cli/commands/validate.js

@@ -8,8 +8,9 @@ import { setupConstraints, collectReferencedIds } from '../constraint-registry.j
 import { printVersionBanner } from '../version-banner.js';
 import { loadThemeTokens } from './utils.js';
 export async function validateCommand(_options) {
-    // Show version banner (subtle, dimmed)
-    printVersionBanner({ quiet: _options.format === 'json' });
+    // Show version banner (subtle, dimmed). Stay quiet whenever stdout must be
+    // machine-parseable — JSON output OR a JSON summary (TASK-035 B).
+    printVersionBanner({ quiet: _options.format === 'json' || _options.summary === 'json' });
     try {
         const bps = parseBreakpoints(process.argv);
         const crossAxisDebug = process.argv.includes('--cross-axis-debug');
@@ -109,12 +110,15 @@ export async function validateCommand(_options) {
             pushRow(bp ?? 'global', { rules: rulesEvaluated, warnings: warns.length, errors: errs.length });
             const dur = globalThis.performance.now() - tStart;
             perBpTimings.push({ bp: bp ?? 'global', ms: dur });
-            // Only print text output if not in JSON mode
+            // Only print text output if not in JSON mode. When --summary json is set,
+            // route the human lines to STDERR so stdout carries only the parseable JSON
+            // summary (TASK-035 B: per-issue lines previously polluted the summary).
             if (outputFormat !== 'json') {
-                console.log(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
+                const line = summaryFmt === 'json' ? console.error : console.log;
+                line(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
                 for (const it of issues) {
                     const tag = it.level === 'error' ? 'ERROR' : 'WARN ';
-                    console.log(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`);
+                    line(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`);
                 }
             }
         }

package/cli/commands/validate.ts

@@ -11,8 +11,9 @@ import { printVersionBanner } from '../version-banner.js';
 import { loadThemeTokens } from './utils.js';
 
 export async function validateCommand(_options: ValidateOptions): Promise<void> {
-  // Show version banner (subtle, dimmed)
-  printVersionBanner({ quiet: _options.format === 'json' });
+  // Show version banner (subtle, dimmed). Stay quiet whenever stdout must be
+  // machine-parseable — JSON output OR a JSON summary (TASK-035 B).
+  printVersionBanner({ quiet: _options.format === 'json' || _options.summary === 'json' });
 
   try {
     const bps = parseBreakpoints(process.argv);
@@ -115,10 +116,13 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
       const dur = globalThis.performance.now() - tStart;
       perBpTimings.push({ bp: bp ?? 'global', ms: dur });
       
-      // Only print text output if not in JSON mode
+      // Only print text output if not in JSON mode. When --summary json is set,
+      // route the human lines to STDERR so stdout carries only the parseable JSON
+      // summary (TASK-035 B: per-issue lines previously polluted the summary).
       if (outputFormat !== 'json') {
-        console.log(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
-        for (const it of issues) { const tag = it.level === 'error' ? 'ERROR' : 'WARN '; console.log(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`); }
+        const line = summaryFmt === 'json' ? console.error : console.log;
+        line(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
+        for (const it of issues) { const tag = it.level === 'error' ? 'ERROR' : 'WARN '; line(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`); }
       }
     }
     const totalMs = globalThis.performance.now() - tStartTotal;

package/cli/commands/why.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA8JnE"}
+{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQ9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyKnE"}

package/cli/commands/why.js

@@ -1,13 +1,24 @@
 import { readFileSync } from 'node:fs';
 import { flattenTokens } from '../../core/flatten.js';
 import { explain } from '../../core/why.js';
-import { loadTokens } from './utils.js';
+import { loadThemeTokens } from './utils.js';
+import { loadTokensWithBreakpoint, mergeTokens, parseBreakpoints } from '../../core/breakpoints.js';
 import { Engine } from '../../core/engine.js';
 import { loadConfig } from '../config.js';
 import { setupConstraints } from '../constraint-registry.js';
 export async function whyCommand(options) {
-    const tokensPath = options.tokens || 'tokens/tokens.json';
-    const tokens = loadTokens(tokensPath);
+    const tokensPath = options.tokens || 'tokens/tokens.example.json';
+    // Theme/breakpoint awareness (TASK-025): mirror validate's merge-then-flatten so
+    // `why` resolves the same values a themed/breakpoint validate would. Both loaders
+    // fail closed on a missing/malformed file.
+    const bp = (options.breakpoint ?? parseBreakpoints(process.argv)[0]);
+    let tokens = loadTokensWithBreakpoint(bp, tokensPath);
+    let themeFlat;
+    if (options.theme) {
+        const themeTokens = loadThemeTokens(options.theme);
+        tokens = mergeTokens(tokens, themeTokens);
+        themeFlat = flattenTokens(themeTokens).flat;
+    }
     const { flat, edges } = flattenTokens(tokens);
     const target = options.tokenId;
     if (!flat[target]) {
@@ -45,6 +56,7 @@ export async function whyCommand(options) {
     const overrides = safeLoad('tokens/overrides/local.json');
     const baseReport = explain(target, flat, edges, {
         overrides: overrides?.overrides ?? overrides,
+        theme: themeFlat,
     });
     // Best-effort constraint summary: which rules currently implicate this token
     let constraintsSummary;
@@ -70,7 +82,7 @@ export async function whyCommand(options) {
             const knownIds = new Set(Object.keys(init));
             // Discover and attach all constraints via centralized registry.
             // Honor --constraints-dir, matching `validate` (default: themes).
-            setupConstraints(engine, { config, constraintsDir: options['constraints-dir'] ?? 'themes' }, { knownIds });
+            setupConstraints(engine, { config, constraintsDir: options['constraints-dir'] ?? 'themes', bp }, { knownIds });
             const candidates = new Set([target]);
             const allIssues = engine.evaluate(candidates);
             if (allIssues.length) {

package/cli/commands/why.ts

@@ -2,15 +2,26 @@ import { readFileSync } from 'node:fs';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
 import { explain } from '../../core/why.js';
 import type { WhyOptions } from '../types.js';
-import { loadTokens } from './utils.js';
+import { loadThemeTokens } from './utils.js';
+import { loadTokensWithBreakpoint, mergeTokens, parseBreakpoints, type Breakpoint } from '../../core/breakpoints.js';
 import { Engine } from '../../core/engine.js';
 import { loadConfig } from '../config.js';
 import type { ConstraintIssue } from '../../core/engine.js';
 import { setupConstraints } from '../constraint-registry.js';
 
 export async function whyCommand(options: WhyOptions): Promise<void> {
-  const tokensPath = options.tokens || 'tokens/tokens.json';
-  const tokens = loadTokens(tokensPath);
+  const tokensPath = options.tokens || 'tokens/tokens.example.json';
+  // Theme/breakpoint awareness (TASK-025): mirror validate's merge-then-flatten so
+  // `why` resolves the same values a themed/breakpoint validate would. Both loaders
+  // fail closed on a missing/malformed file.
+  const bp = (options.breakpoint ?? parseBreakpoints(process.argv)[0]) as Breakpoint | undefined;
+  let tokens = loadTokensWithBreakpoint(bp, tokensPath);
+  let themeFlat: Record<string, FlatToken> | undefined;
+  if (options.theme) {
+    const themeTokens = loadThemeTokens(options.theme);
+    tokens = mergeTokens(tokens, themeTokens);
+    themeFlat = flattenTokens(themeTokens).flat as Record<string, FlatToken>;
+  }
   const { flat, edges } = flattenTokens(tokens);
   const target = options.tokenId;
 
@@ -50,6 +61,7 @@ export async function whyCommand(options: WhyOptions): Promise<void> {
 
   const baseReport = explain(target, flat, edges, {
     overrides: (overrides as any)?.overrides ?? overrides,
+    theme: themeFlat,
   });
 
   // Best-effort constraint summary: which rules currently implicate this token
@@ -87,7 +99,7 @@ export async function whyCommand(options: WhyOptions): Promise<void> {
       // Honor --constraints-dir, matching `validate` (default: themes).
       setupConstraints(
         engine,
-        { config, constraintsDir: options['constraints-dir'] ?? 'themes' },
+        { config, constraintsDir: options['constraints-dir'] ?? 'themes', bp },
         { knownIds },
       );
 

package/cli/dcv.js

@@ -4,6 +4,23 @@ import yargs from 'yargs/yargs';
 import { hideBin } from 'yargs/helpers';
 import { setCommand, buildCommand, validateCommand, graphCommand, whyCommand, patchCommand, patchApplyCommand } from './commands/index.js';
 import { getVersionInfo } from './version-banner.js';
+// Uniform handler wrapper (TASK-035 B): without this, a thrown IO/config error
+// in a command (e.g. patch:apply on a missing file) escapes as an unhandled
+// rejection — Node prints a raw stack trace and exits 1. Wrapping gives every
+// command the clean "exit 2 + one-line message" contract that `validate` already
+// has and docs/JSON-OUTPUT.md promises. Commands that call process.exit()
+// themselves are unaffected (they terminate before the catch).
+function run(fn) {
+    return async (a) => {
+        try {
+            await fn(a);
+        }
+        catch (e) {
+            console.error(`dcv: ${e instanceof Error ? e.message : String(e)}`);
+            process.exit(2);
+        }
+    };
+}
 const cli = yargs(hideBin(process.argv))
     .scriptName('dcv')
     // camel-case-expansion is intentionally OFF, so the CLI delivers flags only
@@ -27,7 +44,7 @@ cli.command('set [expressions..]', 'Set token values', y => y
     .option('output', { type: 'string' })
     .option('theme', { type: 'string' })
     .option('debug-set', { type: 'boolean', hidden: true }) // hidden debug aid (also DCV_DEBUG_SET=1)
-    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => setCommand(a));
+    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), run(setCommand));
 cli.command('build', 'Build token outputs', y => y
     .option('format', { type: 'string', choices: ['css', 'json', 'js'], default: 'css' })
     .option('all-formats', { type: 'boolean', default: false })
@@ -35,7 +52,7 @@ cli.command('build', 'Build token outputs', y => y
     .option('mapper', { type: 'string' })
     .option('theme', { type: 'string' })
     .option('dry-run', { type: 'boolean', default: false })
-    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }), a => buildCommand(a));
+    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }), run(buildCommand));
 cli.command('validate [tokens-path]', 'Validate constraints', y => y
     .positional('tokens-path', { type: 'string', describe: 'Path to a tokens file (positional alias for --tokens)' })
     .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files (default: themes)' })
@@ -46,12 +63,12 @@ cli.command('validate [tokens-path]', 'Validate constraints', y => y
     .option('receipt', { type: 'string', describe: 'Generate validation receipt with audit trail' })
     .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' })
     .option('theme', { type: 'string', describe: 'Apply named theme tokens before validation' })
-    .option('breakpoint', { type: 'string' })
+    .option('breakpoint', { type: 'string', choices: ['sm', 'md', 'lg'] })
     .option('all-breakpoints', { type: 'boolean' })
     .option('cross-axis-debug', { type: 'boolean', hidden: true }) // hidden debug aid
     .option('perf', { type: 'boolean', describe: 'Print timing info' })
     .option('budget-total-ms', { type: 'number', describe: 'Fail if total validation exceeds this (ms)' })
-    .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }), a => validateCommand(a));
+    .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }), run(validateCommand));
 cli.command('graph', 'Generate dependency / constraint graph', y => y
     .option('format', { type: 'string', choices: ['json', 'mermaid', 'dot', 'svg', 'png'], default: 'json' })
     .option('bundle', { type: 'boolean', describe: 'When used with --hasse export mermaid+dot (+image if svg/png requested)' })
@@ -71,22 +88,25 @@ cli.command('graph', 'Generate dependency / constraint graph', y => y
     .option('image-from', { type: 'string', choices: ['mermaid', 'dot'], describe: 'Source format for svg/png export (default: mermaid)' })
     .option('focus', { type: 'string' })
     .option('radius', { type: 'number', default: 1 })
-    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }), a => graphCommand(a));
+    .option('theme', { type: 'string', describe: 'Apply named theme tokens before computing --hasse violation overlays (dependency graph is unaffected)' })
+    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }), run(graphCommand));
 cli.command('why <tokenId>', 'Explain token provenance', y => y
     .positional('tokenId', { type: 'string', demandOption: true })
     .option('format', { type: 'string', choices: ['json', 'table'], default: 'json' })
     .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files for the constraint summary (default: themes)' })
-    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => whyCommand(a));
+    .option('theme', { type: 'string', describe: 'Apply named theme tokens (tokens/themes/<name>.json) before resolving values' })
+    .option('breakpoint', { type: 'string', choices: ['sm', 'md', 'lg'], describe: 'Resolve values for a breakpoint override' })
+    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), run(whyCommand));
 cli.command('patch', 'Export patch (diff) from overrides', y => y
     .option('overrides', { type: 'string', describe: 'Path or inline JSON of flat overrides' })
     .option('format', { type: 'string', choices: ['json', 'css', 'js'], default: 'json' })
     .option('output', { type: 'string' })
-    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => patchCommand(a));
+    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), run(patchCommand));
 cli.command('patch:apply <patch>', 'Apply patch document to tokens', y => y
     .positional('patch', { type: 'string', demandOption: true })
     .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
     .option('output', { type: 'string', describe: 'Write updated tokens to this file' })
-    .option('dry-run', { type: 'boolean', default: false }), a => patchApplyCommand(a));
+    .option('dry-run', { type: 'boolean', default: false }), run(patchApplyCommand));
 // Wire `--version` to the real package version (same source as the banner).
 // Without this, yargs can't locate package.json from the installed bin and
 // prints "unknown" (TASK-021 release smoke-test finding).

package/cli/dcv.ts

@@ -6,6 +6,23 @@ import { type SetOptions, type BuildOptions, type ValidateOptions, type GraphOpt
 import { setCommand, buildCommand, validateCommand, graphCommand, whyCommand, patchCommand, patchApplyCommand } from './commands/index.js';
 import { getVersionInfo } from './version-banner.js';
 
+// Uniform handler wrapper (TASK-035 B): without this, a thrown IO/config error
+// in a command (e.g. patch:apply on a missing file) escapes as an unhandled
+// rejection — Node prints a raw stack trace and exits 1. Wrapping gives every
+// command the clean "exit 2 + one-line message" contract that `validate` already
+// has and docs/JSON-OUTPUT.md promises. Commands that call process.exit()
+// themselves are unaffected (they terminate before the catch).
+function run<T>(fn: (a: T) => void | Promise<void>): (a: T) => Promise<void> {
+  return async (a: T) => {
+    try {
+      await fn(a);
+    } catch (e) {
+      console.error(`dcv: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(2);
+    }
+  };
+}
+
 const cli = yargs(hideBin(process.argv))
   .scriptName('dcv')
   // camel-case-expansion is intentionally OFF, so the CLI delivers flags only
@@ -31,7 +48,7 @@ cli.command<SetOptions>('set [expressions..]', 'Set token values', y => y
   .option('theme', { type: 'string' })
   .option('debug-set', { type: 'boolean', hidden: true }) // hidden debug aid (also DCV_DEBUG_SET=1)
   .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => setCommand(a)
+  run(setCommand)
 );
 
 cli.command<BuildOptions>('build', 'Build token outputs', y => y
@@ -42,7 +59,7 @@ cli.command<BuildOptions>('build', 'Build token outputs', y => y
   .option('theme', { type: 'string' })
   .option('dry-run', { type: 'boolean', default: false })
   .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }),
-  a => buildCommand(a)
+  run(buildCommand)
 );
 
 cli.command<ValidateOptions>('validate [tokens-path]', 'Validate constraints', y => y
@@ -55,13 +72,13 @@ cli.command<ValidateOptions>('validate [tokens-path]', 'Validate constraints', y
   .option('receipt', { type: 'string', describe: 'Generate validation receipt with audit trail' })
   .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' })
   .option('theme', { type: 'string', describe: 'Apply named theme tokens before validation' })
-  .option('breakpoint', { type: 'string' })
+  .option('breakpoint', { type: 'string', choices: ['sm','md','lg'] })
   .option('all-breakpoints', { type: 'boolean' })
   .option('cross-axis-debug', { type: 'boolean', hidden: true }) // hidden debug aid
   .option('perf', { type: 'boolean', describe: 'Print timing info' })
   .option('budget-total-ms', { type: 'number', describe: 'Fail if total validation exceeds this (ms)' })
   .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }),
-  a => validateCommand(a)
+  run(validateCommand)
 );
 
 cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y => y
@@ -83,16 +100,19 @@ cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y =
   .option('image-from', { type: 'string', choices: ['mermaid','dot'], describe: 'Source format for svg/png export (default: mermaid)' })
   .option('focus', { type: 'string' })
   .option('radius', { type: 'number', default: 1 })
+  .option('theme', { type: 'string', describe: 'Apply named theme tokens before computing --hasse violation overlays (dependency graph is unaffected)' })
   .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }),
-  a => graphCommand(a)
+  run(graphCommand)
 );
 
 cli.command<WhyOptions>('why <tokenId>', 'Explain token provenance', y => y
   .positional('tokenId', { type: 'string', demandOption: true })
   .option('format', { type: 'string', choices: ['json','table'], default: 'json' })
   .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files for the constraint summary (default: themes)' })
+  .option('theme', { type: 'string', describe: 'Apply named theme tokens (tokens/themes/<name>.json) before resolving values' })
+  .option('breakpoint', { type: 'string', choices: ['sm','md','lg'], describe: 'Resolve values for a breakpoint override' })
   .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => whyCommand(a)
+  run(whyCommand)
 );
 
 cli.command<PatchOptions>('patch', 'Export patch (diff) from overrides', y => y
@@ -100,7 +120,7 @@ cli.command<PatchOptions>('patch', 'Export patch (diff) from overrides', y => y
   .option('format', { type: 'string', choices: ['json','css','js'], default: 'json' })
   .option('output', { type: 'string' })
   .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => patchCommand(a)
+  run(patchCommand)
 );
 
 cli.command<PatchApplyOptions>('patch:apply <patch>', 'Apply patch document to tokens', y => y
@@ -108,7 +128,7 @@ cli.command<PatchApplyOptions>('patch:apply <patch>', 'Apply patch document to t
   .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
   .option('output', { type: 'string', describe: 'Write updated tokens to this file' })
   .option('dry-run', { type: 'boolean', default: false }),
-  a => patchApplyCommand(a)
+  run(patchApplyCommand)
 );
 
 // Wire `--version` to the real package version (same source as the banner).

package/cli/types.d.ts

@@ -81,11 +81,15 @@ export interface GraphOptions extends GlobalOptions {
     focus?: string;
     radius?: number;
     tokens?: string;
+    theme?: string;
+    breakpoint?: 'sm' | 'md' | 'lg';
 }
 export interface WhyOptions extends GlobalOptions {
     tokenId: string;
     'constraints-dir'?: string;
     format?: 'json' | 'table';
+    theme?: string;
+    breakpoint?: 'sm' | 'md' | 'lg';
 }
 export interface PatchOptions extends GlobalOptions {
     overrides?: string;

package/cli/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAAG,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;AAChH,MAAM,MAAM,SAAS,GAAG,eAAe,CAAC;AACxC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACrD,MAAM,WAAW,aAAa;IAAG,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE;AAClE,MAAM,MAAM,aAAa,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,CAAA;CAAE,GAAG,aAAa,CAAC;AAE3F,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AACD,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAGjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AACD,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AACD,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CACrC;AACD,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,YAAY,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CACjC;AACD,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CACjC;AACD,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AACD,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/cli/types.ts

@@ -77,11 +77,15 @@ export interface GraphOptions extends GlobalOptions {
   focus?: string;
   radius?: number;
   tokens?: string;
+  theme?: string;
+  breakpoint?: 'sm' | 'md' | 'lg';
 }
 export interface WhyOptions extends GlobalOptions {
   tokenId: string;
   'constraints-dir'?: string;
   format?: 'json' | 'table';
+  theme?: string;
+  breakpoint?: 'sm' | 'md' | 'lg';
 }
 export interface PatchOptions extends GlobalOptions {
   overrides?: string; // path to flat overrides json or inline json

package/core/breakpoints.d.ts

@@ -1,5 +1,6 @@
 import type { TokenNode } from "./flatten.js";
 export type Breakpoint = "sm" | "md" | "lg";
+export declare const BREAKPOINTS: readonly Breakpoint[];
 export declare function parseBreakpoints(argv: string[]): Breakpoint[];
 export declare function loadJsonSafe<T = unknown>(path: string): T | null;
 export declare function loadOrders(axis: string, bp?: Breakpoint): [string, "<=" | ">=", string][];

package/core/breakpoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAM7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAkBxF"}
+{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,eAAO,MAAM,WAAW,EAAE,SAAS,UAAU,EAAuB,CAAC;AAErE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAe7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAkBxF"}

package/core/breakpoints.js

@@ -1,12 +1,21 @@
 // core/breakpoints.ts
 import fs from "node:fs";
+export const BREAKPOINTS = ["sm", "md", "lg"];
 export function parseBreakpoints(argv) {
     const allIdx = argv.indexOf("--all-breakpoints");
     if (allIdx >= 0)
         return ["sm", "md", "lg"];
     const bpIdx = argv.indexOf("--breakpoint");
-    if (bpIdx >= 0)
-        return [argv[bpIdx + 1]];
+    if (bpIdx >= 0) {
+        // Validate the value (TASK-035 B): an unknown/missing breakpoint must not be
+        // accepted — it would load a non-existent override and validate the BASE
+        // tokens as if the breakpoint applied (a confident false green on a typo).
+        const val = argv[bpIdx + 1];
+        if (!val || !BREAKPOINTS.includes(val)) {
+            throw new Error(`Invalid --breakpoint "${val ?? ""}". Expected one of: ${BREAKPOINTS.join(", ")}.`);
+        }
+        return [val];
+    }
     return []; // no BP slicing requested
 }
 export function loadJsonSafe(path) {

package/core/breakpoints.ts

@@ -4,11 +4,22 @@ import type { TokenNode } from "./flatten.js";
 
 export type Breakpoint = "sm" | "md" | "lg";
 
+export const BREAKPOINTS: readonly Breakpoint[] = ["sm", "md", "lg"];
+
 export function parseBreakpoints(argv: string[]): Breakpoint[] {
   const allIdx = argv.indexOf("--all-breakpoints");
   if (allIdx >= 0) return ["sm", "md", "lg"];
   const bpIdx = argv.indexOf("--breakpoint");
-  if (bpIdx >= 0) return [argv[bpIdx + 1] as Breakpoint];
+  if (bpIdx >= 0) {
+    // Validate the value (TASK-035 B): an unknown/missing breakpoint must not be
+    // accepted — it would load a non-existent override and validate the BASE
+    // tokens as if the breakpoint applied (a confident false green on a typo).
+    const val = argv[bpIdx + 1];
+    if (!val || !BREAKPOINTS.includes(val as Breakpoint)) {
+      throw new Error(`Invalid --breakpoint "${val ?? ""}". Expected one of: ${BREAKPOINTS.join(", ")}.`);
+    }
+    return [val as Breakpoint];
+  }
   return []; // no BP slicing requested
 }
 

package/core/dtcg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dtcg.d.ts","sourceRoot":"","sources":["dtcg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAsDF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAU/E"}
+{"version":3,"file":"dtcg.d.ts","sourceRoot":"","sources":["dtcg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AA2DF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAU/E"}

package/core/dtcg.js

@@ -64,7 +64,13 @@ function isColorObject(obj, type) {
         'hex' in obj);
 }
 function isDimensionObject(obj, type) {
-    return (type ?? '').toLowerCase() === 'dimension' || ('value' in obj && 'unit' in obj);
+    if ((type ?? '').toLowerCase() === 'dimension')
+        return true;
+    // A bare { value: <number> } (with or without `unit`) is a dimension even when
+    // $type is absent — normalizeDimension defaults the unit to px. Previously this
+    // required `unit` too, so a unit-less dimension became an <unsupported> sentinel
+    // (TASK-035 E). isColorObject runs first, so a numeric `value` here is a length.
+    return 'value' in obj && typeof obj.value === 'number';
 }
 /**
  * Normalize a raw DTCG `$value` to the string/number form the engine expects.

package/core/dtcg.ts

@@ -80,7 +80,12 @@ function isColorObject(obj: Record<string, unknown>, type?: string): boolean {
 }
 
 function isDimensionObject(obj: Record<string, unknown>, type?: string): boolean {
-  return (type ?? '').toLowerCase() === 'dimension' || ('value' in obj && 'unit' in obj);
+  if ((type ?? '').toLowerCase() === 'dimension') return true;
+  // A bare { value: <number> } (with or without `unit`) is a dimension even when
+  // $type is absent — normalizeDimension defaults the unit to px. Previously this
+  // required `unit` too, so a unit-less dimension became an <unsupported> sentinel
+  // (TASK-035 E). isColorObject runs first, so a numeric `value` here is a length.
+  return 'value' in obj && typeof obj.value === 'number';
 }
 
 /**

package/core/patch.d.ts

@@ -23,6 +23,13 @@ export interface BuildPatchOptions {
     breakpoint?: string;
     includeUnchanged?: boolean;
 }
+/**
+ * Canonical hash of a token set's flattened id→value map. Shared by buildPatch
+ * (to stamp baseTokensHash) and patch:apply (to detect drift). They MUST use the
+ * exact same serialization — previously patch:apply used a different
+ * JSON.stringify form, so the drift warning fired on every apply (TASK-035 D).
+ */
+export declare function computeBaseTokensHash(tokens: TokenNode): string;
 export declare function applyFlatOverrides(tokens: TokenNode, overrides?: Record<string, any>): void;
 export declare function buildPatch(opts: BuildPatchOptions): PatchDocument;
 //# sourceMappingURL=patch.d.ts.map

package/core/patch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["patch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC,EAAE,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAuB3F;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAyEjE"}
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["patch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC,EAAE,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAK/D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAuB3F;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAwEjE"}

package/core/patch.js

@@ -3,6 +3,18 @@ import { flattenTokens } from './flatten.js';
 function canonicalString(obj) {
     return JSON.stringify(obj, Object.keys(obj).sort(), 2);
 }
+/**
+ * Canonical hash of a token set's flattened id→value map. Shared by buildPatch
+ * (to stamp baseTokensHash) and patch:apply (to detect drift). They MUST use the
+ * exact same serialization — previously patch:apply used a different
+ * JSON.stringify form, so the drift warning fired on every apply (TASK-035 D).
+ */
+export function computeBaseTokensHash(tokens) {
+    const flat = flattenTokens(JSON.parse(JSON.stringify(tokens))).flat;
+    const values = {};
+    Object.keys(flat).sort().forEach((id) => { values[id] = flat[id]?.value; });
+    return createHash('sha256').update(canonicalString(values)).digest('hex');
+}
 export function applyFlatOverrides(tokens, overrides) {
     if (!overrides)
         return;
@@ -36,10 +48,9 @@ export function buildPatch(opts) {
     const cloned = JSON.parse(JSON.stringify(opts.tokens));
     // Flatten original
     const baseFlat = flattenTokens(cloned).flat;
-    // Canonical base tokens hash (id -> value) for drift detection when applying patch later
-    const baseFlatValues = {};
-    Object.keys(baseFlat).sort().forEach(id => { baseFlatValues[id] = baseFlat[id]?.value; });
-    const baseTokensHash = createHash('sha256').update(canonicalString(baseFlatValues)).digest('hex');
+    // Canonical base tokens hash (id -> value) for drift detection when applying
+    // the patch later — uses the SHARED hash so patch:apply agrees (TASK-035 D).
+    const baseTokensHash = computeBaseTokensHash(opts.tokens);
     // Apply overrides on a fresh clone for diffing
     const modified = JSON.parse(JSON.stringify(opts.tokens));
     const removalIds = new Set();

package/core/patch.ts

@@ -33,6 +33,19 @@ function canonicalString(obj: any): string {
   return JSON.stringify(obj, Object.keys(obj).sort(), 2);
 }
 
+/**
+ * Canonical hash of a token set's flattened id→value map. Shared by buildPatch
+ * (to stamp baseTokensHash) and patch:apply (to detect drift). They MUST use the
+ * exact same serialization — previously patch:apply used a different
+ * JSON.stringify form, so the drift warning fired on every apply (TASK-035 D).
+ */
+export function computeBaseTokensHash(tokens: TokenNode): string {
+  const flat = flattenTokens(JSON.parse(JSON.stringify(tokens))).flat as Record<string, any>;
+  const values: Record<string, any> = {};
+  Object.keys(flat).sort().forEach((id) => { values[id] = flat[id]?.value; });
+  return createHash('sha256').update(canonicalString(values)).digest('hex');
+}
+
 export function applyFlatOverrides(tokens: TokenNode, overrides?: Record<string, any>): void {
   if (!overrides) return;
   for (const [id, val] of Object.entries(overrides)) {
@@ -62,10 +75,9 @@ export function buildPatch(opts: BuildPatchOptions): PatchDocument {
   const cloned = JSON.parse(JSON.stringify(opts.tokens));
   // Flatten original
   const baseFlat = flattenTokens(cloned as any).flat as Record<string, any>;
-  // Canonical base tokens hash (id -> value) for drift detection when applying patch later
-  const baseFlatValues: Record<string, any> = {};
-  Object.keys(baseFlat).sort().forEach(id => { baseFlatValues[id] = baseFlat[id]?.value; });
-  const baseTokensHash = createHash('sha256').update(canonicalString(baseFlatValues)).digest('hex');
+  // Canonical base tokens hash (id -> value) for drift detection when applying
+  // the patch later — uses the SHARED hash so patch:apply agrees (TASK-035 D).
+  const baseTokensHash = computeBaseTokensHash(opts.tokens);
   // Apply overrides on a fresh clone for diffing
   const modified = JSON.parse(JSON.stringify(opts.tokens));
   const removalIds = new Set<string>();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-constraint-validator",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Mathematical constraint validator for design systems — ensuring consistency, accessibility, and logical coherence",
   "type": "module",
   "engines": {

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.CseperkePapp/design-constraint-validator",
   "title": "Design Constraint Validator",
   "description": "Validate design tokens for accessibility, scales, and design-system constraint consistency.",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "repository": {
     "url": "https://github.com/CseperkePapp/design-constraint-validator",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "design-constraint-validator",
-      "version": "2.2.1",
+      "version": "2.3.0",
       "transport": {
         "type": "stdio"
       }