@calibrate-ds/core 0.1.0

package/dist/normalizer/instance-resolver.js

@@ -0,0 +1,747 @@
+import { rgbToHex } from "./helpers.js";
+import { resolveTokenBindingFromIndex } from "../tokens/resolution.js";
+/** Converts any Figma display name to a valid PascalCase React component identifier.
+ *  "nav-arrow-down" → "NavArrowDown", "homeFilled" → "HomeFilled", "Text field mobile" → "TextFieldMobile"
+ */
+function toPascalCase(name) {
+    return name
+        .split(/[\s\-_]+/)
+        .filter(Boolean)
+        .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+}
+/** Figma variant axis names that exist only in the design tool and have no React equivalent.
+ *  `weight` controls icon stroke thickness in Figma but React SVG icons are static.
+ *  `theme` / `platform` / `appearance` are Figma presentation-layer concerns only.
+ */
+const FIGMA_ONLY_PROP_NAMES = new Set(["weight", "theme", "platform", "appearance"]);
+/** Figma interaction-state values for the `state` axis that represent hover/focus/press
+ *  states handled in CSS/event handlers — never passed as static React props.
+ */
+const FIGMA_INTERACTION_STATE_VALUES = new Set([
+    "default", "hover", "hovered", "pressed", "focused", "active", "visited",
+]);
+/**
+ * Deterministically resolves a usage "recipe" for a nested dependency instance.
+ * This helps downstream AI implementation avoid guessing about slot visibility
+ * and intended visual configuration.
+ */
+export function resolveInstanceRecipe(node, components = [], tokenIndex) {
+    if (!node.componentId)
+        return undefined;
+    try {
+        return doResolveInstanceRecipe(node, components, tokenIndex);
+    }
+    catch (e) {
+        console.warn(`Failed to enrich recipe for node ${node.name || "unknown"}: ${e.message}`);
+        const componentName = (node?.name || "").split('/')[0].trim();
+        return {
+            standardType: "generic",
+            visibleSlots: [],
+            hiddenSlots: [],
+            textVisible: true,
+            leadingIconVisible: false,
+            trailingIconVisible: false,
+            summary: "Generic fallback component",
+            resolvedProps: {},
+            implementationMode: "invoke-dependency",
+            classification: {
+                representable: [],
+                derivedButRepresentable: [],
+                nonRepresentable: [],
+                warnings: [`Enrichment crashed: ${e.message}`]
+            },
+            invocationHint: `<${toPascalCase(componentName || "Unknown")} />`,
+            invocationContract: {
+                componentName: toPascalCase(componentName || "Unknown"),
+                importName: toPascalCase(componentName || "Unknown"),
+                resolvedProps: {},
+                propSourceMap: {},
+                omitProps: [],
+                slotContract: {},
+                childrenPolicy: "generic",
+                iconBindingPolicy: {},
+                renderHint: ""
+            }
+        };
+    }
+}
+function doResolveInstanceRecipe(node, components = [], tokenIndex) {
+    // Only resolve recipes for instances (which have componentId)
+    if (!node.componentId)
+        return undefined;
+    // Resolves a Figma node ID (raw "136:594" or PTB "comp_136_594") to a ComponentDefinition.
+    // Layout tree nodes already store PTB IDs, but propertyOverrides (INSTANCE_SWAP values) keep raw Figma IDs.
+    const findComp = (id, name) => {
+        // Phase 1a: exact PTB ID match
+        let comp = components.find(c => c.id === id);
+        // Phase 1b: designToolNodeId match (catches raw variant IDs stored on the model)
+        if (!comp)
+            comp = components.find(c => c.designToolNodeId === id);
+        // Phase 1c: raw Figma ID → PTB format conversion ("106:390" → "comp_106_390")
+        if (!comp && /^\d+:\d+$/.test(id)) {
+            comp = components.find(c => c.id === `comp_${id.replace(/:/g, "_")}`);
+        }
+        // Phase 2: name-based fallback — when IDs diverge (variant ID vs set ID)
+        if (!comp && name) {
+            const baseName = name.split("/")[0].trim();
+            const baseLower = baseName.toLowerCase().replace(/\s+/g, "");
+            comp = components.find(c => c.name === baseName ||
+                c.name.toLowerCase().replace(/\s+/g, "") === baseLower);
+        }
+        return comp;
+    };
+    const dependency = findComp(node.componentId, node.name);
+    const visibleSlots = [];
+    const hiddenSlots = [];
+    const childNodes = [];
+    const traverse = (n) => {
+        childNodes.push(n);
+        if (n.children)
+            n.children.forEach(traverse);
+    };
+    if (node.children)
+        node.children.forEach(traverse);
+    // 1. Text / Label Analysis
+    let textContent = node.textContent;
+    let textVisible = node.visible !== false;
+    // 2. Props Aggregation
+    const resolvedProps = {};
+    const propSourceMap = {};
+    // Helper to clean property names for implementation-like usage
+    const cleanPropName = (name) => {
+        return name.trim()
+            .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+            .replace(/^./, (str) => str.toLowerCase());
+    };
+    if (node.variantSelection && typeof node.variantSelection === 'object') {
+        for (const [key, value] of Object.entries(node.variantSelection)) {
+            const cleanKey = cleanPropName(key);
+            resolvedProps[cleanKey] = value;
+            propSourceMap[key] = cleanKey;
+        }
+    }
+    if (node.propertyOverrides && typeof node.propertyOverrides === 'object') {
+        for (const [key, value] of Object.entries(node.propertyOverrides)) {
+            const cleanKey = cleanPropName(key);
+            resolvedProps[cleanKey] = value;
+            propSourceMap[key] = cleanKey;
+            const k = key.toLowerCase();
+            // Common Figma property names for text
+            if (k === "label" || k === "text" || k === "value" || k === "title") {
+                if (typeof value === "string") {
+                    textContent = value;
+                }
+                // Booleans often control visibility of text slots
+                if (value === false || value === "") {
+                    textVisible = false;
+                }
+                if (value === true)
+                    textVisible = true;
+            }
+        }
+    }
+    // Resolve instance IDs into dependency contracts
+    for (const [key, value] of Object.entries(resolvedProps)) {
+        if (typeof value === "string" && /^(\d+:\d+|I\d+:\d+.*)$/.test(value)) {
+            const dep = findComp(value);
+            if (dep) {
+                resolvedProps[key] = {
+                    kind: "dependency",
+                    componentId: dep.id,
+                    componentName: dep.name,
+                    importName: dep.name
+                };
+            }
+            else {
+                resolvedProps[key] = {
+                    kind: "unknown",
+                    componentId: value
+                };
+            }
+        }
+    }
+    // 3. Icon Analysis (Heuristics based on common Figma naming and variant patterns)
+    let leadingIconVisible = false;
+    let trailingIconVisible = false;
+    // Check variant selection (e.g. "Icon=Both", "Leading Icon=On")
+    if (node.variantSelection) {
+        for (const [key, value] of Object.entries(node.variantSelection)) {
+            const k = key.toLowerCase();
+            const v = String(value).toLowerCase();
+            const isPositive = v === "true" || v === "on" || v === "visible" || v === "yes" || (v !== "none" && v !== "false" && v !== "off");
+            if (k.includes("icon")) {
+                if (isPositive) {
+                    if (k.includes("leading") || k.includes("start") || k.includes("left") || k.includes("before")) {
+                        leadingIconVisible = true;
+                    }
+                    else if (k.includes("trailing") || k.includes("end") || k.includes("right") || k.includes("after")) {
+                        trailingIconVisible = true;
+                    }
+                    else {
+                        leadingIconVisible = true;
+                    }
+                }
+                if (v === "both") {
+                    leadingIconVisible = true;
+                    trailingIconVisible = true;
+                }
+                if (v === "leading" || v === "start" || v === "left")
+                    leadingIconVisible = true;
+                if (v === "trailing" || v === "end" || v === "right")
+                    trailingIconVisible = true;
+            }
+        }
+    }
+    // Check boolean property overrides (e.g. "showIcon": true, "showButtonText": false)
+    if (node.propertyOverrides) {
+        for (const [key, value] of Object.entries(node.propertyOverrides)) {
+            const k = key.toLowerCase();
+            if (typeof value === "boolean") {
+                if (k.includes("text") || k.includes("label") || k === "show") {
+                    if (k.includes("show") || k.includes("visible") || k.includes("enabled")) {
+                        textVisible = value;
+                    }
+                }
+                if (k.includes("icon")) {
+                    if (k.includes("leading") || k.includes("start") || k.includes("left")) {
+                        leadingIconVisible = value;
+                    }
+                    else if (k.includes("trailing") || k.includes("end") || k.includes("right")) {
+                        trailingIconVisible = value;
+                    }
+                    else if (k.includes("show") || k.includes("visible") || !k.includes("name")) {
+                        leadingIconVisible = value;
+                    }
+                }
+            }
+            if (typeof value === "boolean") {
+                if (value)
+                    visibleSlots.push(key);
+                else
+                    hiddenSlots.push(key);
+            }
+        }
+    }
+    // 4. Override Classification
+    const classification = {
+        representable: [],
+        derivedButRepresentable: [],
+        nonRepresentable: [],
+        warnings: []
+    };
+    if (dependency) {
+        const depProps = new Set((dependency.properties || []).map(p => p.name.toLowerCase()));
+        const depVariants = new Set((dependency.variantAxes || []).map(v => v.name.toLowerCase()));
+        // Check variant selection
+        if (node.variantSelection && typeof node.variantSelection === 'object') {
+            for (const key of Object.keys(node.variantSelection)) {
+                if (depVariants.has(key.toLowerCase())) {
+                    classification.representable.push(key);
+                }
+                else {
+                    classification.nonRepresentable.push(key);
+                    classification.warnings.push(`Variant axis "${key}" not found on dependency "${dependency.name}".`);
+                }
+            }
+        }
+        // Check property overrides
+        if (node.propertyOverrides && typeof node.propertyOverrides === 'object') {
+            for (const key of Object.keys(node.propertyOverrides)) {
+                if (depProps.has(key.toLowerCase())) {
+                    classification.representable.push(key);
+                }
+                else {
+                    // Heuristics for derived representable
+                    const k = key.toLowerCase();
+                    const v = node.propertyOverrides[key];
+                    if (typeof v === "object" && v !== null && v.kind === "dependency") {
+                        classification.derivedButRepresentable.push(key);
+                    }
+                    else if (k.includes("label") || k.includes("text") || k.includes("icon") || k.includes("show") || k.includes("visible")) {
+                        classification.derivedButRepresentable.push(key);
+                    }
+                    else {
+                        classification.nonRepresentable.push(key);
+                        classification.warnings.push(`Override "${key}" doesn't map to a public prop on "${dependency.name}".`);
+                    }
+                }
+            }
+        }
+    }
+    else {
+        classification.warnings.push(`Dependency "${node.componentId}" not found in model.`);
+    }
+    // 4.5 Style Override Detection
+    const styleOverrides = {};
+    if (node.rawStyles && dependency && dependency.styleMetadata) {
+        if (node.rawStyles.fills && dependency.styleMetadata.fills) {
+            const instanceFills = JSON.stringify(node.rawStyles.fills);
+            const depFills = dependency.styleMetadata.fills;
+            if (instanceFills !== depFills) {
+                const diff = resolveStyleDiff(String(depFills), instanceFills, tokenIndex);
+                if (diff) {
+                    styleOverrides["fill"] = diff;
+                    classification.nonRepresentable.push("style:fill");
+                    classification.warnings.push(`Nested instance has a local fill override not covered by dependency API.`);
+                }
+            }
+        }
+        if (node.rawStyles.strokes && dependency.styleMetadata.strokes) {
+            const instanceStrokes = JSON.stringify(node.rawStyles.strokes);
+            const depStrokes = dependency.styleMetadata.strokes;
+            if (instanceStrokes !== depStrokes) {
+                const diff = resolveStyleDiff(String(depStrokes), instanceStrokes, tokenIndex);
+                if (diff) {
+                    styleOverrides["stroke"] = diff;
+                    classification.nonRepresentable.push("style:stroke");
+                    classification.warnings.push(`Nested instance has a local stroke override not covered by dependency API.`);
+                }
+            }
+        }
+    }
+    // 5. Determine Implementation Mode
+    let implementationMode = "invoke-dependency";
+    if (classification.nonRepresentable.length > 0) {
+        implementationMode = "invoke-dependency-with-local-patch";
+        if (classification.nonRepresentable.length > 3) {
+            implementationMode = "recommend-variant-promotion";
+        }
+    }
+    else if (classification.representable.length > 0 || classification.derivedButRepresentable.length > 0) {
+        implementationMode = "invoke-dependency-with-overrides";
+    }
+    // 7. Determine Standard Functional Type
+    let standardType = "generic";
+    if (textVisible) {
+        if (!leadingIconVisible && !trailingIconVisible)
+            standardType = "text-only";
+        else if (leadingIconVisible && !trailingIconVisible)
+            standardType = "text-with-leading-icon";
+        else if (!leadingIconVisible && trailingIconVisible)
+            standardType = "text-with-trailing-icon";
+        else if (leadingIconVisible && trailingIconVisible)
+            standardType = "text-with-both-icons";
+    }
+    else {
+        if (leadingIconVisible || trailingIconVisible)
+            standardType = "icon-only";
+    }
+    // 8. Build Concise Summary
+    let summaryParts = [];
+    const typeLabels = {
+        "text-only": "Text-only",
+        "icon-only": "Icon-only",
+        "text-with-leading-icon": "Text with leading icon",
+        "text-with-trailing-icon": "Text with trailing icon",
+        "text-with-both-icons": "Text with both icons",
+        "generic": "Generic"
+    };
+    summaryParts.push(typeLabels[standardType] || "Generic instance");
+    if (textVisible && textContent)
+        summaryParts.push(`displaying "${textContent}"`);
+    else if (textVisible)
+        summaryParts.push("displaying default text");
+    if (!textVisible && (leadingIconVisible || trailingIconVisible))
+        summaryParts.push("as a standalone icon action");
+    const summary = summaryParts.join(" ");
+    // 9. Generate Invocation Hint & Slot Contracts
+    // Build a set of valid prop names from the resolved dep component.
+    // When the dep is known, props that don't match any of its variant axes or
+    // Figma component properties are stale overrides (renamed/removed in the source)
+    // and must not appear in the invocationHint.
+    const validDepPropKeys = new Set();
+    if (dependency) {
+        for (const ax of (dependency.variantAxes || [])) {
+            validDepPropKeys.add(cleanPropName(ax.name));
+        }
+        for (const prop of (dependency.properties || [])) {
+            validDepPropKeys.add(cleanPropName(prop.name));
+        }
+    }
+    const componentName = (node.name || "").split('/')[0].trim();
+    const propParts = [];
+    for (const [k, v] of Object.entries(resolvedProps)) {
+        // Always keep dependency-kind values (INSTANCE_SWAP overrides); only validate scalar props.
+        const isDep = v && typeof v === "object" && v.kind === "dependency";
+        if (!isDep) {
+            // Drop Figma-design-only axes (no React equivalent)
+            if (FIGMA_ONLY_PROP_NAMES.has(k))
+                continue;
+            // Drop `state` when its value is a Figma interaction state (hover/pressed/default…)
+            if (k === "state" && typeof v === "string" && FIGMA_INTERACTION_STATE_VALUES.has(v.toLowerCase()))
+                continue;
+            // Drop props that don't exist on the resolved dep's variant axes or component properties
+            if (dependency && validDepPropKeys.size > 0 && !validDepPropKeys.has(k))
+                continue;
+        }
+        if (isDep) {
+            propParts.push(`${k}={<${toPascalCase(v.importName)} />}`);
+        }
+        else if (typeof v === "string") {
+            propParts.push(`${k}="${v}"`);
+        }
+        else if (v === true) {
+            propParts.push(k);
+        }
+        else if (v === false) {
+            propParts.push(`${k}={false}`);
+        }
+        else {
+            propParts.push(`${k}={${JSON.stringify(v)}}`);
+        }
+    }
+    const safeCompName = toPascalCase(componentName);
+    const invocationHint = propParts.length > 0
+        ? `<${safeCompName} ${propParts.join(" ")} />`
+        : `<${safeCompName} />`;
+    // Strict Slot Contract Generation
+    const slotContract = {};
+    const resolveSlotDep = (slotNode) => {
+        if (slotNode?.componentId) {
+            const dep = findComp(slotNode.componentId, slotNode.name);
+            if (dep) {
+                return {
+                    componentName: dep.name,
+                    importName: dep.name,
+                    componentId: dep.id
+                };
+            }
+        }
+        return null;
+    };
+    // Identified slots based on common roles and node types
+    const textNodes = childNodes.filter(c => (c.role === "text" || c.type === "TEXT" || c.textContent !== undefined || c.rawStyles?.nodeType === "TEXT"));
+    const instanceNodes = childNodes.filter(c => (c.role === "instance" || c.type === "INSTANCE"));
+    const overrideNames = (node.childOverrides || []).map((o) => o.name);
+    // Map content slots (text)
+    const processedNames = new Set();
+    const computeSlotRender = (kind, visible, prop, textContent, dependency) => {
+        const depName = dependency
+            ? toPascalCase(dependency.componentName || dependency.importName)
+            : null;
+        if (!visible) {
+            return {
+                visibilityBehavior: "hidden-by-default",
+                renderPattern: prop ? `{${prop} ?? null}` : "null"
+            };
+        }
+        if (kind === "text") {
+            return {
+                visibilityBehavior: prop ? "caller-controlled" : "always",
+                renderPattern: prop ? `{${prop}}` : (textContent ? `"${textContent}"` : "null")
+            };
+        }
+        if (kind === "child") {
+            return {
+                visibilityBehavior: prop ? "caller-controlled" : "always",
+                renderPattern: prop ? `{${prop}}` : (depName ? `<${depName} />` : "null")
+            };
+        }
+        if (kind === "icon" || kind === "asset") {
+            if (prop) {
+                return {
+                    visibilityBehavior: "caller-overrideable",
+                    renderPattern: depName ? `{${prop} ?? <${depName} />}` : `{${prop} ?? null}`
+                };
+            }
+            return { visibilityBehavior: "always", renderPattern: depName ? `<${depName} />` : "null" };
+        }
+        // unknown kind
+        if (prop)
+            return { visibilityBehavior: "caller-controlled", renderPattern: `{${prop}}` };
+        return { visibilityBehavior: "always", renderPattern: depName ? `<${depName} />` : "null" };
+    };
+    const addSlot = (name, kind, visible, prop, textContent, dependency) => {
+        const cleanName = cleanPropName(name);
+        if (processedNames.has(cleanName))
+            return;
+        processedNames.add(cleanName);
+        const { renderPattern, visibilityBehavior } = computeSlotRender(kind, visible, prop, textContent, dependency);
+        slotContract[cleanName] = {
+            kind,
+            visible,
+            prop,
+            textContent,
+            dependency,
+            renderPattern,
+            visibilityBehavior
+        };
+    };
+    textNodes.forEach(tn => {
+        addSlot(tn.name, "text", tn.visible !== false, Object.entries(propSourceMap).find(([r, n]) => n === cleanPropName(tn.name) || r === tn.name)?.[1], tn.textContent);
+    });
+    // Also look at overrides for text slots that might not be in the tree
+    (node.childOverrides || []).forEach((o) => {
+        if (o.textContent !== undefined) {
+            addSlot(o.name, "text", o.visible !== false, Object.entries(propSourceMap).find(([r, n]) => n === cleanPropName(o.name) || r === o.name)?.[1], o.textContent);
+        }
+    });
+    instanceNodes.forEach(inode => {
+        let kind = "unknown";
+        const lowerName = inode.name.toLowerCase();
+        const ICON_KEYWORDS = ["icon", "chevron", "arrow", "close", "menu", "more", "check", "plus", "minus",
+            "search", "add", "delete", "edit", "clear", "back", "forward", "info",
+            "warning", "alert", "error", "star", "heart", "bolt", "flag", "dot"];
+        const hasDimension = /\d+x\d+/.test(inode.name);
+        const hasIconKeyword = ICON_KEYWORDS.some(k => lowerName.includes(k));
+        if (hasDimension || hasIconKeyword)
+            kind = "icon";
+        else if (lowerName.includes("asset") || lowerName.includes("img") || lowerName.includes("avatar"))
+            kind = "asset";
+        else if (inode.componentId)
+            kind = "child";
+        addSlot(inode.name, kind, inode.visible !== false, Object.entries(propSourceMap).find(([r, n]) => n === cleanPropName(inode.name) || r === inode.name)?.[1], undefined, resolveSlotDep(inode));
+    });
+    // Also look at overrides for instance slots
+    (node.childOverrides || []).forEach((o) => {
+        if (o.componentId) {
+            let kind = "child";
+            if (o.name.toLowerCase().includes("icon"))
+                kind = "icon";
+            addSlot(o.name, kind, o.visible !== false, Object.entries(propSourceMap).find(([r, n]) => n === cleanPropName(o.name) || r === o.name)?.[1], undefined, resolveSlotDep(o));
+        }
+    });
+    const overrideContract = compileOverrideContract(node.childOverrides || [], components, tokenIndex);
+    const instanceSummary = {
+        baseComponent: componentName,
+        variantSelection: node.variantSelection || {},
+        divergenceSummary: {
+            contentOverrides: Object.keys(overrideContract.content),
+            slotVisibilityOverrides: Object.keys(overrideContract.slotVisibility),
+            styleOverrides: Object.keys(overrideContract.style),
+            dependencyOverrides: Object.keys(overrideContract.dependency)
+        }
+    };
+    const designRules = { notes: [] };
+    if (dependency) {
+        // Intentional border policy
+        const baseHasBorder = dependency.styleMetadata && (dependency.styleMetadata.strokes || dependency.styleMetadata.border);
+        const instanceHasBorder = node.rawStyles && (node.rawStyles.strokes || node.rawStyles.border);
+        if (baseHasBorder && !instanceHasBorder) {
+            designRules.border = { policy: "none", reason: "intentional border removal in this instance" };
+            designRules.notes?.push("Border intentionally removed; do not re-add from base component defaults.");
+        }
+        // Slot visibility policy
+        if (hiddenSlots.length > 0) {
+            designRules.slotVisibilityPolicy = "strict";
+            designRules.notes?.push(`Slots [${hiddenSlots.join(", ")}] are intentionally hidden.`);
+        }
+    }
+    const implementationHints = {
+        preferInvocationContract: true,
+        preferOverrideContract: true,
+        preferSlotContract: true,
+        avoidDeepTreeInference: true,
+        notes: [
+            "Use slotContract to identify icon identities instead of inspecting child nodes.",
+            "Follow divergenceSummary for intentional local overrides."
+        ]
+    };
+    const recipe = {
+        standardType,
+        instanceSummary,
+        visibleSlots,
+        hiddenSlots,
+        textVisible,
+        textContent,
+        leadingIconVisible,
+        trailingIconVisible,
+        summary,
+        resolvedProps,
+        styleOverrides: Object.keys(styleOverrides).length > 0 ? styleOverrides : undefined,
+        invocationHint,
+        implementationMode,
+        classification,
+        slotContract,
+        designRules,
+        implementationHints,
+        overrideContract
+    };
+    recipe.invocationContract = resolveInvocationContract(node, recipe);
+    return recipe;
+}
+/**
+ * Re-resolves all instance recipes in a tree once all component definitions are available.
+ */
+export function relinkTreeRecipes(node, components, tokenIndex) {
+    if (node.componentId) {
+        node.recipe = resolveInstanceRecipe(node, components, tokenIndex);
+    }
+    if (node.children) {
+        for (const child of node.children) {
+            relinkTreeRecipes(child, components, tokenIndex);
+        }
+    }
+    if (node.childOverrides) {
+        for (const override of node.childOverrides) {
+            // Mock a node for recipe resolution
+            const mockNode = {
+                type: "leaf",
+                name: override.name,
+                componentId: override.componentId,
+                variantSelection: override.variantSelection,
+                propertyOverrides: override.propertyOverrides,
+                rawStyles: override.rawStyles,
+                visible: override.visible !== false
+            };
+            override.recipe = resolveInstanceRecipe(mockNode, components, tokenIndex);
+        }
+    }
+}
+/**
+ * Resolves a visual style diff between two Figma paint JSON blocks.
+ */
+function resolveStyleDiff(fromRaw, toRaw, tokenIndex) {
+    try {
+        const from = JSON.parse(fromRaw);
+        const to = JSON.parse(toRaw);
+        // Only handle simple solid fills for now
+        const fromSolid = Array.isArray(from) ? from.find((f) => f.type === "SOLID") : undefined;
+        const toSolid = Array.isArray(to) ? to.find((f) => f.type === "SOLID") : undefined;
+        if (!toSolid)
+            return undefined;
+        const res = { resolution: "literal" };
+        if (toSolid.color) {
+            res.toColor = rgbToHex(toSolid.color.r, toSolid.color.g, toSolid.color.b);
+        }
+        if (toSolid.boundVariables?.color && tokenIndex) {
+            const binding = resolveTokenBindingFromIndex(toSolid.boundVariables.color.id, tokenIndex);
+            if (binding) {
+                res.toToken = binding.sourceTokenName;
+                res.toCssVar = binding.canonicalCssVar;
+                res.resolution = "token";
+                res.toBinding = binding;
+            }
+        }
+        if (fromSolid) {
+            if (fromSolid.color) {
+                res.fromColor = rgbToHex(fromSolid.color.r, fromSolid.color.g, fromSolid.color.b);
+            }
+            if (fromSolid.boundVariables?.color && tokenIndex) {
+                const binding = resolveTokenBindingFromIndex(fromSolid.boundVariables.color.id, tokenIndex);
+                if (binding) {
+                    res.fromToken = binding.sourceTokenName;
+                    res.fromCssVar = binding.canonicalCssVar;
+                    res.fromBinding = binding;
+                }
+            }
+        }
+        return res;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Derives a code-facing invocation contract from design-time usage.
+ */
+function resolveInvocationContract(node, recipe) {
+    const componentName = toPascalCase((node?.name || "").split('/')[0].trim());
+    const resolvedProps = recipe?.resolvedProps ? { ...recipe.resolvedProps } : {};
+    const omitProps = [];
+    const iconBindingPolicy = {};
+    // Determine children policy
+    let childrenPolicy = "generic";
+    if (recipe?.standardType === "icon-only")
+        childrenPolicy = "none";
+    else if (recipe?.standardType === "text-only" || recipe?.textContent)
+        childrenPolicy = "text";
+    // Handle prop omission (e.g. if text is hidden, omit 'label' prop if it exists)
+    if (recipe && !recipe.textVisible) {
+        omitProps.push("label", "text", "value", "title");
+    }
+    // Icon bindings from overrides
+    if (node?.propertyOverrides && typeof node.propertyOverrides === 'object') {
+        for (const [key, value] of Object.entries(node.propertyOverrides)) {
+            const k = (key || "").toLowerCase();
+            if (k.includes("icon") && typeof value === "string") {
+                iconBindingPolicy[k] = value;
+            }
+        }
+    }
+    return {
+        componentName,
+        importName: componentName,
+        resolvedProps,
+        propSourceMap: recipe?.propSourceMap || {},
+        omitProps,
+        slotContract: recipe?.slotContract || {},
+        childrenPolicy,
+        iconBindingPolicy,
+        renderHint: recipe?.invocationHint || "",
+        overrideContract: recipe?.overrideContract
+    };
+}
+/**
+ * Compiles low-level child overrides into a code-facing contract.
+ */
+function compileOverrideContract(childOverrides, components, tokenIndex) {
+    const contract = {
+        slotVisibility: {},
+        content: {},
+        dependency: {},
+        style: {},
+        classification: {
+            representable: [],
+            derivedButRepresentable: [],
+            nonRepresentable: [],
+            warnings: []
+        }
+    };
+    const safeArray = (val) => Array.isArray(val) ? val : [];
+    for (const override of safeArray(childOverrides)) {
+        const name = override.name || "unknown";
+        // 1. Visibility Overrides
+        if (override.visible === false) {
+            contract.slotVisibility[name] = false;
+        }
+        else if (override.visible === true) {
+            contract.slotVisibility[name] = true;
+        }
+        // 2. Content Overrides
+        if (override.textContent !== undefined) {
+            contract.content[name] = override.textContent;
+        }
+        // 3. Dependency Overrides (Swaps)
+        if (override.componentId) {
+            let dep = components.find(c => c.id === override.componentId);
+            if (!dep && /^\d+:\d+$/.test(override.componentId)) {
+                dep = components.find(c => c.id === `comp_${override.componentId.replace(/:/g, "_")}`);
+            }
+            if (dep) {
+                contract.dependency[name] = {
+                    kind: "dependency",
+                    componentName: dep.name,
+                    importName: dep.name,
+                    componentId: dep.id
+                };
+            }
+        }
+        // 4. Style Overrides (Simplistic for now, matches resolveStyleDiff logic)
+        if (override.rawStyles && (override.rawStyles.fills || override.rawStyles.strokes)) {
+            const styles = {};
+            if (override.rawStyles.fills) {
+                const fill = resolveStyleDiff("[]", JSON.stringify(override.rawStyles.fills), tokenIndex);
+                if (fill)
+                    styles.fill = fill;
+            }
+            if (override.rawStyles.strokes) {
+                const stroke = resolveStyleDiff("[]", JSON.stringify(override.rawStyles.strokes), tokenIndex);
+                if (stroke)
+                    styles.stroke = stroke;
+            }
+            if (Object.keys(styles).length > 0) {
+                contract.style[name] = styles;
+            }
+        }
+    }
+    // Basic classification
+    contract.classification.representable = [
+        ...Object.keys(contract.slotVisibility),
+        ...Object.keys(contract.content),
+        ...Object.keys(contract.dependency)
+    ];
+    return contract;
+}
+//# sourceMappingURL=instance-resolver.js.map