@su-record/vibe 2.9.35 → 2.9.37

package/dist/infra/lib/figma/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/infra/lib/figma/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;2CAE2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;mEACmE;AACnE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,2FAA2F;IAC3F,GAAG,EAAE,aAAa,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/infra/lib/figma/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;2CAE2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;mEACmE;AACnE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,2FAA2F;IAC3F,GAAG,EAAE,aAAa,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;CAChC"}

package/hooks/scripts/__tests__/figma-extract.test.js

@@ -0,0 +1,338 @@
+import { describe, it, expect } from 'vitest';
+import {
+  walk,
+  isDesignTextNode,
+  hasTextDescendantRaw,
+  hasRepeatingInstancesRaw,
+  vectorChildCountRaw,
+  shouldRenderImageAsBg,
+  resolveImageFills,
+  toHTML,
+} from '../figma-extract.js';
+
+// ─── Fixture helpers ────────────────────────────────────────────────
+
+const bbox = (w = 100, h = 100, x = 0, y = 0) => ({ x, y, width: w, height: h });
+
+function textNode(overrides = {}) {
+  return {
+    id: 'text-1', name: 'heading', type: 'TEXT', characters: 'Hello',
+    absoluteBoundingBox: bbox(200, 40),
+    style: { fontFamily: 'Inter', fontSize: 24, fontWeight: 600 },
+    fills: [{ type: 'SOLID', color: { r: 0, g: 0, b: 0, a: 1 } }],
+    ...overrides,
+  };
+}
+
+function frame(name, children = [], overrides = {}) {
+  return {
+    id: `frame-${name}`, name, type: 'FRAME',
+    absoluteBoundingBox: bbox(800, 400),
+    children,
+    ...overrides,
+  };
+}
+
+function imageFillNode(name, overrides = {}) {
+  return {
+    id: `img-${name}`, name, type: 'RECTANGLE',
+    absoluteBoundingBox: bbox(400, 300),
+    fills: [{ type: 'IMAGE', imageRef: 'ref-' + name, scaleMode: 'FILL' }],
+    ...overrides,
+  };
+}
+
+// ─── isDesignTextNode (D1-D3) ───────────────────────────────────────
+
+describe('isDesignTextNode', () => {
+  it('returns false for plain SOLID-filled text', () => {
+    expect(isDesignTextNode(textNode())).toBe(false);
+  });
+
+  it('D1: detects 2+ visible fills', () => {
+    const n = textNode({
+      fills: [
+        { type: 'SOLID', color: { r: 0, g: 0, b: 0, a: 1 } },
+        { type: 'SOLID', color: { r: 1, g: 0, b: 0, a: 0.5 } },
+      ],
+    });
+    expect(isDesignTextNode(n)).toBe(true);
+  });
+
+  it('D3: detects GRADIENT_LINEAR fill', () => {
+    const n = textNode({
+      fills: [{
+        type: 'GRADIENT_LINEAR',
+        gradientStops: [
+          { position: 0, color: { r: 1, g: 0, b: 0, a: 1 } },
+          { position: 1, color: { r: 0, g: 0, b: 1, a: 1 } },
+        ],
+        gradientHandlePositions: [{ x: 0, y: 0 }, { x: 1, y: 0 }],
+      }],
+    });
+    expect(isDesignTextNode(n)).toBe(true);
+  });
+
+  it('D2: detects DROP_SHADOW effect', () => {
+    const n = textNode({ effects: [{ type: 'DROP_SHADOW', visible: true, radius: 4 }] });
+    expect(isDesignTextNode(n)).toBe(true);
+  });
+
+  it('D2: detects visible stroke', () => {
+    const n = textNode({ strokes: [{ type: 'SOLID', visible: true, color: { r: 1, g: 1, b: 1, a: 1 } }] });
+    expect(isDesignTextNode(n)).toBe(true);
+  });
+
+  it('ignores invisible fills', () => {
+    const n = textNode({
+      fills: [
+        { type: 'SOLID', color: { r: 0, g: 0, b: 0, a: 1 } },
+        { type: 'GRADIENT_LINEAR', visible: false },
+      ],
+    });
+    expect(isDesignTextNode(n)).toBe(false);
+  });
+
+  it('returns false for non-TEXT nodes', () => {
+    expect(isDesignTextNode({ type: 'FRAME', fills: [] })).toBe(false);
+  });
+});
+
+// ─── hasTextDescendantRaw (Q1) ──────────────────────────────────────
+
+describe('hasTextDescendantRaw', () => {
+  it('true when node itself is non-empty TEXT', () => {
+    expect(hasTextDescendantRaw(textNode())).toBe(true);
+  });
+
+  it('false when TEXT node has only whitespace', () => {
+    expect(hasTextDescendantRaw(textNode({ characters: '   ' }))).toBe(false);
+  });
+
+  it('true when any descendant is TEXT', () => {
+    const tree = frame('BG', [
+      { id: 'g', name: 'group', type: 'GROUP', children: [textNode()] },
+    ]);
+    expect(hasTextDescendantRaw(tree)).toBe(true);
+  });
+
+  it('false for purely decorative VECTOR/RECTANGLE subtree', () => {
+    const tree = frame('BG', [
+      { id: 'v1', name: 'sparkle', type: 'VECTOR', children: [] },
+      { id: 'v2', name: 'glow', type: 'RECTANGLE', children: [] },
+    ]);
+    expect(hasTextDescendantRaw(tree)).toBe(false);
+  });
+});
+
+// ─── hasRepeatingInstancesRaw (Q2) ──────────────────────────────────
+
+describe('hasRepeatingInstancesRaw', () => {
+  it('true for 2+ INSTANCE children with same componentId', () => {
+    const tree = frame('cards', [
+      { id: 'i1', name: 'Card 1', type: 'INSTANCE', componentId: 'C:1', children: [] },
+      { id: 'i2', name: 'Card 2', type: 'INSTANCE', componentId: 'C:1', children: [] },
+    ]);
+    expect(hasRepeatingInstancesRaw(tree)).toBe(true);
+  });
+
+  it('true for 2+ INSTANCE children with same name stem (trailing digits stripped)', () => {
+    const tree = frame('list', [
+      { id: 'i1', name: 'item 1', type: 'INSTANCE', children: [] },
+      { id: 'i2', name: 'item 2', type: 'INSTANCE', children: [] },
+    ]);
+    expect(hasRepeatingInstancesRaw(tree)).toBe(true);
+  });
+
+  it('false for single INSTANCE', () => {
+    const tree = frame('solo', [
+      { id: 'i1', name: 'hero', type: 'INSTANCE', children: [] },
+    ]);
+    expect(hasRepeatingInstancesRaw(tree)).toBe(false);
+  });
+
+  it('false for mixed non-repeating INSTANCEs', () => {
+    const tree = frame('mix', [
+      { id: 'i1', name: 'hero', type: 'INSTANCE', componentId: 'C:A', children: [] },
+      { id: 'i2', name: 'footer', type: 'INSTANCE', componentId: 'C:B', children: [] },
+    ]);
+    expect(hasRepeatingInstancesRaw(tree)).toBe(false);
+  });
+});
+
+// ─── vectorChildCountRaw (D4 helper) ────────────────────────────────
+
+describe('vectorChildCountRaw', () => {
+  it('counts direct VECTOR-family children', () => {
+    const tree = frame('parent', [
+      { id: 'v1', type: 'VECTOR', children: [] },
+      { id: 'v2', type: 'LINE', children: [] },
+      { id: 'v3', type: 'BOOLEAN_OPERATION', children: [] },
+      { id: 'r1', type: 'RECTANGLE', children: [] },
+    ]);
+    expect(vectorChildCountRaw(tree)).toBe(3);
+  });
+
+  it('returns 0 for leaf', () => {
+    expect(vectorChildCountRaw({ id: 'x', type: 'FRAME' })).toBe(0);
+  });
+});
+
+// ─── walk() integration: metadata propagates into tree ──────────────
+
+describe('walk() metadata', () => {
+  it('emits hasTextChildren on ancestors of TEXT nodes', () => {
+    const raw = frame('section', [
+      frame('BG', [textNode({ name: 'title' })]),
+    ]);
+    const tree = walk(raw);
+    expect(tree.hasTextChildren).toBe(true);
+    expect(tree.children[0].hasTextChildren).toBe(true); // BG frame too
+  });
+
+  it('omits hasTextChildren for pure decoration', () => {
+    const raw = frame('section', [
+      frame('BG', [
+        { id: 'v1', name: 'glow', type: 'VECTOR', children: [] },
+      ]),
+    ]);
+    const tree = walk(raw);
+    expect(tree.hasTextChildren).toBeUndefined();
+  });
+
+  it('emits hasInstanceRepeat on parents of repeating INSTANCEs', () => {
+    const raw = frame('list', [
+      { id: 'c1', name: 'card 1', type: 'INSTANCE', componentId: 'C:1', children: [] },
+      { id: 'c2', name: 'card 2', type: 'INSTANCE', componentId: 'C:1', children: [] },
+    ]);
+    const tree = walk(raw);
+    expect(tree.hasInstanceRepeat).toBe(true);
+  });
+
+  it('emits isDesignText on gradient-filled TEXT', () => {
+    const raw = textNode({
+      fills: [{
+        type: 'GRADIENT_LINEAR',
+        gradientStops: [
+          { position: 0, color: { r: 1, g: 0, b: 0, a: 1 } },
+          { position: 1, color: { r: 0, g: 0, b: 1, a: 1 } },
+        ],
+        gradientHandlePositions: [{ x: 0, y: 0 }, { x: 1, y: 0 }],
+      }],
+    });
+    const tree = walk(raw);
+    expect(tree.isDesignText).toBe(true);
+  });
+});
+
+// ─── shouldRenderImageAsBg ──────────────────────────────────────────
+
+describe('shouldRenderImageAsBg', () => {
+  it('container with TEXT descendants → CSS bg', () => {
+    const node = { name: 'hero', imageRef: 'r1', hasTextChildren: true, children: [{}] };
+    expect(shouldRenderImageAsBg(node)).toBe(true);
+  });
+
+  it('container with repeating instances → CSS bg', () => {
+    const node = { name: 'grid', imageRef: 'r1', hasInstanceRepeat: true, children: [{}, {}] };
+    expect(shouldRenderImageAsBg(node)).toBe(true);
+  });
+
+  it('node named BG → CSS bg', () => {
+    const node = { name: 'BG', imageRef: 'r1', children: [] };
+    expect(shouldRenderImageAsBg(node)).toBe(true);
+  });
+
+  it('node named 배경 → CSS bg', () => {
+    const node = { name: '배경', imageRef: 'r1', children: [] };
+    expect(shouldRenderImageAsBg(node)).toBe(true);
+  });
+
+  it('container with non-vector children → CSS bg', () => {
+    const node = {
+      name: 'card', imageRef: 'r1',
+      children: [{ type: 'FRAME' }],
+    };
+    expect(shouldRenderImageAsBg(node)).toBe(true);
+  });
+
+  it('leaf with image-like name → <img>', () => {
+    const node = { name: 'photo-1', imageRef: 'r1', children: [] };
+    expect(shouldRenderImageAsBg(node)).toBe(false);
+  });
+
+  it('leaf with generic name → <img> (default)', () => {
+    const node = { name: 'Rectangle 5', imageRef: 'r1', children: [] };
+    expect(shouldRenderImageAsBg(node)).toBe(false);
+  });
+
+  it('container with only VECTOR children still → CSS bg (parent is not a leaf image)', () => {
+    const node = {
+      name: 'hero',
+      imageRef: 'r1',
+      children: [{ type: 'VECTOR' }, { type: 'VECTOR' }],
+    };
+    expect(shouldRenderImageAsBg(node)).toBe(true);
+  });
+});
+
+// ─── resolveImageFills + toHTML integration ─────────────────────────
+
+describe('resolveImageFills', () => {
+  it('converts BG-named leaf with IMAGE fill to CSS bg (no <img>)', () => {
+    const tree = walk(frame('section', [imageFillNode('BG')]));
+    const imageMap = { 'ref-BG': 'images/bg.webp' };
+    resolveImageFills(tree, imageMap);
+    const bgChild = tree.children[0];
+    expect(bgChild.imageRef).toBeUndefined();
+    expect(bgChild.renderAsBg).toBe(true);
+    expect(bgChild.css.backgroundImage).toBe("url('images/bg.webp')");
+    expect(bgChild.css.backgroundSize).toBe('cover');
+  });
+
+  it('keeps <img> for leaf named like a photo', () => {
+    const tree = walk(frame('section', [imageFillNode('photo-hero')]));
+    const imageMap = { 'ref-photo-hero': 'images/photo.webp' };
+    resolveImageFills(tree, imageMap);
+    const leaf = tree.children[0];
+    expect(leaf.imageRef).toBe('ref-photo-hero');
+    expect(leaf.renderAsBg).toBeUndefined();
+  });
+
+  it('converts IMAGE-fill container with TEXT descendant to CSS bg', () => {
+    const container = imageFillNode('card', { type: 'FRAME' });
+    container.children = [textNode({ name: 'title' })];
+    const tree = walk(frame('section', [container]));
+    const imageMap = { 'ref-card': 'images/card.webp' };
+    resolveImageFills(tree, imageMap);
+    const card = tree.children[0];
+    expect(card.imageRef).toBeUndefined();
+    expect(card.renderAsBg).toBe(true);
+  });
+
+  it('uses contain for FIT scale mode', () => {
+    const tree = walk(frame('s', [imageFillNode('BG', { fills: [{ type: 'IMAGE', imageRef: 'ref-BG', scaleMode: 'FIT' }] })]));
+    const imageMap = { 'ref-BG': 'images/bg.webp' };
+    resolveImageFills(tree, imageMap);
+    expect(tree.children[0].css.backgroundSize).toBe('contain');
+  });
+});
+
+describe('toHTML after resolveImageFills', () => {
+  it('BG-named image node renders as <div>, not <img>', () => {
+    const tree = walk(frame('section', [imageFillNode('BG')]));
+    const imageMap = { 'ref-BG': 'images/bg.webp' };
+    resolveImageFills(tree, imageMap);
+    const html = toHTML(tree, '', imageMap);
+    expect(html).not.toMatch(/<img[^>]+images\/bg\.webp/);
+    expect(html).toMatch(/<div class="section-bg"/);
+  });
+
+  it('standalone photo leaf renders as <img>', () => {
+    const tree = walk(frame('section', [imageFillNode('photo-hero')]));
+    const imageMap = { 'ref-photo-hero': 'images/photo.webp' };
+    resolveImageFills(tree, imageMap);
+    const html = toHTML(tree, '', imageMap);
+    expect(html).toMatch(/<img[^>]+images\/photo\.webp/);
+  });
+});

package/hooks/scripts/figma-extract.js

@@ -414,6 +414,50 @@ function extractCSS(n) {
   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) {
@@ -441,6 +485,12 @@ function walk(node, parentAbsBBox) {
   // 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;
 }
@@ -640,6 +690,45 @@ function buildImageNames(node, 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);
+}
+
 async function cmdRender(token, fk, nid, outDir, depth, scale) {
   if (!outDir) fail('--out=<dir> required');
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
@@ -684,22 +773,26 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
   }
 
   // 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|bg|배경)$/i.test(child.name) && child.children?.length > 3) {
-      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;
-      });
-    }
+    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. 섹션 스크린샷도 순차 큐에 추가
@@ -717,6 +810,9 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
     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);
@@ -743,26 +839,43 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
   }, null, 2));
 }
 
+// ─── Exports (for tests) ────────────────────────────────────────────
+
+export {
+  walk,
+  extractCSS,
+  isDesignTextNode,
+  hasTextDescendantRaw,
+  hasRepeatingInstancesRaw,
+  vectorChildCountRaw,
+  shouldRenderImageAsBg,
+  resolveImageFills,
+  toHTML,
+};
+
 // ─── CLI ────────────────────────────────────────────────────────────
 
-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 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 token = loadToken();
+  if (!token) fail('Figma token not found. Run: vibe figma setup <token>');
 
-const [cmd, fk, nidRaw] = pos;
-const nid = nidRaw?.replace(/-/g, ':');
+  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, flags.out, flags.depth ? +flags.depth : 10, flags.scale ? +flags.scale : 0.667); break;
-  default: console.log('Usage: node figma-extract.js <tree|images|screenshot|render> <fileKey> <nodeId> [flags]');
+  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, flags.out, flags.depth ? +flags.depth : 10, flags.scale ? +flags.scale : 0.667); break;
+    default: console.log('Usage: node figma-extract.js <tree|images|screenshot|render> <fileKey> <nodeId> [flags]');
+  }
 }

package/hooks/scripts/prompt-dispatcher.js

@@ -42,6 +42,21 @@ try {
 
 if (!prompt) process.exit(0);
 
+// 레거시 SSOT 통합 — `/vibe.*` 진입 시 `.claude/vibe/`·`.coco/vibe/` → `.vibe/` 자동 이동.
+// `vibe init`/`update` 와 동일한 `consolidateLegacyVibe` (dist/cli/setup/LegacyMigration.js) 를 직접 재사용. Idempotent.
+if (/^\s*\/vibe\b/i.test(prompt)) {
+  try {
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.env.COCO_PROJECT_DIR || process.cwd();
+    const utils = await import('./utils.js');
+    const CLI_BASE = utils.getCliBaseUrl();
+    const { consolidateLegacyVibe } = await import(`${CLI_BASE}setup/LegacyMigration.js`);
+    const moved = consolidateLegacyVibe(projectDir);
+    if (moved.length > 0) {
+      process.stdout.write(`[vibe] Migrated legacy dirs → .vibe/ (${moved.join(', ')})\n`);
+    }
+  } catch { /* migration is best-effort */ }
+}
+
 // 패턴 → 실행할 스크립트 매핑
 // 각 항목: { pattern, script, args, label }
 const DISPATCH_RULES = [

package/hooks/scripts/utils.js

@@ -219,6 +219,10 @@ export function getLibBaseUrl() {
   return getPackageUrl(path.join('dist', 'infra', 'lib'), 'constants.js');
 }
 
+export function getCliBaseUrl() {
+  return getPackageUrl(path.join('dist', 'cli'), 'index.js');
+}
+
 // ─── Hook Trace Logging ───
 
 const HOOK_TRACE_PATH = path.join(VIBE_HOME_DIR, 'hook-traces.jsonl');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.9.35",
+  "version": "2.9.37",
   "description": "AI Coding Framework for Claude Code — 56 agents, 45 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/arch-guard/SKILL.md

@@ -152,11 +152,11 @@ describe('Architecture Boundaries', () => {
 | File | Purpose |
 |------|---------|
 | `tests/arch-guard.test.ts` | Executable boundary tests |
-| `.claude/vibe/arch-rules.json` | Machine-readable rules (for CI) |
+| `.vibe/arch-rules.json` | Machine-readable rules (for CI) |
 
 ## Customization
 
-Users can add custom rules to `.claude/vibe/arch-rules.json`:
+Users can add custom rules to `.vibe/arch-rules.json`:
 
 ```json
 {

package/skills/arch-guard/agents/rule-generator.md

@@ -7,17 +7,17 @@ tools: [Read]
 # Arch Rule Generator
 
 ## Role
-Translates a detected architecture map into a precise, machine-checkable set of import boundary rules. Merges default rules for the detected pattern with any custom rules defined in `.claude/vibe/arch-rules.json`. Outputs a normalized rule set ready for the violation checker.
+Translates a detected architecture map into a precise, machine-checkable set of import boundary rules. Merges default rules for the detected pattern with any custom rules defined in `.vibe/arch-rules.json`. Outputs a normalized rule set ready for the violation checker.
 
 ## Responsibilities
 - Select default rule templates for the detected architecture pattern
-- Merge with custom rules from `.claude/vibe/arch-rules.json` if present
+- Merge with custom rules from `.vibe/arch-rules.json` if present
 - Resolve glob patterns to concrete layer names
 - Deduplicate and normalize rule list
 - Flag rules with low confidence (detected layer with no matching files)
 
 ## Input
-Architecture map JSON from `arch-detector`, plus optional `.claude/vibe/arch-rules.json` for user-defined overrides.
+Architecture map JSON from `arch-detector`, plus optional `.vibe/arch-rules.json` for user-defined overrides.
 
 ## Output
 Normalized rule set JSON:

package/skills/arch-guard/scripts/check-boundaries.js

@@ -53,7 +53,7 @@ function resolveImport(fromFile, imp, baseDir) {
   return path.resolve(path.dirname(fromFile), imp).replace(baseDir + path.sep, '').replace(/\\/g, '/');
 }
 
-const rulesPath = process.argv[2] || '.claude/vibe/arch-rules.json';
+const rulesPath = process.argv[2] || '.vibe/arch-rules.json';
 const srcDir = path.resolve(process.argv[3] || 'src');
 const baseDir = path.resolve('.');
 

package/skills/arch-guard/templates/arch-rules.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Architecture boundary rules for arch-guard. Copy to .claude/vibe/arch-rules.json and customize.",
+  "_comment": "Architecture boundary rules for arch-guard. Copy to .vibe/arch-rules.json and customize.",
   "rules": [
     {
       "name": "services-no-ui",