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

package/server/service/apply-patch.test.ts

@@ -0,0 +1,757 @@
+/**
+ * applyBoardEditPatch / applyOp 단위 테스트.
+ *
+ * BoardEditPatch 4종 op (add / remove / modify / replace) 의 정확한 적용,
+ * pure function 보장 (입력 mutate 없음), nested object deep merge 동작을 회귀 방지.
+ *
+ * 식별자 정책 — 컴포넌트 targeting 은 항상 `refid` (things-scene universal numeric
+ * handle). `id` 는 데이터 바인딩 이름이며 unique 가 아니라 targeting 에 사용하지 않음.
+ */
+import {
+  applyBoardEditPatch,
+  applyBoardEditPatchVerbose,
+  applyOp,
+  computeInverseOp,
+  mergeComponent
+} from './apply-patch'
+import type { BoardEditOp, BoardEditPatch } from './types'
+
+const make = (
+  components: any[] = [],
+  width = 1000,
+  height = 600
+): any => ({ width, height, components })
+
+describe('applyOp — add', () => {
+  test('빈 보드에 컴포넌트 추가', () => {
+    const r = applyOp(make(), { op: 'add', component: { refid: 1, type: 'rect' } as any })
+    expect(r.components).toHaveLength(1)
+    expect(r.components[0].refid).toBe(1)
+  })
+
+  test('기존 컴포넌트 보존하고 추가', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyOp(board, { op: 'add', component: { refid: 2, type: 'circle' } as any })
+    expect(r.components.map((c: any) => c.refid)).toEqual([1, 2])
+  })
+
+  test('width/height 등 보드 메타 보존', () => {
+    const board = make([], 1920, 1080)
+    const r = applyOp(board, { op: 'add', component: { refid: 1, type: 'rect' } as any })
+    expect(r.width).toBe(1920)
+    expect(r.height).toBe(1080)
+  })
+
+  test('입력을 mutate 하지 않음', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const before = JSON.stringify(board)
+    applyOp(board, { op: 'add', component: { refid: 2, type: 'circle' } as any })
+    expect(JSON.stringify(board)).toBe(before)
+  })
+})
+
+describe('applyOp — remove', () => {
+  test('refid 매칭 컴포넌트 제거', () => {
+    const board = make([
+      { refid: 1, type: 'rect' },
+      { refid: 2, type: 'circle' }
+    ])
+    const r = applyOp(board, { op: 'remove', refid: 1 })
+    expect(r.components).toHaveLength(1)
+    expect(r.components[0].refid).toBe(2)
+  })
+
+  test('없는 refid 는 변화 없음', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyOp(board, { op: 'remove', refid: 999 })
+    expect(r.components).toHaveLength(1)
+  })
+
+  test('id 만 같고 refid 다른 컴포넌트는 제거되지 않음 (id 는 unique 아님)', () => {
+    // 같은 데이터 바인딩 id 를 가진 두 컴포넌트가 있어도, refid 매칭 한 개만 제거.
+    const board = make([
+      { refid: 1, type: 'rect', id: 'motor-1' },
+      { refid: 2, type: 'rect', id: 'motor-1' }
+    ])
+    const r = applyOp(board, { op: 'remove', refid: 1 })
+    expect(r.components).toHaveLength(1)
+    expect(r.components[0].refid).toBe(2)
+  })
+
+  test('입력을 mutate 하지 않음', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const before = JSON.stringify(board)
+    applyOp(board, { op: 'remove', refid: 1 })
+    expect(JSON.stringify(board)).toBe(before)
+  })
+})
+
+describe('applyOp — modify', () => {
+  test('top-level 속성 변경', () => {
+    const board = make([{ refid: 1, type: 'rect', left: 10, top: 20 }])
+    const r = applyOp(board, { op: 'modify', refid: 1, patch: { left: 100 } as any })
+    expect((r.components[0] as any).left).toBe(100)
+    expect((r.components[0] as any).top).toBe(20)
+    expect((r.components[0] as any).type).toBe('rect')
+  })
+
+  test('없는 refid 는 변경 없음', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyOp(board, { op: 'modify', refid: 999, patch: { type: 'circle' } as any })
+    expect((r.components[0] as any).type).toBe('rect')
+  })
+
+  test('id 같은 다른 컴포넌트는 영향 없음 (id 는 unique 아님 → modify 도 refid 정확 매칭)', () => {
+    const board = make([
+      { refid: 1, type: 'rect', id: 'motor-1', left: 10 },
+      { refid: 2, type: 'rect', id: 'motor-1', left: 50 }
+    ])
+    const r = applyOp(board, { op: 'modify', refid: 1, patch: { left: 999 } as any })
+    expect((r.components[0] as any).left).toBe(999)
+    expect((r.components[1] as any).left).toBe(50) // 데이터 바인딩 id 가 같아도 영향 없음
+  })
+
+  test('nested object (threeD 등) 는 deep merge — 색만 바꿀 때 geometry 보존', () => {
+    const board = make([
+      {
+        refid: 1,
+        type: 'rect',
+        threeD: {
+          enabled: true,
+          geometry: { type: 'box', size: { x: 100, y: 100, z: 50 } },
+          material: { color: '#ff0000' }
+        }
+      }
+    ])
+    const r = applyOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { threeD: { material: { color: '#00ff00' } } } as any
+    })
+    const c = r.components[0] as any
+    expect(c.threeD.enabled).toBe(true)
+    expect(c.threeD.geometry).toEqual({ type: 'box', size: { x: 100, y: 100, z: 50 } })
+    expect(c.threeD.material.color).toBe('#00ff00')
+  })
+
+  test('배열 값은 deep merge 안 함 (전체 교체)', () => {
+    const board = make([{ refid: 1, type: 'polyline', points: [[0, 0], [1, 1]] }])
+    const r = applyOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { points: [[5, 5]] } as any
+    })
+    expect((r.components[0] as any).points).toEqual([[5, 5]])
+  })
+
+  test('patch 에 null 은 키 제거 시맨틱 (typeof null === object 함정 회피)', () => {
+    const board = make([{ refid: 1, type: 'rect', threeD: { enabled: true } }])
+    const r = applyOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { threeD: null } as any
+    })
+    // null 로 set 이 아니라 키 자체 제거
+    expect('threeD' in (r.components[0] as any)).toBe(false)
+  })
+
+  test('다른 컴포넌트는 영향 없음', () => {
+    const board = make([
+      { refid: 1, type: 'rect', left: 10 },
+      { refid: 2, type: 'circle', cx: 50 }
+    ])
+    const r = applyOp(board, { op: 'modify', refid: 1, patch: { left: 100 } as any })
+    expect((r.components[1] as any).cx).toBe(50)
+  })
+
+  test('입력을 mutate 하지 않음', () => {
+    const board = make([
+      { refid: 1, type: 'rect', threeD: { material: { color: '#ff0000' } } }
+    ])
+    const before = JSON.stringify(board)
+    applyOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { threeD: { material: { color: '#00ff00' } } } as any
+    })
+    expect(JSON.stringify(board)).toBe(before)
+  })
+})
+
+describe('applyOp — modifyBoard (root 속성 변경)', () => {
+  test('fillStyle 단일 변경 — children 영향 없음', () => {
+    const board = make([{ refid: 1, type: 'rect', fillStyle: '#fff' }])
+    const r = applyOp(board, { op: 'modifyBoard', patch: { fillStyle: '#0a1929' } as any })
+    expect((r as any).fillStyle).toBe('#0a1929')
+    // children 그대로
+    expect(r.components).toHaveLength(1)
+    expect((r.components[0] as any).fillStyle).toBe('#fff')
+  })
+
+  test('width / height 변경', () => {
+    const board = make([], 1000, 600)
+    const r = applyOp(board, { op: 'modifyBoard', patch: { width: 1920, height: 1080 } as any })
+    expect(r.width).toBe(1920)
+    expect(r.height).toBe(1080)
+  })
+
+  test('name 등 임의 root 속성', () => {
+    const board = make([])
+    const r: any = applyOp(board, {
+      op: 'modifyBoard',
+      patch: { name: 'Production Floor', description: 'desc' } as any
+    })
+    expect(r.name).toBe('Production Floor')
+    expect(r.description).toBe('desc')
+  })
+
+  test('patch 의 components 키는 무시 — children 변경은 별도 op', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyOp(board, {
+      op: 'modifyBoard',
+      patch: { fillStyle: '#000', components: [] } as any
+    })
+    expect((r as any).fillStyle).toBe('#000')
+    expect(r.components).toHaveLength(1) // children 보존
+  })
+
+  test('nested object deep merge (예: 향후 root level theme 객체)', () => {
+    const board: any = { ...make([]), theme: { primary: '#fff', secondary: '#aaa' } }
+    const r: any = applyOp(board, {
+      op: 'modifyBoard',
+      patch: { theme: { primary: '#0a1929' } } as any
+    })
+    expect(r.theme.primary).toBe('#0a1929')
+    expect(r.theme.secondary).toBe('#aaa') // 보존
+  })
+
+  test('입력을 mutate 하지 않음', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const before = JSON.stringify(board)
+    applyOp(board, { op: 'modifyBoard', patch: { fillStyle: '#000' } as any })
+    expect(JSON.stringify(board)).toBe(before)
+  })
+})
+
+describe('applyOp — replace', () => {
+  test('전체 보드 교체', () => {
+    const board = make([{ refid: 1, type: 'rect' }], 1000, 600)
+    const newBoard: any = { width: 1920, height: 1080, components: [{ refid: 9, type: 'circle' }] }
+    const r = applyOp(board, { op: 'replace', board: newBoard })
+    expect(r).toBe(newBoard)
+  })
+})
+
+describe('applyBoardEditPatch — 다중 op', () => {
+  test('여러 op 가 순차 적용', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const patch: BoardEditPatch = {
+      ops: [
+        { op: 'add', component: { refid: 2, type: 'circle' } as any },
+        { op: 'modify', refid: 1, patch: { left: 100 } as any },
+        { op: 'remove', refid: 1 }
+      ],
+      summary: '',
+      confidence: 0.9
+    }
+    const r = applyBoardEditPatch(board, patch)
+    expect(r.components).toHaveLength(1)
+    expect((r.components[0] as any).refid).toBe(2)
+  })
+
+  test('빈 ops 는 보드 그대로', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatch(board, { ops: [], summary: '', confidence: 0 })
+    expect(r).toBe(board)
+  })
+
+  test('undefined 보드 → 기본 빈 보드 사용', () => {
+    const r = applyBoardEditPatch(undefined, {
+      ops: [{ op: 'add', component: { refid: 1, type: 'rect' } as any }],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.components).toHaveLength(1)
+    expect(r.width).toBeGreaterThan(0)
+    expect(r.height).toBeGreaterThan(0)
+  })
+
+  test('replace + 후속 op 조합', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const newBase: any = { width: 800, height: 480, components: [{ refid: 9, type: 'rect' }] }
+    const patch: BoardEditPatch = {
+      ops: [
+        { op: 'replace', board: newBase },
+        { op: 'add', component: { refid: 10, type: 'circle' } as any }
+      ],
+      summary: '',
+      confidence: 1
+    }
+    const r = applyBoardEditPatch(board, patch)
+    expect(r.width).toBe(800)
+    expect(r.components.map((c: any) => c.refid)).toEqual([9, 10])
+  })
+
+  test('알 수 없는 op 는 무시 (default case)', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const patch: any = {
+      ops: [{ op: 'unknown', whatever: 1 }],
+      summary: '',
+      confidence: 0
+    }
+    const r = applyBoardEditPatch(board, patch)
+    expect(r.components).toHaveLength(1)
+  })
+})
+
+describe('applyBoardEditPatchVerbose — silent no-op 검출 (회귀 방지)', () => {
+  // 핵심: AI 가 잘못된/존재하지 않는 refid 로 modify/remove 를 시도하면 applyOp 는
+  // silent no-op 으로 끝난다. Verbose 변형이 이를 missed[] 로 보고하지 않으면
+  // 호스트가 "AI 가 수정했다는데 보드는 그대로" 상황을 사용자에게 알릴 수 없다.
+  test('존재하지 않는 refid 로 modify → missed', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [{ op: 'modify', refid: 999, patch: { left: 100 } as any }],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(0)
+    expect(r.missed).toHaveLength(1)
+    expect(r.board).toBe(board)
+  })
+
+  test('존재하지 않는 refid 로 remove → missed', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [{ op: 'remove', refid: 999 }],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(0)
+    expect(r.missed).toHaveLength(1)
+    expect(r.board).toBe(board)
+  })
+
+  test('정상 modify → applied', () => {
+    const board = make([{ refid: 1, type: 'rect', left: 0 }])
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [{ op: 'modify', refid: 1, patch: { left: 100 } as any }],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(1)
+    expect(r.missed).toHaveLength(0)
+    expect((r.board.components[0] as any).left).toBe(100)
+  })
+
+  test('add 는 항상 applied (refid 의존 안 함 — 추가될 컴포넌트의 refid 는 scene 이 부여)', () => {
+    const board = make()
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [{ op: 'add', component: { refid: 9, type: 'rect' } as any }],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(1)
+    expect(r.missed).toHaveLength(0)
+  })
+
+  test('replace 는 항상 applied', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [
+        { op: 'replace', board: { width: 800, height: 600, components: [] } as any }
+      ],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(1)
+    expect(r.missed).toHaveLength(0)
+  })
+
+  test('mixed: 일부 applied + 일부 missed', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [
+        { op: 'modify', refid: 1, patch: { left: 1 } as any },
+        { op: 'modify', refid: 998, patch: { left: 2 } as any },
+        { op: 'remove', refid: 999 },
+        { op: 'add', component: { refid: 2, type: 'circle' } as any }
+      ],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(2) // modify refid 1 + add
+    expect(r.missed).toHaveLength(2) // modify ghost + remove phantom
+    expect(r.board.components.map((c: any) => c.refid)).toEqual([1, 2])
+  })
+
+  test('빈 ops — applied/missed 모두 빈 배열', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatchVerbose(board, { ops: [], summary: '', confidence: 1 })
+    expect(r.applied).toEqual([])
+    expect(r.missed).toEqual([])
+    expect(r.board).toBe(board)
+  })
+
+  test('applyBoardEditPatch (non-verbose) 는 board 만 반환 — 기존 호출자 호환', () => {
+    const board = make([{ refid: 1, type: 'rect', left: 0 }])
+    const r = applyBoardEditPatch(board, {
+      ops: [{ op: 'modify', refid: 1, patch: { left: 50 } as any }],
+      summary: '',
+      confidence: 1
+    })
+    expect((r.components[0] as any).left).toBe(50)
+  })
+
+  test('modifyBoard 가 fillStyle 외 root 키 (sky/exposure 등) 만 바꿀 때 → applied (회귀 방지)', () => {
+    // 회귀 방지: componentsUnchanged 가 width/height/fillStyle 만 비교하므로 sky/exposure
+    // 등 다른 root 키를 바꾸는 modifyBoard 는 false negative 로 missed 분류돼 board 가
+    // 갱신 안 되던 silent data-loss 버그. componentMutating 분기로 modify/remove 만
+    // componentsUnchanged 검사하도록 수정.
+    const board: any = { width: 1000, height: 600, components: [{ refid: 1, type: 'rect' }] }
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [{ op: 'modifyBoard', patch: { sky: 'color', exposure: 0.7 } as any }],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(1)
+    expect(r.missed).toHaveLength(0)
+    expect((r.board as any).sky).toBe('color')
+    expect((r.board as any).exposure).toBe(0.7)
+  })
+})
+
+describe('mergeComponent — host 측 in-place 적용에 사용되는 deep merge', () => {
+  test('top-level 속성 추가/변경', () => {
+    const r = mergeComponent({ refid: 1, type: 'rect', left: 10 } as any, { left: 20, top: 30 } as any)
+    expect(r).toEqual({ refid: 1, type: 'rect', left: 20, top: 30 })
+  })
+
+  test('nested object deep merge (threeD)', () => {
+    const base = {
+      refid: 1,
+      type: 'rect',
+      threeD: {
+        enabled: true,
+        material: { color: '#ff0000', metalness: 0.5 },
+        geometry: { type: 'box', size: { x: 100 } }
+      }
+    } as any
+    const patch = {
+      threeD: { material: { color: '#00ff00' } }
+    } as any
+    const r: any = mergeComponent(base, patch)
+    expect(r.threeD.material.color).toBe('#00ff00')
+    expect(r.threeD.material.metalness).toBe(0.5) // 보존
+    expect(r.threeD.geometry).toEqual({ type: 'box', size: { x: 100 } }) // 보존
+    expect(r.threeD.enabled).toBe(true) // 보존
+  })
+
+  test('배열은 deep merge 안 함 (전체 교체)', () => {
+    const r: any = mergeComponent({ refid: 1, type: 'polyline', points: [[0, 0], [10, 10]] } as any, {
+      points: [[5, 5]]
+    } as any)
+    expect(r.points).toEqual([[5, 5]])
+  })
+
+  test('patch 에 null = 키 제거 (null 로 set 아님)', () => {
+    const r: any = mergeComponent({ refid: 1, type: 'rect', threeD: { enabled: true } } as any, {
+      threeD: null
+    } as any)
+    expect('threeD' in r).toBe(false)
+  })
+
+  test('patch 에 null = 키 제거 — fillStyle (mode=none 시나리오)', () => {
+    const r: any = mergeComponent(
+      { refid: 1, type: 'rect', fillStyle: { type: 'gradient', colorStops: [] } } as any,
+      { fillStyle: null } as any
+    )
+    expect('fillStyle' in r).toBe(false)
+  })
+
+  test('patch 에 null = 키 제거 — nested deep merge', () => {
+    // threeD 병합 중 metalness 만 제거하고 싶을 때
+    const r: any = mergeComponent(
+      { refid: 1, type: 'rect', threeD: { material: { color: '#fff', metalness: 0.5 } } } as any,
+      { threeD: { material: { metalness: null } } } as any
+    )
+    expect(r.threeD.material).toEqual({ color: '#fff' })
+    expect('metalness' in r.threeD.material).toBe(false)
+  })
+
+  test('base 를 mutate 하지 않음', () => {
+    const base = { refid: 1, type: 'rect', threeD: { material: { color: '#f00' } } } as any
+    const before = JSON.stringify(base)
+    mergeComponent(base, { threeD: { material: { color: '#0f0' } } } as any)
+    expect(JSON.stringify(base)).toBe(before)
+  })
+})
+
+describe('applyBoardEditPatch — 입력 보존', () => {
+  test('패치 적용 후 원본 board 객체는 변경 없음', () => {
+    const board = make([{ refid: 1, type: 'rect', left: 10 }])
+    const before = JSON.stringify(board)
+    applyBoardEditPatch(board, {
+      ops: [
+        { op: 'add', component: { refid: 2, type: 'circle' } as any },
+        { op: 'modify', refid: 1, patch: { left: 999 } as any }
+      ],
+      summary: '',
+      confidence: 1
+    })
+    expect(JSON.stringify(board)).toBe(before)
+  })
+})
+
+describe('computeInverseOp — Revert 의 역연산 계산', () => {
+  // 핵심 보장: patch 적용 직전 board 상태에서 op 의 inverse 를 만들 수 있어야 한다.
+  // 호스트가 patch 시점에 누적해두면 나중에 역순 in-place 적용으로 복원 가능.
+
+  test('add: 모델 단계에서 inverse 계산 불가 → null (호스트가 scene refid 캡처 후 직접 만듦)', () => {
+    const board = make([])
+    const r = computeInverseOp(board, {
+      op: 'add',
+      component: { refid: 9, type: 'rect' } as any
+    })
+    expect(r).toBeNull()
+  })
+
+  test('remove: 삭제될 컴포넌트의 model 을 add inverse 로 보관', () => {
+    const board = make([
+      { refid: 1, type: 'rect', left: 10, top: 20, name: 'AGV-1' },
+      { refid: 2, type: 'circle' }
+    ])
+    const r = computeInverseOp(board, { op: 'remove', refid: 1 })
+    expect(r).toEqual({
+      op: 'add',
+      component: { refid: 1, type: 'rect', left: 10, top: 20, name: 'AGV-1' }
+    })
+  })
+
+  test('remove: 매칭 실패 → null (silent no-op 의 inverse 도 없음)', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = computeInverseOp(board, { op: 'remove', refid: 999 })
+    expect(r).toBeNull()
+  })
+
+  test('remove: 깊은 클론 — 원본 mutate 시에도 inverse 보존', () => {
+    const orig = { refid: 1, type: 'rect', threeD: { material: { color: '#ff0000' } } }
+    const board = make([orig as any])
+    const r: any = computeInverseOp(board, { op: 'remove', refid: 1 })
+    orig.threeD.material.color = '#00ff00'
+    expect(r.component.threeD.material.color).toBe('#ff0000')
+  })
+
+  test('modify: patch 가 건드린 키만 원본 값 보관 (전체 컴포넌트 X)', () => {
+    const board = make([
+      { refid: 1, type: 'rect', left: 10, top: 20, fillStyle: '#fff', height: 100 }
+    ])
+    const r = computeInverseOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { left: 999, fillStyle: '#000' } as any
+    })
+    expect(r).toEqual({
+      op: 'modify',
+      refid: 1,
+      patch: { left: 10, fillStyle: '#fff' }
+    })
+  })
+
+  test('modify: nested 값은 통째로 deep-clone 으로 보관 (threeD.material 등)', () => {
+    const board = make([
+      {
+        refid: 1,
+        type: 'rect',
+        threeD: { enabled: true, material: { color: '#ff0000', metalness: 0.5 } }
+      }
+    ])
+    const r: any = computeInverseOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { threeD: { material: { color: '#00ff00' } } } as any
+    })
+    expect(r.patch.threeD).toEqual({
+      enabled: true,
+      material: { color: '#ff0000', metalness: 0.5 }
+    })
+  })
+
+  test('modify: 원본에 없던 키는 null 보관 (revert 시 키 제거 시맨틱)', () => {
+    const board = make([{ refid: 1, type: 'rect' } as any])
+    const r: any = computeInverseOp(board, {
+      op: 'modify',
+      refid: 1,
+      patch: { fillStyle: '#000' } as any
+    })
+    // null 인 inverse 적용 시 mergeComponent 가 키를 제거 → 원본 (키 없음) 복원
+    expect(r.patch.fillStyle).toBeNull()
+  })
+
+  test('modify: 매칭 실패 → null', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = computeInverseOp(board, {
+      op: 'modify',
+      refid: 999,
+      patch: { left: 100 } as any
+    })
+    expect(r).toBeNull()
+  })
+
+  test('modifyBoard: patch 가 건드린 root 키만 원본 보관', () => {
+    const board: any = {
+      width: 1920,
+      height: 1080,
+      fillStyle: '#fff',
+      name: 'Floor',
+      components: []
+    }
+    const r = computeInverseOp(board, {
+      op: 'modifyBoard',
+      patch: { fillStyle: '#0a1929', exposure: 0.7 } as any
+    })
+    expect(r).toEqual({
+      op: 'modifyBoard',
+      patch: { fillStyle: '#fff', exposure: null } // exposure 원본에 없음 → null
+    })
+  })
+
+  test("modifyBoard: patch 의 'components' 키는 무시 (자식은 별도 op)", () => {
+    const board = make([{ refid: 1, type: 'rect' }], 1920, 1080)
+    const r: any = computeInverseOp(board, {
+      op: 'modifyBoard',
+      patch: { fillStyle: '#000', components: [] } as any
+    })
+    expect(Object.keys(r.patch).sort()).toEqual(['fillStyle'])
+  })
+
+  test('replace: 이전 보드 통째로 deep-clone 해서 inverse replace', () => {
+    const board = make([{ refid: 1, type: 'rect' }], 1000, 600)
+    const r: any = computeInverseOp(board, {
+      op: 'replace',
+      board: { width: 800, height: 600, components: [] } as any
+    })
+    expect(r.op).toBe('replace')
+    expect(r.board).toEqual(board)
+    ;(board.components as any).push({ refid: 999, type: 'circle' })
+    expect(r.board.components).toHaveLength(1)
+  })
+
+  test('undefined board → null (방어)', () => {
+    expect(computeInverseOp(undefined, { op: 'remove', refid: 1 })).toBeNull()
+  })
+
+  test('round-trip: applyOp 후 inverse 적용 → 원본 복원 (modify)', () => {
+    const board = make([{ refid: 1, type: 'rect', left: 10, top: 20 }])
+    const op: BoardEditOp = { op: 'modify', refid: 1, patch: { left: 100 } as any }
+    const inverse = computeInverseOp(board, op)!
+    const after = applyOp(board, op)
+    const restored = applyOp(after, inverse)
+    expect((restored.components[0] as any).left).toBe(10)
+    expect((restored.components[0] as any).top).toBe(20)
+  })
+
+  test('round-trip: applyOp 후 inverse 적용 → 원본 복원 (remove)', () => {
+    const board = make([
+      { refid: 1, type: 'rect', name: 'A' },
+      { refid: 2, type: 'circle' }
+    ])
+    const op: BoardEditOp = { op: 'remove', refid: 1 }
+    const inverse = computeInverseOp(board, op)!
+    const after = applyOp(board, op)
+    expect(after.components).toHaveLength(1)
+    const restored = applyOp(after, inverse)
+    expect(restored.components).toHaveLength(2)
+    expect(restored.components.map(c => (c as any).refid).sort()).toEqual([1, 2])
+  })
+
+  test('round-trip: modifyBoard 의 inverse 로 원본 fillStyle 복원', () => {
+    const board: any = { width: 1000, height: 600, fillStyle: '#fff', components: [] }
+    const op: BoardEditOp = { op: 'modifyBoard', patch: { fillStyle: '#0a1929' } as any }
+    const inverse = computeInverseOp(board, op)!
+    const after: any = applyOp(board, op)
+    expect(after.fillStyle).toBe('#0a1929')
+    const restored: any = applyOp(after, inverse)
+    expect(restored.fillStyle).toBe('#fff')
+  })
+})
+
+describe('Phase 2 — Scene 조작 op 의 model 차원 정책', () => {
+  // model 차원 시뮬레이션은 noop (things-scene API 가 정본). verbose 는 무조건 applied 분류.
+
+  test('align: applyOp 는 board 그대로 반환 (noop)', () => {
+    const board = make([
+      { refid: 1, type: 'rect', left: 10, top: 20 },
+      { refid: 2, type: 'rect', left: 50, top: 80 }
+    ])
+    const r = applyOp(board, { op: 'align', refids: [1, 2], direction: 'left' })
+    expect(r).toBe(board) // reference 동일
+  })
+
+  test('distribute: noop', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyOp(board, { op: 'distribute', refids: [1, 2, 3], axis: 'horizontal' })
+    expect(r).toBe(board)
+  })
+
+  test('group / ungroup / zorder / arrange: noop', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    expect(applyOp(board, { op: 'group', refids: [1, 2] })).toBe(board)
+    expect(applyOp(board, { op: 'ungroup', refid: 5 })).toBe(board)
+    expect(applyOp(board, { op: 'zorder', refid: 1, direction: 'front' })).toBe(board)
+    expect(
+      applyOp(board, {
+        op: 'arrange',
+        refids: [1, 2],
+        layout: { type: 'grid', cols: 2 }
+      })
+    ).toBe(board)
+  })
+
+  test('verbose 분류 — scene-only op 는 모두 applied (missed 아님)', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    const r = applyBoardEditPatchVerbose(board, {
+      ops: [
+        { op: 'align', refids: [1], direction: 'left' },
+        { op: 'distribute', refids: [1, 2], axis: 'horizontal' },
+        { op: 'group', refids: [1, 2] },
+        { op: 'ungroup', refid: 1 },
+        { op: 'zorder', refid: 1, direction: 'front' },
+        { op: 'arrange', refids: [1, 2], layout: { type: 'row' } }
+      ],
+      summary: '',
+      confidence: 1
+    })
+    expect(r.applied).toHaveLength(6)
+    expect(r.missed).toHaveLength(0)
+  })
+
+  test('computeInverseOp — zorder 는 자동 반전 (forward↔backward, front↔back)', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    expect(
+      computeInverseOp(board, { op: 'zorder', refid: 1, direction: 'forward' })
+    ).toEqual({ op: 'zorder', refid: 1, direction: 'backward' })
+    expect(
+      computeInverseOp(board, { op: 'zorder', refid: 1, direction: 'front' })
+    ).toEqual({ op: 'zorder', refid: 1, direction: 'back' })
+  })
+
+  test('computeInverseOp — align/distribute/group/ungroup/arrange 는 null (호스트 책임)', () => {
+    const board = make([{ refid: 1, type: 'rect' }])
+    expect(
+      computeInverseOp(board, { op: 'align', refids: [1, 2], direction: 'left' })
+    ).toBeNull()
+    expect(
+      computeInverseOp(board, { op: 'distribute', refids: [1, 2], axis: 'horizontal' })
+    ).toBeNull()
+    expect(computeInverseOp(board, { op: 'group', refids: [1, 2] })).toBeNull()
+    expect(computeInverseOp(board, { op: 'ungroup', refid: 1 })).toBeNull()
+    expect(
+      computeInverseOp(board, {
+        op: 'arrange',
+        refids: [1, 2],
+        layout: { type: 'grid', cols: 2 }
+      })
+    ).toBeNull()
+  })
+})