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

package/dist-server/service/apply-patch.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyBoardEditPatch = applyBoardEditPatch;
+exports.applyBoardEditPatchVerbose = applyBoardEditPatchVerbose;
+exports.computeInverseOp = computeInverseOp;
+exports.applyOp = applyOp;
+exports.mergeComponent = mergeComponent;
+const EMPTY_BOARD = {
+    width: 1000,
+    height: 600,
+    components: []
+};
+function applyBoardEditPatch(board, patch) {
+    return applyBoardEditPatchVerbose(board, patch).board;
+}
+/**
+ * Verbose 변형 — 각 op 의 적용 여부를 보고.
+ *
+ * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다 (patch 함수의
+ * 의도적 단순화). LLM 이 잘못된 id 를 만들어 보내면 사용자에게 "수정했습니다"
+ * 라고 답하지만 실제로는 아무 변화도 없는 상황이 발생 — 호스트가 missed 를
+ * 보고 사용자에게 경고할 수 있도록 별도 entry point 제공.
+ */
+function applyBoardEditPatchVerbose(board, patch) {
+    let result = board ?? EMPTY_BOARD;
+    const applied = [];
+    const missed = [];
+    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, next) {
+    // 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)
+ */
+function computeInverseOp(board, op) {
+    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 = {};
+            for (const k of Object.keys(op.patch || {})) {
+                const v = target[k];
+                oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v));
+            }
+            return { op: 'modify', refid: op.refid, patch: oldValues };
+        }
+        case 'modifyBoard': {
+            const oldValues = {};
+            const patch = op.patch || {};
+            for (const k of Object.keys(patch)) {
+                if (k === 'components')
+                    continue;
+                const v = board[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 = {
+                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([
+    'align',
+    'distribute',
+    'group',
+    'ungroup',
+    'zorder',
+    'arrange'
+]);
+function applyOp(board, op) {
+    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 };
+            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, patch) {
+    const out = { ...board };
+    for (const key of Object.keys(patch)) {
+        const bv = board[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, b) {
+    const out = { ...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 이면 해당 키를 제거한다 (위 시맨틱 참조).
+ */
+function mergeComponent(base, patch) {
+    const out = { ...base };
+    for (const key of Object.keys(patch)) {
+        const baseVal = base[key];
+        const patchVal = patch[key];
+        if (patchVal === null) {
+            delete out[key];
+        }
+        else if (isPlainObject(baseVal) && isPlainObject(patchVal)) {
+            out[key] = deepMerge(baseVal, patchVal);
+        }
+        else {
+            out[key] = patchVal;
+        }
+    }
+    return out;
+}
+function deepMerge(a, b) {
+    const out = { ...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) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+// ── 자식 컴포넌트 (group/container 안) 까지 매칭 — deep search ─
+/**
+ * 보드 트리 안에서 refid 로 컴포넌트 찾기 — 깊은 search.
+ * top-level 만 보던 옛 동작 → group/container 자식도 매칭.
+ */
+function findComponentDeep(components, refid) {
+    for (const c of components) {
+        if (!c)
+            continue;
+        if (c.refid === refid)
+            return c;
+        const children = c.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, refid, patch) {
+    let changed = false;
+    const out = components.map(c => {
+        if (!c)
+            return c;
+        if (c.refid === refid) {
+            changed = true;
+            return mergeComponent(c, patch);
+        }
+        const children = c.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, refid) {
+    let changed = false;
+    const out = [];
+    for (const c of components) {
+        if (!c) {
+            out.push(c);
+            continue;
+        }
+        if (c.refid === refid) {
+            changed = true;
+            continue; // 이 컴포넌트 자체를 제거
+        }
+        const children = c.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;
+}
+//# sourceMappingURL=apply-patch.js.map

package/dist-server/service/apply-patch.js.map

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

package/dist-server/service/assistant.d.ts

@@ -0,0 +1,84 @@
+/**
+ * DefaultBoardAIAssistant — base AIClient 위에 LLM 프롬프트로 chat() 구현.
+ */
+import type { AIClient, AITool, AIToolCall, AIToolChatResult } from '@things-factory/ai-client-base';
+import { type BoardModel, type ComponentCategory } from '@things-factory/board-import';
+import type { BoardAIAssistant, BoardEditOp, ChatOptions, ChatResponse, LLMMessage } from './types.js';
+import { type AgenticLoopResult } from './agentic-loop';
+export interface BoardAIAssistantOptions {
+    /** 기본 scope (chat 호출 시 옵션이 없으면 사용) */
+    scopes?: string[];
+    knownTypes?: string[];
+    categories?: ComponentCategory[];
+}
+export declare class DefaultBoardAIAssistant implements BoardAIAssistant {
+    private base;
+    private options;
+    readonly id: string;
+    constructor(base: AIClient, options?: BoardAIAssistantOptions);
+    chat(messages: LLMMessage[], currentBoard: BoardModel | undefined, options?: ChatOptions): Promise<ChatResponse>;
+    private chatViaTools;
+    private resolveTypesAndCategories;
+    private buildSystemPromptForTools;
+}
+/**
+ * 4 op 직교 set 을 4 개의 도구로 정의.
+ *
+ * 핵심: addComponent 의 `type` 파라미터가 knownTypes 의 enum 으로 강제 →
+ *       LLM 이 등록 안 된 type 을 만들 수 없음 (provider 단계에서 차단).
+ *
+ * 좌표/크기 키들은 모두 optional 로 허용 (type 별로 사용 키 다름).
+ * type-specific 추가 속성은 additionalProperties 로 허용.
+ */
+export declare function buildBoardEditTools(knownTypes: string[]): AITool[];
+/**
+ * Read tool 의 서버측 실행기 — currentBoard / selectedRefids 에 대해 즉시 실행해 결과 반환.
+ * LLM 의 다음 turn 에 tool_result 로 회신된다.
+ *
+ * 식별자 정책:
+ *   - 컴포넌트 targeting 은 항상 refid (universal numeric handle).
+ *   - id 는 데이터 바인딩 이름이며 unique 가 아니다 — filter 용도로만 사용 (findComponents).
+ */
+export declare function executeReadTool(call: AIToolCall, currentBoard: BoardModel | null | undefined, selectedRefids: number[]): any;
+export declare function isReadTool(name: string): boolean;
+/**
+ * 등록된 색 팔레트 이름 목록 — catalog-resolver / 클라이언트 popup 데이터 source.
+ * 호스트 패키지가 추가 팔레트 등록은 현재 미지원 (향후 별도 registry 패턴 필요).
+ */
+export declare function listColorPaletteNames(): string[];
+/**
+ * 등록된 레이아웃 템플릿 이름 목록 — 위와 동일.
+ */
+export declare function listLayoutTemplateNames(): string[];
+/**
+ * agentic loop 의 비정상 종료 사유 → 사용자 메시지에 부기할 한국어 한 줄.
+ *
+ * 정상 종료 (abortReason undefined) 면 빈 문자열 — concat 해도 무해.
+ * 사용자에게 "왜 중간에 멈췄는지" 단서 제공이 목적 — 침묵 종료 금지.
+ */
+export declare function formatAbortNotice(abortReason: AgenticLoopResult['abortReason']): string;
+/**
+ * tool 결과를 UI fold-able 박스에 보여줄 만한 크기로 요약.
+ *
+ * 원본 그대로면 findComponents 50개 / getAtmosphereGuide 같은 큰 객체가 ChatMessage
+ * 영속까지 부담 — 핵심 모양만 유지하고 나머지는 marker.
+ */
+export declare function summarizeToolResult(value: any, depth?: number): any;
+export declare function isWriteTool(name: string): boolean;
+export declare function isActionTool(name: string): boolean;
+/**
+ * Tool call → BoardActionOp 변환 (C-1 ephemeral scene 조작).
+ * 잘못된 인자는 null — agentic loop 가 Unknown tool 비슷하게 처리.
+ */
+export declare function toolCallToBoardActionOp(tc: AIToolCall): import('./types.js').BoardActionOp | null;
+/**
+ * AIToolChatResult → ChatResponse.
+ *
+ * 정책 — followUp 항상 undefined: reply 와 동일 텍스트를 followUp 에 복제하면 클라이언트
+ * 에서 .md-body 와 .followup 두 박스에 같은 내용이 표시되어 사용자에게 "동일 응답이
+ * 두 번 반복" 으로 보인다. 명확화 질문이 필요한 경우 LLM 이 reply 자체에 포함시키도록
+ * 설계.
+ */
+export declare function toolResultToChatResponse(result: AIToolChatResult): ChatResponse;
+export declare function toolCallToBoardEditOp(tc: AIToolCall, components?: ReadonlyArray<any>): BoardEditOp | BoardEditOp[] | null;
+export declare function summarizeBoard(board: BoardModel | null | undefined): any;