@things-factory/board-ai 10.0.0-beta.108

package/server/service/assistant-integration.test.ts

@@ -0,0 +1,922 @@
+/**
+ * 통합 테스트 — assistant.chat() → BoardEditPatch → apply-patch 풀 파이프라인.
+ *
+ * 단위 테스트의 공백 보완:
+ *   - assistant.test.ts 는 patch 가 "올바르게 만들어지는지" 까지만 검증
+ *   - apply-patch.test.ts 는 patch 가 "올바르게 적용되는지" 까지만 검증
+ *   - 둘이 맞물려 "사용자 입력 X + mock LLM 응답 Y → 최종 board Z" 가 일치하는지는
+ *     아무도 검증하지 않았다 → 회귀가 가장 자주 새는 지점
+ *
+ * 시나리오는 사용자가 실제로 던질만한 자연어 의도를 mock LLM 의 tool_call 시퀀스로
+ * 표현. assistant 가 patch + actions 를 만들고, apply-patch 가 board 에 반영되는
+ * 전체 흐름을 검증.
+ */
+import type { AIClient } from '@things-factory/ai-client-base'
+import { DefaultBoardAIAssistant } from './assistant'
+import { applyBoardEditPatch, applyBoardEditPatchVerbose } from './apply-patch'
+import type { BoardModel } from '@things-factory/board-import'
+
+// ── Mock provider — assistant.test.ts 의 패턴과 동일 ──────────────────
+function makeMockClient(turns: Array<{ text?: string; toolCalls: any[]; stopReason?: string }>) {
+  let turnIdx = 0
+  const callLog: any[] = []
+  const client: AIClient = {
+    id: 'mock:integration',
+    chat: async () => '',
+    generateJSON: async () => ({}),
+    chatWithTools: async (messages: any[]) => {
+      callLog.push({ messages: JSON.parse(JSON.stringify(messages)) })
+      const turn = turns[turnIdx++] ?? { toolCalls: [], stopReason: 'end_turn' }
+      return {
+        text: turn.text,
+        toolCalls: turn.toolCalls,
+        stopReason: turn.stopReason ?? (turn.toolCalls.length > 0 ? 'tool_use' : 'end_turn')
+      }
+    }
+  } as any
+  return { client, callLog }
+}
+
+const makeBoard = (components: any[] = [], width = 1000, height = 600): BoardModel =>
+  ({ width, height, components } as any)
+
+describe('통합 — addComponent 시나리오', () => {
+  test('"rect 하나 추가" → 보드에 컴포넌트 +1', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'c1',
+            name: 'addComponent',
+            arguments: { type: 'rect', left: 50, top: 60, width: 100, height: 80 }
+          }
+        ]
+      },
+      { text: 'rect 추가했습니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'rect 하나 추가' }], initial)
+
+    expect(r.patch?.ops).toHaveLength(1)
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(1)
+    expect(verbose.missed).toHaveLength(0)
+    expect(verbose.board.components).toHaveLength(1)
+    const added: any = verbose.board.components[0]
+    expect(added.type).toBe('rect')
+    expect(added.left).toBe(50)
+    expect(added.top).toBe(60)
+  })
+
+  test('빈 보드에 다중 컴포넌트 추가 (한 turn 안에 add 3개)', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'addComponent', arguments: { type: 'rect', left: 0, top: 0, width: 50, height: 50 } },
+          { id: 'c2', name: 'addComponent', arguments: { type: 'circle', cx: 100, cy: 100, radius: 20 } },
+          { id: 'c3', name: 'addComponent', arguments: { type: 'text', left: 200, top: 200, width: 100, height: 30, text: 'hello' } }
+        ]
+      },
+      { text: '3개 추가', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'rect, circle, text 추가' }], initial)
+
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.board.components).toHaveLength(3)
+    expect(verbose.board.components.map((c: any) => c.type)).toEqual(['rect', 'circle', 'text'])
+    expect(verbose.applied).toHaveLength(3)
+    expect(verbose.missed).toHaveLength(0)
+  })
+})
+
+describe('통합 — modifyComponentByRefid 시나리오', () => {
+  test('"refid 35 를 left=200 으로" → 해당 컴포넌트만 변경', async () => {
+    const initial = makeBoard([
+      { refid: 35, type: 'rect', left: 10, top: 20, width: 100, height: 50, fillStyle: '#fff' },
+      { refid: 36, type: 'circle', cx: 50, cy: 50, radius: 20 }
+    ])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'c1',
+            name: 'modifyComponentByRefid',
+            arguments: { refid: 35, patch: { left: 200 } }
+          }
+        ]
+      },
+      { text: '이동 완료', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '왼쪽 200으로' }], initial)
+
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(1)
+    expect(verbose.missed).toHaveLength(0)
+    const c1: any = verbose.board.components[0]
+    const c2: any = verbose.board.components[1]
+    expect(c1.left).toBe(200)
+    expect(c1.top).toBe(20) // 다른 속성 보존
+    expect(c1.width).toBe(100)
+    expect(c1.fillStyle).toBe('#fff')
+    expect(c2.cx).toBe(50) // 다른 컴포넌트 무영향
+  })
+
+  test('AI 가 존재하지 않는 refid 수정 시도 → verbose missed 보고 (silent no-op 검출)', async () => {
+    // 핵심 회귀 방지: AI 가 hallucinate 한 refid 로 modify 하면 board 는 변경 없이 끝남.
+    // verbose 결과의 missed[] 가 비어 있으면 호스트가 "AI 가 수정했다 했는데 보드 그대로"
+    // 상황을 사용자에게 알릴 수 없다.
+    const initial = makeBoard([{ refid: 35, type: 'rect', left: 10 }])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'c1',
+            name: 'modifyComponentByRefid',
+            arguments: { refid: 999, patch: { left: 200 } } // 999 는 없음
+          }
+        ]
+      },
+      { text: '수정 시도', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '999 left=200' }], initial)
+
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(0)
+    expect(verbose.missed).toHaveLength(1)
+    // 보드는 그대로
+    expect((verbose.board.components[0] as any).left).toBe(10)
+  })
+})
+
+describe('통합 — modifyBoard 시나리오 (root 속성)', () => {
+  test('"배경색 #0a1929" → root.fillStyle 만 변경, children 영향 없음', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect', fillStyle: '#fff' }
+    ]) as any
+    initial.fillStyle = '#cccccc'
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'c1',
+            name: 'modifyBoard',
+            arguments: { patch: { fillStyle: '#0a1929' } }
+          }
+        ]
+      },
+      { text: '배경 변경', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '심해 컬러' }], initial)
+
+    const after: any = applyBoardEditPatch(initial, r.patch!)
+    expect(after.fillStyle).toBe('#0a1929')
+    expect(after.components).toHaveLength(1)
+    expect((after.components[0] as any).fillStyle).toBe('#fff') // 자식은 그대로
+  })
+
+  test('"심해 분위기" multi-turn — getAtmosphereGuide 후 modifyBoard 패치가 root 에 반영', async () => {
+    // 실제 사용 패턴: AI 가 atmosphere primer 를 먼저 read tool 로 가져와 archetype
+    // 보고, 거기서 추출한 patch (sky/exposure/dirLight 등) 로 modifyBoard 호출.
+    const initial = makeBoard()
+    const { client, callLog } = makeMockClient([
+      // turn 1: read tool — guide 조회
+      {
+        toolCalls: [{ id: 'c1', name: 'getAtmosphereGuide', arguments: {} }]
+      },
+      // turn 2: write tool — guide 의 deepOcean archetype 적용
+      {
+        toolCalls: [
+          {
+            id: 'c2',
+            name: 'modifyBoard',
+            arguments: {
+              patch: { sky: 'color', skyColor: '#0a1929', exposure: 0.7, hemiIntensity: 1.5 }
+            }
+          }
+        ]
+      },
+      { text: '심해 분위기 적용', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '심해 분위기로' }], initial)
+
+    expect(callLog).toHaveLength(3) // read → write → finalize
+    expect(r.patch?.ops).toHaveLength(1) // read 는 patch 에 안 잡히고 modifyBoard 만
+    const after: any = applyBoardEditPatch(initial, r.patch!)
+    expect(after.sky).toBe('color')
+    expect(after.skyColor).toBe('#0a1929')
+    expect(after.exposure).toBe(0.7)
+    // toolUsages 에는 둘 다 (read + write) 누적
+    expect(r.toolUsages).toHaveLength(2)
+    expect(r.toolUsages![0].kind).toBe('read')
+    expect(r.toolUsages![1].kind).toBe('write')
+  })
+})
+
+describe('통합 — removeComponentByRefid', () => {
+  test('"refid 36 삭제" → 보드 -1', async () => {
+    const initial = makeBoard([
+      { refid: 35, type: 'rect' },
+      { refid: 36, type: 'circle' },
+      { refid: 37, type: 'text' }
+    ])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'removeComponentByRefid', arguments: { refid: 36 } }
+        ]
+      },
+      { text: '삭제', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '36 삭제' }], initial)
+
+    const after = applyBoardEditPatch(initial, r.patch!)
+    expect(after.components).toHaveLength(2)
+    expect(after.components.map((c: any) => c.refid)).toEqual([35, 37])
+  })
+})
+
+describe('통합 — replaceBoard', () => {
+  test('"이 보드 갈아엎고 새로" → board 통째로 교체', async () => {
+    const initial = makeBoard([{ refid: 1, type: 'rect' }], 1000, 600)
+    const newBoard = {
+      width: 1920,
+      height: 1080,
+      fillStyle: '#000',
+      components: [
+        { type: 'circle', cx: 100, cy: 100, radius: 50 }
+      ]
+    }
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'replaceBoard', arguments: newBoard }
+        ]
+      },
+      { text: '교체', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '갈아엎어' }], initial)
+
+    const after: any = applyBoardEditPatch(initial, r.patch!)
+    expect(after.width).toBe(1920)
+    expect(after.height).toBe(1080)
+    expect(after.fillStyle).toBe('#000')
+    expect(after.components).toHaveLength(1)
+    expect(after.components[0].type).toBe('circle')
+  })
+})
+
+describe('통합 — read-then-write 다중 turn', () => {
+  test('"refid 1 알아본 후 그것의 left=100 으로" → 최종 patch 는 modify 만', async () => {
+    const initial = makeBoard([{ refid: 1, type: 'rect', left: 0, top: 0 }])
+    const { client, callLog } = makeMockClient([
+      // turn 1: read
+      {
+        toolCalls: [{ id: 'r1', name: 'getComponentByRefid', arguments: { refid: 1 } }]
+      },
+      // turn 2: write
+      {
+        toolCalls: [
+          { id: 'w1', name: 'modifyComponentByRefid', arguments: { refid: 1, patch: { left: 100 } } }
+        ]
+      },
+      { text: '확인 후 수정', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'refid 1 100으로' }], initial)
+
+    expect(callLog).toHaveLength(3)
+    expect(r.patch?.ops).toHaveLength(1) // read 는 patch 에 안 들어감
+    expect(r.patch?.ops[0].op).toBe('modify')
+    const after = applyBoardEditPatch(initial, r.patch!)
+    expect((after.components[0] as any).left).toBe(100)
+  })
+
+  test('"rect 들 찾아서 모두 빨갛게" → findComponents 후 turn-by-turn modify 누적', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect', fillStyle: '#fff' },
+      { refid: 2, type: 'rect', fillStyle: '#fff' },
+      { refid: 3, type: 'circle', fillStyle: '#fff' } // rect 아님
+    ])
+    const { client } = makeMockClient([
+      // turn 1: find
+      {
+        toolCalls: [{ id: 'f1', name: 'findComponents', arguments: { type: 'rect' } }]
+      },
+      // turn 2: 결과 받고 두 개 한번에 modify
+      {
+        toolCalls: [
+          { id: 'm1', name: 'modifyComponentByRefid', arguments: { refid: 1, patch: { fillStyle: '#ff0000' } } },
+          { id: 'm2', name: 'modifyComponentByRefid', arguments: { refid: 2, patch: { fillStyle: '#ff0000' } } }
+        ]
+      },
+      { text: '2개 변경', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'rect 다 빨갛게' }], initial)
+
+    expect(r.patch?.ops).toHaveLength(2)
+    const after = applyBoardEditPatch(initial, r.patch!)
+    expect((after.components[0] as any).fillStyle).toBe('#ff0000') // rect
+    expect((after.components[1] as any).fillStyle).toBe('#ff0000') // rect
+    expect((after.components[2] as any).fillStyle).toBe('#fff') // circle 무영향
+  })
+})
+
+describe('통합 — write + action 혼합', () => {
+  test('"refid 1 left=100 한 후 view 모드" → patch.ops 1, actions 1', async () => {
+    const initial = makeBoard([{ refid: 1, type: 'rect', left: 0 }])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'w1', name: 'modifyComponentByRefid', arguments: { refid: 1, patch: { left: 100 } } },
+          { id: 'a1', name: 'setSceneMode', arguments: { mode: 'view' } }
+        ]
+      },
+      { text: '완료', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '100으로 옮기고 보기' }], initial)
+
+    // patch 와 actions 가 각자 독립
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.patch?.ops[0]).toEqual({ op: 'modify', refid: 1, patch: { left: 100 } })
+    expect(r.actions).toHaveLength(1)
+    expect(r.actions![0]).toEqual({ action: 'setSceneMode', mode: 'view' })
+
+    // apply-patch 는 patch.ops 만 처리 (actions 는 호스트가 별도 처리)
+    const after = applyBoardEditPatch(initial, r.patch!)
+    expect((after.components[0] as any).left).toBe(100)
+  })
+
+  test('"7번으로 카메라 이동 후 그것 선택" → patch 없음, actions 만', async () => {
+    const initial = makeBoard([{ refid: 7, type: 'rect' }])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'a1', name: 'centerToComponent', arguments: { refid: 7 } },
+          { id: 'a2', name: 'selectComponents', arguments: { refids: [7] } }
+        ]
+      },
+      { text: '이동 + 선택', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '7 보여줘' }], initial)
+
+    expect(r.patch).toBeUndefined() // 모델 변경 X
+    expect(r.actions).toHaveLength(2)
+    expect(r.actions![0]).toEqual({ action: 'centerToComponent', refid: 7 })
+    expect(r.actions![1]).toEqual({ action: 'selectComponents', refids: [7] })
+  })
+})
+
+describe('통합 — 다중 op 한 patch 안 순차 적용', () => {
+  test('add + modify 가 같은 patch 에서 순서대로 적용 (modify 가 add 된 컴포넌트 대상이 아니어도 OK)', async () => {
+    const initial = makeBoard([{ refid: 1, type: 'rect', left: 0 }])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'addComponent', arguments: { type: 'circle', cx: 100, cy: 100 } },
+          { id: 'c2', name: 'modifyComponentByRefid', arguments: { refid: 1, patch: { left: 50 } } }
+        ]
+      },
+      { text: 'done', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'circle 추가하고 1 left=50' }], initial)
+
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(2)
+    expect(verbose.board.components).toHaveLength(2)
+    expect((verbose.board.components[0] as any).left).toBe(50)
+    expect((verbose.board.components[1] as any).type).toBe('circle')
+  })
+
+  test('일부 applied + 일부 missed 혼합', async () => {
+    const initial = makeBoard([{ refid: 1, type: 'rect', left: 0 }])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'modifyComponentByRefid', arguments: { refid: 1, patch: { left: 100 } } },
+          { id: 'c2', name: 'modifyComponentByRefid', arguments: { refid: 999, patch: { left: 200 } } }, // 없음
+          { id: 'c3', name: 'addComponent', arguments: { type: 'circle', cx: 50, cy: 50 } }
+        ]
+      },
+      { text: 'done', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'do' }], initial)
+
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(2) // refid 1 modify + add
+    expect(verbose.missed).toHaveLength(1) // refid 999 modify
+    expect(verbose.board.components).toHaveLength(2)
+  })
+})
+
+describe('통합 — Phase 2 scene 조작 op (모델 차원 noop, scene API 정본)', () => {
+  test('alignComponents 는 verbose applied (apply-patch 는 noop, scene 호출이 정본)', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect', left: 10, top: 0 },
+      { refid: 2, type: 'rect', left: 50, top: 0 }
+    ])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'alignComponents', arguments: { refids: [1, 2], direction: 'left' } }
+        ]
+      },
+      { text: '정렬', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '왼쪽 정렬' }], initial)
+
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.patch?.ops[0]).toEqual({ op: 'align', refids: [1, 2], direction: 'left' })
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(1)
+    expect(verbose.missed).toHaveLength(0)
+    expect(verbose.board).toBe(initial) // model 차원에선 reference 동일
+  })
+
+  test('group + zorder 혼합', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect' },
+      { refid: 2, type: 'rect' }
+    ])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'groupComponents', arguments: { refids: [1, 2] } },
+          { id: 'c2', name: 'changeZorder', arguments: { refid: 1, direction: 'forward' } }
+        ]
+      },
+      { text: 'done', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '그룹 + 앞으로' }], initial)
+
+    expect(r.patch?.ops).toHaveLength(2)
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(2)
+    expect(verbose.missed).toHaveLength(0)
+  })
+})
+
+describe('통합 — text-only 응답 (patch 없음)', () => {
+  test('"안녕" → reply 만, patch/actions 모두 undefined', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([{ text: '안녕하세요!', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '안녕' }], initial)
+
+    expect(r.reply).toBe('안녕하세요!')
+    expect(r.patch).toBeUndefined()
+    expect(r.actions).toBeUndefined()
+    // 보드도 변경 없음
+    const after = applyBoardEditPatch(initial, { ops: [], summary: '', confidence: 0 })
+    expect(after).toBe(initial)
+  })
+})
+
+describe('통합 — Prefab (검증된 복합 컴포넌트 한 번에 추가)', () => {
+  test('"모니터링 카드 하나 추가" — getAvailablePrefabs → addPrefab 흐름', async () => {
+    const initial = makeBoard()
+    const { client, callLog } = makeMockClient([
+      // turn 1: AI 가 사용 가능 prefab 카탈로그 조회
+      {
+        toolCalls: [{ id: 'r1', name: 'getAvailablePrefabs', arguments: {} }]
+      },
+      // turn 2: 카탈로그 보고 monitor-card 선택해서 instantiate
+      {
+        toolCalls: [
+          {
+            id: 'w1',
+            name: 'addPrefab',
+            arguments: {
+              name: 'monitor-card',
+              left: 50,
+              top: 30,
+              options: { title: '온도', value: '23.5°C', subtitle: 'Sensor #1' }
+            }
+          }
+        ]
+      },
+      { text: '온도 모니터링 카드 추가했습니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '온도 모니터링 카드 추가' }], initial)
+
+    expect(callLog).toHaveLength(3) // read → write → finalize
+    expect(r.patch?.ops).toHaveLength(1) // addPrefab → 단일 add op
+    const after = applyBoardEditPatch(initial, r.patch!)
+    expect(after.components).toHaveLength(1)
+    const added: any = after.components[0]
+    expect(added.type).toBe('group') // prefab 은 group 으로 wrapping
+    expect(added.left).toBe(50)
+    // 자식 텍스트에 옵션 반영
+    const texts = added.components
+      .filter((c: any) => c.type === 'text')
+      .map((c: any) => c.text)
+    expect(texts).toContain('온도')
+    expect(texts).toContain('23.5°C')
+  })
+
+  test('"KPI 타일 3개 (생산량/가동률/불량률)" — 다중 addPrefab in 같은 turn', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'w1',
+            name: 'addPrefab',
+            arguments: {
+              name: 'stat-tile',
+              left: 20,
+              top: 20,
+              options: { title: '생산량', value: '1,234', fillStyle: '#0ea5e9' }
+            }
+          },
+          {
+            id: 'w2',
+            name: 'addPrefab',
+            arguments: {
+              name: 'stat-tile',
+              left: 260,
+              top: 20,
+              options: { title: '가동률', value: '92%', fillStyle: '#10b981' }
+            }
+          },
+          {
+            id: 'w3',
+            name: 'addPrefab',
+            arguments: {
+              name: 'stat-tile',
+              left: 500,
+              top: 20,
+              options: { title: '불량률', value: '0.8%', fillStyle: '#ef4444' }
+            }
+          }
+        ]
+      },
+      { text: 'KPI 타일 3종 추가', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'KPI 타일 3개' }], initial)
+
+    expect(r.patch?.ops).toHaveLength(3)
+    const after = applyBoardEditPatch(initial, r.patch!)
+    expect(after.components).toHaveLength(3)
+    // 각 타일이 group 이고 fillStyle 이 다름 (옵션 반영)
+    const fills = (after.components as any[])
+      .map(g => g.components.find((c: any) => c.type === 'rect')?.fillStyle)
+      .sort()
+    expect(fills).toEqual(['#0ea5e9', '#10b981', '#ef4444'])
+  })
+
+  test('잘못된 prefab name → patch 에 누락 (silent skip — toolCallToBoardEditOp 가 null 반환)', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'w1',
+            name: 'addPrefab',
+            arguments: { name: 'no-such-prefab', left: 0, top: 0 }
+          }
+        ]
+      },
+      { text: 'tried', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'x' }], initial)
+    // 잘못된 prefab → toolCallToBoardEditOp 가 null → patch 에 op 미추가
+    expect(r.patch).toBeUndefined()
+  })
+})
+
+describe('통합 — Design system 카탈로그 (color palette + layout template + prefab 조합)', () => {
+  test('"산업 분위기 KPI 대시보드" — palettes → layout → 다중 prefab 흐름', async () => {
+    // 가장 풍부한 시나리오 — 사용자 자연어 의도 하나가 3개 read tool 순차 호출 후
+    // 일관된 색·구도·prefab 으로 결과화. design system 의 시너지를 end-to-end 로 검증.
+    const initial = makeBoard()
+    const { client, callLog } = makeMockClient([
+      // turn 1: AI 가 색 팔레트 카탈로그 먼저 조회
+      {
+        toolCalls: [{ id: 'r1', name: 'getColorPalettes', arguments: {} }]
+      },
+      // turn 2: layout template 조회
+      {
+        toolCalls: [{ id: 'r2', name: 'getLayoutTemplates', arguments: {} }]
+      },
+      // turn 3: 보드 배경 + 다중 KPI 타일 한꺼번에
+      {
+        toolCalls: [
+          {
+            id: 'w1',
+            name: 'modifyBoard',
+            arguments: { patch: { fillStyle: '#0f1722' } } // industrial-steel.base
+          },
+          {
+            id: 'w2',
+            name: 'addPrefab',
+            arguments: {
+              name: 'stat-tile',
+              left: 20,
+              top: 20,
+              width: 290,
+              height: 130,
+              options: { title: '생산량', value: '1,234', fillStyle: '#1a2332' } // surface
+            }
+          },
+          {
+            id: 'w3',
+            name: 'addPrefab',
+            arguments: {
+              name: 'stat-tile',
+              left: 330,
+              top: 20,
+              width: 290,
+              height: 130,
+              options: { title: '가동률', value: '92%', fillStyle: '#1a2332' }
+            }
+          }
+        ]
+      },
+      { text: '산업 분위기 KPI 대시보드 구성 완료', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '산업 분위기 KPI 대시보드 만들어' }], initial)
+
+    expect(callLog).toHaveLength(4) // palette → layout → write → finalize
+    expect(r.toolUsages).toHaveLength(5) // 2 read + 3 write 모두 누적
+    const readNames = r.toolUsages!.filter(u => u.kind === 'read').map(u => u.name)
+    expect(readNames).toContain('getColorPalettes')
+    expect(readNames).toContain('getLayoutTemplates')
+
+    // patch 적용 후 보드 배경 + 2 prefab tile
+    const after: any = applyBoardEditPatch(initial, r.patch!)
+    expect(after.fillStyle).toBe('#0f1722') // industrial-steel.base
+    expect(after.components).toHaveLength(2)
+    // 모두 group prefab
+    for (const c of after.components) {
+      expect((c as any).type).toBe('group')
+      // surface 색이 일관 적용
+      const bg = (c as any).components.find((cc: any) => cc.type === 'rect')
+      expect(bg.fillStyle).toBe('#1a2332')
+    }
+  })
+
+  test('"색 추천해줘" → getColorPalettes 호출만 (text-only 응답)', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'r1',
+            name: 'getColorPalettes',
+            arguments: { keywordPattern: 'cyber' }
+          }
+        ]
+      },
+      {
+        text:
+          'neon-cyberpunk 팔레트를 추천드립니다. base #050008 + accent #ec4899 (magenta) + cyan success.',
+        toolCalls: []
+      }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat(
+      [{ role: 'user', content: 'SF 분위기 색 추천' }],
+      initial
+    )
+    expect(r.reply).toContain('neon-cyberpunk')
+    expect(r.patch).toBeUndefined() // 추천만, 적용 안 함
+    expect(r.toolUsages![0].name).toBe('getColorPalettes')
+  })
+})
+
+describe('통합 — #token 멘션 자동 해석 (본문 보존 + mention map 첨부)', () => {
+  test('"#경광등1 빨갛게" → 본문 #경광등1 보존, refid 는 mention map 안에만', async () => {
+    const initial = makeBoard([
+      { refid: 35, type: 'rect', name: '경광등1', id: 'motor-1', fillStyle: '#fff' }
+    ])
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '#경광등1 빨갛게' }], initial)
+
+    const conv = callLog[0].messages
+    const lastUserMsg = conv[conv.length - 1]
+    expect(lastUserMsg.role).toBe('user')
+    // 본문 영역 — # 보존, refid 노출 X
+    const mapStart = lastUserMsg.content.indexOf('--- mention map')
+    expect(mapStart).toBeGreaterThan(0)
+    const body = lastUserMsg.content.slice(0, mapStart)
+    expect(body).toContain('#경광등1 빨갛게')
+    expect(body).not.toMatch(/refid/i)
+    // mention map 안에 refid + name + id + type 모두 등장
+    const map = lastUserMsg.content.slice(mapStart)
+    expect(map).toContain('#경광등1 →')
+    expect(map).toContain("name='경광등1'")
+    expect(map).toContain("id='motor-1'")
+    expect(map).toContain('refid=35')
+  })
+
+  test('id 로 직접 지칭 — #motor-1 → mention map 에 매핑', async () => {
+    const initial = makeBoard([
+      { refid: 5, type: 'rect', id: 'motor-1' }
+    ])
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '#motor-1 stop' }], initial)
+    const lastUserMsg = callLog[0].messages[callLog[0].messages.length - 1]
+    expect(lastUserMsg.content).toContain('#motor-1 stop') // 본문 보존
+    expect(lastUserMsg.content).toContain("id='motor-1'")
+    expect(lastUserMsg.content).toContain('refid=5')
+  })
+
+  test('type 으로 와이드 지칭 — #rect → 같은 type 모든 컴포넌트', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect', name: 'A' },
+      { refid: 2, type: 'rect', name: 'B' },
+      { refid: 3, type: 'circle' }
+    ])
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '#rect 모두 빨갛게' }], initial)
+    const lastUserMsg = callLog[0].messages[callLog[0].messages.length - 1]
+    expect(lastUserMsg.content).toContain('#rect 모두 빨갛게') // 본문 보존
+    expect(lastUserMsg.content).toContain('#rect →')
+    expect(lastUserMsg.content).toContain('refid=1')
+    expect(lastUserMsg.content).toContain('refid=2')
+    expect(lastUserMsg.content).not.toContain('refid=3') // circle 제외
+  })
+
+  test('매칭 실패 시 원문 보존 — mention map 첨부 안 함', async () => {
+    const initial = makeBoard([{ refid: 1, name: 'A' }])
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '#NoSuchThing 어쩌구' }], initial)
+    const lastUserMsg = callLog[0].messages[callLog[0].messages.length - 1]
+    expect(lastUserMsg.content).toContain('#NoSuchThing 어쩌구')
+    expect(lastUserMsg.content).not.toContain('mention map')
+  })
+
+  test('직전 history 의 user 메시지는 변환 안 함 — 마지막만', async () => {
+    const initial = makeBoard([{ refid: 35, name: '경광등1' }])
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat(
+      [
+        { role: 'user', content: '#경광등1 처음 언급' }, // 이전 — 그대로
+        { role: 'assistant', content: '확인' },
+        { role: 'user', content: '#경광등1 빨갛게' } // 마지막 — 변환
+      ],
+      initial
+    )
+    const conv = callLog[0].messages
+    const userMsgs = conv.filter((m: any) => m.role === 'user')
+    const lastUser = userMsgs[userMsgs.length - 1]
+    const prevUser = userMsgs[userMsgs.length - 2]
+    // 마지막 user — mention map 첨부됨
+    expect(lastUser.content).toContain('mention map')
+    expect(lastUser.content).toContain('refid=35')
+    // 이전 user — 변환 없음, 그대로
+    expect(prevUser.content).toBe('#경광등1 처음 언급')
+    expect(prevUser.content).not.toContain('mention map')
+  })
+})
+
+describe('통합 — @name 카탈로그 멘션 자동 해석 (kind 보강)', () => {
+  test('"@monitor-card 추가" → LLM 에는 \'monitor-card (prefab) 추가\'', async () => {
+    const initial = makeBoard()
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '@monitor-card 추가' }], initial)
+    const conv = callLog[0].messages
+    const lastUserMsg = conv[conv.length - 1]
+    expect(lastUserMsg.content).toContain('monitor-card (prefab)')
+    expect(lastUserMsg.content).not.toContain('@monitor-card')
+  })
+
+  test('# 와 @ 가 같은 메시지에 — # 는 mention map, @ 는 inline 변환', async () => {
+    const initial = makeBoard([{ refid: 35, name: '경광등1' }])
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat(
+      [{ role: 'user', content: '#경광등1 옆에 @stat-tile 추가' }],
+      initial
+    )
+    const conv = callLog[0].messages
+    const lastUserMsg = conv[conv.length - 1]
+    // # 는 본문 보존 + mention map
+    expect(lastUserMsg.content).toContain('#경광등1')
+    expect(lastUserMsg.content).toContain('mention map')
+    expect(lastUserMsg.content).toContain('refid=35')
+    // @ 는 inline disambiguation
+    expect(lastUserMsg.content).toContain('stat-tile (prefab)')
+  })
+
+  test('알 수 없는 @ token → 원문 보존', async () => {
+    const initial = makeBoard()
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '@unknown 어쩌고' }], initial)
+    const conv = callLog[0].messages
+    const lastUserMsg = conv[conv.length - 1]
+    expect(lastUserMsg.content).toContain('@unknown')
+  })
+})
+
+describe('통합 — Sugar layout (arrange grid/row/column)', () => {
+  test('"3x2 그리드로" → arrangeInGrid → arrange op (scene-only verbose applied)', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect', left: 0, top: 0, width: 100, height: 50 },
+      { refid: 2, type: 'rect', left: 0, top: 0, width: 100, height: 50 },
+      { refid: 3, type: 'rect', left: 0, top: 0, width: 100, height: 50 },
+      { refid: 4, type: 'rect', left: 0, top: 0, width: 100, height: 50 },
+      { refid: 5, type: 'rect', left: 0, top: 0, width: 100, height: 50 },
+      { refid: 6, type: 'rect', left: 0, top: 0, width: 100, height: 50 }
+    ])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'w1',
+            name: 'arrangeInGrid',
+            arguments: { refids: [1, 2, 3, 4, 5, 6], cols: 3 }
+          }
+        ]
+      },
+      { text: '3x2 그리드 정렬 완료', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '3x2 그리드로 배치' }], initial)
+
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.patch?.ops[0].op).toBe('arrange')
+    if (r.patch?.ops[0].op === 'arrange') {
+      expect(r.patch.ops[0].refids).toEqual([1, 2, 3, 4, 5, 6])
+      expect(r.patch.ops[0].layout).toEqual({ type: 'grid', cols: 3 })
+    }
+    // model 차원 noop — 호스트가 정본 (board-edit-dispatch 가 위치 계산)
+    const verbose = applyBoardEditPatchVerbose(initial, r.patch!)
+    expect(verbose.applied).toHaveLength(1)
+    expect(verbose.missed).toHaveLength(0)
+    expect(verbose.board).toBe(initial) // model 동일
+  })
+
+  test('"한 줄로 가운데 정렬" → arrangeInRow + align:center', async () => {
+    const initial = makeBoard([
+      { refid: 1, type: 'rect', width: 100, height: 50 },
+      { refid: 2, type: 'rect', width: 100, height: 80 }
+    ])
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'w1',
+            name: 'arrangeInRow',
+            arguments: { refids: [1, 2], align: 'center', gap: 5 }
+          }
+        ]
+      },
+      { text: '한 줄', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '한 줄로' }], initial)
+    if (r.patch?.ops[0].op === 'arrange' && r.patch.ops[0].layout.type === 'row') {
+      expect(r.patch.ops[0].layout.align).toBe('center')
+      expect(r.patch.ops[0].layout.gap).toBe(5)
+    }
+  })
+})
+
+describe('통합 — patch 신뢰도 / summary 가 reply 에서 도출', () => {
+  test('write tool 호출 시 reply 텍스트가 patch.summary 에 매핑', async () => {
+    const initial = makeBoard()
+    const { client } = makeMockClient([
+      {
+        text: '컴포넌트 5개 추가했습니다.',
+        toolCalls: [
+          { id: 'c1', name: 'addComponent', arguments: { type: 'rect', left: 0, top: 0, width: 50, height: 50 } }
+        ]
+      },
+      { text: '컴포넌트 5개 추가했습니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'rect 5개' }], initial)
+
+    expect(r.patch?.summary).toBe('컴포넌트 5개 추가했습니다.')
+    expect(r.patch?.confidence).toBeGreaterThan(0)
+    expect(r.patch?.confidence).toBeLessThanOrEqual(1)
+  })
+})