@dannote/figma-use 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -7,8 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.3] - 2026-01-19
+
+### Added
+
+- **`diff visual`** — create visual diff between two nodes as PNG
+  ```bash
+  figma-use diff visual --from <id1> --to <id2> --output diff.png
+  ```
+  Red pixels show differences. Options: `--scale`, `--threshold`
+
+### Changed
+
+- `set rotation` now uses `--angle` flag instead of positional argument (fixes negative values like `--angle -15`)
+
+## [0.6.2] - 2026-01-19
+
+### Added
+
+- `bun run format` — format code with oxfmt
+- `bun run lint` — lint code with oxlint
+
 ## [0.6.1] - 2026-01-19
 
+### Added
+
+- **`diff` commands** (experimental) — incremental updates via unified diff patches
+  - `diff create --from <id> --to <id>` — compare two node trees and generate patch
+  - `diff apply` — apply a patch to Figma nodes (validates old values!)
+  - `diff show` — show diff between current state and new properties
+  ```bash
+  # Compare two frames (e.g., before/after, A/B variants)
+  figma-use diff create --from 123:456 --to 789:012
+  
+  # Apply patch (validates old values match)
+  figma-use diff apply --stdin < patch.diff
+  
+  # Dry run
+  figma-use diff apply --stdin --dry-run < patch.diff
+  ```
+- Uses `diff` library for unified diff parsing and validation
+
 ### Fixed
 
 - `--timeout` now applies to single commands (e.g., `eval`) via proxy `/command`
@@ -222,7 +261,7 @@ the same batch. See `component-set.tsx` for detailed explanation.
   - From stdin: `echo '<Frame style={{...}} />' | figma-use render --stdin`
   - With props: `--props '{"title": "Hello"}'`
   - Into parent: `--parent "1:23"`
-  - Dry run: `--dryRun` outputs NodeChanges JSON
+  - Dry run: `--dry-run` outputs NodeChanges JSON
 - **Multiplayer WebSocket connection pooling** in proxy
   - First render: ~4s (establishes connection)
   - Subsequent renders: ~0.4s (10x faster!)

package/README.md

@@ -304,6 +304,24 @@ figma-use me                                 # Current user info
 figma-use file info                          # File key and name
 ```
 
+### Diff (Experimental)
+
+Compare two frames and generate a unified diff patch:
+
+```bash
+# Compare original vs modified version
+figma-use diff create --from 123:456 --to 789:012
+```
+
+Apply patch with validation (fails if current state doesn't match expected):
+
+```bash
+figma-use diff apply patch.diff           # Apply from file
+figma-use diff apply --stdin < patch.diff # Apply from stdin
+figma-use diff apply patch.diff --dry-run # Preview changes
+figma-use diff apply patch.diff --force   # Skip validation
+```
+
 ### Escape Hatch
 
 ```bash

package/SKILL.md

@@ -34,57 +34,84 @@ figma-use plugin install
 
 ---
 
-## ⚠️ Incremental Updates (CRITICAL)
+## ⚠️ Incremental Updates via Diff (Experimental)
 
 **After initial render, NEVER re-render the full JSX tree.**
 
-When modifying an existing design:
-1. Save node IDs from the initial render (`--json` output)
-2. Use targeted CLI commands to modify individual nodes
-3. Only re-render if the structure fundamentally changes (>50% new elements)
+Use unified diff patches to apply targeted changes with validation:
 
-### Modify properties by ID
-```bash
-figma-use set fill <id> "#FF0000"           # Change color
-figma-use set opacity <id> 0.5              # Change opacity  
-figma-use set radius <id> 12                # Change corner radius
-figma-use node resize <id> --width 300 --height 200
-figma-use node move <id> --x 100 --y 200
-figma-use node rename <id> "New Name"
-```
+> ⚠️ **Experimental:** `diff` commands are new and may change.
 
-### Add new elements to existing parent
+### Compare two frames and generate patch
 ```bash
-figma-use create rect --parent <parent-id> --width 50 --height 50 --fill "#00F"
-figma-use create text --parent <parent-id> --text "Label" --fontSize 14
+# Compare original vs modified version
+figma-use diff create --from 123:456 --to 789:012
 ```
 
-### Delete elements
-```bash
-figma-use node delete <id>
+Output (unified diff format):
+```diff
+--- /Card/Header #123:457
++++ /Card/Header #789:013
+@@ -1,5 +1,5 @@
+ type: FRAME
+ size: 200 50
+ pos: 0 0
+-fill: #FFFFFF
++fill: #F0F0F0
+-opacity: 0.8
++opacity: 1
 ```
 
-### Example: Fixing transparency issues
+⚠️ **Don't forget space prefix on context lines** — `size: 48 40` will fail, ` size: 48 40` works.
+
+### Apply patch (validates old values!)
 ```bash
-# BAD: Re-rendering 60 elements to fix one opacity
-cat <<'EOF' | figma-use render --stdin
-<Frame>... 60 elements ...</Frame>
-EOF
+# Dry run — preview changes
+figma-use diff apply patch.diff --dry-run
 
-# GOOD: Fix the specific node
-figma-use set opacity 123:456 1.0
+# Apply changes (fails if old values don't match)
+figma-use diff apply patch.diff
+
+# Force apply (skip validation)
+figma-use diff apply patch.diff --force
+
+# From stdin
+cat patch.diff | figma-use diff apply --stdin
 ```
 
-### Example: Adjusting colors after critique
+### Visual diff (PNG)
 ```bash
-# Change shadow color from black to warm orange
-figma-use set fill 123:789 "#D97706"
+figma-use diff visual --from <id1> --to <id2> --output diff.png
+figma-use diff visual --from <id1> --to <id2> --output diff.png --threshold 0.05  # Stricter
+```
+
+Red pixels show differences. Useful for verifying modifications.
+
+### Workflow: Iterative design with critique
+
+1. **Render initial design:**
+   ```bash
+   cat design.jsx | figma-use render --stdin --json > nodes.json
+   ```
 
-# Move misaligned element
-figma-use node move 123:790 --x 240 --y 100
+2. **Get critique, then generate patch:**
+   ```bash
+   # Clone and modify (or compare to another frame)
+   figma-use diff create --from <original> --to <modified>
+   ```
 
-# Resize tail to better proportions  
-figma-use node resize 123:791 --width 120 --height 30
+3. **Apply patch to original:**
+   ```bash
+   figma-use diff apply --stdin < changes.diff
+   ```
+
+### Direct commands (for simple changes)
+```bash
+figma-use set fill <id> "#FF0000"
+figma-use set opacity <id> 0.5
+figma-use node resize <id> --width 300 --height 200
+figma-use node move <id> --x 100 --y 200
+figma-use node delete <id>
 ```
 
 ---
@@ -301,6 +328,18 @@ 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
 ```
 
+For modifications, use visual diff to highlight changes:
+
+```bash
+# Before modifying, export original
+figma-use export node <id> --output /tmp/before.png
+
+# After changes, compare visually
+figma-use diff visual --from <original-id> --to <modified-id> --output /tmp/diff.png
+```
+
+Red pixels = differences. Use `--threshold 0.05` for stricter comparison.
+
 ### Copying Elements Between Pages
 
 `node clone` creates a copy in the same parent. To move to another page: