fix: Code Connect using variant node IDs instead of component set node IDs (#55)

* fix(icons): use component set node IDs for Code Connect instead of variant node IDs

Figma Code Connect API requires top-level component or component set node IDs,
but ExFig was passing variant node IDs (e.g. RTL=Off) which caused publish errors:
"node is not a top level component or component set"

Add `codeConnectNodeId` computed property on Component that returns the parent
component set nodeId for variants and own nodeId for regular components. Apply it
to AssetMetadata and ImagePack construction in all code paths.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: update cluade.md

* fix: after review

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: alexey1312

CLAUDE.md

@@ -247,10 +247,20 @@ as string literals in ExFigCore inits; use shared constants only within ExFigCLI
 ### RTL Detection Design
 
 - `Component.iconName`: uses `containingComponentSet.name` for variants, own `name` otherwise
+- `Component.codeConnectNodeId`: uses `containingComponentSet.nodeId` for variants, own `nodeId` otherwise (Figma Code Connect rejects variant node IDs)
 - `Component.defaultRTLProperty = "RTL"`: shared constant in ExFigCLI for the magic string
 - PNG images intentionally do NOT carry `isRTL` — raster images skip mirroring by design
 - `buildPairedComponents` must use `iconName` (not `name`) — variant `name` is `"RTL=Off"`, not the icon name
 
+### Modifying Node ID Logic (AssetMetadata / ImagePack)
+
+When changing how node IDs are resolved (e.g., `codeConnectNodeId`), update ALL construction sites in `ImageLoaderBase.swift`:
+
+1. `AssetMetadata` in `fetchImageComponentsWithGranularCache` (~line 156)
+2. `AssetMetadata` in `fetchImageComponentsWithGranularCacheAndPairing` (~line 220)
+3. `ImagePack` primaryNodeId in `loadVectorImages` (vector/SVG path)
+4. `ImagePack` primaryNodeId in `loadPNGImages` (raster path)
+
 ### Adding a CLI Command
 
 1. Create `Sources/ExFigCLI/Subcommands/NewCommand.swift` implementing `AsyncParsableCommand`

Sources/ExFigCLI/Loaders/ImageLoaderBase.swift

@@ -152,9 +152,10 @@ class ImageLoaderBase: @unchecked Sendable {
         )
 
         // Build metadata for all assets (for Code Connect and template generation)
-        // Use iconName to get the real name (component set name for variants)
-        let allAssetMetadata = allComponents.map { nodeId, component in
-            AssetMetadata(name: component.iconName, nodeId: nodeId, fileId: fileId)
+        // Use component set data for variants: iconName for name, codeConnectNodeId for node ID.
+        // Figma Code Connect rejects variant node IDs — requires top-level component/component set IDs.
+        let allAssetMetadata = allComponents.map { _, component in
+            AssetMetadata(name: component.iconName, nodeId: component.codeConnectNodeId, fileId: fileId)
         }
 
         guard let manager = granularCacheManager, !allComponents.isEmpty else {
@@ -216,8 +217,8 @@ class ImageLoaderBase: @unchecked Sendable {
         let allComponents = try await fetchImageComponents(
             fileId: fileId, frameName: frameName, pageName: pageName, filter: filter, rtlProperty: rtlProperty
         )
-        let allAssetMetadata = allComponents.map { nodeId, component in
-            AssetMetadata(name: component.iconName, nodeId: nodeId, fileId: fileId)
+        let allAssetMetadata = allComponents.map { _, component in
+            AssetMetadata(name: component.iconName, nodeId: component.codeConnectNodeId, fileId: fileId)
         }
 
         guard let manager = granularCacheManager, !allComponents.isEmpty else {
@@ -505,7 +506,7 @@ class ImageLoaderBase: @unchecked Sendable {
                     isRTL: component.useRTL(rtlProperty: rtlProperty)
                 )
             }
-            let primaryNodeId = components.first?.0
+            let primaryNodeId = components.first.map(\.1.codeConnectNodeId)
             return ImagePack(
                 name: packName,
                 images: packImages,
@@ -645,7 +646,7 @@ class ImageLoaderBase: @unchecked Sendable {
                     )
                 }
             }
-            let primaryNodeId = components.first?.0
+            let primaryNodeId = components.first.map(\.1.codeConnectNodeId)
             return ImagePack(
                 name: packName,
                 images: packImages,
@@ -892,6 +893,13 @@ public extension Component {
         containingFrame.containingComponentSet?.name ?? name
     }
 
+    /// Node ID for Code Connect: component set ID for variants, own ID otherwise.
+    /// Figma Code Connect rejects variant node IDs — use this to avoid
+    /// "node is not a top level component or component set" errors.
+    var codeConnectNodeId: String {
+        containingFrame.containingComponentSet?.nodeId ?? nodeId
+    }
+
     /// Extracts the RTL variant value from the component name (e.g. "Off" from "RTL=Off").
     /// Parses "Property=Value, Property2=Value2" format used by Figma variant components.
     func rtlVariantValue(propertyName: String) -> String? {

Tests/ExFigTests/Loaders/ComponentRTLTests.swift

@@ -156,6 +156,41 @@ final class ComponentRTLTests: XCTestCase {
         XCTAssertFalse(component.useRTL(rtlProperty: ""))
     }
 
+    // MARK: - codeConnectNodeId
+
+    func testCodeConnectNodeId_variantComponent_usesComponentSetNodeId() {
+        let component = makeComponent(
+            name: "RTL=Off",
+            componentSetName: "arrow-left"
+        )
+        // Component set nodeId is "99:0", own nodeId is "1:0"
+        XCTAssertEqual(component.codeConnectNodeId, "99:0")
+    }
+
+    func testCodeConnectNodeId_regularComponent_usesOwnNodeId() {
+        let component = makeComponent(name: "arrow-left")
+        XCTAssertEqual(component.codeConnectNodeId, "1:0")
+    }
+
+    func testCodeConnectNodeId_variantWithMultipleProperties_usesComponentSetNodeId() {
+        let component = makeComponent(
+            name: "State=Default, RTL=Off",
+            componentSetName: "new-orders"
+        )
+        XCTAssertEqual(component.codeConnectNodeId, "99:0")
+    }
+
+    func testCodeConnectNodeId_componentSetWithNilNodeId_fallsBackToOwnNodeId() {
+        // When containingComponentSet exists but has no nodeId (anomalous API response),
+        // should fall back to component's own nodeId
+        let component = makeComponent(
+            name: "RTL=Off",
+            componentSetName: "arrow-left",
+            componentSetNodeId: nil
+        )
+        XCTAssertEqual(component.codeConnectNodeId, "1:0")
+    }
+
     // MARK: - defaultRTLProperty
 
     func testDefaultRTLProperty() {
@@ -168,14 +203,21 @@ final class ComponentRTLTests: XCTestCase {
         name: String,
         description: String? = nil,
         frameName: String = "Icons",
-        componentSetName: String? = nil
+        componentSetName: String? = nil,
+        componentSetNodeId: String? = "99:0"
     ) -> Component {
         let descriptionField = description.map { ", \"description\": \"\($0)\"" } ?? ""
 
         let componentSetField = if let componentSetName {
-            """
-            , "containingComponentSet": { "nodeId": "99:0", "name": "\(componentSetName)" }
-            """
+            if let componentSetNodeId {
+                """
+                , "containingComponentSet": { "nodeId": "\(componentSetNodeId)", "name": "\(componentSetName)" }
+                """
+            } else {
+                """
+                , "containingComponentSet": { "name": "\(componentSetName)" }
+                """
+            }
         } else {
             ""
         }