inkhouse 0.1.0-beta.0

package/src/class-utils.ts

@@ -0,0 +1,105 @@
+import { type JsxNode, type JsxElement, splitClassName } from './node-ir';
+
+export type ComponentDefResolver = (name: string) => any | null;
+
+export function mergeClasses(base: string[], extra: string[]): string[] {
+  const seen: Record<string, boolean> = {};
+  const out: string[] = [];
+  for (const cls of base || []) {
+    if (!cls || seen[cls]) continue;
+    seen[cls] = true;
+    out.push(cls);
+  }
+  for (const cls of extra || []) {
+    if (!cls || seen[cls]) continue;
+    if (cls === 'rounded' || cls.indexOf('rounded-') === 0) {
+      const nextOut: string[] = [];
+      for (const existing of out) {
+        if (existing === 'rounded' || existing.indexOf('rounded-') === 0) {
+          delete seen[existing];
+          continue;
+        }
+        nextOut.push(existing);
+      }
+      out.length = 0;
+      for (const existing of nextOut) out.push(existing);
+    }
+    seen[cls] = true;
+    out.push(cls);
+  }
+  return out;
+}
+
+export function getCompoundClasses(def: any, tagName: string): string[] {
+  if (!def || def.type !== 'compound' || !def.subComponents) return [];
+  const target = tagName.toLowerCase();
+  let fallback: any = null;
+  for (const sub of def.subComponents) {
+    if (!sub || !sub.name) continue;
+    const subName = String(sub.name).toLowerCase();
+    if (subName === target) return sub.classes || [];
+    if (!fallback && (sub.slot === 'container' || subName === String(def.name || '').toLowerCase())) {
+      fallback = sub;
+    }
+  }
+  if (fallback && String(def.name || '').toLowerCase() === target) {
+    return fallback.classes || [];
+  }
+  return [];
+}
+
+export function treeHasFullWidth(
+  node: JsxNode | undefined,
+  parentCompoundDef: any | null,
+  options: {
+    getComponentDefByName: ComponentDefResolver;
+    normalizeComponentDef: (def: any) => any;
+    hasWidthHintInClasses: (classes: string[]) => boolean;
+    propsContainWidthHint: (props: Record<string, any> | undefined) => boolean;
+  }
+): boolean {
+  if (!node || node.type !== 'element') return false;
+  const el = node as JsxElement;
+  let classes = splitClassName(el.props && el.props.className);
+  let nextParentCompoundDef = parentCompoundDef || null;
+
+  if (el.isComponent) {
+    const compDef = options.getComponentDefByName(el.tagName);
+    if (compDef) {
+      const normalizedDef = options.normalizeComponentDef(compDef);
+      if (normalizedDef.type === 'compound') {
+        nextParentCompoundDef = normalizedDef;
+        const compoundClasses = getCompoundClasses(normalizedDef, el.tagName);
+        if (compoundClasses.length > 0) {
+          classes = mergeClasses(compoundClasses, classes);
+        }
+      }
+
+      const baseClasses = normalizedDef.baseClasses || normalizedDef.classes || [];
+      if (baseClasses.length > 0) {
+        classes = mergeClasses(baseClasses, classes);
+      }
+
+      const variants = normalizedDef.variantClasses || {};
+      const defaults = normalizedDef.defaultVariants || {};
+      for (const key in variants) {
+        const value = (el.props && el.props[key]) || defaults[key];
+        if (value && variants[key] && variants[key][value]) {
+          classes = mergeClasses(variants[key][value], classes);
+        }
+      }
+    } else if (parentCompoundDef) {
+      const inherited = getCompoundClasses(parentCompoundDef, el.tagName);
+      if (inherited.length > 0) {
+        classes = mergeClasses(inherited, classes);
+      }
+    }
+  }
+
+  if (options.hasWidthHintInClasses(classes)) return true;
+  if (options.propsContainWidthHint(el.props)) return true;
+  for (const child of el.children || []) {
+    if (treeHasFullWidth(child, nextParentCompoundDef, options)) return true;
+  }
+  return false;
+}

package/src/clip-path-decorative.ts

@@ -0,0 +1,194 @@
+import { getClassesForBreakpoint } from './responsive-analyzer';
+import { applyTailwindStylesToFrame, markAbsoluteNode, markPositionInfo } from './tailwind';
+import { parseUtilityClass } from './utility-resolver';
+import { resolveBlobDimensions, resolveBlobPlacement } from './blob-placement';
+import { centerPlacedRotationTransform } from './transform-math';
+
+declare const figma: any;
+
+const DEBUG_BLOB_PLACEMENT = false;
+
+export type DecorativeClipPathParams = {
+  clipPathPolygon: string;
+  classes: string[];
+  contextMaxWidth?: number;
+  colorGroup: Record<string, string>;
+  radiusGroup: Record<string, string> | null;
+  theme: string;
+};
+
+export function parseClipPathFromStyle(style: string | Record<string, string> | undefined): string | null {
+  if (!style) return null;
+  if (typeof style === 'object') {
+    const clipPath = (style as any).clipPath || (style as any)['clip-path'];
+    if (!clipPath || typeof clipPath !== 'string') return null;
+    const match = clipPath.match(/polygon\s*\(\s*([^)]+)\s*\)/);
+    if (!match) return null;
+    return match[1].trim();
+  }
+  const match = (style as string).match(/polygon\s*\(\s*([^)]+)\s*\)/);
+  if (!match) return null;
+  return match[1].trim();
+}
+
+export function buildDecorativeClipPathNode(params: DecorativeClipPathParams): SceneNode | null {
+  const { clipPathPolygon, classes, contextMaxWidth, colorGroup, radiusGroup, theme } = params;
+  const activeClasses = (contextMaxWidth != null && contextMaxWidth >= 640)
+    ? getClassesForBreakpoint(classes, 'sm')
+    : classes;
+  const { vectorWidth, vectorHeight } = resolveBlobDimensions(activeClasses);
+  const vector = createVectorFromPolygon(clipPathPolygon, vectorWidth, vectorHeight);
+  if (!vector) return null;
+
+  const blobNode: SceneNode = vector;
+  vector.name = 'gradient-blob';
+  const clippedClasses = stripBlurUtilities(activeClasses);
+  applyTailwindStylesToFrame(vector as any, clippedClasses, colorGroup, radiusGroup, theme);
+
+  const containerWidth = contextMaxWidth;
+  if (containerWidth) {
+    const placement = resolveBlobPlacement(activeClasses, containerWidth, vectorWidth, vectorHeight);
+    const cssRotateDeg = placement.cssRotateDeg;
+    const topOffset = placement.topOffset;
+
+    const mask = figma.createFrame();
+    mask.name = 'gradient-blob-mask';
+    mask.layoutMode = 'NONE';
+    mask.primaryAxisSizingMode = 'FIXED';
+    mask.counterAxisSizingMode = 'FIXED';
+    mask.fills = [];
+    mask.strokes = [];
+    mask.clipsContent = false;
+    mask.resize(containerWidth, vectorHeight);
+
+    const blobBox = figma.createFrame();
+    blobBox.name = 'gradient-blob-box';
+    blobBox.layoutMode = 'NONE';
+    blobBox.primaryAxisSizingMode = 'FIXED';
+    blobBox.counterAxisSizingMode = 'FIXED';
+    blobBox.fills = [];
+    blobBox.strokes = [];
+    blobBox.resize(vectorWidth, vectorHeight);
+    blobBox.appendChild(blobNode);
+    vector.x = 0;
+    vector.y = 0;
+    mask.appendChild(blobBox);
+
+    const usedMatrix = Math.abs(cssRotateDeg) > 0.001
+      ? setTransformFromCenter(blobBox as SceneNode, vectorWidth, vectorHeight, placement.desiredCenterX, placement.desiredCenterY, cssRotateDeg)
+      : false;
+    if (!usedMatrix) {
+      blobBox.x = placement.desiredCenterX - vectorWidth / 2;
+      blobBox.y = 0;
+      if (Math.abs(cssRotateDeg) > 0.001) {
+        try {
+          blobBox.rotation = -cssRotateDeg;
+        } catch (_err) {
+          // ignore rotation errors
+        }
+      }
+    }
+    if (DEBUG_BLOB_PLACEMENT) {
+      console.log('[blob-place]', {
+        containerWidth,
+        vectorWidth,
+        vectorHeight,
+        desiredCenterX: placement.desiredCenterX,
+        desiredCenterY: placement.desiredCenterY,
+        topOffset,
+        cssRotateDeg,
+        usedMatrix,
+      });
+    }
+    return mask;
+  }
+
+  if (contextMaxWidth == null) {
+    const placement = resolveBlobPlacement(activeClasses, 0, vectorWidth, vectorHeight);
+    const cssRotateDeg = placement.cssRotateDeg;
+    if (Math.abs(cssRotateDeg) > 0.001) {
+      try {
+        (blobNode as any).rotation = -cssRotateDeg;
+      } catch (_err) {
+        // ignore rotation errors
+      }
+    }
+    markAbsoluteNode(blobNode);
+    markPositionInfo(blobNode, { left: placement.desiredCenterX - vectorWidth / 2, top: placement.topOffset });
+  }
+  return blobNode;
+}
+
+function createVectorFromPolygon(
+  polygonStr: string,
+  width: number,
+  height: number
+): VectorNode | null {
+  try {
+    const points = parsePolygonPoints(polygonStr, width, height);
+    if (!points || points.length < 3) return null;
+
+    let pathData = `M ${points[0].x} ${points[0].y}`;
+    for (let i = 1; i < points.length; i++) {
+      pathData += ` L ${points[i].x} ${points[i].y}`;
+    }
+    pathData += ' Z';
+
+    const vector = figma.createVector();
+    vector.vectorPaths = [{ windingRule: 'EVENODD', data: pathData }];
+    vector.resize(width, height);
+    vector.strokes = [];
+    vector.fills = [];
+    return vector;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function parsePolygonPoints(
+  polygonStr: string,
+  width: number,
+  height: number
+): { x: number; y: number }[] | null {
+  const points = polygonStr.split(',').map(p => {
+    const parts = p.trim().split(/\s+/);
+    if (parts.length < 2) return null;
+    const x = parseFloat(parts[0].replace('%', '')) / 100;
+    const y = parseFloat(parts[1].replace('%', '')) / 100;
+    if (isNaN(x) || isNaN(y)) return null;
+    return { x: x * width, y: y * height };
+  }).filter(Boolean) as { x: number; y: number }[];
+  return points.length >= 3 ? points : null;
+}
+
+function stripBlurUtilities(classes: string[]): string[] {
+  const next: string[] = [];
+  for (let i = 0; i < classes.length; i++) {
+    const cls = classes[i];
+    const atom = parseUtilityClass(cls);
+    if (!atom.utility) {
+      next.push(cls);
+      continue;
+    }
+    if (/^blur(?:-.+)?$/.test(atom.utility)) continue;
+    next.push(cls);
+  }
+  return next;
+}
+
+function setTransformFromCenter(
+  node: SceneNode,
+  width: number,
+  height: number,
+  centerX: number,
+  centerY: number,
+  rotationDeg: number
+): boolean {
+  const transform = centerPlacedRotationTransform(width, height, centerX, centerY, rotationDeg);
+  try {
+    (node as any).relativeTransform = transform;
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}

package/src/color-resolver.ts

@@ -0,0 +1,98 @@
+import { TOKENS, getThemeColors } from './tokens';
+import type { RGB } from './colors';
+
+const NON_COLOR_TEXT_PREFIXES = new Set([
+  'xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl', '8xl', '9xl',
+  'left', 'center', 'right', 'justify', 'start', 'end', 'wrap', 'nowrap', 'balance', 'pretty',
+]);
+const NON_COLOR_TEXT_TOKENS = new Set([
+  'transparent',
+  'current',
+  'inherit',
+]);
+
+function getBaseClass(value: string): string | null {
+  if (!value) return null;
+  if (value.indexOf(':') !== -1) return null;
+  return value;
+}
+
+function isRgbObject(value: unknown): value is RGB {
+  if (!value || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.r === 'number' && typeof obj.g === 'number' && typeof obj.b === 'number';
+}
+
+export function extractTextColorToken(classes: string[]): string | null {
+  let token: string | null = null;
+  for (const cls of classes) {
+    const base = getBaseClass(cls);
+    if (!base || !base.startsWith('text-')) continue;
+    const raw = base.slice('text-'.length);
+    if (!raw || raw.startsWith('[') || NON_COLOR_TEXT_PREFIXES.has(raw) || NON_COLOR_TEXT_TOKENS.has(raw)) {
+      continue;
+    }
+    token = raw;
+  }
+  if (!token) return null;
+  const match = token.match(/^(.+)\/(\d+)$/);
+  return match ? match[1] : token;
+}
+
+export function resolveColorFromToken(
+  token: string,
+  colorGroup: Record<string, string>,
+  theme: string
+): string | null {
+  if (!token) return null;
+  const match = token.match(/^(.+)\/(\d+)$/);
+  const actualToken = match ? match[1] : token;
+  if (colorGroup[actualToken]) return colorGroup[actualToken];
+  const themeColors = getThemeColors(TOKENS, theme);
+  if (themeColors[actualToken]) return themeColors[actualToken];
+  const themeNames = Object.keys(TOKENS).filter((name) => name !== 'core');
+  for (const themeName of themeNames) {
+    const block = TOKENS[themeName];
+    if (!block || !('color' in block) || !block.color) continue;
+    if (block.color[actualToken]) return block.color[actualToken];
+  }
+  return null;
+}
+
+export function extractCssVarToken(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const match = value.match(/var\(--([^)]+)\)/);
+  if (!match) return null;
+  const token = match[1].replace(/^color-/, '');
+  return token || null;
+}
+
+export function resolveTextColorValue(
+  value: unknown,
+  token: string | null | undefined,
+  colorGroup: Record<string, string>,
+  theme: string
+): string | RGB | null {
+  if (value) {
+    if (isRgbObject(value)) {
+      return value;
+    }
+    const varToken = extractCssVarToken(value);
+    if (varToken) {
+      return resolveColorFromToken(varToken, colorGroup, theme) || String(value);
+    }
+    return typeof value === 'string' ? value : null;
+  }
+  if (token) return resolveColorFromToken(token, colorGroup, theme);
+  return null;
+}
+
+export function resolveTextColorFallback(
+  classes: string[],
+  colorGroup: Record<string, string>,
+  theme: string
+): string | null {
+  const token = extractTextColorToken(classes);
+  if (!token) return null;
+  return resolveColorFromToken(token, colorGroup, theme);
+}

package/src/colors.ts

@@ -0,0 +1,196 @@
+// --- Color parsing: OKLCH -> sRGB ---
+
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+  a?: number;
+}
+
+interface ColorIndexEntry {
+  token: string;
+  rgb: RGB;
+}
+
+// Module-level state for color index
+const COLOR_INDEX: ColorIndexEntry[] = [];
+
+export const DEBUG = false;
+
+export function debug(...args: unknown[]): void {
+  if (!DEBUG) return;
+  try {
+    console.log.apply(console, ["[TailwindTokens]"].concat([].slice.call(args)));
+  } catch (err) {}
+}
+
+export function clamp01(x: number): number {
+  return Math.max(0, Math.min(1, x));
+}
+
+export function oklchToRgb(str: string): RGB {
+  const s = str.trim();
+  if (!s.toLowerCase().startsWith('oklch(') || !s.endsWith(')')) {
+    throw new Error('Unsupported color: ' + str);
+  }
+  let inner = s.slice(6, -1).trim();
+  let alpha = '1';
+  const slash = inner.indexOf('/');
+  if (slash !== -1) {
+    alpha = inner.slice(slash + 1).trim();
+    inner = inner.slice(0, slash).trim();
+  }
+  const parts = inner.split(' ').filter(Boolean);
+  if (parts.length < 3) throw new Error('Invalid OKLCH: ' + str);
+  const [Ls, Cs, Hs] = parts;
+  const L = Ls.endsWith('%') ? parseFloat(Ls) / 100 : parseFloat(Ls);
+  const C = parseFloat(Cs);
+  const H = parseFloat(Hs);
+  const A = alpha.endsWith('%') ? parseFloat(alpha) / 100 : parseFloat(alpha || '1');
+  const hr = (H * Math.PI) / 180;
+  const a = C * Math.cos(hr);
+  const b = C * Math.sin(hr);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l3 = l_ ** 3, m3 = m_ ** 3, s3 = s_ ** 3;
+  let r = 4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3;
+  let g = -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3;
+  let b2 = -0.0041960863 * l3 - 0.7034186147 * m3 + 1.7076147010 * s3;
+  function lin2srgb(c: number): number {
+    return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+  }
+  return { r: clamp01(lin2srgb(r)), g: clamp01(lin2srgb(g)), b: clamp01(lin2srgb(b2)), a: clamp01(A) };
+}
+
+export function parseColor(value: unknown): RGB {
+  if (value && typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    if (typeof obj.r === 'number' && typeof obj.g === 'number' && typeof obj.b === 'number') {
+      return {
+        r: clamp01(obj.r as number),
+        g: clamp01(obj.g as number),
+        b: clamp01(obj.b as number),
+        a: obj.a == null ? 1 : clamp01(obj.a as number)
+      };
+    }
+  }
+  const v = String(value || '').trim();
+  if (v.toLowerCase().startsWith('oklch(')) return oklchToRgb(v);
+  if (/^#([0-9a-f]{3}|([0-9a-f]{2}){3})$/i.test(v)) {
+    let hex = v.slice(1);
+    if (hex.length === 3) hex = hex.split('').map(c => c + c).join('');
+    const n = parseInt(hex, 16);
+    return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255, a: 1 };
+  }
+  return { r: 1, g: 1, b: 1, a: 1 };
+}
+
+export function colorToLabel(value: unknown): string {
+  if (value && typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    if (typeof obj.r === 'number') {
+      const a = obj.a == null ? 1 : Math.round((obj.a as number) * 100) / 100;
+      return 'rgba(' + Math.round((obj.r as number) * 255) + ', ' + Math.round((obj.g as number) * 255) + ', ' + Math.round((obj.b as number) * 255) + ', ' + a + ')';
+    }
+  }
+  return String(value || '');
+}
+
+export function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return !!val && typeof val === 'object' && !Array.isArray(val);
+}
+
+export function mergeTokens(base: unknown, override: unknown): unknown {
+  if (!isPlainObject(base)) return override;
+  const out: Record<string, unknown> = {};
+  for (const key in base) out[key] = base[key];
+  for (const key in (override as Record<string, unknown>)) {
+    if (isPlainObject(base[key]) && isPlainObject((override as Record<string, unknown>)[key])) {
+      out[key] = mergeTokens(base[key], (override as Record<string, unknown>)[key]);
+    } else {
+      out[key] = (override as Record<string, unknown>)[key];
+    }
+  }
+  return out;
+}
+
+export function normalizeThemeName(value: string): string | null {
+  const v = String(value || '').toLowerCase();
+  if (v.indexOf('primary') !== -1) return 'primary';
+  if (v.indexOf('secondary') !== -1) return 'secondary';
+  if (v.indexOf('tertiary') !== -1) return 'tertiary';
+  if (v.indexOf('light') !== -1) return 'primary';
+  if (v.indexOf('dark') !== -1) return 'secondary';
+  if (v.indexOf('core') !== -1 || v.indexOf('base') !== -1) return 'core';
+  return null;
+}
+
+export function normalizeGroupName(value: string): string | null {
+  const v = String(value || '').toLowerCase();
+  if (v === 'colors' || v === 'colour' || v === 'colours') return 'color';
+  if (v === 'radii' || v === 'radius' || v === 'border-radius' || v === 'borderradius') return 'radius';
+  if (v === 'space' || v === 'spacing') return 'spacing';
+  if (v === 'fontsize' || v === 'font-size' || v === 'fontsizes') return 'fontsize';
+  if (v === 'font' || v === 'fonts') return 'font';
+  if (v === 'fontweight' || v === 'font-weight' || v === 'weights') return 'fontWeight';
+  if (v === 'tracking' || v === 'letterspacing' || v === 'letter-spacing') return 'tracking';
+  if (v === 'typography' || v === 'text') return 'typography';
+  if (v === 'color') return 'color';
+  return null;
+}
+
+export function normalizeTypographyProp(value: string): string {
+  const v = String(value || '').toLowerCase();
+  if (v === 'fontsize' || v === 'font-size') return 'fontSize';
+  if (v === 'lineheight' || v === 'line-height') return 'lineHeight';
+  if (v === 'letterspacing' || v === 'letter-spacing') return 'letterSpacing';
+  if (v === 'fontfamily' || v === 'font-family') return 'fontFamily';
+  if (v === 'fontweight' || v === 'font-weight') return 'fontWeight';
+  return value;
+}
+
+export function normalizeSizeValue(value: unknown): string {
+  if (typeof value === 'number') return value + 'px';
+  const raw = String(value || '').trim();
+  if (!raw) return raw;
+  if (raw.startsWith('calc(')) return raw;
+  if (/^-?[0-9.]+(px|rem|em|%)$/i.test(raw)) return raw;
+  if (/^-?[0-9.]+$/.test(raw)) return raw + 'px';
+  return raw;
+}
+
+// --- Color index for nearest-color lookups ---
+
+export function rebuildColorIndex(tokens: any): void {
+  COLOR_INDEX.length = 0;
+  for (const theme of Object.keys(tokens)) {
+    const col: Record<string, unknown> = (tokens[theme] && tokens[theme].color) ? tokens[theme].color : {};
+    for (const [token, value] of Object.entries(col)) {
+      try {
+        COLOR_INDEX.push({ token, rgb: parseColor(value) });
+      } catch (err) {
+        // ignore bad color
+      }
+    }
+  }
+}
+
+export function dist2(a: RGB, b: RGB): number {
+  const dr = a.r - b.r, dg = a.g - b.g, db = a.b - b.b;
+  return dr * dr + dg * dg + db * db;
+}
+
+export function nearestColorToken(rgb: RGB | null): string | null {
+  if (!rgb) return null;
+  let bestToken: string | null = null;
+  let best = Infinity;
+  for (const entry of COLOR_INDEX) {
+    const d = dist2(rgb, entry.rgb);
+    if (d < best) {
+      best = d;
+      bestToken = entry.token;
+    }
+  }
+  return bestToken;
+}

package/src/component-defs.ts

@@ -0,0 +1,54 @@
+import { COMPONENT_DEFS } from './tokens';
+
+// --- Component Definition Helpers ---
+// These helpers let the plugin dynamically read from scanned component definitions
+
+export function getComponentDef(name: string): any | null {
+  if (!COMPONENT_DEFS || !COMPONENT_DEFS.components) return null;
+  for (const raw of COMPONENT_DEFS.components) {
+    const def = raw && raw.analysis ? raw.analysis : raw;
+    if (def && def.name && def.name.toLowerCase() === name.toLowerCase()) {
+      return def;
+    }
+  }
+  return null;
+}
+
+export function getCVAComponentVariants(name: string): any | null {
+  const def = getComponentDef(name);
+  if (!def || def.type !== 'cva') return null;
+  return def.variants;
+}
+
+export function getCVAComponentClasses(name: string, variantName?: string, variantValue?: string): string[] {
+  const def = getComponentDef(name);
+  if (!def || def.type !== 'cva') return [];
+  const classes: string[] = def.baseClasses.slice();
+  if (variantName && variantValue && def.variantClasses && def.variantClasses[variantName]) {
+    const variantClasses = def.variantClasses[variantName][variantValue];
+    if (variantClasses) {
+      return classes.concat(variantClasses);
+    }
+  }
+  return classes;
+}
+
+export function getStateComponentStates(name: string): string[] | null {
+  const def = getComponentDef(name);
+  if (!def || def.type !== 'state') return null;
+  return Object.keys(def.states);
+}
+
+export function getCompoundSubComponents(name: string): any[] | null {
+  const def = getComponentDef(name);
+  if (!def || def.type !== 'compound') return null;
+  return def.subComponents;
+}
+
+export function listAllComponents(): { name: string; type: string }[] {
+  if (!COMPONENT_DEFS || !COMPONENT_DEFS.components) return [];
+  return COMPONENT_DEFS.components.map((raw: any) => {
+    const def = raw && raw.analysis ? raw.analysis : raw;
+    return { name: def?.name, type: def?.type };
+  });
+}