devlens-mcp 0.3.3 → 0.4.1

package/README.md

@@ -5,9 +5,9 @@
 DevLens gives AI agents the ability to **see, interact with, and verify** your mobile app running on a simulator or emulator. It bridges the gap between "AI writes code" and "AI confirms the code works" — enabling a fully automated **design-to-code-to-verification loop**.
 
 ```
-Figma Design  ──►  AI Agent  ──►  Code Changes  ──►  Hot Reload  ──►  Screenshot  ──►  Compare
-                       ▲                                                                   │
-                       └───────────────── Fix & repeat until > 95% match ──────────────────┘
+Figma Design  ──►  AI Agent  ──►  Code Changes  ──►  Hot Reload  ──►  Screenshot  ──►  Compare  ──►  VQA Validate
+                       ▲                                                                                   │
+                       └──────────────────── Fix & repeat until 100% match (zero VQA) ────────────────────┘
 ```
 
 ---
@@ -19,31 +19,14 @@ Figma Design  ──►  AI Agent  ──►  Code Changes  ──►  Hot Reloa
 claude mcp add devlens -- npx devlens-mcp@latest
 ```
 
-### Cursor IDE
-Add to `~/.cursor/mcp.json`:
+### Cursor IDE / Claude Desktop
+Add to `~/.cursor/mcp.json` (Cursor) or `~/Library/Application Support/Claude/claude_desktop_config.json` (Desktop):
 ```json
 {
   "mcpServers": {
     "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
-      "env": {
-        "METRO_PORT": "8081",
-        "FIGMA_TOKEN": "figd_xxxxx"
-      }
-    }
-  }
-}
-```
-
-### Claude Desktop
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "devlens": {
-      "command": "npx",
-      "args": ["devlens-mcp@latest"],
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
       "env": {
         "METRO_PORT": "8081",
         "FIGMA_TOKEN": "figd_xxxxx"
@@ -55,6 +38,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Restart your AI client after editing the config.
 
+> **v0.4.0+**: DevLens now auto-detects your shell and `node` path on startup. It will patch MCP config files automatically if it detects a misconfigured shell or node path. See [setup guide](./docs/setup-guide.md) for details.
+
 ---
 
 ## What Problems Does It Solve?
@@ -75,6 +60,19 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 
 ---
 
+## New in v0.4.0
+
+- **Auto-Detect Shell & Node Path** — DevLens now auto-detects your shell (bash/zsh/fish), finds the correct `node`/`npx` path, and auto-patches MCP config files if they are misconfigured. No more "node not found" errors.
+- **VQA Validator** — new `devlens_vqa_validate` tool runs comprehensive Visual Quality Assurance against Figma designs. Checks spacing, colors, alignment, sizing, and missing/extra elements. Returns a structured VQA report with fix suggestions. Goal: zero VQA tickets from designer team.
+- **Smart Analysis Depth** — new `devlens_analyze` tool with configurable scope: `minimal` (quick diff, no layout report), `targeted` (compare specific elements only), `full` (complete analysis). `devlens_compare_with_figma` now has a `depth` parameter (`quick`/`standard`/`thorough`).
+- **Status Bar & Nav Bar Exclusion** — comparisons now auto-exclude volatile status bar (time, battery) and navigation bar regions. Reduces false-positive diffs by 3-5%.
+- **Perceptual Comparison Mode** — new SSIM-inspired block-based comparison tolerates anti-aliasing and sub-pixel font rendering differences. Enable with `perceptual: true` or use `depth: "thorough"`.
+- **Smart Figma Preprocessing** — new `"smart"` strategy combines rounded corner masking, histogram-guided artifact removal, and residual border trimming for cleaner Figma exports.
+- **Scoped Snapshots** — `devlens_snapshot` now supports `scope: "component"` to capture only a subtree of a specific ref, reducing token usage for targeted checks.
+- **Improved Verdict Thresholds** — layout analyzer thresholds tuned: "excellent" raised to 95%, sub-pixel alignment padding added to reduce off-by-one edge mismatches.
+
+---
+
 ## New in v0.3.1
 
 - **Layout-Aware Comparison** — `devlens_compare_with_figma` now reports per-element similarity scores using the accessibility tree. Instead of a single misleading global pixel-diff number, you get `"Header: 94%, ChatInput: 61%, ToolsGrid: 44% ← investigate"`. Set `layoutReport: false` to disable.
@@ -102,7 +100,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 
 ---
 
-## Tools (34)
+## Tools (37)
 
 ### Device Management (3)
 | Tool | Description |
@@ -140,7 +138,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 | `devlens_fill_form` | Fill multiple fields at once |
 | `devlens_capture_flow` | Batch execute actions + capture labeled screenshots |
 
-### Screenshots & Visual (5)
+### Screenshots & Visual (6)
 | Tool | Description |
 |------|-------------|
 | `devlens_screenshot` | Take screenshot (base64 + file) |
@@ -148,6 +146,7 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 | `devlens_element_screenshot` | Screenshot a specific element |
 | `devlens_compare_images` | A/B compare two saved screenshots |
 | `devlens_compare_with_figma` | Compare device screen against Figma design with per-element layout report |
+| `devlens_compare_properties` | Compare ALL design properties (text sizes, colors, spacing, dimensions) per component against Figma |
 
 ### React Native / Metro (6)
 | Tool | Description |
@@ -170,6 +169,12 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 |------|-------------|
 | `devlens_ds_context` | Load design tokens, component interfaces, and usage patterns from your codebase |
 
+### Analysis & VQA (2)
+| Tool | Description |
+|------|-------------|
+| `devlens_analyze` | Smart analysis with configurable depth (minimal/targeted/full). Respects scope of request — minimal changes get minimal analysis. |
+| `devlens_vqa_validate` | Run VQA validation against Figma. Checks spacing, color, alignment, sizing, missing elements. Returns issues + fix suggestions. |
+
 ---
 
 ## The Figma Verification Workflow
@@ -177,17 +182,17 @@ Without DevLens, AI agents resort to manual, error-prone workflows:
 DevLens integrates with Figma to create an automated design verification loop:
 
 ```
-┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
-│  Figma   │────►│   AI     │────►│  Code    │────►│  Device  │
-│  Design  │     │  Agent   │     │  Editor  │     │  Screen  │
-└──────────┘     └──────┬───┘     └──────────┘     └────┬─────┘
-                        │                                │
-                        │◄─── devlens_compare ───────────┘
-                        │     (similarity < 95%?)
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Figma   │────►│   AI     │────►│  Code    │────►│  Device  │────►│   VQA    │
+│  Design  │     │  Agent   │     │  Editor  │     │  Screen  │     │ Validate │
+└──────────┘     └──────┬───┘     └──────────┘     └──────────┘     └────┬─────┘
+                        │                                                 │
+                        │◄─── devlens_vqa_validate ──────────────────────┘
+                        │     (issues found?)
                         │              │
                         ▼              ▼
-                   Fix Code ◄─── Layout Report
-                                (per-element scores)
+                   Fix Code ◄─── VQA Report
+                                (spacing, color, alignment issues + fix suggestions)
 ```
 
 ### Step-by-step:
@@ -199,9 +204,11 @@ DevLens integrates with Figma to create an automated design verification loop:
 5. **Hot reload** — `devlens_hot_reload` triggers Metro fast refresh
 6. **Wait for stability** — `devlens_wait_for_screen` waits until UI stops changing
 7. **Validate elements** — `devlens_snapshot(validate: true)` catches invisible/zero-size elements
-8. **Compare with Figma** — `devlens_compare_with_figma(figmaUrl: "...")` returns device screenshot, Figma reference, diff image, and per-element layout scores
-9. **Analyze diff** — AI reads which elements are `poor`/`partial` and fixes those specifically
-10. **Fix & repeat** — Adjust code until overall similarity > 95%
+8. **Quick check** — `devlens_compare_with_figma(figmaUrl: "...", depth: "quick")` for fast iteration
+9. **Property comparison** — `devlens_compare_properties(figmaUrl: "...")` for per-component mismatches (font size, color, spacing, dimensions)
+10. **VQA validation** — `devlens_vqa_validate(figmaUrl: "...")` runs full VQA: spacing, colors, alignment, sizing, missing elements
+11. **Fix issues** — AI reads VQA/property reports with fix suggestions and applies fixes
+12. **Repeat** — Run VQA again until status is `PASS` (zero VQA issues for designers)
 
 ---
 
@@ -325,6 +332,9 @@ Configure via `devlens.config.json` in your app root (see [Setup Guide](./docs/s
 | "File not exportable" on Figma compare | Disable "Prevent viewers from copying and exporting" in Figma share settings |
 | `devlens_ds_context` returns empty | Set `DEVLENS_CONFIG` env var to your `devlens.config.json` path |
 | Comparison similarity always low | Run `devlens_snapshot` first so layout report has element bounds to work with |
+| Status bar causing false diffs | Use `excludeSystemBars: "auto"` (default in v0.4.0) or `"ios"`/`"android"` |
+| VQA report empty | Run `devlens_snapshot` first to populate element refs before `devlens_vqa_validate` |
+| Shell/node path wrong in MCP config | v0.4.0 auto-patches on startup; check logs for `[devlens] Patched` messages |
 
 ---
 

package/RELEASE_NOTES.md

@@ -0,0 +1,253 @@
+# DevLens v0.4.0 — Release Notes
+
+**Release Date:** March 2026
+**Previous Version:** v0.3.3
+**npm:** `npx devlens-mcp@latest`
+
+---
+
+## Headline
+
+DevLens v0.4.0 introduces **VQA validation**, **auto-config detection**, **smart analysis depth**, and **enhanced visual matching** — enabling a workflow where designers receive builds with **zero VQA tickets**.
+
+---
+
+## What's New
+
+### 1. Auto-Detect Shell & Node Path
+
+**Problem:** Developers manually configured `/bin/zsh`, `/bin/bash`, and `node`/`npx` paths in MCP server JSON. Wrong path = silent failure.
+
+**Now:** DevLens auto-detects on every startup:
+- Reads `$SHELL` to find your shell (bash, zsh, fish)
+- Runs `which node` / `which npx` inside your login shell profile
+- Falls back to common paths: nvm, volta, fnm, homebrew, nodenv, asdf
+- Scans all MCP config files (Cursor, Claude Desktop, Claude Code)
+- If a mismatch is found, **auto-patches** the JSON (with `.bak` backup)
+
+**Result:** "node not found" errors are gone. New developers just paste the default config and it works.
+
+**Common misconfiguration auto-fixed:**
+If you had a config like this (using `node` with shell flags — broken):
+```json
+{
+  "command": "/opt/homebrew/bin/node",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
+```
+DevLens v0.4.0 detects that `node` doesn't understand `-l` / `-c` (those are shell flags) and auto-patches to:
+```json
+{
+  "command": "/bin/zsh",
+  "args": ["-l", "-c", "npx devlens-mcp@latest"]
+}
+```
+A `.bak` backup is created before any patch.
+
+**Do developers need to change their config?** **No.** The recommended config is the same as always:
+```json
+{
+  "mcpServers": {
+    "devlens": {
+      "command": "/bin/zsh",
+      "args": ["-l", "-c", "npx devlens-mcp@latest"],
+      "env": {
+        "METRO_PORT": "8081",
+        "FIGMA_TOKEN": "figd_xxxxx"
+      }
+    }
+  }
+}
+```
+If your existing config has incorrect paths, DevLens fixes it on startup. No action needed.
+
+**New files:**
+- `src/setup/shell-detector.ts` — shell & node path detection
+- `src/setup/config-patcher.ts` — MCP config auto-patcher
+
+---
+
+### 2. VQA Validator — Zero Designer Tickets
+
+**Problem:** Traditional workflow wastes 2-3 days: Dev builds → Designer reviews → 15 VQA tickets → Dev fixes → More tickets → Repeat.
+
+**Now:** `devlens_vqa_validate` runs comprehensive Visual QA against Figma before the designer ever sees the build.
+
+**What it checks:**
+| Category | What it validates |
+|----------|-------------------|
+| Spacing | Gaps between elements vs Figma specs |
+| Colors | Dominant colors per region (CIE76 Delta-E) |
+| Alignment | Element center/edge positions |
+| Sizing | Width/height within 5% tolerance |
+| Missing | Regions with <60% match (content probably missing) |
+| Extra | Elements on device not in Figma |
+| Typography | Font sizes/weights via accessibility tree |
+
+**VQA Report format:**
+```
+=== VQA Report: WARNING ===
+Overall Score: 91.3%
+Issues: 3 (0 critical, 2 major, 1 minor)
+
+--- Issues ---
+  1. [MAJOR] [spacing] Gap between [e3] and [e5]: expected 12px, actual 20px
+  2. [MAJOR] [color] Color mismatch on [e7]: expected #1A73E8, actual #2196F3
+  3. [minor] [alignment] Element [e2] off by (3, 2)px
+
+--- Suggested Fixes ---
+  1. [high] Adjust margin/padding on [e3] to 12px gap.
+  2. [high] Update color for [e7] to #1A73E8. Check design token mapping.
+  3. [medium] Fix alignment of [e2] — adjust flex alignment.
+```
+
+**Developer workflow — just paste this prompt in Cursor:**
+```
+Build the HomeScreen from this Figma and make sure VQA passes with zero issues:
+https://figma.com/design/ABC123/MyApp?node-id=10-200
+
+Run VQA after building. Fix all issues. Re-run until PASS.
+```
+
+**New files:**
+- `src/tools/vqa-tools.ts` — `devlens_vqa_validate` tool
+- `src/visual/vqa-analyzer.ts` — VQA analysis engine (spacing, sizing, alignment, color, missing/extra)
+- `src/visual/color-extractor.ts` — dominant color extraction & CIE76 Delta-E comparison
+
+---
+
+### 3. Smart Analysis Depth
+
+**Problem:** DevLens always ran full analysis — full snapshot + full layout report + full comparison. For a small padding change, this was overkill and slow.
+
+**Now:** Analysis respects the scope of the request:
+
+| Tool / Param | When to use | What it does |
+|--------------|-------------|--------------|
+| `devlens_analyze(scope: "minimal")` | Small CSS tweak | Quick pixel diff, no layout report |
+| `devlens_analyze(scope: "targeted", targetRefs: ["e5"])` | Check one component | Inspects only specified elements |
+| `devlens_analyze(scope: "full")` | Full screen build | Complete snapshot + layout + comparison |
+| `devlens_compare_with_figma(depth: "quick")` | Fast iteration | Skip layout report, loose threshold |
+| `devlens_compare_with_figma(depth: "standard")` | Normal compare | Current v0.3 behavior |
+| `devlens_compare_with_figma(depth: "thorough")` | Final check | Per-element + perceptual + VQA hints |
+| `devlens_snapshot(scope: "component", componentRef: "e3")` | Reduce tokens | Capture only a subtree |
+
+**New file:** `src/tools/analyze-tools.ts`
+
+---
+
+### 4. Enhanced Visual Matching (95% → 100%)
+
+Four improvements that eliminate the 5% false-positive gap:
+
+#### 4a. Status Bar & Nav Bar Exclusion
+- Auto-detects iOS or Android from image dimensions
+- Masks status bar (time, battery, signal) and nav bar (home indicator)
+- Enabled by default: `excludeSystemBars: "auto"`
+- Eliminates 3-5% false diffs from volatile system UI
+
+#### 4b. Perceptual Comparison Mode
+- SSIM-inspired 8x8 block averaging
+- Tolerates anti-aliasing and sub-pixel font rendering differences
+- Enable with `perceptual: true` or `depth: "thorough"`
+- New verdict: 99%+ = "Pixel-perfect match. No VQA issues expected."
+
+#### 4c. Smart Figma Preprocessing
+- New `"smart"` strategy for `preprocessReference`
+- Masks rounded corners (detects corner radius, fills with inner color)
+- Content-based cropping + residual border trimming
+- Handles dark bars, light borders, transparent padding
+
+#### 4d. Sub-pixel Alignment
+- Layout analyzer adds 1px padding to scaled bounds
+- Prevents off-by-one edge mismatches between device and Figma
+- Verdict thresholds tuned: "excellent" = 95%+, "good" = 82%+
+
+---
+
+## New Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `devlens_analyze` | Smart analysis with configurable scope (minimal/targeted/full) |
+| `devlens_vqa_validate` | VQA validator — checks spacing, color, alignment, sizing, missing elements against Figma |
+| `devlens_compare_properties` | Per-component property comparison — text sizes, colors, spacing, dimensions, layout direction with exact expected vs actual values and configurable tolerances |
+
+**Total tools: 37** (up from 34 in v0.3.3)
+
+---
+
+## Enhanced Tools
+
+| Tool | What changed |
+|------|-------------|
+| `devlens_compare_with_figma` | New `depth` param (quick/standard/thorough), `excludeSystemBars` param |
+| `devlens_snapshot` | New `scope` param (screen/component), `componentRef` for subtree capture |
+| `devlens_compare_screenshot` | Inherits status bar exclusion and perceptual mode from comparator |
+
+---
+
+## Files Changed
+
+### New (9 files)
+| File | Purpose |
+|------|---------|
+| `src/setup/shell-detector.ts` | Shell type & node path detection |
+| `src/setup/config-patcher.ts` | MCP config JSON auto-patcher |
+| `src/tools/analyze-tools.ts` | `devlens_analyze` tool |
+| `src/tools/vqa-tools.ts` | `devlens_vqa_validate` tool |
+| `src/visual/vqa-analyzer.ts` | VQA engine: spacing, sizing, alignment, color, missing checks |
+| `src/visual/color-extractor.ts` | Dominant color extraction & Delta-E comparison |
+| `src/figma/figma-properties.ts` | Extract all comparable design properties from Figma REST API |
+| `src/snapshot/device-properties.ts` | Extract comparable properties from device snapshot + screenshot |
+| `src/visual/property-comparator.ts` | Per-property comparison engine with tolerances and severity |
+
+### Modified (11 files)
+| File | What changed |
+|------|-------------|
+| `bin/cli.ts` | Calls `detectAndPatchConfig()` on startup |
+| `src/server.ts` | Registers analyze + VQA tools, version bumped to 0.4.0 |
+| `src/visual/comparator.ts` | Status bar exclusion, perceptual mode, updated verdicts |
+| `src/visual/layout-analyzer.ts` | Sub-pixel alignment padding, tuned verdict thresholds |
+| `src/utils/image-preprocess.ts` | `"smart"` strategy, `maskRoundedCorners()` |
+| `src/tools/screenshot-tools.ts` | `depth` and `excludeSystemBars` params on compare_with_figma |
+| `src/tools/snapshot-tools.ts` | `scope` and `componentRef` params on snapshot |
+| `package.json` | Version 0.3.3 → 0.4.0 |
+| `README.md` | v0.4.0 changelog, updated tool count, VQA workflow |
+| `docs/setup-guide.md` | Auto-detect docs, VQA prompts, updated tool count |
+| `docs/figma-workflow.md` | Full VQA workflow section with prompts |
+| `docs/tool-reference.md` | analyze + vqa_validate reference entries |
+
+---
+
+## Breaking Changes
+
+None. All existing tool parameters and behaviors are backward-compatible. New parameters have sensible defaults:
+- `excludeSystemBars` defaults to `"auto"`
+- `depth` defaults to `"standard"` (same as v0.3 behavior)
+- `scope` defaults to `"screen"` / `"full"` (same as v0.3 behavior)
+
+---
+
+## Upgrade
+
+```bash
+# If using npx (recommended) — automatic, just restart your AI client
+# npx devlens-mcp@latest always fetches the latest
+
+# If installed locally
+npm install devlens-mcp@latest
+
+# Clear stale npx cache if needed
+rm -rf ~/.npm/_npx/*devlens*
+```
+
+---
+
+## What's Next (v0.5.0 roadmap)
+
+- Figma node-level comparison (compare Figma component tree against accessibility tree)
+- Auto-fix integration (VQA suggestions applied directly to source code)
+- CI/CD integration (run VQA as a build step, fail on critical issues)
+- Multi-screen VQA batch (validate entire flow in one call)
+- Design token drift detection (flag tokens in code that don't match Figma)

package/dist/bin/cli.js

@@ -2,7 +2,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("../src/index.js");
+const config_patcher_js_1 = require("../src/setup/config-patcher.js");
 async function main() {
+    await (0, config_patcher_js_1.detectAndPatchConfig)();
     const server = await (0, index_js_1.createServer)();
     process.on("SIGINT", async () => {
         await server.close();

package/dist/bin/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";;;AAEA,8CAA+C;AAE/C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,MAAM,IAAA,uBAAY,GAAE,CAAC;IAEpC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";;;AAEA,8CAA+C;AAC/C,sEAAsE;AAEtE,KAAK,UAAU,IAAI;IACjB,MAAM,IAAA,wCAAoB,GAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,MAAM,IAAA,uBAAY,GAAE,CAAC;IAEpC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/src/figma/figma-properties.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Extract all comparable design properties from a Figma node tree.
+ * Uses the REST API JSON response (not pixel exports).
+ *
+ * Builds on figma-structure.ts which fetches the raw node tree.
+ * This module walks that tree and normalizes every measurable property
+ * into a flat, comparable format.
+ */
+export interface FigmaComponentProps {
+    nodeId: string;
+    name: string;
+    type: string;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    text?: {
+        content: string;
+        fontSize: number;
+        fontFamily: string;
+        fontWeight: number;
+        lineHeight: number;
+        letterSpacing: number;
+        textAlign: string;
+    };
+    fills: Array<{
+        type: "SOLID" | "GRADIENT" | "IMAGE";
+        color?: {
+            r: number;
+            g: number;
+            b: number;
+            a: number;
+        };
+        opacity?: number;
+    }>;
+    cornerRadius?: number;
+    opacity: number;
+    visible: boolean;
+    stroke?: {
+        color: {
+            r: number;
+            g: number;
+            b: number;
+            a: number;
+        };
+        weight: number;
+    };
+    effects: Array<{
+        type: string;
+        color?: {
+            r: number;
+            g: number;
+            b: number;
+            a: number;
+        };
+        offset?: {
+            x: number;
+            y: number;
+        };
+        radius: number;
+    }>;
+    layout?: {
+        mode: "HORIZONTAL" | "VERTICAL" | "NONE";
+        itemSpacing: number;
+        padding: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+        primaryAlign: string;
+        counterAlign: string;
+        sizingH: string;
+        sizingV: string;
+    };
+    children: FigmaComponentProps[];
+}
+/**
+ * Walk a raw Figma REST API node and extract all comparable properties.
+ */
+export declare function extractFigmaProperties(raw: any): FigmaComponentProps;
+/**
+ * Flatten a FigmaComponentProps tree into a list of all nodes.
+ */
+export declare function flattenFigmaTree(root: FigmaComponentProps, parentPath?: string): Array<FigmaComponentProps & {
+    path: string;
+}>;
+//# sourceMappingURL=figma-properties.d.ts.map

package/dist/src/figma/figma-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-properties.d.ts","sourceRoot":"","sources":["../../../src/figma/figma-properties.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,mBAAmB;IAElC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IAGb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAGV,IAAI,CAAC,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAGF,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;QACrC,KAAK,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACvD,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IAGjB,MAAM,CAAC,EAAE;QACP,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACtD,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAGF,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACvD,MAAM,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAClC,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IAGH,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;QACzC,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QACtE,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAmBD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,mBAAmB,CAqFpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,mBAAmB,EACzB,UAAU,SAAK,GACd,KAAK,CAAC,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAY/C"}

package/dist/src/figma/figma-properties.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Extract all comparable design properties from a Figma node tree.
+ * Uses the REST API JSON response (not pixel exports).
+ *
+ * Builds on figma-structure.ts which fetches the raw node tree.
+ * This module walks that tree and normalizes every measurable property
+ * into a flat, comparable format.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFigmaProperties = extractFigmaProperties;
+exports.flattenFigmaTree = flattenFigmaTree;
+/**
+ * Convert Figma's 0-1 RGBA to 0-255.
+ */
+function toRgb255(c) {
+    return {
+        r: Math.round((c.r ?? 0) * 255),
+        g: Math.round((c.g ?? 0) * 255),
+        b: Math.round((c.b ?? 0) * 255),
+        a: Math.round((c.a ?? 1) * 255),
+    };
+}
+/**
+ * Walk a raw Figma REST API node and extract all comparable properties.
+ */
+function extractFigmaProperties(raw) {
+    const bbox = raw.absoluteBoundingBox ?? { x: 0, y: 0, width: 0, height: 0 };
+    // Text properties
+    let text;
+    if (raw.type === "TEXT" && raw.characters) {
+        const style = raw.style ?? {};
+        text = {
+            content: raw.characters,
+            fontSize: style.fontSize ?? 0,
+            fontFamily: style.fontFamily ?? "",
+            fontWeight: style.fontWeight ?? 400,
+            lineHeight: style.lineHeightPx ?? 0,
+            letterSpacing: style.letterSpacing ?? 0,
+            textAlign: style.textAlignHorizontal ?? "LEFT",
+        };
+    }
+    // Fills
+    const fills = (raw.fills ?? [])
+        .filter((f) => f.visible !== false)
+        .map((f) => ({
+        type: f.type ?? "SOLID",
+        color: f.color ? toRgb255(f.color) : undefined,
+        opacity: f.opacity,
+    }));
+    // Stroke
+    let stroke;
+    if (raw.strokes?.length > 0 && raw.strokes[0].color) {
+        stroke = {
+            color: toRgb255(raw.strokes[0].color),
+            weight: raw.strokeWeight ?? 0,
+        };
+    }
+    // Effects
+    const effects = (raw.effects ?? [])
+        .filter((e) => e.visible !== false)
+        .map((e) => ({
+        type: e.type ?? "UNKNOWN",
+        color: e.color ? toRgb255(e.color) : undefined,
+        offset: e.offset,
+        radius: e.radius ?? 0,
+    }));
+    // Layout
+    let layout;
+    if (raw.layoutMode && raw.layoutMode !== "NONE") {
+        layout = {
+            mode: raw.layoutMode,
+            itemSpacing: raw.itemSpacing ?? 0,
+            padding: {
+                top: raw.paddingTop ?? 0,
+                right: raw.paddingRight ?? 0,
+                bottom: raw.paddingBottom ?? 0,
+                left: raw.paddingLeft ?? 0,
+            },
+            primaryAlign: raw.primaryAxisAlignItems ?? "MIN",
+            counterAlign: raw.counterAxisAlignItems ?? "MIN",
+            sizingH: raw.layoutSizingHorizontal ?? "FIXED",
+            sizingV: raw.layoutSizingVertical ?? "FIXED",
+        };
+    }
+    return {
+        nodeId: raw.id ?? "",
+        name: raw.name ?? "",
+        type: raw.type ?? "UNKNOWN",
+        width: bbox.width ?? 0,
+        height: bbox.height ?? 0,
+        x: bbox.x ?? 0,
+        y: bbox.y ?? 0,
+        text,
+        fills,
+        cornerRadius: raw.cornerRadius ?? undefined,
+        opacity: raw.opacity ?? 1,
+        visible: raw.visible !== false,
+        stroke,
+        effects,
+        layout,
+        children: Array.isArray(raw.children)
+            ? raw.children.map(extractFigmaProperties)
+            : [],
+    };
+}
+/**
+ * Flatten a FigmaComponentProps tree into a list of all nodes.
+ */
+function flattenFigmaTree(root, parentPath = "") {
+    const path = parentPath ? `${parentPath} > ${root.name}` : root.name;
+    const result = [];
+    if (root.width > 0 && root.height > 0) {
+        result.push({ ...root, path });
+    }
+    for (const child of root.children) {
+        result.push(...flattenFigmaTree(child, path));
+    }
+    return result;
+}
+//# sourceMappingURL=figma-properties.js.map

package/dist/src/figma/figma-properties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-properties.js","sourceRoot":"","sources":["../../../src/figma/figma-properties.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAmFH,wDAqFC;AAKD,4CAeC;AA7HD;;GAEG;AACH,SAAS,QAAQ,CAAC,CAAkD;IAMlE,OAAO;QACL,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/B,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/B,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/B,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB,CAAC,GAAQ;IAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAE5E,kBAAkB;IAClB,IAAI,IAA6C,CAAC;IAClD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9B,IAAI,GAAG;YACL,OAAO,EAAE,GAAG,CAAC,UAAU;YACvB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC;YAC7B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE;YAClC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,GAAG;YACnC,UAAU,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC;YACnC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,CAAC;YACvC,SAAS,EAAE,KAAK,CAAC,mBAAmB,IAAI,MAAM;SAC/C,CAAC;IACJ,CAAC;IAED,QAAQ;IACR,MAAM,KAAK,GAAiC,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;SAC1D,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;SACvC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,OAAO;QACvB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;QAC9C,OAAO,EAAE,CAAC,CAAC,OAAO;KACnB,CAAC,CAAC,CAAC;IAEN,SAAS;IACT,IAAI,MAAiD,CAAC;IACtD,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACpD,MAAM,GAAG;YACP,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YACrC,MAAM,EAAE,GAAG,CAAC,YAAY,IAAI,CAAC;SAC9B,CAAC;IACJ,CAAC;IAED,UAAU;IACV,MAAM,OAAO,GAAmC,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;SAChE,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;SACvC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,SAAS;QACzB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;QAC9C,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC;KACtB,CAAC,CAAC,CAAC;IAEN,SAAS;IACT,IAAI,MAAiD,CAAC;IACtD,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;QAChD,MAAM,GAAG;YACP,IAAI,EAAE,GAAG,CAAC,UAAU;YACpB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,CAAC;YACjC,OAAO,EAAE;gBACP,GAAG,EAAE,GAAG,CAAC,UAAU,IAAI,CAAC;gBACxB,KAAK,EAAE,GAAG,CAAC,YAAY,IAAI,CAAC;gBAC5B,MAAM,EAAE,GAAG,CAAC,aAAa,IAAI,CAAC;gBAC9B,IAAI,EAAE,GAAG,CAAC,WAAW,IAAI,CAAC;aAC3B;YACD,YAAY,EAAE,GAAG,CAAC,qBAAqB,IAAI,KAAK;YAChD,YAAY,EAAE,GAAG,CAAC,qBAAqB,IAAI,KAAK;YAChD,OAAO,EAAE,GAAG,CAAC,sBAAsB,IAAI,OAAO;YAC9C,OAAO,EAAE,GAAG,CAAC,oBAAoB,IAAI,OAAO;SAC7C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE;QACpB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;QACpB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC;QACtB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC;QACxB,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;QACd,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;QACd,IAAI;QACJ,KAAK;QACL,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,SAAS;QAC3C,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,CAAC;QACzB,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,KAAK;QAC9B,MAAM;QACN,OAAO;QACP,MAAM;QACN,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;YACnC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,sBAAsB,CAAC;YAC1C,CAAC,CAAC,EAAE;KACP,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAC9B,IAAyB,EACzB,UAAU,GAAG,EAAE;IAEf,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACrE,MAAM,MAAM,GAAkD,EAAE,CAAC;IAEjE,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}