@3fn/core 13.0.0

package/dist/figma/DesignExtractor.js

@@ -0,0 +1,2838 @@
+"use strict";
+/**
+ * DesignExtractor — Reads Figma designs via dual-MCP strategy and generates
+ * design-outline.md documents with confidence flags.
+ *
+ * Uses Kiro Figma Power for rich design context and figma-console-mcp for
+ * variable/style data. Orchestrates TokenTranslator for value matching and
+ * VariantAnalyzer for context-aware recommendations.
+ *
+ * @see Design: .kiro/specs/054b-figma-design-extract/design.md
+ * @requirements Req 1 (DesignExtractor Implementation)
+ * @spec 054b-figma-design-extract
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DesignExtractor = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const https_1 = __importDefault(require("https"));
+const http_1 = __importDefault(require("http"));
+// ---------------------------------------------------------------------------
+// DesignExtractor
+// ---------------------------------------------------------------------------
+/**
+ * Orchestrates extraction from Figma via dual-MCP strategy and generates
+ * design-outline.md documents.
+ *
+ * Uses:
+ * - Kiro Figma Power for rich design context (component structure, layout)
+ * - figma-console-mcp via ConsoleMCPClient for variables and styles
+ * - TokenTranslator for Figma value → DesignerPunk token matching
+ * - VariantAnalyzer for context-aware variant mapping recommendations
+ */
+class DesignExtractor {
+    constructor(consoleMcp, translator, analyzer, kiroPower, mcpDocs) {
+        this.consoleMcp = consoleMcp;
+        this.translator = translator;
+        this.analyzer = analyzer;
+        this.kiroPower = kiroPower;
+        this.mcpDocs = mcpDocs;
+    }
+    // -------------------------------------------------------------------------
+    // readFigmaComponent (Task 3.2)
+    // -------------------------------------------------------------------------
+    /**
+     * Read a Figma component via dual-MCP strategy.
+     *
+     * Primary: Kiro Figma Power `get_design_context` for rich component
+     * structure (layout, properties, visual states).
+     * Fallback: `get_metadata` + figma-console-mcp `figma_get_component`
+     * if `get_design_context` lacks detail or Kiro Power is unavailable.
+     *
+     * @param fileKey - The Figma file key.
+     * @param nodeId - The node ID of the component to extract.
+     * @returns An ExtractedComponent with structure, layout, and states.
+     * @throws Error if component cannot be read from either MCP source.
+     */
+    async readFigmaComponent(fileKey, nodeId) {
+        // Try primary path: Kiro Figma Power
+        if (this.kiroPower) {
+            try {
+                const designContext = await this.kiroPower.getDesignContext(fileKey, nodeId);
+                if (designContext.code && designContext.code.trim().length > 0) {
+                    const extracted = this.parseDesignContext(designContext);
+                    if (extracted.name) {
+                        return {
+                            ...extracted,
+                            rawDesignContext: designContext.code,
+                            source: 'kiro-power',
+                        };
+                    }
+                }
+            }
+            catch {
+                // Kiro Power failed — fall through to fallback
+            }
+        }
+        // Fallback: get_metadata + figma_get_component
+        return this.readFigmaComponentFallback(fileKey, nodeId);
+    }
+    /**
+     * Parse Kiro Figma Power `get_design_context` response into an
+     * ExtractedComponent.
+     *
+     * Extracts component name, description, variants, states, properties,
+     * and layout from the generated code string.
+     */
+    parseDesignContext(response) {
+        const code = response.code ?? '';
+        return {
+            name: this.extractComponentName(code),
+            description: this.extractDescription(code),
+            variants: this.extractVariants(code),
+            states: this.extractStates(code),
+            properties: this.extractProperties(code),
+            layout: this.extractLayout(code),
+            source: 'kiro-power',
+        };
+    }
+    /**
+     * Fallback component reading via get_metadata + figma_get_component.
+     *
+     * Primary extraction path when Kiro Power is unavailable (which is the
+     * common case). Extracts structured layout data, boundVariables, fills,
+     * and cornerRadius directly from the Console MCP component response.
+     */
+    async readFigmaComponentFallback(fileKey, nodeId) {
+        // Try metadata from Kiro Power if available
+        let rawMetadata;
+        if (this.kiroPower) {
+            try {
+                const metadata = await this.kiroPower.getMetadata(fileKey, nodeId);
+                rawMetadata = metadata.xml;
+            }
+            catch {
+                // Metadata unavailable — continue without it
+            }
+        }
+        // Get component data from figma-console-mcp
+        let componentData;
+        try {
+            componentData = await this.consoleMcp.getComponent(fileKey, nodeId);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to read Figma component (file: ${fileKey}, node: ${nodeId}): ${msg}`);
+        }
+        if (!componentData.name) {
+            throw new Error(`Component not found or invalid node ID (file: ${fileKey}, node: ${nodeId})`);
+        }
+        // Build variants from variantProperties map
+        const variants = [];
+        if (componentData.variantProperties) {
+            const propEntries = Object.entries(componentData.variantProperties);
+            if (propEntries.length > 0) {
+                // Generate variant combinations from the first property's values
+                const [firstProp, firstValues] = propEntries[0];
+                for (const val of firstValues) {
+                    variants.push({
+                        name: `${firstProp}=${val}`,
+                        properties: { [firstProp]: val },
+                    });
+                }
+            }
+        }
+        // Extract component properties and states from children's componentProperties.
+        // Children of a COMPONENT_SET carry componentProperties like:
+        //   { "State": { value: "Incomplete", type: "VARIANT" },
+        //     "Size": { value: "Sm", type: "VARIANT" },
+        //     "Show Label#1231:0": { type: "BOOLEAN", value: false } }
+        const { properties, states: childStates } = this.extractChildComponentProperties(componentData);
+        // Extract states from metadata XML if available, merge with child states
+        const metadataStates = rawMetadata ? this.extractStatesFromMetadata(rawMetadata) : [];
+        const stateNames = new Set(metadataStates.map(s => s.name));
+        for (const cs of childStates) {
+            if (!stateNames.has(cs.name)) {
+                metadataStates.push(cs);
+                stateNames.add(cs.name);
+            }
+        }
+        // Extract structured layout data from component children
+        const { layout, boundVariableMap, cornerRadius, fills } = this.extractLayoutFromComponentData(componentData);
+        return {
+            name: componentData.name,
+            description: componentData.description ?? '',
+            variants,
+            states: metadataStates,
+            properties,
+            layout,
+            boundVariableMap,
+            cornerRadius,
+            fills,
+            rawMetadata,
+            source: 'console-mcp-fallback',
+        };
+    }
+    /**
+     * Extract structured layout data from a Console MCP component response.
+     *
+     * Walks the component's children (variant instances in a component set)
+     * to extract padding, itemSpacing, cornerRadius, fills, and boundVariables.
+     * Uses the first child with layout data as the representative, since
+     * variant children typically share the same structural tokens.
+     *
+     * boundVariables entries use VARIABLE_ALIAS format:
+     *   { "paddingLeft": { "type": "VARIABLE_ALIAS", "id": "VariableID:..." } }
+     *
+     * We resolve variable IDs to names via the bindings loaded separately
+     * in readTokenBindings(). Here we store the raw property→variableId map
+     * and also extract any inline variable name references.
+     */
+    /**
+       * Extract structured layout data from a Console MCP component response.
+       *
+       * Walks the component's children recursively to extract padding,
+       * itemSpacing, cornerRadius, fills, and boundVariables. Uses the first
+       * child with layout data as the representative for spacing/layout, and
+       * collects boundVariables from all levels of the tree (since bindings
+       * often live on grandchildren — e.g. fill color bindings on inner frames).
+       *
+       * boundVariables entries use VARIABLE_ALIAS format:
+       *   { "paddingLeft": { "type": "VARIABLE_ALIAS", "id": "VariableID:..." } }
+       *
+       * Fill-level boundVariables are nested inside the fills array:
+       *   fills: [{ color: {...}, boundVariables: { color: { id: "..." } } }]
+       *
+       * We resolve variable IDs to names via the bindings loaded separately
+       * in readTokenBindings(). Here we store the raw property→variableId map.
+       */
+    extractLayoutFromComponentData(componentData) {
+        const boundVariableMap = new Map();
+        let layout = { mode: 'none' };
+        let cornerRadius;
+        let fills;
+        // The component data may be a component set (with children) or a single component.
+        // Try children first, then fall back to the component itself.
+        const raw = componentData;
+        const children = raw.children;
+        const nodesToInspect = children && children.length > 0
+            ? children
+            : [raw];
+        for (const node of nodesToInspect) {
+            // Extract layout mode from layoutMode field
+            const layoutMode = node.layoutMode;
+            if (layoutMode && layout.mode === 'none') {
+                if (layoutMode === 'HORIZONTAL')
+                    layout.mode = 'horizontal';
+                else if (layoutMode === 'VERTICAL')
+                    layout.mode = 'vertical';
+            }
+            // Extract spacing values — use first node that has them
+            const itemSpacing = node.itemSpacing;
+            if (itemSpacing != null && layout.itemSpacing == null) {
+                layout.itemSpacing = itemSpacing;
+            }
+            // Extract padding
+            const pTop = node.paddingTop;
+            const pRight = node.paddingRight;
+            const pBottom = node.paddingBottom;
+            const pLeft = node.paddingLeft;
+            if ((pTop != null || pRight != null || pBottom != null || pLeft != null) && !layout.padding) {
+                layout.padding = {
+                    top: pTop,
+                    right: pRight,
+                    bottom: pBottom,
+                    left: pLeft,
+                };
+            }
+            // Extract corner radius
+            const cr = node.cornerRadius;
+            if (cr != null && cornerRadius == null) {
+                cornerRadius = cr;
+            }
+            // Extract fills from this node (top-level fills for the component)
+            const nodeFills = node.fills;
+            if (nodeFills && nodeFills.length > 0 && !fills) {
+                fills = nodeFills.map((f) => {
+                    const color = f.color;
+                    let colorStr;
+                    if (color) {
+                        const r = Math.round((color.r ?? 0) * 255);
+                        const g = Math.round((color.g ?? 0) * 255);
+                        const b = Math.round((color.b ?? 0) * 255);
+                        colorStr = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+                    }
+                    // Extract fill-level boundVariables (e.g. color bound to a variable)
+                    const fillBoundVars = f.boundVariables;
+                    if (fillBoundVars) {
+                        this.extractBoundVariables(fillBoundVars, boundVariableMap);
+                    }
+                    return {
+                        type: String(f.type ?? 'SOLID'),
+                        color: colorStr,
+                        opacity: f.opacity,
+                    };
+                });
+            }
+            // Extract node-level boundVariables (spacing, padding, radius bindings)
+            const boundVars = node.boundVariables;
+            if (boundVars) {
+                this.extractBoundVariables(boundVars, boundVariableMap);
+            }
+            // Stop scanning siblings once we have layout data (spacing/padding)
+            if (layout.mode !== 'none')
+                break;
+        }
+        // Always walk the full tree for boundVariables and deep fills.
+        // boundVariables and color bindings often live on grandchildren
+        // (e.g. fill color bindings on inner frames within instance children).
+        // We collect ALL of them, not just the first match.
+        for (const node of nodesToInspect) {
+            this.collectBoundVariablesRecursive(node, boundVariableMap, 0, 4);
+        }
+        // Collect fills from deep children that have boundVariables on their
+        // fills — these represent designer-intentional color assignments that
+        // the top-level fills may not capture.
+        const deepFills = this.collectDeepFills(nodesToInspect);
+        if (deepFills.length > 0) {
+            // Merge deep fills with top-level fills, deduplicating by color value
+            const existingColors = new Set((fills ?? []).map(f => f.color));
+            for (const df of deepFills) {
+                if (df.color && !existingColors.has(df.color)) {
+                    if (!fills)
+                        fills = [];
+                    fills.push(df);
+                    existingColors.add(df.color);
+                }
+            }
+        }
+        return { layout, boundVariableMap, cornerRadius, fills };
+    }
+    /**
+     * Extract component properties and visual states from children's
+     * componentProperties fields.
+     *
+     * Walks all children (and grandchildren) looking for `componentProperties`
+     * objects. Extracts:
+     * - VARIANT properties with value matching known state names → StateDefinition
+     * - VARIANT properties → PropertyDefinition (with type from variant options)
+     * - BOOLEAN properties → PropertyDefinition
+     *
+     * Deduplicates by property name (strips Figma hash suffixes like "#1231:0").
+     */
+    extractChildComponentProperties(componentData) {
+        const properties = [];
+        const states = [];
+        const seenProps = new Set();
+        const seenStates = new Set();
+        const stateKeywords = new Set([
+            'hover', 'focus', 'disabled', 'pressed', 'active', 'selected',
+            'error', 'loading', 'incomplete', 'complete', 'current',
+        ]);
+        const raw = componentData;
+        const children = raw.children;
+        if (!children)
+            return { properties, states };
+        const walkNode = (node) => {
+            const cp = node.componentProperties;
+            if (cp) {
+                for (const [rawName, def] of Object.entries(cp)) {
+                    // Strip Figma hash suffix (e.g. "Show Label#1231:0" → "Show Label")
+                    const cleanName = rawName.replace(/#[\d:]+$/, '').trim();
+                    if (seenProps.has(cleanName))
+                        continue;
+                    seenProps.add(cleanName);
+                    if (def.type === 'VARIANT') {
+                        const value = String(def.value ?? '');
+                        // Check if this variant value is a visual state
+                        if (stateKeywords.has(value.toLowerCase()) && !seenStates.has(value.toLowerCase())) {
+                            states.push({ name: value.toLowerCase() });
+                            seenStates.add(value.toLowerCase());
+                        }
+                        properties.push({
+                            name: cleanName,
+                            type: 'variant',
+                            defaultValue: value,
+                        });
+                    }
+                    else if (def.type === 'BOOLEAN') {
+                        properties.push({
+                            name: cleanName,
+                            type: 'boolean',
+                            defaultValue: String(def.value ?? 'false'),
+                        });
+                    }
+                }
+            }
+            // Recurse into children
+            const nodeChildren = node.children;
+            if (nodeChildren) {
+                for (const child of nodeChildren) {
+                    walkNode(child);
+                }
+            }
+        };
+        for (const child of children) {
+            walkNode(child);
+        }
+        return { properties, states };
+    }
+    // -------------------------------------------------------------------------
+    // Hierarchical Node Tree Construction (Task 1.3)
+    // -------------------------------------------------------------------------
+    /**
+     * Build a hierarchical node tree with per-node token classifications.
+     *
+     * Recursively walks the Figma node tree preserving parent-child
+     * relationships. Each node carries its own token classifications
+     * (semantic, primitive, unidentified) rather than flattening them.
+     *
+     * @param figmaNode - Raw Figma node object from API response
+     * @param depth - Current depth in the tree (root = 0)
+     * @param ancestors - Ancestor node types from root to parent
+     * @returns NodeWithClassifications tree
+     * @requirements Req 2 (Hierarchical Node Tree Preservation)
+     */
+    buildNodeTree(figmaNode, depth = 0, ancestors = []) {
+        const nodeType = figmaNode.type ?? 'FRAME';
+        const validTypes = new Set([
+            'COMPONENT_SET', 'COMPONENT', 'INSTANCE', 'FRAME', 'TEXT',
+        ]);
+        const type = validTypes.has(nodeType)
+            ? nodeType
+            : 'FRAME';
+        const node = {
+            id: String(figmaNode.id ?? ''),
+            name: String(figmaNode.name ?? ''),
+            type,
+            depth,
+            ancestorChain: ancestors,
+            tokenClassifications: {
+                semanticIdentified: [],
+                primitiveIdentified: [],
+                unidentified: [],
+            },
+            children: [],
+        };
+        // Extract layout properties
+        node.layout = this.extractNodeLayout(figmaNode);
+        // Extract text style for TEXT nodes
+        if (type === 'TEXT') {
+            node.textStyle = this.extractTextStyle(figmaNode);
+        }
+        // Extract stroke colors
+        const strokes = figmaNode.strokes;
+        if (strokes?.length) {
+            const extracted = [];
+            for (const stroke of strokes) {
+                const c = stroke.color;
+                if (!c)
+                    continue;
+                const r = Math.round((c.r ?? 0) * 255);
+                const g = Math.round((c.g ?? 0) * 255);
+                const b = Math.round((c.b ?? 0) * 255);
+                const a = (c.a ?? 1) * (stroke.opacity ?? 1);
+                extracted.push({ color: `rgba(${r}, ${g}, ${b}, ${a})` });
+            }
+            if (extracted.length)
+                node.strokes = extracted;
+        }
+        // Extract componentProperties for INSTANCE nodes
+        if (type === 'INSTANCE') {
+            node.componentProperties = this.extractNodeComponentProperties(figmaNode);
+        }
+        // Classify tokens for this node
+        this.classifyNodeTokens(figmaNode, node);
+        // Recursively build children
+        const children = figmaNode.children;
+        if (children) {
+            const newAncestors = [...ancestors, nodeType];
+            node.children = children.map(child => this.buildNodeTree(child, depth + 1, newAncestors));
+        }
+        return node;
+    }
+    /**
+     * Detect composition patterns in a node tree.
+     *
+     * Groups INSTANCE children by component name and identifies repeated
+     * usage patterns with shared properties and property variations.
+     * Applies recursively at every level of the node tree.
+     *
+     * @param nodeTree - Root of the classified node tree
+     * @returns Array of detected composition patterns across all tree levels
+     * @requirements Req 3 (Composition Pattern Detection)
+     */
+    detectCompositionPatterns(nodeTree) {
+        const patterns = [];
+        this.detectPatternsAtLevel(nodeTree, patterns);
+        return patterns;
+    }
+    /**
+     * Detect composition patterns at a single level and recurse into children.
+     */
+    detectPatternsAtLevel(node, patterns) {
+        if (node.children.length > 0) {
+            // Group INSTANCE children by component name
+            const grouped = new Map();
+            for (const child of node.children) {
+                if (child.type === 'INSTANCE') {
+                    const existing = grouped.get(child.name);
+                    if (existing) {
+                        existing.push(child);
+                    }
+                    else {
+                        grouped.set(child.name, [child]);
+                    }
+                }
+            }
+            // Build patterns for groups with 2+ instances
+            for (const [componentName, instances] of grouped) {
+                if (instances.length < 2)
+                    continue;
+                const shared = this.findSharedProperties(instances);
+                const variations = this.groupByPropertyVariations(instances, shared);
+                patterns.push({
+                    componentName,
+                    count: instances.length,
+                    sharedProperties: shared,
+                    propertyVariations: variations,
+                    depth: instances[0].depth,
+                });
+            }
+            // Recurse into all children (not just INSTANCE)
+            for (const child of node.children) {
+                this.detectPatternsAtLevel(child, patterns);
+            }
+        }
+    }
+    /**
+     * Find properties shared across all instances in a group.
+     *
+     * A property is "shared" when every instance has the same value for it.
+     */
+    findSharedProperties(instances) {
+        const first = instances[0].componentProperties;
+        if (!first || instances.length === 0)
+            return {};
+        const shared = {};
+        for (const [key, def] of Object.entries(first)) {
+            const allSame = instances.every(inst => {
+                const cp = inst.componentProperties;
+                if (!cp || !(key in cp))
+                    return false;
+                return this.valuesEqual(cp[key].value, def.value);
+            });
+            if (allSame) {
+                shared[key] = def.value;
+            }
+        }
+        return shared;
+    }
+    /**
+     * Group instances by their non-shared property combinations.
+     *
+     * Returns distinct property value combinations with counts.
+     */
+    groupByPropertyVariations(instances, sharedProperties) {
+        const variationMap = new Map();
+        for (const inst of instances) {
+            const cp = inst.componentProperties;
+            const varying = {};
+            if (cp) {
+                for (const [key, def] of Object.entries(cp)) {
+                    if (!(key in sharedProperties)) {
+                        varying[key] = def.value;
+                    }
+                }
+            }
+            const key = JSON.stringify(varying, Object.keys(varying).sort());
+            const existing = variationMap.get(key);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                variationMap.set(key, { properties: varying, count: 1 });
+            }
+        }
+        return Array.from(variationMap.values());
+    }
+    // -----------------------------------------------------------------------
+    // Screenshot Capture (Task 2.3)
+    // -----------------------------------------------------------------------
+    /**
+     * Capture a component screenshot via figma-console-mcp.
+     *
+     * Calls `figma_get_component_image` at 2x scale in PNG format.
+     * On failure, logs a warning and returns null so extraction can
+     * continue without a screenshot.
+     *
+     * @param fileKey - The Figma file key.
+     * @param nodeId - The node ID of the component to capture.
+     * @param outputDir - Directory for storing screenshot images.
+     * @param componentName - Component name for the filename.
+     * @param variant - Optional variant identifier for the filename.
+     * @returns ScreenshotMetadata or null if capture failed.
+     * @requirements Req 5 (Component Screenshots)
+     */
+    async captureComponentScreenshot(fileUrl, nodeId, outputDir, componentName, variant) {
+        try {
+            const result = await this.consoleMcp.getComponentImage(fileUrl, nodeId, {
+                scale: 2,
+                format: 'png',
+            });
+            if (!result.imageUrl) {
+                console.warn(`[DesignExtractor] Screenshot capture returned no image URL for "${componentName}"`);
+                return null;
+            }
+            // Build filename
+            const safeName = componentName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+            const safeVariant = variant
+                ? '-' + variant.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+                : '';
+            const filename = `${safeName}${safeVariant}.png`;
+            const relativePath = `./images/${filename}`;
+            // Download image to disk
+            const absPath = path.join(outputDir, 'images', filename);
+            try {
+                await this.downloadFile(result.imageUrl, absPath);
+            }
+            catch (dlErr) {
+                const msg = dlErr instanceof Error ? dlErr.message : String(dlErr);
+                console.warn(`[DesignExtractor] Image download failed for "${componentName}": ${msg}`);
+            }
+            return {
+                filePath: relativePath,
+                url: result.imageUrl,
+                format: 'png',
+                scale: 2,
+                variant,
+                capturedAt: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.warn(`[DesignExtractor] Screenshot capture failed for "${componentName}": ${msg}`);
+            return null;
+        }
+    }
+    /** Download a file from a URL to a local path. */
+    downloadFile(url, dest) {
+        return new Promise((resolve, reject) => {
+            const mod = url.startsWith('https') ? https_1.default : http_1.default;
+            const file = fs.createWriteStream(dest);
+            mod.get(url, (res) => {
+                if (res.statusCode === 301 || res.statusCode === 302) {
+                    file.close();
+                    fs.unlinkSync(dest);
+                    this.downloadFile(res.headers.location, dest).then(resolve, reject);
+                    return;
+                }
+                if (res.statusCode !== 200) {
+                    file.close();
+                    fs.unlinkSync(dest);
+                    reject(new Error(`HTTP ${res.statusCode}`));
+                    return;
+                }
+                res.pipe(file);
+                file.on('finish', () => { file.close(); resolve(); });
+            }).on('error', (err) => {
+                file.close();
+                fs.unlinkSync(dest);
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Deep equality check for property values.
+     */
+    valuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (a === null || b === null)
+            return false;
+        if (typeof a !== typeof b)
+            return false;
+        if (typeof a === 'object') {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        return false;
+    }
+    /**
+     * Extract layout properties from a single Figma node.
+     *
+     * Returns undefined when the node has no layout-related properties,
+     * keeping the node tree compact.
+     */
+    extractNodeLayout(node) {
+        const layoutMode = node.layoutMode;
+        const pTop = node.paddingTop;
+        const pRight = node.paddingRight;
+        const pBottom = node.paddingBottom;
+        const pLeft = node.paddingLeft;
+        const itemSpacing = node.itemSpacing;
+        const counterAxisSpacing = node.counterAxisSpacing;
+        const cornerRadius = node.cornerRadius;
+        const width = node.width;
+        const height = node.height;
+        const layoutSizingH = node.layoutSizingHorizontal;
+        const layoutSizingV = node.layoutSizingVertical;
+        const primaryAlign = node.primaryAxisAlignItems;
+        const counterAlign = node.counterAxisAlignItems;
+        const layoutAlign = node.layoutAlign;
+        const layoutGrow = node.layoutGrow;
+        const opacity = node.opacity;
+        const strokeWeight = node.strokeWeight;
+        const strokeAlign = node.strokeAlign;
+        const hasLayout = layoutMode != null ||
+            pTop != null || pRight != null || pBottom != null || pLeft != null ||
+            itemSpacing != null || counterAxisSpacing != null || cornerRadius != null ||
+            width != null || height != null || opacity != null || strokeWeight != null;
+        if (!hasLayout)
+            return undefined;
+        const layout = {};
+        if (layoutMode === 'HORIZONTAL' || layoutMode === 'VERTICAL') {
+            layout.layoutMode = layoutMode;
+        }
+        else if (layoutMode) {
+            layout.layoutMode = 'NONE';
+        }
+        if (pTop != null || pRight != null || pBottom != null || pLeft != null) {
+            layout.padding = {
+                top: pTop ?? 0,
+                right: pRight ?? 0,
+                bottom: pBottom ?? 0,
+                left: pLeft ?? 0,
+            };
+        }
+        if (itemSpacing != null)
+            layout.itemSpacing = itemSpacing;
+        if (counterAxisSpacing != null)
+            layout.counterAxisSpacing = counterAxisSpacing;
+        if (cornerRadius != null)
+            layout.cornerRadius = cornerRadius;
+        if (width != null)
+            layout.width = width;
+        if (height != null)
+            layout.height = height;
+        if (layoutSizingH === 'FIXED' || layoutSizingH === 'HUG' || layoutSizingH === 'FILL') {
+            layout.layoutSizingHorizontal = layoutSizingH;
+        }
+        if (layoutSizingV === 'FIXED' || layoutSizingV === 'HUG' || layoutSizingV === 'FILL') {
+            layout.layoutSizingVertical = layoutSizingV;
+        }
+        if (primaryAlign)
+            layout.primaryAxisAlignItems = primaryAlign;
+        if (counterAlign)
+            layout.counterAxisAlignItems = counterAlign;
+        if (layoutAlign)
+            layout.layoutAlign = layoutAlign;
+        if (layoutGrow != null)
+            layout.layoutGrow = layoutGrow;
+        if (opacity != null && opacity !== 1)
+            layout.opacity = opacity;
+        if (strokeWeight != null && strokeWeight > 0)
+            layout.strokeWeight = strokeWeight;
+        if (strokeAlign)
+            layout.strokeAlign = strokeAlign;
+        return layout;
+    }
+    /**
+     * Extract text style properties from a TEXT node.
+     */
+    extractTextStyle(node) {
+        const style = {};
+        let hasData = false;
+        const chars = node.characters;
+        if (chars != null) {
+            style.characters = chars;
+            hasData = true;
+        }
+        const fontSize = node.fontSize;
+        if (fontSize != null) {
+            style.fontSize = fontSize;
+            hasData = true;
+        }
+        const fontName = node.fontName;
+        if (fontName?.family) {
+            style.fontFamily = fontName.family;
+            hasData = true;
+        }
+        if (fontName?.style) {
+            style.fontStyle = fontName.style;
+            hasData = true;
+        }
+        const fontWeight = node.fontWeight;
+        if (fontWeight != null) {
+            style.fontWeight = fontWeight;
+            hasData = true;
+        }
+        const lh = node.lineHeight;
+        if (lh?.value != null && lh.unit !== 'AUTO') {
+            style.lineHeight = lh.value;
+            hasData = true;
+        }
+        const ls = node.letterSpacing;
+        if (ls?.value != null && ls.value !== 0) {
+            style.letterSpacing = ls.value;
+            hasData = true;
+        }
+        const tah = node.textAlignHorizontal;
+        if (tah) {
+            style.textAlignHorizontal = tah;
+            hasData = true;
+        }
+        const tav = node.textAlignVertical;
+        if (tav) {
+            style.textAlignVertical = tav;
+            hasData = true;
+        }
+        return hasData ? style : undefined;
+    }
+    /**
+     * Extract componentProperties from an INSTANCE node.
+     *
+     * Strips Figma hash suffixes (e.g. "Show Label#1231:0" → "Show Label")
+     * and returns undefined when no properties exist.
+     */
+    extractNodeComponentProperties(node) {
+        const cp = node.componentProperties;
+        if (!cp || Object.keys(cp).length === 0)
+            return undefined;
+        const result = {};
+        for (const [rawName, def] of Object.entries(cp)) {
+            const cleanName = rawName.replace(/#[\d:]+$/, '').trim();
+            const type = def.type;
+            result[cleanName] = { type, value: def.value };
+        }
+        return result;
+    }
+    /**
+     * Classify tokens for a single Figma node using TokenTranslator.
+     *
+     * Collects spacing, radius, and fill-color properties from the node,
+     * translates each via the translator, and sorts results into the
+     * three-tier classification buckets on the node.
+     */
+    classifyNodeTokens(figmaNode, node) {
+        const propertiesToClassify = [];
+        // Spacing properties
+        const spacingProps = [
+            ['paddingTop', 'padding-top'],
+            ['paddingRight', 'padding-right'],
+            ['paddingBottom', 'padding-bottom'],
+            ['paddingLeft', 'padding-left'],
+            ['itemSpacing', 'item-spacing'],
+            ['counterAxisSpacing', 'counter-axis-spacing'],
+        ];
+        const boundVars = figmaNode.boundVariables;
+        const layoutMode = figmaNode.layoutMode;
+        const nodeType = figmaNode.type;
+        const isLeaf = nodeType === 'TEXT' || nodeType === 'VECTOR'
+            || nodeType === 'ELLIPSE' || nodeType === 'LINE'
+            || nodeType === 'STAR' || nodeType === 'POLYGON';
+        for (const [figmaProp, cssProp] of spacingProps) {
+            const value = figmaNode[figmaProp];
+            if (value == null)
+                continue;
+            // Skip irrelevant zero-value defaults
+            if (cssProp === 'counter-axis-spacing' && value === 0)
+                continue;
+            if (cssProp === 'item-spacing' && layoutMode === 'NONE')
+                continue;
+            if (isLeaf && cssProp.startsWith('padding-') && value === 0)
+                continue;
+            const varName = this.getBoundVariableName(boundVars, figmaProp);
+            propertiesToClassify.push({
+                property: cssProp,
+                figmaVarName: varName,
+                rawValue: value,
+                category: 'spacing',
+            });
+        }
+        // Corner radius
+        const cornerRadius = figmaNode.cornerRadius;
+        if (cornerRadius != null && cornerRadius !== 0) {
+            const varName = this.getBoundVariableName(boundVars, 'cornerRadius');
+            propertiesToClassify.push({
+                property: 'border-radius',
+                figmaVarName: varName,
+                rawValue: cornerRadius,
+                category: 'radius',
+            });
+        }
+        // Fill colors
+        const fills = figmaNode.fills;
+        if (fills) {
+            for (const fill of fills) {
+                const color = fill.color;
+                if (!color)
+                    continue;
+                const r = Math.round((color.r ?? 0) * 255);
+                const g = Math.round((color.g ?? 0) * 255);
+                const b = Math.round((color.b ?? 0) * 255);
+                const a = (color.a ?? 1) * (fill.opacity ?? 1);
+                const rgba = `rgba(${r}, ${g}, ${b}, ${a})`;
+                const fillBv = fill.boundVariables;
+                const varName = this.getBoundVariableName(fillBv, 'color');
+                propertiesToClassify.push({
+                    property: 'fill',
+                    figmaVarName: varName,
+                    rawValue: rgba,
+                    category: 'color',
+                });
+            }
+        }
+        // Opacity
+        const opacity = figmaNode.opacity;
+        if (opacity != null && opacity !== 1) {
+            const varName = this.getBoundVariableName(boundVars, 'opacity');
+            propertiesToClassify.push({
+                property: 'opacity',
+                figmaVarName: varName,
+                rawValue: opacity,
+                category: 'opacity',
+            });
+        }
+        // Stroke weight
+        const strokeWeight = figmaNode.strokeWeight;
+        if (strokeWeight != null && strokeWeight > 0) {
+            const varName = this.getBoundVariableName(boundVars, 'strokeWeight');
+            propertiesToClassify.push({
+                property: 'border-width',
+                figmaVarName: varName,
+                rawValue: strokeWeight,
+                category: 'borderWidth',
+            });
+        }
+        // Stroke colors
+        const strokes = figmaNode.strokes;
+        if (strokes) {
+            for (const stroke of strokes) {
+                const c = stroke.color;
+                if (!c)
+                    continue;
+                const r = Math.round((c.r ?? 0) * 255);
+                const g = Math.round((c.g ?? 0) * 255);
+                const b = Math.round((c.b ?? 0) * 255);
+                const a = (c.a ?? 1) * (stroke.opacity ?? 1);
+                const strokeBv = stroke.boundVariables;
+                const varName = this.getBoundVariableName(strokeBv, 'color');
+                propertiesToClassify.push({
+                    property: 'stroke',
+                    figmaVarName: varName,
+                    rawValue: `rgba(${r}, ${g}, ${b}, ${a})`,
+                    category: 'color',
+                });
+            }
+        }
+        // Typography properties (TEXT nodes only)
+        if (nodeType === 'TEXT') {
+            const fontSize = figmaNode.fontSize;
+            if (fontSize != null) {
+                const varName = this.getBoundVariableName(boundVars, 'fontSize');
+                propertiesToClassify.push({
+                    property: 'font-size',
+                    figmaVarName: varName,
+                    rawValue: fontSize,
+                    category: 'fontSize',
+                });
+            }
+            const fontWeight = figmaNode.fontWeight;
+            if (fontWeight != null) {
+                const varName = this.getBoundVariableName(boundVars, 'fontWeight');
+                propertiesToClassify.push({
+                    property: 'font-weight',
+                    figmaVarName: varName,
+                    rawValue: fontWeight,
+                    category: 'fontWeight',
+                });
+            }
+            const lh = figmaNode.lineHeight;
+            if (lh?.value != null && lh.unit !== 'AUTO') {
+                const varName = this.getBoundVariableName(boundVars, 'lineHeight');
+                propertiesToClassify.push({
+                    property: 'line-height',
+                    figmaVarName: varName,
+                    rawValue: lh.value,
+                    category: 'lineHeight',
+                });
+            }
+            const ls = figmaNode.letterSpacing;
+            if (ls?.value != null && ls.value !== 0) {
+                const varName = this.getBoundVariableName(boundVars, 'letterSpacing');
+                propertiesToClassify.push({
+                    property: 'letter-spacing',
+                    figmaVarName: varName,
+                    rawValue: ls.value,
+                    category: 'letterSpacing',
+                });
+            }
+        }
+        // Classify each property
+        for (const { property, figmaVarName, rawValue, category } of propertiesToClassify) {
+            const result = this.translator.translate(figmaVarName, rawValue, category);
+            const tier = this.translator.classifyTokenMatch(result);
+            // Value-based matches → Unidentified with suggestion (only bindings earn Identified)
+            if (result.matchMethod === 'value' && tier !== 'unidentified') {
+                node.tokenClassifications.unidentified.push({
+                    property,
+                    rawValue: result.rawValue,
+                    reason: figmaVarName ? 'unresolved-binding' : 'value-match',
+                    suggestedToken: result.semantic ?? result.primitive ?? result.token,
+                    boundVariableId: figmaVarName,
+                });
+            }
+            else if (tier === 'semantic') {
+                node.tokenClassifications.semanticIdentified.push(this.translator.toClassifiedToken(result, property));
+            }
+            else if (tier === 'primitive') {
+                node.tokenClassifications.primitiveIdentified.push(this.translator.toClassifiedToken(result, property));
+            }
+            else {
+                node.tokenClassifications.unidentified.push(this.translator.toUnidentifiedValue(result, property));
+            }
+        }
+    }
+    /**
+     * Extract a Figma variable name from a node's boundVariables for a
+     * given property.
+     *
+     * Handles both single-binding objects and array-of-bindings.
+     */
+    getBoundVariableName(boundVars, property) {
+        if (!boundVars)
+            return undefined;
+        const binding = boundVars[property];
+        if (!binding || typeof binding !== 'object')
+            return undefined;
+        const bindingObj = binding;
+        const entry = Array.isArray(bindingObj) ? bindingObj[0] : bindingObj;
+        if (!entry || typeof entry !== 'object')
+            return undefined;
+        const entryObj = entry;
+        return entryObj.id;
+    }
+    /**
+     * Extract boundVariables from a node's boundVariables object into the map.
+     */
+    extractBoundVariables(boundVars, boundVariableMap) {
+        for (const [prop, binding] of Object.entries(boundVars)) {
+            if (!binding || typeof binding !== 'object')
+                continue;
+            const bindingObj = binding;
+            const bindingEntries = Array.isArray(bindingObj) ? bindingObj : [bindingObj];
+            for (const entry of bindingEntries) {
+                const entryObj = entry;
+                const varId = entryObj.id;
+                if (varId && !boundVariableMap.has(prop)) {
+                    boundVariableMap.set(prop, varId);
+                }
+            }
+        }
+    }
+    /**
+     * Recursively walk a node tree to collect all boundVariables.
+     *
+     * Collects from node-level boundVariables and fill-level boundVariables
+     * on all descendants up to maxDepth.
+     */
+    collectBoundVariablesRecursive(node, boundVariableMap, depth, maxDepth) {
+        if (depth > maxDepth)
+            return;
+        // Node-level boundVariables
+        const boundVars = node.boundVariables;
+        if (boundVars) {
+            this.extractBoundVariables(boundVars, boundVariableMap);
+        }
+        // Fill-level boundVariables (color bindings inside fills array)
+        const nodeFills = node.fills;
+        if (nodeFills) {
+            for (const fill of nodeFills) {
+                const fillBoundVars = fill.boundVariables;
+                if (fillBoundVars) {
+                    this.extractBoundVariables(fillBoundVars, boundVariableMap);
+                }
+            }
+        }
+        // Recurse into children
+        const children = node.children;
+        if (children) {
+            for (const child of children) {
+                this.collectBoundVariablesRecursive(child, boundVariableMap, depth + 1, maxDepth);
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Bound Variable Batch Resolution (Task 1.5)
+    // -----------------------------------------------------------------------
+    /**
+     * Walk a raw Figma node tree and collect all bound variable entries
+     * with full node context.
+     *
+     * Checks spacing properties, cornerRadius, and fill colors for
+     * boundVariables. Returns all entries (not deduplicated) — dedup
+     * happens in batchResolveBoundVariables.
+     *
+     * @param figmaNode - Raw Figma node object from API response
+     * @param depth - Current depth in the tree (root = 0)
+     * @param ancestors - Ancestor node types from root to parent
+     * @returns Array of BoundVariableEntry with full node context
+     * @requirements Req 4 (Bound Variable Batch Resolution)
+     */
+    collectBoundVariableIds(figmaNode, depth = 0, ancestors = []) {
+        const entries = [];
+        const nodeId = String(figmaNode.id ?? '');
+        const nodeName = String(figmaNode.name ?? '');
+        const nodeType = String(figmaNode.type ?? 'FRAME');
+        const boundVars = figmaNode.boundVariables;
+        // Spacing properties
+        const spacingProps = [
+            ['paddingTop', 'padding-top'],
+            ['paddingRight', 'padding-right'],
+            ['paddingBottom', 'padding-bottom'],
+            ['paddingLeft', 'padding-left'],
+            ['itemSpacing', 'item-spacing'],
+            ['counterAxisSpacing', 'counter-axis-spacing'],
+        ];
+        for (const [figmaProp, cssProp] of spacingProps) {
+            const value = figmaNode[figmaProp];
+            if (value == null)
+                continue;
+            const varId = this.getBoundVariableName(boundVars, figmaProp);
+            if (varId) {
+                entries.push({
+                    variableId: varId,
+                    property: cssProp,
+                    nodeId,
+                    nodeName,
+                    ancestorChain: ancestors,
+                    rawValue: value,
+                    category: 'spacing',
+                });
+            }
+        }
+        // Corner radius
+        const cornerRadius = figmaNode.cornerRadius;
+        if (cornerRadius != null) {
+            const varId = this.getBoundVariableName(boundVars, 'cornerRadius');
+            if (varId) {
+                entries.push({
+                    variableId: varId,
+                    property: 'border-radius',
+                    nodeId,
+                    nodeName,
+                    ancestorChain: ancestors,
+                    rawValue: cornerRadius,
+                    category: 'radius',
+                });
+            }
+        }
+        // Fill colors
+        const fills = figmaNode.fills;
+        if (fills) {
+            for (const fill of fills) {
+                const color = fill.color;
+                if (!color)
+                    continue;
+                const r = Math.round((color.r ?? 0) * 255);
+                const g = Math.round((color.g ?? 0) * 255);
+                const b = Math.round((color.b ?? 0) * 255);
+                const a = (color.a ?? 1) * (fill.opacity ?? 1);
+                const rgba = `rgba(${r}, ${g}, ${b}, ${a})`;
+                const fillBv = fill.boundVariables;
+                const varId = this.getBoundVariableName(fillBv, 'color');
+                if (varId) {
+                    entries.push({
+                        variableId: varId,
+                        property: 'fill',
+                        nodeId,
+                        nodeName,
+                        ancestorChain: ancestors,
+                        rawValue: rgba,
+                        category: 'color',
+                    });
+                }
+            }
+        }
+        // Opacity
+        const opacity = figmaNode.opacity;
+        if (opacity != null && opacity !== 1) {
+            const varId = this.getBoundVariableName(boundVars, 'opacity');
+            if (varId) {
+                entries.push({
+                    variableId: varId, property: 'opacity', nodeId, nodeName,
+                    ancestorChain: ancestors, rawValue: opacity, category: 'opacity',
+                });
+            }
+        }
+        // Stroke weight
+        const strokeWeight = figmaNode.strokeWeight;
+        if (strokeWeight != null && strokeWeight > 0) {
+            const varId = this.getBoundVariableName(boundVars, 'strokeWeight');
+            if (varId) {
+                entries.push({
+                    variableId: varId, property: 'border-width', nodeId, nodeName,
+                    ancestorChain: ancestors, rawValue: strokeWeight, category: 'borderWidth',
+                });
+            }
+        }
+        // Stroke colors
+        const strokes = figmaNode.strokes;
+        if (strokes) {
+            for (const stroke of strokes) {
+                const sc = stroke.color;
+                if (!sc)
+                    continue;
+                const sr = Math.round((sc.r ?? 0) * 255);
+                const sg = Math.round((sc.g ?? 0) * 255);
+                const sb = Math.round((sc.b ?? 0) * 255);
+                const sa = (sc.a ?? 1) * (stroke.opacity ?? 1);
+                const strokeBv = stroke.boundVariables;
+                const varId = this.getBoundVariableName(strokeBv, 'color');
+                if (varId) {
+                    entries.push({
+                        variableId: varId, property: 'stroke', nodeId, nodeName,
+                        ancestorChain: ancestors, rawValue: `rgba(${sr}, ${sg}, ${sb}, ${sa})`, category: 'color',
+                    });
+                }
+            }
+        }
+        // Typography bindings (TEXT nodes only)
+        if (nodeType === 'TEXT') {
+            const typoProps = [
+                ['fontSize', 'font-size', 'fontSize'],
+                ['fontWeight', 'font-weight', 'fontWeight'],
+                ['lineHeight', 'line-height', 'lineHeight'],
+                ['letterSpacing', 'letter-spacing', 'letterSpacing'],
+            ];
+            for (const [figmaProp, cssProp, cat] of typoProps) {
+                const varId = this.getBoundVariableName(boundVars, figmaProp);
+                if (varId) {
+                    const raw = figmaNode[figmaProp];
+                    const rawVal = typeof raw === 'object' && raw !== null
+                        ? raw.value ?? 0
+                        : raw ?? 0;
+                    entries.push({
+                        variableId: varId, property: cssProp, nodeId, nodeName,
+                        ancestorChain: ancestors, rawValue: rawVal, category: cat,
+                    });
+                }
+            }
+        }
+        // Recurse into children
+        const children = figmaNode.children;
+        if (children) {
+            const newAncestors = [...ancestors, nodeType];
+            for (const child of children) {
+                entries.push(...this.collectBoundVariableIds(child, depth + 1, newAncestors));
+            }
+        }
+        return entries;
+    }
+    /**
+     * Batch-resolve bound variable IDs via the Figma Plugin API.
+     *
+     * Deduplicates variable IDs, calls figma_execute to resolve names,
+     * and returns a map of resolved names plus an array of unresolved
+     * bindings with full node context.
+     *
+     * @param fileKey - The Figma file key
+     * @param entries - BoundVariableEntry[] collected from the node tree
+     * @returns Object with resolved map and unresolvedBindings array
+     * @requirements Req 4 (Bound Variable Batch Resolution)
+     */
+    async batchResolveBoundVariables(fileKey, entries) {
+        const resolved = new Map();
+        const unresolvedBindings = [];
+        if (entries.length === 0) {
+            return { resolved, unresolvedBindings };
+        }
+        // Deduplicate variable IDs
+        const uniqueIds = [...new Set(entries.map(e => e.variableId))];
+        // Build Plugin API code
+        const code = `
+      const results = {};
+      const collections = {};
+      for (const id of ${JSON.stringify(uniqueIds)}) {
+        try {
+          const v = await figma.variables.getVariableByIdAsync(id);
+          if (v) {
+            let collectionName = collections[v.variableCollectionId];
+            if (!collectionName) {
+              try {
+                const c = await figma.variables.getVariableCollectionByIdAsync(v.variableCollectionId);
+                collectionName = c ? c.name : '';
+              } catch(e) { collectionName = ''; }
+              collections[v.variableCollectionId] = collectionName;
+            }
+            results[id] = { name: v.name, collection: collectionName };
+          }
+        } catch (e) {
+          // Variable not found — skip
+        }
+      }
+      return results;
+      `.trim();
+        try {
+            const result = await this.consoleMcp.execute(fileKey, code);
+            // Parse the result — may be wrapped in { result: { ... } } or { result: "..." }
+            let resolvedData = {};
+            if (result && typeof result === 'object') {
+                const raw = result;
+                let inner = raw.result ?? raw;
+                if (typeof inner === 'string') {
+                    try {
+                        inner = JSON.parse(inner);
+                    }
+                    catch { /* not JSON */ }
+                }
+                if (inner && typeof inner === 'object') {
+                    resolvedData = inner;
+                }
+            }
+            // Populate resolved map
+            for (const [varId, info] of Object.entries(resolvedData)) {
+                if (info?.name) {
+                    resolved.set(varId, info.name);
+                }
+            }
+            // Build unresolvedBindings for IDs that failed
+            for (const entry of entries) {
+                if (!resolved.has(entry.variableId)) {
+                    unresolvedBindings.push({
+                        variableId: entry.variableId,
+                        property: entry.property,
+                        nodeId: entry.nodeId,
+                        nodeName: entry.nodeName,
+                        ancestorChain: entry.ancestorChain,
+                        reason: 'api-resolution-failed',
+                    });
+                }
+            }
+        }
+        catch {
+            // API call failed entirely — all entries are unresolved
+            for (const entry of entries) {
+                unresolvedBindings.push({
+                    variableId: entry.variableId,
+                    property: entry.property,
+                    nodeId: entry.nodeId,
+                    nodeName: entry.nodeName,
+                    ancestorChain: entry.ancestorChain,
+                    reason: 'api-resolution-failed',
+                });
+            }
+        }
+        return { resolved, unresolvedBindings };
+    }
+    /**
+     * Walk a NodeWithClassifications tree and reclassify unidentified values
+     * that have a boundVariableId using resolved variable names.
+     *
+     * For each unidentified value with a boundVariableId found in the
+     * resolvedMap, re-translates using the resolved name and moves
+     * successfully classified tokens from unidentified to semantic or
+     * primitive. Mutates the tree in place.
+     *
+     * @param nodeTree - Root of the classified node tree
+     * @param resolvedMap - Map of variableId → resolved variable name
+     * @requirements Req 4 (Bound Variable Batch Resolution)
+     */
+    reclassifyWithResolvedBindings(nodeTree, resolvedMap) {
+        const { unidentified } = nodeTree.tokenClassifications;
+        const remaining = [];
+        for (const entry of unidentified) {
+            if (entry.boundVariableId && resolvedMap.has(entry.boundVariableId)) {
+                const resolvedName = resolvedMap.get(entry.boundVariableId);
+                // Use translateByBinding directly — no enrichResponse promotion.
+                // The designer bound to THIS variable; honour the tier it lives at.
+                const bindingResult = this.translator.translateByBinding(resolvedName);
+                if (bindingResult.confidence === 'no-match') {
+                    // Binding resolved to a name but no matching token in DTCG —
+                    // likely a component-level variable that needs to be created.
+                    entry.reason = 'no-token-match';
+                    entry.suggestedToken = resolvedName;
+                    remaining.push(entry);
+                    continue;
+                }
+                // Determine tier from the token itself (alias = semantic, raw = primitive)
+                const tokenObj = this.translator.lookupToken(bindingResult.token);
+                const isAlias = tokenObj && typeof tokenObj.$value === 'string'
+                    && tokenObj.$value.startsWith('{') && tokenObj.$value.endsWith('}');
+                const classified = {
+                    property: entry.property,
+                    semanticToken: isAlias ? bindingResult.token : undefined,
+                    primitiveToken: isAlias
+                        ? tokenObj.$value.slice(1, -1)
+                        : bindingResult.token,
+                    rawValue: bindingResult.rawValue,
+                    matchMethod: 'binding',
+                    confidence: 'exact',
+                };
+                if (isAlias) {
+                    nodeTree.tokenClassifications.semanticIdentified.push(classified);
+                }
+                else {
+                    nodeTree.tokenClassifications.primitiveIdentified.push(classified);
+                }
+            }
+            else {
+                remaining.push(entry);
+            }
+        }
+        nodeTree.tokenClassifications.unidentified = remaining;
+        // Recurse into children
+        for (const child of nodeTree.children) {
+            this.reclassifyWithResolvedBindings(child, resolvedMap);
+        }
+    }
+    /**
+     * Collect fills from deep children that have boundVariables on their fills.
+     *
+     * These represent designer-intentional color assignments (variables bound
+     * to fill colors) that may differ from the parent component's fills.
+     * Returns deduplicated fills with their hex color values.
+     */
+    collectDeepFills(nodes) {
+        const result = [];
+        const seenColors = new Set();
+        const walk = (node, depth) => {
+            if (depth > 4)
+                return;
+            const nodeFills = node.fills;
+            if (nodeFills) {
+                for (const fill of nodeFills) {
+                    // Only collect fills that have boundVariables (designer intent)
+                    const fillBv = fill.boundVariables;
+                    if (!fillBv || Object.keys(fillBv).length === 0)
+                        continue;
+                    const color = fill.color;
+                    if (!color)
+                        continue;
+                    const r = Math.round((color.r ?? 0) * 255);
+                    const g = Math.round((color.g ?? 0) * 255);
+                    const b = Math.round((color.b ?? 0) * 255);
+                    const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+                    if (!seenColors.has(hex)) {
+                        seenColors.add(hex);
+                        result.push({
+                            type: String(fill.type ?? 'SOLID'),
+                            color: hex,
+                            opacity: fill.opacity,
+                        });
+                    }
+                }
+            }
+            const children = node.children;
+            if (children) {
+                for (const child of children) {
+                    walk(child, depth + 1);
+                }
+            }
+        };
+        for (const node of nodes) {
+            walk(node, 0);
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Design context parsing helpers
+    // -------------------------------------------------------------------------
+    /** Extract component name from generated code. */
+    extractComponentName(code) {
+        // Match class/component name patterns
+        const classMatch = code.match(/class\s+(\w+)/);
+        if (classMatch)
+            return classMatch[1];
+        const componentMatch = code.match(/(?:export\s+)?(?:default\s+)?(?:function|const)\s+(\w+)/);
+        if (componentMatch)
+            return componentMatch[1];
+        // Try HTML custom element tag
+        const tagMatch = code.match(/<([a-z][\w-]*)/);
+        if (tagMatch)
+            return tagMatch[1];
+        return '';
+    }
+    /** Extract description from code comments or JSDoc. */
+    extractDescription(code) {
+        const jsdocMatch = code.match(/\/\*\*\s*\n?\s*\*?\s*(.+?)(?:\n|\*\/)/);
+        if (jsdocMatch)
+            return jsdocMatch[1].trim();
+        const commentMatch = code.match(/\/\/\s*(.+)/);
+        if (commentMatch)
+            return commentMatch[1].trim();
+        return '';
+    }
+    /** Extract variant definitions from code. */
+    extractVariants(code) {
+        const variants = [];
+        // Match variant property patterns (e.g. variant="primary", size="large")
+        const variantPattern = /(?:variant|type|size|state)\s*[=:]\s*["'](\w+)["']/gi;
+        const seen = new Set();
+        let match;
+        while ((match = variantPattern.exec(code)) !== null) {
+            const propName = match[0].split(/[=:]/)[0].trim().toLowerCase();
+            const value = match[1];
+            const key = `${propName}=${value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                variants.push({ name: key, properties: { [propName]: value } });
+            }
+        }
+        return variants;
+    }
+    /** Extract visual states from code (hover, focus, disabled, pressed). */
+    extractStates(code) {
+        const stateKeywords = ['hover', 'focus', 'disabled', 'pressed', 'active', 'selected'];
+        const states = [];
+        const codeLower = code.toLowerCase();
+        for (const keyword of stateKeywords) {
+            if (codeLower.includes(keyword)) {
+                states.push({ name: keyword });
+            }
+        }
+        return states;
+    }
+    /** Extract component properties from code. */
+    extractProperties(code) {
+        const properties = [];
+        // Match TypeScript interface/type property patterns
+        const propPattern = /(\w+)\s*[?]?\s*:\s*(string|number|boolean|'[^']*'(?:\s*\|\s*'[^']*')*)/g;
+        const seen = new Set();
+        let match;
+        while ((match = propPattern.exec(code)) !== null) {
+            const name = match[1];
+            const type = match[2];
+            if (!seen.has(name)) {
+                seen.add(name);
+                properties.push({ name, type });
+            }
+        }
+        return properties;
+    }
+    /** Extract layout information from code. */
+    extractLayout(code) {
+        const codeLower = code.toLowerCase();
+        let mode = 'none';
+        if (codeLower.includes('flex-direction: row') || codeLower.includes('flexdirection: row') || codeLower.includes('display: flex')) {
+            mode = 'horizontal';
+        }
+        if (codeLower.includes('flex-direction: column') || codeLower.includes('flexdirection: column')) {
+            mode = 'vertical';
+        }
+        const layout = { mode };
+        // Extract gap/spacing
+        const gapMatch = code.match(/gap:\s*(\d+)/);
+        if (gapMatch) {
+            layout.itemSpacing = parseInt(gapMatch[1], 10);
+        }
+        // Extract padding
+        const paddingMatch = code.match(/padding:\s*(\d+)(?:px)?(?:\s+(\d+)(?:px)?)?(?:\s+(\d+)(?:px)?)?(?:\s+(\d+)(?:px)?)?/);
+        if (paddingMatch) {
+            const values = [paddingMatch[1], paddingMatch[2], paddingMatch[3], paddingMatch[4]]
+                .filter(Boolean)
+                .map(Number);
+            if (values.length === 1) {
+                layout.padding = { top: values[0], right: values[0], bottom: values[0], left: values[0] };
+            }
+            else if (values.length === 2) {
+                layout.padding = { top: values[0], right: values[1], bottom: values[0], left: values[1] };
+            }
+            else if (values.length === 4) {
+                layout.padding = { top: values[0], right: values[1], bottom: values[2], left: values[3] };
+            }
+        }
+        return layout;
+    }
+    /** Extract states from metadata XML. */
+    extractStatesFromMetadata(xml) {
+        const stateKeywords = ['hover', 'focus', 'disabled', 'pressed', 'active', 'selected'];
+        const states = [];
+        const xmlLower = xml.toLowerCase();
+        for (const keyword of stateKeywords) {
+            if (xmlLower.includes(keyword)) {
+                states.push({ name: keyword });
+            }
+        }
+        return states;
+    }
+    // -------------------------------------------------------------------------
+    // readTokenBindings (Task 3.3)
+    // -------------------------------------------------------------------------
+    /**
+     * Read all token bindings (Figma variables) from a file.
+     *
+     * Uses figma-console-mcp via `consoleMcp.getVariables()` which calls
+     * `figma_get_token_values`. Maps results to `TokenBinding[]` with alias
+     * detection based on `valuesByMode` containing `{ aliasOf: string }`.
+     *
+     * @param fileKey - The Figma file key.
+     * @returns Array of token bindings with alias relationships detected.
+     */
+    async readTokenBindings(fileKey) {
+        const variables = await this.consoleMcp.getVariables(fileKey);
+        if (!variables || variables.length === 0) {
+            return [];
+        }
+        // Build a lookup of variable names for alias target resolution
+        const nameById = new Map();
+        for (const v of variables) {
+            if (v.id) {
+                nameById.set(v.id, v.name);
+            }
+        }
+        return variables.map((v) => {
+            // Detect alias: valuesByMode values shaped { aliasOf: string }
+            const { isAlias, aliasTarget } = this.detectAlias(v.valuesByMode, nameById);
+            // collectionName is available at runtime from figma_get_token_values
+            // even though the FigmaVariable type doesn't declare it
+            const raw = v;
+            const collectionName = typeof raw.collectionName === 'string'
+                ? raw.collectionName
+                : this.inferCollectionFromName(v.name, isAlias);
+            return {
+                variableName: v.name,
+                variableId: v.id ?? '',
+                collectionName,
+                resolvedType: v.resolvedType,
+                valuesByMode: v.valuesByMode,
+                isAlias,
+                aliasTarget,
+            };
+        });
+    }
+    /**
+     * Detect whether a variable is an alias by inspecting its mode values.
+     *
+     * Figma aliases are represented as `{ aliasOf: string }` in valuesByMode.
+     * Returns the first alias target found (semantic tokens typically alias
+     * the same primitive across all modes).
+     */
+    detectAlias(valuesByMode, nameById) {
+        for (const modeValue of Object.values(valuesByMode)) {
+            if (modeValue &&
+                typeof modeValue === 'object' &&
+                'aliasOf' in modeValue) {
+                const aliasRef = modeValue.aliasOf;
+                // aliasOf may be a variable name or an ID — resolve via lookup
+                const resolved = nameById.get(aliasRef) ?? aliasRef;
+                return { isAlias: true, aliasTarget: resolved };
+            }
+        }
+        return { isAlias: false };
+    }
+    /**
+     * Infer collection name from variable name when not provided by MCP.
+     *
+     * Heuristic: variables with dot-separated semantic paths (e.g.
+     * "color.primary", "color.feedback.success.text") are Semantics;
+     * simple group/value names (e.g. "space/100", "color/purple/300")
+     * are Primitives.
+     */
+    inferCollectionFromName(name, isAlias) {
+        if (isAlias)
+            return 'Semantics';
+        // Semantic tokens use dot notation in their Figma names (pushed via 054a)
+        // e.g. "color.primary", "color.feedback.success.text"
+        if (name.includes('.'))
+            return 'Semantics';
+        // Primitive tokens use slash notation: "space/100", "color/purple/300"
+        return 'Primitives';
+    }
+    /**
+     * Read Figma styles (effect and text) from a file via figma-console-mcp.
+     *
+     * Calls `consoleMcp.getStyles(fileKey)` which invokes `figma_get_styles`,
+     * then maps results to `FigmaStyle[]`. Effect styles represent shadows/blurs;
+     * text styles represent typography.
+     *
+     * @param fileKey - The Figma file key.
+     * @returns Array of FigmaStyle objects separated by type.
+     * @requirements Req 3 (Composite Token Reconstruction)
+     */
+    async readStyles(fileKey) {
+        const rawStyles = await this.consoleMcp.getStyles(fileKey);
+        if (!rawStyles || rawStyles.length === 0) {
+            return [];
+        }
+        return rawStyles.map((s) => ({
+            name: s.name,
+            type: s.type,
+            properties: s.properties,
+        }));
+    }
+    // -------------------------------------------------------------------------
+    // queryContext (Task 3.5)
+    // -------------------------------------------------------------------------
+    /**
+     * Determine the component family from a component name and query
+     * DesignerPunk MCP for family pattern and existing component status.
+     *
+     * Family extraction uses PascalCase heuristics:
+     *   "ButtonCTA"       → "Button"
+     *   "InputTextBase"   → "Input"
+     *   "IconBase"        → "Icon"
+     *   "ContainerBase"   → "Container"
+     *
+     * Delegates to VariantAnalyzer's `queryFamilyPattern()` and
+     * `queryExistingComponents()` for the actual MCP queries.
+     *
+     * @param componentName - The Figma component name (e.g. "ButtonCTA").
+     * @returns ExtractionContext with family pattern and existing components.
+     * @requirements Req 1 (DesignExtractor), Req 4 (Context-Aware Variant Mapping)
+     */
+    async queryContext(componentName) {
+        const familyName = this.extractFamilyName(componentName);
+        const [familyPattern, existingComponents] = await Promise.all([
+            this.analyzer.queryFamilyPattern(familyName),
+            this.analyzer.queryExistingComponents(familyName),
+        ]);
+        return { familyPattern, existingComponents };
+    }
+    /**
+     * Extract the family name from a PascalCase component name.
+     *
+     * Splits on uppercase boundaries and returns the first segment.
+     * Handles common suffixes like "Base", "CTA", etc.
+     *
+     * Examples:
+     *   "ButtonCTA"       → "Button"
+     *   "InputTextBase"   → "Input"
+     *   "IconBase"        → "Icon"
+     *   "container-base"  → "Container" (kebab-case fallback)
+     *   "Button"          → "Button"
+     */
+    extractFamilyName(componentName) {
+        // Handle kebab-case (e.g. "button-cta", "input-text-base")
+        if (componentName.includes('-')) {
+            const first = componentName.split('-')[0];
+            return first.charAt(0).toUpperCase() + first.slice(1).toLowerCase();
+        }
+        // PascalCase: split on uppercase boundaries
+        const segments = componentName.replace(/([a-z])([A-Z])/g, '$1 $2').split(' ');
+        return segments[0];
+    }
+    // -------------------------------------------------------------------------
+    // translateTokens (Task 3.6)
+    // -------------------------------------------------------------------------
+    /**
+     * Translate all component properties to DesignerPunk token references.
+     *
+     * Builds a binding lookup map from the token bindings, then iterates
+     * over the component's layout, color, typography, radius, and shadow
+     * properties. For each property, checks if a variable binding exists
+     * and delegates to `translator.translate()` with binding-first strategy.
+     *
+     * Tracks no-match values for pause reporting in the extraction confidence.
+     *
+     * @param component - The extracted Figma component with layout and raw data.
+     * @param bindings - Token bindings read from figma-console-mcp.
+     * @returns Aggregated TokenUsage with all translated references.
+     * @requirements Req 2 (TokenTranslator Implementation)
+     */
+    translateTokens(component, bindings) {
+        // Build binding lookup: variableName → TokenBinding
+        const bindingMap = new Map();
+        for (const binding of bindings) {
+            bindingMap.set(binding.variableName, binding);
+        }
+        // Build variable ID → variable name lookup for resolving boundVariables
+        const nameById = new Map();
+        for (const binding of bindings) {
+            if (binding.variableId) {
+                nameById.set(binding.variableId, binding.variableName);
+            }
+        }
+        const usage = {
+            spacing: [],
+            colors: [],
+            typography: [],
+            radius: [],
+            shadows: [],
+        };
+        // --- Direct boundVariable translation (highest confidence path) ---
+        // When Console MCP provides boundVariables from component children,
+        // we can resolve variable IDs directly to token names without value scanning.
+        const bvMap = component.boundVariableMap;
+        // Track which layout properties were resolved via boundVariables so we
+        // can fall through to value-based matching for the rest.
+        const resolvedByBinding = new Set();
+        if (bvMap && bvMap.size > 0) {
+            // Mapping of Figma boundVariable property names to our categories
+            const spacingProps = {
+                paddingLeft: 'padding-left',
+                paddingRight: 'padding-right',
+                paddingTop: 'padding-top',
+                paddingBottom: 'padding-bottom',
+                itemSpacing: 'item-spacing',
+            };
+            const radiusProps = {
+                topLeftRadius: 'border-radius-top-left',
+                topRightRadius: 'border-radius-top-right',
+                bottomLeftRadius: 'border-radius-bottom-left',
+                bottomRightRadius: 'border-radius-bottom-right',
+                cornerRadius: 'border-radius',
+            };
+            const colorProps = {
+                color: 'fill',
+            };
+            for (const [figmaProp, varId] of bvMap) {
+                const varName = nameById.get(varId);
+                if (!varName)
+                    continue; // Variable ID not found in bindings
+                const cssProperty = spacingProps[figmaProp] ?? radiusProps[figmaProp] ?? colorProps[figmaProp];
+                if (!cssProperty)
+                    continue; // Unknown property — skip
+                let category;
+                if (spacingProps[figmaProp])
+                    category = 'spacing';
+                else if (radiusProps[figmaProp])
+                    category = 'radius';
+                else
+                    category = 'color';
+                const result = this.translator.translate(varName, 0, category);
+                const ref = {
+                    property: cssProperty,
+                    token: result.token,
+                    confidence: result.confidence,
+                    matchMethod: 'binding',
+                    primitive: result.primitive,
+                    semantic: result.semantic,
+                    delta: result.delta,
+                    rawValue: result.rawValue,
+                    suggestion: result.suggestion,
+                };
+                if (category === 'spacing') {
+                    usage.spacing.push(ref);
+                    resolvedByBinding.add(cssProperty);
+                }
+                else if (category === 'radius') {
+                    usage.radius.push(ref);
+                    resolvedByBinding.add(cssProperty);
+                }
+                else {
+                    usage.colors.push(ref);
+                }
+            }
+        }
+        // --- Layout-based spacing (fills gaps not covered by boundVariables) ---
+        // Always attempt layout-based translation for properties that weren't
+        // resolved via direct boundVariable binding above.
+        {
+            const layout = component.layout;
+            if (layout.itemSpacing != null && !resolvedByBinding.has('item-spacing')) {
+                const ref = this.translateProperty('item-spacing', layout.itemSpacing, 'spacing', bindingMap);
+                usage.spacing.push(ref);
+            }
+            if (layout.padding) {
+                const sides = [
+                    ['padding-top', layout.padding.top],
+                    ['padding-right', layout.padding.right],
+                    ['padding-bottom', layout.padding.bottom],
+                    ['padding-left', layout.padding.left],
+                ];
+                for (const [prop, value] of sides) {
+                    if (value != null && !resolvedByBinding.has(prop)) {
+                        usage.spacing.push(this.translateProperty(prop, value, 'spacing', bindingMap));
+                    }
+                }
+            }
+            // Corner radius from structured data (when not resolved via boundVariable)
+            if (component.cornerRadius != null && usage.radius.length === 0) {
+                usage.radius.push(this.translateProperty('border-radius', component.cornerRadius, 'radius', bindingMap));
+            }
+        }
+        // --- Fills from structured data (when no rawDesignContext) ---
+        if (component.fills && component.fills.length > 0 && !component.rawDesignContext) {
+            for (const fill of component.fills) {
+                if (fill.color) {
+                    usage.colors.push(this.translateProperty('fill', fill.color, 'color', bindingMap));
+                }
+            }
+        }
+        // --- Parse raw design context for colors, typography, radius, shadows ---
+        const raw = component.rawDesignContext ?? '';
+        // Colors: match CSS color properties
+        const colorPatterns = [
+            { pattern: /(?:background|background-color)\s*:\s*([^;}\n]+)/gi, prop: 'background' },
+            { pattern: /(?:^|[^-])color\s*:\s*([^;}\n]+)/gim, prop: 'color' },
+            { pattern: /border-color\s*:\s*([^;}\n]+)/gi, prop: 'border-color' },
+            { pattern: /fill\s*:\s*([^;}\n]+)/gi, prop: 'fill' },
+            { pattern: /stroke\s*:\s*([^;}\n]+)/gi, prop: 'stroke' },
+        ];
+        for (const { pattern, prop } of colorPatterns) {
+            let match;
+            while ((match = pattern.exec(raw)) !== null) {
+                const value = match[1].trim();
+                if (this.isColorValue(value)) {
+                    usage.colors.push(this.translateProperty(prop, value, 'color', bindingMap));
+                }
+            }
+        }
+        // Typography: font-size, font-family, font-weight, line-height
+        const typographyPatterns = [
+            { pattern: /font-size\s*:\s*([^;}\n]+)/gi, prop: 'font-size' },
+            { pattern: /font-weight\s*:\s*([^;}\n]+)/gi, prop: 'font-weight' },
+            { pattern: /line-height\s*:\s*([^;}\n]+)/gi, prop: 'line-height' },
+        ];
+        for (const { pattern, prop } of typographyPatterns) {
+            let match;
+            while ((match = pattern.exec(raw)) !== null) {
+                const value = match[1].trim();
+                usage.typography.push(this.translateProperty(prop, value, 'typography', bindingMap));
+            }
+        }
+        // Radius: border-radius
+        const radiusPattern = /border-radius\s*:\s*([^;}\n]+)/gi;
+        let radiusMatch;
+        while ((radiusMatch = radiusPattern.exec(raw)) !== null) {
+            const value = radiusMatch[1].trim();
+            usage.radius.push(this.translateProperty('border-radius', value, 'radius', bindingMap));
+        }
+        // Shadows: box-shadow
+        const shadowPattern = /box-shadow\s*:\s*([^;}\n]+)/gi;
+        let shadowMatch;
+        while ((shadowMatch = shadowPattern.exec(raw)) !== null) {
+            const value = shadowMatch[1].trim();
+            usage.shadows.push(this.translateProperty('box-shadow', value, 'shadow', bindingMap));
+        }
+        return usage;
+    }
+    /**
+     * Translate a single property value to a token reference.
+     *
+     * Checks the binding map for a variable whose resolved value matches
+     * the raw value, then delegates to `translator.translate()`.
+     */
+    translateProperty(property, rawValue, category, bindingMap) {
+        // Try to find a binding whose value matches this raw value
+        const bindingName = this.findBindingForValue(rawValue, category, bindingMap);
+        const result = this.translator.translate(bindingName, rawValue, category);
+        return {
+            property,
+            token: result.token,
+            confidence: result.confidence,
+            matchMethod: result.matchMethod,
+            primitive: result.primitive,
+            semantic: result.semantic,
+            delta: result.delta,
+            rawValue: result.rawValue,
+            suggestion: result.suggestion,
+        };
+    }
+    /**
+     * Find a binding variable name whose resolved value matches the given raw value.
+     *
+     * Searches the binding map for a variable of the matching type whose
+     * first mode value equals the raw value. Returns the variable name
+     * (for binding-first translation) or undefined if no binding found.
+     */
+    findBindingForValue(rawValue, category, bindingMap) {
+        const expectedType = category === 'color' ? 'COLOR' : 'FLOAT';
+        for (const [name, binding] of bindingMap) {
+            if (binding.resolvedType !== expectedType)
+                continue;
+            // Check first mode value
+            const modeValues = Object.values(binding.valuesByMode);
+            if (modeValues.length === 0)
+                continue;
+            const firstValue = modeValues[0];
+            // Skip alias objects — they don't carry resolved values
+            if (firstValue != null && typeof firstValue === 'object')
+                continue;
+            if (typeof rawValue === 'number' && firstValue === rawValue) {
+                return name;
+            }
+            if (String(rawValue) === String(firstValue)) {
+                return name;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if a CSS value looks like a color (hex, rgb, rgba, hsl, named).
+     */
+    /**
+       * Check if a CSS value looks like a color (hex, rgb, rgba, hsl, named).
+       */
+    isColorValue(value) {
+        const v = value.toLowerCase().trim();
+        // Exclude CSS keywords and non-color values
+        const nonColorKeywords = new Set([
+            'inherit', 'initial', 'unset', 'revert', 'none', 'transparent',
+            'currentcolor', 'auto', 'normal',
+        ]);
+        if (nonColorKeywords.has(v))
+            return false;
+        // Exclude url(), var() (non-color), calc(), etc.
+        if (v.startsWith('url(') || v.startsWith('calc('))
+            return false;
+        return (v.startsWith('#') ||
+            v.startsWith('rgb') ||
+            v.startsWith('hsl') ||
+            v.startsWith('var(--color'));
+    }
+    // -------------------------------------------------------------------------
+    // reconstructCompositeTokens (Task 3.7)
+    // -------------------------------------------------------------------------
+    /**
+     * Reconstruct composite token references from Figma styles.
+     *
+     * Primary path: match style names directly to DTCG composite tokens
+     * (names match because 054a pushed them with known names).
+     *
+     * Fallback path: if style name doesn't match, attempt property-by-property
+     * reconstruction by searching the DTCG token tree for tokens whose
+     * composite sub-values match the style's raw properties.
+     *
+     * Unmatched composites are flagged with ⚠️ confidence for Ada's review.
+     *
+     * @param styles - Figma styles read via figma-console-mcp.
+     * @param dtcgTokens - The loaded DTCG token file for lookup.
+     * @returns TokenReference[] with matched composite tokens.
+     * @requirements Req 3 (Composite Token Reconstruction)
+     */
+    reconstructCompositeTokens(styles, dtcgTokens) {
+        const results = [];
+        for (const style of styles) {
+            const category = style.type === 'EFFECT' ? 'shadow' : 'typography';
+            // Primary path: direct name match against DTCG token tree
+            const directMatch = this.lookupCompositeToken(style.name, category, dtcgTokens);
+            if (directMatch) {
+                results.push({
+                    property: category,
+                    token: directMatch.path,
+                    confidence: 'exact',
+                    matchMethod: 'binding',
+                    primitive: directMatch.path,
+                });
+                continue;
+            }
+            // Fallback path: property-by-property reconstruction
+            const reconstructed = this.reconstructFromProperties(style, category, dtcgTokens);
+            if (reconstructed) {
+                results.push(reconstructed);
+                continue;
+            }
+            // No match — flag for Ada's review
+            results.push({
+                property: category,
+                token: '',
+                confidence: 'no-match',
+                matchMethod: 'value',
+                delta: `Unmatched ${category} style "${style.name}" — requires Ada review`,
+            });
+        }
+        return results;
+    }
+    /**
+     * Look up a composite token by name in the DTCG token tree.
+     *
+     * Tries multiple name resolution strategies:
+     * 1. Direct path: `{category}.{styleName}` (e.g. `shadow.elevation200`)
+     * 2. Full style name as path (e.g. `shadow.elevation200` already dot-separated)
+     * 3. Style name with dots converted from slashes
+     *
+     * @returns The token path and token object if found, or null.
+     */
+    lookupCompositeToken(styleName, category, dtcgTokens) {
+        // Strategy 1: style name already includes category prefix (e.g. "shadow.elevation200")
+        if (styleName.startsWith(`${category}.`)) {
+            const token = this.resolveTokenPath(styleName, dtcgTokens);
+            if (token)
+                return { path: styleName, token };
+        }
+        // Strategy 2: prepend category (e.g. "elevation200" → "shadow.elevation200")
+        const prefixedPath = `${category}.${styleName}`;
+        const prefixedToken = this.resolveTokenPath(prefixedPath, dtcgTokens);
+        if (prefixedToken)
+            return { path: prefixedPath, token: prefixedToken };
+        // Strategy 3: convert slashes to dots and try both with and without prefix
+        const dotName = styleName.replace(/\//g, '.');
+        if (dotName !== styleName) {
+            if (dotName.startsWith(`${category}.`)) {
+                const token = this.resolveTokenPath(dotName, dtcgTokens);
+                if (token)
+                    return { path: dotName, token };
+            }
+            const prefixedDot = `${category}.${dotName}`;
+            const token = this.resolveTokenPath(prefixedDot, dtcgTokens);
+            if (token)
+                return { path: prefixedDot, token };
+        }
+        return null;
+    }
+    /**
+     * Resolve a dot-separated token path in the DTCG token tree.
+     *
+     * Walks the tree following each path segment and returns the node
+     * if it has a `$value` (i.e. is a token, not just a group).
+     */
+    resolveTokenPath(path, dtcgTokens) {
+        const parts = path.split('.');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let current = dtcgTokens;
+        for (const part of parts) {
+            if (current == null || typeof current !== 'object')
+                return null;
+            current = current[part];
+        }
+        if (current != null && typeof current === 'object' && '$value' in current) {
+            return current;
+        }
+        return null;
+    }
+    /**
+     * Attempt to reconstruct a composite token from raw style properties.
+     *
+     * For shadow styles: compares offsetX, offsetY, blur, spread, color
+     * against all shadow tokens in the DTCG tree.
+     *
+     * For typography styles: compares fontFamily, fontSize, fontWeight,
+     * lineHeight against all typography tokens in the DTCG tree.
+     *
+     * Returns an approximate-confidence match if a token's sub-values
+     * match the style properties, or null if no reconstruction possible.
+     */
+    reconstructFromProperties(style, category, dtcgTokens) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const group = dtcgTokens[category];
+        if (!group || typeof group !== 'object')
+            return null;
+        const props = style.properties;
+        let bestMatch = null;
+        for (const [key, entry] of Object.entries(group)) {
+            if (key.startsWith('$'))
+                continue;
+            if (entry == null || typeof entry !== 'object' || !('$value' in entry))
+                continue;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const tokenValue = entry.$value;
+            if (tokenValue == null || typeof tokenValue !== 'object')
+                continue;
+            const score = category === 'shadow'
+                ? this.scoreShadowMatch(props, tokenValue)
+                : this.scoreTypographyMatch(props, tokenValue);
+            if (score > 0 && (bestMatch === null || score > bestMatch.score)) {
+                bestMatch = { path: `${category}.${key}`, score };
+            }
+        }
+        if (bestMatch) {
+            return {
+                property: category,
+                token: bestMatch.path,
+                confidence: 'approximate',
+                matchMethod: 'value',
+                primitive: bestMatch.path,
+                delta: `Reconstructed from properties (score: ${bestMatch.score}/4)`,
+            };
+        }
+        return null;
+    }
+    /**
+     * Score how well a Figma effect style's properties match a DTCG shadow token value.
+     *
+     * Compares offsetX, offsetY, blur, and spread. Each matching property
+     * adds 1 to the score (max 4). Returns 0 if no properties match.
+     */
+    scoreShadowMatch(styleProps, tokenValue) {
+        let score = 0;
+        const fields = ['offsetX', 'offsetY', 'blur', 'spread'];
+        for (const field of fields) {
+            const styleProp = styleProps[field];
+            const tokenProp = tokenValue[field];
+            if (styleProp == null || tokenProp == null)
+                continue;
+            if (this.dimensionValuesMatch(styleProp, tokenProp))
+                score++;
+        }
+        return score;
+    }
+    /**
+     * Score how well a Figma text style's properties match a DTCG typography token value.
+     *
+     * Compares fontFamily, fontSize, fontWeight, and lineHeight. Each matching
+     * property adds 1 to the score (max 4). Returns 0 if no properties match.
+     */
+    scoreTypographyMatch(styleProps, tokenValue) {
+        let score = 0;
+        // fontFamily: string comparison
+        if (styleProps.fontFamily != null && tokenValue.fontFamily != null) {
+            if (String(styleProps.fontFamily) === String(tokenValue.fontFamily))
+                score++;
+        }
+        // fontSize: dimension comparison
+        if (styleProps.fontSize != null && tokenValue.fontSize != null) {
+            if (this.dimensionValuesMatch(styleProps.fontSize, tokenValue.fontSize))
+                score++;
+        }
+        // fontWeight: numeric comparison
+        if (styleProps.fontWeight != null && tokenValue.fontWeight != null) {
+            if (Number(styleProps.fontWeight) === Number(tokenValue.fontWeight))
+                score++;
+        }
+        // lineHeight: numeric comparison (may be unitless ratio or px)
+        if (styleProps.lineHeight != null && tokenValue.lineHeight != null) {
+            if (this.dimensionValuesMatch(styleProps.lineHeight, tokenValue.lineHeight))
+                score++;
+        }
+        return score;
+    }
+    /**
+     * Compare two dimension values that may be numbers or strings with units.
+     *
+     * Handles: `24` vs `"24px"`, `"16px"` vs `"16px"`, `1.5` vs `1.5`.
+     */
+    dimensionValuesMatch(a, b) {
+        // Both numeric
+        const numA = typeof a === 'number' ? a : parseFloat(String(a));
+        const numB = typeof b === 'number' ? b : parseFloat(String(b));
+        if (!isNaN(numA) && !isNaN(numB)) {
+            return numA === numB;
+        }
+        // String comparison as fallback
+        return String(a) === String(b);
+    }
+    /**
+     * Classify a component as interactive or static based on keyword heuristics.
+     *
+     * Checks the component name against known interactive and static keywords.
+     * If both match (unlikely but possible), interactive takes precedence because
+     * missing behavioral contracts on an interactive component is a higher risk
+     * than unnecessary contracts on a static one.
+     *
+     * @param componentName - The Figma component name.
+     * @returns 'interactive' or 'static'.
+     */
+    classifyComponent(componentName) {
+        const lower = componentName.toLowerCase();
+        const isInteractive = DesignExtractor.INTERACTIVE_KEYWORDS.some((kw) => lower.includes(kw));
+        if (isInteractive)
+            return 'interactive';
+        const isStatic = DesignExtractor.STATIC_KEYWORDS.some((kw) => lower.includes(kw));
+        if (isStatic)
+            return 'static';
+        // Default: treat unknown components as interactive (safer — forces review)
+        return 'interactive';
+    }
+    /**
+     * Extract visual state names from a component's detected states.
+     *
+     * Filters for well-known interaction states: hover, focus, disabled, pressed,
+     * active, selected, error, loading.
+     */
+    extractVisualStates(states) {
+        const knownStates = new Set([
+            'hover', 'focus', 'disabled', 'pressed',
+            'active', 'selected', 'error', 'loading',
+            'long-press',
+        ]);
+        return states
+            .map((s) => s.name.toLowerCase())
+            .filter((name) => knownStates.has(name));
+    }
+    /**
+     * Detect behavioral contract status for a component.
+     *
+     * Classifies the component as interactive or static using keyword heuristics,
+     * extracts visual states from the Figma component, and flags missing
+     * behavioral contracts for interactive components.
+     *
+     * For static components, auto-generates a "no interaction" contract.
+     *
+     * @param component - The extracted Figma component.
+     * @returns BehavioralContractStatus with classification, states, and confidence.
+     */
+    detectBehavioralContracts(component) {
+        const classification = this.classifyComponent(component.name);
+        const detectedStates = this.extractVisualStates(component.states);
+        if (classification === 'static') {
+            return {
+                classification: 'static',
+                detectedStates,
+                contractsDefined: true,
+                autoContract: 'No interaction — static display component',
+                confidence: '✅',
+            };
+        }
+        // Interactive component: flag missing behavioral contracts
+        // Behavioral contracts are considered missing because Figma designs
+        // don't encode interaction behavior — only visual states.
+        // The actual contracts must be defined during spec review.
+        const hasStates = detectedStates.length > 0;
+        return {
+            classification: 'interactive',
+            detectedStates,
+            contractsDefined: false,
+            confidence: '❌',
+        };
+    }
+    // -------------------------------------------------------------------------
+    // detectPlatformParity (Task 3.9)
+    // -------------------------------------------------------------------------
+    /**
+     * Detect platform-specific interactions and flag parity concerns.
+     *
+     * Applies heuristics to classify each detected visual state by platform
+     * support (hover = web-only, focus = all platforms, long-press = mobile).
+     * Optionally queries platform-implementation-guidelines.md via
+     * DesignerPunk MCP for cross-reference validation.
+     *
+     * Provides decision options for platform-specific interactions:
+     * omit on unsupported platform, map to alternative interaction, or
+     * defer to human review.
+     *
+     * @param component - The extracted Figma component.
+     * @returns PlatformParityCheck with interactions and concern status.
+     * @requirements Req 7 (Platform Parity Detection)
+     */
+    async detectPlatformParity(component) {
+        const detectedStates = this.extractVisualStates(component.states);
+        // Query platform guidelines for cross-reference (best-effort)
+        let guidelinesContent = null;
+        if (this.mcpDocs) {
+            try {
+                guidelinesContent = await this.mcpDocs.getSection('governance/platform-implementation-guidelines.md', 'State Management Consistency');
+            }
+            catch {
+                // MCP unavailable — proceed with heuristics only
+            }
+        }
+        const interactions = [];
+        for (const state of detectedStates) {
+            const platforms = DesignExtractor.PLATFORM_HEURISTICS[state];
+            if (!platforms)
+                continue;
+            const allPlatforms = ['web', 'ios', 'android'];
+            const missingPlatforms = allPlatforms.filter((p) => !platforms.includes(p));
+            // Only flag interactions that are NOT available on all platforms
+            if (missingPlatforms.length === 0)
+                continue;
+            const recommendation = this.buildPlatformRecommendation(state, platforms, missingPlatforms, guidelinesContent);
+            interactions.push({
+                interaction: state,
+                platforms,
+                recommendation,
+            });
+        }
+        return {
+            interactions,
+            hasConcerns: interactions.length > 0,
+        };
+    }
+    /**
+     * Build a recommendation string for a platform-specific interaction.
+     *
+     * Includes decision options for the human reviewer: omit on unsupported
+     * platforms, map to an alternative interaction, or provide a custom
+     * approach.
+     */
+    buildPlatformRecommendation(state, supportedPlatforms, missingPlatforms, guidelinesContent) {
+        const supported = supportedPlatforms.join(', ');
+        const missing = missingPlatforms.join(', ');
+        // State-specific recommendations
+        if (state === 'hover') {
+            return (`"${state}" is ${supported}-only (not available on ${missing}). ` +
+                'Decision options: (a) omit hover feedback on mobile, ' +
+                '(b) map to press/active state on mobile, ' +
+                '(c) provide alternative visual feedback.' +
+                (guidelinesContent ? ' Cross-referenced with platform-implementation-guidelines.md.' : ''));
+        }
+        if (state === 'long-press') {
+            return (`"${state}" is ${supported}-only (not available on ${missing}). ` +
+                'Decision options: (a) omit on web, ' +
+                '(b) map to right-click/context menu on web, ' +
+                '(c) provide alternative trigger.' +
+                (guidelinesContent ? ' Cross-referenced with platform-implementation-guidelines.md.' : ''));
+        }
+        // Generic recommendation for other platform-limited states
+        return (`"${state}" is available on ${supported} but not on ${missing}. ` +
+            `Decision options: (a) omit on ${missing}, ` +
+            '(b) map to equivalent interaction, ' +
+            '(c) defer to human review.' +
+            (guidelinesContent ? ' Cross-referenced with platform-implementation-guidelines.md.' : ''));
+    }
+    // -------------------------------------------------------------------------
+    // detectComponentTokenDecisions (Task 3.10)
+    // -------------------------------------------------------------------------
+    /**
+     * Detect repeated primitive token usage and surface component token
+     * decision points for Ada's review.
+     *
+     * Scans all token categories in the usage map, groups references by
+     * their resolved primitive token, and generates illustrative component
+     * token suggestions for any primitive used two or more times.
+     *
+     * All suggestions are explicitly labeled as pending human review —
+     * no autonomous token creation per governance.
+     *
+     * @param tokenUsage - Aggregated token usage from translateTokens().
+     * @param componentName - Component name for illustrative naming.
+     * @returns Array of decision points for Ada's review.
+     */
+    detectComponentTokenDecisions(tokenUsage, componentName = 'component') {
+        // Build a map of primitiveToken → list of property locations
+        const usageMap = new Map();
+        const categories = [
+            ['spacing', 'spacing'],
+            ['colors', 'color'],
+            ['typography', 'typography'],
+            ['radius', 'radius'],
+            ['shadows', 'shadow'],
+        ];
+        for (const [category] of categories) {
+            const refs = tokenUsage[category];
+            for (const ref of refs) {
+                // Only consider matched tokens (not no-match)
+                if (ref.confidence === 'no-match')
+                    continue;
+                // Use the primitive token if available, otherwise the main token
+                const primitiveKey = ref.primitive ?? ref.token;
+                if (!primitiveKey)
+                    continue;
+                const location = ref.property;
+                const existing = usageMap.get(primitiveKey) ?? [];
+                existing.push(location);
+                usageMap.set(primitiveKey, existing);
+            }
+        }
+        // Generate decisions for tokens used 2+ times
+        const decisions = [];
+        const baseName = this.extractComponentBaseName(componentName);
+        for (const [primitiveToken, locations] of usageMap) {
+            if (locations.length < 2)
+                continue;
+            const propertyGroup = this.inferPropertyGroup(locations);
+            const suggestion = `${baseName}.${propertyGroup} = ${primitiveToken}`;
+            decisions.push({
+                primitiveToken,
+                usageCount: locations.length,
+                locations,
+                illustrativeSuggestion: suggestion,
+                rationale: `${primitiveToken} is used across ${locations.length} properties ` +
+                    `(${locations.join(', ')}). Consistent usage suggests semantic ` +
+                    `intent that could be encoded as a component token.`,
+            });
+        }
+        // Sort by usage count descending for prioritized review
+        decisions.sort((a, b) => b.usageCount - a.usageCount);
+        return decisions;
+    }
+    /**
+     * Extract a short base name from a component name for illustrative
+     * token naming.
+     *
+     * "ButtonCTA" → "button", "InputTextBase" → "input", "ContainerBase" → "container"
+     */
+    extractComponentBaseName(componentName) {
+        // Split PascalCase into words, take the first word, lowercase it
+        const words = componentName.replace(/([a-z])([A-Z])/g, '$1 $2').split(/[\s_-]+/);
+        return (words[0] ?? 'component').toLowerCase();
+    }
+    /**
+     * Infer a property group name from a list of CSS property locations.
+     *
+     * Groups related properties into semantic names:
+     * - padding-left, padding-right → "padding.horizontal"
+     * - padding-top, padding-bottom → "padding.vertical"
+     * - mixed padding → "padding"
+     * - color, fill, background → "fill"
+     * - border-radius → "radius"
+     * - Otherwise uses the first property name.
+     */
+    inferPropertyGroup(locations) {
+        const normalized = locations.map(l => l.toLowerCase());
+        // Check for padding patterns
+        const hasPaddingLeft = normalized.some(l => l.includes('padding-left') || l.includes('padding-inline-start'));
+        const hasPaddingRight = normalized.some(l => l.includes('padding-right') || l.includes('padding-inline-end'));
+        const hasPaddingTop = normalized.some(l => l.includes('padding-top') || l.includes('padding-block-start'));
+        const hasPaddingBottom = normalized.some(l => l.includes('padding-bottom') || l.includes('padding-block-end'));
+        const allPadding = normalized.every(l => l.includes('padding'));
+        if (allPadding) {
+            if ((hasPaddingLeft || hasPaddingRight) && !hasPaddingTop && !hasPaddingBottom) {
+                return 'padding.horizontal';
+            }
+            if ((hasPaddingTop || hasPaddingBottom) && !hasPaddingLeft && !hasPaddingRight) {
+                return 'padding.vertical';
+            }
+            return 'padding';
+        }
+        // Check for spacing patterns (item-spacing, gap, margin)
+        if (normalized.every(l => l.includes('spacing') || l.includes('gap') || l.includes('margin'))) {
+            return 'spacing';
+        }
+        // Check for color patterns
+        if (normalized.every(l => l.includes('color') || l.includes('fill') || l.includes('background') || l.includes('stroke'))) {
+            return 'fill';
+        }
+        // Check for radius
+        if (normalized.every(l => l.includes('radius'))) {
+            return 'radius';
+        }
+        // Check for shadow
+        if (normalized.every(l => l.includes('shadow'))) {
+            return 'shadow';
+        }
+        // Check for typography
+        if (normalized.every(l => l.includes('font') || l.includes('line-height') || l.includes('letter-spacing'))) {
+            return 'typography';
+        }
+        // Fallback: use the first property, cleaned up
+        return normalized[0]?.replace(/[^a-z0-9.]/g, '-') ?? 'token';
+    }
+    /**
+     * Validate mode consistency across token bindings.
+     *
+     * For each binding with multiple mode values, checks whether light and
+     * dark mode values are identical. Discrepancies are categorized:
+     *
+     * - **expected**: Color tokens differ by mode (light/dark theme variations).
+     * - **unexpected**: Spacing, radius, or typography tokens differ by mode
+     *   (structural tokens should be mode-agnostic).
+     *
+     * @param bindings - Token bindings read from Figma.
+     * @returns ModeValidationResult with discrepancies and a flag for unexpected ones.
+     * @requirements Req 9 (Mode Consistency Validation)
+     */
+    validateModes(bindings) {
+        const discrepancies = [];
+        for (const binding of bindings) {
+            const modeEntries = Object.entries(binding.valuesByMode);
+            // Need at least two modes to compare
+            if (modeEntries.length < 2)
+                continue;
+            // Identify light and dark mode entries by key name heuristic
+            const lightKey = modeEntries.find(([k]) => /light/i.test(k));
+            const darkKey = modeEntries.find(([k]) => /dark/i.test(k));
+            // If we can't identify light/dark by name, compare first two modes
+            const [modeA, modeB] = lightKey && darkKey
+                ? [lightKey, darkKey]
+                : [modeEntries[0], modeEntries[1]];
+            const valueA = modeA[1];
+            const valueB = modeB[1];
+            // Skip alias objects — they reference other variables, not resolved values
+            if (this.isAliasValue(valueA) || this.isAliasValue(valueB))
+                continue;
+            // Compare values — use JSON.stringify for deep equality of objects
+            if (this.modeValuesEqual(valueA, valueB))
+                continue;
+            // Values differ — categorize the discrepancy
+            const category = binding.resolvedType === 'COLOR' ? 'expected' : 'unexpected';
+            discrepancies.push({
+                variableName: binding.variableName,
+                lightValue: valueA,
+                darkValue: valueB,
+                category,
+            });
+        }
+        return {
+            discrepancies,
+            hasUnexpectedDiscrepancies: discrepancies.some(d => d.category === 'unexpected'),
+        };
+    }
+    /**
+     * Resolve variable IDs from boundVariableMap that aren't in the bindings.
+     *
+     * When `figma_get_token_values` (limit: 500) doesn't return all variables,
+     * some boundVariable IDs from the component tree won't resolve in the
+     * `nameById` lookup during `translateTokens`. This method uses
+     * `figma_execute` with Plugin API to batch-resolve those missing IDs,
+     * returning synthetic TokenBinding entries that can be appended to the
+     * bindings array.
+     *
+     * @param fileKey - The Figma file key.
+     * @param boundVariableMap - Property→variableId map from component extraction.
+     * @param existingBindings - Bindings already loaded from figma_get_token_values.
+     * @returns Additional TokenBinding entries for previously unresolved IDs.
+     */
+    async resolveUnknownVariableIds(fileKey, boundVariableMap, existingBindings) {
+        if (!boundVariableMap || boundVariableMap.size === 0)
+            return [];
+        // Build set of known variable IDs
+        const knownIds = new Set();
+        for (const binding of existingBindings) {
+            if (binding.variableId)
+                knownIds.add(binding.variableId);
+        }
+        // Collect unresolved IDs (deduplicated)
+        const unresolvedIds = new Set();
+        for (const varId of boundVariableMap.values()) {
+            if (!knownIds.has(varId))
+                unresolvedIds.add(varId);
+        }
+        if (unresolvedIds.size === 0)
+            return [];
+        // Batch-resolve via Plugin API
+        const idsArray = [...unresolvedIds];
+        const code = `
+      const results = {};
+      for (const id of ${JSON.stringify(idsArray)}) {
+        try {
+          const v = figma.variables.getVariableById(id);
+          if (v) {
+            results[id] = {
+              name: v.name,
+              resolvedType: v.resolvedType,
+              id: v.id,
+            };
+          }
+        } catch (e) {
+          // Variable not found — skip
+        }
+      }
+      return results;
+    `.trim();
+        try {
+            const result = await this.consoleMcp.execute(fileKey, code);
+            // Parse the result — may be wrapped in various formats
+            let resolved = {};
+            if (result && typeof result === 'object') {
+                // Handle { result: { ... } } wrapper from figma_execute
+                const raw = result;
+                const inner = raw.result ?? raw;
+                if (inner && typeof inner === 'object') {
+                    resolved = inner;
+                }
+            }
+            const additionalBindings = [];
+            for (const [varId, info] of Object.entries(resolved)) {
+                if (!info?.name)
+                    continue;
+                additionalBindings.push({
+                    variableName: info.name,
+                    variableId: varId,
+                    collectionName: this.inferCollectionFromName(info.name, false),
+                    resolvedType: (info.resolvedType ?? 'FLOAT'),
+                    valuesByMode: {},
+                    isAlias: false,
+                });
+            }
+            return additionalBindings;
+        }
+        catch {
+            // Plugin API resolution failed — return empty (value-based fallback still works)
+            return [];
+        }
+    }
+    /**
+     * Check whether a mode value is an alias reference (not a resolved value).
+     */
+    isAliasValue(value) {
+        return (value != null &&
+            typeof value === 'object' &&
+            'aliasOf' in value);
+    }
+    /**
+     * Compare two mode values for equality.
+     *
+     * Handles primitives (number, string) directly and falls back to
+     * JSON.stringify for object values (e.g. color objects).
+     */
+    modeValuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (typeof a !== typeof b)
+            return false;
+        if (typeof a === 'object' && a !== null && b !== null) {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        return false;
+    }
+    /**
+     * Extract a Figma component and produce a ComponentAnalysis.
+     *
+     * Orchestrates: read component → build node tree → collect/resolve
+     * bound variables → reclassify → detect composition patterns →
+     * capture screenshot → gather recommendations.
+     */
+    async extractComponentAnalysis(fileKey, nodeId, outputDir, fileUrl) {
+        // 1. Read component structure, token bindings, and styles in parallel
+        const [component, bindings, styles] = await Promise.all([
+            this.readFigmaComponent(fileKey, nodeId),
+            this.readTokenBindings(fileKey),
+            this.readStyles(fileKey),
+        ]);
+        // 2. Resolve unknown variable IDs
+        if (component.boundVariableMap && component.boundVariableMap.size > 0) {
+            const additional = await this.resolveUnknownVariableIds(fileKey, component.boundVariableMap, bindings);
+            if (additional.length > 0)
+                bindings.push(...additional);
+        }
+        // 3. Get raw component data for node tree building
+        const rawComponent = await this.consoleMcp.getComponent(fileKey, nodeId);
+        // 4. Build hierarchical node tree with per-node classification
+        const nodeTree = this.buildNodeTree(rawComponent);
+        // 5. Collect and resolve bound variable IDs
+        const boundEntries = this.collectBoundVariableIds(rawComponent);
+        const { resolved, unresolvedBindings } = await this.batchResolveBoundVariables(fileKey, boundEntries);
+        // 6. Reclassify unidentified values using resolved bindings
+        this.reclassifyWithResolvedBindings(nodeTree, resolved);
+        // 7. Aggregate classification counts
+        const classificationSummary = this.aggregateClassifications(nodeTree);
+        // 8. Detect composition patterns
+        const compositionPatterns = this.detectCompositionPatterns(nodeTree);
+        // 9. Capture screenshots (variants for COMPONENT_SET, single for others)
+        const screenshots = [];
+        const screenshotUrl = fileUrl ?? `https://www.figma.com/design/${fileKey}`;
+        if (nodeTree.type === 'COMPONENT_SET' && nodeTree.children.length > 0) {
+            for (const child of nodeTree.children) {
+                const shot = await this.captureComponentScreenshot(screenshotUrl, child.id, outputDir, component.name, child.name);
+                if (shot)
+                    screenshots.push(shot);
+            }
+        }
+        else {
+            const shot = await this.captureComponentScreenshot(screenshotUrl, nodeId, outputDir, component.name);
+            if (shot)
+                screenshots.push(shot);
+        }
+        // 10. Gather recommendations (reuse existing methods)
+        const tokenUsage = this.translateTokens(component, bindings);
+        const compositeTokens = this.reconstructCompositeTokens(styles, this.translator.getDtcgTokens());
+        for (const ref of compositeTokens) {
+            if (ref.property === 'shadow')
+                tokenUsage.shadows.push(ref);
+            else if (ref.property === 'typography')
+                tokenUsage.typography.push(ref);
+        }
+        const context = await this.queryContext(component.name);
+        const analyzerComponent = {
+            name: component.name,
+            description: component.description,
+            variants: component.variants.map(v => ({ name: v.name, properties: v.properties })),
+            states: component.states.map(s => s.name),
+        };
+        const variantMapping = await this.analyzer.analyzeVariants(analyzerComponent, context);
+        const componentTokens = this.detectComponentTokenDecisions(tokenUsage, component.name);
+        const modeValidation = this.validateModes(bindings);
+        const platformParity = await this.detectPlatformParity(component);
+        // 11. Build variant definitions from raw response
+        const variantDefinitions = this.buildVariantDefinitions(rawComponent);
+        // 12. Determine component type
+        const componentType = this.resolveComponentType(rawComponent);
+        return {
+            componentName: component.name,
+            componentType,
+            figmaId: nodeId,
+            fileKey,
+            variantDefinitions: Object.keys(variantDefinitions).length > 0 ? variantDefinitions : undefined,
+            nodeTree,
+            classificationSummary,
+            compositionPatterns,
+            unresolvedBindings,
+            recommendations: {
+                variantMapping: variantMapping.recommendations.length > 0 || variantMapping.conflicts.length > 0 ? variantMapping : undefined,
+                componentTokens: componentTokens.length > 0 ? componentTokens : undefined,
+                modeValidation: modeValidation.hasUnexpectedDiscrepancies ? modeValidation : undefined,
+                platformParity: platformParity.hasConcerns ? platformParity : undefined,
+            },
+            screenshots,
+            extractedAt: new Date().toISOString(),
+            extractorVersion: '6.3.0',
+        };
+    }
+    /** Aggregate classification counts across all nodes in a tree. */
+    aggregateClassifications(node) {
+        let semantic = node.tokenClassifications.semanticIdentified.length;
+        let primitive = node.tokenClassifications.primitiveIdentified.length;
+        let unidentified = node.tokenClassifications.unidentified.length;
+        for (const child of node.children) {
+            const c = this.aggregateClassifications(child);
+            semantic += c.semanticIdentified;
+            primitive += c.primitiveIdentified;
+            unidentified += c.unidentified;
+        }
+        return { semanticIdentified: semantic, primitiveIdentified: primitive, unidentified };
+    }
+    /** Build variantDefinitions from raw Figma component response. */
+    buildVariantDefinitions(raw) {
+        const defs = {};
+        const vp = raw.variantProperties;
+        if (vp) {
+            for (const [name, options] of Object.entries(vp)) {
+                defs[name] = { type: 'VARIANT', defaultValue: options[0] ?? '', variantOptions: options };
+            }
+        }
+        return defs;
+    }
+    /** Resolve component type from raw Figma response. */
+    resolveComponentType(raw) {
+        const t = raw.type;
+        if (t === 'COMPONENT_SET' || t === 'COMPONENT' || t === 'INSTANCE')
+            return t;
+        // If it has variantProperties, it's a COMPONENT_SET
+        if (raw.variantProperties)
+            return 'COMPONENT_SET';
+        return 'COMPONENT';
+    }
+}
+exports.DesignExtractor = DesignExtractor;
+/** Platform-interaction heuristics: interaction → supported platforms. */
+DesignExtractor.PLATFORM_HEURISTICS = {
+    hover: ['web'],
+    focus: ['web', 'ios', 'android'],
+    pressed: ['web', 'ios', 'android'],
+    disabled: ['web', 'ios', 'android'],
+    active: ['web', 'ios', 'android'],
+    selected: ['web', 'ios', 'android'],
+    'long-press': ['ios', 'android'],
+    loading: ['web', 'ios', 'android'],
+    error: ['web', 'ios', 'android'],
+};
+// ---------------------------------------------------------------------------
+// Behavioral contract detection (Task 3.8)
+// ---------------------------------------------------------------------------
+/**
+ * Keywords that indicate an interactive component requiring behavioral contracts.
+ * Matched case-insensitively against the component name.
+ */
+DesignExtractor.INTERACTIVE_KEYWORDS = [
+    'button', 'input', 'toggle', 'switch', 'checkbox', 'radio',
+    'select', 'dropdown', 'slider', 'tab', 'link', 'menu',
+    'dialog', 'modal', 'tooltip', 'popover', 'accordion',
+];
+/**
+ * Keywords that indicate a static (non-interactive) component.
+ * Matched case-insensitively against the component name.
+ */
+DesignExtractor.STATIC_KEYWORDS = [
+    'badge', 'divider', 'icon', 'avatar', 'label', 'tag',
+    'separator', 'spacer', 'image', 'logo', 'progress',
+];
+//# sourceMappingURL=DesignExtractor.js.map