@su-record/vibe 3.2.64 → 4.0.0

package/hooks/scripts/figma-extract.js

@@ -1,885 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * figma-extract.js — Figma REST API 디자인 추출 도구
- *
- * Usage:
- *   node figma-extract.js tree <fileKey> <nodeId> [--depth=10]
- *   node figma-extract.js images <fileKey> <nodeId> --out=<dir> [--depth=10]
- *   node figma-extract.js screenshot <fileKey> <nodeId> --out=<path>
- *
- * Token: ~/.vibe/config.json → credentials.figma.accessToken
- *        또는 FIGMA_ACCESS_TOKEN env
- */
-
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import { execFileSync } from 'child_process';
-
-// ─── Config ─────────────────────────────────────────────────────────
-
-const FIGMA_API = 'https://api.figma.com/v1';
-const MAX_RETRIES = 3;
-const INITIAL_DELAY_MS = 2000;
-const SCREENSHOT_INTERVAL_MS = 500; // rate limit 보호: screenshot 간 최소 간격
-const DOWNLOAD_CONCURRENCY = 8;     // 이미지 다운로드 최대 동시 수
-
-// ─── WebP 변환 ──────────────────────────────────────────────────────
-
-let _cwebpAvailable;
-function hasCwebp() {
-  if (_cwebpAvailable === undefined) {
-    try { execFileSync('cwebp', ['-version'], { stdio: 'ignore' }); _cwebpAvailable = true; }
-    catch { _cwebpAvailable = false; }
-  }
-  return _cwebpAvailable;
-}
-
-/** PNG 버퍼를 webp 파일로 저장. cwebp 없으면 png 폴백. */
-function writeAsWebp(pngBuf, outPath) {
-  if (!hasCwebp()) {
-    // cwebp 없으면 png 폴백
-    const fallback = outPath.replace(/\.webp$/, '.png');
-    fs.writeFileSync(fallback, pngBuf);
-    return fallback;
-  }
-  const tmpPng = outPath + '.tmp.png';
-  fs.writeFileSync(tmpPng, pngBuf);
-  try {
-    execFileSync('cwebp', ['-q', '85', tmpPng, '-o', outPath], { stdio: 'ignore' });
-    fs.unlinkSync(tmpPng);
-    return outPath;
-  } catch {
-    // 변환 실패 시 png 폴백
-    const fallback = outPath.replace(/\.webp$/, '.png');
-    fs.renameSync(tmpPng, fallback);
-    return fallback;
-  }
-}
-
-function loadToken() {
-  if (process.env.FIGMA_ACCESS_TOKEN) return process.env.FIGMA_ACCESS_TOKEN;
-  const configPath = path.join(os.homedir(), '.vibe', 'config.json');
-  try {
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    const token = config?.credentials?.figma?.accessToken;
-    if (token) return token;
-  } catch { /* ignore */ }
-  return null;
-}
-
-function fail(msg) { console.error(JSON.stringify({ error: msg })); process.exit(1); }
-function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
-
-// ─── Concurrency Helpers ────────────────────────────────────────────
-
-/** 병렬 다운로드 풀: 최대 N개 동시 실행 (이미지 다운로드용) */
-async function parallelPool(tasks, concurrency = DOWNLOAD_CONCURRENCY) {
-  const results = [];
-  let idx = 0;
-  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, async () => {
-    while (idx < tasks.length) {
-      const i = idx++;
-      try { results[i] = await tasks[i](); } catch (e) { results[i] = e; }
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
-
-/** 순차 큐: screenshot API용 (rate limit 보호, 간격 보장) */
-async function sequentialQueue(tasks, intervalMs = SCREENSHOT_INTERVAL_MS) {
-  const results = [];
-  for (let i = 0; i < tasks.length; i++) {
-    if (i > 0) await sleep(intervalMs);
-    try { results.push(await tasks[i]()); } catch (e) { results.push({ error: e.message }); }
-  }
-  return results;
-}
-
-// ─── HTTP (에러 보류 & 복구) ────────────────────────────────────────
-
-async function apiFetch(endpoint, token, { silent = false } = {}) {
-  let lastErr = '';
-  for (let i = 0; i < MAX_RETRIES; i++) {
-    try {
-      const res = await fetch(`${FIGMA_API}${endpoint}`, { headers: { 'X-Figma-Token': token } });
-      if (res.status === 429) { await sleep(INITIAL_DELAY_MS * 2 ** i); continue; }
-      if (res.status === 403) { if (silent) return null; fail('403 Forbidden — check token permissions'); }
-      if (res.status === 404) { if (silent) return null; fail('404 — check fileKey/nodeId'); }
-      if (!res.ok) {
-        lastErr = `HTTP ${res.status}`;
-        if (res.status >= 500) { await sleep(INITIAL_DELAY_MS * 2 ** i); continue; }
-        if (silent) return null;
-        fail(lastErr);
-      }
-      return await res.json();
-    } catch (e) {
-      lastErr = e.message;
-      if (i < MAX_RETRIES - 1) await sleep(INITIAL_DELAY_MS * 2 ** i);
-    }
-  }
-  if (silent) return null;
-  fail(`Failed after ${MAX_RETRIES} retries: ${lastErr}`);
-}
-
-// ─── Color ──────────────────────────────────────────────────────────
-
-function toCSS(c) {
-  if (!c) return null;
-  const r = Math.round(c.r * 255), g = Math.round(c.g * 255), b = Math.round(c.b * 255), a = c.a ?? 1;
-  if (a === 1) return `#${r.toString(16).padStart(2,'0')}${g.toString(16).padStart(2,'0')}${b.toString(16).padStart(2,'0')}`;
-  return `rgba(${r}, ${g}, ${b}, ${+a.toFixed(2)})`;
-}
-
-// ─── Gradient Helpers ───────────────────────────────────────────────
-
-function toLinearGradient(f) {
-  if (!f.gradientHandlePositions || !f.gradientStops) return null;
-  const [p0, p1] = f.gradientHandlePositions;
-  const angle = Math.round(Math.atan2(p1.y - p0.y, p1.x - p0.x) * 180 / Math.PI + 90);
-  const opacity = f.opacity ?? 1;
-  const stops = f.gradientStops.map(s => {
-    const c = opacity < 1 ? { ...s.color, a: (s.color.a ?? 1) * opacity } : s.color;
-    return `${toCSS(c)} ${Math.round(s.position * 100)}%`;
-  }).join(', ');
-  return `linear-gradient(${angle}deg, ${stops})`;
-}
-
-function toRadialGradient(f) {
-  if (!f.gradientStops) return null;
-  const opacity = f.opacity ?? 1;
-  const stops = f.gradientStops.map(s => {
-    const c = opacity < 1 ? { ...s.color, a: (s.color.a ?? 1) * opacity } : s.color;
-    return `${toCSS(c)} ${Math.round(s.position * 100)}%`;
-  }).join(', ');
-  return `radial-gradient(circle, ${stops})`;
-}
-
-// ─── Blend Mode Map ─────────────────────────────────────────────────
-
-const BLEND_MODES = { MULTIPLY:'multiply', SCREEN:'screen', OVERLAY:'overlay', DARKEN:'darken', LIGHTEN:'lighten', COLOR_DODGE:'color-dodge', COLOR_BURN:'color-burn', HARD_LIGHT:'hard-light', SOFT_LIGHT:'soft-light', DIFFERENCE:'difference', EXCLUSION:'exclusion', HUE:'hue', SATURATION:'saturation', COLOR:'color', LUMINOSITY:'luminosity' };
-
-// Figma-only blend modes with no CSS equivalent (silent-drop hazards)
-const UNSUPPORTED_BLEND_MODES = new Set(['LINEAR_BURN', 'LINEAR_DODGE', 'PLUS_DARKER', 'PLUS_LIGHTER']);
-
-// ─── Raw extraction & Audit (Figma→CSS translation-loss detection) ──
-
-/** Pull raw numeric Figma properties for later raw-vs-computed reconciliation. */
-function extractRaw(n) {
-  const raw = {};
-  if (n.itemSpacing != null) raw.itemSpacing = n.itemSpacing;
-  if (n.paddingTop != null) raw.paddingTop = n.paddingTop;
-  if (n.paddingRight != null) raw.paddingRight = n.paddingRight;
-  if (n.paddingBottom != null) raw.paddingBottom = n.paddingBottom;
-  if (n.paddingLeft != null) raw.paddingLeft = n.paddingLeft;
-  if (n.cornerRadius != null) raw.cornerRadius = n.cornerRadius;
-  if (n.rectangleCornerRadii) raw.rectangleCornerRadii = n.rectangleCornerRadii;
-  if (n.strokeWeight != null) raw.strokeWeight = n.strokeWeight;
-  if (n.strokeAlign) raw.strokeAlign = n.strokeAlign;
-  if (n.blendMode) raw.blendMode = n.blendMode;
-  if (n.opacity != null) raw.opacity = n.opacity;
-  if (n.type === 'TEXT' && n.style) {
-    const s = n.style;
-    if (s.fontSize != null) raw.fontSize = s.fontSize;
-    if (s.lineHeightPx != null) raw.lineHeightPx = s.lineHeightPx;
-    if (s.letterSpacing != null) raw.letterSpacing = s.letterSpacing;
-    if (s.fontWeight != null) raw.fontWeight = s.fontWeight;
-    if (s.leadingTrim) raw.leadingTrim = s.leadingTrim;
-    if (s.textBoxTrim) raw.textBoxTrim = s.textBoxTrim;
-  }
-  return raw;
-}
-
-/** Detect Figma properties that do not cross the CSS boundary cleanly. */
-function auditNode(n) {
-  const warnings = [];
-  // Stroke alignment — only CENTER maps to CSS border
-  if (n.strokeAlign && n.strokeAlign !== 'CENTER' && (n.strokes || []).some(s => s.visible !== false)) {
-    warnings.push({
-      property: 'strokeAlign',
-      value: n.strokeAlign,
-      severity: 'P1',
-      reason: `CSS border renders stroke centered; Figma ${n.strokeAlign} cannot be matched without box-sizing trade-offs.`,
-    });
-  }
-  // Node-level blend mode
-  if (n.blendMode && UNSUPPORTED_BLEND_MODES.has(n.blendMode)) {
-    warnings.push({
-      property: 'blendMode',
-      value: n.blendMode,
-      severity: 'P1',
-      reason: `mix-blend-mode has no equivalent for ${n.blendMode}.`,
-    });
-  }
-  // Per-fill blend mode
-  for (const f of n.fills || []) {
-    if (f.visible !== false && f.blendMode && UNSUPPORTED_BLEND_MODES.has(f.blendMode)) {
-      warnings.push({
-        property: 'fill.blendMode',
-        value: f.blendMode,
-        severity: 'P1',
-        reason: `background-blend-mode has no equivalent for ${f.blendMode}.`,
-      });
-    }
-  }
-  // leadingTrim / textBoxTrim (text-box-trim is Firefox-unsupported)
-  if (n.type === 'TEXT' && n.style) {
-    if (n.style.leadingTrim && n.style.leadingTrim !== 'NONE') {
-      warnings.push({
-        property: 'leadingTrim',
-        value: n.style.leadingTrim,
-        severity: 'P2',
-        reason: 'text-box-trim is not supported in Firefox; visual vertical alignment will drift.',
-      });
-    }
-    if (n.style.textBoxTrim && n.style.textBoxTrim !== 'NONE') {
-      warnings.push({
-        property: 'textBoxTrim',
-        value: n.style.textBoxTrim,
-        severity: 'P2',
-        reason: 'text-box-trim browser support is limited.',
-      });
-    }
-  }
-  // Constraints SCALE/CENTER — no CSS layout equivalent
-  if (n.constraints) {
-    const { horizontal, vertical } = n.constraints;
-    for (const [axis, val] of [['horizontal', horizontal], ['vertical', vertical]]) {
-      if (val === 'SCALE' || val === 'CENTER') {
-        warnings.push({
-          property: `constraints.${axis}`,
-          value: val,
-          severity: 'P2',
-          reason: `Figma ${val} constraint has no direct CSS mapping; responsive behavior will diverge.`,
-        });
-      }
-    }
-  }
-  // Individual stroke weights combined with non-center align
-  if (n.individualStrokeWeights && n.strokeAlign && n.strokeAlign !== 'CENTER') {
-    warnings.push({
-      property: 'individualStrokeWeights',
-      value: n.strokeAlign,
-      severity: 'P2',
-      reason: 'Per-side border widths only align cleanly when strokeAlign=CENTER.',
-    });
-  }
-  return warnings;
-}
-
-// ─── CSS Extraction ─────────────────────────────────────────────────
-
-function extractCSS(n) {
-  const css = {};
-  // Layout
-  if (n.layoutMode === 'VERTICAL') { css.display = 'flex'; css.flexDirection = 'column'; }
-  else if (n.layoutMode === 'HORIZONTAL') { css.display = 'flex'; css.flexDirection = 'row'; }
-  const axM = { MIN:'flex-start', CENTER:'center', MAX:'flex-end', SPACE_BETWEEN:'space-between' };
-  const crM = { MIN:'flex-start', CENTER:'center', MAX:'flex-end', BASELINE:'baseline' };
-  if (n.primaryAxisAlignItems && axM[n.primaryAxisAlignItems]) css.justifyContent = axM[n.primaryAxisAlignItems];
-  if (n.counterAxisAlignItems && crM[n.counterAxisAlignItems]) css.alignItems = crM[n.counterAxisAlignItems];
-  if (n.itemSpacing > 0) css.gap = `${n.itemSpacing}px`;
-  // layoutGrow
-  if (n.layoutGrow === 1) css.flexGrow = '1';
-  // Padding
-  const pt=n.paddingTop||0, pr=n.paddingRight||0, pb=n.paddingBottom||0, pl=n.paddingLeft||0;
-  if (pt||pr||pb||pl) css.padding = `${pt}px ${pr}px ${pb}px ${pl}px`;
-  // Size
-  if (n.absoluteBoundingBox) { css.width = `${Math.round(n.absoluteBoundingBox.width)}px`; css.height = `${Math.round(n.absoluteBoundingBox.height)}px`; }
-  // layoutSizing — HUG removes fixed dimensions, FILL handled by converter with parent context
-  if (n.layoutSizingHorizontal === 'HUG') delete css.width;
-  if (n.layoutSizingVertical === 'HUG') delete css.height;
-  // Position / overflow / opacity
-  if (n.layoutPositioning === 'ABSOLUTE') css.position = 'absolute';
-  if (n.clipsContent) css.overflow = 'hidden';
-  if (n.opacity != null && n.opacity < 1) css.opacity = n.opacity.toFixed(2);
-  // Rotation
-  if (n.rotation != null && Math.abs(n.rotation) > 0.05) {
-    const deg = +((-n.rotation) % 360).toFixed(2);
-    css.transform = `rotate(${deg}deg)`;
-  }
-  // Node-level blend mode
-  if (n.blendMode && BLEND_MODES[n.blendMode]) css.mixBlendMode = BLEND_MODES[n.blendMode];
-  // Radius
-  if (n.cornerRadius > 0) css.borderRadius = `${n.cornerRadius}px`;
-  else if (n.rectangleCornerRadii) { const [a,b,c,d] = n.rectangleCornerRadii; css.borderRadius = `${a}px ${b}px ${c}px ${d}px`; }
-  // Fills — multi-fill aware
-  let imgRef, imgScaleMode;
-  const visibleFills = (n.fills||[]).filter(f=>f.visible!==false);
-  // Backward compat: single-fill css properties
-  const firstSolid = visibleFills.find(f=>f.type==='SOLID');
-  if (firstSolid) css.backgroundColor = toCSS({ ...firstSolid.color, a: firstSolid.opacity ?? firstSolid.color?.a ?? 1 });
-  const firstImage = visibleFills.find(f=>f.type==='IMAGE');
-  if (firstImage) { imgRef = firstImage.imageRef; imgScaleMode = firstImage.scaleMode; }
-  // Gradient → backgroundImage
-  const gradients = [];
-  for (const f of visibleFills) {
-    if (f.type === 'GRADIENT_LINEAR') { const g = toLinearGradient(f); if (g) gradients.push(g); }
-    else if (f.type === 'GRADIENT_RADIAL' || f.type === 'GRADIENT_ANGULAR' || f.type === 'GRADIENT_DIAMOND') {
-      const g = toRadialGradient(f); if (g) gradients.push(g);
-    }
-  }
-  if (gradients.length) css.backgroundImage = gradients.join(', ');
-  // Per-fill blendMode → backgroundBlendMode
-  for (const f of visibleFills) {
-    if (f.blendMode && f.blendMode !== 'NORMAL' && BLEND_MODES[f.blendMode]) {
-      css.backgroundBlendMode = BLEND_MODES[f.blendMode]; break;
-    }
-  }
-  // Fill filters (saturation → grayscale/saturate)
-  for (const f of visibleFills) {
-    if (f.filters?.saturation != null && f.filters.saturation !== 0) {
-      const sat = f.filters.saturation;
-      const filterVal = sat < 0 ? `grayscale(${Math.round(Math.abs(sat) * 100)}%)` : `saturate(${Math.round((1 + sat) * 100)}%)`;
-      css.filter = (css.filter ? css.filter + ' ' : '') + filterVal;
-    }
-  }
-  // Multi-fill structured array (when 2+ visible fills — for converter)
-  let _fills;
-  if (visibleFills.length > 1) {
-    _fills = visibleFills.map(f => {
-      const entry = { type: f.type };
-      if (f.type === 'SOLID') entry.color = toCSS({ ...f.color, a: f.opacity ?? f.color?.a ?? 1 });
-      if (f.type === 'IMAGE') { entry.imageRef = f.imageRef; if (f.scaleMode) entry.scaleMode = f.scaleMode; }
-      if (f.type?.startsWith('GRADIENT_')) {
-        entry.gradient = f.type === 'GRADIENT_LINEAR' ? toLinearGradient(f) : toRadialGradient(f);
-      }
-      if (f.blendMode && f.blendMode !== 'NORMAL' && BLEND_MODES[f.blendMode]) entry.blendMode = BLEND_MODES[f.blendMode];
-      if (f.filters?.saturation != null && f.filters.saturation !== 0) entry.filters = f.filters;
-      return entry;
-    });
-  }
-  // Strokes — strokeAlign aware + individual strokes + dashes
-  const stroke = (n.strokes||[]).find(s=>s.visible!==false&&s.type==='SOLID');
-  const isw = n.individualStrokeWeights;
-  const hasStroke = stroke && (n.strokeWeight || isw);
-  if (hasStroke) {
-    const strokeColor = toCSS({ ...stroke.color, a: stroke.opacity ?? stroke.color?.a ?? 1 });
-    // Individual stroke weights (different per side)
-    if (isw && (isw.top !== isw.bottom || isw.left !== isw.right || isw.top !== isw.left)) {
-      if (isw.top) css.borderTop = `${isw.top}px solid ${strokeColor}`;
-      if (isw.right) css.borderRight = `${isw.right}px solid ${strokeColor}`;
-      if (isw.bottom) css.borderBottom = `${isw.bottom}px solid ${strokeColor}`;
-      if (isw.left) css.borderLeft = `${isw.left}px solid ${strokeColor}`;
-    } else if (n.strokeAlign === 'OUTSIDE') {
-      css.outline = `${n.strokeWeight}px solid ${strokeColor}`;
-    } else {
-      css.border = `${n.strokeWeight}px solid ${strokeColor}`;
-      if (n.strokeAlign === 'INSIDE') css.boxSizing = 'border-box';
-    }
-    // Dashed strokes
-    if (n.strokeDashes?.length) {
-      css.borderStyle = 'dashed';
-    }
-  }
-  // Effects
-  const shadows = [];
-  for (const e of (n.effects||[]).filter(e=>e.visible!==false)) {
-    if (e.type==='DROP_SHADOW'||e.type==='INNER_SHADOW') {
-      const ins = e.type==='INNER_SHADOW'?'inset ':'';
-      shadows.push(`${ins}${e.offset?.x||0}px ${e.offset?.y||0}px ${e.radius||0}px ${e.spread||0}px ${toCSS(e.color)}`);
-    } else if (e.type==='LAYER_BLUR') {
-      css.filter = (css.filter ? css.filter + ' ' : '') + `blur(${e.radius}px)`;
-    } else if (e.type==='BACKGROUND_BLUR') css.backdropFilter = `blur(${e.radius}px)`;
-  }
-  if (shadows.length) css.boxShadow = shadows.join(', ');
-  // Text
-  if (n.type === 'TEXT' && n.style) {
-    const s = n.style;
-    if (s.fontFamily) css.fontFamily = `'${s.fontFamily}', sans-serif`;
-    if (s.fontSize) css.fontSize = `${s.fontSize}px`;
-    if (s.fontWeight) css.fontWeight = String(s.fontWeight);
-    if (s.lineHeightPx) css.lineHeight = `${s.lineHeightPx}px`;
-    if (s.letterSpacing) css.letterSpacing = `${s.letterSpacing}px`;
-    const ta = { LEFT:'left', CENTER:'center', RIGHT:'right', JUSTIFIED:'justify' };
-    if (s.textAlignHorizontal && ta[s.textAlignHorizontal]) css.textAlign = ta[s.textAlignHorizontal];
-    // textCase → text-transform
-    const tc = { UPPER:'uppercase', LOWER:'lowercase', TITLE:'capitalize' };
-    if (s.textCase && tc[s.textCase]) css.textTransform = tc[s.textCase];
-    // textTruncation → ellipsis
-    if (s.textTruncation === 'ENDING') {
-      css.overflow = 'hidden'; css.textOverflow = 'ellipsis'; css.whiteSpace = 'nowrap';
-    }
-    // paragraphSpacing
-    if (s.paragraphSpacing > 0) css.marginBottom = `${s.paragraphSpacing}px`;
-    const tf = visibleFills.find(f=>f.type==='SOLID');
-    if (tf) css.color = toCSS(tf.color);
-  }
-  const result = { ...css };
-  if (imgRef) result._imageRef = imgRef;
-  if (imgScaleMode) result._imageScaleMode = imgScaleMode;
-  if (_fills) result._fills = _fills;
-  return result;
-}
-
-// ─── Determination (image-vs-HTML) Helpers ──────────────────────────
-
-const BG_NAME_RE = /^(BG|bg|배경|background)$/i;
-const VECTOR_TYPE_RE = /^(VECTOR|LINE|BOOLEAN_OPERATION|STAR|REGULAR_POLYGON)$/;
-const FOREGROUND_IMG_NAME_RE = /(^|[-_\s])(image|photo|thumb|thumbnail|avatar|icon|logo|img|picture|banner|poster)([-_\s]|\d|$)/i;
-
-/** D1-D3: TEXT whose visual fidelity cannot be preserved by HTML text.
- *  D4/D5 (vector siblings, non-web font) need project context and are left to the converter. */
-function isDesignTextNode(n) {
-  if (n.type !== 'TEXT') return false;
-  const fills = (n.fills || []).filter(f => f.visible !== false);
-  if (fills.length >= 2) return true; // D1
-  if (fills.some(f => typeof f.type === 'string' && f.type.startsWith('GRADIENT_'))) return true; // D3
-  if ((n.effects || []).some(e => e.visible !== false && (e.type === 'DROP_SHADOW' || e.type === 'INNER_SHADOW'))) return true; // D2
-  if ((n.strokes || []).some(s => s.visible !== false)) return true; // D2 (text stroke)
-  return false;
-}
-
-/** Q1: any descendant carries meaningful text content. */
-function hasTextDescendantRaw(n) {
-  if (n.type === 'TEXT' && typeof n.characters === 'string' && n.characters.trim().length) return true;
-  return (n.children || []).some(hasTextDescendantRaw);
-}
-
-/** Q2: 2+ direct children sharing the same componentId (or normalized name stem). */
-function hasRepeatingInstancesRaw(n) {
-  const kids = n.children || [];
-  if (kids.length < 2) return false;
-  const keyCount = {};
-  for (const c of kids) {
-    if (c.type !== 'INSTANCE' && c.type !== 'COMPONENT') continue;
-    const key = c.componentId || (c.name || '').replace(/\s*\d+\s*$/, '').trim();
-    if (!key) continue;
-    keyCount[key] = (keyCount[key] || 0) + 1;
-    if (keyCount[key] >= 2) return true;
-  }
-  return false;
-}
-
-/** D4 helper: direct VECTOR-family children count. */
-function vectorChildCountRaw(n) {
-  return (n.children || []).filter(c => VECTOR_TYPE_RE.test(c.type || '')).length;
-}
-
-// ─── Tree ───────────────────────────────────────────────────────────
-
-function walk(node, parentAbsBBox) {
-  const css = extractCSS(node);
-  const r = { nodeId: node.id, name: node.name||'', type: node.type, size: null, css: {...css}, children: [] };
-  if (node.type==='TEXT' && node.characters) r.text = node.characters;
-  if (node.absoluteBoundingBox) r.size = { width: Math.round(node.absoluteBoundingBox.width), height: Math.round(node.absoluteBoundingBox.height) };
-  // Unpack internal fields → top-level metadata
-  if (css._imageRef) { r.imageRef = css._imageRef; delete r.css._imageRef; }
-  if (css._imageScaleMode) { r.imageScaleMode = css._imageScaleMode; delete r.css._imageScaleMode; }
-  if (css._fills) { r.fills = css._fills; delete r.css._fills; }
-  // Mask flag (converter skips or applies clip-path)
-  if (node.isMask) r.isMask = true;
-  // layoutSizing metadata (converter uses with parent context)
-  if (node.layoutSizingHorizontal) r.layoutSizingH = node.layoutSizingHorizontal;
-  if (node.layoutSizingVertical) r.layoutSizingV = node.layoutSizingVertical;
-  // Absolute positioning: parent-relative top/left
-  if (node.layoutPositioning === 'ABSOLUTE' && node.absoluteBoundingBox && parentAbsBBox) {
-    r.css.top = `${Math.round(node.absoluteBoundingBox.y - parentAbsBBox.y)}px`;
-    r.css.left = `${Math.round(node.absoluteBoundingBox.x - parentAbsBBox.x)}px`;
-  }
-  // Raw Figma values (for raw-vs-computed reconciliation in verification phase)
-  const raw = extractRaw(node);
-  if (Object.keys(raw).length) r.raw = raw;
-  // Translation-loss warnings (Figma → CSS incompatibilities)
-  const warnings = auditNode(node);
-  if (warnings.length) r.warnings = warnings;
-  // Determination metadata (Q1, Q2, D1-D3) — used downstream to decide <img> vs CSS bg vs composite
-  if (hasTextDescendantRaw(node)) r.hasTextChildren = true;
-  if (hasRepeatingInstancesRaw(node)) r.hasInstanceRepeat = true;
-  if (node.type === 'TEXT' && isDesignTextNode(node)) r.isDesignText = true;
-  const vcnt = vectorChildCountRaw(node);
-  if (vcnt > 0) r.vectorChildCount = vcnt;
-  if (node.children?.length) r.children = node.children.map(c => walk(c, node.absoluteBoundingBox));
-  return r;
-}
-
-/** Aggregate all warnings in a tree into a rollup keyed by severity. */
-function rollupWarnings(tree) {
-  const all = [];
-  function visit(n) {
-    if (n.warnings?.length) {
-      for (const w of n.warnings) all.push({ nodeId: n.nodeId, name: n.name, ...w });
-    }
-    (n.children || []).forEach(visit);
-  }
-  visit(tree);
-  const p1 = all.filter(w => w.severity === 'P1').length;
-  const p2 = all.filter(w => w.severity === 'P2').length;
-  return { total: all.length, p1, p2, items: all };
-}
-
-function collectRefs(node, set = new Set()) {
-  if (node.imageRef) set.add(node.imageRef);
-  if (node.fills) { for (const f of node.fills) { if (f.imageRef) set.add(f.imageRef); } }
-  (node.children||[]).forEach(c => collectRefs(c, set));
-  return set;
-}
-
-// ─── Commands ───────────────────────────────────────────────────────
-
-async function cmdTree(token, fk, nid, depth) {
-  const dp = depth ? `&depth=${depth}` : '';
-  const data = await apiFetch(`/files/${fk}/nodes?ids=${nid}${dp}`, token);
-  const nd = data.nodes?.[nid];
-  if (!nd?.document) fail(`Node ${nid} not found`);
-  const tree = walk(nd.document);
-  tree.auditSummary = rollupWarnings(tree);
-  console.log(JSON.stringify(tree, null, 2));
-}
-
-async function cmdImages(token, fk, nid, outDir, depth) {
-  if (!outDir) fail('--out required');
-  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
-  // tree → refs
-  const dp = depth ? `&depth=${depth}` : '';
-  const data = await apiFetch(`/files/${fk}/nodes?ids=${nid}${dp}`, token);
-  const nd = data.nodes?.[nid];
-  if (!nd?.document) fail(`Node ${nid} not found`);
-  const tree = walk(nd.document);
-  const refs = collectRefs(tree);
-  if (!refs.size) { console.log(JSON.stringify({ total: 0, images: {} })); return; }
-  // download — 병렬 풀 (최대 DOWNLOAD_CONCURRENCY 동시)
-  const allImg = await apiFetch(`/files/${fk}/images`, token);
-  const urls = allImg.meta?.images || {};
-  const imageMap = {};
-  const dlTasks = [];
-  for (const ref of refs) {
-    const url = urls[ref];
-    if (!url) continue;
-    const outWebp = path.join(outDir, ref.slice(0,16) + '.webp');
-    dlTasks.push(() => fetch(url).then(r=>r.arrayBuffer()).then(b=>{
-      const actual = writeAsWebp(Buffer.from(b), outWebp);
-      if (fs.statSync(actual).size > 0) imageMap[ref] = actual;
-    }));
-  }
-  await parallelPool(dlTasks);
-  console.log(JSON.stringify({ total: Object.keys(imageMap).length, images: imageMap }, null, 2));
-}
-
-async function cmdScreenshot(token, fk, nid, outPath) {
-  if (!outPath) fail('--out required');
-  const dir = path.dirname(outPath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  const result = await screenshotWithRecovery(token, fk, nid, outPath);
-  if (!result) fail('Screenshot failed at all scales');
-  console.log(JSON.stringify(result));
-}
-
-/** 에러 보류 & scale 다운 복구: scale=2 → scale=1 → null */
-async function screenshotWithRecovery(token, fk, nid, outPath) {
-  for (const scale of [2, 1]) {
-    const data = await apiFetch(`/images/${fk}?ids=${nid}&format=png&scale=${scale}`, token, { silent: true });
-    if (!data) continue;
-    const url = data.images?.[nid];
-    if (!url) continue;
-    try {
-      const buf = Buffer.from(await (await fetch(url)).arrayBuffer());
-      let finalPath = outPath;
-      if (outPath.endsWith('.webp')) {
-        finalPath = writeAsWebp(buf, outPath);
-      } else {
-        fs.writeFileSync(outPath, buf);
-      }
-      const sz = fs.statSync(finalPath).size;
-      if (sz > 0) return { path: finalPath, size: sz, scale };
-    } catch { /* 보류 — 다음 scale로 */ }
-  }
-  return null;
-}
-
-// ─── Render: HTML + SCSS + Images + Screenshot ─────────────────────
-
-function kebab(str) {
-  return str
-    .replace(/([a-z])([A-Z])/g, '$1-$2')
-    .replace(/[\s_/\\:]+/g, '-')
-    .replace(/[^a-zA-Z0-9-]/g, '')  // 한글 제거 — 클래스명은 영문만
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '')
-    .toLowerCase()
-    .slice(0, 30);  // 최대 30자
-}
-
-function nodeName(node, parentPrefix) {
-  let raw = node.name || '';
-  // TEXT 노드: 텍스트 대신 부모 컨텍스트 + 'text' 사용
-  if (node.type === 'TEXT') raw = raw.slice(0, 20) || 'text';
-  // 의미 없는 이름 정리
-  raw = raw.replace(/^(Frame|Group|Rectangle|Vector|Ellipse)\s*/i, '');
-  if (!raw || /^\d+$/.test(raw)) raw = node.type?.toLowerCase() || 'node';
-  const k = kebab(raw);
-  return parentPrefix ? `${parentPrefix}-${k}` : k;
-}
-
-/** 노드 트리 → HTML 문자열 생성 */
-function toHTML(node, prefix, imgMap, indent = 0) {
-  const pad = '  '.repeat(indent);
-  const cls = nodeName(node, prefix);
-  const lines = [];
-
-  // 이미지 노드
-  if (node.imageRef && imgMap[node.imageRef]) {
-    const isDecorative = node.name?.match(/^(BG|bg|배경|Shadow|Glow|Light|snow|눈|얼음|빙판|트리|Particle)/i);
-    const alt = isDecorative ? '' : (node.name || '');
-    const ariaHidden = isDecorative ? ' aria-hidden="true"' : '';
-    lines.push(`${pad}<img class="${cls}" src="${imgMap[node.imageRef]}" alt="${alt}"${ariaHidden} />`);
-    return lines.join('\n');
-  }
-
-  // 텍스트 노드
-  if (node.type === 'TEXT' && node.text) {
-    const tag = node.text.length > 100 ? 'p' : 'span';
-    lines.push(`${pad}<${tag} class="${cls}">${node.text}</${tag}>`);
-    return lines.join('\n');
-  }
-
-  // 컨테이너 노드
-  const tag = node.type === 'TEXT' ? 'p' : 'div';
-  if (!node.children?.length) {
-    lines.push(`${pad}<${tag} class="${cls}" />`);
-    return lines.join('\n');
-  }
-
-  lines.push(`${pad}<${tag} class="${cls}">`);
-  for (const child of node.children) {
-    lines.push(toHTML(child, cls, imgMap, indent + 1));
-  }
-  lines.push(`${pad}</${tag}>`);
-  return lines.join('\n');
-}
-
-/** 노드 트리 → SCSS 문자열 생성 */
-function toSCSS(node, prefix, indent = 0) {
-  const cls = nodeName(node, prefix);
-  const lines = [];
-  const css = node.css || {};
-  const props = Object.entries(css);
-
-  if (props.length) {
-    lines.push(`.${cls} {`);
-    for (const [k, v] of props) {
-      // camelCase → kebab-case
-      const prop = k.replace(/([A-Z])/g, '-$1').toLowerCase();
-      lines.push(`  ${prop}: ${v};`);
-    }
-    lines.push('}');
-    lines.push('');
-  }
-
-  if (node.children?.length) {
-    for (const child of node.children) {
-      lines.push(toSCSS(child, cls));
-    }
-  }
-  return lines.join('\n');
-}
-
-/** imageRef → 이름 기반 매핑 (해시 아닌 노드 name 사용) */
-function buildImageNames(node, prefix, result = {}) {
-  if (node.imageRef) {
-    const name = nodeName(node, prefix);
-    result[node.imageRef] = name + '.webp';
-  }
-  if (node.children) {
-    for (const child of node.children) {
-      buildImageNames(child, nodeName(node, prefix) || prefix, result);
-    }
-  }
-  return result;
-}
-
-/** Decide how an IMAGE-fill node should render: CSS background vs <img> tag.
- *  Rules (first match wins):
- *    1. Has TEXT descendants → CSS bg (text would be baked into <img>)
- *    2. Has repeating instance children → CSS bg (repeats need HTML structure)
- *    3. Named BG/background → CSS bg
- *    4. Has non-decorative children (type not in VECTOR-family) → CSS bg
- *    5. Leaf named image/photo/thumb/etc → <img>
- *    6. Leaf otherwise → <img> (standalone asset)
- */
-function shouldRenderImageAsBg(node) {
-  if (node.hasTextChildren) return true;
-  if (node.hasInstanceRepeat) return true;
-  if (BG_NAME_RE.test(node.name || '')) return true;
-  const kids = node.children || [];
-  const contentKids = kids.filter(c => !VECTOR_TYPE_RE.test(c.type || '') && c.type !== 'RECTANGLE');
-  if (contentKids.length > 0) return true;
-  if (kids.length > 0) return true; // any non-leaf with fills is a container → bg
-  if (FOREGROUND_IMG_NAME_RE.test(node.name || '')) return false;
-  return false; // leaf fallback: <img>
-}
-
-/** Walk tree and convert IMAGE-fill nodes that are actually backgrounds into CSS background-image.
- *  Mutates node.css and removes node.imageRef so downstream toHTML emits a container <div>. */
-function resolveImageFills(node, imgMap) {
-  if (node.imageRef && imgMap[node.imageRef] && shouldRenderImageAsBg(node)) {
-    const url = imgMap[node.imageRef];
-    const scaleMode = node.imageScaleMode;
-    const bgSize = scaleMode === 'FIT' ? 'contain' : scaleMode === 'TILE' ? 'auto' : 'cover';
-    const bgRepeat = scaleMode === 'TILE' ? 'repeat' : 'no-repeat';
-    node.css.backgroundImage = `url('${url}')`;
-    node.css.backgroundSize = bgSize;
-    node.css.backgroundRepeat = bgRepeat;
-    node.css.backgroundPosition = 'center';
-    node.renderAsBg = true;
-    delete node.imageRef;
-  }
-  for (const c of node.children || []) resolveImageFills(c, imgMap);
-}
-
-/**
- * @param {{ outDir?: string, depth?: number, scale?: number }} opts
- */
-async function cmdRender(token, fk, nid, opts) {
-  const { outDir, depth, scale } = opts;
-  if (!outDir) fail('--out=<dir> required');
-  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
-
-  const imgDir = path.join(outDir, 'images');
-  if (!fs.existsSync(imgDir)) fs.mkdirSync(imgDir, { recursive: true });
-
-  // 1. 트리 + 이미지 URL을 동시에 가져오기 (스트리밍 겹침)
-  const dp = depth ? `&depth=${depth}` : '';
-  const [treeData, allImg] = await Promise.all([
-    apiFetch(`/files/${fk}/nodes?ids=${nid}${dp}`, token),
-    apiFetch(`/files/${fk}/images`, token, { silent: true }),
-  ]);
-  const nd = treeData.nodes?.[nid];
-  if (!nd?.document) fail(`Node ${nid} not found`);
-  const tree = walk(nd.document);
-  tree.auditSummary = rollupWarnings(tree);
-
-  // 2. 이미지 이름 매핑 (노드 name 기반)
-  const sectionPrefix = kebab(tree.name);
-  const imageNames = buildImageNames(tree, sectionPrefix);
-  const refs = collectRefs(tree);
-
-  // 3. fill 이미지 다운로드 — 병렬 풀 (safe: 파일 다운로드)
-  let imageMap = {};
-  const urls = allImg?.meta?.images || {};
-  if (refs.size) {
-    const dlTasks = [];
-    for (const ref of refs) {
-      const url = urls[ref];
-      if (!url) continue;
-      const fileName = imageNames[ref] || ref.slice(0, 16) + '.webp';
-      const filePath = path.join(imgDir, fileName);
-      dlTasks.push(() => fetch(url).then(r => r.arrayBuffer()).then(b => {
-        const actual = writeAsWebp(Buffer.from(b), filePath);
-        const actualName = path.basename(actual);
-        if (fs.statSync(actual).size > 0) imageMap[ref] = `images/${actualName}`;
-      }));
-    }
-    // 다운로드 시작 (병렬) — BG screenshot 수집과 동시 진행
-    var downloadPromise = parallelPool(dlTasks);
-  }
-
-  // 4. 복합 BG 노드 → 순차 큐 (unsafe: Figma render API rate limit)
-  //    텍스트/반복 인스턴스가 섞인 BG는 composite 캡처 금지 — 이미지에 TEXT가 굽혀
-  //    HTML 레이어와 중복되거나, 리스트/카드를 한 장으로 뭉개버리는 회귀가 있음
-  //    (exchange-section1, daily-step2-list, prize-section1 케이스)
-  const bgTasks = [];
-  for (const child of tree.children || []) {
-    if (!BG_NAME_RE.test(child.name) || !(child.children?.length > 3)) continue;
-    if (child.hasTextChildren) continue; // TEXT 포함 → HTML로 분리 처리
-    if (child.hasInstanceRepeat) continue; // 반복 인스턴스 → v-for로 처리
-    const bgName = `${sectionPrefix}-bg-composite.webp`;
-    const bgPath = path.join(imgDir, bgName);
-    bgTasks.push(async () => {
-      const result = await screenshotWithRecovery(token, fk, child.nodeId, bgPath);
-      if (result) {
-        const actualName = path.basename(result.path);
-        imageMap[`__bg_${child.nodeId}`] = `images/${actualName}`;
-        child.imageRef = `__bg_${child.nodeId}`;
-        child.children = [];
-      }
-      return result;
-    });
-  }
-
-  // 5. 섹션 스크린샷도 순차 큐에 추가
-  const screenshotPath = path.join(outDir, `${sectionPrefix}-screenshot.webp`);
-  let actualScreenshot = screenshotPath;
-  bgTasks.push(async () => {
-    const result = await screenshotWithRecovery(token, fk, nid, screenshotPath);
-    if (result) actualScreenshot = result.path;
-    return result;
-  });
-
-  // 6. 병렬 다운로드 + 순차 스크린샷을 동시 실행 (스트리밍 겹침)
-  await Promise.all([
-    downloadPromise || Promise.resolve(),
-    sequentialQueue(bgTasks),
-  ]);
-
-  // 6b. IMAGE-fill 노드를 CSS background 로 변환 (배경성이면 <img> 금지)
-  resolveImageFills(tree, imageMap);
-
-  // 7. HTML 생성
-  const html = toHTML(tree, '', imageMap);
-  fs.writeFileSync(path.join(outDir, `${sectionPrefix}.html`), html);
-
-  // 8. SCSS 생성
-  const scss = toSCSS(tree, '');
-  fs.writeFileSync(path.join(outDir, `${sectionPrefix}.scss`), scss);
-
-  // 9. 트리 JSON 저장
-  fs.writeFileSync(path.join(outDir, `${sectionPrefix}.json`), JSON.stringify(tree, null, 2));
-
-  // 출력 요약
-  console.log(JSON.stringify({
-    section: sectionPrefix,
-    files: {
-      html: `${sectionPrefix}.html`,
-      scss: `${sectionPrefix}.scss`,
-      json: `${sectionPrefix}.json`,
-      screenshot: path.basename(actualScreenshot),
-    },
-    images: imageMap,
-    imageCount: Object.keys(imageMap).length,
-    auditSummary: tree.auditSummary,
-  }, null, 2));
-}
-
-// ─── Exports (for tests) ────────────────────────────────────────────
-
-export {
-  walk,
-  extractCSS,
-  isDesignTextNode,
-  hasTextDescendantRaw,
-  hasRepeatingInstancesRaw,
-  vectorChildCountRaw,
-  shouldRenderImageAsBg,
-  resolveImageFills,
-  toHTML,
-};
-
-// ─── CLI ────────────────────────────────────────────────────────────
-
-const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
-if (invokedDirectly) {
-  const args = process.argv.slice(2);
-  const flags = {};
-  const pos = [];
-  for (const a of args) {
-    if (a.startsWith('--')) { const [k,v] = a.slice(2).split('='); flags[k] = v ?? ''; }
-    else pos.push(a);
-  }
-
-  const token = loadToken();
-  if (!token) fail('Figma token not found. Run: vibe figma setup <token>');
-
-  const [cmd, fk, nidRaw] = pos;
-  const nid = nidRaw?.replace(/-/g, ':');
-
-  switch (cmd) {
-    case 'tree': await cmdTree(token, fk, nid, flags.depth ? +flags.depth : undefined); break;
-    case 'images': await cmdImages(token, fk, nid, flags.out, flags.depth ? +flags.depth : 10); break;
-    case 'screenshot': await cmdScreenshot(token, fk, nid, flags.out); break;
-    case 'render': await cmdRender(token, fk, nid, { outDir: flags.out, depth: flags.depth ? +flags.depth : 10, scale: flags.scale ? +flags.scale : 0.667 }); break;
-    default: console.log('Usage: node figma-extract.js <tree|images|screenshot|render> <fileKey> <nodeId> [flags]');
-  }
-}