@calibrate-ds/core 0.1.0

package/dist/context/get-component-context.js

@@ -0,0 +1,898 @@
+import * as path from "node:path";
+import { checkComponentReadiness } from "../plan/implementation-plan.js";
+import { getPTBTokenVariableName } from "../tokens/naming.js";
+import { calculateContextHash, hashComponentDefinition } from "./hashing.js";
+import { resolveTokenBinding } from "../tokens/resolution.js";
+import { relinkTreeRecipes } from "../normalizer/instance-resolver.js";
+import { buildCompressedContext } from "./compressed-context.js";
+import { resolveDSPaths } from "../filesystem/resolve-ds-paths.js";
+import { createNamingStrategy, normalizeIconDisplayName } from "../mappings/naming-strategy.js";
+import { isIconComponent } from "../icons/enrich-icon-svgs.js";
+/**
+ * Constructs a formalized v1 ComponentContext for a given component.
+ * This acts as the stable design-system truth for tooling.
+ */
+function safeObject(val) {
+    return val && typeof val === 'object' && !Array.isArray(val) ? val : {};
+}
+function safeArray(val) {
+    return Array.isArray(val) ? val : [];
+}
+/**
+ * Normalizes a property name into camelCase for implementation usage.
+ */
+function cleanPropName(name) {
+    return name.trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+(.)/g, (_, c) => c.toUpperCase())
+        .replace(/[^a-zA-Z0-9]/g, "");
+}
+/**
+ * Resolves an implementation-ready content contract for a text node,
+ * awareness of both props and state-specific defaults.
+ */
+function resolveContentContract(node, variantDiffs) {
+    const name = (node.name || "").trim();
+    const role = node.role || "";
+    const baseValue = node.textContent || "";
+    const contract = {
+        bindingMode: "static",
+        dataType: "string",
+        required: true,
+        baseValue: baseValue,
+        sourceRole: role
+    };
+    // 1. Scan variantDiffs for state-specific text content
+    const stateDefaults = {};
+    let hasStateChanges = false;
+    for (const diff of safeArray(variantDiffs)) {
+        const foundNode = safeArray(diff.changedNodes).find((n) => n.nodeName === name);
+        if (foundNode) {
+            const textChange = safeArray(foundNode.changes).find((c) => c.property === "textContent");
+            if (textChange && textChange.to !== undefined) {
+                const stateKey = diff.variantName || Object.values(diff.variantSelection || {}).join("-");
+                stateDefaults[stateKey] = textChange.to;
+                hasStateChanges = true;
+            }
+        }
+    }
+    if (hasStateChanges) {
+        contract.stateDefaults = stateDefaults;
+    }
+    // 2. Heuristics for dynamic prop mapping
+    const lowerName = name.toLowerCase();
+    let propCandidate;
+    if (lowerName.includes("title") || lowerName.includes("header") || role === "title")
+        propCandidate = "title";
+    else if (lowerName.includes("description") || lowerName.includes("body") || lowerName.includes("summary") || role === "description")
+        propCandidate = "description";
+    else if (lowerName.includes("time") || lowerName.includes("date") || lowerName.includes("timestamp"))
+        propCandidate = "time";
+    else if (lowerName.includes("label") || role === "label")
+        propCandidate = "label";
+    else if (lowerName.includes("button text") || lowerName.includes("btn text") || (lowerName === "text" && role === "text"))
+        propCandidate = "text";
+    else if (lowerName.includes("helper") || role === "helper-text")
+        propCandidate = "helperText";
+    else if (lowerName.includes("error") || role === "error-text")
+        propCandidate = "errorText";
+    const hasProp = !!propCandidate;
+    // 3. Determine Binding Mode
+    if (hasProp && hasStateChanges) {
+        contract.bindingMode = "state-default-with-prop-override";
+        contract.propName = propCandidate;
+        contract.overridePriority = ["explicitProp", "stateDefault", "baseValue"];
+    }
+    else if (hasProp) {
+        contract.bindingMode = "prop-only";
+        contract.propName = propCandidate;
+    }
+    else if (hasStateChanges) {
+        contract.bindingMode = "state-only";
+    }
+    else if (role === "placeholder-text" || lowerName.includes("placeholder")) {
+        contract.bindingMode = "prop-only";
+        contract.propName = propCandidate || "placeholder";
+    }
+    else if (name.length > 2 && !name.includes("Layer") && !name.includes("Frame") && !name.includes("Group")) {
+        contract.bindingMode = "dynamicHint";
+        contract.propName = cleanPropName(name);
+        contract.warning = "Inferred from node name; verify if this should be a prop/state binding.";
+    }
+    return contract;
+}
+/**
+ * Extracts a semantic text style reference (e.g. body/sm) from raw Figma style data.
+ */
+function resolveTextStyleRef(node, designSystemStyles) {
+    const styleId = node.rawStyles?.figmaStyles?.text;
+    const styleDef = styleId && designSystemStyles ? designSystemStyles[styleId] : undefined;
+    // Use style library name first, fallback to node-level name if available
+    const displayName = styleDef?.name || node.rawStyles?.textStyle?.name;
+    if (!displayName)
+        return undefined;
+    if (displayName.includes("/")) {
+        const parts = displayName.split("/");
+        return {
+            group: parts[0].trim().toLowerCase(),
+            name: parts[1].trim().toLowerCase(),
+            displayName
+        };
+    }
+    return {
+        displayName,
+        name: displayName.trim().toLowerCase()
+    };
+}
+/**
+ * Compiles a transition summary between variants.
+ */
+function resolveTransitionSummary(variantDiffs) {
+    const summary = {};
+    for (const diff of safeArray(variantDiffs)) {
+        if (!diff.variantName)
+            continue;
+        // For simplicity in Phase 3, we summarize "base -> variant"
+        const key = `base -> ${diff.variantName}`;
+        summary[key] = {
+            contentChanges: safeArray(diff.changedNodes)
+                .filter((n) => safeArray(n.changes).some((c) => c.property === "textContent"))
+                .map((n) => n.nodeName),
+            slotVisibilityChanges: [
+                ...safeArray(diff.addedNodes).map((n) => n.name),
+                ...safeArray(diff.removedNodes).map((n) => n.name)
+            ],
+            styleChanges: safeArray(diff.changedNodes)
+                .filter((n) => safeArray(n.changes).some((c) => c.property !== "textContent"))
+                .map((n) => n.nodeName),
+            dependencyChanges: safeArray(diff.changedNodes)
+                .filter((n) => safeArray(n.changes).some((c) => c.property === "componentId"))
+                .map((n) => n.nodeName)
+        };
+    }
+    return summary;
+}
+/**
+ * Infers a state contract for components with variants.
+ */
+function resolveStateContract(component, variantDiffs) {
+    if (!component.variantAxes || component.variantAxes.length === 0)
+        return undefined;
+    // Use the first axis as the primary state axis for now
+    const primaryAxis = component.variantAxes[0];
+    const stateDefaults = {};
+    for (const diff of safeArray(variantDiffs)) {
+        const stateKey = diff.variantName || Object.values(diff.variantSelection || {}).join("-");
+        stateDefaults[stateKey] = {
+            content: {},
+            slotVisibility: {},
+            style: {},
+            dependency: {}
+        };
+        // Compile content and style defaults
+        for (const node of safeArray(diff.changedNodes)) {
+            const textChange = safeArray(node.changes).find((c) => c.property === "textContent");
+            if (textChange) {
+                stateDefaults[stateKey].content[node.nodeName] = textChange.to;
+            }
+            const styleChanges = safeArray(node.changes).filter((c) => c.property !== "textContent" && c.property !== "componentId");
+            if (styleChanges.length > 0) {
+                stateDefaults[stateKey].style[node.nodeName] = styleChanges.reduce((acc, c) => {
+                    acc[c.property] = c.to;
+                    return acc;
+                }, {});
+            }
+            const dependencyChange = safeArray(node.changes).find((c) => c.property === "componentId");
+            if (dependencyChange) {
+                stateDefaults[stateKey].dependency[node.nodeName] = dependencyChange.to;
+            }
+        }
+        // Compile visibility defaults
+        for (const node of safeArray(diff.addedNodes)) {
+            stateDefaults[stateKey].slotVisibility[node.name] = true;
+        }
+        for (const node of safeArray(diff.removedNodes)) {
+            stateDefaults[stateKey].slotVisibility[node.name] = false;
+        }
+    }
+    return {
+        controller: {
+            kind: "prop",
+            name: cleanPropName(primaryAxis.name),
+            dataType: "string",
+            defaultValue: primaryAxis.defaultValue
+        },
+        stateAxis: {
+            name: primaryAxis.name,
+            options: primaryAxis.options
+        },
+        stateDefaults,
+        overridePriority: ["explicitProp", "stateDefault", "baseValue"]
+    };
+}
+/**
+ * Extracts interactions from Figma prototype data if available.
+ */
+function resolveInteractionContract(component) {
+    const events = [];
+    const warnings = [];
+    // Heuristic: If it's a button or has "click" in name, expect interaction
+    const hasClickableName = component.name.toLowerCase().includes("button") ||
+        component.name.toLowerCase().includes("btn") ||
+        component.name.toLowerCase().includes("link");
+    if (hasClickableName) {
+        // We lack deep prototype parsing in this version, so we provide a hint/placeholder
+        warnings.push("Interactive affordance detected based on component name; verify Figma prototyping for exact behavior.");
+    }
+    return {
+        events,
+        interactionModel: "declarative",
+        warnings: warnings.length > 0 ? warnings : undefined
+    };
+}
+/**
+ * Normalizes a Figma trigger into a runtime event and category.
+ */
+function normalizeTrigger(figmaTrigger) {
+    const type = figmaTrigger?.type || "unknown";
+    switch (type) {
+        case "ON_CLICK": return { runtime: "onClick", category: "click" };
+        case "MOUSE_ENTER": return { runtime: "onMouseEnter", category: "pointer-enter" };
+        case "MOUSE_LEAVE": return { runtime: "onMouseLeave", category: "pointer-leave" };
+        case "MOUSE_DOWN": return { runtime: "onMouseDown", category: "pointer-down" };
+        case "MOUSE_UP": return { runtime: "onMouseUp", category: "pointer-up" };
+        case "AFTER_DELAY": return { runtime: "afterDelay", category: "timer" };
+        case "ON_DRAG": return { runtime: "onDrag", category: "gesture" };
+        case "ON_HOVER": return { runtime: "onMouseEnter", category: "pointer-enter" }; // Map hover to enter for simplicity
+        default: return { runtime: "unknown", category: "unknown" };
+    }
+}
+/**
+ * Normalizes a Figma action.
+ */
+function normalizeAction(figmaAction) {
+    const type = figmaAction?.type || "unknown";
+    switch (type) {
+        case "NODE":
+            if (figmaAction.navigation === "CHANGE_TO") {
+                return { type: "changeState", targetState: figmaAction.destinationId };
+            }
+            if (figmaAction.navigation === "NAVIGATE") {
+                return { type: "navigate", targetFrame: figmaAction.destinationId };
+            }
+            return { type: "unknown" };
+        case "OPEN_OVERLAY": return { type: "openOverlay", targetOverlay: figmaAction.destinationId };
+        case "CLOSE_OVERLAY": return { type: "closeOverlay" };
+        case "BACK": return { type: "back" };
+        case "URL": return { type: "navigate", targetFrame: figmaAction.url };
+        default: return { type: "unknown" };
+    }
+}
+/**
+ * Normalizes Figma animation metadata.
+ */
+function normalizeAnimation(figmaAnimation) {
+    if (!figmaAnimation)
+        return undefined;
+    const type = figmaAnimation.type || "instant";
+    return {
+        figma: type,
+        type: type.toLowerCase().replace(/_([a-z])/g, (g) => g[1].toUpperCase()), // e.g. SMART_ANIMATE -> smartAnimate
+        curve: figmaAnimation.easing?.toLowerCase() || "ease-out",
+        durationMs: figmaAnimation.duration !== undefined ? Math.round(figmaAnimation.duration * 1000) : 300,
+    };
+}
+/**
+ * Infers animation implementation hints based on state differences.
+ */
+function resolveAnimationHints(action, component) {
+    if (action.type !== "changeState" || !action.targetState) {
+        return { preferredImplementation: "state-swap" };
+    }
+    // Try to find the diff for the target state
+    const diffs = safeArray(component.variantDiffs);
+    const targetDiff = diffs.find(d => d.variantName === action.targetState ||
+        Object.values(d.variantSelection || {}).join("-") === action.targetState);
+    if (!targetDiff) {
+        return { preferredImplementation: "layout-transition" }; // Default for smart animate
+    }
+    const changedProps = new Set();
+    for (const node of safeArray(targetDiff.changedNodes)) {
+        for (const change of safeArray(node.changes)) {
+            if (change.property === "absoluteBoundingBox" || change.property === "size")
+                changedProps.add("size");
+            if (change.property === "opacity")
+                changedProps.add("opacity");
+            if (change.property === "fills" || change.property === "color")
+                changedProps.add("color");
+        }
+    }
+    return {
+        changedProperties: changedProps.size > 0 ? Array.from(changedProps) : undefined,
+        preferredImplementation: changedProps.has("size") ? "layout-transition" : "opacity-transition"
+    };
+}
+/**
+ * Resolves high-fidelity prototype interactions.
+ */
+function resolvePrototypeInteractionContract(component) {
+    const interactions = [];
+    const warnings = [];
+    const stateTransitions = new Set();
+    const processReactions = (node, path = "root") => {
+        const reactions = safeArray(node.reactions);
+        for (const reaction of reactions) {
+            const trigger = normalizeTrigger(reaction.trigger);
+            const action = normalizeAction(reaction.action);
+            const animation = normalizeAnimation(reaction.action?.transition);
+            const animationHints = resolveAnimationHints(action, component);
+            if (trigger.runtime === "unknown" || action.type === "unknown") {
+                warnings.push(`Incomplete normalization for interaction on node '${node.name}' (type: ${reaction.trigger?.type})`);
+            }
+            const interaction = {
+                source: {
+                    nodeName: node.name || "unknown",
+                    path,
+                    role: node.role || "generic"
+                },
+                trigger: {
+                    figma: reaction.trigger?.type || "unknown",
+                    runtime: trigger.runtime,
+                    category: trigger.category
+                },
+                action: {
+                    figma: reaction.action?.type || "unknown",
+                    ...action
+                },
+                animation,
+                animationHints
+            };
+            // Detect state transitions for reverse logic checking
+            if (interaction.action.type === "changeState" && interaction.action.targetState) {
+                stateTransitions.add(`${interaction.trigger.category}->${interaction.action.targetState}`);
+            }
+            interactions.push(interaction);
+        }
+        if (node.children) {
+            for (const child of safeArray(node.children)) {
+                processReactions(child, `${path}/${child.name}`);
+            }
+        }
+    };
+    // Process the render tree (canonical view for all components)
+    if (component.renderTree) {
+        processReactions(component.renderTree);
+    }
+    else if (component.baseRenderTree) {
+        // Fallback for sets if renderTree is somehow missing or distinct
+        processReactions(component.baseRenderTree);
+    }
+    // Check for reverse transition gaps (e.g. hover without leave)
+    const hoverTransitions = interactions.filter(i => i.trigger.category === "pointer-enter");
+    for (const hover of hoverTransitions) {
+        const hasReverse = interactions.some(i => i.trigger.category === "pointer-leave" &&
+            i.source.nodeName === hover.source.nodeName);
+        if (!hasReverse) {
+            warnings.push(`One-way hover transition detected on '${hover.source.nodeName}'; reverse transition (pointer-leave) not found.`);
+        }
+    }
+    return {
+        interactions,
+        warnings: warnings.length > 0 ? warnings : undefined
+    };
+}
+export async function getComponentContext(componentId, model, config, manifest) {
+    const component = model.components.find(c => c.id === componentId);
+    if (!component)
+        return undefined;
+    const manifestEntry = manifest?.components[componentId];
+    // Precompute import path helpers once for all dependency lookups
+    const { componentsDir } = resolveDSPaths(config);
+    const naming = createNamingStrategy(config.naming);
+    const currentCategoryDir = component.categoryPath
+        ? path.join(componentsDir, naming.formatFolderName(component.categoryPath), naming.formatFolderName(component.name))
+        : path.join(componentsDir, naming.formatFolderName(component.name));
+    const dependencies = await (async () => {
+        const grouped = new Map();
+        for (const id of (component.dependencies || [])) {
+            // id is usually a PTB internal ID (comp_N_M), but falls back to the raw
+            // Figma componentId when the normalizer couldn't map it. Support both.
+            const dep = model.components.find((c) => c.id === id ||
+                c.designToolNodeId === id ||
+                (/^\d+:\d+$/.test(id) && c.id === `comp_${id.replace(/:/g, "_")}`));
+            const name = dep ? dep.name : `unknown (${id})`;
+            const existing = grouped.get(name);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                let status = "external";
+                let importPath;
+                if (dep) {
+                    const readiness = await checkComponentReadiness(dep, config, manifest);
+                    status = readiness.isReady ? "ready" : "missing";
+                    // Compute the correct relative import path from this component to the dependency.
+                    // Icon components use a fixed ../../icons/ prefix handled separately by post-processing.
+                    if (!isIconComponent(dep.name)) {
+                        const depName = dep.name;
+                        const depFolderName = naming.formatFolderName(depName);
+                        const depDir = dep.categoryPath
+                            ? path.join(componentsDir, naming.formatFolderName(dep.categoryPath), depFolderName)
+                            : path.join(componentsDir, depFolderName);
+                        const rel = path.relative(currentCategoryDir, depDir).replace(/\\/g, "/") + "/index.js";
+                        importPath = rel.startsWith(".") ? rel : "./" + rel;
+                    }
+                    else {
+                        const normalized = normalizeIconDisplayName(dep.name);
+                        importPath = `../../icons/${naming.formatFolderName(normalized)}/index.js`;
+                    }
+                }
+                const propHints = [];
+                if (dep) {
+                    for (const axis of (dep.variantAxes || [])) {
+                        const propName = cleanPropName(axis.name);
+                        const union = axis.options.map((o) => `'${o}'`).join(" | ");
+                        const defNote = axis.defaultValue ? ` /* default: '${axis.defaultValue}' */` : "";
+                        propHints.push(`${propName}?: ${union}${defNote}`);
+                    }
+                    for (const prop of (dep.properties || [])) {
+                        const propName = cleanPropName(prop.name);
+                        if (prop.type === "text") {
+                            const defNote = prop.defaultValue ? ` /* default: "${prop.defaultValue}" */` : "";
+                            propHints.push(`${propName}?: string${defNote}`);
+                        }
+                        else if (prop.type === "boolean") {
+                            const defNote = prop.defaultValue !== undefined ? ` /* default: ${prop.defaultValue} */` : "";
+                            propHints.push(`${propName}?: boolean${defNote}`);
+                        }
+                        else if (prop.type === "instance") {
+                            propHints.push(`${propName}?: React.ReactNode`);
+                        }
+                    }
+                }
+                grouped.set(name, { id, name, count: 1, kind: "nested-instance", source: "figma-nested-instance", status, importPath, propHints });
+            }
+        }
+        return Array.from(grouped.values()).sort((a, b) => a.name.localeCompare(b.name));
+    })();
+    const resolvedBindings = {};
+    const resolveAndAdd = (slot, sourceVarId, targetObj = resolvedBindings) => {
+        if (!sourceVarId)
+            return;
+        const resolved = resolveTokenBinding(sourceVarId, model.tokens);
+        if (resolved) {
+            targetObj[slot] = resolved;
+        }
+    };
+    // 1. Resolve explicit token bindings
+    for (const b of (component.tokenBindings || [])) {
+        if (b.boundToken?.id) {
+            resolveAndAdd(b.slot, b.boundToken.id);
+        }
+        else if (b.resolvedToken?.id) {
+            resolveAndAdd(b.slot, b.resolvedToken.id);
+        }
+    }
+    // 2. Resolve layout tokens
+    if (component.layout) {
+        if (component.layout.gap?.resolvedToken?.id) {
+            resolveAndAdd("gap", component.layout.gap.resolvedToken.id);
+        }
+        if (component.layout.padding) {
+            const p = component.layout.padding;
+            if (p.top?.resolvedToken?.id)
+                resolveAndAdd("paddingTop", p.top.resolvedToken.id);
+            if (p.right?.resolvedToken?.id)
+                resolveAndAdd("paddingRight", p.right.resolvedToken.id);
+            if (p.bottom?.resolvedToken?.id)
+                resolveAndAdd("paddingBottom", p.bottom.resolvedToken.id);
+            if (p.left?.resolvedToken?.id)
+                resolveAndAdd("paddingLeft", p.left.resolvedToken.id);
+        }
+    }
+    // 3. Resolve sizing tokens
+    if (component.size) {
+        if (component.size.width?.resolvedToken?.id)
+            resolveAndAdd("width", component.size.width.resolvedToken.id);
+        if (component.size.height?.resolvedToken?.id)
+            resolveAndAdd("height", component.size.height.resolvedToken.id);
+    }
+    // 4. Resolve stylistic metadata if it contains variable IDs (rare but possible)
+    if (component.styleMetadata) {
+        for (const [key, value] of Object.entries(component.styleMetadata)) {
+            if (typeof value === "string" && value.startsWith("VariableID:")) {
+                resolveAndAdd(key, value);
+            }
+        }
+    }
+    const contentSourceMap = {};
+    const variantDiffs = component.variantDiffs || [];
+    const context = {
+        component: {
+            name: component.name,
+            id: component.id,
+            kind: typeof component.kind === "string"
+                ? { value: component.kind, inferred: true }
+                : component.kind ?? { value: "unclassified", inferred: true },
+            category: component.categoryPath || "unclassified",
+            framework: config.framework.name,
+            artifacts: manifestEntry ? {
+                folder: manifestEntry.folder,
+                files: manifestEntry.artifacts,
+                isManaged: true
+            } : {
+                isManaged: false
+            },
+            description: component.description || null
+        },
+        variantAxes: (component.variantAxes || []).map(p => ({
+            ...p,
+            source: p.source || "figma-component-set"
+        })),
+        properties: (component.properties || []).map(p => ({
+            ...p,
+            source: p.source || "figma-component-property"
+        })),
+        dependencies,
+        slots: component.styleMetadata ? Object.keys(component.styleMetadata).map(name => ({ name })) : [],
+        tokenBindings: (component.tokenBindings || []).map(b => {
+            const resolved = typeof b.resolvedToken === "string"
+                ? { name: b.resolvedToken }
+                : b.resolvedToken;
+            if (resolved && resolved.name && resolved.collection?.name) {
+                resolved.cssVariable = getPTBTokenVariableName(resolved.collection.name, resolved.name);
+            }
+            return {
+                ...b,
+                resolvedToken: resolved,
+                boundToken: typeof b.boundToken === "string"
+                    ? { name: b.boundToken }
+                    : b.boundToken,
+                source: b.source || (b.boundToken ? "figma-variable-binding" : undefined)
+            };
+        }),
+        resolvedBindings,
+        layout: component.layout ? {
+            ...component.layout,
+            mainAlignment: component.layout.mainAlignment || component.layout.alignment || "start",
+            crossAlignment: component.layout.crossAlignment || "center",
+            gap: component.layout.gap ? {
+                ...component.layout.gap,
+                resolvedToken: typeof component.layout.gap.resolvedToken === "string"
+                    ? { name: component.layout.gap.resolvedToken }
+                    : component.layout.gap.resolvedToken
+            } : undefined,
+            padding: component.layout.padding ? {
+                top: {
+                    ...component.layout.padding.top,
+                    resolvedToken: typeof component.layout.padding.top.resolvedToken === "string"
+                        ? { name: component.layout.padding.top.resolvedToken }
+                        : component.layout.padding.top.resolvedToken
+                },
+                right: {
+                    ...component.layout.padding.right,
+                    resolvedToken: typeof component.layout.padding.right.resolvedToken === "string"
+                        ? { name: component.layout.padding.right.resolvedToken }
+                        : component.layout.padding.right.resolvedToken
+                },
+                bottom: {
+                    ...component.layout.padding.bottom,
+                    resolvedToken: typeof component.layout.padding.bottom.resolvedToken === "string"
+                        ? { name: component.layout.padding.bottom.resolvedToken }
+                        : component.layout.padding.bottom.resolvedToken
+                },
+                left: {
+                    ...component.layout.padding.left,
+                    resolvedToken: typeof component.layout.padding.left.resolvedToken === "string"
+                        ? { name: component.layout.padding.left.resolvedToken }
+                        : component.layout.padding.left.resolvedToken
+                },
+            } : undefined
+        } : null,
+        size: component.size ? {
+            width: {
+                ...component.size.width,
+                resolvedToken: typeof component.size.width.resolvedToken === "string"
+                    ? { name: component.size.width.resolvedToken }
+                    : component.size.width.resolvedToken
+            },
+            height: {
+                ...component.size.height,
+                resolvedToken: typeof component.size.height.resolvedToken === "string"
+                    ? { name: component.size.height.resolvedToken }
+                    : component.size.height.resolvedToken
+            }
+        } : null,
+        renderTree: component.renderTree,
+        baseRenderTree: component.baseRenderTree,
+        defaultVariantSelection: component.defaultVariantSelection,
+        variantDiffs: component.variantDiffs,
+        childNodes: component.childNodes,
+        dependencyInstances: component.dependencyInstances,
+        contentSourceMap: {},
+        stateContract: resolveStateContract(component, variantDiffs),
+        interactionContract: resolveInteractionContract(component),
+        transitionSummary: resolveTransitionSummary(variantDiffs),
+        prototypeInteractionContract: resolvePrototypeInteractionContract(component)
+    };
+    // 5. Relink recipes first to ensure engineering contracts are ready
+    if (context.renderTree)
+        relinkTreeRecipes(context.renderTree, model.components);
+    if (context.baseRenderTree)
+        relinkTreeRecipes(context.baseRenderTree, model.components);
+    // 6. Populate resolvedBindings and contentBindings onto tree nodes recursively
+    function populateTreeBindings(node) {
+        if (!node)
+            return;
+        try {
+            doPopulateTreeBindings(node);
+        }
+        catch (e) {
+            node.warnings = safeArray(node.warnings);
+            node.warnings.push({
+                type: "enrichment-fallback",
+                nodeName: node.name || "unknown",
+                reason: e.message
+            });
+        }
+    }
+    function doPopulateTreeBindings(node) {
+        const nodeBoundVars = safeObject(node.boundVariables);
+        const styleBoundVars = safeObject(node.rawStyles?.textStyle?.boundVariables);
+        const allBoundVars = { ...styleBoundVars, ...nodeBoundVars }; // Node direct bindings take precedence
+        if (Object.keys(allBoundVars).length > 0) {
+            node.resolvedBindings = node.resolvedBindings || {};
+            for (const [key, val] of Object.entries(allBoundVars)) {
+                if (!val)
+                    continue;
+                if (Array.isArray(val) && val[0] && val[0].id) {
+                    if (key === "fills") {
+                        resolveAndAdd("fill", val[0].id, node.resolvedBindings);
+                        resolveAndAdd("color", val[0].id, node.resolvedBindings);
+                    }
+                    else {
+                        const slot = key === "strokes" ? "stroke" : key;
+                        resolveAndAdd(slot, val[0].id, node.resolvedBindings);
+                    }
+                }
+                else if (typeof val === "object" && val.id) {
+                    resolveAndAdd(key, val.id, node.resolvedBindings);
+                }
+            }
+        }
+        if (node.rawStyles && Array.isArray(node.rawStyles.fills)) {
+            for (const fill of safeArray(node.rawStyles.fills)) {
+                const fillBoundVars = safeObject(fill?.boundVariables);
+                if (fillBoundVars.color && fillBoundVars.color.id) {
+                    node.resolvedBindings = node.resolvedBindings || {};
+                    resolveAndAdd("color", fillBoundVars.color.id, node.resolvedBindings);
+                    resolveAndAdd("fill", fillBoundVars.color.id, node.resolvedBindings);
+                    break;
+                }
+            }
+        }
+        if (node.role === "text" || node.role === "title" || node.role === "label" || node.role === "placeholder-text" || node.role === "error-text" || node.role === "helper-text" || (node.type === "leaf" && (node.textContent !== undefined || (node.name || "").includes("Text"))) || node.rawStyles?.nodeType === "TEXT") {
+            // Refined Typography Contract v2
+            const rawStyle = node.rawStyles?.textStyle || {};
+            const textStyleRef = resolveTextStyleRef(node, model.styles);
+            // Derive preferredClassName from the resolved style ref, or fall back to any
+            // raw style name on the node itself (covers externally-defined text styles
+            // that aren't synced into model.styles but whose name is present on the node).
+            let preferredClassName;
+            if (textStyleRef?.displayName) {
+                preferredClassName = `type-${textStyleRef.displayName.toLowerCase().replace(/[/\s]+/g, "-")}`;
+            }
+            else {
+                const rawName = node.rawStyles?.figmaStyles?.textStyleName ?? node.rawStyles?.textStyle?.name;
+                if (rawName) {
+                    preferredClassName = `type-${String(rawName).toLowerCase().replace(/[/\s]+/g, "-")}`;
+                }
+            }
+            node.typographyContract = {
+                textStyleRef,
+                resolved: {},
+                codeHint: preferredClassName ? { preferredClassName } : undefined,
+                textAutoResize: rawStyle.textAutoResize
+            };
+            const resolveTypographySlot = (slot, cssFallbackKey, formatFallback) => {
+                const styleBoundVars = safeObject(rawStyle?.boundVariables);
+                const nodeBoundVars = safeObject(node?.boundVariables);
+                // Tier 1: Assigned Style Property (Variable-backed first, then Literal)
+                // This prioritizes the "Style Truth" as requested.
+                if (styleBoundVars[slot]) {
+                    const varArr = safeArray(styleBoundVars[slot]);
+                    const varId = styleBoundVars[slot]?.id || varArr?.[0]?.id;
+                    if (varId) {
+                        const resolved = resolveTokenBinding(varId, model.tokens);
+                        if (resolved)
+                            return resolved;
+                    }
+                }
+                // If no style variable, check for style literal (Semantic Truth)
+                // Only treat it as "Semantic Truth" if it's from a named style.
+                const styleVal = safeObject(rawStyle)[cssFallbackKey];
+                if (styleVal !== undefined && styleVal !== null && rawStyle.name) {
+                    return {
+                        sourceTokenName: "literal",
+                        cssValue: formatFallback(styleVal),
+                        cssVar: "",
+                        canonicalCssVar: "",
+                        valueType: slot === "fontWeight" ? "NUMBER" : (slot === "fontFamily" ? "STRING" : "DIMENSION"),
+                        resolutionPath: ["literal"]
+                    };
+                }
+                // Tier 2: Node-level bound variables (Instance Overrides)
+                if (nodeBoundVars[slot]) {
+                    const varArr = safeArray(nodeBoundVars[slot]);
+                    const varId = nodeBoundVars[slot]?.id || varArr?.[0]?.id;
+                    if (varId) {
+                        const resolved = resolveTokenBinding(varId, model.tokens);
+                        if (resolved)
+                            return resolved;
+                    }
+                }
+                // Tier 3: Rendered fallback measurements (Node raw styles if no style is present)
+                const rawVal = safeObject(rawStyle)[cssFallbackKey];
+                if (rawVal !== undefined && rawVal !== null) {
+                    return {
+                        sourceTokenName: "rendered-fallback",
+                        cssValue: formatFallback(rawVal),
+                        cssVar: "",
+                        canonicalCssVar: "",
+                        valueType: slot === "fontWeight" ? "NUMBER" : (slot === "fontFamily" ? "STRING" : "DIMENSION"),
+                        resolutionPath: ["rendered-fallback"]
+                    };
+                }
+                return undefined;
+            };
+            const fontSize = resolveTypographySlot("fontSize", "fontSize", v => `${v}px`);
+            const lineHeight = resolveTypographySlot("lineHeight", "lineHeightPx", v => `${v}px`);
+            const fontWeight = resolveTypographySlot("fontWeight", "fontWeight", v => `${v}`);
+            const fontFamily = resolveTypographySlot("fontFamily", "fontFamily", v => `${v}`);
+            const letterSpacing = resolveTypographySlot("letterSpacing", "letterSpacing", v => `${v}px`);
+            if (fontSize)
+                node.typographyContract.resolved.fontSize = fontSize;
+            if (lineHeight)
+                node.typographyContract.resolved.lineHeight = lineHeight;
+            if (fontWeight)
+                node.typographyContract.resolved.fontWeight = fontWeight;
+            if (fontFamily)
+                node.typographyContract.resolved.fontFamily = fontFamily;
+            if (letterSpacing)
+                node.typographyContract.resolved.letterSpacing = letterSpacing;
+            // Extract Content Contract
+            const contract = resolveContentContract(node, variantDiffs);
+            node.contentContract = contract;
+            if (contract.propName) {
+                contentSourceMap[node.name || "Text"] = contract.propName;
+            }
+        }
+        if (node.children) {
+            for (const child of safeArray(node.children))
+                populateTreeBindings(child);
+        }
+        if (node.childOverrides) {
+            for (const child of safeArray(node.childOverrides))
+                populateTreeBindings(child);
+        }
+    }
+    if (context.renderTree)
+        populateTreeBindings(context.renderTree);
+    if (context.baseRenderTree)
+        populateTreeBindings(context.baseRenderTree);
+    if (context.childNodes) {
+        for (const child of context.childNodes)
+            populateTreeBindings(child);
+    }
+    // Calculate metadata and add it to the final context
+    const metadata = {
+        schemaVersion: "1.0.0",
+        componentId: component.id,
+        componentName: component.name,
+        sourceSnapshotId: model.version || "unknown",
+        contextHash: "", // filled in next step
+        generatedAt: new Date().toISOString(),
+        dependencyContextHashes: (() => {
+            const hashes = {};
+            for (const dep of dependencies) {
+                // Include "missing" (in model, not yet implemented) as well as "ready" —
+                // the hash tracks what the design snapshot says about this dep, not its build state.
+                if (dep.status === "ready" || dep.status === "missing") {
+                    const depDef = model.components.find((c) => c.id === dep.id || c.figmaNodeId === dep.id);
+                    if (depDef)
+                        hashes[dep.name] = hashComponentDefinition(depDef);
+                }
+            }
+            return hashes;
+        })()
+    };
+    const finalContext = {
+        metadata,
+        ...context
+    };
+    finalContext.metadata.contextHash = calculateContextHash(finalContext);
+    finalContext.contentSourceMap = contentSourceMap;
+    // 8. Build Compressed Context Layer
+    if (finalContext.variantDiffs && finalContext.variantDiffs.length > 0) {
+        finalContext.compressedContext = buildCompressedContext(component, finalContext, model.tokens);
+    }
+    // 9. Update Implementation Hints
+    finalContext.implementationHints = finalContext.implementationHints || {};
+    if (finalContext.compressedContext) {
+        finalContext.implementationHints.notes = finalContext.implementationHints.notes || [];
+        finalContext.implementationHints.notes.push("Prefer compressedContext (Base + Patch) over raw variantDiffs when possible.");
+    }
+    // 10. Derive semanticElement — the recommended HTML root element.
+    // Computed deterministically from name patterns, componentType, and contracts.
+    // Omitted when "div" is the correct default. Rules are first-match-wins.
+    const semanticElement = (() => {
+        const n = component.name.toLowerCase();
+        const ic = finalContext.interactionContract;
+        const ct = component.componentType;
+        const events = ic?.events ?? [];
+        // ── Navigation structures ──────────────────────────────────────────────
+        const hasNavigateAction = events.some((e) => e.action?.type === "navigate" || e.action?.type === "navigate-back");
+        if (/\bnav(igation|bar|rail|menu)?\b/.test(n) || hasNavigateAction)
+            return "nav";
+        if (/\b(tab-?bar|tab-?list|breadcrumb|pagination)\b/.test(n))
+            return "nav";
+        if (/\b(sidebar|side-?nav)\b/.test(n))
+            return "nav";
+        // ── List containers ────────────────────────────────────────────────────
+        if (/\bmenu\b/.test(n) && !/\bmenu-?item\b/.test(n))
+            return "ul";
+        if (/\b(list|item-?list)\b/.test(n) && !/\bdrop/.test(n))
+            return "ul";
+        // ── List items — strong suffix signals only ────────────────────────────
+        // "Menu Item", "List Item", "Dropdown Item", "Select Option" etc.
+        if (/\b(menu-?item|list-?item|dropdown-?item|select-?item|select-?option|option)\b/.test(n))
+            return "li";
+        // ── Explicit button names ──────────────────────────────────────────────
+        if (/\b(btn|button)\b/.test(n))
+            return "button";
+        // ── Tab / accordion triggers ───────────────────────────────────────────
+        // The item/trigger itself is interactive; the container is nav/ul.
+        if (/\btab\b/.test(n) && /\b(item|trigger|tab)\b/.test(n) && !/\bbar\b/.test(n))
+            return "button";
+        if (/\baccordion\b/.test(n) && /\b(item|trigger|header)\b/.test(n))
+            return "button";
+        // ── Form controls — label wraps the native input ───────────────────────
+        // checkbox / radio: root is <label> so clicking anywhere toggles the input.
+        if (/\b(checkbox|radio-?button?)\b/.test(n))
+            return "label";
+        // toggle / switch: stateful binary control, semantically a <button role="switch">
+        if (/\b(toggle|switch)\b/.test(n) && ct === "formControl")
+            return "button";
+        // text inputs / search: root <label> groups the visible field with its label text.
+        if (/\b(input|text-?field|text-?area|search-?bar|search-?field)\b/.test(n))
+            return "label";
+        // ── Interaction-driven atomics ─────────────────────────────────────────
+        // A non-composite component whose primary contract is a click/tap is a button.
+        const hasClickTrigger = events.some((e) => e.trigger?.category === "click" || e.trigger?.category === "pointer-down");
+        if (hasClickTrigger && ct !== "composite")
+            return "button";
+        // ── Document-level landmarks ───────────────────────────────────────────
+        if (/\b(form|sign-?in|sign-?up|login|register)\b/.test(n))
+            return "form";
+        if (/\b(dialog|modal|sheet|drawer|overlay)\b/.test(n))
+            return "dialog";
+        if (/\bheader\b/.test(n))
+            return "header";
+        if (/\bfooter\b/.test(n))
+            return "footer";
+        if (/\b(main|page-?content|content-?area)\b/.test(n))
+            return "main";
+        if (/\baside\b/.test(n))
+            return "aside";
+        if (/\bsection\b/.test(n))
+            return "section";
+        if (/\barticle\b/.test(n))
+            return "article";
+        return undefined; // div is the correct default — no hint needed
+    })();
+    if (semanticElement) {
+        finalContext.implementationHints.semanticElement = semanticElement;
+    }
+    return finalContext;
+}
+//# sourceMappingURL=get-component-context.js.map