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

package/client/components/chat-input-builder.ts

@@ -0,0 +1,40 @@
+/**
+ * boardAIChat GraphQL mutation 의 input 객체 빌더.
+ *
+ * board-ai-chat.ts (Lit / Material Web 의존) 와 분리 — pure 함수만 두면 jest 의 node
+ * 환경에서도 import 가능. 회귀 테스트 (selectedRefids 누락 등) 가 단위 테스트로 잠긴다.
+ */
+
+export interface ChatMutationInputArgs {
+  sessionId?: string
+  history: Array<{ role: string; content: string }>
+  liveBoard: any
+  scopes?: string[]
+  knownTypes?: string[]
+  categories?: string[]
+  componentSchemas?: any
+  /**
+   * 선택된 컴포넌트의 `refid` 배열 — things-scene universal numeric handle.
+   * id (데이터 바인딩 이름) 와는 다른 개념.
+   */
+  selectedRefids: number[]
+}
+
+/**
+ * GraphQL mutation 의 input 객체를 빌드.
+ *
+ * 핵심 보호 — `selectedRefids` 가 항상 포함되어야 한다. 누락이 사용자에게 보고된
+ * "AI 가 선택된 컴포넌트를 모른다" 의 root cause 였다.
+ */
+export function buildChatMutationInput(args: ChatMutationInputArgs): Record<string, any> {
+  return {
+    sessionId: args.sessionId ?? null,
+    messages: args.history,
+    currentBoard: args.liveBoard ?? null,
+    scopes: args.scopes,
+    knownTypes: args.knownTypes,
+    categories: args.categories,
+    componentSchemas: args.componentSchemas,
+    selectedRefids: args.selectedRefids
+  }
+}

package/client/components/markdown.test.ts

@@ -0,0 +1,220 @@
+/**
+ * renderMarkdown 단위 테스트.
+ *
+ * 핵심 회귀 방지 영역:
+ *   1. 기본 markdown (bold, italic, list, code, link).
+ *   2. 보안 — raw HTML, javascript: 링크 차단.
+ *   3. CJK + 구두점 + ** 인접의 flanking 실패 케이스 (한국어 채팅 응답에서 빈번).
+ *   4. 코드 펜스/인라인 코드 안의 ** 는 건드리지 않음.
+ */
+import { renderMarkdown, escapeHtml, extractCjkStrongs } from './markdown'
+
+describe('renderMarkdown — 기본 markdown', () => {
+  test('빈 문자열은 빈 문자열 반환', () => {
+    expect(renderMarkdown('')).toBe('')
+  })
+
+  test('일반 텍스트는 <p> 로 감쌈', () => {
+    expect(renderMarkdown('hello')).toContain('<p>hello</p>')
+  })
+
+  test('** 로 굵게', () => {
+    expect(renderMarkdown('**bold** text')).toContain('<strong>bold</strong>')
+  })
+
+  test('* 로 기울임', () => {
+    expect(renderMarkdown('an *italic* word')).toContain('<em>italic</em>')
+  })
+
+  test('- 로 unordered list', () => {
+    const out = renderMarkdown('- a\n- b\n- c')
+    expect(out).toContain('<ul>')
+    expect(out).toContain('<li>a</li>')
+    expect(out).toContain('<li>b</li>')
+    expect(out).toContain('<li>c</li>')
+  })
+
+  test('inline code', () => {
+    expect(renderMarkdown('use `foo` here')).toContain('<code>foo</code>')
+  })
+
+  test('fenced code block', () => {
+    const md = '```\nconst x = 1\n```'
+    expect(renderMarkdown(md)).toContain('<pre>')
+    expect(renderMarkdown(md)).toContain('<code>')
+  })
+
+  test('헤더', () => {
+    expect(renderMarkdown('# Title')).toContain('<h1>Title</h1>')
+    expect(renderMarkdown('## Sub')).toContain('<h2>Sub</h2>')
+  })
+
+  test('breaks: 단일 newline 은 <br>', () => {
+    expect(renderMarkdown('line1\nline2')).toContain('<br>')
+  })
+})
+
+describe('renderMarkdown — 보안', () => {
+  test('raw <script> 차단', () => {
+    const out = renderMarkdown("<script>alert('x')</script>")
+    expect(out).not.toContain('<script>')
+    expect(out).not.toContain('alert')
+  })
+
+  test('raw <iframe> 차단', () => {
+    const out = renderMarkdown('<iframe src=x></iframe>')
+    expect(out).not.toContain('<iframe')
+  })
+
+  test('inline HTML strong 차단 (renderer.html → 빈 문자열)', () => {
+    const out = renderMarkdown('Hello <strong>world</strong>')
+    // raw HTML 은 제거되고 텍스트만 남거나 비어야 함
+    expect(out).not.toContain('<strong>world</strong>')
+  })
+
+  test('javascript: 링크 차단', () => {
+    const out = renderMarkdown("[click](javascript:alert(1))")
+    expect(out).not.toMatch(/href="javascript:/i)
+  })
+
+  test('data: 링크 차단', () => {
+    const out = renderMarkdown('[x](data:text/html,<script>alert(1)</script>)')
+    expect(out).not.toMatch(/href="data:/i)
+  })
+
+  test('정상 https 링크는 통과', () => {
+    const out = renderMarkdown('[ok](https://example.com)')
+    expect(out).toMatch(/href="https:\/\/example\.com"/)
+  })
+})
+
+describe('renderMarkdown — CJK + 구두점 인접 (회귀 방지)', () => {
+  // 이 그룹은 사용자 보고 사례. CommonMark flanking 규칙으로 인해 ** 가
+  // 닫히지 않던 케이스들을 모두 회복해야 한다.
+  const cases: Array<[string, string, string]> = [
+    ["closing ** 이 punct + CJK 사이", "**'rect'**의", '<strong>&#039;rect&#039;</strong>의'],
+    ["키 **'fillStyle'**의", "키 **'fillStyle'**의", '<strong>&#039;fillStyle&#039;</strong>의'],
+    ["AGV 이름 + 조사", "**'AGV-1'**의 위치", '<strong>&#039;AGV-1&#039;</strong>의'],
+    ["다중 인접 한글", "사용자가 **'AGV-1'**컴포넌트를", '<strong>&#039;AGV-1&#039;</strong>컴포넌트를'],
+    ["bold 안 . 으로 끝", '**foo.**의', '<strong>foo.</strong>의'],
+    ["bold 안 ) 으로 끝", '**foo)**의', '<strong>foo)</strong>의'],
+    ["한 ** punct 시작 인접", "한**'foo'**", '한<strong>&#039;foo&#039;</strong>'],
+    ["양쪽 모두 CJK + punct", "한**'foo'**글", '한<strong>&#039;foo&#039;</strong>글']
+  ]
+
+  for (const [name, input, expected] of cases) {
+    test(name, () => {
+      const out = renderMarkdown(input)
+      expect(out).toContain(expected)
+    })
+  }
+
+  test('정상 케이스는 그대로 marked 가 처리', () => {
+    // 닫는 ** 가 공백 직전인 경우 — flanking 통과 (marked native; entity 표기는 &#39;)
+    const a = renderMarkdown("키 **'fillStyle'** 의")
+    expect(a).toMatch(/<strong>(&#0?39;|')fillStyle(&#0?39;|')<\/strong>/)
+    const b = renderMarkdown("Type **'rect'** here")
+    expect(b).toMatch(/<strong>(&#0?39;|')rect(&#0?39;|')<\/strong>/)
+  })
+
+  test('사용자 실제 케이스 — 산업용 다크 모드 대시보드', () => {
+    const md = "**공장 설비 및 생산 현황을 한눈에 파악하기 위한 '산업용 다크 모드 대시보드'** 도 확인해보라."
+    const out = renderMarkdown(md)
+    expect(out).toContain('<strong>')
+    expect(out).toContain('대시보드')
+  })
+
+  test('punct 가 끝/시작에 없으면 변경 없음', () => {
+    // marked 자체가 처리할 수 있는 케이스 — 우회 안 일어남
+    const out = renderMarkdown('한**foo**글')
+    expect(out).toContain('<strong>foo</strong>')
+  })
+
+  test('일본어 인접', () => {
+    expect(renderMarkdown("これは**'値'**です")).toContain('<strong>&#039;値&#039;</strong>')
+  })
+
+  test('중국어 인접', () => {
+    expect(renderMarkdown("这是**'值'**测试")).toContain('<strong>&#039;值&#039;</strong>')
+  })
+
+  test('인라인 코드 안의 ** 는 건드리지 않음', () => {
+    // 코드 안의 ** 는 그대로 텍스트로 남아야 함
+    const out = renderMarkdown('`**not bold**`')
+    expect(out).toContain('<code>**not bold**</code>')
+  })
+
+  test('코드 펜스 안의 ** 는 건드리지 않음', () => {
+    const md = '```\n**not bold**\n```'
+    const out = renderMarkdown(md)
+    expect(out).toContain('<code>')
+    // 펜스 안의 ** 는 marked 가 텍스트로 그대로 둠
+    expect(out).toMatch(/\*\*not bold\*\*/)
+  })
+
+  test('placeholder 토큰 (BAICJKSTRONG…) 이 출력에 노출되지 않음', () => {
+    const out = renderMarkdown("키 **'fillStyle'**의")
+    expect(out).not.toContain('BAICJKSTRONG')
+    expect(out).not.toContain('ENDMARK')
+  })
+
+  test('치환된 strong 내용은 HTML escape 됨', () => {
+    // CJK-fix 경로를 타는 케이스에 < > 가 섞여도 안전하게 escape 되어야 한다.
+    // before='', after='의' (CJK), innerStart=', innerEnd=' (둘 다 punct) → fix 트리거.
+    const out = renderMarkdown("**'<bad>'**의")
+    expect(out).not.toContain('<bad>')
+    expect(out).toContain('&lt;bad&gt;')
+    expect(out).toContain('<strong>')
+  })
+
+  test('여러 strong 가 한 줄에 있어도 모두 처리', () => {
+    const out = renderMarkdown("**'A'**과 **'B'**는 다르다")
+    // 둘 다 strong 으로 렌더되어야 함
+    const matches = out.match(/<strong>/g) ?? []
+    expect(matches.length).toBe(2)
+  })
+})
+
+describe('extractCjkStrongs — 내부 동작', () => {
+  test('필요 없는 케이스는 stored 비어 있음', () => {
+    const r = extractCjkStrongs('regular **bold** text')
+    expect(r.stored).toEqual([])
+    expect(r.processed).toBe('regular **bold** text')
+  })
+
+  test('필요한 케이스만 추출', () => {
+    const r = extractCjkStrongs("키 **'fillStyle'**의")
+    expect(r.stored).toEqual(["'fillStyle'"])
+    expect(r.processed).toContain('BAICJKSTRONG')
+  })
+
+  test('인라인 코드 안의 ** 는 추출 안 함', () => {
+    const r = extractCjkStrongs("`**'foo'**의` 와 텍스트")
+    expect(r.stored).toEqual([])
+    expect(r.processed).toContain("`**'foo'**의`")
+  })
+
+  test('코드 펜스 안의 ** 는 추출 안 함', () => {
+    const r = extractCjkStrongs("```\n**'foo'**의\n```")
+    expect(r.stored).toEqual([])
+  })
+
+  test('짝이 안 맞는 ** 는 무시', () => {
+    const r = extractCjkStrongs('한**foo and 글')
+    expect(r.stored).toEqual([])
+  })
+})
+
+describe('escapeHtml — HTML 이스케이프', () => {
+  test('< > & " \' 모두 escape', () => {
+    expect(escapeHtml('<script>')).toBe('&lt;script&gt;')
+    expect(escapeHtml('a & b')).toBe('a &amp; b')
+    expect(escapeHtml('"q"')).toBe('&quot;q&quot;')
+    expect(escapeHtml("'a'")).toBe('&#039;a&#039;')
+  })
+
+  test('일반 문자는 변경 없음', () => {
+    expect(escapeHtml('hello world')).toBe('hello world')
+    expect(escapeHtml('한글 テスト 中文')).toBe('한글 テスト 中文')
+  })
+})

package/client/components/markdown.ts

@@ -0,0 +1,184 @@
+/**
+ * Board AI 채팅 메시지의 Markdown 렌더링.
+ *
+ * 보안:
+ *   - raw HTML 차단 (renderer.html → ''), 위험 link 스킴 (javascript:, data: 등) 차단.
+ *
+ * CJK 보강:
+ *   - CommonMark의 left/right-flanking 규칙 때문에 한국어/일본어/중국어 텍스트와
+ *     ** 강조 마커 사이에 구두점이 끼면 마커가 닫히지 않는 케이스가 발생한다.
+ *     예) "**'rect'**의" → 닫는 ** 가 [구두점] + [CJK] 사이에 위치하므로 right-flanking 실패
+ *   - 이런 케이스는 marked 에 넘기기 전에 자체적으로 추출 → 자리표시자로 치환 → marked
+ *     수행 → 후처리에서 <strong>...</strong> 로 복원하는 방식으로 처리한다.
+ *   - 이 우회는 사용자가 의도적으로 넣은 ** 만 대상으로 하므로 보안적으로 안전하다 (내용은
+ *     escapeHtml 로 항상 escape).
+ */
+import { marked } from 'marked'
+
+const markdownRenderer = new marked.Renderer()
+markdownRenderer.html = () => ''
+const origLink = markdownRenderer.link.bind(markdownRenderer)
+markdownRenderer.link = (token: any) => {
+  const href = typeof token?.href === 'string' ? token.href.trim() : ''
+  if (/^(javascript|data|vbscript):/i.test(href)) {
+    return token?.text ?? ''
+  }
+  return origLink(token)
+}
+
+marked.setOptions({
+  gfm: true,
+  breaks: true,
+  pedantic: false,
+  renderer: markdownRenderer,
+  async: false
+} as any)
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;')
+}
+
+// CJK 문자 범위: Hiragana, Katakana, CJK Unified Ideographs (Ext A 포함), Hangul, 전각/반각
+const CJK_RE = /[぀-ヿ㐀-䶿一-鿿가-힯＀-￯]/
+const PUNCT_RE = /\p{P}/u
+
+// marked 가 절대 변형하지 않는 토큰 (영숫자만 사용)
+const PLACEHOLDER_PREFIX = 'BAICJKSTRONG'
+const PLACEHOLDER_SUFFIX = 'ENDMARK'
+
+interface ExtractResult {
+  processed: string
+  stored: string[]
+}
+
+/**
+ * `**X**` 패턴 중 CJK + 구두점 인접 때문에 marked 의 flanking 규칙에서 누락되는
+ * 케이스를 추출. 코드 펜스(```)와 인라인 코드(`...`) 안쪽은 건드리지 않는다.
+ *
+ * 검출 기준 (CommonMark right-flanking 실패 ↔ left-flanking 실패):
+ *   - 닫는 ** 직전 문자가 구두점 AND 직후 문자가 CJK letter
+ *   - 여는 ** 직전 문자가 CJK letter AND 직후 문자가 구두점
+ */
+export function extractCjkStrongs(text: string): ExtractResult {
+  const stored: string[] = []
+  const lines = text.split('\n')
+  const outLines: string[] = []
+  let inFence = false
+
+  for (const line of lines) {
+    if (/^\s{0,3}```/.test(line)) {
+      inFence = !inFence
+      outLines.push(line)
+      continue
+    }
+    if (inFence) {
+      outLines.push(line)
+      continue
+    }
+    outLines.push(processLine(line, stored, () => outLines[outLines.length - 1] ?? ''))
+  }
+
+  return { processed: outLines.join('\n'), stored }
+}
+
+function processLine(line: string, stored: string[], prevLine: () => string): string {
+  let i = 0
+  let result = ''
+  while (i < line.length) {
+    const ch = line[i]
+
+    if (ch === '`') {
+      const end = line.indexOf('`', i + 1)
+      if (end === -1) {
+        result += line.slice(i)
+        break
+      }
+      result += line.slice(i, end + 1)
+      i = end + 1
+      continue
+    }
+
+    if (ch === '*' && line[i + 1] === '*') {
+      const close = findCloseStrong(line, i + 2)
+      if (close === -1) {
+        result += '**'
+        i += 2
+        continue
+      }
+      const inner = line.slice(i + 2, close)
+      if (inner.length === 0) {
+        result += '**'
+        i += 2
+        continue
+      }
+      const before = result.length > 0 ? result.slice(-1) : prevLine().slice(-1)
+      const after = close + 2 < line.length ? line[close + 2] : ''
+      if (needsCjkFix(before, after, inner)) {
+        stored.push(inner)
+        result += `${PLACEHOLDER_PREFIX}${stored.length - 1}${PLACEHOLDER_SUFFIX}`
+      } else {
+        result += line.slice(i, close + 2)
+      }
+      i = close + 2
+      continue
+    }
+
+    result += ch
+    i++
+  }
+  return result
+}
+
+function findCloseStrong(line: string, start: number): number {
+  let i = start
+  while (i < line.length - 1) {
+    if (line[i] === '`') {
+      const end = line.indexOf('`', i + 1)
+      if (end === -1) return -1
+      i = end + 1
+      continue
+    }
+    if (line[i] === '*' && line[i + 1] === '*') return i
+    i++
+  }
+  return -1
+}
+
+function needsCjkFix(before: string, after: string, inner: string): boolean {
+  const innerStart = inner[0]
+  const innerEnd = inner[inner.length - 1]
+  return (
+    (before !== '' && CJK_RE.test(before) && PUNCT_RE.test(innerStart)) ||
+    (after !== '' && CJK_RE.test(after) && PUNCT_RE.test(innerEnd))
+  )
+}
+
+function restoreCjkStrongs(html: string, stored: string[]): string {
+  let out = html
+  for (let n = 0; n < stored.length; n++) {
+    const token = `${PLACEHOLDER_PREFIX}${n}${PLACEHOLDER_SUFFIX}`
+    const replacement = `<strong>${escapeHtml(stored[n])}</strong>`
+    out = out.split(token).join(replacement)
+  }
+  return out
+}
+
+export function renderMarkdown(text: string): string {
+  if (!text) return ''
+  try {
+    const { processed, stored } = extractCjkStrongs(text)
+    const out = marked.parse(processed)
+    if (typeof out !== 'string') {
+      // marked 가 Promise 를 반환했다면 (async lexer 등) 안전한 fallback
+      return escapeHtml(text).replace(/\n/g, '<br>')
+    }
+    return restoreCjkStrongs(out, stored)
+  } catch {
+    return escapeHtml(text).replace(/\n/g, '<br>')
+  }
+}

package/client/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @things-factory/board-ai — client entries.
+ *
+ * - `<ox-board-ai-chat>`: 자연어 채팅 컴포넌트 (Lit). board-modeller 또는 워크스페이스에서 임베드.
+ *
+ * 향후 추가 예정:
+ *   - `<ox-board-workspace>`: editor / ai / split 모드 전환 컨테이너
+ *   - 모드 전환 애니메이션 + 단축키 + 자동 전환 룰
+ */
+export * from './components/board-ai-chat.js'
+export * from './utils/board-edit-patch.js'

package/client/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig-base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "declaration": true,
+    "module": "esnext",
+    "outDir": "../dist-client",
+    "baseUrl": "./"
+  },
+  "include": ["./**/*"]
+}

package/client/utils/board-edit-patch.ts

@@ -0,0 +1,200 @@
+/**
+ * Client-side BoardEditPatch types + applier.
+ *
+ * NOTE: 동일 정의가 server/service/types.ts + apply-patch.ts 에 있음.
+ * client 번들이 server 코드를 import 하지 않도록 분리. 변경 시 양쪽 동기화 필요.
+ */
+
+/**
+ * 컴포넌트 타깃팅은 항상 `refid` (things-scene universal numeric handle).
+ * `id` 는 데이터 바인딩 이름이며 unique 가 아니므로 targeting 에 사용하지 않는다.
+ *
+ * 보드는 최상위 부모 — 자체 속성 (fillStyle / width / height / name 등) 을 갖고,
+ * `modifyBoard` 로 변경. 자식 컴포넌트 변경 (`modify`) 와 분리.
+ */
+export type BoardEditOp =
+  | { op: 'add'; component: any }
+  | { op: 'remove'; refid: number }
+  | { op: 'modify'; refid: number; patch: any }
+  | { op: 'modifyBoard'; patch: any }
+  | { op: 'replace'; board: any }
+
+export interface BoardEditPatch {
+  ops: BoardEditOp[]
+  summary: string
+  confidence: number
+}
+
+export interface PatchApplyReport {
+  /** 패치 적용 후 보드. 모든 op 가 noop 이어도 입력 그대로 반환. */
+  board: any
+  /** 실제로 보드를 바꾼 op 들. */
+  applied: BoardEditOp[]
+  /** id 매칭 실패 등으로 noop 이 된 op 들 — 호출자가 사용자에게 알릴 단서. */
+  missed: BoardEditOp[]
+}
+
+const EMPTY_BOARD = { width: 1000, height: 600, components: [] as any[] }
+
+/**
+ * Patch 를 BoardModel 에 적용 (pure, board 를 mutate 하지 않음).
+ */
+export function applyBoardEditPatch(board: any | undefined, patch: BoardEditPatch): any {
+  return applyBoardEditPatchVerbose(board, patch).board
+}
+
+/**
+ * Verbose 변형 — 각 op 의 적용 여부를 보고.
+ *
+ * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다. LLM 이 잘못된
+ * id 를 만들어 보내면 사용자에게 "수정했습니다" 라고 답하지만 실제로는 아무 변화도
+ * 없는 상황이 발생 — 호스트가 missed 를 보고 사용자에게 경고할 수 있도록 별도
+ * entry point 제공.
+ */
+export function applyBoardEditPatchVerbose(
+  board: any | undefined,
+  patch: BoardEditPatch
+): PatchApplyReport {
+  let result: any = board ?? EMPTY_BOARD
+  const applied: BoardEditOp[] = []
+  const missed: BoardEditOp[] = []
+
+  for (const op of patch.ops) {
+    const next = applyOp(result, op)
+    if (next === result || componentsUnchanged(result, next)) {
+      missed.push(op)
+    } else {
+      applied.push(op)
+      result = next
+    }
+  }
+
+  return { board: result, applied, missed }
+}
+
+function componentsUnchanged(prev: any, next: any): boolean {
+  // applyOp 는 항상 새 객체를 만든다. 따라서 reference 비교가 안 되고 내용 비교 필요.
+  // components 는 map/filter 결과 reference 도 다를 수 있으므로 length + 요소 ref 비교.
+  const a = prev.components ?? []
+  const b = next.components ?? []
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return prev.width === next.width && prev.height === next.height && prev.fillStyle === next.fillStyle
+}
+
+function applyOp(board: any, op: BoardEditOp): any {
+  switch (op.op) {
+    case 'replace':
+      return op.board
+    case 'add':
+      return { ...board, components: [...(board.components || []), op.component] }
+    case 'remove':
+      return {
+        ...board,
+        components: (board.components || []).filter((c: any) => c?.refid !== op.refid)
+      }
+    case 'modify':
+      return {
+        ...board,
+        components: (board.components || []).map((c: any) =>
+          c?.refid === op.refid ? mergeComponent(c, op.patch) : c
+        )
+      }
+    case 'modifyBoard': {
+      const patch = { ...(op.patch || {}) }
+      delete patch.components // 자식 변경은 별도 op
+      return mergeComponent(board, patch) // 최상위 board 자체에 deep-merge
+    }
+    default:
+      return board
+  }
+}
+
+/**
+ * 주어진 board 상태에서 op 의 inverse 를 계산.
+ *
+ * Revert 기능 — patch 적용 직전 board + op 로 역연산을 만든다. 호스트가
+ * 누적해두면 나중에 역순 실행만으로 복원.
+ *
+ * add 의 inverse 는 새로 발급될 refid 를 알아야 → 모델 단계에서 계산 불가.
+ * 호스트가 scene.add 직후 refid 를 캡처해 직접 만들 것.
+ */
+export function computeInverseOp(board: any, op: BoardEditOp): BoardEditOp | null {
+  if (!board) return null
+  const components = board.components ?? []
+
+  switch (op.op) {
+    case 'add':
+      return null
+
+    case 'remove': {
+      const target = components.find((c: any) => c?.refid === op.refid)
+      if (!target) return null
+      return { op: 'add', component: JSON.parse(JSON.stringify(target)) }
+    }
+
+    case 'modify': {
+      const target = components.find((c: any) => c?.refid === op.refid)
+      if (!target) return null
+      const oldValues: any = {}
+      for (const k of Object.keys(op.patch || {})) {
+        const v = (target as any)[k]
+        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+      }
+      return { op: 'modify', refid: op.refid, patch: oldValues }
+    }
+
+    case 'modifyBoard': {
+      const oldValues: any = {}
+      const patch = op.patch || {}
+      for (const k of Object.keys(patch)) {
+        if (k === 'components') continue
+        const v = (board as any)[k]
+        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+      }
+      return { op: 'modifyBoard', patch: oldValues }
+    }
+
+    case 'replace':
+      return { op: 'replace', board: JSON.parse(JSON.stringify(board)) }
+
+    default:
+      return null
+  }
+}
+
+/**
+ * 컴포넌트에 부분 patch 를 적용 (deep merge).
+ * threeD 등 nested object 는 deep merge — 색만 바꾸려고 했을 때 geometry 까지 사라지지 않도록.
+ *
+ * host (board-modeller-page) 에서 things-scene 의 component.set(merged) 호출 전에 사용.
+ */
+export function mergeComponent(base: any, patch: any): any {
+  const out: any = { ...base }
+  for (const key of Object.keys(patch)) {
+    if (isPlainObject(base[key]) && isPlainObject(patch[key])) {
+      out[key] = deepMerge(base[key], patch[key])
+    } else {
+      out[key] = patch[key]
+    }
+  }
+  return out
+}
+
+function deepMerge(a: any, b: any): any {
+  const out: any = { ...a }
+  for (const key of Object.keys(b)) {
+    if (isPlainObject(a[key]) && isPlainObject(b[key])) {
+      out[key] = deepMerge(a[key], b[key])
+    } else {
+      out[key] = b[key]
+    }
+  }
+  return out
+}
+
+function isPlainObject(v: any): boolean {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}