feat: improve Figma visual fidelity — crop scale, sharp, fix command regen (#254)

* feat: add visual validation, notable component detection, and improved Figma context

- Add visual comparison validation (pixelmatch + LLM vision) that runs on
  final iterations when Figma screenshots are present, with automatic
  2-iteration extension to fix visual issues
- Add --no-visual-check CLI flag to disable visual validation
- Add dev-server module for launching/capturing implementation screenshots
- Detect notable sub-components in Figma sections (scroll indicators,
  social sidebars, nav elements) with position hints and scroll behavior
- Improve context-builder Figma instructions: z-index stacking clarity,
  STRETCH→cover guidance, scroll indicator patterns, completeness checklist,
  absolute positioning precision
- Enhance plan-generator with inner shadow CSS output, deeper node traversal
  (depth 8), and text-descendant inclusion at deep levels
- Add vision call tracking to CostTracker

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

* feat: add ralph-starter figma interactive wizard command

New `ralph-starter figma` command with 4-step interactive wizard:
1. Figma design URL (validated)
2. Task description
3. Tech stack (auto-detect from package.json + list + custom)
4. Model selection (smart per-agent: Opus recommended for Claude)

Delegates to runCommand with pre-configured Figma options.

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

* fix: remove duplicate showWelcome() call from figma command

showWelcome() is already called by runCommand(), so calling it in
figmaCommand() resulted in the welcome banner showing twice.

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

* feat: improve Figma visual fidelity — crop scale, sharp, fix command regen

- Fix composite crop scale: compute actual scale from image metadata
  instead of hardcoding 2x (Figma API caps at 4096px)
- Make sharp mandatory with auto-install (ensureSharp helper in
  src/utils/sharp.ts), replace hacky new Function imports
- Scale-aware pixelDiff: resize impl screenshots to match Figma
  dimensions before pixel comparison
- Fix background-size for cropped composites: use 100% auto instead
  of cover when clipCropTop > 0
- Fix decorative text z-index: opacity < 0.3 gets z-index 1 (behind
  content text) instead of z-index 10
- Fix content overlap calculation: use main content section Y position
  (not hero text) for negative margin guidance
- Save .ralph/figma-source.json during run for later spec regeneration
- Fix command regenerates both spec and IMPLEMENTATION_PLAN.md from
  cached Figma API data, skips "nothing to fix" when spec updated
- Add parentBackgroundColor and compositeClipCropTops to spec options
- Add HTML entity sanitization for Figma text content

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

---------

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

Author: rubenmarcus

package.json

@@ -77,19 +77,20 @@
     "inquirer": "^13.2.2",
     "ora": "^9.1.0",
     "pdf-parse": "^2.4.5",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.33.0",
     "simple-git": "^3.27.0",
     "yaml": "^2.7.0",
     "zod": "^4.3.6"
   },
-  "optionalDependencies": {
-    "sharp": "^0.34.5"
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^20.3.1",
     "@types/inquirer": "^9.0.7",
     "@types/node": "^25.1.0",
+    "@types/pngjs": "^6.0.5",
     "@vitest/coverage-v8": "^4.0.18",
     "commitizen": "^4.3.1",
     "cz-conventional-changelog": "^3.3.0",