canicode 0.12.1 → 0.12.3

package/skills/canicode-roundtrip/helpers.js

@@ -788,6 +788,432 @@ ${footer}`;
     return out;
   }
 
+  // src/core/roundtrip/apply-componentize.ts
+  var COMPONENTIZE_EVENT = "cic_roundtrip_componentize";
+  function isInsideInstance(node) {
+    let current = node.parent;
+    while (current) {
+      if (current.type === "INSTANCE") return true;
+      current = current.parent;
+    }
+    return false;
+  }
+  function isFreeFormParent(node) {
+    const parent = node.parent;
+    if (!parent) return true;
+    const layoutMode = parent["layoutMode"];
+    return layoutMode === void 0 || layoutMode === "NONE";
+  }
+  function resolveFinalName(desired, existing) {
+    if (!existing.has(desired)) {
+      return { finalName: desired, collisionResolved: false };
+    }
+    let counter = 2;
+    while (existing.has(`${desired} ${counter}`)) counter++;
+    return { finalName: `${desired} ${counter}`, collisionResolved: true };
+  }
+  function annotateFallback(node, ruleId, categories, body) {
+    if (!categories) return;
+    upsertCanicodeAnnotation(node, {
+      ruleId,
+      markdown: body,
+      categoryId: categories.flag
+    });
+  }
+  function applyComponentize(options) {
+    const { node, existingComponentNames, ruleId, categories, telemetry } = options;
+    if (isInsideInstance(node)) {
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize skipped \u2014 node is inside an INSTANCE subtree.**
+
+Re-running ${ruleId} componentize on a node inside an instance would either throw or destructively detach the surrounding instance (see roundtrip-protocol.md:286). Move the source frame outside the instance, or detach the parent instance intentionally before componentizing.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "skipped-inside-instance"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "componentize skipped: inside instance",
+        outcome: "skipped-inside-instance"
+      };
+    }
+    if (isFreeFormParent(node)) {
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize skipped \u2014 parent has no Auto Layout.**
+
+Componentizing and swapping siblings under a free-form parent would require manual coordinate carryover that can mangle layout silently (ADR-023 decision A). Wrap the duplicates in an Auto Layout frame first, then re-run the roundtrip.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "skipped-free-form-parent"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "componentize skipped: free-form parent",
+        outcome: "skipped-free-form-parent"
+      };
+    }
+    const desiredName = typeof node.name === "string" ? node.name : "Component";
+    const { finalName, collisionResolved } = resolveFinalName(
+      desiredName,
+      existingComponentNames
+    );
+    const create = figma.createComponentFromNode;
+    if (typeof create !== "function") {
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize skipped \u2014 \`figma.createComponentFromNode\` unavailable.**
+
+The Plugin API host did not expose the Create component primitive in this session. The FRAME has been flagged so the next roundtrip can retry.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: "createComponentFromNode-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "componentize skipped: createComponentFromNode unavailable",
+        outcome: "error"
+      };
+    }
+    try {
+      const created = create.call(figma, node);
+      created.name = finalName;
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "componentized",
+        nameCollisionResolved: collisionResolved
+      });
+      const result = {
+        icon: "\u2705",
+        label: collisionResolved ? `componentized as "${finalName}" (renamed from collision)` : `componentized as "${finalName}"`,
+        outcome: "componentized",
+        newComponentId: created.id,
+        finalName
+      };
+      if (collisionResolved) result.nameCollisionResolved = true;
+      return result;
+    } catch (e) {
+      const msg = String(e?.message ?? e);
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize failed \u2014 \`createComponentFromNode\` threw.**
+
+Error: \`${msg}\`. The FRAME has been flagged so the designer can inspect the structure (locked layer, unsupported child mix, etc.) before the next roundtrip pass.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: msg
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `componentize failed: ${msg}`,
+        outcome: "error"
+      };
+    }
+  }
+
+  // src/core/roundtrip/apply-replace-with-instance.ts
+  var REPLACE_EVENT = "cic_roundtrip_replace_with_instance";
+  function isFreeFormParent2(parent) {
+    if (!parent) return true;
+    const layoutMode = parent["layoutMode"];
+    return layoutMode === void 0 || layoutMode === "NONE";
+  }
+  function annotateFallback2(node, ruleId, categories, body) {
+    if (!node || !categories) return;
+    upsertCanicodeAnnotation(node, {
+      ruleId,
+      markdown: body,
+      categoryId: categories.flag
+    });
+  }
+  function isComponentLike(type) {
+    return type === "COMPONENT" || type === "COMPONENT_SET";
+  }
+  async function applyReplaceWithInstance(options) {
+    const { mainComponentId, targetNodeId, ruleId, categories, telemetry } = options;
+    const [target, main] = await Promise.all([
+      figma.getNodeByIdAsync(targetNodeId),
+      figma.getNodeByIdAsync(mainComponentId)
+    ]);
+    if (!target) {
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "target-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace skipped: target node ${targetNodeId} missing`,
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (!main) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 main component \`${mainComponentId}\` not found.**
+
+The componentize step (delta 1) likely failed earlier in this batch, or the main was deleted between componentize and swap. The FRAME has been flagged so the next roundtrip pass can re-derive the group.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "main-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace skipped: main ${mainComponentId} missing`,
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (!isComponentLike(main.type)) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 \`${mainComponentId}\` is not a COMPONENT.**
+
+Resolved to a \`${main.type}\` node. Phase 3's swap step requires the main to be a \`COMPONENT\` or \`COMPONENT_SET\`. Check that componentize ran cleanly on the source frame before this call.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "main-not-component",
+        resolvedType: main.type
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace skipped: main is ${main.type}, not COMPONENT`,
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (target.id === main.id) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 target and main are the same node.**
+
+This usually means the componentize source was passed in the swap set by mistake. The componentize source becomes the main; only the remaining sibling FRAMEs should be swapped.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "target-is-main"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: target equals main",
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    const parent = target.parent;
+    if (!parent) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 target has no parent.**
+
+Cannot insert a new instance for an orphaned node. The FRAME has been flagged; no swap performed.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "no-parent"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: no parent",
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (isFreeFormParent2(parent)) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 parent has no Auto Layout.**
+
+Swapping a sibling FRAME with an instance under a free-form parent would require explicit coordinate carryover that can mangle layout silently (ADR-023 decision A). Wrap the duplicates in an Auto Layout frame first, then re-run the roundtrip.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-free-form-parent"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: free-form parent",
+        outcome: "skipped-free-form-parent"
+      };
+    }
+    const create = main.createInstance;
+    if (typeof create !== "function") {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 \`createInstance\` unavailable on main.**
+
+The Plugin API host did not expose \`createInstance\` on the resolved main (\`${main.type}\`). The FRAME has been flagged so the next roundtrip can retry once the host catches up.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: "createInstance-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: createInstance unavailable",
+        outcome: "error"
+      };
+    }
+    try {
+      const instance = create.call(main);
+      const siblings = parent.children ?? [];
+      const idx = siblings.findIndex((s) => s.id === target.id);
+      const insert = parent.insertChild;
+      const append = parent.appendChild;
+      if (idx >= 0 && typeof insert === "function") {
+        insert.call(parent, idx, instance);
+      } else if (typeof append === "function") {
+        append.call(parent, instance);
+      } else {
+        throw new Error(
+          "parent exposes neither insertChild nor appendChild \u2014 cannot insert instance"
+        );
+      }
+      if (typeof target.remove === "function") {
+        target.remove();
+      } else {
+        throw new Error("target node missing `remove` \u2014 cannot detach old FRAME");
+      }
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "replaced"
+      });
+      return {
+        icon: "\u2705",
+        label: `replaced with instance of "${main.name}"`,
+        outcome: "replaced",
+        newInstanceId: instance.id
+      };
+    } catch (e) {
+      const msg = String(e?.message ?? e);
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace failed \u2014 Plugin API threw.**
+
+Error: \`${msg}\`. The FRAME has been flagged so the designer can inspect (locked layer, parent restrictions, etc.) before the next roundtrip pass.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: msg
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace failed: ${msg}`,
+        outcome: "error"
+      };
+    }
+  }
+
+  // src/core/roundtrip/apply-group-componentize.ts
+  function summarizeReplaceCounts(results) {
+    const total = results.length;
+    if (total === 0) return "";
+    const replaced = results.filter((r) => r.outcome === "replaced").length;
+    const reasons = [];
+    const freeForm = results.filter(
+      (r) => r.outcome === "skipped-free-form-parent"
+    ).length;
+    const prereq = results.filter(
+      (r) => r.outcome === "skipped-prereq-missing"
+    ).length;
+    const error = results.filter((r) => r.outcome === "error").length;
+    if (freeForm > 0) reasons.push(`${freeForm} free-form parent`);
+    if (prereq > 0) reasons.push(`${prereq} prereq missing`);
+    if (error > 0) reasons.push(`${error} error`);
+    const tail = reasons.length > 0 ? ` (${reasons.join(", ")})` : "";
+    return `swapped ${replaced}/${total} siblings${tail}`;
+  }
+  async function applyGroupComponentize(options) {
+    const { question, existingComponentNames, categories, telemetry } = options;
+    const members = question.groupMembers;
+    const firstId = members[0];
+    if (firstId === void 0) {
+      return {
+        outcome: "missing-first-member",
+        replaceResults: [],
+        summary: "group componentize skipped: no members in group"
+      };
+    }
+    const firstNode = await figma.getNodeByIdAsync(firstId);
+    if (!firstNode) {
+      return {
+        outcome: "missing-first-member",
+        replaceResults: [],
+        summary: `group componentize skipped: first member ${firstId} not found`
+      };
+    }
+    const componentizeResult = applyComponentize({
+      node: firstNode,
+      existingComponentNames,
+      ruleId: question.ruleId,
+      ...categories !== void 0 ? { categories } : {},
+      ...telemetry !== void 0 ? { telemetry } : {}
+    });
+    if (componentizeResult.outcome !== "componentized") {
+      return {
+        outcome: "componentize-failed",
+        componentizeResult,
+        replaceResults: [],
+        summary: `group componentize skipped: ${componentizeResult.label}`
+      };
+    }
+    const newComponentId = componentizeResult.newComponentId;
+    const swapTargets = members.slice(1);
+    const replaceResults = [];
+    for (const targetId of swapTargets) {
+      const r = await applyReplaceWithInstance({
+        mainComponentId: newComponentId,
+        targetNodeId: targetId,
+        ruleId: question.ruleId,
+        ...categories !== void 0 ? { categories } : {},
+        ...telemetry !== void 0 ? { telemetry } : {}
+      });
+      replaceResults.push(r);
+    }
+    const swapSummary = summarizeReplaceCounts(replaceResults);
+    const finalName = componentizeResult.finalName ?? "(unnamed)";
+    const summary = swapSummary.length > 0 ? `componentized "${finalName}", ${swapSummary}` : `componentized "${finalName}"`;
+    return {
+      outcome: "componentized-and-swapped",
+      componentizeResult,
+      replaceResults,
+      summary
+    };
+  }
+
   // src/core/roundtrip/remove-canicode-annotations.ts
   var LEGACY_CANICODE_PREFIX = "**[canicode]";
   function isCanicodeAnnotation(annotation, categories) {
@@ -813,7 +1239,10 @@ ${footer}`;
 
   exports.applyAutoFix = applyAutoFix;
   exports.applyAutoFixes = applyAutoFixes;
+  exports.applyComponentize = applyComponentize;
+  exports.applyGroupComponentize = applyGroupComponentize;
   exports.applyPropertyMod = applyPropertyMod;
+  exports.applyReplaceWithInstance = applyReplaceWithInstance;
   exports.applyUnmappedComponentOptOut = applyUnmappedComponentOptOut;
   exports.applyWithInstanceFallback = applyWithInstanceFallback;
   exports.buildIntentionallyUnmappedAnnotationBody = buildIntentionallyUnmappedAnnotationBody;

package/skills/cursor/canicode-roundtrip/SKILL.md

@@ -25,6 +25,8 @@ disable-model-invocation: false
 
 **Channel contrast:** **`canicode-gotchas`** stores answers in **local** `.claude/skills/canicode-gotchas/SKILL.md` only (memo — no Figma write). **`canicode-roundtrip`** (**this skill**) writes to the **Figma canvas** via Plugin API (`use_figma`). If you only need Q&A persistence, use gotchas; if you need annotations and fixes on the file, use roundtrip.
 
+**Output language (#546):** Detect the user's conversation language from their messages in **this** session. When the user is conversing in a non-English language (e.g. Korean, Japanese, Spanish), every human-readable line you render — Step 1 design summary, Step 2 grade banner, Step 3 question / `Hint:` / `Example:` / batch shared-prompt wording, Step 4 apply summary, Step 5 wrap-up rubric, Step 6 handoff line, Step 7 prompts and wrap-up — must be rendered in that language. Identifiers stay English: `ruleId`, `nodeId`, severity label in brackets, marker glyphs (📝/✅/🌐/⏭️), the upsert-section markdown scaffolding. The full localization scope and exclusions are in Step 3's preamble below. Default to English only when the user's language is genuinely ambiguous (and ask once).
+
 Orchestrate the full design-to-code roundtrip: analyze a Figma design for readiness, collect gotcha answers for problem areas, **apply fixes directly to the Figma design** via `use_figma`, re-analyze to verify gotchas were captured, then generate code. Success means **gotchas answered and carried into annotations / writes** — not a numeric grade bump (analyze still reports grade for continuity; roundtrip success is lint-first).
 
 ## Prerequisites
@@ -159,6 +161,8 @@ Detect the user's conversation language from their recent messages in **this** s
 
 Iterate `groupedQuestions.groups[].batches[]` and branch on `batch.batchMode` (`"safe"` — one uniform answer, `"opt-in"` — shared answer offered as default with per-node `split` override (#426), `"none"` — single-question). Instance notes, batch prompt templates per mode, replicas, split/skip/n/a, "skip remaining" early-exit affordance (surface before the first batch, re-surface every 3rd), stdin upsert — **[Appendix Step 3](https://github.com/let-sunny/canicode/blob/main/docs/roundtrip-protocol.md#appendix--step-3-grouped-survey-groupedquestions)**. Per ADR-016, do not re-implement grouping.
 
+**Pacing — one batch per message (#545):** Render exactly **one** batch per assistant message and **wait for the user's reply** before rendering the next. A `safe` / `opt-in` multi-instance batch is still **one** batch — render the shared prompt once and wait. Do **not** dump multiple batches in a single message and ask "Reply with answers numbered 1–N"; that defeats the paced Q&A UX. The total-batch count and the `skip remaining` affordance are surfaced once before batch 1 (and re-surfaced every 3rd batch per the appendix); they are not a license to bulk-render. The only exception is `skip remaining` — when the user invokes it, mark all unanswered batches as skipped and proceed straight to Step 4.
+
 
 ### Step 4: Apply gotcha answers to Figma design
 
@@ -257,6 +261,92 @@ The name must match **the variable's `name` field exactly** — including any sl
 
 Instance-child guard and per-rule prompts — **[Appendix Strategy B](https://github.com/let-sunny/canicode/blob/main/docs/roundtrip-protocol.md#appendix--strategy-b-structural-modification)**. Decline / guard → Strategy C annotation.
 
+##### Strategy B group componentize — Phase 3 (`missing-component:structure-repetition`)
+
+When `applyStrategy === "structural-mod"` AND `question.ruleId === "missing-component"` AND `question.subType === "structure-repetition"` AND `question.groupMembers` is set, the question represents a fingerprint group of N FRAMEs the user can componentize-and-swap in one batch. The group spans both same-parent siblings and cross-parent matches found by the Stage 3 scope-wide pass (#557). Render the per-question prompt with the **group size** explicitly so the designer knows the scope before answering. Substitute `{nodeName}` with `question.nodeName` and `{others}` with `question.groupMembers.length - 1` (the count excluding the first member that becomes the new component); render in the user's session language:
+
+- Korean: `> "{nodeName}" 외에 동일한 구조의 frame이 {others}개 더 있습니다 (총 {others + 1}개). 모두 컴포넌트화 할까요? (yes/no)`
+- English: `> "{nodeName}" and {others} other frame(s) share the same structure ({others + 1} total). Componentize the whole group? (yes/no)`
+
+On `yes`, compute the file-wide existing component name set once (decision C uses this for the suffix), then call the group orchestrator. On `no` / `skip`, drop the question without writing anything; the gotcha state is captured in the SKILL's section markdown either way.
+
+<!-- adr-016-ack: existingComponentNames computed via figma.root API; orchestration loop lives in applyGroupComponentize -->
+```javascript
+const existingComponentNames = new Set(
+  figma.root
+    .findAllWithCriteria({ types: ["COMPONENT", "COMPONENT_SET"] })
+    .map((c) => c.name)
+);
+const result = await CanICodeRoundtrip.applyGroupComponentize({
+  question: { ruleId: question.ruleId, groupMembers: question.groupMembers },
+  existingComponentNames,
+  categories,
+});
+// result.summary — e.g. `componentized "Card", swapped 3/4 siblings (1 free-form parent)`
+// result.outcome — `componentized-and-swapped` | `componentize-failed` | `missing-first-member`
+//
+// Step 4 report counter mapping (bump ONCE per primitive call, not once per
+// outcome bucket — counters track work performed, not aggregate verdicts):
+//   componentize step:
+//     componentizeResult.outcome === "componentized" → resolved (+1)
+//     componentizeResult.outcome === "skipped-*" or "error" → annotated (+1)
+//   each replace step (iterate result.replaceResults):
+//     replaceResult.outcome === "replaced" → resolved (+1)
+//     replaceResult.outcome === "skipped-*" or "error" → annotated (+1)
+//   missing-first-member → skipped (+1) and no further bumps
+```
+
+Notes:
+- **Free-form parents are refused per ADR-023 decision A.** When the group's parent (or any swap-target's parent) has no Auto Layout, the relevant primitive annotates the source FRAME with a "wrap in Auto Layout first" hint and skips the write. The summary string surfaces the count (`(1 free-form parent)`) so the designer sees the partial outcome at a glance.
+- **Name collision auto-suffixes per ADR-023 decision C** (`Card 2`, `Card 3`, …). The orchestrator passes `existingComponentNames` to the componentize step which resolves the suffix and reports the rename in `result.componentizeResult.finalName`.
+- **Per-member opt-out is not yet wired** — the orchestrator treats `groupMembers` as canonical. If the designer wants to exclude a specific member, that is currently a manual pre-edit (delete the entry from the question payload before calling) or a follow-up enhancement.
+- **No replica fan-out.** Stage 3 questions never carry `replicaNodeIds` (the `#356` instance-child dedupe applies to single-node violations, not group-shaped ones). Iterate `groupMembers` instead.
+
+###### Code Connect handoff for the new component (Phase 3 delta 5, optional)
+
+When `result.outcome === "componentized-and-swapped"` AND `result.componentizeResult.newComponentId` is set, the new component is a candidate for a Code Connect mapping so future roundtrips reuse the just-generated code instead of regenerating markup. This mirrors the Workflow 1 (#509) Step 7 close-out — same pre-check, same MCP tools, just sharing the closing question.
+
+Per ADR-023 decision E this is **silent skip + one-line pointer** when prereqs are absent — Phase 3 does not own onboarding (Workflow 1 / #509 does). The check is the same `npx canicode doctor --figma-url <url>` already run at Step 1.5 (`prereqs.codeConnectReady` cached on the session) — do **not** re-run doctor here. If prereqs were missing, surface ONE line and move on:
+
+> Code Connect 미설정이라 매핑 단계는 건너뜁니다. Workflow 1 (`/canicode-roundtrip <component-url>`)로 setup하면 다음부터 자동 매핑됩니다.
+
+(English: `> Code Connect not configured — skipping mapping. Run Workflow 1 (\`/canicode-roundtrip <component-url>\`) to set it up; subsequent roundtrips map automatically.`)
+
+When prereqs are ready, ask the satisfaction prompt and, on `yes`, register the mapping:
+
+```javascript
+// 1. Probe the just-componentized main for an existing mapping (idempotency)
+const existing = await mcp__figma__get_code_connect_map({
+  componentId: result.componentizeResult.newComponentId,
+});
+if (existing) {
+  // Already mapped — surface and move on. Do not overwrite without consent.
+  return;
+}
+
+// 2. Ask the user (one line, in session language)
+//    Korean: "이 새 component를 Code Connect 매핑으로 등록할까요? (yes/no)"
+//    English: "Register this new component with Code Connect? (yes/no)"
+
+// 3. On yes, fetch suggestions and register the user's choice
+const suggestions = await mcp__figma__get_code_connect_suggestions({
+  componentId: result.componentizeResult.newComponentId,
+  componentName: result.componentizeResult.finalName,
+});
+// Render suggestions to the user; on confirmation:
+await mcp__figma__add_code_connect_map({
+  componentId: result.componentizeResult.newComponentId,
+  codePath: chosenSuggestion.path,        // e.g. "src/components/Card.tsx"
+  codeName: chosenSuggestion.exportName,  // e.g. "Card"
+});
+await mcp__figma__send_code_connect_mappings();
+```
+
+Notes:
+- **Inherits Step 1.5 prereq check.** Do not re-invoke `canicode doctor` — the cached result from Step 1.5 already covers `figma.config.json` + `@figma/code-connect` install + Figma publish status. Skipping the re-check keeps the close-out fast and avoids a second Figma round-trip.
+- **No suggestions match → still surface the option.** When `get_code_connect_suggestions` returns empty, ask the user for a manual `codePath` + `codeName` (one prompt, optional). Skipping is always valid — the new component remains unmapped and Workflow 1 can register it later.
+- **Wraps the Step 4 apply line** with one extra outcome marker: `+ Code Connect: Card → src/components/Card.tsx` on success, `+ Code Connect: skipped (prereq missing)` or `+ Code Connect: skipped (user declined)` on the two skip paths. Counts as part of the Phase 3 group's overall result for Step 5 tally — no new counter, just an annotation appended to the existing line.
+
 #### Strategy C: Annotation — record on the design for designer reference
 
 Rules with `applyStrategy === "annotation"` cannot be auto-fixed via Plugin API. Add the gotcha answer as a Figma annotation so designers see it in Dev Mode. Use the helper — it handles the D1 mutex, D2 in-place upsert, and D4 category assignment. When `question.replicaNodeIds` is present (#356), iterate the merged set so every replica instance gets the annotation:
@@ -398,6 +488,8 @@ The response now carries:
 
 Under ADR-012's annotate-by-default policy, many writes become 📝 annotations. Treat **issues-delta + `acknowledgedCount`** as the headline success signal — not grade movement (#423).
 
+**Grade-movement attribution (#547):** When the wrap-up shows a grade jump (e.g. `C+ → B+`), attribute the move to the resolved bucket (`✅` / `🔧` / `🌐`) explicitly so the user does not mis-infer that 📝 annotations contributed. Per ADR-012, annotations are zero-score by design — they carry context into code-gen but never move the grade. When `tally.Y > 0` (any 📝 annotated count), include a one-liner near the bucket tally clarifying this. Templates below already include the line; do not omit it.
+
 **Tally** — call `CanICodeRoundtrip.computeRoundtripTally` with the structured `stepFourReport` you assembled in Step 4 and the re-analyze response from Step 5b. The helper handles every count derivation (`N = X + Y + Z + W`, `V_open = V - V_ack`) and validates that `acknowledgedCount` cannot exceed `issueCount`. Render the returned `{ X, Y, Z, W, N, V, V_ack, V_open }` straight into the templates below — do **not** re-derive any of these from the Step 4 prose:
 
 ```javascript
@@ -424,6 +516,8 @@ If Step 4 produced no `stepFourReport` (e.g. user skipped every question, or no
     —
     V issues remaining (unresolved gotchas + non-actionable rules)
 
+  *(When Y > 0)* 📝 annotations carry context into code-gen but do not change the grade — that is by design (ADR-012). Any grade movement comes from the ✅ / 🔧 / 🌐 buckets above.
+
   Ready for code generation. *(Optional:) Report still shows grade **{grade}** — informational only.*
   ```
 - Clean up canicode annotations on fixed nodes via `use_figma`. Use the bundled `removeCanicodeAnnotations` helper — it gates on **categoryId** (the durable canicode-side identifier — the body no longer carries a `[canicode]` prefix per #353), includes `legacyAutoFix` if `ensureCanicodeCategories` returned it (pre-#355 `canicode:auto-fix` sweep), and also matches the legacy `**[canicode]` body prefix as a secondary marker for entries on files that have not been re-roundtripped yet. The match logic lives in `src/core/roundtrip/remove-canicode-annotations.ts` with vitest coverage so prose stays ADR-016-compliant:
@@ -456,6 +550,8 @@ for (const id of nodeIds) {
        ↳ V_ack acknowledged via canicode annotations (carried into code-gen)
        ↳ V_open unaddressed (no annotation — your follow-up backlog)
 
+  *(When Y > 0)* 📝 annotations carry context into code-gen but do not change the grade — that is by design (ADR-012). Any grade movement comes from the ✅ / 🔧 / 🌐 buckets above.
+
   Proceed to code generation with remaining context? *(Optional footnote: report grade **{grade}**.)*
   ```
 
@@ -478,6 +574,8 @@ Stopped — N issues addressed, V remaining for manual follow-up:
      ↳ V_ack acknowledged via canicode annotations
      ↳ V_open unaddressed
 
+*(When Y > 0)* 📝 annotations carry context into code-gen but do not change the grade — that is by design (ADR-012).
+
 *(Optional)* Report grade: **{grade}**.
 ```
 
@@ -516,6 +614,8 @@ Roundtrip complete — N issues addressed, code generated:
      ↳ V_ack acknowledged via canicode annotations
      ↳ V_open unaddressed
 
+*(When Y > 0)* 📝 annotations carry context into code-gen but do not change the grade — that is by design (ADR-012).
+
 *(Optional)* Report grade: **{grade}**.
 Code: <files generated / next-step pointer from figma-implement-design>
 ```
@@ -599,6 +699,8 @@ Roundtrip complete — N issues addressed, code generated, mapping <state>:
      ↳ V_ack acknowledged via canicode annotations
      ↳ V_open unaddressed
 
+*(When Y > 0)* 📝 annotations carry context into code-gen but do not change the grade — that is by design (ADR-012).
+
 Code: <files generated / next-step pointer from figma-implement-design>
 Code Connect: <mapping outcome line>
 ```

package/skills/cursor/canicode-roundtrip/helpers-bootstrap.js

@@ -6,7 +6,7 @@
 // globalThis.__canicodeBootstrapResult and throws ReferenceError so the agent re-prepends the
 // installer on the next batch.
 (function __canicodeBootstrap() {
-  var expected = "0.12.1";
+  var expected = "0.12.3";
   var src = figma.root.getSharedPluginData("canicode", "helpersSrc");
   var actual = figma.root.getSharedPluginData("canicode", "helpersVersion");
   if (!src) {