design-constraint-validator 1.0.0 → 2.0.1

package/core/constraints/monotonic.ts

@@ -1,74 +1,74 @@
-// core/constraints/monotonic.ts
-import type { ConstraintPlugin } from "../engine.js";
-import type { Order } from "../poset.js";
-
-export function MonotonicPlugin(
-  orders: Order[], 
-  parse: (v: unknown) => number | null,
-  ruleId = "monotonic"
-): ConstraintPlugin {
-  return {
-    id: ruleId,
-    evaluate(engine, candidates) {
-      const issues = [];
-      for (const [a, op, b] of orders) {
-        const va = parse(engine.get(a));
-        const vb = parse(engine.get(b));
-        if (va == null || vb == null) continue; // skip unparseable
-        const ok = op === ">=" ? va >= vb : va <= vb;
-        if (!ok && (candidates.has(a) || candidates.has(b))) {
-          issues.push({
-            id: `${a}|${b}`,
-            rule: "monotonic",
-            level: "error" as const,
-            message: `${a} ${op} ${b} violated: ${va} vs ${vb}`
-          });
-        }
-      }
-      return issues;
-    }
-  };
-}
-
-// a minimal parser for "rem"/"px" numbers
-export const parseSize = (v: unknown): number | null => {
-  if (typeof v !== "string") return null;
-  const m = v.trim().match(/^([0-9.]+)(rem|px)?$/i);
-  if (!m) return null;
-  const num = parseFloat(m[1]);
-  const unit = (m[2] || "rem").toLowerCase();
-  return unit === "px" ? num : num * 16; // assume 1rem=16px for comparisons
-};
-
-// Parser for unitless numbers (like scale factors)
-export const parseNumber = (v: unknown): number | null => {
-  if (typeof v === "number") return v;
-  if (typeof v === "string") {
-    const num = parseFloat(v.trim());
-    return isNaN(num) ? null : num;
-  }
-  return null;
-};
-
-// Parser for color lightness (OKLCH L channel)
-export const parseLightness = (v: unknown): number | null => {
-  if (typeof v !== "string") return null;
-  
-  // Match oklch(L C H / A) format
-  const oklchMatch = v.trim().match(/oklch\s*\(\s*([0-9.]+)\s+/i);
-  if (oklchMatch) {
-    return parseFloat(oklchMatch[1]);
-  }
-  
-  // For hex colors, rough approximation (you'd want a proper converter)
-  const hexMatch = v.trim().match(/^#([0-9a-f]{6})$/i);
-  if (hexMatch) {
-    const r = parseInt(hexMatch[1].slice(0, 2), 16) / 255;
-    const g = parseInt(hexMatch[1].slice(2, 4), 16) / 255;
-    const b = parseInt(hexMatch[1].slice(4, 6), 16) / 255;
-    // Simple luminance approximation
-    return 0.299 * r + 0.587 * g + 0.114 * b;
-  }
-  
-  return null;
-};
+// core/constraints/monotonic.ts
+import type { ConstraintPlugin } from "../engine.js";
+import type { Order } from "../poset.js";
+
+export function MonotonicPlugin(
+  orders: Order[], 
+  parse: (v: unknown) => number | null,
+  ruleId = "monotonic"
+): ConstraintPlugin {
+  return {
+    id: ruleId,
+    evaluate(engine, candidates) {
+      const issues = [];
+      for (const [a, op, b] of orders) {
+        const va = parse(engine.get(a));
+        const vb = parse(engine.get(b));
+        if (va == null || vb == null) continue; // skip unparseable
+        const ok = op === ">=" ? va >= vb : va <= vb;
+        if (!ok && (candidates.has(a) || candidates.has(b))) {
+          issues.push({
+            id: `${a}|${b}`,
+            rule: "monotonic",
+            level: "error" as const,
+            message: `${a} ${op} ${b} violated: ${va} vs ${vb}`
+          });
+        }
+      }
+      return issues;
+    }
+  };
+}
+
+// a minimal parser for "rem"/"px" numbers
+export const parseSize = (v: unknown): number | null => {
+  if (typeof v !== "string") return null;
+  const m = v.trim().match(/^([0-9.]+)(rem|px)?$/i);
+  if (!m) return null;
+  const num = parseFloat(m[1]);
+  const unit = (m[2] || "rem").toLowerCase();
+  return unit === "px" ? num : num * 16; // assume 1rem=16px for comparisons
+};
+
+// Parser for unitless numbers (like scale factors)
+export const parseNumber = (v: unknown): number | null => {
+  if (typeof v === "number") return v;
+  if (typeof v === "string") {
+    const num = parseFloat(v.trim());
+    return isNaN(num) ? null : num;
+  }
+  return null;
+};
+
+// Parser for color lightness (OKLCH L channel)
+export const parseLightness = (v: unknown): number | null => {
+  if (typeof v !== "string") return null;
+  
+  // Match oklch(L C H / A) format
+  const oklchMatch = v.trim().match(/oklch\s*\(\s*([0-9.]+)\s+/i);
+  if (oklchMatch) {
+    return parseFloat(oklchMatch[1]);
+  }
+  
+  // For hex colors, rough approximation (you'd want a proper converter)
+  const hexMatch = v.trim().match(/^#([0-9a-f]{6})$/i);
+  if (hexMatch) {
+    const r = parseInt(hexMatch[1].slice(0, 2), 16) / 255;
+    const g = parseInt(hexMatch[1].slice(2, 4), 16) / 255;
+    const b = parseInt(hexMatch[1].slice(4, 6), 16) / 255;
+    // Simple luminance approximation
+    return 0.299 * r + 0.587 * g + 0.114 * b;
+  }
+  
+  return null;
+};

package/core/constraints/threshold.ts

@@ -1,43 +1,43 @@
-import type { ConstraintPlugin } from "../engine.js";
-
-export type ThresholdRule = {
-  id: string;                    // token id to check
-  op: ">=" | "<=";               // comparison
-  valuePx: number;               // threshold in px
-  where?: string;                // optional context label
-  level?: "error" | "warn";      // default error
-};
-
-const parseSizePx = (v: unknown): number | null => {
-  if (typeof v !== "string") return null;
-  const m = v.trim().match(/^([0-9.]+)\s*(px|rem)?$/i);
-  if (!m) return null;
-  const n = parseFloat(m[1]);
-  const unit = (m[2] || "px").toLowerCase();
-  return unit === "rem" ? n * 16 : n;
-};
-
-export function ThresholdPlugin(rules: ThresholdRule[], ruleId = "threshold"): ConstraintPlugin {
-  return {
-    id: ruleId,
-    evaluate(engine, candidates) {
-      const issues = [];
-      for (const r of rules) {
-        if (!candidates.has(r.id)) continue; // incremental
-        const px = parseSizePx(engine.get(r.id));
-        if (px == null) continue;
-        const ok = r.op === ">=" ? px >= r.valuePx : px <= r.valuePx;
-        if (!ok) {
-          issues.push({
-            id: r.id,
-            rule: ruleId,
-            level: r.level ?? "error",
-            where: r.where,
-            message: `${r.id} ${r.op} ${r.valuePx}px violated: ${px}px`
-          });
-        }
-      }
-      return issues;
-    }
-  };
-}
+import type { ConstraintPlugin } from "../engine.js";
+
+export type ThresholdRule = {
+  id: string;                    // token id to check
+  op: ">=" | "<=";               // comparison
+  valuePx: number;               // threshold in px
+  where?: string;                // optional context label
+  level?: "error" | "warn";      // default error
+};
+
+const parseSizePx = (v: unknown): number | null => {
+  if (typeof v !== "string") return null;
+  const m = v.trim().match(/^([0-9.]+)\s*(px|rem)?$/i);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  const unit = (m[2] || "px").toLowerCase();
+  return unit === "rem" ? n * 16 : n;
+};
+
+export function ThresholdPlugin(rules: ThresholdRule[], ruleId = "threshold"): ConstraintPlugin {
+  return {
+    id: ruleId,
+    evaluate(engine, candidates) {
+      const issues = [];
+      for (const r of rules) {
+        if (!candidates.has(r.id)) continue; // incremental
+        const px = parseSizePx(engine.get(r.id));
+        if (px == null) continue;
+        const ok = r.op === ">=" ? px >= r.valuePx : px <= r.valuePx;
+        if (!ok) {
+          issues.push({
+            id: r.id,
+            rule: ruleId,
+            level: r.level ?? "error",
+            where: r.where,
+            message: `${r.id} ${r.op} ${r.valuePx}px violated: ${px}px`
+          });
+        }
+      }
+      return issues;
+    }
+  };
+}

package/core/constraints/wcag.ts

@@ -1,70 +1,70 @@
-import type { ConstraintPlugin } from "../engine.js";
-import type { TokenId } from "../flatten.js";
-import { parseCssColor, compositeOver, relativeLuminance, contrastRatio } from "../color.js";
-
-export type ContrastPair = {
-  fg: TokenId;
-  bg: TokenId;
-  min: number;           // e.g., 4.5
-  where?: string;
-  // Optional ultimate backdrop if bg is transparent; token id or literal color.
-  backdrop?: TokenId | string; // default: "#ffffff"
-};
-
-function resolveColor(engineGet: (id: TokenId)=>unknown, x: TokenId | string): string | undefined {
-  if (typeof x !== "string") return undefined;
-  // If it's a CSS color literal, return as is; else treat as token id.
-  const isLiteral = /^#|^rgb|^hsl|^oklch|^oklab|^transparent/i.test(x);
-  return isLiteral ? x : String(engineGet(x) ?? "");
-}
-
-export function WcagContrastPlugin(pairs: ContrastPair[]): ConstraintPlugin {
-  return {
-    id: "wcag-contrast",
-    evaluate(engine, candidates) {
-      const issues = [];
-      for (const p of pairs) {
-        if (!candidates.has(p.fg) && !candidates.has(p.bg)) continue;
-
-        const fgStr = String(engine.get(p.fg) ?? "");
-        const bgStr = String(engine.get(p.bg) ?? "");
-        const fg = parseCssColor(fgStr);
-        const bgRaw = parseCssColor(bgStr);
-
-        const backdropStr = resolveColor(engine.get.bind(engine), p.backdrop ?? "#ffffff");
-        const backdrop = parseCssColor(backdropStr || "#ffffff");
-
-        if (!fg || !bgRaw || !backdrop) {
-          issues.push({
-            id: `${p.fg}|${p.bg}`,
-            rule: "wcag-contrast",
-            level: "warn" as const,
-            where: p.where,
-            message: `Unparseable color(s): fg="${fgStr}" bg="${bgStr}" backdrop="${backdropStr}"`
-          });
-          continue;
-        }
-
-        // Effective background (handle bg alpha)
-        const effBg = bgRaw.a < 1 ? compositeOver(bgRaw, backdrop) : bgRaw;
-        // Effective foreground over effective background
-        const effFg = fg.a < 1 ? compositeOver(fg, effBg) : fg;
-
-        const Lfg = relativeLuminance(effFg);
-        const Lbg = relativeLuminance(effBg);
-        const ratio = contrastRatio(Lfg, Lbg);
-
-        if (ratio < p.min) {
-          issues.push({
-            id: `${p.fg}|${p.bg}`,
-            rule: "wcag-contrast",
-            level: "error" as const,
-            where: p.where,
-            message: `Contrast ${ratio.toFixed(2)}:1 < ${p.min}:1`
-          });
-        }
-      }
-      return issues;
-    }
-  };
-}
+import type { ConstraintPlugin } from "../engine.js";
+import type { TokenId } from "../flatten.js";
+import { parseCssColor, compositeOver, relativeLuminance, contrastRatio } from "../color.js";
+
+export type ContrastPair = {
+  fg: TokenId;
+  bg: TokenId;
+  min: number;           // e.g., 4.5
+  where?: string;
+  // Optional ultimate backdrop if bg is transparent; token id or literal color.
+  backdrop?: TokenId | string; // default: "#ffffff"
+};
+
+function resolveColor(engineGet: (id: TokenId)=>unknown, x: TokenId | string): string | undefined {
+  if (typeof x !== "string") return undefined;
+  // If it's a CSS color literal, return as is; else treat as token id.
+  const isLiteral = /^#|^rgb|^hsl|^oklch|^oklab|^transparent/i.test(x);
+  return isLiteral ? x : String(engineGet(x) ?? "");
+}
+
+export function WcagContrastPlugin(pairs: ContrastPair[]): ConstraintPlugin {
+  return {
+    id: "wcag-contrast",
+    evaluate(engine, candidates) {
+      const issues = [];
+      for (const p of pairs) {
+        if (!candidates.has(p.fg) && !candidates.has(p.bg)) continue;
+
+        const fgStr = String(engine.get(p.fg) ?? "");
+        const bgStr = String(engine.get(p.bg) ?? "");
+        const fg = parseCssColor(fgStr);
+        const bgRaw = parseCssColor(bgStr);
+
+        const backdropStr = resolveColor(engine.get.bind(engine), p.backdrop ?? "#ffffff");
+        const backdrop = parseCssColor(backdropStr || "#ffffff");
+
+        if (!fg || !bgRaw || !backdrop) {
+          issues.push({
+            id: `${p.fg}|${p.bg}`,
+            rule: "wcag-contrast",
+            level: "warn" as const,
+            where: p.where,
+            message: `Unparseable color(s): fg="${fgStr}" bg="${bgStr}" backdrop="${backdropStr}"`
+          });
+          continue;
+        }
+
+        // Effective background (handle bg alpha)
+        const effBg = bgRaw.a < 1 ? compositeOver(bgRaw, backdrop) : bgRaw;
+        // Effective foreground over effective background
+        const effFg = fg.a < 1 ? compositeOver(fg, effBg) : fg;
+
+        const Lfg = relativeLuminance(effFg);
+        const Lbg = relativeLuminance(effBg);
+        const ratio = contrastRatio(Lfg, Lbg);
+
+        if (ratio < p.min) {
+          issues.push({
+            id: `${p.fg}|${p.bg}`,
+            rule: "wcag-contrast",
+            level: "error" as const,
+            where: p.where,
+            message: `Contrast ${ratio.toFixed(2)}:1 < ${p.min}:1`
+          });
+        }
+      }
+      return issues;
+    }
+  };
+}

package/core/cross-axis-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-axis-config.d.ts","sourceRoot":"","sources":["cross-axis-config.ts"],"names":[],"mappings":"AAQA,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,0CA2HnD"}
+{"version":3,"file":"cross-axis-config.d.ts","sourceRoot":"","sources":["cross-axis-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,0CA2HnD"}

package/core/engine.d.ts

@@ -1,13 +1,90 @@
 import type { TokenId, TokenValue } from "./flatten.js";
+/**
+ * Represents a constraint violation.
+ *
+ * Phase 3C: Enhanced with metadata for tooling and visualization.
+ */
 export type ConstraintIssue = {
     id: TokenId | string;
     rule: string;
     level: "error" | "warn";
     message: string;
     where?: string;
+    /**
+     * Token IDs involved in this violation.
+     * Useful for filtering, highlighting, and incremental validation.
+     *
+     * Example: For a WCAG contrast violation between fg and bg tokens,
+     * this would be [fgTokenId, bgTokenId].
+     */
+    involvedTokens?: TokenId[];
+    /**
+     * Graph edges (reference relationships) involved in this violation.
+     * Useful for visualization and "why" explanations.
+     *
+     * Example: If a token references another that violates a constraint,
+     * this captures that reference edge.
+     */
+    involvedEdges?: Array<[TokenId, TokenId]>;
 };
+/**
+ * Constraint plugin interface.
+ *
+ * Phase 3C: Documented contract for candidate-based evaluation.
+ *
+ * ## Candidate Contract
+ *
+ * Plugins MUST honor the `candidates` set for incremental validation:
+ * - Only evaluate constraints that involve at least one candidate token
+ * - Return violations where at least one involved token is in candidates
+ * - This enables efficient re-validation when tokens change
+ *
+ * ## Metadata Contract
+ *
+ * Plugins SHOULD populate `involvedTokens` in returned issues:
+ * - List all token IDs that participate in the constraint
+ * - This enables filtering, highlighting, and graph visualization
+ * - Optional but recommended for better tooling support
+ *
+ * ## Example Implementation
+ *
+ * ```ts
+ * export function MyPlugin(rules: Rule[]): ConstraintPlugin {
+ *   return {
+ *     id: "my-plugin",
+ *     evaluate(engine, candidates) {
+ *       const issues: ConstraintIssue[] = [];
+ *       for (const rule of rules) {
+ *         // Honor candidates: skip if no involved tokens are candidates
+ *         if (!candidates.has(rule.tokenA) && !candidates.has(rule.tokenB)) {
+ *           continue;
+ *         }
+ *         // Check constraint...
+ *         if (violated) {
+ *           issues.push({
+ *             id: `${rule.tokenA}|${rule.tokenB}`,
+ *             rule: "my-plugin",
+ *             level: "error",
+ *             message: "...",
+ *             involvedTokens: [rule.tokenA, rule.tokenB], // Metadata
+ *           });
+ *         }
+ *       }
+ *       return issues;
+ *     }
+ *   };
+ * }
+ * ```
+ */
 export type ConstraintPlugin = {
     id: string;
+    /**
+     * Evaluate constraints for a set of candidate tokens.
+     *
+     * @param engine Engine instance providing token values and graph
+     * @param candidates Set of token IDs to evaluate (changed + affected)
+     * @returns Array of constraint violations
+     */
     evaluate(engine: Engine, candidates: Set<TokenId>): ConstraintIssue[];
 };
 export type Graph = Map<TokenId, Set<TokenId>>;
@@ -19,6 +96,24 @@ export declare class Engine {
     use(plugin: ConstraintPlugin): this;
     get(id: TokenId): TokenValue | undefined;
     set(id: TokenId, value: TokenValue): void;
+    /**
+     * Get all token IDs in the engine.
+     *
+     * Phase 3C: Exposed for plugins and adapters.
+     * Useful for iterating all tokens or creating a full candidate set.
+     *
+     * @returns Array of all token IDs
+     */
+    getAllIds(): TokenId[];
+    /**
+     * Get flat token map (ID → value).
+     *
+     * Phase 3C: Exposed to avoid duplicate flattening in CLI/adapters.
+     * Returns a plain object suitable for serialization or adapter use.
+     *
+     * @returns Record mapping token IDs to their current values
+     */
+    getFlatTokens(): Record<TokenId, TokenValue>;
     /** All nodes that depend (directly/indirectly) on start. */
     affected(start: TokenId): Set<TokenId>;
     evaluate(candidates: Set<TokenId>): ConstraintIssue[];

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,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;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IAEX,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,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;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"}

package/core/engine.js

@@ -16,6 +16,28 @@ export class Engine {
     use(plugin) { this.plugins.push(plugin); return this; }
     get(id) { return this.values.get(id); }
     set(id, value) { this.values.set(id, value); }
+    /**
+     * Get all token IDs in the engine.
+     *
+     * Phase 3C: Exposed for plugins and adapters.
+     * Useful for iterating all tokens or creating a full candidate set.
+     *
+     * @returns Array of all token IDs
+     */
+    getAllIds() {
+        return Array.from(this.values.keys());
+    }
+    /**
+     * Get flat token map (ID → value).
+     *
+     * Phase 3C: Exposed to avoid duplicate flattening in CLI/adapters.
+     * Returns a plain object suitable for serialization or adapter use.
+     *
+     * @returns Record mapping token IDs to their current values
+     */
+    getFlatTokens() {
+        return Object.fromEntries(this.values);
+    }
     /** All nodes that depend (directly/indirectly) on start. */
     affected(start) {
         const seen = new Set();