byuckchon-frontend-cli 1.5.0 → 1.6.1

package/README.md

@@ -91,6 +91,68 @@ bc init
 > 안전망은 git diff. 매 작업 후 `git status` / `git diff` 로 확인하고, 마음에 안 들면 `git checkout .` 으로 되돌리세요.
 > 다음 버전에서 per-file 승인(`y/n/v`) 옵션 추가 예정.
 
+### Figma 연동 — 디자인 → 코드 (v1.6+)
+
+채팅 안에서 모델이 직접 Figma REST API 를 호출해서 디자인 정보를 읽고 컴포넌트/페이지를 만듭니다.
+
+#### 사용자가 한 번만 하는 셋업
+
+```bash
+# 1) Figma → Settings → Personal access tokens → "Generate new token"
+#    Read 권한만 있으면 충분 (file 읽기 / image export 둘 다 read 로 됨)
+
+# 2) 토큰을 .env 에 박기 (gitignore 됨)
+echo "FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxx" >> .env
+
+# 3) bc.config.json 의 design.figma 에 파일/노드 URL 박기 (bc adopt 시점에 입력하거나 직접 편집)
+```
+
+`bc.config.json` 예시:
+
+```json
+{
+  "design": {
+    "figma": "https://www.figma.com/design/ABC123/Marketd-Admin?node-id=2-105",
+    "figmaTokenEnv": "FIGMA_TOKEN"
+  }
+}
+```
+
+#### 디자이너 협업이 필요한 부분
+
+| 디자이너 측 작업                       | 왜 필요?                                                  |
+| --------------------------------------- | --------------------------------------------------------- |
+| 프레임/컴포넌트에 **의미 있는 이름**     | `Frame 21` 이 아니라 `Card/Product/Sold-out` 처럼 의미별로 — AI 가 이름으로 컴포넌트 이름과 variant 를 추론합니다. |
+| **Auto layout** 적용                    | 안 쓰면 픽셀 좌표만 떨어져 `position: absolute` 코드가 나옵니다. Auto layout 이면 자동으로 `flex`/`gap` 변환. |
+| **로컬 스타일** 등록 (color/text)        | "Brand/Primary" 같은 스타일을 등록해두면 `fetch_figma_styles` 로 디자인 토큰을 일괄 추출해서 Tailwind 테마로 바로 박을 수 있어요. |
+| **Components** 화 (♦ 마름모 아이콘)     | 반복 UI 가 component 면 모델이 "이거 디자인 시스템 컴포넌트구나" 인식 → 코드에서도 재사용 컴포넌트를 만듭니다. |
+| frame 별로 **"Copy link to selection"** | 일반 share link 는 파일 전체. 특정 frame URL 을 받아야 AI 가 그것만 정확히 가져옵니다. |
+
+#### 채팅에서 쓰는 법
+
+```text
+you › 새 멤버 카드 컴포넌트 만들어줘. 디자인은 https://www.figma.com/design/.../?node-id=12-34 이거 참고해서.
+
+🔧 fetch_figma("https://www.figma.com/design/.../?node-id=12-34")
+🔧 list_files("src/components/**/Card*")
+🔧 read_file("src/components/Card/ProductCard.tsx")
+🆕 생성 src/components/Card/MemberCard/MemberCard.tsx (52 lines)
+🆕 생성 src/components/Card/MemberCard/index.ts (3 lines)
+bc › Auto layout 이 row 였고 padding 12/16 이었어요. MemberCard 만들었습니다.
+     기존 ProductCard 와 같은 폴더 컨벤션을 따랐어요.
+```
+
+내장 Figma 툴:
+
+| 툴                    | 동작                                                          |
+| --------------------- | ------------------------------------------------------------- |
+| `fetch_figma`         | 노드 트리 (autoLayout / fills / text / size / children) 가져오기 |
+| `fetch_figma_image`   | 프레임을 PNG/JPG/SVG 로 export — public asset 으로 저장도 가능 |
+| `fetch_figma_styles`  | 파일의 컬러/타이포 토큰 목록 → 디자인 토큰 generator 만들 때    |
+
+> Figma 응답은 자동으로 압축됩니다 (자식 60개, 깊이 8 까지). 너무 큰 프레임은 더 작은
+> 자식 frame URL 을 줘서 분할 정복하세요.
+
 ### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
 
 `bc.config.json` 의 `api.openapi` 와 코드 인덱스는 **chat 시작할 때 알아서 준비됩니다.**
@@ -202,17 +264,39 @@ TTY 안에서 자동으로 ink 모드로 뜨고, 파이프/CI 같은 비-TTY 환
 이미지 첨부는 png / jpg / jpeg / gif / webp 만 지원하며,
 Claude / GPT 비전 모델에 멀티파트 메시지로 전달됩니다.
 
-**이미지 첨부 3가지 방법:**
+**이미지 첨부 3가지 방법:** (ink·plain 모드 모두 지원 — v1.6.1+)
 1. `/image ./shot.png` — 경로 직접
 2. **드래그 & 드롭** — `/image ` 까지 입력 후, Finder 에서 파일을 터미널 위로 끌어다 놓으면 절대경로가 자동 입력됩니다. Enter.
-3. `/paste` — **macOS 한정**, 클립보드의 이미지(예: `Cmd+Shift+4` 스크린샷)를 바로 첨부.
+3. `/paste` — **macOS 한정**, 클립보드의 이미지(예: `Cmd+Shift+4` 스크린샷 또는 Finder 에서 `Cmd+C` 한 이미지)를 바로 첨부.
    - 사전에 `brew install pngpaste` 한 번 필요.
 
-### 한글 입력이 안 보일 때
+> **터미널에서 `Cmd+V` 로 직접 붙이기는 왜 안 되나?** 터미널 앱은 클립보드의 "이미지 바이트" 를
+> 앱에 전달하지 않고 텍스트만 줍니다 (OS/터미널 공통 제약). 그래서 클립보드 이미지를 붙이려면
+> `/paste` 가 `pngpaste` 로 클립보드를 직접 읽어 첨부합니다 — `Cmd+C` → 입력창에 `/paste` → Enter.
+
+> **썸네일 미리보기:** iTerm2 · kitty · WezTerm 에서는 plain 모드에서 첨부 직후 작은 썸네일이
+> 인라인으로 표시됩니다. 그 외 터미널은 파일명 + 용량만 표시됩니다 (터미널이 이미지 렌더링을
+> 지원하지 않기 때문).
+
+### 한글 입력이 자꾸 씹힐 때 (v1.6+)
+
+`ink` 의 TextInput 은 macOS 한글 IME 의 조합 단계와 충돌해 글자가 한 박자 늦게 보이거나
+빠뜨려지는 경우가 있습니다 — ink-text-input 의 알려진 한계입니다.
+
+**가장 확실한 해결**: 입력 모드를 plain(readline) 으로 영구 전환
+
+```bash
+bc config set-ui plain    # 글로벌로 plain 모드 고정
+# 한글 입력 안정, 모든 기본 기능 동작 (RAG, OpenAPI, Figma 툴 호출까지)
+# 단, ink 전용 기능 일부 미지원: 슬래시 자동완성 메뉴, 인라인 이미지 첨부
+```
+
+ink 로 다시 돌아오려면:
+```bash
+bc config set-ui ink
+```
 
-ink 가 터미널 커서를 숨겨버려서 macOS 한글 IME 의 조합 미리보기가 안 보이는 이슈가 있었습니다.
-v1.4 부터는 ink 시작 후 커서를 강제로 다시 켜고 가짜 커서를 끄는 방식으로 수정되어 정상 동작해야 합니다.
-혹시 그래도 문제가 보이면 `bc chat --plain` 으로 readline 모드를 쓸 수 있습니다 (TUI 기능은 일부 제한).
+일회성으로 plain 만 쓰고 싶으면 `bc chat --plain`.
 
 ### `bc config` — 설정
 
@@ -224,6 +308,8 @@ bc config set-key anthropic                 # 키 안전 입력 (가려짐)
 bc config set-key anthropic sk-ant-...      # 직접 지정
 bc config set-gateway https://ai.example.com  # 사내 게이트웨이 모드
 bc config set-gateway                       # 게이트웨이 해제 (BYOK 모드)
+bc config set-ui plain                      # 한글 IME 안정 모드
+bc config set-ui ink                        # 풀 TUI 복귀
 ```
 
 ## 설정 위치
@@ -263,7 +349,9 @@ bc config set-gateway                       # 게이트웨이 해제 (BYOK 모
 - [x] Phase 3c-1: chat 시작 시 인덱스 자동 빌드, OpenAPI 자동 fetch+캐시+시스템 프롬프트 주입
 - [x] v1.4.1 — `deepMerge(null, obj)` TypeError 수정 (`bc adopt` 한 프로젝트에서 모든 명령이 터지던 버그)
 - [x] v1.5.0 — 에이전트 모드 (read/list/search/write/edit 툴) — AI 가 실제 파일을 만든다
-- [ ] v1.6.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
+- [x] v1.6.0 — Figma 툴 (fetch_figma / image / styles), 한글 IME 안정 plain 모드 (`bc config set-ui plain`)
+- [x] v1.6.1 — 툴 스키마 `jsonSchema()` 래핑 (`schema is not a function` 수정), plain 모드 이미지 첨부(`/image`·`/paste`) + iTerm2/kitty 인라인 썸네일
+- [ ] v1.7.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
 - [ ] Phase 3c-2: Figma 실 fetch (URL → 노드 트리 → 컴포넌트 인텐트)
 - [ ] Phase 4: `bc gen component/page` (AST 편집 + 검증 루프), `/apply` diff 미리보기
 

package/bin/index.js

@@ -17,6 +17,7 @@ import {
   configSetModelCommand,
   configSetKeyCommand,
   configSetGatewayCommand,
+  configSetUiCommand,
 } from '../src/commands/config.js';
 
 // 프로젝트 .env 가 있으면 자동 로드 (ANTHROPIC_API_KEY, OPENAI_API_KEY 등).
@@ -27,7 +28,7 @@ const program = new Command();
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.5.0');
+  .version('1.6.1');
 
 program
   .command('init')
@@ -128,6 +129,13 @@ cfg
     await configSetGatewayCommand(url);
   });
 
+cfg
+  .command('set-ui <mode>')
+  .description('chat 입력 모드: ink (풀 TUI) | plain (readline — 한글 IME 안정)')
+  .action(async (mode) => {
+    await configSetUiCommand(mode);
+  });
+
 program.exitOverride((err) => {
   if (
     err.code === 'commander.help' ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {

package/src/ai/clipboard.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * macOS 클립보드의 이미지(스크린샷 등)를 임시 PNG 로 떨궈 절대경로를 돌려준다.
+ *
+ * 터미널 앱은 Cmd+V 로 "이미지 바이트" 를 받지 못한다 (텍스트만 받음). 그래서
+ * 클립보드 이미지를 붙이려면 OS 클립보드를 직접 읽는 외부 도구가 필요하다.
+ *   - macOS: `pngpaste` (brew install pngpaste)
+ *
+ * 다른 OS 거나 도구가 없으면 도움이 되는 에러로 throw.
+ */
+export async function pasteClipboardImage() {
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      '클립보드 이미지 붙여넣기는 현재 macOS 만 지원합니다. 다른 OS 에서는 파일로 저장하고 /image <경로> 를 쓰세요.',
+    );
+  }
+
+  const checkOk = await new Promise((resolve) => {
+    const p = spawn('which', ['pngpaste']);
+    p.on('close', (code) => resolve(code === 0));
+    p.on('error', () => resolve(false));
+  });
+  if (!checkOk) {
+    throw new Error(
+      'pngpaste 가 필요합니다. 설치: `brew install pngpaste`  (Homebrew 가 없으면 https://brew.sh)',
+    );
+  }
+
+  const tmp = path.join(os.tmpdir(), `bc-paste-${Date.now()}.png`);
+  await new Promise((resolve, reject) => {
+    const p = spawn('pngpaste', [tmp]);
+    let stderr = '';
+    p.stderr.on('data', (d) => (stderr += d.toString()));
+    p.on('close', (code) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(
+            '클립보드에 이미지가 없거나 읽을 수 없습니다.' +
+              (stderr ? ' (' + stderr.trim() + ')' : ''),
+          ),
+        );
+    });
+    p.on('error', (e) => reject(e));
+  });
+
+  const stat = await fs.stat(tmp);
+  if (!stat.isFile() || stat.size === 0) {
+    throw new Error('클립보드 이미지 저장 실패 (파일이 비어있음).');
+  }
+  return tmp;
+}
+
+/**
+ * 드래그&드롭 / 붙여넣기로 들어온 경로 문자열을 정리한다.
+ * - 앞뒤 따옴표 제거
+ * - 백슬래시 이스케이프(`\ `) 제거
+ * - 양끝 공백 제거
+ */
+export function cleanDroppedPath(raw) {
+  if (!raw) return '';
+  let s = raw.trim();
+  if (
+    (s.startsWith("'") && s.endsWith("'")) ||
+    (s.startsWith('"') && s.endsWith('"'))
+  ) {
+    s = s.slice(1, -1);
+  }
+  s = s.replace(/\\ /g, ' ');
+  return s.trim();
+}

package/src/ai/imagePreview.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 터미널 인라인 이미지 프리뷰.
+ *
+ * 일반 터미널은 이미지를 못 그린다. 하지만 일부는 자체 프로토콜이 있다:
+ *   - iTerm2  : OSC 1337 ; File=... (base64) BEL
+ *   - kitty   : APC _G ... ST  (kitty graphics protocol)
+ *   - WezTerm : iTerm2 프로토콜 호환
+ *
+ * 지원되면 작은 썸네일을 직접 stdout 에 그려준다. 안 되면 false 반환 → 호출측에서
+ * 파일명/용량만 텍스트로 표시.
+ *
+ * ⚠️ ink TUI 안에서는 re-render 가 escape 시퀀스를 덮어쓰므로 쓰지 않는다.
+ *    readline(plain) 모드처럼 stdout 을 직접 쓰는 곳에서만 사용.
+ */
+export function detectInlineImageSupport() {
+  const term = process.env.TERM ?? '';
+  const prog = process.env.TERM_PROGRAM ?? '';
+  if (prog === 'iTerm.app' || prog === 'WezTerm') return 'iterm2';
+  if (term.includes('kitty') || process.env.KITTY_WINDOW_ID) return 'kitty';
+  return null;
+}
+
+const ESC = '\u001B';
+const BEL = '\u0007';
+
+/** iTerm2 inline image. heightCells 만큼만 차지하도록 제한해 작은 썸네일로. */
+function itermInline(base64, { heightCells = 6 } = {}) {
+  const args = [
+    'inline=1',
+    `height=${heightCells}`,
+    'preserveAspectRatio=1',
+  ].join(';');
+  return `${ESC}]1337;File=${args}:${base64}${BEL}`;
+}
+
+/** kitty graphics — 한 번에 전송(a=T), 직접 표시. */
+function kittyInline(base64) {
+  // kitty 는 4096 바이트 청크로 쪼개야 한다.
+  const CHUNK = 4096;
+  let out = '';
+  let first = true;
+  for (let i = 0; i < base64.length; i += CHUNK) {
+    const piece = base64.slice(i, i + CHUNK);
+    const more = i + CHUNK < base64.length ? 1 : 0;
+    if (first) {
+      out += `${ESC}_Ga=T,f=100,m=${more};${piece}${ESC}\\`;
+      first = false;
+    } else {
+      out += `${ESC}_Gm=${more};${piece}${ESC}\\`;
+    }
+  }
+  return out;
+}
+
+/**
+ * 이미지 파일을 작은 썸네일로 터미널에 그린다.
+ * @returns {Promise<boolean>} 그렸으면 true, 미지원이면 false
+ */
+export async function printInlineThumbnail(filePath, { heightCells = 6 } = {}) {
+  const kind = detectInlineImageSupport();
+  if (!kind) return false;
+  try {
+    const buf = await fs.readFile(path.resolve(filePath));
+    // 너무 크면 프리뷰 스킵 (전송 비용). 2MB 초과면 패스.
+    if (buf.byteLength > 2 * 1024 * 1024) return false;
+    const base64 = buf.toString('base64');
+    if (kind === 'iterm2') {
+      process.stdout.write('  ' + itermInline(base64, { heightCells }) + '\n');
+    } else if (kind === 'kitty') {
+      process.stdout.write('  ' + kittyInline(base64) + '\n');
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/ai/systemPrompt.js

@@ -28,6 +28,18 @@ export function buildSystemPrompt({ effective, paths, project }) {
     '     - 자동 생성된 `*.gen.ts` 가 있다면 거기서 타입을 import 해서 재정의를 피한다.',
     '  3) 마지막으로 **만든 파일 목록과 다음 액션(어디서 import 하면 되는지 등)** 을 한국어로 짧게 요약.',
     '',
+    '## Figma 작업 (디자인 → 코드)',
+    '사용자가 Figma 링크를 던지거나 "디자인대로 만들어줘" 같은 요청을 하면:',
+    '  1) `fetch_figma(url)` 로 디자인 트리를 받는다. 노드의 name, autoLayout, fills, text, size 를 학습.',
+    '  2) 필요하면 `fetch_figma_styles(url)` 로 컬러/타이포 토큰을 받아 Tailwind config 또는 theme 변수에 반영.',
+    '  3) `list_files` 로 기존 UI 컴포넌트 폴더 구조를 보고, 같은 컨벤션 따라 `write_file` 로 생성.',
+    '  4) Figma `INSTANCE` (= 디자인 시스템 컴포넌트) 가 보이면 기존 코드의 동일 컴포넌트를 ',
+    '     `search_code` 로 찾아 재사용한다. 없으면 컴포넌트부터 생성.',
+    '  5) 픽셀 좌표(absoluteBoundingBox) 보다 **autoLayout** 우선. autoLayout 이 있으면',
+    '     `flex direction={row|col} gap-x` 패턴으로 짠다. 없으면 디자이너에게 ',
+    '     "Auto layout 으로 정리해달라" 고 요청하라고 안내.',
+    '  6) 색은 가능하면 fills 의 raw rgba 대신 Tailwind 색 이름이나 디자인 토큰을 사용.',
+    '',
     '"코드 짜줘" 라는 표현은 채팅창에 코드 블록을 출력하라는 의미가 **아니다**.',
     '항상 툴을 사용해 실제 파일을 만들어라. 채팅에는 진행 상황과 결과 요약만 짧게 적는다.',
     '',
@@ -57,7 +69,13 @@ export function buildSystemPrompt({ effective, paths, project }) {
       }\``,
     );
   }
-  if (project?.design?.figma) meta.push(`- Figma: ${project.design.figma}`);
+  if (project?.design?.figma) {
+    meta.push(`- Figma: ${project.design.figma}`);
+    meta.push(
+      '  (Figma 작업 요청을 받으면 fetch_figma 툴로 디자인을 먼저 읽고, ' +
+        '필요하면 fetch_figma_styles 로 토큰을 가져와 코드를 짠다.)',
+    );
+  }
   if (project?.api?.openapi) meta.push(`- OpenAPI: ${project.api.openapi}`);
   if (project?.api?.baseUrl) meta.push(`- API base URL: ${project.api.baseUrl}`);
   if (effective?.model) meta.push(`- 사용 모델: ${effective.model}`);

package/src/ai/tools.js

@@ -2,9 +2,16 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import fg from 'fast-glob';
-import { tool } from 'ai';
+import { tool, jsonSchema } from 'ai';
 
 import { searchIndex } from '../indexer/search.js';
+import {
+  fetchFromUrl as fetchFigmaFromUrl,
+  fetchImageUrls as fetchFigmaImageUrls,
+  fetchStyles as fetchFigmaStyles,
+} from '../figma/api.js';
+import { simplifyFetchNodes } from '../figma/simplify.js';
+import { parseFigmaUrl } from '../figma/url.js';
 
 /**
  * Agentic chat 용 툴 정의.
@@ -164,35 +171,120 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
     return { ok: true, path: rel, action: 'edited' };
   }
 
+  // ─────────── Figma 툴 ───────────
+
+  async function fetchFigma({ url, depth = 4 }) {
+    try {
+      const result = await fetchFigmaFromUrl({ url, effective, depth });
+      if (result.kind === 'file') {
+        return {
+          ok: true,
+          kind: 'file_summary',
+          file: result.summary.name,
+          pages: result.summary.pages,
+          hint:
+            'node-id 가 없는 파일 링크입니다. 디자이너에게 특정 frame 의 ' +
+            '"Copy link to selection" 을 받아오면 더 정확한 코드 생성 가능.',
+        };
+      }
+      const simple = simplifyFetchNodes(result.raw);
+      return {
+        ok: true,
+        kind: 'nodes',
+        fileKey: result.fileKey,
+        nodeId: result.nodeId,
+        documents: simple.documents,
+        components: simple.components,
+        styles: simple.styles,
+      };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err), status: err?.status };
+    }
+  }
+
+  async function fetchFigmaImage({ url, format = 'png', scale = 2, savePath }) {
+    try {
+      const parsed = parseFigmaUrl(url);
+      if (!parsed?.nodeId) {
+        return { ok: false, error: 'node-id 가 있는 frame 링크가 필요합니다.' };
+      }
+      const images = await fetchFigmaImageUrls({
+        fileKey: parsed.fileKey,
+        nodeIds: [parsed.nodeId],
+        format,
+        scale,
+        effective,
+      });
+      const imageUrl = images[parsed.nodeId];
+      if (!imageUrl) {
+        return { ok: false, error: 'Figma 가 이미지 URL 을 돌려주지 않음' };
+      }
+      if (savePath) {
+        const { abs, rel } = safePath(savePath);
+        const res = await fetch(imageUrl);
+        const buf = Buffer.from(await res.arrayBuffer());
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, buf);
+        onEvent({ kind: 'write_created', path: rel, bytes: buf.byteLength });
+        return { ok: true, savedTo: rel, bytes: buf.byteLength, format };
+      }
+      return { ok: true, url: imageUrl, format, expiresInSeconds: 60 * 60 * 24 * 14 };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
+  async function fetchFigmaStylesTool({ url }) {
+    try {
+      const parsed = parseFigmaUrl(url);
+      if (!parsed) return { ok: false, error: 'Figma URL 형식이 아닙니다.' };
+      const styles = await fetchFigmaStyles({ fileKey: parsed.fileKey, effective });
+      // 모델이 디자인 토큰을 만들 때 쓸 수 있도록 styleType 별로 그룹.
+      const grouped = {};
+      for (const s of styles) {
+        const t = s.style_type ?? s.styleType ?? 'OTHER';
+        (grouped[t] ??= []).push({
+          name: s.name,
+          description: s.description ?? '',
+          key: s.key,
+          nodeId: s.node_id ?? s.nodeId,
+        });
+      }
+      return { ok: true, fileKey: parsed.fileKey, total: styles.length, grouped };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
   return {
     read_file: tool({
       description:
         '프로젝트 안의 파일이나 디렉터리 내용을 읽는다. 코드 짜기 전에 반드시 기존 코드 컨벤션을 먼저 읽어볼 것.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: { path: { type: 'string', description: '프로젝트 루트 기준 상대 경로' } },
         required: ['path'],
         additionalProperties: false,
-      },
+      }),
       execute: readFile,
     }),
     list_files: tool({
       description:
         '글롭 패턴으로 파일을 나열. 폴더 구조 파악, 비슷한 모듈 위치 찾기에 사용. 예: "src/api/**/*.ts"',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           pattern: { type: 'string', default: '**/*' },
           limit: { type: 'number', default: 100 },
         },
         additionalProperties: false,
-      },
+      }),
       execute: listFiles,
     }),
     search_code: tool({
       description:
         '코드베이스를 의미 기반(임베딩)으로 검색. "fetch 래퍼 패턴", "useQuery hook 컨벤션" 같이 자연어로 찾기. 인덱스가 없으면 에러.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           query: { type: 'string' },
@@ -200,13 +292,13 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['query'],
         additionalProperties: false,
-      },
+      }),
       execute: searchCode,
     }),
     write_file: tool({
       description:
         '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           path: { type: 'string' },
@@ -214,13 +306,13 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['path', 'content'],
         additionalProperties: false,
-      },
+      }),
       execute: writeFile,
     }),
     edit_file: tool({
       description:
         '기존 파일에서 old_string 을 찾아 new_string 으로 정확히 1번 치환. old_string 은 파일 안에서 유일해지도록 충분한 컨텍스트(앞뒤 줄) 를 포함시킬 것. 여러 번 등장하면 에러로 거부.',
-      inputSchema: {
+      inputSchema: jsonSchema({
         type: 'object',
         properties: {
           path: { type: 'string' },
@@ -229,8 +321,54 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
         },
         required: ['path', 'old_string', 'new_string'],
         additionalProperties: false,
-      },
+      }),
       execute: editFile,
     }),
+    fetch_figma: tool({
+      description:
+        'Figma 노드 트리(컴포넌트/프레임/페이지) 를 읽는다. URL 에 node-id 가 있으면 그 frame 의 ' +
+        '간소화된 디자인 정보(autoLayout, fills, text, size, children 등) 를 반환. ' +
+        '없으면 파일 페이지 목록만. 컴포넌트/페이지 생성 요청을 받으면 이 툴을 먼저 호출해서 ' +
+        '디자인 의도를 학습한 뒤 코드를 짠다.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'Figma share/copy link' },
+          depth: { type: 'number', default: 4, description: '노드 트리 탐색 깊이 (1-8)' },
+        },
+        required: ['url'],
+        additionalProperties: false,
+      }),
+      execute: fetchFigma,
+    }),
+    fetch_figma_image: tool({
+      description:
+        'Figma 프레임을 PNG/JPG/SVG 이미지로 export. savePath 를 주면 프로젝트 폴더 안에 파일로 저장 ' +
+        '(스토리북 배경, public asset 등). 안 주면 임시 URL 만 반환.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          url: { type: 'string' },
+          format: { type: 'string', enum: ['png', 'jpg', 'svg', 'pdf'], default: 'png' },
+          scale: { type: 'number', default: 2 },
+          savePath: { type: 'string' },
+        },
+        required: ['url'],
+        additionalProperties: false,
+      }),
+      execute: fetchFigmaImage,
+    }),
+    fetch_figma_styles: tool({
+      description:
+        'Figma 파일의 로컬 스타일(컬러/타이포/이펙트 토큰) 목록을 가져온다. 디자인 토큰 추출 / ' +
+        'Tailwind 테마 설정 / theme.ts 생성 시 사용.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: { url: { type: 'string' } },
+        required: ['url'],
+        additionalProperties: false,
+      }),
+      execute: fetchFigmaStylesTool,
+    }),
   };
 }

package/src/commands/adopt.js

@@ -141,6 +141,13 @@ export async function adoptCommand(opts = {}) {
   if (!process.env.ANTHROPIC_API_KEY) {
     console.log(chalk.dim('    bc config set-key anthropic    # API 키 등록'));
   }
+  if (next.design.figma && !process.env.FIGMA_TOKEN) {
+    console.log(
+      chalk.dim(
+        '    .env 에 FIGMA_TOKEN=figd-... 추가  # https://www.figma.com/settings 에서 발급',
+      ),
+    );
+  }
   console.log(chalk.dim('    bc chat                        # 이 프로젝트 컨텍스트로 대화'));
   console.log();
 }

package/src/commands/chat.js

@@ -11,6 +11,9 @@ import { TokenMeter } from '../ai/tokenMeter.js';
 import { buildSystemPrompt } from '../ai/systemPrompt.js';
 import { findModel } from '../ai/models.js';
 import { buildTools } from '../ai/tools.js';
+import { toSdkMessages, isImagePath, imagePartFromFile } from '../ai/messageContent.js';
+import { pasteClipboardImage, cleanDroppedPath } from '../ai/clipboard.js';
+import { printInlineThumbnail } from '../ai/imagePreview.js';
 import {
   createSession,
   saveSession,
@@ -133,8 +136,11 @@ export async function chatCommand(opts = {}) {
   await saveSession(session); // 빈 파일이라도 디스크에 만들어둠
 
   // ink 는 stdin/stdout 둘 다 TTY 이어야 정상 동작.
+  // - --plain 플래그가 명시되거나 비-TTY 면 readline 폴백.
+  // - 글로벌 ui.mode 가 "plain" 이면 한글 IME 가 깨지는 케이스를 자동 회피.
   const isTTY = process.stdin.isTTY && process.stdout.isTTY;
-  if (!isTTY || opts.plain) {
+  const wantPlain = opts.plain || cfg.global?.ui?.mode === 'plain';
+  if (!isTTY || wantPlain) {
     return runReadlineFallback({ cfg, resolved, system, session, openapiInfo });
   }
 
@@ -251,7 +257,46 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
   if (session?.messages?.length) {
     console.log(chalk.dim(`  세션: ${session.id} (${session.messages.length} turns 이어가기)`));
   }
-  console.log(chalk.dim('  /exit 또는 Ctrl+D 로 종료\n'));
+  console.log(
+    chalk.dim('  /image <경로> · /paste(클립보드 이미지) · /clear-attach · /exit\n'),
+  );
+
+  // 다음 메시지에 함께 보낼 이미지 첨부 목록.
+  let pendingAttachments = [];
+
+  const printAttachments = () => {
+    if (!pendingAttachments.length) {
+      console.log(chalk.dim('  첨부 없음.'));
+      return;
+    }
+    console.log(chalk.dim('  현재 첨부:'));
+    for (const a of pendingAttachments) {
+      console.log(chalk.dim(`    - ${path.basename(a.path)} (${a.sizeKb}KB)`));
+    }
+  };
+
+  const addImage = async (rawPath) => {
+    const p = cleanDroppedPath(rawPath);
+    if (!p) {
+      console.log(chalk.red('  사용법: /image <파일 경로>'));
+      return;
+    }
+    if (!isImagePath(p)) {
+      console.log(chalk.red('  지원 확장자: png, jpg, jpeg, gif, webp'));
+      return;
+    }
+    try {
+      const { default: fsp } = await import('node:fs/promises');
+      const stat = await fsp.stat(path.resolve(p));
+      const sizeKb = Math.max(1, Math.round(stat.size / 1024));
+      pendingAttachments.push({ kind: 'image', path: path.resolve(p), sizeKb });
+      console.log(chalk.green(`  📎 첨부: ${path.basename(p)} (${sizeKb}KB)`));
+      // iTerm2 / kitty / WezTerm 이면 작은 썸네일을 바로 보여준다.
+      await printInlineThumbnail(path.resolve(p), { heightCells: 6 });
+    } catch (e) {
+      console.log(chalk.red('  이미지 읽기 실패: ' + (e?.message ?? e)));
+    }
+  };
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -281,7 +326,50 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       rl.close();
       return;
     }
-    history.push({ role: 'user', content: line });
+    // 이미지 첨부 관련 슬래시 명령 — plain 모드에서도 지원.
+    if (line.startsWith('/image')) {
+      await addImage(line.slice('/image'.length).trim());
+      ask();
+      continue;
+    }
+    if (line === '/paste') {
+      try {
+        const file = await pasteClipboardImage();
+        await addImage(file);
+      } catch (e) {
+        console.log(chalk.red('  ' + (e?.message ?? e)));
+      }
+      ask();
+      continue;
+    }
+    if (line === '/attachments') {
+      printAttachments();
+      ask();
+      continue;
+    }
+    if (line === '/clear-attach') {
+      pendingAttachments = [];
+      console.log(chalk.dim('  첨부를 비웠습니다.'));
+      ask();
+      continue;
+    }
+
+    // 일반 메시지 — 첨부가 있으면 멀티모달 content 로 구성.
+    if (pendingAttachments.length) {
+      const parts = [{ type: 'text', text: line }];
+      try {
+        for (const att of pendingAttachments) {
+          parts.push(await imagePartFromFile(att.path));
+        }
+        history.push({ role: 'user', content: parts });
+      } catch (e) {
+        console.log(chalk.red('  첨부 처리 실패: ' + (e?.message ?? e)));
+        history.push({ role: 'user', content: line });
+      }
+      pendingAttachments = [];
+    } else {
+      history.push({ role: 'user', content: line });
+    }
     rl.pause();
 
     const projectRoot = cfg.paths.projectFile
@@ -337,7 +425,14 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
 
     // 세션 자동 저장 — readline 모드에서도 끊김 대비.
     if (session) {
-      session.messages = history.map((h) => ({ role: h.role, text: h.content }));
+      session.messages = history.map((h) => {
+        // 멀티모달(content 가 배열) 인 경우 text 파트만 추출해 저장 (이미지 바이트는 세션에 안 남김).
+        if (Array.isArray(h.content)) {
+          const textPart = h.content.find((p) => p.type === 'text');
+          return { role: h.role, text: textPart?.text ?? '[이미지 첨부]' };
+        }
+        return { role: h.role, text: h.content };
+      });
       try {
         await saveSession(session);
       } catch {

package/src/commands/config.js

@@ -51,6 +51,12 @@ export async function configShowCommand() {
   console.log(
     `    ${chalk.dim('요청 확인')}    ${eff.effective.limits.confirmAtTokens.toLocaleString()} tokens`,
   );
+  console.log();
+  console.log(chalk.bold('  UI'));
+  console.log(
+    `    ${chalk.dim('chat 입력 모드')}  ${eff.global?.ui?.mode ?? 'ink'} ` +
+      chalk.dim('(plain 으로 두면 한글 IME 안정. bc config set-ui plain)'),
+  );
 
   if (eff.paths.projectFile) {
     console.log();
@@ -130,6 +136,24 @@ export async function configSetKeyCommand(provider, key) {
   console.log(chalk.dim(`    파일: ${CONFIG_PATHS.globalFile} (chmod 600)\n`));
 }
 
+export async function configSetUiCommand(mode) {
+  const allowed = ['ink', 'plain'];
+  if (!allowed.includes(mode)) {
+    console.error(chalk.red(`사용법: bc config set-ui <${allowed.join('|')}>`));
+    console.error(
+      chalk.dim(
+        '  ink   = 풀 TUI (기본). 한글 IME 가 종종 씹히는 환경에서는 plain 권장.\n' +
+          '  plain = readline 폴백. 한글 입력 안정, 슬래시 명령/이미지 미지원.\n',
+      ),
+    );
+    process.exit(1);
+  }
+  const global = await loadGlobalConfig();
+  global.ui = { ...(global.ui ?? {}), mode };
+  await saveGlobalConfig(global);
+  console.log(chalk.green(`\n  ✓ chat 입력 모드를 '${mode}' 로 저장했습니다.\n`));
+}
+
 export async function configSetGatewayCommand(url) {
   const global = await loadGlobalConfig();
   global.ai.gateway = url && url.trim() ? url.trim() : null;

package/src/config/index.js

@@ -20,6 +20,7 @@ const DEFAULT_GLOBAL = {
     apiKeys: {
       // anthropic: 'sk-ant-...',
       // openai: 'sk-...',
+      // figma: 'figd-...'   // 통상 .env(FIGMA_TOKEN) 로 둠
     },
     /** 사내 게이트웨이를 쓰는 경우 base URL. 비우면 BYOK 모드. */
     gateway: null,
@@ -30,6 +31,14 @@ const DEFAULT_GLOBAL = {
     /** 한 요청이 이 토큰을 넘으면 사용자에게 확인. */
     confirmAtTokens: 12_000,
   },
+  ui: {
+    /**
+     * "ink" | "plain"
+     * 한글 IME 가 ink 에서 글자가 씹히면 "plain" 으로 두면 항상 readline 모드로 진입.
+     * --plain 플래그를 매번 안 쳐도 됨.
+     */
+    mode: 'ink',
+  },
 };
 
 /**

package/src/figma/api.js

@@ -0,0 +1,117 @@
+import { parseFigmaUrl } from './url.js';
+
+/**
+ * Figma REST API 클라이언트.
+ *
+ * 인증: Personal Access Token 을 `X-Figma-Token` 헤더로 보냄.
+ * 토큰은 https://www.figma.com/settings 에서 "Personal access tokens" 로 발급.
+ *
+ * effective.figmaToken (또는 process.env[figmaTokenEnv]) 에서 키를 가져옴.
+ */
+const BASE = 'https://api.figma.com/v1';
+
+export class FigmaError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function tokenFromEnv(effective) {
+  // 1) bc.config.json design.figmaTokenEnv 로 지정한 환경변수
+  const envName = effective?.design?.figmaTokenEnv ?? 'FIGMA_TOKEN';
+  return process.env[envName] ?? process.env.FIGMA_TOKEN ?? null;
+}
+
+async function call(pathAndQuery, { token }) {
+  if (!token) {
+    throw new FigmaError(
+      'Figma 토큰이 없습니다. https://www.figma.com/settings 에서 Personal access token 을 발급받고 ' +
+        '`.env` 에 `FIGMA_TOKEN=figd_...` 로 등록하세요.',
+    );
+  }
+  const res = await fetch(BASE + pathAndQuery, {
+    headers: { 'X-Figma-Token': token },
+  });
+  if (!res.ok) {
+    let body = null;
+    try {
+      body = await res.text();
+    } catch {
+      /* noop */
+    }
+    throw new FigmaError(`Figma API ${res.status} ${res.statusText}: ${pathAndQuery}`, {
+      status: res.status,
+      body,
+    });
+  }
+  return res.json();
+}
+
+/** 파일의 상위 메타 (페이지 목록만 — 노드 트리는 안 가져옴). */
+export async function fetchFileSummary({ fileKey, effective }) {
+  const token = tokenFromEnv(effective);
+  const data = await call(`/files/${fileKey}?depth=1`, { token });
+  return {
+    fileKey,
+    name: data.name,
+    lastModified: data.lastModified,
+    pages:
+      data.document?.children?.map((c) => ({
+        id: c.id,
+        name: c.name,
+        type: c.type,
+      })) ?? [],
+  };
+}
+
+/** 특정 노드들의 상세 트리를 가져옴 (가장 자주 쓰는 API). */
+export async function fetchNodes({ fileKey, nodeIds, effective, depth }) {
+  const token = tokenFromEnv(effective);
+  const ids = (Array.isArray(nodeIds) ? nodeIds : [nodeIds])
+    .filter(Boolean)
+    .map(encodeURIComponent)
+    .join(',');
+  const depthQ = depth ? `&depth=${depth}` : '';
+  const data = await call(`/files/${fileKey}/nodes?ids=${ids}${depthQ}`, { token });
+  return data;
+}
+
+/** 노드를 이미지(PNG/JPG/SVG)로 export 하는 임시 URL 을 받아옴 */
+export async function fetchImageUrls({ fileKey, nodeIds, format = 'png', scale = 2, effective }) {
+  const token = tokenFromEnv(effective);
+  const ids = nodeIds.map(encodeURIComponent).join(',');
+  const data = await call(
+    `/images/${fileKey}?ids=${ids}&format=${format}&scale=${scale}`,
+    { token },
+  );
+  // 응답: { images: { "1:2": "https://...", ... } }
+  return data.images ?? {};
+}
+
+/** 파일에 정의된 로컬 스타일 (color/typography/effect/grid) */
+export async function fetchStyles({ fileKey, effective }) {
+  const token = tokenFromEnv(effective);
+  const data = await call(`/files/${fileKey}/styles`, { token });
+  return data.meta?.styles ?? data.styles ?? [];
+}
+
+/** URL 한 줄로 시작하는 헬퍼 — chat 의 툴에서 가장 흔히 쓰임. */
+export async function fetchFromUrl({ url, effective, depth }) {
+  const parsed = parseFigmaUrl(url);
+  if (!parsed) {
+    throw new FigmaError(`Figma URL 형식이 아닙니다: ${url}`);
+  }
+  if (!parsed.nodeId) {
+    // node-id 없으면 파일 요약만
+    return { kind: 'file', summary: await fetchFileSummary({ fileKey: parsed.fileKey, effective }) };
+  }
+  const data = await fetchNodes({
+    fileKey: parsed.fileKey,
+    nodeIds: [parsed.nodeId],
+    effective,
+    depth,
+  });
+  return { kind: 'nodes', fileKey: parsed.fileKey, nodeId: parsed.nodeId, raw: data };
+}

package/src/figma/simplify.js

@@ -0,0 +1,180 @@
+/**
+ * Figma 노드 트리를 LLM 이 읽기 좋게 압축한다.
+ *
+ * Figma 원 응답은 노드 하나에 수십 KB 도 흔하다. 그대로 모델에 넣으면 토큰이 폭발하고
+ * 모델도 중요한 게 뭔지 못 찾는다. 다음 정보만 남긴다:
+ *   - 이름 (= 디자이너의 의도. 컴포넌트/페이지 명명 규칙)
+ *   - 타입 (FRAME, COMPONENT, INSTANCE, TEXT, RECTANGLE, ...)
+ *   - 위치/크기 (필요한 경우만)
+ *   - autoLayout (있으면 flex/gap 변환에 핵심)
+ *   - fills (색)
+ *   - strokes
+ *   - effects (shadow)
+ *   - text 의 경우 글자 + 폰트 사양
+ *   - cornerRadius, padding 같은 자주 쓰는 박스 속성
+ *   - 자식들 (재귀)
+ *
+ * 모델은 이 압축본을 받아서 React/Tailwind/styled JSX 를 생성한다.
+ */
+
+const MAX_CHILDREN = 60;
+const MAX_DEPTH = 8;
+
+function pickColor(paint) {
+  if (!paint || paint.visible === false) return null;
+  if (paint.type === 'SOLID' && paint.color) {
+    const { r, g, b } = paint.color;
+    const a = paint.opacity ?? paint.color.a ?? 1;
+    return {
+      type: 'solid',
+      rgba: `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${Number(a.toFixed(3))})`,
+    };
+  }
+  if (paint.type?.startsWith('GRADIENT')) {
+    return {
+      type: 'gradient',
+      kind: paint.type,
+      stops:
+        paint.gradientStops?.map((s) => ({
+          position: s.position,
+          rgba:
+            s.color &&
+            `rgba(${Math.round(s.color.r * 255)}, ${Math.round(s.color.g * 255)}, ${Math.round(s.color.b * 255)}, ${Number((s.color.a ?? 1).toFixed(3))})`,
+        })) ?? [],
+    };
+  }
+  if (paint.type === 'IMAGE') {
+    return { type: 'image', scaleMode: paint.scaleMode };
+  }
+  return null;
+}
+
+function describeAutoLayout(node) {
+  if (!node.layoutMode || node.layoutMode === 'NONE') return null;
+  return {
+    direction: node.layoutMode === 'HORIZONTAL' ? 'row' : 'column',
+    gap: node.itemSpacing ?? 0,
+    padding: {
+      top: node.paddingTop ?? 0,
+      right: node.paddingRight ?? 0,
+      bottom: node.paddingBottom ?? 0,
+      left: node.paddingLeft ?? 0,
+    },
+    alignItems: node.counterAxisAlignItems,
+    justifyContent: node.primaryAxisAlignItems,
+    wrap: node.layoutWrap === 'WRAP',
+  };
+}
+
+function describeText(node) {
+  if (node.type !== 'TEXT') return null;
+  const s = node.style ?? {};
+  return {
+    characters: node.characters ?? '',
+    fontFamily: s.fontFamily,
+    fontSize: s.fontSize,
+    fontWeight: s.fontWeight,
+    lineHeight: s.lineHeightPx,
+    letterSpacing: s.letterSpacing,
+    textAlign: s.textAlignHorizontal?.toLowerCase(),
+  };
+}
+
+function simplifyNode(node, depth = 0) {
+  if (!node) return null;
+  const out = {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+  };
+
+  if (node.absoluteBoundingBox) {
+    out.size = {
+      w: Math.round(node.absoluteBoundingBox.width),
+      h: Math.round(node.absoluteBoundingBox.height),
+    };
+  }
+
+  const auto = describeAutoLayout(node);
+  if (auto) out.autoLayout = auto;
+
+  if (node.fills?.length) {
+    const fills = node.fills.map(pickColor).filter(Boolean);
+    if (fills.length) out.fills = fills;
+  }
+  if (node.strokes?.length) {
+    const strokes = node.strokes.map(pickColor).filter(Boolean);
+    if (strokes.length) {
+      out.strokes = strokes;
+      out.strokeWeight = node.strokeWeight;
+    }
+  }
+  if (node.cornerRadius != null) out.cornerRadius = node.cornerRadius;
+  if (node.rectangleCornerRadii) out.cornerRadii = node.rectangleCornerRadii;
+  if (node.effects?.length) {
+    out.effects = node.effects.map((e) => ({
+      type: e.type,
+      radius: e.radius,
+      offset: e.offset,
+      color: e.color &&
+        `rgba(${Math.round(e.color.r * 255)}, ${Math.round(e.color.g * 255)}, ${Math.round(e.color.b * 255)}, ${Number((e.color.a ?? 1).toFixed(3))})`,
+    }));
+  }
+  if (node.opacity != null && node.opacity < 1) out.opacity = node.opacity;
+
+  const text = describeText(node);
+  if (text) out.text = text;
+
+  // Component / Instance — 디자인 시스템의 신호. AI 가 재사용 결정하는 단서.
+  if (node.type === 'INSTANCE' && node.componentId) {
+    out.componentRef = node.componentId;
+  }
+
+  if (node.children?.length && depth < MAX_DEPTH) {
+    const kids = node.children.slice(0, MAX_CHILDREN);
+    const truncated = node.children.length > MAX_CHILDREN;
+    out.children = kids
+      .map((c) => simplifyNode(c, depth + 1))
+      .filter(Boolean);
+    if (truncated) out.childrenTruncated = node.children.length - MAX_CHILDREN;
+  }
+
+  return out;
+}
+
+/**
+ * Figma `fetchNodes` 응답을 받아서 LLM 친화적으로 압축.
+ *
+ * @param {object} fetchNodesResponse - Figma API `/v1/files/.../nodes` 결과
+ * @returns {{ documents: Array<simpleNode>, components: Record, styles: Record }}
+ */
+export function simplifyFetchNodes(fetchNodesResponse) {
+  const out = { documents: [], components: {}, styles: {} };
+  const nodes = fetchNodesResponse?.nodes ?? {};
+  for (const [id, payload] of Object.entries(nodes)) {
+    if (!payload?.document) continue;
+    out.documents.push({
+      requestedId: id,
+      ...simplifyNode(payload.document, 0),
+    });
+    if (payload.components) {
+      Object.assign(out.components, payload.components);
+    }
+    if (payload.styles) {
+      Object.assign(out.styles, payload.styles);
+    }
+  }
+  return out;
+}
+
+/** 사람 눈으로 보기 좋은 한 줄 요약 (디버깅/UI 표시용) */
+export function quickSummary(simple) {
+  if (!simple) return '';
+  const parts = [simple.name + ' [' + simple.type + ']'];
+  if (simple.size) parts.push(`${simple.size.w}×${simple.size.h}`);
+  if (simple.autoLayout) parts.push('auto-' + simple.autoLayout.direction);
+  if (simple.children?.length) parts.push(`children=${simple.children.length}`);
+  return parts.join(' · ');
+}
+
+export { simplifyNode };

package/src/figma/url.js

@@ -0,0 +1,41 @@
+/**
+ * Figma URL/링크 파서.
+ *
+ * 지원하는 URL 형태:
+ *   https://www.figma.com/file/{fileKey}/...                     (구버전 share link)
+ *   https://www.figma.com/design/{fileKey}/...                   (신버전, 2023+)
+ *   https://www.figma.com/proto/{fileKey}/...                    (프로토타입)
+ *   ...?node-id=123-456    또는  ...?node-id=123%3A456           (특정 노드)
+ *
+ * Figma 내부 노드 ID 는 "123:456" 인데 URL 에서는 보통 "123-456" 또는 인코딩됨.
+ * API 호출 시엔 "123:456" 으로 다시 변환해야 함.
+ */
+
+const URL_RE = /figma\.com\/(?:file|design|proto)\/([A-Za-z0-9]+)/;
+
+export function parseFigmaUrl(input) {
+  if (!input || typeof input !== 'string') return null;
+  const m = input.match(URL_RE);
+  if (!m) return null;
+  const fileKey = m[1];
+
+  // node-id 추출
+  let nodeId = null;
+  try {
+    const u = new URL(input);
+    const raw = u.searchParams.get('node-id');
+    if (raw) {
+      // "123-456" → "123:456",  "123%3A456" → "123:456"
+      nodeId = decodeURIComponent(raw).replace(/-/g, ':');
+    }
+  } catch {
+    /* not a valid URL — fileKey 만 있으면 그것대로 ok */
+  }
+
+  return { fileKey, nodeId };
+}
+
+/** 디자이너가 도면에서 "Copy link" 한 결과인지 (= node-id 있음) */
+export function hasNode(parsed) {
+  return !!parsed?.nodeId;
+}