canicode 0.12.1 → 0.12.3

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

@@ -2,8 +2,8 @@
 // Prepend to the FIRST use_figma batch of a roundtrip session. Caches the helpers source on
 // figma.root via setSharedPluginData so subsequent batches can prepend the much smaller
 // helpers-bootstrap.js instead of re-pasting ~31KB every call (#424, ADR-020).
-var __CANICODE_HELPERS_SRC__ = "var CanICodeRoundtrip = (function (exports) {\n  'use strict';\n\n  // src/core/roundtrip/annotations.ts\n  function stripAnnotations(annotations) {\n    const input = annotations ?? [];\n    const out = [];\n    for (const a of input) {\n      const hasLM = typeof a.labelMarkdown === \"string\" && a.labelMarkdown.length > 0;\n      const hasLabel = typeof a.label === \"string\" && a.label.length > 0;\n      if (!hasLM && !hasLabel) continue;\n      const base = hasLM ? { labelMarkdown: a.labelMarkdown } : { label: a.label };\n      if (a.categoryId) base.categoryId = a.categoryId;\n      if (Array.isArray(a.properties) && a.properties.length > 0) {\n        base.properties = a.properties;\n      }\n      out.push(base);\n    }\n    return out;\n  }\n  async function ensureCanicodeCategories() {\n    const api = figma.annotations;\n    const existing = await api.getAnnotationCategoriesAsync();\n    const byLabel = new Map(existing.map((c) => [c.label, c.id]));\n    async function ensure(label, color) {\n      const cached = byLabel.get(label);\n      if (cached) return cached;\n      const created = await api.addAnnotationCategoryAsync({ label, color });\n      byLabel.set(label, created.id);\n      return created.id;\n    }\n    const result = {\n      gotcha: await ensure(\"canicode:gotcha\", \"blue\"),\n      flag: await ensure(\"canicode:flag\", \"green\"),\n      fallback: await ensure(\"canicode:fallback\", \"yellow\")\n    };\n    const legacyAutoFix = byLabel.get(\"canicode:auto-fix\");\n    if (legacyAutoFix) result.legacyAutoFix = legacyAutoFix;\n    return result;\n  }\n  function upsertCanicodeAnnotation(node, input) {\n    if (!node || !(\"annotations\" in node)) return false;\n    const { ruleId, markdown, categoryId, properties } = input;\n    const legacyPrefix = `**[canicode] ${ruleId}**`;\n    const footer = `\\u2014 *${ruleId}*`;\n    let bodyText = markdown;\n    if (bodyText.startsWith(legacyPrefix)) {\n      bodyText = bodyText.slice(legacyPrefix.length).replace(/^\\s*\\n+/, \"\");\n    }\n    const trimmed = bodyText.replace(/\\s+$/, \"\");\n    const body = trimmed.endsWith(footer) ? trimmed : `${trimmed}\n\n${footer}`;\n    const existing = stripAnnotations(node.annotations);\n    const entry = { labelMarkdown: body };\n    if (categoryId) entry.categoryId = categoryId;\n    if (properties && properties.length > 0) entry.properties = properties;\n    const matchesRuleId = (text) => {\n      if (typeof text !== \"string\") return false;\n      return text.startsWith(legacyPrefix) || text.includes(footer);\n    };\n    const idx = existing.findIndex(\n      (a) => matchesRuleId(a.labelMarkdown) || matchesRuleId(a.label)\n    );\n    if (idx >= 0) existing[idx] = entry;\n    else existing.push(entry);\n    try {\n      node.annotations = existing;\n      return true;\n    } catch (e) {\n      const msg = String(e?.message ?? e);\n      const isNodeTypeReject = /invalid property .+ for a .+ node/i.test(msg);\n      if (!entry.properties || !isNodeTypeReject) throw e;\n      delete entry.properties;\n      if (idx >= 0) existing[idx] = entry;\n      node.annotations = existing;\n      return true;\n    }\n  }\n\n  // src/core/roundtrip/annotation-payload.ts\n  var CANICODE_JSON_FENCE = \"```canicode-json\";\n  function formatIntentValueForDisplay(value) {\n    if (value === void 0) return \"undefined\";\n    if (value === null) return \"null\";\n    if (typeof value === \"object\") {\n      try {\n        return `\\`${JSON.stringify(value)}\\``;\n      } catch {\n        return String(value);\n      }\n    }\n    return `\\`${String(value)}\\``;\n  }\n  function buildCodegenDirective(args) {\n    const { sceneNodeId, intent } = args;\n    const val = intent.value === void 0 ? \"undefined\" : JSON.stringify(intent.value);\n    return `When generating code for node ${sceneNodeId}, set ${intent.field} to ${val} (user intent, scope: ${intent.scope}). Prefer this over the current Figma scene value when they disagree.`;\n  }\n  function sceneOutcomeToAck(result, reason) {\n    return reason !== void 0 ? { result, reason } : { result };\n  }\n  function buildOutcomeHumanLine(args) {\n    if (args.skippedDefinitionDueToAdr012) {\n      const adrHint = \" Canicode skipped writing the source component without `allowDefinitionWrite: true` (ADR-012 safer default). The instance-level change did not apply as intended in the scene.\";\n      if (args.reason === \"silent-ignore\") {\n        return \"**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore).\" + adrHint;\n      }\n      return \"**Scene write outcome:** Figma rejected an instance-level change\" + (args.errorMessage ? `: ${args.errorMessage}` : \"\") + \".\" + adrHint;\n    }\n    if (args.reason === \"silent-ignore\") {\n      return \"**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore). No source definition was available to escalate.\";\n    }\n    if (args.reason === \"override-error\") {\n      return \"**Scene write outcome:** Figma rejected an instance-level change\" + (args.errorMessage ? `: ${args.errorMessage}` : \"\") + \". No source definition was available to escalate.\";\n    }\n    return \"**Scene write outcome:** Could not apply automatically\" + (args.errorMessage ? `: ${args.errorMessage}` : \"\") + \".\";\n  }\n  function buildAdr012PropagationParagraph(args) {\n    const { componentName, replicaCount } = args;\n    const fanOutHint = typeof replicaCount === \"number\" && replicaCount >= 2 ? ` This batched question covers ${replicaCount} instance scenes \\u2014 changing **${componentName}** at the definition still affects every inheriting instance, not just one row in the batch.` : \"\";\n    return `Canicode's safer default (ADR-012) is to skip writing the source component **${componentName}** without explicit opt-in, because that write propagates to every non-overridden instance of **${componentName}** in the file.${fanOutHint} Prefer a manual override on **this** instance when you only need a local fix. Use \\`allowDefinitionWrite: true\\` only when you intend to change **${componentName}** for all inheriting instances \\u2014 it is not a neutral shortcut for a single-instance tweak.`;\n  }\n  function buildDefinitionWriteSkippedBody(args) {\n    const {\n      ruleId,\n      sceneNodeId,\n      componentName,\n      reason,\n      errorMessage,\n      replicaCount,\n      intent\n    } = args;\n    const ackIntent = intent ? {\n      kind: \"property\",\n      field: intent.field,\n      value: intent.value,\n      scope: intent.scope\n    } : void 0;\n    const sceneWriteOutcome = sceneOutcomeToAck(\"user-declined-propagation\", \"adr-012-opt-in-disabled\");\n    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      ...ackIntent ? { intent: ackIntent } : {},\n      sceneWriteOutcome,\n      ...codegenDirective ? { codegenDirective } : {}\n    };\n    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;\n    const outcomeLine = buildOutcomeHumanLine({\n      reason,\n      ...errorMessage !== void 0 ? { errorMessage } : {},\n      skippedDefinitionDueToAdr012: true\n    });\n    const adrBlock = buildAdr012PropagationParagraph({\n      componentName,\n      ...replicaCount !== void 0 ? { replicaCount } : {}\n    });\n    const proseParts = [userAnswerLine, outcomeLine, adrBlock].filter(\n      (p) => p !== null\n    );\n    const prose = proseParts.join(\"\\n\\n\");\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  function buildNoDefinitionFallbackBody(args) {\n    const { ruleId, sceneNodeId, reason, errorMessage, intent } = args;\n    const ackIntent = intent ? { kind: \"property\", field: intent.field, value: intent.value, scope: intent.scope } : void 0;\n    const outcomeResult = reason === \"silent-ignore\" ? \"silent-ignored\" : reason === \"override-error\" ? \"api-rejected\" : \"api-rejected\";\n    const sceneWriteOutcome = sceneOutcomeToAck(\n      outcomeResult,\n      reason === \"silent-ignore\" ? \"silent-ignore-no-definition\" : \"no-definition-escalation\"\n    );\n    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      ...ackIntent ? { intent: ackIntent } : {},\n      sceneWriteOutcome,\n      ...codegenDirective ? { codegenDirective } : {}\n    };\n    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;\n    const outcomeLine = buildOutcomeHumanLine({\n      reason,\n      ...errorMessage !== void 0 ? { errorMessage } : {},\n      skippedDefinitionDueToAdr012: false\n    });\n    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join(\"\\n\\n\");\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  function buildDefinitionTierFailureBody(args) {\n    const { ruleId, sceneNodeId, intent, kind, errorMessage } = args;\n    const sceneWriteOutcome = sceneOutcomeToAck(\n      kind === \"read-only-library\" ? \"api-rejected\" : \"api-rejected\",\n      kind === \"read-only-library\" ? \"definition-read-only\" : \"definition-write-failed\"\n    );\n    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      ...intent ? {\n        intent: {\n          kind: \"property\",\n          field: intent.field,\n          value: intent.value,\n          scope: intent.scope\n        }\n      } : {},\n      sceneWriteOutcome,\n      ...codegenDirective ? { codegenDirective } : {}\n    };\n    const human = kind === \"read-only-library\" ? \"source component lives in an external library and is read-only from this file \\u2014 apply the fix in the library file itself.\" : `could not apply at source definition: ${errorMessage}`;\n    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;\n    const outcomeLine = `**Scene write outcome:** ${human}`;\n    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join(\"\\n\\n\");\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  function appendJsonFenceAndFooter(prose, jsonBlock, ruleId) {\n    const footer = `\\u2014 *${ruleId}*`;\n    const hasIntent = jsonBlock.intent !== void 0;\n    if (!hasIntent) {\n      return `${prose}\n\n${footer}`;\n    }\n    const jsonText = JSON.stringify(jsonBlock, null, 0);\n    return `${prose}\n\n${CANICODE_JSON_FENCE}\n${jsonText}\n\\`\\`\\`\n\n${footer}`;\n  }\n  function buildIntentionallyUnmappedAnnotationBody(args) {\n    const { sceneNodeId, ruleId } = args;\n    const intent = {\n      kind: \"rule-opt-out\",\n      ruleId\n    };\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      intent,\n      sceneWriteOutcome: { result: \"succeeded\", reason: \"rule-opt-out\" }\n    };\n    const prose = \"User marked this component as intentionally unmapped \\u2014 canicode will skip the unmapped-component check for this node on subsequent analyze runs.\";\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  var FENCED_JSON_RE = new RegExp(\n    `${CANICODE_JSON_FENCE.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\")}\\\\s*([\\\\s\\\\S]*?)\\\\s*\\`\\`\\``,\n    \"m\"\n  );\n  function parseCanicodeJsonPayloadFromMarkdown(text) {\n    const m = FENCED_JSON_RE.exec(text);\n    if (!m?.[1]) return void 0;\n    try {\n      const raw = JSON.parse(m[1].trim());\n      if (!raw || typeof raw !== \"object\") return void 0;\n      const o = raw;\n      if (o.v !== 1 || typeof o.ruleId !== \"string\") return void 0;\n      return raw;\n    } catch {\n      return void 0;\n    }\n  }\n\n  // src/core/roundtrip/apply-with-instance-fallback.ts\n  var DEFINITION_WRITE_SKIPPED_EVENT = \"cic_roundtrip_definition_write_skipped\";\n  function categoryIdForAnnotate(categories, kind, roundtripIntent) {\n    if (kind === \"adr012-definition-skipped\") {\n      return categories.fallback;\n    }\n    if (roundtripIntent !== void 0) {\n      return categories.gotcha;\n    }\n    return categories.flag;\n  }\n  function resolveSourceComponentName(definition, question) {\n    if (definition && typeof definition.name === \"string\" && definition.name) {\n      return definition.name;\n    }\n    const ic = question.instanceContext;\n    if (ic && typeof ic.sourceComponentName === \"string\" && ic.sourceComponentName) {\n      return ic.sourceComponentName;\n    }\n    return \"the source component\";\n  }\n  async function routeToDefinitionOrAnnotate(definition, writeFn, ctx) {\n    if (definition && !ctx.allowDefinitionWrite && ctx.reason !== \"non-override-error\") {\n      const componentName = resolveSourceComponentName(definition, ctx.question);\n      const replicaCount = typeof ctx.question.replicas === \"number\" && Number.isInteger(ctx.question.replicas) ? ctx.question.replicas : void 0;\n      if (ctx.categories) {\n        upsertCanicodeAnnotation(ctx.scene, {\n          ruleId: ctx.question.ruleId,\n          markdown: buildDefinitionWriteSkippedBody({\n            ruleId: ctx.question.ruleId,\n            sceneNodeId: ctx.scene.id,\n            componentName,\n            reason: ctx.reason,\n            ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},\n            ...replicaCount !== void 0 ? { replicaCount } : {},\n            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}\n          }),\n          categoryId: categoryIdForAnnotate(\n            ctx.categories,\n            \"adr012-definition-skipped\",\n            ctx.roundtripIntent\n          )\n        });\n      }\n      ctx.telemetry?.(DEFINITION_WRITE_SKIPPED_EVENT, {\n        ruleId: ctx.question.ruleId,\n        reason: ctx.reason\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"definition write skipped (opt-in disabled)\"\n      };\n    }\n    if (!definition) {\n      if (ctx.categories) {\n        const markdown = buildNoDefinitionFallbackBody({\n          ruleId: ctx.question.ruleId,\n          sceneNodeId: ctx.scene.id,\n          reason: ctx.reason,\n          ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},\n          ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}\n        });\n        upsertCanicodeAnnotation(ctx.scene, {\n          ruleId: ctx.question.ruleId,\n          markdown,\n          categoryId: categoryIdForAnnotate(\n            ctx.categories,\n            \"other-failure\",\n            ctx.roundtripIntent\n          )\n        });\n      }\n      return ctx.reason === \"silent-ignore\" ? { icon: \"\\u{1F4DD}\", label: \"silent-ignore, annotated\" } : { icon: \"\\u{1F4DD}\", label: `error: ${ctx.errorMessage ?? \"\"}` };\n    }\n    try {\n      await writeFn(definition);\n      return {\n        icon: \"\\u{1F310}\",\n        label: ctx.reason === \"silent-ignore\" ? \"source definition (silent-ignore fallback)\" : \"source definition\"\n      };\n    } catch (defErr) {\n      const defMsg = String(defErr?.message ?? defErr);\n      const isRemoteReadOnly = definition.remote === true || /read-only/i.test(defMsg);\n      if (ctx.categories) {\n        upsertCanicodeAnnotation(ctx.scene, {\n          ruleId: ctx.question.ruleId,\n          markdown: buildDefinitionTierFailureBody({\n            ruleId: ctx.question.ruleId,\n            sceneNodeId: ctx.scene.id,\n            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {},\n            kind: isRemoteReadOnly ? \"read-only-library\" : \"definition-error\",\n            errorMessage: defMsg\n          }),\n          categoryId: categoryIdForAnnotate(\n            ctx.categories,\n            \"other-failure\",\n            ctx.roundtripIntent\n          )\n        });\n      }\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: isRemoteReadOnly ? \"external library (read-only)\" : `definition error: ${defMsg}`\n      };\n    }\n  }\n  async function applyWithInstanceFallback(question, writeFn, context = {}) {\n    const { categories, allowDefinitionWrite = false, telemetry, roundtripIntent } = context;\n    const scene = await figma.getNodeByIdAsync(question.nodeId);\n    if (!scene) return { icon: \"\\u{1F4DD}\", label: \"missing node\" };\n    const definition = question.sourceChildId ? await figma.getNodeByIdAsync(question.sourceChildId) : null;\n    try {\n      const changed = await writeFn(scene);\n      if (changed === false) {\n        return routeToDefinitionOrAnnotate(definition, writeFn, {\n          question,\n          scene,\n          categories,\n          reason: \"silent-ignore\",\n          allowDefinitionWrite,\n          telemetry,\n          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n        });\n      }\n      return { icon: \"\\u2705\", label: \"instance/scene\" };\n    } catch (e) {\n      const msg = String(e?.message ?? e);\n      const looksLikeInstanceOverride = /cannot be overridden/i.test(msg) || /override/i.test(msg);\n      if (!looksLikeInstanceOverride) {\n        return routeToDefinitionOrAnnotate(null, writeFn, {\n          question,\n          scene,\n          categories,\n          reason: \"non-override-error\",\n          errorMessage: msg,\n          allowDefinitionWrite,\n          telemetry,\n          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n        });\n      }\n      return routeToDefinitionOrAnnotate(definition, writeFn, {\n        question,\n        scene,\n        categories,\n        reason: \"override-error\",\n        errorMessage: msg,\n        allowDefinitionWrite,\n        telemetry,\n        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n      });\n    }\n  }\n\n  // src/core/roundtrip/apply-property-mod.ts\n  async function resolveVariableByName(name) {\n    const locals = await figma.variables.getLocalVariablesAsync();\n    return locals.find((v) => v.name === name) ?? null;\n  }\n  function parseValue(raw) {\n    if (raw && typeof raw === \"object\" && \"variable\" in raw) {\n      const v = raw;\n      const parsed = { kind: \"binding\", name: v.variable };\n      if (\"fallback\" in v) parsed.fallback = v.fallback;\n      return parsed;\n    }\n    if (raw && typeof raw === \"object\" && \"fallback\" in raw) {\n      return { kind: \"scalar\", scalar: raw.fallback };\n    }\n    return { kind: \"scalar\", scalar: raw };\n  }\n  function isPaintProp(prop) {\n    return prop === \"fills\" || prop === \"strokes\";\n  }\n  function applyPropertyBinding(target, prop, variable) {\n    if (isPaintProp(prop)) {\n      const current = target[prop];\n      if (current === figma.mixed || !Array.isArray(current)) return false;\n      const paints = current;\n      const bound = paints.map(\n        (paint) => figma.variables.setBoundVariableForPaint(paint, \"color\", variable)\n      );\n      target[prop] = bound;\n      return true;\n    }\n    target.setBoundVariable(prop, variable);\n    return true;\n  }\n  function buildRoundtripIntentFromPropertyAnswer(question, answerValue) {\n    const raw = question.targetProperty;\n    if (raw === void 0) return void 0;\n    const props = Array.isArray(raw) ? raw : [raw];\n    if (props.length === 0) return void 0;\n    if (props.length === 1) {\n      const prop = props[0];\n      const perProp = answerValue && typeof answerValue === \"object\" && !(\"variable\" in answerValue) && !Array.isArray(answerValue) ? answerValue[prop] : answerValue;\n      const parsed = parseValueForIntent(perProp);\n      if (parsed === void 0) return void 0;\n      return { field: prop, value: parsed, scope: \"instance\" };\n    }\n    const obj = answerValue && typeof answerValue === \"object\" && !(\"variable\" in answerValue) && !Array.isArray(answerValue) ? answerValue : void 0;\n    const picked = {};\n    for (const p of props) {\n      if (obj && p in obj && obj[p] !== void 0) picked[p] = obj[p];\n    }\n    if (Object.keys(picked).length === 0) return void 0;\n    return {\n      field: props.join(\", \"),\n      value: picked,\n      scope: \"instance\"\n    };\n  }\n  function parseValueForIntent(raw) {\n    if (raw && typeof raw === \"object\" && \"variable\" in raw) {\n      return { variable: raw.variable };\n    }\n    if (raw && typeof raw === \"object\" && \"fallback\" in raw) {\n      return raw.fallback;\n    }\n    return raw;\n  }\n  function applyPropertyScalar(target, prop, scalar) {\n    const rec = target;\n    const before = rec[prop];\n    rec[prop] = scalar;\n    if (rec[prop] === before && before !== scalar) return false;\n    return true;\n  }\n  async function applyPropertyMod(question, answerValue, context = {}) {\n    const roundtripIntent = buildRoundtripIntentFromPropertyAnswer(\n      question,\n      answerValue\n    );\n    const props = Array.isArray(question.targetProperty) ? question.targetProperty : question.targetProperty !== void 0 ? [question.targetProperty] : [];\n    return applyWithInstanceFallback(\n      question,\n      async (target) => {\n        if (!target) return void 0;\n        let changed = void 0;\n        for (const prop of props) {\n          if (!(prop in target)) continue;\n          const perProp = answerValue && typeof answerValue === \"object\" && !(\"variable\" in answerValue) && !Array.isArray(answerValue) ? answerValue[prop] : answerValue;\n          const parsed = parseValue(perProp);\n          if (parsed.kind === \"binding\") {\n            const variable = await resolveVariableByName(parsed.name);\n            if (variable) {\n              applyPropertyBinding(target, prop, variable);\n              continue;\n            }\n            if (parsed.fallback !== void 0) {\n              if (!applyPropertyScalar(target, prop, parsed.fallback)) {\n                changed = false;\n              }\n            }\n            continue;\n          }\n          if (parsed.scalar === void 0) continue;\n          if (!applyPropertyScalar(target, prop, parsed.scalar)) {\n            changed = false;\n          }\n        }\n        return changed;\n      },\n      {\n        ...context,\n        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n      }\n    );\n  }\n\n  // src/core/roundtrip/probe-definition-writability.ts\n  async function probeDefinitionWritability(questions) {\n    const verdict = /* @__PURE__ */ new Map();\n    const unwritableNames = [];\n    const seenName = /* @__PURE__ */ new Set();\n    for (const q of questions) {\n      const id = q.sourceChildId;\n      if (!id) continue;\n      if (verdict.has(id)) continue;\n      const node = await figma.getNodeByIdAsync(id);\n      const writability = resolveWritability(node);\n      const isUnwritable = writability.isUnwritable;\n      verdict.set(id, isUnwritable ? \"unwritable\" : \"writable\");\n      if (isUnwritable) {\n        const name = typeof writability.componentName === \"string\" && writability.componentName || typeof node?.name === \"string\" && node.name || q.instanceContext?.sourceComponentName || id;\n        if (!seenName.has(name)) {\n          seenName.add(name);\n          unwritableNames.push(name);\n        }\n      }\n    }\n    const totalCount = verdict.size;\n    let unwritableCount = 0;\n    for (const v of verdict.values()) if (v === \"unwritable\") unwritableCount++;\n    return {\n      totalCount,\n      unwritableCount,\n      unwritableSourceNames: unwritableNames,\n      allUnwritable: totalCount > 0 && unwritableCount === totalCount,\n      partiallyUnwritable: unwritableCount > 0 && unwritableCount < totalCount\n    };\n  }\n  function resolveWritability(node) {\n    if (node === null) return { isUnwritable: true };\n    if (\"remote\" in node && typeof node.remote === \"boolean\") {\n      return { isUnwritable: node.remote === true };\n    }\n    const containing = findContainingComponent(node);\n    if (!containing) {\n      return { isUnwritable: false };\n    }\n    const isUnwritable = \"remote\" in containing && containing.remote === true;\n    return {\n      isUnwritable,\n      ...isUnwritable && typeof containing.name === \"string\" ? { componentName: containing.name } : {}\n    };\n  }\n  function findContainingComponent(node) {\n    let cur = node;\n    for (let i = 0; i < 100 && cur; i++) {\n      if (cur.type === \"COMPONENT\" || cur.type === \"COMPONENT_SET\") return cur;\n      cur = cur.parent ?? null;\n    }\n    return null;\n  }\n\n  // src/core/roundtrip/read-acknowledgments.ts\n  var FOOTER_RE = /—\\s+\\*([A-Za-z0-9-]+)\\*\\s*$/;\n  var LEGACY_PREFIX_RE = /^\\*\\*\\[canicode\\]\\s+([A-Za-z0-9-]+)\\*\\*/;\n  function extractAcknowledgmentsFromNode(node, canicodeCategoryIds) {\n    if (!node || !(\"annotations\" in node)) return [];\n    const annotations = node.annotations ?? [];\n    if (annotations.length === 0) return [];\n    const out = [];\n    for (const a of annotations) {\n      const text = (typeof a.labelMarkdown === \"string\" && a.labelMarkdown.length > 0 ? a.labelMarkdown : \"\") || (typeof a.label === \"string\" && a.label.length > 0 ? a.label : \"\");\n      if (!text) continue;\n      if (canicodeCategoryIds) {\n        if (!a.categoryId || !canicodeCategoryIds.has(a.categoryId)) continue;\n      }\n      const ruleId = extractRuleId(text);\n      if (!ruleId) continue;\n      const payload = parseCanicodeJsonPayloadFromMarkdown(text);\n      const payloadAligned = payload && payload.ruleId === ruleId;\n      out.push({\n        nodeId: node.id,\n        ruleId,\n        ...payloadAligned && payload.intent ? { intent: payload.intent } : {},\n        ...payloadAligned && payload.sceneWriteOutcome ? { sceneWriteOutcome: payload.sceneWriteOutcome } : {},\n        ...payloadAligned && payload.codegenDirective ? { codegenDirective: payload.codegenDirective } : {}\n      });\n    }\n    return out;\n  }\n  function extractRuleId(text) {\n    const footer = FOOTER_RE.exec(text);\n    if (footer) return footer[1] ?? null;\n    const legacy = LEGACY_PREFIX_RE.exec(text);\n    if (legacy) return legacy[1] ?? null;\n    return null;\n  }\n  async function readCanicodeAcknowledgments(rootNodeId, categories) {\n    const root = await figma.getNodeByIdAsync(rootNodeId);\n    if (!root) return [];\n    const canicodeCategoryIds = categories ? new Set(\n      [\n        categories.gotcha,\n        categories.flag,\n        categories.fallback,\n        categories.legacyAutoFix\n      ].filter((id) => typeof id === \"string\" && id.length > 0)\n    ) : void 0;\n    const out = [];\n    walk(root, canicodeCategoryIds, out);\n    return out;\n  }\n  function safeChildren(node) {\n    try {\n      const c = node.children;\n      return Array.isArray(c) ? c : [];\n    } catch {\n      return [];\n    }\n  }\n  function walk(node, canicodeCategoryIds, out) {\n    try {\n      const local = extractAcknowledgmentsFromNode(node, canicodeCategoryIds);\n      for (const a of local) out.push(a);\n    } catch {\n    }\n    for (const child of safeChildren(node)) {\n      if (child && typeof child === \"object\") walk(child, canicodeCategoryIds, out);\n    }\n  }\n\n  // src/core/roundtrip/apply-unmapped-component-opt-out.ts\n  async function applyUnmappedComponentOptOut(input, context) {\n    const { nodeId, ruleId } = input;\n    const { categories } = context;\n    const scene = await figma.getNodeByIdAsync(nodeId);\n    if (!scene) {\n      return { icon: \"\\u{1F4DD}\", label: `missing node \\u2014 ${ruleId}` };\n    }\n    const markdown = buildIntentionallyUnmappedAnnotationBody({\n      sceneNodeId: scene.id,\n      ruleId\n    });\n    upsertCanicodeAnnotation(scene, {\n      ruleId,\n      markdown,\n      categoryId: categories.gotcha\n    });\n    return { icon: \"\\u{1F4DD}\", label: `opt-out annotation written \\u2014 ${ruleId}` };\n  }\n\n  // src/core/roundtrip/compute-roundtrip-tally.ts\n  function computeRoundtripTally(args) {\n    const { stepFourReport, reanalyzeResponse } = args;\n    const { resolved, annotated, definitionWritten, skipped } = stepFourReport;\n    const { issueCount, acknowledgedCount } = reanalyzeResponse;\n    if (acknowledgedCount > issueCount) {\n      throw new Error(\n        `computeRoundtripTally: reanalyzeResponse.acknowledgedCount (${acknowledgedCount}) cannot exceed issueCount (${issueCount}). Acknowledged issues are a subset of remaining issues.`\n      );\n    }\n    return {\n      X: resolved,\n      Y: annotated,\n      Z: definitionWritten,\n      W: skipped,\n      N: resolved + annotated + definitionWritten + skipped,\n      V: issueCount,\n      V_ack: acknowledgedCount,\n      V_open: issueCount - acknowledgedCount\n    };\n  }\n\n  // src/core/roundtrip/apply-auto-fix.ts\n  function pickNodeName(issue, resolved) {\n    if (resolved && typeof resolved.name === \"string\" && resolved.name.length > 0) {\n      return resolved.name;\n    }\n    if (typeof issue.nodePath === \"string\" && issue.nodePath.length > 0) {\n      const segments = issue.nodePath.split(/\\s*[›>/]\\s*/);\n      const tail = segments[segments.length - 1];\n      if (tail && tail.length > 0) return tail;\n    }\n    return issue.nodeId;\n  }\n  function mapInstanceFallbackIcon(result) {\n    if (result.icon === \"\\u2705\") return \"\\u{1F527}\";\n    return result.icon;\n  }\n  async function applyAutoFix(issue, context) {\n    const { categories } = context;\n    const ruleId = issue.ruleId;\n    if (issue.targetProperty === \"name\" && typeof issue.suggestedName === \"string\") {\n      const suggestedName = issue.suggestedName;\n      const question = {\n        nodeId: issue.nodeId,\n        ruleId,\n        ...issue.sourceChildId ? { sourceChildId: issue.sourceChildId } : {}\n      };\n      const result = await applyWithInstanceFallback(\n        question,\n        (target) => {\n          if (target) {\n            target.name = suggestedName;\n          }\n        },\n        {\n          categories,\n          ...context.allowDefinitionWrite !== void 0 ? { allowDefinitionWrite: context.allowDefinitionWrite } : {},\n          ...context.telemetry !== void 0 ? { telemetry: context.telemetry } : {}\n        }\n      );\n      const sceneAfter = await figma.getNodeByIdAsync(issue.nodeId);\n      return {\n        outcome: mapInstanceFallbackIcon(result),\n        nodeId: issue.nodeId,\n        nodeName: pickNodeName(issue, sceneAfter),\n        ruleId,\n        label: result.label\n      };\n    }\n    const scene = await figma.getNodeByIdAsync(issue.nodeId);\n    const markdown = issue.message ?? `Auto-flagged: ${ruleId}`;\n    if (scene) {\n      upsertCanicodeAnnotation(scene, {\n        ruleId,\n        markdown,\n        categoryId: categories.flag,\n        ...issue.annotationProperties && issue.annotationProperties.length > 0 ? { properties: issue.annotationProperties } : {}\n      });\n    }\n    return {\n      outcome: \"\\u{1F4DD}\",\n      nodeId: issue.nodeId,\n      nodeName: pickNodeName(issue, scene),\n      ruleId,\n      label: scene ? `annotation added to canicode:flag \\u2014 ${ruleId}` : `missing node (annotation skipped) \\u2014 ${ruleId}`\n    };\n  }\n  async function applyAutoFixes(issues, context) {\n    const out = [];\n    for (const issue of issues) {\n      if (issue.applyStrategy !== \"auto-fix\") {\n        out.push({\n          outcome: \"\\u23ED\\uFE0F\",\n          nodeId: issue.nodeId,\n          nodeName: pickNodeName(issue, null),\n          ruleId: issue.ruleId,\n          label: `skipped \\u2014 applyStrategy is ${issue.applyStrategy ?? \"absent\"}`\n        });\n        continue;\n      }\n      out.push(await applyAutoFix(issue, context));\n    }\n    return out;\n  }\n\n  // src/core/roundtrip/remove-canicode-annotations.ts\n  var LEGACY_CANICODE_PREFIX = \"**[canicode]\";\n  function isCanicodeAnnotation(annotation, categories) {\n    const canicodeIds = new Set(\n      [\n        categories.gotcha,\n        categories.flag,\n        categories.fallback,\n        categories.legacyAutoFix\n      ].filter((id) => Boolean(id))\n    );\n    if (annotation.categoryId && canicodeIds.has(annotation.categoryId)) {\n      return true;\n    }\n    if (annotation.labelMarkdown?.startsWith(LEGACY_CANICODE_PREFIX)) {\n      return true;\n    }\n    return false;\n  }\n  function removeCanicodeAnnotations(annotations, categories) {\n    return annotations.filter((a) => !isCanicodeAnnotation(a, categories));\n  }\n\n  exports.applyAutoFix = applyAutoFix;\n  exports.applyAutoFixes = applyAutoFixes;\n  exports.applyPropertyMod = applyPropertyMod;\n  exports.applyUnmappedComponentOptOut = applyUnmappedComponentOptOut;\n  exports.applyWithInstanceFallback = applyWithInstanceFallback;\n  exports.buildIntentionallyUnmappedAnnotationBody = buildIntentionallyUnmappedAnnotationBody;\n  exports.computeRoundtripTally = computeRoundtripTally;\n  exports.ensureCanicodeCategories = ensureCanicodeCategories;\n  exports.extractAcknowledgmentsFromNode = extractAcknowledgmentsFromNode;\n  exports.isCanicodeAnnotation = isCanicodeAnnotation;\n  exports.probeDefinitionWritability = probeDefinitionWritability;\n  exports.readCanicodeAcknowledgments = readCanicodeAcknowledgments;\n  exports.removeCanicodeAnnotations = removeCanicodeAnnotations;\n  exports.resolveVariableByName = resolveVariableByName;\n  exports.stripAnnotations = stripAnnotations;\n  exports.upsertCanicodeAnnotation = upsertCanicodeAnnotation;\n\n  return exports;\n\n})({});\n\n;globalThis.CanICodeRoundtrip = CanICodeRoundtrip;\n";
-var __CANICODE_HELPERS_VERSION__ = "0.12.1";
+var __CANICODE_HELPERS_SRC__ = "var CanICodeRoundtrip = (function (exports) {\n  'use strict';\n\n  // src/core/roundtrip/annotations.ts\n  function stripAnnotations(annotations) {\n    const input = annotations ?? [];\n    const out = [];\n    for (const a of input) {\n      const hasLM = typeof a.labelMarkdown === \"string\" && a.labelMarkdown.length > 0;\n      const hasLabel = typeof a.label === \"string\" && a.label.length > 0;\n      if (!hasLM && !hasLabel) continue;\n      const base = hasLM ? { labelMarkdown: a.labelMarkdown } : { label: a.label };\n      if (a.categoryId) base.categoryId = a.categoryId;\n      if (Array.isArray(a.properties) && a.properties.length > 0) {\n        base.properties = a.properties;\n      }\n      out.push(base);\n    }\n    return out;\n  }\n  async function ensureCanicodeCategories() {\n    const api = figma.annotations;\n    const existing = await api.getAnnotationCategoriesAsync();\n    const byLabel = new Map(existing.map((c) => [c.label, c.id]));\n    async function ensure(label, color) {\n      const cached = byLabel.get(label);\n      if (cached) return cached;\n      const created = await api.addAnnotationCategoryAsync({ label, color });\n      byLabel.set(label, created.id);\n      return created.id;\n    }\n    const result = {\n      gotcha: await ensure(\"canicode:gotcha\", \"blue\"),\n      flag: await ensure(\"canicode:flag\", \"green\"),\n      fallback: await ensure(\"canicode:fallback\", \"yellow\")\n    };\n    const legacyAutoFix = byLabel.get(\"canicode:auto-fix\");\n    if (legacyAutoFix) result.legacyAutoFix = legacyAutoFix;\n    return result;\n  }\n  function upsertCanicodeAnnotation(node, input) {\n    if (!node || !(\"annotations\" in node)) return false;\n    const { ruleId, markdown, categoryId, properties } = input;\n    const legacyPrefix = `**[canicode] ${ruleId}**`;\n    const footer = `\\u2014 *${ruleId}*`;\n    let bodyText = markdown;\n    if (bodyText.startsWith(legacyPrefix)) {\n      bodyText = bodyText.slice(legacyPrefix.length).replace(/^\\s*\\n+/, \"\");\n    }\n    const trimmed = bodyText.replace(/\\s+$/, \"\");\n    const body = trimmed.endsWith(footer) ? trimmed : `${trimmed}\n\n${footer}`;\n    const existing = stripAnnotations(node.annotations);\n    const entry = { labelMarkdown: body };\n    if (categoryId) entry.categoryId = categoryId;\n    if (properties && properties.length > 0) entry.properties = properties;\n    const matchesRuleId = (text) => {\n      if (typeof text !== \"string\") return false;\n      return text.startsWith(legacyPrefix) || text.includes(footer);\n    };\n    const idx = existing.findIndex(\n      (a) => matchesRuleId(a.labelMarkdown) || matchesRuleId(a.label)\n    );\n    if (idx >= 0) existing[idx] = entry;\n    else existing.push(entry);\n    try {\n      node.annotations = existing;\n      return true;\n    } catch (e) {\n      const msg = String(e?.message ?? e);\n      const isNodeTypeReject = /invalid property .+ for a .+ node/i.test(msg);\n      if (!entry.properties || !isNodeTypeReject) throw e;\n      delete entry.properties;\n      if (idx >= 0) existing[idx] = entry;\n      node.annotations = existing;\n      return true;\n    }\n  }\n\n  // src/core/roundtrip/annotation-payload.ts\n  var CANICODE_JSON_FENCE = \"```canicode-json\";\n  function formatIntentValueForDisplay(value) {\n    if (value === void 0) return \"undefined\";\n    if (value === null) return \"null\";\n    if (typeof value === \"object\") {\n      try {\n        return `\\`${JSON.stringify(value)}\\``;\n      } catch {\n        return String(value);\n      }\n    }\n    return `\\`${String(value)}\\``;\n  }\n  function buildCodegenDirective(args) {\n    const { sceneNodeId, intent } = args;\n    const val = intent.value === void 0 ? \"undefined\" : JSON.stringify(intent.value);\n    return `When generating code for node ${sceneNodeId}, set ${intent.field} to ${val} (user intent, scope: ${intent.scope}). Prefer this over the current Figma scene value when they disagree.`;\n  }\n  function sceneOutcomeToAck(result, reason) {\n    return reason !== void 0 ? { result, reason } : { result };\n  }\n  function buildOutcomeHumanLine(args) {\n    if (args.skippedDefinitionDueToAdr012) {\n      const adrHint = \" Canicode skipped writing the source component without `allowDefinitionWrite: true` (ADR-012 safer default). The instance-level change did not apply as intended in the scene.\";\n      if (args.reason === \"silent-ignore\") {\n        return \"**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore).\" + adrHint;\n      }\n      return \"**Scene write outcome:** Figma rejected an instance-level change\" + (args.errorMessage ? `: ${args.errorMessage}` : \"\") + \".\" + adrHint;\n    }\n    if (args.reason === \"silent-ignore\") {\n      return \"**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore). No source definition was available to escalate.\";\n    }\n    if (args.reason === \"override-error\") {\n      return \"**Scene write outcome:** Figma rejected an instance-level change\" + (args.errorMessage ? `: ${args.errorMessage}` : \"\") + \". No source definition was available to escalate.\";\n    }\n    return \"**Scene write outcome:** Could not apply automatically\" + (args.errorMessage ? `: ${args.errorMessage}` : \"\") + \".\";\n  }\n  function buildAdr012PropagationParagraph(args) {\n    const { componentName, replicaCount } = args;\n    const fanOutHint = typeof replicaCount === \"number\" && replicaCount >= 2 ? ` This batched question covers ${replicaCount} instance scenes \\u2014 changing **${componentName}** at the definition still affects every inheriting instance, not just one row in the batch.` : \"\";\n    return `Canicode's safer default (ADR-012) is to skip writing the source component **${componentName}** without explicit opt-in, because that write propagates to every non-overridden instance of **${componentName}** in the file.${fanOutHint} Prefer a manual override on **this** instance when you only need a local fix. Use \\`allowDefinitionWrite: true\\` only when you intend to change **${componentName}** for all inheriting instances \\u2014 it is not a neutral shortcut for a single-instance tweak.`;\n  }\n  function buildDefinitionWriteSkippedBody(args) {\n    const {\n      ruleId,\n      sceneNodeId,\n      componentName,\n      reason,\n      errorMessage,\n      replicaCount,\n      intent\n    } = args;\n    const ackIntent = intent ? {\n      kind: \"property\",\n      field: intent.field,\n      value: intent.value,\n      scope: intent.scope\n    } : void 0;\n    const sceneWriteOutcome = sceneOutcomeToAck(\"user-declined-propagation\", \"adr-012-opt-in-disabled\");\n    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      ...ackIntent ? { intent: ackIntent } : {},\n      sceneWriteOutcome,\n      ...codegenDirective ? { codegenDirective } : {}\n    };\n    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;\n    const outcomeLine = buildOutcomeHumanLine({\n      reason,\n      ...errorMessage !== void 0 ? { errorMessage } : {},\n      skippedDefinitionDueToAdr012: true\n    });\n    const adrBlock = buildAdr012PropagationParagraph({\n      componentName,\n      ...replicaCount !== void 0 ? { replicaCount } : {}\n    });\n    const proseParts = [userAnswerLine, outcomeLine, adrBlock].filter(\n      (p) => p !== null\n    );\n    const prose = proseParts.join(\"\\n\\n\");\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  function buildNoDefinitionFallbackBody(args) {\n    const { ruleId, sceneNodeId, reason, errorMessage, intent } = args;\n    const ackIntent = intent ? { kind: \"property\", field: intent.field, value: intent.value, scope: intent.scope } : void 0;\n    const outcomeResult = reason === \"silent-ignore\" ? \"silent-ignored\" : reason === \"override-error\" ? \"api-rejected\" : \"api-rejected\";\n    const sceneWriteOutcome = sceneOutcomeToAck(\n      outcomeResult,\n      reason === \"silent-ignore\" ? \"silent-ignore-no-definition\" : \"no-definition-escalation\"\n    );\n    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      ...ackIntent ? { intent: ackIntent } : {},\n      sceneWriteOutcome,\n      ...codegenDirective ? { codegenDirective } : {}\n    };\n    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;\n    const outcomeLine = buildOutcomeHumanLine({\n      reason,\n      ...errorMessage !== void 0 ? { errorMessage } : {},\n      skippedDefinitionDueToAdr012: false\n    });\n    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join(\"\\n\\n\");\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  function buildDefinitionTierFailureBody(args) {\n    const { ruleId, sceneNodeId, intent, kind, errorMessage } = args;\n    const sceneWriteOutcome = sceneOutcomeToAck(\n      kind === \"read-only-library\" ? \"api-rejected\" : \"api-rejected\",\n      kind === \"read-only-library\" ? \"definition-read-only\" : \"definition-write-failed\"\n    );\n    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      ...intent ? {\n        intent: {\n          kind: \"property\",\n          field: intent.field,\n          value: intent.value,\n          scope: intent.scope\n        }\n      } : {},\n      sceneWriteOutcome,\n      ...codegenDirective ? { codegenDirective } : {}\n    };\n    const human = kind === \"read-only-library\" ? \"source component lives in an external library and is read-only from this file \\u2014 apply the fix in the library file itself.\" : `could not apply at source definition: ${errorMessage}`;\n    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;\n    const outcomeLine = `**Scene write outcome:** ${human}`;\n    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join(\"\\n\\n\");\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  function appendJsonFenceAndFooter(prose, jsonBlock, ruleId) {\n    const footer = `\\u2014 *${ruleId}*`;\n    const hasIntent = jsonBlock.intent !== void 0;\n    if (!hasIntent) {\n      return `${prose}\n\n${footer}`;\n    }\n    const jsonText = JSON.stringify(jsonBlock, null, 0);\n    return `${prose}\n\n${CANICODE_JSON_FENCE}\n${jsonText}\n\\`\\`\\`\n\n${footer}`;\n  }\n  function buildIntentionallyUnmappedAnnotationBody(args) {\n    const { sceneNodeId, ruleId } = args;\n    const intent = {\n      kind: \"rule-opt-out\",\n      ruleId\n    };\n    const jsonBlock = {\n      v: 1,\n      ruleId,\n      nodeId: sceneNodeId,\n      intent,\n      sceneWriteOutcome: { result: \"succeeded\", reason: \"rule-opt-out\" }\n    };\n    const prose = \"User marked this component as intentionally unmapped \\u2014 canicode will skip the unmapped-component check for this node on subsequent analyze runs.\";\n    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);\n  }\n  var FENCED_JSON_RE = new RegExp(\n    `${CANICODE_JSON_FENCE.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\")}\\\\s*([\\\\s\\\\S]*?)\\\\s*\\`\\`\\``,\n    \"m\"\n  );\n  function parseCanicodeJsonPayloadFromMarkdown(text) {\n    const m = FENCED_JSON_RE.exec(text);\n    if (!m?.[1]) return void 0;\n    try {\n      const raw = JSON.parse(m[1].trim());\n      if (!raw || typeof raw !== \"object\") return void 0;\n      const o = raw;\n      if (o.v !== 1 || typeof o.ruleId !== \"string\") return void 0;\n      return raw;\n    } catch {\n      return void 0;\n    }\n  }\n\n  // src/core/roundtrip/apply-with-instance-fallback.ts\n  var DEFINITION_WRITE_SKIPPED_EVENT = \"cic_roundtrip_definition_write_skipped\";\n  function categoryIdForAnnotate(categories, kind, roundtripIntent) {\n    if (kind === \"adr012-definition-skipped\") {\n      return categories.fallback;\n    }\n    if (roundtripIntent !== void 0) {\n      return categories.gotcha;\n    }\n    return categories.flag;\n  }\n  function resolveSourceComponentName(definition, question) {\n    if (definition && typeof definition.name === \"string\" && definition.name) {\n      return definition.name;\n    }\n    const ic = question.instanceContext;\n    if (ic && typeof ic.sourceComponentName === \"string\" && ic.sourceComponentName) {\n      return ic.sourceComponentName;\n    }\n    return \"the source component\";\n  }\n  async function routeToDefinitionOrAnnotate(definition, writeFn, ctx) {\n    if (definition && !ctx.allowDefinitionWrite && ctx.reason !== \"non-override-error\") {\n      const componentName = resolveSourceComponentName(definition, ctx.question);\n      const replicaCount = typeof ctx.question.replicas === \"number\" && Number.isInteger(ctx.question.replicas) ? ctx.question.replicas : void 0;\n      if (ctx.categories) {\n        upsertCanicodeAnnotation(ctx.scene, {\n          ruleId: ctx.question.ruleId,\n          markdown: buildDefinitionWriteSkippedBody({\n            ruleId: ctx.question.ruleId,\n            sceneNodeId: ctx.scene.id,\n            componentName,\n            reason: ctx.reason,\n            ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},\n            ...replicaCount !== void 0 ? { replicaCount } : {},\n            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}\n          }),\n          categoryId: categoryIdForAnnotate(\n            ctx.categories,\n            \"adr012-definition-skipped\",\n            ctx.roundtripIntent\n          )\n        });\n      }\n      ctx.telemetry?.(DEFINITION_WRITE_SKIPPED_EVENT, {\n        ruleId: ctx.question.ruleId,\n        reason: ctx.reason\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"definition write skipped (opt-in disabled)\"\n      };\n    }\n    if (!definition) {\n      if (ctx.categories) {\n        const markdown = buildNoDefinitionFallbackBody({\n          ruleId: ctx.question.ruleId,\n          sceneNodeId: ctx.scene.id,\n          reason: ctx.reason,\n          ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},\n          ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}\n        });\n        upsertCanicodeAnnotation(ctx.scene, {\n          ruleId: ctx.question.ruleId,\n          markdown,\n          categoryId: categoryIdForAnnotate(\n            ctx.categories,\n            \"other-failure\",\n            ctx.roundtripIntent\n          )\n        });\n      }\n      return ctx.reason === \"silent-ignore\" ? { icon: \"\\u{1F4DD}\", label: \"silent-ignore, annotated\" } : { icon: \"\\u{1F4DD}\", label: `error: ${ctx.errorMessage ?? \"\"}` };\n    }\n    try {\n      await writeFn(definition);\n      return {\n        icon: \"\\u{1F310}\",\n        label: ctx.reason === \"silent-ignore\" ? \"source definition (silent-ignore fallback)\" : \"source definition\"\n      };\n    } catch (defErr) {\n      const defMsg = String(defErr?.message ?? defErr);\n      const isRemoteReadOnly = definition.remote === true || /read-only/i.test(defMsg);\n      if (ctx.categories) {\n        upsertCanicodeAnnotation(ctx.scene, {\n          ruleId: ctx.question.ruleId,\n          markdown: buildDefinitionTierFailureBody({\n            ruleId: ctx.question.ruleId,\n            sceneNodeId: ctx.scene.id,\n            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {},\n            kind: isRemoteReadOnly ? \"read-only-library\" : \"definition-error\",\n            errorMessage: defMsg\n          }),\n          categoryId: categoryIdForAnnotate(\n            ctx.categories,\n            \"other-failure\",\n            ctx.roundtripIntent\n          )\n        });\n      }\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: isRemoteReadOnly ? \"external library (read-only)\" : `definition error: ${defMsg}`\n      };\n    }\n  }\n  async function applyWithInstanceFallback(question, writeFn, context = {}) {\n    const { categories, allowDefinitionWrite = false, telemetry, roundtripIntent } = context;\n    const scene = await figma.getNodeByIdAsync(question.nodeId);\n    if (!scene) return { icon: \"\\u{1F4DD}\", label: \"missing node\" };\n    const definition = question.sourceChildId ? await figma.getNodeByIdAsync(question.sourceChildId) : null;\n    try {\n      const changed = await writeFn(scene);\n      if (changed === false) {\n        return routeToDefinitionOrAnnotate(definition, writeFn, {\n          question,\n          scene,\n          categories,\n          reason: \"silent-ignore\",\n          allowDefinitionWrite,\n          telemetry,\n          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n        });\n      }\n      return { icon: \"\\u2705\", label: \"instance/scene\" };\n    } catch (e) {\n      const msg = String(e?.message ?? e);\n      const looksLikeInstanceOverride = /cannot be overridden/i.test(msg) || /override/i.test(msg);\n      if (!looksLikeInstanceOverride) {\n        return routeToDefinitionOrAnnotate(null, writeFn, {\n          question,\n          scene,\n          categories,\n          reason: \"non-override-error\",\n          errorMessage: msg,\n          allowDefinitionWrite,\n          telemetry,\n          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n        });\n      }\n      return routeToDefinitionOrAnnotate(definition, writeFn, {\n        question,\n        scene,\n        categories,\n        reason: \"override-error\",\n        errorMessage: msg,\n        allowDefinitionWrite,\n        telemetry,\n        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n      });\n    }\n  }\n\n  // src/core/roundtrip/apply-property-mod.ts\n  async function resolveVariableByName(name) {\n    const locals = await figma.variables.getLocalVariablesAsync();\n    return locals.find((v) => v.name === name) ?? null;\n  }\n  function parseValue(raw) {\n    if (raw && typeof raw === \"object\" && \"variable\" in raw) {\n      const v = raw;\n      const parsed = { kind: \"binding\", name: v.variable };\n      if (\"fallback\" in v) parsed.fallback = v.fallback;\n      return parsed;\n    }\n    if (raw && typeof raw === \"object\" && \"fallback\" in raw) {\n      return { kind: \"scalar\", scalar: raw.fallback };\n    }\n    return { kind: \"scalar\", scalar: raw };\n  }\n  function isPaintProp(prop) {\n    return prop === \"fills\" || prop === \"strokes\";\n  }\n  function applyPropertyBinding(target, prop, variable) {\n    if (isPaintProp(prop)) {\n      const current = target[prop];\n      if (current === figma.mixed || !Array.isArray(current)) return false;\n      const paints = current;\n      const bound = paints.map(\n        (paint) => figma.variables.setBoundVariableForPaint(paint, \"color\", variable)\n      );\n      target[prop] = bound;\n      return true;\n    }\n    target.setBoundVariable(prop, variable);\n    return true;\n  }\n  function buildRoundtripIntentFromPropertyAnswer(question, answerValue) {\n    const raw = question.targetProperty;\n    if (raw === void 0) return void 0;\n    const props = Array.isArray(raw) ? raw : [raw];\n    if (props.length === 0) return void 0;\n    if (props.length === 1) {\n      const prop = props[0];\n      const perProp = answerValue && typeof answerValue === \"object\" && !(\"variable\" in answerValue) && !Array.isArray(answerValue) ? answerValue[prop] : answerValue;\n      const parsed = parseValueForIntent(perProp);\n      if (parsed === void 0) return void 0;\n      return { field: prop, value: parsed, scope: \"instance\" };\n    }\n    const obj = answerValue && typeof answerValue === \"object\" && !(\"variable\" in answerValue) && !Array.isArray(answerValue) ? answerValue : void 0;\n    const picked = {};\n    for (const p of props) {\n      if (obj && p in obj && obj[p] !== void 0) picked[p] = obj[p];\n    }\n    if (Object.keys(picked).length === 0) return void 0;\n    return {\n      field: props.join(\", \"),\n      value: picked,\n      scope: \"instance\"\n    };\n  }\n  function parseValueForIntent(raw) {\n    if (raw && typeof raw === \"object\" && \"variable\" in raw) {\n      return { variable: raw.variable };\n    }\n    if (raw && typeof raw === \"object\" && \"fallback\" in raw) {\n      return raw.fallback;\n    }\n    return raw;\n  }\n  function applyPropertyScalar(target, prop, scalar) {\n    const rec = target;\n    const before = rec[prop];\n    rec[prop] = scalar;\n    if (rec[prop] === before && before !== scalar) return false;\n    return true;\n  }\n  async function applyPropertyMod(question, answerValue, context = {}) {\n    const roundtripIntent = buildRoundtripIntentFromPropertyAnswer(\n      question,\n      answerValue\n    );\n    const props = Array.isArray(question.targetProperty) ? question.targetProperty : question.targetProperty !== void 0 ? [question.targetProperty] : [];\n    return applyWithInstanceFallback(\n      question,\n      async (target) => {\n        if (!target) return void 0;\n        let changed = void 0;\n        for (const prop of props) {\n          if (!(prop in target)) continue;\n          const perProp = answerValue && typeof answerValue === \"object\" && !(\"variable\" in answerValue) && !Array.isArray(answerValue) ? answerValue[prop] : answerValue;\n          const parsed = parseValue(perProp);\n          if (parsed.kind === \"binding\") {\n            const variable = await resolveVariableByName(parsed.name);\n            if (variable) {\n              applyPropertyBinding(target, prop, variable);\n              continue;\n            }\n            if (parsed.fallback !== void 0) {\n              if (!applyPropertyScalar(target, prop, parsed.fallback)) {\n                changed = false;\n              }\n            }\n            continue;\n          }\n          if (parsed.scalar === void 0) continue;\n          if (!applyPropertyScalar(target, prop, parsed.scalar)) {\n            changed = false;\n          }\n        }\n        return changed;\n      },\n      {\n        ...context,\n        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}\n      }\n    );\n  }\n\n  // src/core/roundtrip/probe-definition-writability.ts\n  async function probeDefinitionWritability(questions) {\n    const verdict = /* @__PURE__ */ new Map();\n    const unwritableNames = [];\n    const seenName = /* @__PURE__ */ new Set();\n    for (const q of questions) {\n      const id = q.sourceChildId;\n      if (!id) continue;\n      if (verdict.has(id)) continue;\n      const node = await figma.getNodeByIdAsync(id);\n      const writability = resolveWritability(node);\n      const isUnwritable = writability.isUnwritable;\n      verdict.set(id, isUnwritable ? \"unwritable\" : \"writable\");\n      if (isUnwritable) {\n        const name = typeof writability.componentName === \"string\" && writability.componentName || typeof node?.name === \"string\" && node.name || q.instanceContext?.sourceComponentName || id;\n        if (!seenName.has(name)) {\n          seenName.add(name);\n          unwritableNames.push(name);\n        }\n      }\n    }\n    const totalCount = verdict.size;\n    let unwritableCount = 0;\n    for (const v of verdict.values()) if (v === \"unwritable\") unwritableCount++;\n    return {\n      totalCount,\n      unwritableCount,\n      unwritableSourceNames: unwritableNames,\n      allUnwritable: totalCount > 0 && unwritableCount === totalCount,\n      partiallyUnwritable: unwritableCount > 0 && unwritableCount < totalCount\n    };\n  }\n  function resolveWritability(node) {\n    if (node === null) return { isUnwritable: true };\n    if (\"remote\" in node && typeof node.remote === \"boolean\") {\n      return { isUnwritable: node.remote === true };\n    }\n    const containing = findContainingComponent(node);\n    if (!containing) {\n      return { isUnwritable: false };\n    }\n    const isUnwritable = \"remote\" in containing && containing.remote === true;\n    return {\n      isUnwritable,\n      ...isUnwritable && typeof containing.name === \"string\" ? { componentName: containing.name } : {}\n    };\n  }\n  function findContainingComponent(node) {\n    let cur = node;\n    for (let i = 0; i < 100 && cur; i++) {\n      if (cur.type === \"COMPONENT\" || cur.type === \"COMPONENT_SET\") return cur;\n      cur = cur.parent ?? null;\n    }\n    return null;\n  }\n\n  // src/core/roundtrip/read-acknowledgments.ts\n  var FOOTER_RE = /—\\s+\\*([A-Za-z0-9-]+)\\*\\s*$/;\n  var LEGACY_PREFIX_RE = /^\\*\\*\\[canicode\\]\\s+([A-Za-z0-9-]+)\\*\\*/;\n  function extractAcknowledgmentsFromNode(node, canicodeCategoryIds) {\n    if (!node || !(\"annotations\" in node)) return [];\n    const annotations = node.annotations ?? [];\n    if (annotations.length === 0) return [];\n    const out = [];\n    for (const a of annotations) {\n      const text = (typeof a.labelMarkdown === \"string\" && a.labelMarkdown.length > 0 ? a.labelMarkdown : \"\") || (typeof a.label === \"string\" && a.label.length > 0 ? a.label : \"\");\n      if (!text) continue;\n      if (canicodeCategoryIds) {\n        if (!a.categoryId || !canicodeCategoryIds.has(a.categoryId)) continue;\n      }\n      const ruleId = extractRuleId(text);\n      if (!ruleId) continue;\n      const payload = parseCanicodeJsonPayloadFromMarkdown(text);\n      const payloadAligned = payload && payload.ruleId === ruleId;\n      out.push({\n        nodeId: node.id,\n        ruleId,\n        ...payloadAligned && payload.intent ? { intent: payload.intent } : {},\n        ...payloadAligned && payload.sceneWriteOutcome ? { sceneWriteOutcome: payload.sceneWriteOutcome } : {},\n        ...payloadAligned && payload.codegenDirective ? { codegenDirective: payload.codegenDirective } : {}\n      });\n    }\n    return out;\n  }\n  function extractRuleId(text) {\n    const footer = FOOTER_RE.exec(text);\n    if (footer) return footer[1] ?? null;\n    const legacy = LEGACY_PREFIX_RE.exec(text);\n    if (legacy) return legacy[1] ?? null;\n    return null;\n  }\n  async function readCanicodeAcknowledgments(rootNodeId, categories) {\n    const root = await figma.getNodeByIdAsync(rootNodeId);\n    if (!root) return [];\n    const canicodeCategoryIds = categories ? new Set(\n      [\n        categories.gotcha,\n        categories.flag,\n        categories.fallback,\n        categories.legacyAutoFix\n      ].filter((id) => typeof id === \"string\" && id.length > 0)\n    ) : void 0;\n    const out = [];\n    walk(root, canicodeCategoryIds, out);\n    return out;\n  }\n  function safeChildren(node) {\n    try {\n      const c = node.children;\n      return Array.isArray(c) ? c : [];\n    } catch {\n      return [];\n    }\n  }\n  function walk(node, canicodeCategoryIds, out) {\n    try {\n      const local = extractAcknowledgmentsFromNode(node, canicodeCategoryIds);\n      for (const a of local) out.push(a);\n    } catch {\n    }\n    for (const child of safeChildren(node)) {\n      if (child && typeof child === \"object\") walk(child, canicodeCategoryIds, out);\n    }\n  }\n\n  // src/core/roundtrip/apply-unmapped-component-opt-out.ts\n  async function applyUnmappedComponentOptOut(input, context) {\n    const { nodeId, ruleId } = input;\n    const { categories } = context;\n    const scene = await figma.getNodeByIdAsync(nodeId);\n    if (!scene) {\n      return { icon: \"\\u{1F4DD}\", label: `missing node \\u2014 ${ruleId}` };\n    }\n    const markdown = buildIntentionallyUnmappedAnnotationBody({\n      sceneNodeId: scene.id,\n      ruleId\n    });\n    upsertCanicodeAnnotation(scene, {\n      ruleId,\n      markdown,\n      categoryId: categories.gotcha\n    });\n    return { icon: \"\\u{1F4DD}\", label: `opt-out annotation written \\u2014 ${ruleId}` };\n  }\n\n  // src/core/roundtrip/compute-roundtrip-tally.ts\n  function computeRoundtripTally(args) {\n    const { stepFourReport, reanalyzeResponse } = args;\n    const { resolved, annotated, definitionWritten, skipped } = stepFourReport;\n    const { issueCount, acknowledgedCount } = reanalyzeResponse;\n    if (acknowledgedCount > issueCount) {\n      throw new Error(\n        `computeRoundtripTally: reanalyzeResponse.acknowledgedCount (${acknowledgedCount}) cannot exceed issueCount (${issueCount}). Acknowledged issues are a subset of remaining issues.`\n      );\n    }\n    return {\n      X: resolved,\n      Y: annotated,\n      Z: definitionWritten,\n      W: skipped,\n      N: resolved + annotated + definitionWritten + skipped,\n      V: issueCount,\n      V_ack: acknowledgedCount,\n      V_open: issueCount - acknowledgedCount\n    };\n  }\n\n  // src/core/roundtrip/apply-auto-fix.ts\n  function pickNodeName(issue, resolved) {\n    if (resolved && typeof resolved.name === \"string\" && resolved.name.length > 0) {\n      return resolved.name;\n    }\n    if (typeof issue.nodePath === \"string\" && issue.nodePath.length > 0) {\n      const segments = issue.nodePath.split(/\\s*[›>/]\\s*/);\n      const tail = segments[segments.length - 1];\n      if (tail && tail.length > 0) return tail;\n    }\n    return issue.nodeId;\n  }\n  function mapInstanceFallbackIcon(result) {\n    if (result.icon === \"\\u2705\") return \"\\u{1F527}\";\n    return result.icon;\n  }\n  async function applyAutoFix(issue, context) {\n    const { categories } = context;\n    const ruleId = issue.ruleId;\n    if (issue.targetProperty === \"name\" && typeof issue.suggestedName === \"string\") {\n      const suggestedName = issue.suggestedName;\n      const question = {\n        nodeId: issue.nodeId,\n        ruleId,\n        ...issue.sourceChildId ? { sourceChildId: issue.sourceChildId } : {}\n      };\n      const result = await applyWithInstanceFallback(\n        question,\n        (target) => {\n          if (target) {\n            target.name = suggestedName;\n          }\n        },\n        {\n          categories,\n          ...context.allowDefinitionWrite !== void 0 ? { allowDefinitionWrite: context.allowDefinitionWrite } : {},\n          ...context.telemetry !== void 0 ? { telemetry: context.telemetry } : {}\n        }\n      );\n      const sceneAfter = await figma.getNodeByIdAsync(issue.nodeId);\n      return {\n        outcome: mapInstanceFallbackIcon(result),\n        nodeId: issue.nodeId,\n        nodeName: pickNodeName(issue, sceneAfter),\n        ruleId,\n        label: result.label\n      };\n    }\n    const scene = await figma.getNodeByIdAsync(issue.nodeId);\n    const markdown = issue.message ?? `Auto-flagged: ${ruleId}`;\n    if (scene) {\n      upsertCanicodeAnnotation(scene, {\n        ruleId,\n        markdown,\n        categoryId: categories.flag,\n        ...issue.annotationProperties && issue.annotationProperties.length > 0 ? { properties: issue.annotationProperties } : {}\n      });\n    }\n    return {\n      outcome: \"\\u{1F4DD}\",\n      nodeId: issue.nodeId,\n      nodeName: pickNodeName(issue, scene),\n      ruleId,\n      label: scene ? `annotation added to canicode:flag \\u2014 ${ruleId}` : `missing node (annotation skipped) \\u2014 ${ruleId}`\n    };\n  }\n  async function applyAutoFixes(issues, context) {\n    const out = [];\n    for (const issue of issues) {\n      if (issue.applyStrategy !== \"auto-fix\") {\n        out.push({\n          outcome: \"\\u23ED\\uFE0F\",\n          nodeId: issue.nodeId,\n          nodeName: pickNodeName(issue, null),\n          ruleId: issue.ruleId,\n          label: `skipped \\u2014 applyStrategy is ${issue.applyStrategy ?? \"absent\"}`\n        });\n        continue;\n      }\n      out.push(await applyAutoFix(issue, context));\n    }\n    return out;\n  }\n\n  // src/core/roundtrip/apply-componentize.ts\n  var COMPONENTIZE_EVENT = \"cic_roundtrip_componentize\";\n  function isInsideInstance(node) {\n    let current = node.parent;\n    while (current) {\n      if (current.type === \"INSTANCE\") return true;\n      current = current.parent;\n    }\n    return false;\n  }\n  function isFreeFormParent(node) {\n    const parent = node.parent;\n    if (!parent) return true;\n    const layoutMode = parent[\"layoutMode\"];\n    return layoutMode === void 0 || layoutMode === \"NONE\";\n  }\n  function resolveFinalName(desired, existing) {\n    if (!existing.has(desired)) {\n      return { finalName: desired, collisionResolved: false };\n    }\n    let counter = 2;\n    while (existing.has(`${desired} ${counter}`)) counter++;\n    return { finalName: `${desired} ${counter}`, collisionResolved: true };\n  }\n  function annotateFallback(node, ruleId, categories, body) {\n    if (!categories) return;\n    upsertCanicodeAnnotation(node, {\n      ruleId,\n      markdown: body,\n      categoryId: categories.flag\n    });\n  }\n  function applyComponentize(options) {\n    const { node, existingComponentNames, ruleId, categories, telemetry } = options;\n    if (isInsideInstance(node)) {\n      annotateFallback(\n        node,\n        ruleId,\n        categories,\n        `**Componentize skipped \\u2014 node is inside an INSTANCE subtree.**\n\nRe-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.`\n      );\n      telemetry?.(COMPONENTIZE_EVENT, {\n        ruleId,\n        outcome: \"skipped-inside-instance\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"componentize skipped: inside instance\",\n        outcome: \"skipped-inside-instance\"\n      };\n    }\n    if (isFreeFormParent(node)) {\n      annotateFallback(\n        node,\n        ruleId,\n        categories,\n        `**Componentize skipped \\u2014 parent has no Auto Layout.**\n\nComponentizing 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.`\n      );\n      telemetry?.(COMPONENTIZE_EVENT, {\n        ruleId,\n        outcome: \"skipped-free-form-parent\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"componentize skipped: free-form parent\",\n        outcome: \"skipped-free-form-parent\"\n      };\n    }\n    const desiredName = typeof node.name === \"string\" ? node.name : \"Component\";\n    const { finalName, collisionResolved } = resolveFinalName(\n      desiredName,\n      existingComponentNames\n    );\n    const create = figma.createComponentFromNode;\n    if (typeof create !== \"function\") {\n      annotateFallback(\n        node,\n        ruleId,\n        categories,\n        `**Componentize skipped \\u2014 \\`figma.createComponentFromNode\\` unavailable.**\n\nThe Plugin API host did not expose the Create component primitive in this session. The FRAME has been flagged so the next roundtrip can retry.`\n      );\n      telemetry?.(COMPONENTIZE_EVENT, {\n        ruleId,\n        outcome: \"error\",\n        reason: \"createComponentFromNode-missing\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"componentize skipped: createComponentFromNode unavailable\",\n        outcome: \"error\"\n      };\n    }\n    try {\n      const created = create.call(figma, node);\n      created.name = finalName;\n      telemetry?.(COMPONENTIZE_EVENT, {\n        ruleId,\n        outcome: \"componentized\",\n        nameCollisionResolved: collisionResolved\n      });\n      const result = {\n        icon: \"\\u2705\",\n        label: collisionResolved ? `componentized as \"${finalName}\" (renamed from collision)` : `componentized as \"${finalName}\"`,\n        outcome: \"componentized\",\n        newComponentId: created.id,\n        finalName\n      };\n      if (collisionResolved) result.nameCollisionResolved = true;\n      return result;\n    } catch (e) {\n      const msg = String(e?.message ?? e);\n      annotateFallback(\n        node,\n        ruleId,\n        categories,\n        `**Componentize failed \\u2014 \\`createComponentFromNode\\` threw.**\n\nError: \\`${msg}\\`. The FRAME has been flagged so the designer can inspect the structure (locked layer, unsupported child mix, etc.) before the next roundtrip pass.`\n      );\n      telemetry?.(COMPONENTIZE_EVENT, {\n        ruleId,\n        outcome: \"error\",\n        reason: msg\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: `componentize failed: ${msg}`,\n        outcome: \"error\"\n      };\n    }\n  }\n\n  // src/core/roundtrip/apply-replace-with-instance.ts\n  var REPLACE_EVENT = \"cic_roundtrip_replace_with_instance\";\n  function isFreeFormParent2(parent) {\n    if (!parent) return true;\n    const layoutMode = parent[\"layoutMode\"];\n    return layoutMode === void 0 || layoutMode === \"NONE\";\n  }\n  function annotateFallback2(node, ruleId, categories, body) {\n    if (!node || !categories) return;\n    upsertCanicodeAnnotation(node, {\n      ruleId,\n      markdown: body,\n      categoryId: categories.flag\n    });\n  }\n  function isComponentLike(type) {\n    return type === \"COMPONENT\" || type === \"COMPONENT_SET\";\n  }\n  async function applyReplaceWithInstance(options) {\n    const { mainComponentId, targetNodeId, ruleId, categories, telemetry } = options;\n    const [target, main] = await Promise.all([\n      figma.getNodeByIdAsync(targetNodeId),\n      figma.getNodeByIdAsync(mainComponentId)\n    ]);\n    if (!target) {\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"skipped-prereq-missing\",\n        reason: \"target-missing\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: `replace skipped: target node ${targetNodeId} missing`,\n        outcome: \"skipped-prereq-missing\"\n      };\n    }\n    if (!main) {\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace skipped \\u2014 main component \\`${mainComponentId}\\` not found.**\n\nThe 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.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"skipped-prereq-missing\",\n        reason: \"main-missing\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: `replace skipped: main ${mainComponentId} missing`,\n        outcome: \"skipped-prereq-missing\"\n      };\n    }\n    if (!isComponentLike(main.type)) {\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace skipped \\u2014 \\`${mainComponentId}\\` is not a COMPONENT.**\n\nResolved 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.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"skipped-prereq-missing\",\n        reason: \"main-not-component\",\n        resolvedType: main.type\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: `replace skipped: main is ${main.type}, not COMPONENT`,\n        outcome: \"skipped-prereq-missing\"\n      };\n    }\n    if (target.id === main.id) {\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace skipped \\u2014 target and main are the same node.**\n\nThis 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.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"skipped-prereq-missing\",\n        reason: \"target-is-main\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"replace skipped: target equals main\",\n        outcome: \"skipped-prereq-missing\"\n      };\n    }\n    const parent = target.parent;\n    if (!parent) {\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace skipped \\u2014 target has no parent.**\n\nCannot insert a new instance for an orphaned node. The FRAME has been flagged; no swap performed.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"skipped-prereq-missing\",\n        reason: \"no-parent\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"replace skipped: no parent\",\n        outcome: \"skipped-prereq-missing\"\n      };\n    }\n    if (isFreeFormParent2(parent)) {\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace skipped \\u2014 parent has no Auto Layout.**\n\nSwapping 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.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"skipped-free-form-parent\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"replace skipped: free-form parent\",\n        outcome: \"skipped-free-form-parent\"\n      };\n    }\n    const create = main.createInstance;\n    if (typeof create !== \"function\") {\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace skipped \\u2014 \\`createInstance\\` unavailable on main.**\n\nThe 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.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"error\",\n        reason: \"createInstance-missing\"\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: \"replace skipped: createInstance unavailable\",\n        outcome: \"error\"\n      };\n    }\n    try {\n      const instance = create.call(main);\n      const siblings = parent.children ?? [];\n      const idx = siblings.findIndex((s) => s.id === target.id);\n      const insert = parent.insertChild;\n      const append = parent.appendChild;\n      if (idx >= 0 && typeof insert === \"function\") {\n        insert.call(parent, idx, instance);\n      } else if (typeof append === \"function\") {\n        append.call(parent, instance);\n      } else {\n        throw new Error(\n          \"parent exposes neither insertChild nor appendChild \\u2014 cannot insert instance\"\n        );\n      }\n      if (typeof target.remove === \"function\") {\n        target.remove();\n      } else {\n        throw new Error(\"target node missing `remove` \\u2014 cannot detach old FRAME\");\n      }\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"replaced\"\n      });\n      return {\n        icon: \"\\u2705\",\n        label: `replaced with instance of \"${main.name}\"`,\n        outcome: \"replaced\",\n        newInstanceId: instance.id\n      };\n    } catch (e) {\n      const msg = String(e?.message ?? e);\n      annotateFallback2(\n        target,\n        ruleId,\n        categories,\n        `**Replace failed \\u2014 Plugin API threw.**\n\nError: \\`${msg}\\`. The FRAME has been flagged so the designer can inspect (locked layer, parent restrictions, etc.) before the next roundtrip pass.`\n      );\n      telemetry?.(REPLACE_EVENT, {\n        ruleId,\n        outcome: \"error\",\n        reason: msg\n      });\n      return {\n        icon: \"\\u{1F4DD}\",\n        label: `replace failed: ${msg}`,\n        outcome: \"error\"\n      };\n    }\n  }\n\n  // src/core/roundtrip/apply-group-componentize.ts\n  function summarizeReplaceCounts(results) {\n    const total = results.length;\n    if (total === 0) return \"\";\n    const replaced = results.filter((r) => r.outcome === \"replaced\").length;\n    const reasons = [];\n    const freeForm = results.filter(\n      (r) => r.outcome === \"skipped-free-form-parent\"\n    ).length;\n    const prereq = results.filter(\n      (r) => r.outcome === \"skipped-prereq-missing\"\n    ).length;\n    const error = results.filter((r) => r.outcome === \"error\").length;\n    if (freeForm > 0) reasons.push(`${freeForm} free-form parent`);\n    if (prereq > 0) reasons.push(`${prereq} prereq missing`);\n    if (error > 0) reasons.push(`${error} error`);\n    const tail = reasons.length > 0 ? ` (${reasons.join(\", \")})` : \"\";\n    return `swapped ${replaced}/${total} siblings${tail}`;\n  }\n  async function applyGroupComponentize(options) {\n    const { question, existingComponentNames, categories, telemetry } = options;\n    const members = question.groupMembers;\n    const firstId = members[0];\n    if (firstId === void 0) {\n      return {\n        outcome: \"missing-first-member\",\n        replaceResults: [],\n        summary: \"group componentize skipped: no members in group\"\n      };\n    }\n    const firstNode = await figma.getNodeByIdAsync(firstId);\n    if (!firstNode) {\n      return {\n        outcome: \"missing-first-member\",\n        replaceResults: [],\n        summary: `group componentize skipped: first member ${firstId} not found`\n      };\n    }\n    const componentizeResult = applyComponentize({\n      node: firstNode,\n      existingComponentNames,\n      ruleId: question.ruleId,\n      ...categories !== void 0 ? { categories } : {},\n      ...telemetry !== void 0 ? { telemetry } : {}\n    });\n    if (componentizeResult.outcome !== \"componentized\") {\n      return {\n        outcome: \"componentize-failed\",\n        componentizeResult,\n        replaceResults: [],\n        summary: `group componentize skipped: ${componentizeResult.label}`\n      };\n    }\n    const newComponentId = componentizeResult.newComponentId;\n    const swapTargets = members.slice(1);\n    const replaceResults = [];\n    for (const targetId of swapTargets) {\n      const r = await applyReplaceWithInstance({\n        mainComponentId: newComponentId,\n        targetNodeId: targetId,\n        ruleId: question.ruleId,\n        ...categories !== void 0 ? { categories } : {},\n        ...telemetry !== void 0 ? { telemetry } : {}\n      });\n      replaceResults.push(r);\n    }\n    const swapSummary = summarizeReplaceCounts(replaceResults);\n    const finalName = componentizeResult.finalName ?? \"(unnamed)\";\n    const summary = swapSummary.length > 0 ? `componentized \"${finalName}\", ${swapSummary}` : `componentized \"${finalName}\"`;\n    return {\n      outcome: \"componentized-and-swapped\",\n      componentizeResult,\n      replaceResults,\n      summary\n    };\n  }\n\n  // src/core/roundtrip/remove-canicode-annotations.ts\n  var LEGACY_CANICODE_PREFIX = \"**[canicode]\";\n  function isCanicodeAnnotation(annotation, categories) {\n    const canicodeIds = new Set(\n      [\n        categories.gotcha,\n        categories.flag,\n        categories.fallback,\n        categories.legacyAutoFix\n      ].filter((id) => Boolean(id))\n    );\n    if (annotation.categoryId && canicodeIds.has(annotation.categoryId)) {\n      return true;\n    }\n    if (annotation.labelMarkdown?.startsWith(LEGACY_CANICODE_PREFIX)) {\n      return true;\n    }\n    return false;\n  }\n  function removeCanicodeAnnotations(annotations, categories) {\n    return annotations.filter((a) => !isCanicodeAnnotation(a, categories));\n  }\n\n  exports.applyAutoFix = applyAutoFix;\n  exports.applyAutoFixes = applyAutoFixes;\n  exports.applyComponentize = applyComponentize;\n  exports.applyGroupComponentize = applyGroupComponentize;\n  exports.applyPropertyMod = applyPropertyMod;\n  exports.applyReplaceWithInstance = applyReplaceWithInstance;\n  exports.applyUnmappedComponentOptOut = applyUnmappedComponentOptOut;\n  exports.applyWithInstanceFallback = applyWithInstanceFallback;\n  exports.buildIntentionallyUnmappedAnnotationBody = buildIntentionallyUnmappedAnnotationBody;\n  exports.computeRoundtripTally = computeRoundtripTally;\n  exports.ensureCanicodeCategories = ensureCanicodeCategories;\n  exports.extractAcknowledgmentsFromNode = extractAcknowledgmentsFromNode;\n  exports.isCanicodeAnnotation = isCanicodeAnnotation;\n  exports.probeDefinitionWritability = probeDefinitionWritability;\n  exports.readCanicodeAcknowledgments = readCanicodeAcknowledgments;\n  exports.removeCanicodeAnnotations = removeCanicodeAnnotations;\n  exports.resolveVariableByName = resolveVariableByName;\n  exports.stripAnnotations = stripAnnotations;\n  exports.upsertCanicodeAnnotation = upsertCanicodeAnnotation;\n\n  return exports;\n\n})({});\n\n;globalThis.CanICodeRoundtrip = CanICodeRoundtrip;\n";
+var __CANICODE_HELPERS_VERSION__ = "0.12.3";
 (0, eval)(__CANICODE_HELPERS_SRC__);
 try {
   figma.root.setSharedPluginData("canicode", "helpersSrc", __CANICODE_HELPERS_SRC__);

package/skills/cursor/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;