canicode 0.10.5 → 0.11.1

package/dist/mcp/server.js

@@ -359,6 +359,41 @@ var RULE_ID_CATEGORY = {
   "non-semantic-name": "semantic",
   "inconsistent-naming-convention": "semantic"
 };
+var RULE_PURPOSE = {
+  // Pixel Critical
+  "no-auto-layout": "violation",
+  "absolute-position-in-auto-layout": "violation",
+  "non-layout-container": "violation",
+  // Responsive Critical
+  "fixed-size-in-auto-layout": "violation",
+  // #403: missing-size-constraint reframed as info-collection. The rule
+  // fires on width chains whose intent is structurally undecidable
+  // (FILL container with no chain-bound ancestor; FIXED component or
+  // instance root). The gotcha question is the primary signal; the
+  // -1 score is just enough to keep the rule visible in
+  // diversity scoring without driving grade swings on its own.
+  "missing-size-constraint": "info-collection",
+  // Code Quality
+  "missing-component": "violation",
+  "detached-instance": "violation",
+  "variant-structure-mismatch": "violation",
+  "deep-nesting": "violation",
+  // Token Management
+  "raw-value": "violation",
+  "irregular-spacing": "violation",
+  // Interaction — gotcha-primary: Figma cannot encode "what happens on
+  // click" or "which states exist" in a way downstream code generation can
+  // consume. Rules fire to trigger the annotation, not to flag a violation.
+  "missing-interaction-state": "info-collection",
+  "missing-prototype": "info-collection",
+  // Semantic
+  "non-standard-naming": "violation",
+  "non-semantic-name": "violation",
+  "inconsistent-naming-convention": "violation"
+};
+function getRulePurpose(ruleId) {
+  return RULE_PURPOSE[ruleId] ?? "violation";
+}
 var RULE_CONFIGS = {
   // ── Pixel Critical ──
   "no-auto-layout": {
@@ -386,8 +421,12 @@ var RULE_CONFIGS = {
     enabled: true
   },
   "missing-size-constraint": {
-    severity: "risk",
-    score: -8,
+    // #403: severity downgraded `risk → missing-info` and score from
+    // -8 → -1 to match the new info-collection purpose. Keeping the
+    // rule enabled (not disabled) so its gotchas still surface in the
+    // survey — see RULE_PURPOSE entry above for the full rationale.
+    severity: "missing-info",
+    score: -1,
     enabled: true
   },
   // ── Code Quality ──
@@ -434,17 +473,22 @@ var RULE_CONFIGS = {
     }
   },
   // ── Interaction ──
+  // #406: both rules are `info-collection` — primary output is the gotcha
+  // annotation, not the score. Severity is `missing-info` so they surface in
+  // the gotcha survey (see `generateGotchaSurvey`) even though the penalty
+  // is minimal. Score stays at -1 so re-enabling `missing-prototype` on
+  // fixtures that lack `interactionDestinations` (#139) cannot swing grades.
   "missing-interaction-state": {
-    severity: "suggestion",
+    severity: "missing-info",
     score: -1,
     // uncalibrated: no metric to validate score (#210), kept at -1 to preserve category visibility
     enabled: true
   },
   "missing-prototype": {
     severity: "missing-info",
-    score: -3,
-    enabled: false
-    // disabled: interactionDestinations data missing from fixtures (#139)
+    score: -1,
+    // #406: info-collection — annotation is primary output; score kept minimal so #139 fixtures don't skew calibration
+    enabled: true
   },
   // ── Semantic ──
   "non-standard-naming": {
@@ -512,7 +556,11 @@ function getConfigsWithPreset(preset) {
 }
 var RULE_ANNOTATION_PROPERTIES = {
   "missing-size-constraint": {
-    default: [{ type: "width" }, { type: "height" }]
+    // #403: width-only — the redesigned rule does not evaluate the
+    // height axis (deferred follow-up). Emitting a `height` annotation
+    // here would mark properties the rule never inspected and confuse
+    // downstream Dev Mode hints.
+    default: [{ type: "width" }]
   },
   "irregular-spacing": {
     bySubType: {
@@ -564,6 +612,14 @@ var RuleRegistry = class {
   register(rule) {
     this.rules.set(rule.definition.id, rule);
   }
+  /**
+   * Remove a rule by ID. Primarily used by tests that register a
+   * throwaway rule and need to restore the registry afterwards. Returns
+   * `true` if the rule was present.
+   */
+  unregister(id) {
+    return this.rules.delete(id);
+  }
   /**
    * Get a rule by ID
    */
@@ -615,14 +671,37 @@ function defineRule(rule) {
   ruleRegistry.register(rule);
   return rule;
 }
+var AcknowledgmentIntentSchema = z.object({
+  field: z.string(),
+  value: z.unknown(),
+  scope: z.enum(["instance", "definition"])
+});
+var AcknowledgmentSceneWriteOutcomeSchema = z.object({
+  result: z.enum([
+    "succeeded",
+    "silent-ignored",
+    "api-rejected",
+    "user-declined-propagation",
+    "unknown"
+  ]),
+  reason: z.string().optional()
+});
 var AcknowledgmentSchema = z.object({
   nodeId: z.string(),
-  ruleId: z.string()
+  ruleId: z.string(),
+  intent: AcknowledgmentIntentSchema.optional(),
+  sceneWriteOutcome: AcknowledgmentSceneWriteOutcomeSchema.optional(),
+  codegenDirective: z.string().optional()
 });
 z.array(AcknowledgmentSchema);
 function normalizeNodeId(id) {
   return id.replace(/-/g, ":");
 }
+z.enum(["page", "component"]);
+var COMPONENT_SCOPE_ROOT_TYPES = /* @__PURE__ */ new Set(["COMPONENT", "COMPONENT_SET", "INSTANCE"]);
+function detectAnalysisScope(rootNode) {
+  return COMPONENT_SCOPE_ROOT_TYPES.has(rootNode.type) ? "component" : "page";
+}
 
 // src/core/engine/rule-engine.ts
 function calculateMaxDepth(node, currentDepth = 0) {
@@ -674,6 +753,7 @@ var RuleEngine = class {
   excludeNamePattern;
   excludeNodeTypes;
   acknowledgments;
+  scopeOverride;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
     this.enabledRuleIds = options.enabledRules ? new Set(options.enabledRules) : null;
@@ -686,6 +766,7 @@ var RuleEngine = class {
         (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
       )
     );
+    this.scopeOverride = options.scope;
   }
   /**
    * Analyze a Figma file and return issues
@@ -702,6 +783,8 @@ var RuleEngine = class {
     }
     const maxDepth = calculateMaxDepth(rootNode);
     const nodeCount = countNodes(rootNode);
+    const scope = this.scopeOverride ?? detectAnalysisScope(rootNode);
+    const rootNodeType = rootNode.type;
     const issues = [];
     const failedRules = [];
     const enabledRules = this.getEnabledRules();
@@ -717,6 +800,8 @@ var RuleEngine = class {
       [],
       0,
       analysisState,
+      scope,
+      rootNodeType,
       void 0,
       void 0
     );
@@ -734,7 +819,8 @@ var RuleEngine = class {
       failedRules,
       maxDepth,
       nodeCount,
-      analyzedAt: (/* @__PURE__ */ new Date()).toISOString()
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      scope
     };
   }
   /**
@@ -752,7 +838,7 @@ var RuleEngine = class {
   /**
    * Recursively traverse the tree and run rules
    */
-  traverseAndCheck(node, file, rules, maxDepth, issues, failedRules, depth, path, ancestorTypes, componentDepth, analysisState, parent, siblings) {
+  traverseAndCheck(node, file, rules, maxDepth, issues, failedRules, depth, path, ancestorTypes, componentDepth, analysisState, scope, rootNodeType, parent, siblings) {
     const nodePath = [...path, node.name];
     const isComponentBoundary = node.type === "COMPONENT" || node.type === "COMPONENT_SET" || node.type === "INSTANCE";
     const currentComponentDepth = isComponentBoundary ? 0 : componentDepth;
@@ -771,7 +857,9 @@ var RuleEngine = class {
       path: nodePath,
       ancestorTypes,
       siblings,
-      analysisState
+      analysisState,
+      scope,
+      rootNodeType
     };
     for (const rule of rules) {
       const ruleId = rule.definition.id;
@@ -818,6 +906,8 @@ var RuleEngine = class {
           childAncestorTypes,
           currentComponentDepth + 1,
           analysisState,
+          scope,
+          rootNodeType,
           node,
           node.children
         );
@@ -1773,7 +1863,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version = "0.10.5";
+var version = "0.11.1";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -1967,6 +2057,10 @@ function buildResultJson(fileName, result, scores, options) {
     const suggestedName = issue.violation.suggestedName;
     return {
       ruleId: issue.violation.ruleId,
+      detection: "rule-based",
+      outputChannel: "score",
+      persistenceIntent: "transient",
+      purpose: getRulePurpose(issue.violation.ruleId),
       ...issue.violation.subType && { subType: issue.violation.subType },
       severity: issue.config.severity,
       nodeId: issue.violation.nodeId,
@@ -1989,6 +2083,7 @@ function buildResultJson(fileName, result, scores, options) {
     fileName,
     nodeCount: result.nodeCount,
     maxDepth: result.maxDepth,
+    scope: result.scope,
     issueCount: result.issues.length,
     acknowledgedCount: scores.summary.acknowledgedCount,
     isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
@@ -2008,11 +2103,14 @@ function buildResultJson(fileName, result, scores, options) {
 }
 z.object({
   ruleId: z.string(),
+  detection: z.literal("rule-based"),
+  outputChannel: z.literal("annotation"),
+  persistenceIntent: z.literal("durable"),
   question: z.string(),
   hint: z.string(),
   example: z.string()
 });
-var GOTCHA_QUESTIONS = {
+var GOTCHA_QUESTION_CONTENT = {
   // ── Pixel Critical (blocking) ──
   "no-auto-layout": {
     ruleId: "no-auto-layout",
@@ -2116,6 +2214,17 @@ var GOTCHA_QUESTIONS = {
     example: "Use PascalCase for all component layers (e.g., CardTitle, CardBody)"
   }
 };
+var GOTCHA_QUESTIONS = Object.fromEntries(
+  Object.entries(GOTCHA_QUESTION_CONTENT).map(([ruleId, content]) => [
+    ruleId,
+    {
+      ...content,
+      detection: "rule-based",
+      outputChannel: "annotation",
+      persistenceIntent: "durable"
+    }
+  ])
+);
 
 // src/core/gotcha/group-and-batch-questions.ts
 var BATCHABLE_RULE_IDS = [
@@ -2184,9 +2293,14 @@ function pushIntoBatch(group, question) {
 var NODE_PATH_SEPARATOR = " > ";
 function generateGotchaSurvey(result, scores, options = {}) {
   const grade = scores.overall.grade;
-  const relevantIssues = result.issues.filter(
-    (issue) => issue.config.severity === "blocking" || issue.config.severity === "risk"
-  );
+  const relevantIssues = result.issues.filter((issue) => {
+    const severity = issue.config.severity;
+    if (severity === "blocking" || severity === "risk") return true;
+    if (severity === "missing-info") {
+      return getRulePurpose(issue.violation.ruleId) === "info-collection";
+    }
+    return false;
+  });
   const deduped = deduplicateSiblingIssues(relevantIssues);
   const sorted = stableSortBySeverity(deduped);
   const mapped = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
@@ -2230,14 +2344,17 @@ function getNodeName(nodePath) {
 function stableSortBySeverity(issues) {
   const blocking = [];
   const risk = [];
+  const missingInfo = [];
   for (const issue of issues) {
     if (issue.config.severity === "blocking") {
       blocking.push(issue);
+    } else if (issue.config.severity === "missing-info") {
+      missingInfo.push(issue);
     } else {
       risk.push(issue);
     }
   }
-  return [...blocking, ...risk];
+  return [...blocking, ...risk, ...missingInfo];
 }
 function mapToQuestion(issue, file) {
   const ruleId = issue.violation.ruleId;
@@ -2254,6 +2371,10 @@ function mapToQuestion(issue, file) {
     nodeId: issue.violation.nodeId,
     nodeName,
     ruleId,
+    detection: template.detection,
+    outputChannel: template.outputChannel,
+    persistenceIntent: template.persistenceIntent,
+    purpose: getRulePurpose(issue.violation.ruleId),
     severity: issue.config.severity,
     question: template.question.replace("{nodeName}", nodeName),
     hint: template.hint,
@@ -3508,7 +3629,9 @@ var EVENTS = {
   // cannot import `core/monitoring` directly, so the event fires through a
   // caller-supplied callback. Define the typed name here so a future consumer
   // has a single place to wire it up.
-  ROUNDTRIP_DEFINITION_WRITE_SKIPPED: `${EVENT_PREFIX}roundtrip_definition_write_skipped`
+  ROUNDTRIP_DEFINITION_WRITE_SKIPPED: `${EVENT_PREFIX}roundtrip_definition_write_skipped`,
+  /** CLI `canicode roundtrip-tally` completed successfully. */
+  ROUNDTRIP_TALLY: `${EVENT_PREFIX}roundtrip_tally`
 };
 
 // src/core/monitoring/capture.ts
@@ -3662,9 +3785,6 @@ function isContainerNode(node) {
 function hasAutoLayout(node) {
   return node.layoutMode !== void 0 && node.layoutMode !== "NONE";
 }
-function hasTextContent(node) {
-  return node.type === "TEXT" || (node.children?.some((c) => c.type === "TEXT") ?? false);
-}
 function hasOverlappingBounds(a, b) {
   const boxA = a.absoluteBoundingBox;
   const boxB = b.absoluteBoundingBox;
@@ -3805,12 +3925,6 @@ function isAbsolutePositionExempt(node) {
   if (isExcludedName(node.name)) return true;
   return false;
 }
-function isSizeConstraintExempt(node, context) {
-  if (node.maxWidth !== void 0) return true;
-  if (context.parent?.maxWidth !== void 0) return true;
-  if (context.depth <= 1) return true;
-  return false;
-}
 function isFixedSizeExempt(node) {
   if (isVisualOnlyNode(node)) return true;
   if (isExcludedName(node.name)) return true;
@@ -3877,21 +3991,21 @@ var fixedSizeMsg = {
   })
 };
 var missingSizeConstraintMsg = {
-  maxWidth: (name, currentWidth) => ({
-    message: `"${name}" uses FILL width (currently ${currentWidth}) without max-width`,
-    suggestion: `Add maxWidth to prevent stretching on large screens`
+  pageContainerUnbound: (name, currentWidth) => ({
+    message: `Container "${name}" uses FILL width (currently ${currentWidth}) and no ancestor defines a width bound`,
+    suggestion: `Decide whether this area should stretch with the screen, or set min/max-width here so the responsive behavior is explicit`
   }),
-  minWidth: (name, currentWidth) => ({
-    message: `"${name}" uses FILL width (currently ${currentWidth}) without min-width`,
-    suggestion: `Add minWidth to prevent collapsing on small screens`
+  pageInstanceFixed: (name, currentWidth) => ({
+    message: `Instance "${name}" has fixed width (${currentWidth}) inside an Auto Layout parent`,
+    suggestion: `Confirm whether this fixed width is intentional \u2014 if not, set the instance to FILL so it follows the parent's layout`
   }),
-  wrap: (name) => ({
-    message: `"${name}" is in a wrap container without min-width`,
-    suggestion: `Add minWidth to control when wrapping occurs`
+  componentFixedByDesign: (name, currentWidth) => ({
+    message: `Component "${name}" has fixed width (${currentWidth}) at its root`,
+    suggestion: `Confirm whether this component is intentionally non-responsive \u2014 otherwise switch root sizing to FILL or set min/max bounds`
   }),
-  grid: (name) => ({
-    message: `"${name}" is in a grid layout without size constraints`,
-    suggestion: `Add min/max-width for proper column sizing`
+  componentFixedByOverride: (name, currentWidth) => ({
+    message: `Instance "${name}" overrides root width to fixed (${currentWidth}); the original component may be FILL`,
+    suggestion: `Confirm whether the fixed-width override is intentional \u2014 if not, restore root sizing to inherit from the component definition`
   })
 };
 var nonLayoutContainerMsg = {
@@ -4183,44 +4297,97 @@ var missingSizeConstraintDef = {
   id: "missing-size-constraint",
   name: "Missing Size Constraint",
   category: "responsive-critical",
-  why: "Without min/max-width, AI has no bounds \u2014 generated code may collapse or stretch indefinitely",
-  impact: "Content becomes unreadable or invisible at extreme screen sizes",
-  fix: "Set min-width and/or max-width so AI can generate proper size constraints"
+  why: "Width sizing without explicit bounds (FIXED root or FILL chained to a bounded ancestor) is structurally indistinguishable from missing information \u2014 AI cannot tell whether the designer intended responsive stretching, a fixed cap, or simply forgot to set min/max",
+  impact: "Generated code either guesses hard-coded widths or omits responsive constraints; either way the runtime layout drifts from the design intent at viewports the designer never explicitly considered",
+  fix: "Answer the gotcha to declare intent (responsive vs. fixed-by-design vs. instance override), then encode the answer in Figma sizing \u2014 FILL/HUG with min/max for responsive bounds, FIXED only when intentionally non-responsive"
 };
-var missingSizeConstraintCheck = (node, context) => {
-  if (!isContainerNode(node) && !hasTextContent(node)) return null;
-  if (!context.parent || !hasAutoLayout(context.parent)) return null;
-  const nodePath = context.path.join(" > ");
-  if (context.parent.layoutWrap === "WRAP" && node.layoutSizingHorizontal === "FILL" && node.minWidth === void 0) {
-    return {
-      ruleId: missingSizeConstraintDef.id,
-      subType: "wrap",
-      nodeId: node.id,
-      nodePath,
-      ...missingSizeConstraintMsg.wrap(node.name)
-    };
-  }
-  if (context.parent.layoutMode === "GRID" && node.layoutSizingHorizontal === "FILL" && node.minWidth === void 0 && node.maxWidth === void 0) {
-    return {
-      ruleId: missingSizeConstraintDef.id,
-      subType: "grid",
-      nodeId: node.id,
-      nodePath,
-      ...missingSizeConstraintMsg.grid(node.name)
-    };
+var CHAIN_BOUND_KEY = "missing-size-constraint:chain-bound";
+function getChainBoundCache(context) {
+  return getAnalysisState(context, CHAIN_BOUND_KEY, () => /* @__PURE__ */ new Map());
+}
+function establishesOwnWidthBound(node) {
+  if (node.layoutSizingHorizontal === "FIXED") return true;
+  if (node.minWidth !== void 0 || node.maxWidth !== void 0) return true;
+  return false;
+}
+function recordChainBound(context, node) {
+  const cache = getChainBoundCache(context);
+  const cached = cache.get(node.id);
+  if (cached !== void 0) return cached;
+  const own = establishesOwnWidthBound(node);
+  const parent = context.parent;
+  const inherited = parent ? cache.get(parent.id) ?? false : false;
+  const result = own || inherited;
+  cache.set(node.id, result);
+  return result;
+}
+function parentChainBound(context) {
+  if (!context.parent) return false;
+  return getChainBoundCache(context).get(context.parent.id) ?? false;
+}
+var PAGE_CONTAINER_FRAME_TYPES = /* @__PURE__ */ new Set(["FRAME", "SECTION"]);
+function formatWidth(node) {
+  return node.absoluteBoundingBox ? `${node.absoluteBoundingBox.width}px` : "unknown";
+}
+function buildViolation(subType, node, context, msg) {
+  return {
+    ruleId: missingSizeConstraintDef.id,
+    subType,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    ...msg
+  };
+}
+function checkComponentScopeRoot(node, context) {
+  if (context.depth !== 0) return null;
+  if (node.layoutSizingHorizontal !== "FIXED") return null;
+  const currentWidth = formatWidth(node);
+  if (context.rootNodeType === "INSTANCE") {
+    return buildViolation(
+      "component-fixed-by-override",
+      node,
+      context,
+      missingSizeConstraintMsg.componentFixedByOverride(node.name, currentWidth)
+    );
   }
-  if (node.layoutSizingHorizontal === "FILL") {
-    if (isSizeConstraintExempt(node, context)) return null;
-    const currentWidth = node.absoluteBoundingBox ? `${node.absoluteBoundingBox.width}px` : "unknown";
-    return {
-      ruleId: missingSizeConstraintDef.id,
-      subType: "max-width",
-      nodeId: node.id,
-      nodePath,
-      ...missingSizeConstraintMsg.maxWidth(node.name, currentWidth)
-    };
+  return buildViolation(
+    "component-fixed-by-design",
+    node,
+    context,
+    missingSizeConstraintMsg.componentFixedByDesign(node.name, currentWidth)
+  );
+}
+function checkPageInstanceFixed(node, context) {
+  if (node.type !== "INSTANCE") return null;
+  if (node.layoutSizingHorizontal !== "FIXED") return null;
+  if (!context.parent || !hasAutoLayout(context.parent)) return null;
+  const currentWidth = formatWidth(node);
+  return buildViolation(
+    "page-instance-fixed",
+    node,
+    context,
+    missingSizeConstraintMsg.pageInstanceFixed(node.name, currentWidth)
+  );
+}
+function checkPageContainerUnbound(node, context) {
+  if (!PAGE_CONTAINER_FRAME_TYPES.has(node.type)) return null;
+  if (node.layoutSizingHorizontal !== "FILL") return null;
+  if (parentChainBound(context)) return null;
+  const currentWidth = formatWidth(node);
+  return buildViolation(
+    "page-container-unbound",
+    node,
+    context,
+    missingSizeConstraintMsg.pageContainerUnbound(node.name, currentWidth)
+  );
+}
+var missingSizeConstraintCheck = (node, context) => {
+  recordChainBound(context, node);
+  if (context.ancestorTypes.includes("INSTANCE")) return null;
+  if (context.scope === "component") {
+    return checkComponentScopeRoot(node, context);
   }
-  return null;
+  return checkPageInstanceFixed(node, context) ?? checkPageContainerUnbound(node, context);
 };
 defineRule({
   definition: missingSizeConstraintDef,
@@ -5010,7 +5177,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     targetNodeId: z.string().optional().describe("Scope analysis to a specific node ID"),
     configPath: z.string().optional().describe("Path to config JSON file for rule overrides"),
     openReport: z.boolean().optional().describe("Open the generated HTML report in the user's browser. Defaults to false \u2014 opt in only when a visible report is the explicit user request (#365). The HTML file is always written to disk regardless."),
-    acknowledgments: z.array(AcknowledgmentSchema).optional().describe("(#371) Pre-resolved [{ nodeId, ruleId }] pairs harvested from canicode-authored Figma annotations (e.g. via the `readCanicodeAcknowledgments` Plugin helper inside a use_figma batch). Matching issues are flagged `acknowledged: true` and contribute half weight to the density score so re-analyze surfaces movement after a roundtrip even under ADR-012's annotate-by-default policy.")
+    acknowledgments: z.array(AcknowledgmentSchema).optional().describe("(#371 / ADR-019) Pre-resolved acknowledgments from canicode-authored Figma annotations (e.g. via readCanicodeAcknowledgments in a use_figma batch). Each entry includes nodeId and ruleId; newer annotations may also carry intent, sceneWriteOutcome, and codegenDirective from a canicode-json fenced block (#444). Matching issues are flagged acknowledged and contribute half weight to the density score."),
+    scope: z.enum(["page", "component"]).optional().describe("(#404) Override analysis scope \u2014 `page` (screen/section where container bounds are required) or `component` (standalone reusable unit where root FILL is the design contract). Defaults to auto-detection from the root node type: `COMPONENT` / `COMPONENT_SET` / `INSTANCE` roots resolve to `component`, everything else to `page`.")
   },
   {
     readOnlyHint: false,
@@ -5018,7 +5186,7 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     openWorldHint: true,
     title: "Analyze Figma Design"
   },
-  async ({ input, token, preset, targetNodeId, configPath, openReport, acknowledgments }) => {
+  async ({ input, token, preset, targetNodeId, configPath, openReport, acknowledgments, scope }) => {
     trackEvent(EVENTS.MCP_TOOL_CALLED, { tool: "analyze" });
     try {
       const { file, nodeId } = await loadFile(input, token);
@@ -5031,7 +5199,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
       const result = analyzeFile(file, {
         configs,
         ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
-        ...acknowledgments && acknowledgments.length > 0 ? { acknowledgments } : {}
+        ...acknowledgments && acknowledgments.length > 0 ? { acknowledgments } : {},
+        ...scope ? { scope } : {}
       });
       const scores = calculateScores(result, configs);
       const figmaToken = token ?? process.env["FIGMA_TOKEN"];
@@ -5098,7 +5267,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     token: z.string().optional().describe("Figma API token (falls back to FIGMA_TOKEN env var)"),
     preset: z.enum(["relaxed", "dev-friendly", "ai-ready", "strict"]).optional().describe("Analysis preset"),
     targetNodeId: z.string().optional().describe("Scope analysis to a specific node ID"),
-    configPath: z.string().optional().describe("Path to config JSON file for rule overrides")
+    configPath: z.string().optional().describe("Path to config JSON file for rule overrides"),
+    scope: z.enum(["page", "component"]).optional().describe("(#404) Override analysis scope \u2014 `page` or `component`. Defaults to auto-detection from the root node type.")
   },
   {
     readOnlyHint: false,
@@ -5106,7 +5276,7 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     openWorldHint: true,
     title: "Gotcha Survey"
   },
-  async ({ input, token, preset, targetNodeId, configPath }) => {
+  async ({ input, token, preset, targetNodeId, configPath, scope }) => {
     trackEvent(EVENTS.MCP_TOOL_CALLED, { tool: "gotcha-survey" });
     try {
       const { file, nodeId } = await loadFile(input, token);
@@ -5118,7 +5288,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
       }
       const result = analyzeFile(file, {
         configs,
-        ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {}
+        ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
+        ...scope ? { scope } : {}
       });
       const scores = calculateScores(result, configs);
       const survey = generateGotchaSurvey(result, scores, { designKey: computeDesignKey(input) });