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

package/server/service/apply-patch.ts

@@ -0,0 +1,411 @@
+/**
+ * BoardEditPatch 를 BoardModel 에 적용하는 표준 helper.
+ *
+ * 호출자가 patch 응답을 받아 보드에 반영할 때 사용.
+ * Pure function — 입력을 mutate 하지 않음.
+ */
+import type { BoardComponent, BoardModel } from '@things-factory/board-import'
+import type { BoardEditOp, BoardEditPatch } from './types.js'
+
+const EMPTY_BOARD: BoardModel = {
+  width: 1000,
+  height: 600,
+  components: []
+}
+
+export interface PatchApplyReport {
+  /** 패치 적용 후 보드. 모든 op 가 noop 이어도 입력 그대로 반환. */
+  board: BoardModel
+  /** 실제로 보드를 바꾼 op 들. */
+  applied: BoardEditOp[]
+  /** id 매칭 실패 등으로 noop 이 된 op 들 — 호출자가 사용자에게 알릴 단서. */
+  missed: BoardEditOp[]
+}
+
+export function applyBoardEditPatch(
+  board: BoardModel | undefined,
+  patch: BoardEditPatch
+): BoardModel {
+  return applyBoardEditPatchVerbose(board, patch).board
+}
+
+/**
+ * Verbose 변형 — 각 op 의 적용 여부를 보고.
+ *
+ * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다 (patch 함수의
+ * 의도적 단순화). LLM 이 잘못된 id 를 만들어 보내면 사용자에게 "수정했습니다"
+ * 라고 답하지만 실제로는 아무 변화도 없는 상황이 발생 — 호스트가 missed 를
+ * 보고 사용자에게 경고할 수 있도록 별도 entry point 제공.
+ */
+export function applyBoardEditPatchVerbose(
+  board: BoardModel | undefined,
+  patch: BoardEditPatch
+): PatchApplyReport {
+  let result: BoardModel = board ?? EMPTY_BOARD
+  const applied: BoardEditOp[] = []
+  const missed: BoardEditOp[] = []
+
+  for (const op of patch.ops) {
+    if (SCENE_ONLY_OPS.has(op.op)) {
+      // model 차원 noop 이지만 scene 차원 실제 적용 — applied 로 분류.
+      applied.push(op)
+      continue
+    }
+    const next = applyOp(result, op)
+    // componentsUnchanged 는 components 배열 동일 + width/height/fillStyle 동일 만 본다.
+    // modify / remove 의 silent no-op (ghost refid) 검출 전용 — modifyBoard 가 sky
+    // 등 다른 root 키만 바꿀 때 false negative 로 missed 분류되는 회귀 방지.
+    const componentMutating = op.op === 'modify' || op.op === 'remove'
+    if (next === result || (componentMutating && componentsUnchanged(result, next))) {
+      missed.push(op)
+    } else {
+      applied.push(op)
+      result = next
+    }
+  }
+
+  return { board: result, applied, missed }
+}
+
+function componentsUnchanged(prev: BoardModel, next: BoardModel): boolean {
+  // applyOp 는 항상 새 객체를 만든다 (`{ ...board, components: ... }`). 따라서 reference
+  // 비교가 안 되고 내용 비교가 필요. components 는 map/filter 결과 reference 도 다를 수
+  // 있으므로 length + JSON 깊이 비교.
+  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
+  }
+  // root meta (width/height/...) 비교
+  return prev.width === next.width && prev.height === next.height && prev.fillStyle === next.fillStyle
+}
+
+/**
+ * 주어진 board 상태에서 op 의 inverse 를 계산.
+ *
+ * Revert 기능의 코어 — patch 적용 직전 board 와 op 만 알면 그 op 의 역연산을
+ * 만들 수 있으므로, 호스트가 in-place 적용하면서 함께 누적해 두면 나중에
+ * 역순 실행만으로 복원 가능.
+ *
+ * 반환:
+ *   - inverse op 또는 null (unsupported / 데이터 부족)
+ *   - add 의 inverse 는 add 후 발급되는 refid 가 필요해서 모델 단계에서 계산 불가 →
+ *     호스트가 scene.add 직후 refid 를 캡처해 직접 만들 것 (이 함수는 pre-applied
+ *     board 만 보고 만들 수 있는 종류만 처리: remove / modify / modifyBoard / replace)
+ */
+export function computeInverseOp(
+  board: BoardModel | undefined,
+  op: BoardEditOp
+): BoardEditOp | null {
+  if (!board) return null
+  const components = board.components ?? []
+
+  switch (op.op) {
+    case 'add':
+      // add 의 inverse 는 새로 발급될 refid 를 알아야 → 호스트 측에서 처리
+      return null
+
+    case 'remove': {
+      // 자식 refid 도 매칭 (deep search).
+      const target = findComponentDeep(components, op.refid)
+      if (!target) return null // 매칭 실패 — silent no-op 이라 inverse 도 없음
+      return { op: 'add', component: JSON.parse(JSON.stringify(target)) }
+    }
+
+    case 'modify': {
+      // 자식 refid 도 매칭 (deep search).
+      const target = findComponentDeep(components, op.refid)
+      if (!target) return null
+      // patch 가 건드린 키만 보관. nested 는 통째로.
+      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':
+      // 이전 보드 통째로 보관 — replace 의 자연스러운 inverse 는 또 다른 replace
+      return { op: 'replace', board: JSON.parse(JSON.stringify(board)) }
+
+    case 'zorder': {
+      // forward ↔ backward / front ↔ back — 단순 반전. front/back 의 inverse 는
+      // 정확하지 않을 수 있음 (front 했다가 back 하면 원래 위치 보장 X), 호스트가
+      // 정확한 inverse 를 만들려면 zorder 직전 index 를 캡처해서 명시 modify 시퀀스로.
+      // 여기서는 best-effort 만.
+      const opp: Record<string, 'front' | 'back' | 'forward' | 'backward'> = {
+        forward: 'backward',
+        backward: 'forward',
+        front: 'back',
+        back: 'front'
+      }
+      const dir = opp[op.direction]
+      if (!dir) return null
+      return { op: 'zorder', refid: op.refid, direction: dir }
+    }
+
+    case 'align':
+    case 'distribute':
+    case 'group':
+    case 'ungroup':
+    case 'arrange':
+      // 좌표 변경 / 부모 재구성 / 새 group refid 발급 등은 scene 호출 후에야
+      // 알 수 있음. 호스트가 직접 inverse 만든다 (변경 컴포넌트 좌표 백업 →
+      // modify 시퀀스, group 의 새 refid 캡처 → ungroup 등).
+      return null
+
+    default:
+      return null
+  }
+}
+
+/**
+ * Scene 조작 op 들 — model 차원 시뮬레이션이 things-scene 의 결과와 일치 보장
+ * 어려움 (things-scene 의 정확한 좌표 계산 / refid 발급 / 부모 재구성 로직). 따라서
+ * apply-patch 에서는 noop. 호스트가 things-scene 의 정본 API (scene.align,
+ * scene.distribute, scene.group/ungroup, scene.zorder) 를 직접 호출.
+ *
+ * verbose 분류에서는 무조건 applied 로 — model 변화가 안 보여도 scene 차원 실제 적용됨.
+ */
+const SCENE_ONLY_OPS = new Set<BoardEditOp['op']>([
+  'align',
+  'distribute',
+  'group',
+  'ungroup',
+  'zorder',
+  'arrange'
+])
+
+export function applyOp(board: BoardModel, op: BoardEditOp): BoardModel {
+  const components = board.components ?? []
+  switch (op.op) {
+    case 'replace':
+      return op.board
+
+    case 'add':
+      // top-level 추가 — 본 op 는 자식 컴포넌트로의 추가는 지원 안 함 (별도 op 필요)
+      return { ...board, components: [...components, op.component] }
+
+    case 'remove':
+      // 자식 (group/container 안) refid 도 매칭 — deep search.
+      return { ...board, components: removeComponentDeep(components, op.refid) }
+
+    case 'modify':
+      // 자식 refid 도 매칭 — group/container 안의 컴포넌트 수정 가능.
+      return { ...board, components: modifyComponentDeep(components, op.refid, op.patch) }
+
+    case 'modifyBoard': {
+      // 루트 속성 (fillStyle / width / height / name 등) 만 deep merge.
+      // components 키는 무시 — 자식 변경은 add/remove/modify 별도 op 로.
+      const patch = { ...op.patch } as any
+      delete patch.components
+      return mergeBoardRoot(board, patch)
+    }
+
+    case 'align':
+    case 'distribute':
+    case 'group':
+    case 'ungroup':
+    case 'zorder':
+    case 'arrange':
+      // scene-only — model 차원 noop. 정본은 things-scene API 가.
+      return board
+
+    default:
+      return board
+  }
+}
+
+/**
+ * patch 내 `null` 의 시맨틱 — **"이 키를 제거하라"**.
+ *
+ * 이유:
+ *   1. fillStyle/strokeStyle 처럼 `string | object | undefined` 인 필드는
+ *      null 로 set 하면 typeof null === 'object' 함정에 빠져 다운스트림이 크래시.
+ *   2. computeInverseOp 가 base 에 키가 없던 (`undefined`) 경우 inverse 를 null
+ *      로 발급 — "키 제거" 의도와 정확히 일치. 새 시맨틱 하에서 inverse 가
+ *      자연스럽게 올바로 동작.
+ *   3. mode 전환 시 stale 필드 정리도 새 patch 에 `oldKey: null` 만 끼워서 처리 가능.
+ *
+ * 호출자가 명시적으로 "null 값 자체를 set" 하고 싶으면 → 별도 op 를 도입해야 하나,
+ * 현재 보드 모델에서 의미 있는 사용처가 없음.
+ */
+
+function mergeBoardRoot(board: BoardModel, patch: any): BoardModel {
+  const out: any = { ...board }
+  for (const key of Object.keys(patch)) {
+    const bv = (board as any)[key]
+    const pv = patch[key]
+    if (pv === null) {
+      delete out[key]
+    } else if (
+      bv !== null &&
+      typeof bv === 'object' &&
+      typeof pv === 'object' &&
+      !Array.isArray(bv) &&
+      !Array.isArray(pv)
+    ) {
+      out[key] = deepMergeRoot(bv, pv)
+    } else {
+      out[key] = pv
+    }
+  }
+  return out
+}
+
+function deepMergeRoot(a: any, b: any): any {
+  const out: any = { ...a }
+  for (const key of Object.keys(b)) {
+    const av = a[key]
+    const bv = b[key]
+    if (bv === null) {
+      delete out[key]
+    } else if (
+      av !== null &&
+      typeof av === 'object' &&
+      typeof bv === 'object' &&
+      !Array.isArray(av) &&
+      !Array.isArray(bv)
+    ) {
+      out[key] = deepMergeRoot(av, bv)
+    } else {
+      out[key] = bv
+    }
+  }
+  return out
+}
+
+/**
+ * 컴포넌트에 부분 patch 를 적용.
+ * threeD 등 nested object 는 deep merge — 호출자가 색만 바꾸려고 했을 때 geometry 까지 사라지지 않도록.
+ * patchVal === null 이면 해당 키를 제거한다 (위 시맨틱 참조).
+ */
+export function mergeComponent(base: BoardComponent, patch: Partial<BoardComponent>): BoardComponent {
+  const out: any = { ...base }
+  for (const key of Object.keys(patch)) {
+    const baseVal = (base as any)[key]
+    const patchVal = (patch as any)[key]
+    if (patchVal === null) {
+      delete out[key]
+    } else if (isPlainObject(baseVal) && isPlainObject(patchVal)) {
+      out[key] = deepMerge(baseVal, patchVal)
+    } else {
+      out[key] = patchVal
+    }
+  }
+  return out as BoardComponent
+}
+
+function deepMerge(a: any, b: any): any {
+  const out: any = { ...a }
+  for (const key of Object.keys(b)) {
+    const av = a[key]
+    const bv = b[key]
+    if (bv === null) {
+      delete out[key]
+    } else if (isPlainObject(av) && isPlainObject(bv)) {
+      out[key] = deepMerge(av, bv)
+    } else {
+      out[key] = bv
+    }
+  }
+  return out
+}
+
+function isPlainObject(v: any): boolean {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}
+
+// ── 자식 컴포넌트 (group/container 안) 까지 매칭 — deep search ─
+
+/**
+ * 보드 트리 안에서 refid 로 컴포넌트 찾기 — 깊은 search.
+ * top-level 만 보던 옛 동작 → group/container 자식도 매칭.
+ */
+function findComponentDeep(components: BoardComponent[], refid: number): BoardComponent | undefined {
+  for (const c of components) {
+    if (!c) continue
+    if ((c as any).refid === refid) return c
+    const children = (c as any).components
+    if (Array.isArray(children) && children.length > 0) {
+      const sub = findComponentDeep(children, refid)
+      if (sub) return sub
+    }
+  }
+  return undefined
+}
+
+/**
+ * modify op 의 deep 적용 — 자식 트리까지 walk 하며 매칭되는 컴포넌트만 mergeComponent.
+ * Pure function — 변경 없는 가지는 같은 reference 반환 (structural sharing).
+ */
+function modifyComponentDeep(
+  components: BoardComponent[],
+  refid: number,
+  patch: any
+): BoardComponent[] {
+  let changed = false
+  const out = components.map(c => {
+    if (!c) return c
+    if ((c as any).refid === refid) {
+      changed = true
+      return mergeComponent(c, patch)
+    }
+    const children = (c as any).components
+    if (Array.isArray(children) && children.length > 0) {
+      const updated = modifyComponentDeep(children, refid, patch)
+      if (updated !== children) {
+        changed = true
+        return { ...c, components: updated }
+      }
+    }
+    return c
+  })
+  return changed ? out : components
+}
+
+/**
+ * remove op 의 deep 적용 — 자식 트리까지 walk 하며 해당 refid 의 컴포넌트 제거.
+ * 부모는 보존, 빈 group 도 보존 (group 이 비더라도 사용자가 의도적으로 만든 컨테이너일 수 있음).
+ */
+function removeComponentDeep(
+  components: BoardComponent[],
+  refid: number
+): BoardComponent[] {
+  let changed = false
+  const out: BoardComponent[] = []
+  for (const c of components) {
+    if (!c) {
+      out.push(c)
+      continue
+    }
+    if ((c as any).refid === refid) {
+      changed = true
+      continue // 이 컴포넌트 자체를 제거
+    }
+    const children = (c as any).components
+    if (Array.isArray(children) && children.length > 0) {
+      const updated = removeComponentDeep(children, refid)
+      if (updated !== children) {
+        changed = true
+        out.push({ ...c, components: updated })
+        continue
+      }
+    }
+    out.push(c)
+  }
+  return changed ? out : components
+}