@fragments-sdk/mcp 0.8.0 → 0.9.0

package/dist/{chunk-6JMX4AMO.js → chunk-YSNIGHNU.js}

@@ -470,14 +470,14 @@ function reciprocalRankFusion(resultSets, k = 60) {
   const scoreMap = /* @__PURE__ */ new Map();
   for (const { results } of resultSets) {
     for (let rank = 0; rank < results.length; rank++) {
-      const result = results[rank];
-      const key = `${result.kind}:${result.name}`;
+      const result2 = results[rank];
+      const key = `${result2.kind}:${result2.name}`;
       const rrfScore = 1 / (k + rank + 1);
       const existing = scoreMap.get(key);
       if (existing) {
         existing.score += rrfScore;
       } else {
-        scoreMap.set(key, { score: rrfScore, kind: result.kind, name: result.name });
+        scoreMap.set(key, { score: rrfScore, kind: result2.kind, name: result2.name });
       }
     }
   }
@@ -521,8 +521,8 @@ async function hybridSearch(query, data, limit = 10, kind, apiKey) {
       const engine = new ComponentGraphEngine2(graph);
       const topComponents = [...keywordResults, ...vectorResults].filter((r) => r.kind === "component").slice(0, 5);
       const neighborSet = /* @__PURE__ */ new Set();
-      for (const result of topComponents) {
-        const neighbors = engine.neighbors(result.name, 1);
+      for (const result2 of topComponents) {
+        const neighbors = engine.neighbors(result2.name, 1);
         for (const n of neighbors.neighbors) {
           if (!neighborSet.has(n.component)) {
             neighborSet.add(n.component);
@@ -609,10 +609,10 @@ function buildBlockComponentFrequency(blocks) {
   return freq;
 }
 function boostByBlockFrequency(results, freq) {
-  for (const result of results) {
-    const count = freq.get(result.name.toLowerCase()) ?? 0;
+  for (const result2 of results) {
+    const count = freq.get(result2.name.toLowerCase()) ?? 0;
     if (count > 0) {
-      result.score += count * BLOCK_BOOST_PER_OCCURRENCE;
+      result2.score += count * BLOCK_BOOST_PER_OCCURRENCE;
     }
   }
   results.sort((a, b) => b.score - a.score);
@@ -843,7 +843,7 @@ var discoverHandler = async (args, ctx) => {
         ctx.indexes.componentIndex ?? void 0
       );
       const allowedNames = new Set(components2.map((component) => component.name));
-      const sortedNames = scored.filter((result) => allowedNames.has(result.name)).map((result) => result.name.toLowerCase());
+      const sortedNames = scored.filter((result2) => allowedNames.has(result2.name)).map((result2) => result2.name.toLowerCase());
       components2 = components2.filter((component) => sortedNames.includes(component.name.toLowerCase())).sort(
         (a, b) => sortedNames.indexOf(a.name.toLowerCase()) - sortedNames.indexOf(b.name.toLowerCase())
       );
@@ -898,12 +898,12 @@ var discoverHandler = async (args, ctx) => {
       "component",
       ctx.config.searchApiKey
     );
-    const filteredSearchResults = searchResults.filter((result) => {
-      const component = componentsByName.get(result.name.toLowerCase());
+    const filteredSearchResults = searchResults.filter((result2) => {
+      const component = componentsByName.get(result2.name.toLowerCase());
       if (!component) return false;
       if (category && !categoryMatches(component.category, category)) return false;
       if (status && component.status !== status) return false;
-      result.score += getRankingBonus(component);
+      result2.score += getRankingBonus(component);
       return true;
     });
     const blockMatches = keywordScoreBlocks(
@@ -919,15 +919,15 @@ var discoverHandler = async (args, ctx) => {
       boostByBlockFrequency(filteredSearchResults, blockFreq);
     }
     const maxScore = filteredSearchResults.length > 0 ? filteredSearchResults[0].score : 0;
-    const scored = filteredSearchResults.map((result) => {
-      const component = componentsByName.get(result.name.toLowerCase());
+    const scored = filteredSearchResults.map((result2) => {
+      const component = componentsByName.get(result2.name.toLowerCase());
       if (!component) return null;
       return {
         component: component.name,
         category: component.category,
         description: component.description,
-        confidence: assignConfidence(result.score, maxScore),
-        reasons: [`Matched via hybrid search (score: ${result.score.toFixed(4)})`],
+        confidence: assignConfidence(result2.score, maxScore),
+        reasons: [`Matched via hybrid search (score: ${result2.score.toFixed(4)})`],
         usage: {
           when: getGuidanceWhen(component).slice(0, 3),
           whenNot: getGuidanceWhenNot(component).slice(0, 2)
@@ -1009,13 +1009,13 @@ var discoverHandler = async (args, ctx) => {
       ]);
       const topBlockScore = blockSearchResults.length > 0 ? blockSearchResults[0].score : 0;
       const relevantBlockResults = blockSearchResults.filter(
-        (result) => result.score >= topBlockScore * 0.3
+        (result2) => result2.score >= topBlockScore * 0.3
       );
       if (relevantBlockResults.length > 0) {
         fullBlocks = (await Promise.all(
-          relevantBlockResults.slice(0, 5).map(async (result) => {
+          relevantBlockResults.slice(0, 5).map(async (result2) => {
             const block = allBlocks.find(
-              (entry) => entry.name.toLowerCase() === result.name.toLowerCase()
+              (entry) => entry.name.toLowerCase() === result2.name.toLowerCase()
             );
             if (!block) return null;
             const imports = await buildImportStatements(
@@ -1043,11 +1043,11 @@ var discoverHandler = async (args, ctx) => {
             tokensByName.set(token.name, cat);
           }
         }
-        for (const result of tokenSearchResults) {
-          const cat = tokensByName.get(result.name);
+        for (const result2 of tokenSearchResults) {
+          const cat = tokensByName.get(result2.name);
           if (cat) {
             if (!fullTokens[cat]) fullTokens[cat] = [];
-            fullTokens[cat].push(result.name);
+            fullTokens[cat].push(result2.name);
           }
         }
         if (Object.keys(fullTokens).length === 0) fullTokens = void 0;
@@ -1172,14 +1172,14 @@ var discoverHandler = async (args, ctx) => {
       search2,
       filteredComponents,
       ctx.indexes.componentIndex ?? void 0
-    ).map((result) => {
+    ).map((result2) => {
       const component = filteredComponents.find(
-        (entry) => entry.name.toLowerCase() === result.name.toLowerCase()
+        (entry) => entry.name.toLowerCase() === result2.name.toLowerCase()
       );
       if (!component) return null;
       return {
         component,
-        score: result.score + getRankingBonus(component)
+        score: result2.score + getRankingBonus(component)
       };
     }).filter(Boolean);
     filteredComponents = scored.sort((a, b) => b.score - a.score).map((entry) => entry.component);
@@ -1248,11 +1248,11 @@ function projectFields(obj, fields) {
   if (!fields || fields.length === 0) {
     return obj;
   }
-  const result = {};
+  const result2 = {};
   for (const field of fields) {
     const parts = field.split(".");
     let source = obj;
-    let target = result;
+    let target = result2;
     for (let i = 0; i < parts.length; i++) {
       const part = parts[i];
       const isLast = i === parts.length - 1;
@@ -1272,7 +1272,7 @@ function projectFields(obj, fields) {
       }
     }
   }
-  return result;
+  return result2;
 }
 
 // src/tools/inspect.ts
@@ -1441,23 +1441,23 @@ var inspectHandler = async (args, ctx) => {
     if (aliasMap[parts[0]]) parts[0] = aliasMap[parts[0]];
     return parts.join(".");
   });
-  let result;
+  let result2;
   if (verbosity === "compact" && !resolvedFields?.length) {
-    result = {
+    result2 = {
       meta: fullResult.meta,
       propsSummary: component.propsSummary,
       metadata: component.metadata
     };
   } else if (verbosity === "full") {
-    result = resolvedFields && resolvedFields.length > 0 ? projectFields(fullResult, resolvedFields) : fullResult;
+    result2 = resolvedFields && resolvedFields.length > 0 ? projectFields(fullResult, resolvedFields) : fullResult;
   } else if (resolvedFields && resolvedFields.length > 0) {
-    result = projectFields(fullResult, resolvedFields);
+    result2 = projectFields(fullResult, resolvedFields);
   } else {
     const { source: _source, ...withoutSource } = fullResult;
-    result = withoutSource;
+    result2 = withoutSource;
   }
   return {
-    content: [{ type: "text", text: JSON.stringify(result) }]
+    content: [{ type: "text", text: JSON.stringify(result2) }]
   };
 };
 
@@ -1876,45 +1876,45 @@ var renderHandler = async (args, ctx) => {
   }
   if (figmaUrl) {
     try {
-      const result = await compareComponent(viewerUrl, {
+      const result2 = await compareComponent(viewerUrl, {
         component: componentName,
         variant: variantName,
         props,
         figmaUrl,
         threshold
       }, ctx.config.fileConfig?.endpoints);
-      if (result.error) {
+      if (result2.error) {
         return {
           content: [{
             type: "text",
-            text: `Compare error: ${result.error}${result.suggestion ? `
-Suggestion: ${result.suggestion}` : ""}`
+            text: `Compare error: ${result2.error}${result2.suggestion ? `
+Suggestion: ${result2.suggestion}` : ""}`
           }],
           isError: true
         };
       }
       const content = [];
-      const summaryText = result.match ? `MATCH: ${componentName} matches Figma design (${result.diffPercentage}% diff, threshold: ${result.threshold}%)` : `MISMATCH: ${componentName} differs from Figma design by ${result.diffPercentage}% (threshold: ${result.threshold}%)`;
+      const summaryText = result2.match ? `MATCH: ${componentName} matches Figma design (${result2.diffPercentage}% diff, threshold: ${result2.threshold}%)` : `MISMATCH: ${componentName} differs from Figma design by ${result2.diffPercentage}% (threshold: ${result2.threshold}%)`;
       content.push({ type: "text", text: summaryText });
-      if (result.diff && !result.match) {
+      if (result2.diff && !result2.match) {
         content.push({
           type: "image",
-          data: result.diff.replace("data:image/png;base64,", ""),
+          data: result2.diff.replace("data:image/png;base64,", ""),
           mimeType: "image/png"
         });
         content.push({
           type: "text",
-          text: `Diff image above shows visual differences (red highlights). Changed regions: ${result.changedRegions?.length ?? 0}`
+          text: `Diff image above shows visual differences (red highlights). Changed regions: ${result2.changedRegions?.length ?? 0}`
         });
       }
       content.push({
         type: "text",
         text: JSON.stringify({
-          match: result.match,
-          diffPercentage: result.diffPercentage,
-          threshold: result.threshold,
-          figmaUrl: result.figmaUrl,
-          changedRegions: result.changedRegions
+          match: result2.match,
+          diffPercentage: result2.diffPercentage,
+          threshold: result2.threshold,
+          figmaUrl: result2.figmaUrl,
+          changedRegions: result2.changedRegions
         })
       });
       return { content };
@@ -1929,15 +1929,15 @@ Suggestion: ${result.suggestion}` : ""}`
     }
   }
   try {
-    const result = await renderComponent(viewerUrl, {
+    const result2 = await renderComponent(viewerUrl, {
       component: componentName,
       props,
       variant: variantName,
       viewport: viewport ?? { width: 800, height: 600 }
     }, ctx.config.fileConfig?.endpoints);
-    if (result.error) {
+    if (result2.error) {
       return {
-        content: [{ type: "text", text: `Render error: ${result.error}` }],
+        content: [{ type: "text", text: `Render error: ${result2.error}` }],
         isError: true
       };
     }
@@ -1945,7 +1945,7 @@ Suggestion: ${result.suggestion}` : ""}`
       content: [
         {
           type: "image",
-          data: result.screenshot.replace("data:image/png;base64,", ""),
+          data: result2.screenshot.replace("data:image/png;base64,", ""),
           mimeType: "image/png"
         },
         {
@@ -1992,16 +1992,16 @@ var fixHandler = async (args, ctx) => {
     };
   }
   try {
-    const result = await fixComponent(viewerUrl, {
+    const result2 = await fixComponent(viewerUrl, {
       component: componentName,
       variant: variantName,
       fixType
     }, ctx.config.fileConfig?.endpoints);
-    if (result.error) {
+    if (result2.error) {
       return {
         content: [{
           type: "text",
-          text: `Fix generation error: ${result.error}`
+          text: `Fix generation error: ${result2.error}`
         }],
         isError: true
       };
@@ -2013,10 +2013,10 @@ var fixHandler = async (args, ctx) => {
           component: componentName,
           variant: variantName ?? "all",
           fixType,
-          patches: result.patches,
-          summary: result.summary,
-          patchCount: result.patches.length,
-          nextStep: result.patches.length > 0 ? `Apply patches using your editor or \`patch\` command, then run ${ctx.toolNames.render} to confirm fixes.` : void 0
+          patches: result2.patches,
+          summary: result2.summary,
+          patchCount: result2.patches.length,
+          nextStep: result2.patches.length > 0 ? `Apply patches using your editor or \`patch\` command, then run ${ctx.toolNames.render} to confirm fixes.` : void 0
         })
       }]
     };
@@ -2061,25 +2061,25 @@ var a11yHandler = async (args, ctx) => {
     };
   }
   try {
-    const result = await auditComponent(viewerUrl, {
+    const result2 = await auditComponent(viewerUrl, {
       component: componentName,
       variant: variantName,
       standard,
       includeFixPatches
     }, ctx.config.fileConfig?.endpoints);
-    if (result.error) {
+    if (result2.error) {
       return {
         content: [{
           type: "text",
-          text: `A11y audit error: ${result.error}`
+          text: `A11y audit error: ${result2.error}`
         }],
         isError: true
       };
     }
     let nextStep;
-    if (result.emptyAudit) {
+    if (result2.emptyAudit) {
       nextStep = `No testable elements found for ${variantName ? `variant "${variantName}"` : componentName}. The variant may not exist or renders no accessible content. Check available variants with ${ctx.toolNames.inspect}("${componentName}").`;
-    } else if (result.passed) {
+    } else if (result2.passed) {
       nextStep = 'All accessibility checks passed. Consider running with standard: "AAA" for enhanced compliance.';
     } else {
       nextStep = `Fix the violations above, then re-run ${ctx.toolNames.a11y} to verify. Use ${ctx.toolNames.fix} for automated fixes.`;
@@ -2091,12 +2091,12 @@ var a11yHandler = async (args, ctx) => {
           component: componentName,
           variant: variantName ?? "all",
           standard,
-          totalViolations: result.results.reduce((sum, r) => sum + r.summary.total, 0),
-          variantsPassingAA: `${result.aaPercent}%`,
-          variantsPassingAAA: `${result.aaaPercent}%`,
-          passed: result.passed,
-          ...result.emptyAudit && { emptyAudit: true },
-          results: result.results,
+          totalViolations: result2.results.reduce((sum, r) => sum + r.summary.total, 0),
+          variantsPassingAA: `${result2.aaPercent}%`,
+          variantsPassingAAA: `${result2.aaaPercent}%`,
+          passed: result2.passed,
+          ...result2.emptyAudit && { emptyAudit: true },
+          results: result2.results,
           nextStep
         })
       }]
@@ -2207,12 +2207,12 @@ function handleGraphTool(args, serializedGraph, blocks, componentNames2) {
         const suggestion = closest ? ` Did you mean "${closest}"?` : "";
         return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
       }
-      const result = engine.impact(args.component, args.maxDepth ?? 3);
+      const result2 = engine.impact(args.component, args.maxDepth ?? 3);
       return {
         text: JSON.stringify({
           mode: "impact",
-          ...result,
-          summary: `Changing ${args.component} affects ${result.totalAffected} component(s) and ${result.affectedBlocks.length} block(s)`
+          ...result2,
+          summary: `Changing ${args.component} affects ${result2.totalAffected} component(s) and ${result2.affectedBlocks.length} block(s)`
         })
       };
     }
@@ -2220,14 +2220,14 @@ function handleGraphTool(args, serializedGraph, blocks, componentNames2) {
       if (!args.component || !args.target) {
         return { text: JSON.stringify({ error: "component and target are required for path mode" }), isError: true };
       }
-      const result = engine.path(args.component, args.target);
+      const result2 = engine.path(args.component, args.target);
       return {
         text: JSON.stringify({
           mode: "path",
           from: args.component,
           to: args.target,
-          ...result,
-          edges: result.edges.map((e) => ({
+          ...result2,
+          edges: result2.edges.map((e) => ({
             source: e.source,
             target: e.target,
             type: e.type
@@ -2306,20 +2306,20 @@ var graphHandler = async (args, ctx) => {
   };
   const data = ctx.data;
   const allNames = componentNames(data.snapshot);
-  const result = handleGraphTool(
+  const result2 = handleGraphTool(
     graphArgs,
     data.graph,
     data.blocks,
     allNames
   );
-  if (result.isError) {
+  if (result2.isError) {
     return {
-      content: [{ type: "text", text: result.text }],
+      content: [{ type: "text", text: result2.text }],
       isError: true
     };
   }
   return {
-    content: [{ type: "text", text: result.text }]
+    content: [{ type: "text", text: result2.text }]
   };
 };
 
@@ -2389,13 +2389,274 @@ var perfHandler = async (args, ctx) => {
   };
 };
 
+// src/tools/spec-govern.ts
+var SEVERITY_WEIGHTS = {
+  critical: 10,
+  serious: 5,
+  moderate: 2,
+  minor: 1
+};
+function isRuleEnabled(rule, defaultEnabled = true) {
+  if (rule === void 0) return defaultEnabled;
+  if (typeof rule === "boolean") return rule;
+  return rule.enabled ?? defaultEnabled;
+}
+function ruleSeverity(rule, fallback) {
+  return typeof rule === "object" && rule?.severity ? rule.severity : fallback;
+}
+function ruleOptions(rule) {
+  return typeof rule === "object" && rule?.options ? rule.options : {};
+}
+function nodeId(node, fallback) {
+  return typeof node.id === "string" ? node.id : `node-${fallback}`;
+}
+function nodeType(node) {
+  return typeof node.type === "string" ? node.type : "_unknown";
+}
+function parentType(type) {
+  const dotIndex = type.indexOf(".");
+  return dotIndex > 0 ? type.slice(0, dotIndex) : type;
+}
+function walkNodes(nodes, visitor) {
+  if (!Array.isArray(nodes)) return;
+  for (const [index, node] of nodes.entries()) {
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+      continue;
+    }
+    const specNode = node;
+    visitor(specNode, index);
+    walkNodes(specNode.children, visitor);
+  }
+}
+function flattenNodes(spec) {
+  const flattened = [];
+  walkNodes(spec.nodes, (node) => flattened.push(node));
+  return flattened;
+}
+function worstSeverity(violations) {
+  const order = ["critical", "serious", "moderate", "minor"];
+  return violations.reduce(
+    (worst, violation) => order.indexOf(violation.severity) < order.indexOf(worst) ? violation.severity : worst,
+    "minor"
+  );
+}
+function result(validator, violations) {
+  return {
+    validator,
+    severity: violations.length > 0 ? worstSeverity(violations) : "minor",
+    passed: violations.length === 0,
+    violations
+  };
+}
+function computeScore(violations) {
+  const penalty = violations.reduce(
+    (sum, violation) => sum + SEVERITY_WEIGHTS[violation.severity],
+    0
+  );
+  return Math.max(0, 100 - penalty);
+}
+function validateComponents(nodes, options) {
+  const rules = options.policy?.rules ?? {};
+  const allowRule = rules["components/allow"];
+  const denyRule = rules["components/deny"];
+  const allowOptions = ruleOptions(allowRule);
+  const denyOptions = ruleOptions(denyRule);
+  const allowed = new Set(
+    (allowOptions.components ?? options.allowedComponents).filter(Boolean)
+  );
+  const denied = new Set(denyOptions.components ?? []);
+  const violations = [];
+  for (const [index, node] of nodes.entries()) {
+    const type = nodeType(node);
+    const parent = parentType(type);
+    if (allowed.size > 0 && isRuleEnabled(allowRule) && !allowed.has(type) && !allowed.has(parent)) {
+      violations.push({
+        nodeId: nodeId(node, index),
+        nodeType: type,
+        rule: "components/allow",
+        severity: ruleSeverity(allowRule, "serious"),
+        message: `Component "${type}" is not in the allowed list`,
+        suggestion: `Use one of the allowed components: ${[...allowed].slice(0, 10).join(", ")}${allowed.size > 10 ? "..." : ""}`
+      });
+    }
+    if (denied.size > 0 && isRuleEnabled(denyRule) && (denied.has(type) || denied.has(parent))) {
+      violations.push({
+        nodeId: nodeId(node, index),
+        nodeType: type,
+        rule: "components/deny",
+        severity: ruleSeverity(denyRule, "serious"),
+        message: `Component "${type}" is blocked by the deny list`,
+        suggestion: `Remove "${type}" or replace it with an allowed alternative`
+      });
+    }
+  }
+  return result("components", violations);
+}
+function isEventHandlerProp(prop) {
+  return /^on[A-Z]/.test(prop);
+}
+function validateSafety(nodes) {
+  const violations = [];
+  const dangerousProps = /* @__PURE__ */ new Set(["dangerouslySetInnerHTML", "innerHTML"]);
+  for (const [index, node] of nodes.entries()) {
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      if (dangerousProps.has(prop)) {
+        violations.push({
+          nodeId: nodeId(node, index),
+          nodeType: nodeType(node),
+          rule: "safety/no-dangerous-props",
+          severity: "critical",
+          message: `Dangerous prop "${prop}" is not allowed`,
+          suggestion: `Remove "${prop}" or use a safe rendering pattern`,
+          prop
+        });
+      }
+      if (isEventHandlerProp(prop) && typeof value === "string") {
+        violations.push({
+          nodeId: nodeId(node, index),
+          nodeType: nodeType(node),
+          rule: "safety/no-string-handlers",
+          severity: "serious",
+          message: `Event handler prop "${prop}" must not be a string`,
+          suggestion: `Remove "${prop}" from generated specs`,
+          prop
+        });
+      }
+    }
+  }
+  return result("safety", violations);
+}
+function hasHardcodedCssValue(value) {
+  if (value.includes("var(")) return false;
+  return /#[0-9a-f]{3,8}\b/i.test(value) || /\b\d+(?:px|rem|em)\b/.test(value);
+}
+function validateTokens(nodes, options) {
+  const rules = options.policy?.rules ?? {};
+  const requireRule = rules["tokens/require-design-tokens"];
+  const prefixRule = rules["tokens/allowed-prefixes"];
+  const requireTokens = isRuleEnabled(requireRule);
+  const defaultTokenPrefix = options.tokenPrefix?.replace(/^--/, "");
+  const allowedPrefixes = ruleOptions(prefixRule).prefixes ?? (defaultTokenPrefix ? [defaultTokenPrefix] : []);
+  const violations = [];
+  for (const [index, node] of nodes.entries()) {
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      if (typeof value !== "string") continue;
+      if (requireTokens && hasHardcodedCssValue(value)) {
+        violations.push({
+          nodeId: nodeId(node, index),
+          nodeType: nodeType(node),
+          rule: "tokens/require-design-tokens",
+          severity: ruleSeverity(requireRule, "moderate"),
+          message: `Hardcoded CSS value "${value}" in prop "${prop}" - use a design token instead`,
+          suggestion: "Use a design token instead of a hardcoded CSS value",
+          prop,
+          rawValue: value
+        });
+      }
+      if (allowedPrefixes.length > 0 && isRuleEnabled(prefixRule, Boolean(options.tokenPrefix))) {
+        const matches = value.matchAll(/var\(--([^)]+)\)/g);
+        for (const match of matches) {
+          const tokenName = match[1];
+          if (allowedPrefixes.some((prefix) => tokenName.startsWith(prefix))) {
+            continue;
+          }
+          violations.push({
+            nodeId: nodeId(node, index),
+            nodeType: nodeType(node),
+            rule: "tokens/allowed-prefixes",
+            severity: ruleSeverity(prefixRule, "moderate"),
+            message: `Token "--${tokenName}" does not use an allowed prefix (${allowedPrefixes.join(", ")})`,
+            suggestion: `Use a token with one of the allowed prefixes: ${allowedPrefixes.map((prefix) => `--${prefix}*`).join(", ")}`,
+            prop,
+            rawValue: value
+          });
+        }
+      }
+    }
+  }
+  return result("tokens", violations);
+}
+function textFromChildren(children) {
+  if (!Array.isArray(children)) return "";
+  return children.map((child) => {
+    if (typeof child === "string") return child;
+    if (typeof child === "object" && child !== null && !Array.isArray(child)) {
+      return textFromChildren(child.children);
+    }
+    return "";
+  }).join(" ").trim();
+}
+function validateA11y(nodes) {
+  const violations = [];
+  for (const [index, node] of nodes.entries()) {
+    const type = nodeType(node);
+    if (!/button/i.test(type)) continue;
+    const props = node.props ?? {};
+    const label = props["aria-label"] ?? props["aria-labelledby"] ?? props.title;
+    const childText = textFromChildren(node.children);
+    if (typeof label === "string" && label.trim().length > 0) continue;
+    if (childText.length > 0) continue;
+    violations.push({
+      nodeId: nodeId(node, index),
+      nodeType: type,
+      rule: "button-name",
+      severity: "serious",
+      message: "Buttons must have discernible text (button-name)",
+      suggestion: "Add visible text or an aria-label"
+    });
+  }
+  return result("a11y", violations);
+}
+function runSpecGovern(spec, options) {
+  const startedAt = Date.now();
+  const nodes = flattenNodes(spec);
+  const results = [
+    validateSafety(nodes),
+    validateComponents(nodes, options),
+    validateTokens(nodes, options),
+    validateA11y(nodes)
+  ];
+  const violations = results.flatMap((entry) => entry.violations);
+  const componentTypes = Array.from(
+    new Set(nodes.map((node) => nodeType(node)))
+  );
+  return {
+    passed: results.every((entry) => entry.passed),
+    score: computeScore(violations),
+    results,
+    metadata: {
+      runner: "mcp",
+      duration: Date.now() - startedAt,
+      nodeCount: nodes.length,
+      componentTypes
+    }
+  };
+}
+function formatVerdict(verdict, format = "summary") {
+  if (format === "json") {
+    return JSON.stringify(verdict, null, 2);
+  }
+  const lines = [];
+  const icon = verdict.passed ? "ok" : "fail";
+  lines.push(`${icon} Governance check: score ${verdict.score}/100`);
+  lines.push("");
+  for (const entry of verdict.results) {
+    const resultIcon = entry.passed ? "ok" : "fail";
+    const count = entry.violations.length;
+    lines.push(`  ${resultIcon} ${entry.validator}: ${count === 0 ? "passed" : `${count} violation(s)`}`);
+    for (const violation of entry.violations) {
+      lines.push(`    - [${violation.severity}] ${violation.nodeType}#${violation.nodeId}: ${violation.message}`);
+      if (violation.suggestion) {
+        lines.push(`      -> ${violation.suggestion}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(`Duration: ${verdict.metadata.duration.toFixed(0)}ms | Nodes: ${verdict.metadata.nodeCount}`);
+  return lines.join("\n");
+}
+
 // src/tools/govern.ts
-import {
-  handleGovernTool,
-  formatVerdict,
-  universal,
-  fragments as fragmentsPreset
-} from "@fragments-sdk/govern";
 var governHandler = async (args, ctx) => {
   const spec = args?.spec;
   if (!spec || typeof spec !== "object") {
@@ -2416,23 +2677,12 @@ var governHandler = async (args, ctx) => {
   const allowedComponents = Object.values(ctx.data.components).map(
     (component) => component.name
   );
-  const tokenPrefix = ctx.data.tokens?.prefix;
-  const basePolicy = tokenPrefix === "fui-" ? { rules: fragmentsPreset().rules } : { rules: universal().rules };
-  basePolicy.rules["components/allow"] = {
-    enabled: true,
-    severity: "serious",
-    options: {
-      components: allowedComponents
-    }
-  };
-  const engineOptions = ctx.data.tokens ? { tokenData: ctx.data.tokens } : void 0;
-  const input = {
-    spec,
-    policy: policyOverrides,
-    format
-  };
   try {
-    const verdict = await handleGovernTool(input, basePolicy, engineOptions);
+    const verdict = runSpecGovern(spec, {
+      allowedComponents,
+      tokenPrefix: ctx.data.tokens?.prefix,
+      policy: policyOverrides
+    });
     const text = format === "summary" ? formatVerdict(verdict, "summary") : JSON.stringify(verdict);
     return {
       content: [{ type: "text", text }],
@@ -2463,32 +2713,80 @@ var governHandler = async (args, ctx) => {
 };
 
 // src/tools/validate-and-fix.ts
-import {
-  formatVerdict as formatVerdict2,
-  fragments as fragmentsPreset2,
-  handleGovernTool as handleGovernTool2,
-  universal as universal2
-} from "@fragments-sdk/govern";
 function classifyComponent(component) {
   if (component.status === "deprecated") return "discouraged";
   if (component.isCanonical && component.tier === "core") return "preferred";
   return "allowed";
 }
 function buildEffectiveComponents(ctx) {
-  const selectionByKey = new Map(
+  const validateFixByKey = new Map(
     (ctx.data.validateFixContext?.components ?? []).map((component) => [
       component.componentKey,
-      component.selection
+      component
     ])
   );
   return Object.entries(ctx.data.components).map(([componentKey, component]) => ({
     component,
-    selection: selectionByKey.get(componentKey) ?? classifyComponent(component)
+    selection: validateFixByKey.get(componentKey)?.selection ?? classifyComponent(component),
+    isActive: validateFixByKey.get(componentKey)?.isActive ?? true,
+    reasons: validateFixByKey.get(componentKey)?.reasons ?? []
   }));
 }
 function cloneSpec(spec) {
   return structuredClone(spec);
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateNodeShape(node, path) {
+  if (!isPlainObject(node)) {
+    return `${path} must be an object`;
+  }
+  if ("id" in node && node.id !== void 0 && typeof node.id !== "string") {
+    return `${path}.id must be a string`;
+  }
+  if ("type" in node && node.type !== void 0 && typeof node.type !== "string") {
+    return `${path}.type must be a string`;
+  }
+  if ("props" in node && node.props !== void 0 && !isPlainObject(node.props)) {
+    return `${path}.props must be an object`;
+  }
+  if ("children" in node && node.children !== void 0) {
+    if (!Array.isArray(node.children)) {
+      return `${path}.children must be an array`;
+    }
+    for (const [index, child] of node.children.entries()) {
+      if (!isPlainObject(child)) continue;
+      const childError = validateNodeShape(
+        child,
+        `${path}.children[${index}]`
+      );
+      if (childError) return childError;
+    }
+  }
+  return null;
+}
+function validateSpecShape(spec) {
+  if (!isPlainObject(spec)) {
+    return "spec must be an object";
+  }
+  if ("root" in spec && spec.root !== void 0 && typeof spec.root !== "string") {
+    return "spec.root must be a string";
+  }
+  if ("metadata" in spec && spec.metadata !== void 0 && !isPlainObject(spec.metadata)) {
+    return "spec.metadata must be an object";
+  }
+  if ("nodes" in spec && spec.nodes !== void 0) {
+    if (!Array.isArray(spec.nodes)) {
+      return "spec.nodes must be an array";
+    }
+    for (const [index, node] of spec.nodes.entries()) {
+      const error = validateNodeShape(node, `spec.nodes[${index}]`);
+      if (error) return error;
+    }
+  }
+  return null;
+}
 function getSelectionNames(effectiveComponents, selection) {
   const selections = Array.isArray(selection) ? selection : [selection];
   return Array.from(
@@ -2497,27 +2795,146 @@ function getSelectionNames(effectiveComponents, selection) {
     )
   );
 }
-function buildBasePolicy(ctx) {
-  const tokenPrefix = ctx.data.tokens?.prefix;
-  const basePolicy = tokenPrefix === "fui-" ? { rules: fragmentsPreset2().rules } : { rules: universal2().rules };
-  const allowedComponents = buildEffectiveComponents(ctx).filter(({ selection }) => selection === "preferred" || selection === "allowed").map(({ component }) => component.name);
-  basePolicy.rules["components/allow"] = {
-    enabled: true,
-    severity: "serious",
-    options: {
-      components: allowedComponents
+function normalizeTokens(value) {
+  return value.toLowerCase().split(/[^a-z0-9]+/g).map((token) => token.trim()).filter((token) => token.length >= 3);
+}
+function buildComponentText(component) {
+  return [
+    component.name,
+    component.category,
+    component.description,
+    component.guidance.usageGuidance,
+    ...component.guidance.when,
+    ...component.guidance.whenNot,
+    ...component.guidance.dos,
+    ...component.guidance.donts
+  ].filter(Boolean).join(" ");
+}
+function rankReplacementCandidates(args) {
+  const nodePropKeys = Object.keys(args.node.props ?? {});
+  const sourcePropKeys = new Set(Object.keys(args.source.component.props ?? {}));
+  const sourceTokens = new Set(normalizeTokens(buildComponentText(args.source.component)));
+  return args.candidates.map((candidate) => {
+    let score = 0;
+    const reasons = [];
+    const candidatePropKeys = new Set(Object.keys(candidate.component.props ?? {}));
+    if (candidate.selection === "preferred") {
+      score += 12;
+      reasons.push("preferred selection");
+    }
+    if (candidate.component.isCanonical) {
+      score += 6;
+      reasons.push("canonical component");
+    }
+    if (candidate.component.tier === "core") {
+      score += 4;
+      reasons.push("core tier");
+    }
+    if (candidate.isActive) {
+      score += 3;
+      reasons.push("active component");
+    }
+    const supportedNodeProps = nodePropKeys.filter(
+      (key) => candidatePropKeys.has(key)
+    );
+    if (supportedNodeProps.length > 0) {
+      score += supportedNodeProps.length * 5;
+      reasons.push(`supports node props: ${supportedNodeProps.join(", ")}`);
     }
-  };
-  return basePolicy;
+    const missingNodeProps = nodePropKeys.filter(
+      (key) => !candidatePropKeys.has(key)
+    );
+    if (missingNodeProps.length > 0) {
+      score -= missingNodeProps.length * 6;
+      reasons.push(`missing node props: ${missingNodeProps.join(", ")}`);
+    }
+    const sharedContractProps = [...sourcePropKeys].filter(
+      (key) => candidatePropKeys.has(key)
+    );
+    if (sharedContractProps.length > 0) {
+      score += sharedContractProps.length * 2;
+      reasons.push(`shares source props: ${sharedContractProps.join(", ")}`);
+    }
+    const candidateTokens = new Set(
+      normalizeTokens(buildComponentText(candidate.component))
+    );
+    const tokenOverlap = [...candidateTokens].filter(
+      (token) => sourceTokens.has(token)
+    );
+    if (tokenOverlap.length > 0) {
+      score += Math.min(tokenOverlap.length, 4);
+      reasons.push(`guidance overlap: ${tokenOverlap.join(", ")}`);
+    }
+    if (candidate.component.parentComponentId && candidate.component.parentComponentId === args.source.component.parentComponentId) {
+      score += 2;
+      reasons.push("matches parent component");
+    }
+    return {
+      name: candidate.component.name,
+      score,
+      reasons
+    };
+  }).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
 }
-async function runGovern(spec, ctx, policyOverrides) {
-  const input = {
-    spec,
-    policy: policyOverrides,
-    format: "json"
-  };
-  const engineOptions = ctx.data.tokens ? { tokenData: ctx.data.tokens } : void 0;
-  return handleGovernTool2(input, buildBasePolicy(ctx), engineOptions);
+function chooseDeterministicCandidate(rankedCandidates) {
+  if (rankedCandidates.length === 0) return null;
+  if (rankedCandidates.length === 1) return rankedCandidates[0].name;
+  const [first, second] = rankedCandidates;
+  if (first.score <= 0) return null;
+  if (first.score - second.score < 4) return null;
+  return first.name;
+}
+function countViolations(verdict) {
+  return verdict.results.reduce(
+    (sum, result2) => sum + result2.violations.length,
+    0
+  );
+}
+function getNextAction(status, replacements, unresolvedAmbiguityCount) {
+  if (status === "pass") return "none";
+  if (status === "fixed") return "apply_fixed_spec";
+  if (status === "partial_fix") return "review_partial_fix";
+  if (unresolvedAmbiguityCount > 0) return "resolve_ambiguities";
+  if (replacements.length > 0) return "review_partial_fix";
+  return "revise_input";
+}
+async function emitValidateAndFixTelemetry(args) {
+  if (!args.ctx.mcp?.server) return;
+  try {
+    await args.ctx.mcp.server.sendLoggingMessage({
+      level: "info",
+      data: JSON.stringify({
+        tool: "validate_and_fix",
+        status: args.status,
+        nextAction: args.nextAction,
+        resolutionPath: args.resolutionPath,
+        evaluation: args.evaluation,
+        attestation: args.attestation
+      }),
+      logger: "fragments-mcp"
+    });
+  } catch {
+  }
+}
+function buildAllowedComponents(ctx) {
+  return buildEffectiveComponents(ctx).filter(({ selection }) => selection === "preferred" || selection === "allowed").map(({ component }) => component.name);
+}
+function runGovern(spec, ctx, policyOverrides) {
+  return runSpecGovern(spec, {
+    allowedComponents: buildAllowedComponents(ctx),
+    tokenPrefix: ctx.data.tokens?.prefix,
+    policy: policyOverrides
+  });
+}
+function walkNodes2(nodes, visitor, path = "nodes") {
+  for (const [index, node] of nodes.entries()) {
+    if (!isPlainObject(node)) continue;
+    const nodeRef = `${path}[${index}]`;
+    visitor(node, nodeRef);
+    if (Array.isArray(node.children)) {
+      walkNodes2(node.children, visitor, `${nodeRef}.children`);
+    }
+  }
 }
 function applyDeterministicReplacements(spec, ctx) {
   const effectiveComponents = buildEffectiveComponents(ctx);
@@ -2538,39 +2955,241 @@ function applyDeterministicReplacements(spec, ctx) {
   const fixedSpec = cloneSpec(spec);
   const nodes = Array.isArray(fixedSpec.nodes) ? fixedSpec.nodes : [];
   const replacements = [];
-  for (const node of nodes) {
-    if (!node.type) continue;
+  const ambiguities = [];
+  walkNodes2(nodes, (node, nodeRef) => {
+    if (!node.type) return;
     const componentEntries = byName.get(node.type) ?? [];
     const component = componentEntries[0];
     if (!component || component.selection !== "discouraged" && component.selection !== "forbidden") {
-      continue;
+      return;
+    }
+    const candidateEntries = (preferredByCategory.get(component.component.category ?? "uncategorized") ?? []).filter((candidate) => candidate !== component.component.name).map(
+      (candidateName) => effectiveComponents.find(
+        (entry) => entry.component.name === candidateName
+      )
+    ).filter((entry) => Boolean(entry));
+    const rankedCandidates = rankReplacementCandidates({
+      source: component,
+      candidates: candidateEntries,
+      node
+    });
+    const replacement = chooseDeterministicCandidate(rankedCandidates);
+    if (!replacement) {
+      if (rankedCandidates.length > 1) {
+        ambiguities.push({
+          nodeId: node.id ?? node.type,
+          nodeRef,
+          from: component.component.name,
+          candidates: rankedCandidates.map((candidate) => candidate.name),
+          rankedCandidates,
+          reason: "ambiguous_preferred_components"
+        });
+      }
+      return;
     }
-    const candidates = (preferredByCategory.get(component.component.category ?? "uncategorized") ?? []).filter((candidate) => candidate !== component.component.name);
-    if (candidates.length !== 1) continue;
-    const replacement = candidates[0];
     replacements.push({
       nodeId: node.id ?? node.type,
       from: component.component.name,
       to: replacement,
-      reason: "deprecated_component"
+      reason: "deprecated_component",
+      mode: "deterministic"
     });
     node.type = replacement;
-  }
+  });
   return {
     fixedSpec,
-    replacements
+    replacements,
+    ambiguities
   };
 }
+function applyReplacementAtRef(spec, nodeRef, replacement) {
+  const nodes = Array.isArray(spec.nodes) ? spec.nodes : [];
+  let applied = false;
+  walkNodes2(nodes, (node, currentRef) => {
+    if (applied || currentRef !== nodeRef) return;
+    node.type = replacement;
+    applied = true;
+  });
+  return applied;
+}
+function supportsFormElicitation(ctx) {
+  const capabilities = ctx.mcp?.clientCapabilities?.elicitation;
+  if (!capabilities) return false;
+  return capabilities.form !== void 0 || capabilities.url === void 0;
+}
+function supportsSampling(ctx) {
+  return Boolean(ctx.mcp?.clientCapabilities?.sampling);
+}
+function getSamplingText(response) {
+  if (Array.isArray(response.content)) {
+    return response.content.find((item) => item.type === "text")?.text;
+  }
+  return response.content.type === "text" ? response.content.text : void 0;
+}
+function buildComponentGuidanceMap(ctx) {
+  return new Map(
+    Object.values(ctx.data.components).map((component) => {
+      const guidance = [];
+      if (component.description) {
+        guidance.push(`description: ${component.description}`);
+      }
+      if (component.guidance.usageGuidance) {
+        guidance.push(`usage: ${component.guidance.usageGuidance}`);
+      }
+      if (component.guidance.dos.length > 0) {
+        guidance.push(`dos: ${component.guidance.dos.join("; ")}`);
+      }
+      if (component.guidance.donts.length > 0) {
+        guidance.push(`donts: ${component.guidance.donts.join("; ")}`);
+      }
+      return [component.name, guidance];
+    })
+  );
+}
+function buildAmbiguityGuidanceLines(candidates, guidanceByName) {
+  return candidates.map((candidate) => {
+    const guidance = guidanceByName.get(candidate) ?? [];
+    return guidance.length > 0 ? `${candidate}: ${guidance.join(" | ")}` : `${candidate}: no additional guidance available`;
+  });
+}
+async function resolveAmbiguitiesWithElicitation(ambiguities, spec, ctx) {
+  if (!ctx.mcp?.server || ambiguities.length === 0) return [];
+  const replacements = [];
+  const guidanceByName = buildComponentGuidanceMap(ctx);
+  for (const ambiguity of ambiguities) {
+    const guidanceLines = buildAmbiguityGuidanceLines(
+      ambiguity.candidates,
+      guidanceByName
+    );
+    const result2 = await ctx.mcp.server.elicitInput({
+      mode: "form",
+      message: [
+        `Fragments found multiple safe replacements for ${ambiguity.from} on node ${ambiguity.nodeId}.`,
+        "Choose the best replacement, or skip this change.",
+        "Candidate guidance:",
+        ...guidanceLines
+      ].join("\n"),
+      requestedSchema: {
+        type: "object",
+        properties: {
+          replacement: {
+            type: "string",
+            title: "Replacement",
+            description: [
+              "Select the best replacement for this node.",
+              ...guidanceLines,
+              "Choose Skip to leave this component unchanged."
+            ].join("\n"),
+            oneOf: [
+              ...ambiguity.candidates.map((candidate) => ({
+                const: candidate,
+                title: candidate
+              })),
+              {
+                const: "__skip__",
+                title: "Skip"
+              }
+            ],
+            default: "__skip__"
+          }
+        },
+        required: ["replacement"]
+      }
+    });
+    if (result2.action !== "accept" || !result2.content || typeof result2.content.replacement !== "string" || result2.content.replacement === "__skip__") {
+      continue;
+    }
+    if (!ambiguity.candidates.includes(result2.content.replacement)) {
+      continue;
+    }
+    if (!applyReplacementAtRef(spec, ambiguity.nodeRef, result2.content.replacement)) {
+      continue;
+    }
+    replacements.push({
+      nodeId: ambiguity.nodeId,
+      from: ambiguity.from,
+      to: result2.content.replacement,
+      reason: "deprecated_component",
+      mode: "elicitation"
+    });
+  }
+  return replacements;
+}
+async function resolveAmbiguitiesWithSampling(ambiguities, spec, ctx) {
+  if (!ctx.mcp?.server || ambiguities.length === 0) return [];
+  const guidanceByName = buildComponentGuidanceMap(ctx);
+  const prompt = [
+    "You are choosing design-system component replacements.",
+    'Return strict JSON only in the form {"choices":[{"nodeId":"...","replacement":"...|__skip__"}]}.',
+    "Only choose from the provided candidates.",
+    "Prefer the option whose guidance best matches the original component intent.",
+    JSON.stringify(
+      {
+        ambiguities: ambiguities.map((ambiguity) => ({
+          nodeId: ambiguity.nodeId,
+          from: ambiguity.from,
+          candidates: ambiguity.candidates.map((candidate) => ({
+            name: candidate,
+            guidance: guidanceByName.get(candidate) ?? []
+          }))
+        }))
+      },
+      null,
+      2
+    )
+  ].join("\n\n");
+  const response = await ctx.mcp.server.createMessage({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: prompt
+        }
+      }
+    ],
+    maxTokens: 600
+  });
+  const text = getSamplingText(response);
+  if (!text) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const replacements = [];
+  for (const choice of parsed.choices ?? []) {
+    if (!choice.nodeId || !choice.replacement || choice.replacement === "__skip__") {
+      continue;
+    }
+    const ambiguity = ambiguities.find((entry) => entry.nodeId === choice.nodeId);
+    if (!ambiguity || !ambiguity.candidates.includes(choice.replacement)) {
+      continue;
+    }
+    if (!applyReplacementAtRef(spec, ambiguity.nodeRef, choice.replacement)) {
+      continue;
+    }
+    replacements.push({
+      nodeId: ambiguity.nodeId,
+      from: ambiguity.from,
+      to: choice.replacement,
+      reason: "deprecated_component",
+      mode: "sampling"
+    });
+  }
+  return replacements;
+}
 function buildSummary(args) {
   const lines = [
     `status: ${args.status}`,
-    `original: ${formatVerdict2(args.originalVerdict, "summary")}`
+    `original: ${formatVerdict(args.originalVerdict, "summary")}`
   ];
   if (args.replacements.length > 0) {
     lines.push(
       `replacements: ${args.replacements.map((item) => `${item.from} -> ${item.to}`).join(", ")}`
     );
-    lines.push(`final: ${formatVerdict2(args.finalVerdict, "summary")}`);
+    lines.push(`final: ${formatVerdict(args.finalVerdict, "summary")}`);
   }
   return lines.join("\n");
 }
@@ -2589,43 +3208,166 @@ var validateAndFixHandler = async (args, ctx) => {
       isError: true
     };
   }
+  const specError = validateSpecShape(spec);
+  if (specError) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: `Invalid spec format: ${specError}. Expected: { nodes: [{ id?: string, type?: string, props?: object, children?: object[] }] }`
+          })
+        }
+      ],
+      isError: true
+    };
+  }
   const policyOverrides = args?.policy;
   const applyFixes = args?.applyFixes !== false;
+  const allowElicitation = args?.allowElicitation !== false;
+  const allowSampling = args?.allowSampling !== false;
   const format = args?.format ?? "json";
+  const startedAt = Date.now();
   try {
     const effectiveComponents = buildEffectiveComponents(ctx);
     const originalVerdict = await runGovern(spec, ctx, policyOverrides);
     let finalVerdict = originalVerdict;
+    let workingSpec;
     let fixedSpec;
     let replacements = [];
+    let ambiguities = [];
+    const resolutionPath = [];
     if (!originalVerdict.passed && applyFixes) {
-      const result = applyDeterministicReplacements(
+      const result2 = applyDeterministicReplacements(
         spec,
         ctx
       );
-      replacements = result.replacements;
-      fixedSpec = result.fixedSpec;
+      replacements = result2.replacements;
+      ambiguities = result2.ambiguities;
       if (replacements.length > 0) {
+        workingSpec = result2.fixedSpec;
+        resolutionPath.push("deterministic");
+      }
+      const unresolvedAmbiguities2 = ambiguities.filter(
+        (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+      );
+      if (unresolvedAmbiguities2.length > 0 && allowElicitation && supportsFormElicitation(ctx)) {
+        workingSpec ??= cloneSpec(spec);
+        const elicitedReplacements = await resolveAmbiguitiesWithElicitation(
+          unresolvedAmbiguities2,
+          workingSpec,
+          ctx
+        );
+        if (elicitedReplacements.length > 0) {
+          resolutionPath.push("elicitation");
+        }
+        replacements.push(...elicitedReplacements);
+      }
+      const remainingAmbiguities = ambiguities.filter(
+        (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+      );
+      if (remainingAmbiguities.length > 0 && allowSampling && supportsSampling(ctx)) {
+        workingSpec ??= cloneSpec(spec);
+        const sampledReplacements = await resolveAmbiguitiesWithSampling(
+          remainingAmbiguities,
+          workingSpec,
+          ctx
+        );
+        if (sampledReplacements.length > 0) {
+          resolutionPath.push("sampling");
+        }
+        replacements.push(...sampledReplacements);
+      }
+      fixedSpec = replacements.length > 0 ? workingSpec : void 0;
+      if (fixedSpec) {
         finalVerdict = await runGovern(fixedSpec, ctx, policyOverrides);
       }
     }
-    const status = originalVerdict.passed ? "pass" : replacements.length > 0 ? "fixed" : "fail";
+    const status = originalVerdict.passed ? "pass" : replacements.length > 0 ? finalVerdict.passed ? "fixed" : "partial_fix" : "fail";
+    const unresolvedAmbiguities = ambiguities.filter(
+      (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+    ).map(({ nodeRef: _nodeRef, ...ambiguity }) => ambiguity);
+    const attestation = {
+      sourceType: ctx.data.snapshot.sourceType,
+      sourceLabel: ctx.data.snapshot.sourceLabel,
+      designSystemName: ctx.data.snapshot.metadata.designSystemName,
+      packageName: ctx.data.snapshot.metadata.packageName,
+      importPath: ctx.data.snapshot.metadata.importPath,
+      catalogRevision: ctx.data.validateFixContext?.catalogRevision ?? ctx.data.snapshot.metadata.revision,
+      catalogUpdatedAt: ctx.data.validateFixContext?.updatedAt ?? ctx.data.snapshot.metadata.updatedAt,
+      policy: {
+        mode: ctx.data.validateFixContext?.policy.mode ?? "embedded",
+        endpoint: ctx.data.validateFixContext?.policy.endpoint,
+        overrideApplied: Boolean(policyOverrides)
+      },
+      clientCapabilities: {
+        sampling: supportsSampling(ctx),
+        samplingTools: Boolean(ctx.mcp?.clientCapabilities?.sampling?.tools),
+        elicitationForm: supportsFormElicitation(ctx),
+        roots: Boolean(ctx.mcp?.clientCapabilities?.roots)
+      },
+      capabilitiesUsed: {
+        deterministic: replacements.some((replacement) => replacement.mode === "deterministic"),
+        elicitation: replacements.some((replacement) => replacement.mode === "elicitation"),
+        sampling: replacements.some((replacement) => replacement.mode === "sampling")
+      }
+    };
+    const evaluation = {
+      durationMs: Date.now() - startedAt,
+      originalViolationCount: countViolations(originalVerdict),
+      finalViolationCount: countViolations(finalVerdict),
+      originalPassed: originalVerdict.passed,
+      finalPassed: finalVerdict.passed,
+      replacementCount: replacements.length,
+      replacementsByMode: {
+        deterministic: replacements.filter((replacement) => replacement.mode === "deterministic").length,
+        elicitation: replacements.filter((replacement) => replacement.mode === "elicitation").length,
+        sampling: replacements.filter((replacement) => replacement.mode === "sampling").length
+      },
+      ambiguityCount: ambiguities.length,
+      unresolvedAmbiguityCount: unresolvedAmbiguities.length,
+      candidateRankingUsed: true
+    };
+    const nextAction = getNextAction(
+      status,
+      replacements,
+      unresolvedAmbiguities.length
+    );
     const payload = {
       status,
+      nextAction,
       applyFixes,
+      allowElicitation,
+      allowSampling,
+      resolutionPath,
       replacements,
       originalVerdict,
       finalVerdict,
       ...fixedSpec ? { fixedSpec } : {},
+      attestation,
+      evaluation,
       preferredComponents: getSelectionNames(
         effectiveComponents,
         "preferred"
       ),
-      discouragedComponents: getSelectionNames(effectiveComponents, [
-        "discouraged",
+      discouragedComponents: getSelectionNames(
+        effectiveComponents,
+        "discouraged"
+      ),
+      forbiddenComponents: getSelectionNames(
+        effectiveComponents,
         "forbidden"
-      ])
+      ),
+      unresolvedAmbiguities
     };
+    await emitValidateAndFixTelemetry({
+      ctx,
+      status,
+      resolutionPath,
+      evaluation,
+      attestation,
+      nextAction
+    });
     return {
       content: [
         {
@@ -2640,19 +3382,22 @@ var validateAndFixHandler = async (args, ctx) => {
       ],
       _meta: {
         status,
+        nextAction,
         replacementCount: replacements.length,
-        passed: finalVerdict.passed
+        passed: finalVerdict.passed,
+        unresolvedAmbiguityCount: unresolvedAmbiguities.length,
+        resolutionPath,
+        catalogRevision: attestation.catalogRevision
       }
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const isSpecError = message.includes("Expected") || message.includes("Required");
     return {
       content: [
         {
           type: "text",
           text: JSON.stringify({
-            error: isSpecError ? `Invalid spec format: ${message}. Expected: { nodes: [{ id: string, type: string, props: object, children?: string[] }] }` : message
+            error: message
           })
         }
       ],
@@ -2764,10 +3509,10 @@ var findingsListHandler = async (args, ctx) => {
   if (args.filePath) params.filePath = String(args.filePath);
   if (args.limit != null) params.limit = Number(args.limit);
   try {
-    const result = await fetchFindings(apiKey, params, cloudUrl);
+    const result2 = await fetchFindings(apiKey, params, cloudUrl);
     return {
-      content: [{ type: "text", text: JSON.stringify(result) }],
-      _meta: { count: result.findings.length }
+      content: [{ type: "text", text: JSON.stringify(result2) }],
+      _meta: { count: result2.findings.length }
     };
   } catch (error) {
     return {
@@ -2800,8 +3545,8 @@ var findingsForFileHandler = async (args, ctx) => {
   }
   const cloudUrl = resolveCloudUrl(ctx);
   try {
-    const result = await fetchFindingsForFile(apiKey, filePath, cloudUrl);
-    const findings = result.findings.filter((f) => f.filePath === filePath);
+    const result2 = await fetchFindingsForFile(apiKey, filePath, cloudUrl);
+    const findings = result2.findings.filter((f) => f.filePath === filePath);
     return {
       content: [
         {
@@ -2995,9 +3740,9 @@ function executeWithMiddleware(middlewares, mCtx, handler) {
 function telemetryMiddleware(logger) {
   return async (mCtx, next) => {
     const start = Date.now();
-    const result = await next();
+    const result2 = await next();
     logger(`${mCtx.toolKey}: ${Date.now() - start}ms`);
-    return result;
+    return result2;
   };
 }
 
@@ -3838,7 +4583,7 @@ Check that your tsconfig.json includes the component directories.`
 var extractorModulePromise = null;
 async function loadExtractorModule() {
   if (!extractorModulePromise) {
-    extractorModulePromise = import("./dist-V7D67NXS.js");
+    extractorModulePromise = import("./dist-BDWAHJ4K.js");
   }
   return extractorModulePromise;
 }
@@ -4122,6 +4867,19 @@ function readPackageName(projectRoot) {
 
 // src/adapters/cloud-catalog.ts
 var DEFAULT_CLOUD_URL2 = "https://app.usefragments.com/api/catalog";
+function mergeDesignSystemMetadata(catalogDesignSystem, contextDesignSystem) {
+  return {
+    name: catalogDesignSystem?.name ?? contextDesignSystem?.name,
+    packageName: catalogDesignSystem?.packageName ?? contextDesignSystem?.packageName ?? null,
+    importPath: catalogDesignSystem?.importPath ?? contextDesignSystem?.importPath ?? catalogDesignSystem?.packageName ?? contextDesignSystem?.packageName ?? null
+  };
+}
+function chooseComponentSource(args) {
+  if (args.contextComponents.length > args.catalogComponents.length) {
+    return args.contextComponents;
+  }
+  return args.catalogComponents;
+}
 var TOKEN_CATEGORY_ALIASES2 = {
   color: ["color", "colors", "accent", "background", "foreground", "danger", "brand"],
   spacing: ["spacing", "space", "padding", "margin", "gap", "inset"],
@@ -4246,8 +5004,8 @@ function mapComponent(component, designSystem) {
     sourceType: "cloud",
     sourcePath: component.sourcePath,
     sourceRepoFullName: component.sourceRepoFullName ?? void 0,
-    packageName: designSystem?.packageName ?? void 0,
-    importPath: designSystem?.importPath ?? designSystem?.packageName ?? void 0,
+    packageName: component.packageName ?? designSystem?.packageName ?? void 0,
+    importPath: component.importPath ?? component.packageName ?? designSystem?.importPath ?? designSystem?.packageName ?? void 0,
     publicRef: component.publicRef,
     publicSlug: component.publicSlug ?? null,
     isCanonical: component.isCanonical ?? false,
@@ -4314,21 +5072,32 @@ var CloudCatalogAdapter = class {
       );
     }
     const raw = await response.json();
+    const validateFixRaw = validateFixResponse && validateFixResponse.ok ? await validateFixResponse.json() : void 0;
+    const designSystem = mergeDesignSystemMetadata(
+      raw.designSystem,
+      validateFixRaw?.content?.designSystem
+    );
+    const sourceComponents = chooseComponentSource({
+      catalogComponents: raw.components ?? [],
+      contextComponents: validateFixRaw?.content?.components ?? []
+    });
     const components = Object.fromEntries(
-      (raw.components ?? []).map((component) => [
+      sourceComponents.map((component) => [
         component.componentKey,
-        mapComponent(component, raw.designSystem)
+        mapComponent(component, designSystem)
       ])
     );
     const tokens = raw.tokens?.flat ? groupTokens(raw.tokens.flat) : void 0;
-    const packageName = raw.designSystem?.packageName ?? void 0;
-    const importPath = raw.designSystem?.importPath ?? raw.designSystem?.packageName ?? void 0;
-    const packageMap = packageName ? Object.fromEntries(
+    const packageName = designSystem?.packageName ?? void 0;
+    const importPath = designSystem?.importPath ?? designSystem?.packageName ?? void 0;
+    const packageMap = Object.fromEntries(
       Object.values(components).map((component) => [
         component.name,
-        packageName
-      ])
-    ) : {};
+        component.importPath ?? component.packageName ?? packageName
+      ]).filter(
+        (entry) => typeof entry[1] === "string" && entry[1].length > 0
+      )
+    );
     const snapshot = validateSnapshot({
       schemaVersion: 1,
       sourceType: "cloud",
@@ -4338,7 +5107,7 @@ var CloudCatalogAdapter = class {
         tokens
       }),
       metadata: {
-        designSystemName: raw.designSystem?.name ?? raw.org.name,
+        designSystemName: designSystem?.name ?? raw.org.name,
         packageName,
         importPath,
         revision: raw.revision,
@@ -4349,9 +5118,7 @@ var CloudCatalogAdapter = class {
       packageMap,
       defaultPackageName: packageName
     });
-    const validateFixContext = validateFixResponse && validateFixResponse.ok ? normalizeValidateFixContext(
-      await validateFixResponse.json()
-    ) : void 0;
+    const validateFixContext = validateFixRaw ? normalizeValidateFixContext(validateFixRaw) : void 0;
     const hydratedComponents = Object.fromEntries(
       Object.entries(snapshot.components).map(([componentId, component]) => [
         componentId,
@@ -4690,7 +5457,8 @@ function createMcpServer(config) {
     },
     {
       capabilities: {
-        tools: { listChanged: true }
+        tools: { listChanged: true },
+        logging: {}
       }
     }
   );
@@ -4728,9 +5496,9 @@ function createMcpServer(config) {
     if (resolveProjectRootPromise) return resolveProjectRootPromise;
     resolveProjectRootPromise = (async () => {
       try {
-        const result = await server.listRoots();
-        if (result.roots?.length > 0) {
-          const rootUri = result.roots[0].uri;
+        const result2 = await server.listRoots();
+        if (result2.roots?.length > 0) {
+          const rootUri = result2.roots[0].uri;
           resolvedRoot = fileURLToPath(rootUri);
           return resolvedRoot;
         }
@@ -4785,12 +5553,19 @@ function createMcpServer(config) {
       data,
       config: mergedConfig,
       indexes: { componentIndex, blockIndex, tokenIndex },
+      mcp: {
+        server,
+        clientCapabilities: server.getClientCapabilities()
+      },
       resolvePackageName: (name2) => {
         if (name2) {
           const pkg = data.packageMap[name2];
           if (pkg) return pkg;
         }
         if (data.defaultPackageName) return data.defaultPackageName;
+        if (data.snapshot.sourceType === "cloud") {
+          return "your-component-library";
+        }
         const root = resolvedRoot ?? config.projectRoot;
         const packageJsonPath = join8(root, "package.json");
         if (existsSync9(packageJsonPath)) {
@@ -4882,4 +5657,4 @@ export {
   startMcpServer,
   createSandboxServer
 };
-//# sourceMappingURL=chunk-6JMX4AMO.js.map
+//# sourceMappingURL=chunk-YSNIGHNU.js.map