@dannote/figma-use 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.8] - 2026-01-18
+
+### Added
+
+- `page create` command documented in SKILL.md
+- Auto-layout (hug contents) tests for render
+
+### Fixed
+
+- **JSX render hug contents** — auto-layout frames now correctly calculate size from children
+  - `trigger-layout` moved from proxy to CLI (ensures multiplayer nodes are visible)
+  - Plugin retries node lookup with exponential backoff
+  - Switching sizingMode FIXED→AUTO forces Figma to recalculate
+
 ## [0.5.7] - 2026-01-18
 
 ### Fixed

package/SKILL.md

@@ -51,6 +51,20 @@ echo '<Frame style={{padding: 24, gap: 16, flexDirection: "column", backgroundCo
 
 **Style props:** `width`, `height`, `x`, `y`, `padding`, `paddingTop/Right/Bottom/Left`, `gap`, `flexDirection` (row|column), `justifyContent`, `alignItems`, `backgroundColor`, `borderColor`, `borderWidth`, `borderRadius`, `opacity`, `fontSize`, `fontFamily`, `fontWeight`, `color`, `textAlign`
 
+### Auto-Layout (Hug Contents)
+
+Frames with `flexDirection` automatically calculate size from children:
+
+```bash
+# Height calculated as 50 + 10 (gap) + 30 = 90
+echo '<Frame style={{width: 200, flexDirection: "column", gap: 10}}>
+  <Frame style={{width: 200, height: 50, backgroundColor: "#00FF00"}} />
+  <Frame style={{width: 200, height: 30, backgroundColor: "#0000FF"}} />
+</Frame>' | figma-use render --stdin
+```
+
+**Limitation:** Row layout without explicit width collapses to 1×1 — always set `width` on row containers
+
 ### Buttons Example (3 sizes)
 
 Since stdin doesn't support variables, write out each variant explicitly:
@@ -101,6 +115,7 @@ figma-use render ./MyComponent.figma.tsx
 ### Create
 
 ```bash
+figma-use create page "Page Name"
 figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12 --layout VERTICAL --gap 16
 figma-use create rect --width 100 --height 50 --fill "#FF0000" --radius 8
 figma-use create ellipse --width 80 --height 80 --fill "#00FF00"
@@ -217,3 +232,86 @@ Hex format: `#RGB`, `#RRGGBB`, `#RRGGBBAA`
 ## Node IDs
 
 Format: `sessionID:localID` (e.g., `1:2`, `45:123`). Get from `figma-use selection get` or `figma-use node tree`.
+
+---
+
+## Best Practices
+
+### Always Verify Visually
+
+After any operation, export a screenshot to confirm the result:
+
+```bash
+figma-use export node <id> --scale 0.5 --output /tmp/check.png  # Overview
+figma-use export node <id> --scale 2 --output /tmp/detail.png   # Details
+```
+
+### Copying Elements Between Pages
+
+`node clone` creates a copy in the same parent. To move to another page:
+
+```bash
+figma-use node clone <source-id> --json | jq -r '.id'  # Get new ID
+figma-use node set-parent <new-id> --parent <target-page-or-frame-id>
+figma-use node move <new-id> --x 50 --y 50  # Reposition (coordinates reset)
+```
+
+### Working with Sections
+
+Sections organize components on a page. Elements must be explicitly moved inside:
+
+```bash
+figma-use create section --name "Buttons" --x 0 --y 0 --width 600 --height 200
+figma-use node set-parent <component-id> --parent <section-id>
+figma-use node move <component-id> --x 50 --y 50  # Position inside section
+```
+
+⚠️ **Deleting a section deletes all children inside it!**
+
+### Building a Component from Existing Design
+
+```bash
+# 1. Find and copy the element
+figma-use find --name "Button"
+figma-use node clone <id> --json | jq -r '.id'
+
+# 2. Move to components page/section
+figma-use node set-parent <new-id> --parent <section-id>
+figma-use node move <new-id> --x 50 --y 50
+
+# 3. Rename with proper naming convention
+figma-use node rename <new-id> "Button/Primary"
+
+# 4. Convert to component
+figma-use node to-component <new-id>
+
+# 5. Verify
+figma-use export node <section-id> --scale 0.5 --output /tmp/check.png
+```
+
+### Replacing Frames with Component Instances
+
+When copying a composite element (like a dialog), nested elements are frames, not instances. To use existing components:
+
+```bash
+# Delete the frame
+figma-use node delete <frame-id>
+
+# Create instance of the component
+figma-use create instance --component <component-id> --x 50 --y 50 --parent <parent-id>
+```
+
+### Instance Element IDs
+
+Elements inside instances have composite IDs: `I<instance-id>;<internal-id>`
+
+```bash
+figma-use set text "I123:456;789:10" "New text"  # Modify text inside instance
+```
+
+### Finding Elements by Properties
+
+```bash
+figma-use find --type FRAME 2>&1 | grep "stroke: #EF4444"  # Red border
+figma-use find --type TEXT 2>&1 | grep "Bold"              # Bold text
+```

package/dist/cli/index.js

@@ -27952,7 +27952,7 @@ function styleToNodeChange(type, props, localID, sessionID, parentGUID, position
       "flex-start": "MIN",
       center: "CENTER",
       "flex-end": "MAX",
-      "space-evenly": "SPACE_EVENLY"
+      "space-between": "SPACE_BETWEEN"
     };
     const mapped = validValues[style.justifyContent];
     if (mapped) {
@@ -28605,6 +28605,10 @@ var render_default = defineCommand({
       const pendingInstances = getPendingComponentSetInstances();
       clearPendingComponentSetInstances();
       await sendNodeChanges(result.nodeChanges, pendingInstances);
+      const rootId = `${result.nodeChanges[0].guid.sessionID}:${result.nodeChanges[0].guid.localID}`;
+      try {
+        await sendCommand("trigger-layout", { nodeId: rootId, pendingComponentSetInstances: pendingInstances });
+      } catch {}
       if (args.json) {
         const ids = result.nodeChanges.map((nc) => ({
           id: `${nc.guid.sessionID}:${nc.guid.localID}`,
@@ -29146,7 +29150,7 @@ var set_parent_default = defineCommand({
   },
   async run({ args }) {
     try {
-      const result = await sendCommand("set-parent", {
+      const result = await sendCommand("set-parent-id", {
         id: args.id,
         parentId: args.parent,
         index: args.index ? Number(args.index) : undefined

package/dist/proxy/index.js

@@ -178409,7 +178409,7 @@ enum StackJustify {
   MIN = 0;
   CENTER = 1;
   MAX = 2;
-  SPACE_EVENLY = 3;
+  SPACE_BETWEEN = 3;
 }
 
 enum StackSize {
@@ -209429,27 +209429,15 @@ new Elysia().ws("/plugin", {
   try {
     const { client, sessionID } = await getMultiplayerConnection(fileKey);
     consola.info(`render: ${nodeChanges.length} nodes to ${fileKey}`);
-    await client.sendNodeChangesSync(nodeChanges);
-    if (sendToPlugin) {
-      const rootId = `${nodeChanges[0].guid.sessionID}:${nodeChanges[0].guid.localID}`;
-      const layoutId = crypto.randomUUID();
-      try {
-        await new Promise((resolve, reject) => {
-          const timeout = setTimeout(() => {
-            pendingRequests.delete(layoutId);
-            reject(new Error("Layout trigger timeout"));
-          }, 5000);
-          pendingRequests.set(layoutId, { resolve: () => resolve(), reject, timeout });
-          sendToPlugin(JSON.stringify({
-            id: layoutId,
-            command: "trigger-layout",
-            args: {
-              nodeId: rootId,
-              pendingComponentSetInstances: body.pendingComponentSetInstances || []
-            }
-          }));
-        });
-      } catch {}
+    try {
+      await client.sendNodeChangesSync(nodeChanges);
+    } catch (codecError) {
+      const msg = codecError instanceof Error ? codecError.message : String(codecError);
+      if (msg.includes("Invalid value") && msg.includes("for enum")) {
+        consola.error("Codec error:", msg);
+        return { error: `Unsupported value in node properties: ${msg}` };
+      }
+      throw codecError;
     }
     const ids = nodeChanges.map((nc) => ({
       id: `${nc.guid.sessionID}:${nc.guid.localID}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dannote/figma-use",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Control Figma from the command line. Full read/write access for AI agents.",
   "type": "module",
   "bin": {

package/packages/cli/src/render/reconciler.ts

@@ -15,7 +15,7 @@
  * ### Auto-layout field names differ from Plugin API
  * - justifyContent → stackPrimaryAlignItems (not stackJustify)
  * - alignItems → stackCounterAlignItems (not stackCounterAlign)
- * - Valid values: 'MIN', 'CENTER', 'MAX', 'SPACE_EVENLY' (not 'SPACE_BETWEEN')
+ * - Valid values: 'MIN', 'CENTER', 'MAX', 'SPACE_BETWEEN', 'SPACE_EVENLY'
  * 
  * ### Sizing modes for auto-layout
  * - stackPrimarySizing/stackCounterSizing = 'FIXED' when explicit size given
@@ -247,10 +247,9 @@ function styleToNodeChange(
   // Alignment - NOTE: field names differ from Plugin API!
   // Plugin API uses primaryAxisAlignItems/counterAxisAlignItems
   // Multiplayer uses stackPrimaryAlignItems/stackCounterAlignItems
-  // Also: 'SPACE_BETWEEN' doesn't exist in multiplayer, only 'SPACE_EVENLY'
   if (style.justifyContent) {
     const validValues: Record<string, string> = {
-      'flex-start': 'MIN', 'center': 'CENTER', 'flex-end': 'MAX', 'space-evenly': 'SPACE_EVENLY'
+      'flex-start': 'MIN', 'center': 'CENTER', 'flex-end': 'MAX', 'space-between': 'SPACE_BETWEEN'
     }
     const mapped = validValues[style.justifyContent as string]
     if (mapped) {

package/packages/plugin/dist/main.js

@@ -235,7 +235,8 @@
               parent.appendChild(attachment.node);
             }
           }
-          for (const layout of deferredLayouts) {
+          for (let i = deferredLayouts.length - 1; i >= 0; i--) {
+            const layout = deferredLayouts[i];
             layout.frame.layoutMode = layout.layoutMode;
             layout.frame.primaryAxisSizingMode = "AUTO";
             layout.frame.counterAxisSizingMode = "AUTO";
@@ -642,8 +643,14 @@
         case "resize-node": {
           const { id, width, height } = args;
           const node = yield figma.getNodeByIdAsync(id);
-          if (!node || !("resize" in node)) throw new Error("Node not found");
-          node.resize(width, height);
+          if (!node) throw new Error("Node not found");
+          if ("resize" in node) {
+            node.resize(width, height);
+          } else if ("width" in node && "height" in node) {
+            node.resizeWithoutConstraints(width, height);
+          } else {
+            throw new Error("Node cannot be resized");
+          }
           return serializeNode(node);
         }
         // ==================== UPDATE APPEARANCE ====================
@@ -1211,7 +1218,12 @@
         // ==================== LAYOUT ====================
         case "trigger-layout": {
           const { nodeId, pendingComponentSetInstances } = args;
-          const root = yield figma.getNodeByIdAsync(nodeId);
+          let root = null;
+          for (let i = 0; i < 10; i++) {
+            root = yield figma.getNodeByIdAsync(nodeId);
+            if (root) break;
+            yield new Promise((r) => setTimeout(r, 100 * (i + 1)));
+          }
           if (!root) return null;
           if (pendingComponentSetInstances && pendingComponentSetInstances.length > 0) {
             for (const pending of pendingComponentSetInstances) {
@@ -1260,11 +1272,17 @@
             }
             if ("layoutMode" in node && node.layoutMode !== "NONE") {
               const frame = node;
-              if (frame.width <= 1 && frame.height <= 1) {
-                frame.primaryAxisSizingMode = "AUTO";
-                frame.counterAxisSizingMode = "AUTO";
-                frame.resize(1.01, 1.01);
-                frame.resize(1, 1);
+              const needsPrimaryRecalc = frame.primaryAxisSizingMode === "AUTO";
+              const needsCounterRecalc = frame.counterAxisSizingMode === "AUTO";
+              if (needsPrimaryRecalc || needsCounterRecalc) {
+                if (needsPrimaryRecalc) {
+                  frame.primaryAxisSizingMode = "FIXED";
+                  frame.primaryAxisSizingMode = "AUTO";
+                }
+                if (needsCounterRecalc) {
+                  frame.counterAxisSizingMode = "FIXED";
+                  frame.counterAxisSizingMode = "AUTO";
+                }
               }
             }
           });