@things-factory/board-ai 10.1.24 → 10.1.25

package/dist-server/service/assistant.js

@@ -9,9 +9,9 @@ exports.listLayoutTemplateNames = listLayoutTemplateNames;
 exports.isWriteTool = isWriteTool;
 exports.isActionTool = isActionTool;
 exports.buildToolGate = buildToolGate;
-exports.toolCallToBoardActionOp = toolCallToBoardActionOp;
+exports.toolCallToSceneActionOp = toolCallToSceneActionOp;
 exports.toolResultToChatResponse = toolResultToChatResponse;
-exports.toolCallToBoardEditOp = toolCallToBoardEditOp;
+exports.toolCallToSceneEditOp = toolCallToSceneEditOp;
 exports.summarizeBoard = summarizeBoard;
 const board_import_1 = require("@things-factory/board-import");
 const prefab_registry_1 = require("./prefab-registry");
@@ -183,7 +183,7 @@ class DefaultBoardAIAssistant {
                 executeReadTool: (tc, ctx) => wrappedExecuteReadTool(tc, ctx.board, ctx.selectedRefids),
                 /* 문서에서 부품을 꺼내는 일은 **여기서** 한다 — 루프는 board 의 모양을 모른다. */
                 validateWriteToolCall: (tc, ctx) => (0, tool_validation_1.validateWriteToolCall)(tc, (ctx.board?.components ?? [])),
-                toolCallToOp: toolCallToBoardActionOp,
+                toolCallToOp: toolCallToSceneActionOp,
                 summarizeToolResult: ai_client_base_1.summarizeToolResult
             },
             context: { board: currentBoard, selectedRefids }
@@ -193,11 +193,11 @@ class DefaultBoardAIAssistant {
         const toolUsages = loopResult.toolUsages;
         const lastText = loopResult.lastText;
         const stopReason = loopResult.stopReason;
-        // accumulated write calls → BoardEditPatch (tool 이 array 반환 가능 — flat)
+        // accumulated write calls → SceneEditPatch (tool 이 array 반환 가능 — flat)
         const components = (currentBoard?.components ?? []);
         const ops = accumulatedWriteCalls
             .flatMap(call => {
-            const r = toolCallToBoardEditOp(call, components, gate);
+            const r = toolCallToSceneEditOp(call, components, gate);
             if (r === null)
                 return [];
             return Array.isArray(r) ? r : [r];
@@ -287,7 +287,7 @@ class DefaultBoardAIAssistant {
 아무것도 안 바뀌었기 때문.
 
 룰:
-  1. 변경 요청 → write tool 호출 필수 (modifyBoard / setFill / setStroke / setMaterial /
+  1. 변경 요청 → write tool 호출 필수 (modifyScene / setFill / setStroke / setMaterial /
      setShadow / setOpacity / setVisible / setFont / setText / setMaterial / addComponent /
      removeComponentByRefid / modifyComponentByRefid / align/distribute/group/zorder 등)
   2. 호출 + 짧은 reply 텍스트 동시 작성 OK — reply 는 *결과* 를 한국어로 한두 문장 요약
@@ -311,22 +311,22 @@ root-level properties separate from any child:
     - 3D 환경: \`sky\` / \`skyColor\` / \`exposure\` / \`hemi*\` / \`dirLight*\` / \`dirShadow*\` / \`camera*\` / \`autoRotate\`
     - 식별: \`id\`, \`refid\`, \`type\` ("model-layer")
     ⚠ 보드 \*\*name\*\* 은 root attribute 가 아님 — Board 엔티티의 DB 컬럼이지 scene
-    MODEL 의 필드가 아님 (model-layer 가 무시). 보드 라벨 변경은 modifyBoard 영역 X.
+    MODEL 의 필드가 아님 (model-layer 가 무시). 보드 라벨 변경은 modifyScene 영역 X.
   • Children: an array of components inside the board (rect / circle / text /
     gauge / etc.). 컴포넌트들은 \`name\` (user label) 를 가질 수 있음 — 이는 child
     component 의 속성이지 board root 의 속성이 아님.
 
 Rules:
   - To change a board-level attribute (background, board size, 3D atmosphere)
-    → call \`modifyBoard({ patch: { fillStyle: ..., width: ..., sky: ..., exposure: ..., dirLight*: ..., hemi*: ... } })\`.
+    → call \`modifyScene({ patch: { fillStyle: ..., width: ..., sky: ..., exposure: ..., dirLight*: ..., hemi*: ... } })\`.
     NOTE: 보드 라벨/제목 ("보드 이름") 은 scene model 이 아니라 Board *엔티티* 의 컬럼.
-    things-scene 의 model-layer 는 \`name\` 을 인식하지 않음. modifyBoard 의 patch 에
+    things-scene 의 model-layer 는 \`name\` 을 인식하지 않음. modifyScene 의 patch 에
     \`name\` 을 넣지 말 것 — 죽은 필드로 박힐 뿐 효과 없음.
   - To change a CHILD COMPONENT's attribute → call \`modifyComponentByRefid\`.
-  - DO NOT use modifyBoard to change a child. DO NOT use modifyComponentByRefid
+  - DO NOT use modifyScene to change a child. DO NOT use modifyComponentByRefid
     to change board background.
   - "보드 배경색", "board background", "테두리/캔버스 크기" 같은 요청은 root
-    attribute 변경 → \`modifyBoard\`.
+    attribute 변경 → \`modifyScene\`.
 
 ==== COMPONENT TREE (NESTING) ====
 컴포넌트는 *재귀 구조*. group / container 같은 부모 컴포넌트는 자기 \`components\`
@@ -392,8 +392,8 @@ to that wording in your reply. Do not echo refid back to the user.
 
 ==== AVAILABLE TOOLS ====
 Board-level (root attributes):
-  - modifyBoard: change board's own fillStyle / width / height / fitMode / translate / scale AND 3D atmosphere (sky / skyColor / exposure / hemiSkyColor / hemiGroundColor / hemiIntensity / dirLightEnabled / dirLightColor / dirLightIntensity / dirLightFollowCamera / dirLightAzimuth / dirLightElevation / dirShadow* / camera* / autoRotate / initialCameraView). ⚠ "name" 금지 — scene MODEL 이 아니라 Board 엔티티 컬럼.
-  - replaceBoard: wholesale board reset (heavy — prefer modifyBoard for most changes)
+  - modifyScene: change board's own fillStyle / width / height / fitMode / translate / scale AND 3D atmosphere (sky / skyColor / exposure / hemiSkyColor / hemiGroundColor / hemiIntensity / dirLightEnabled / dirLightColor / dirLightIntensity / dirLightFollowCamera / dirLightAzimuth / dirLightElevation / dirShadow* / camera* / autoRotate / initialCameraView). ⚠ "name" 금지 — scene MODEL 이 아니라 Board 엔티티 컬럼.
+  - replaceBoard: wholesale board reset (heavy — prefer modifyScene for most changes)
 Child components — data:
   - addComponent: add a new component (parallel calls for multiple adds)
   - removeComponentByRefid: remove a child by refid
@@ -450,10 +450,10 @@ Modeller actions (ephemeral — does NOT modify the board model, no undo, no sav
   - fitToView: reset view so the board fits the canvas (mode: fit/ratio/width/height)
   - setSceneMode: switch modeller between 'edit' and 'view' modes
 Knowledge:
-  - getAtmosphereGuide: 3D atmosphere synthesis primer — parameter physics, ranges, color theory, archetype recipes (time-of-day / indoor / surreal). Call BEFORE applying atmospheric/styling modifyBoard for any natural-language mood request.
+  - getAtmosphereGuide: 3D atmosphere synthesis primer — parameter physics, ranges, color theory, archetype recipes (time-of-day / indoor / surreal). Call BEFORE applying atmospheric/styling modifyScene for any natural-language mood request.
 
 ==== 3D ATMOSPHERE SYNTHESIS ====
-3D scene atmosphere = combination of (1) sky preset / color (2) exposure (3) hemisphere ambient (4) directional sun/key (5) floor material. ALL of these are root-level board attributes — applied via a SINGLE modifyBoard call.
+3D scene atmosphere = combination of (1) sky preset / color (2) exposure (3) hemisphere ambient (4) directional sun/key (5) floor material. ALL of these are root-level board attributes — applied via a SINGLE modifyScene call.
 
 For ANY natural-language atmospheric request — "공장 분위기로", "심해 컬러", "황혼", "사이버펑크", "안개 자욱한 새벽", "1980 우주정거장", "따뜻하게", "차갑고 극적으로" — follow this workflow:
 
@@ -461,11 +461,11 @@ For ANY natural-language atmospheric request — "공장 분위기로", "심해
   2. From the guide's "archetypes" section, pick the closest base recipe (time-of-day / indoor / surreal). Interpolate if user combines multiple cues.
   3. Apply user's nuance via the guide's "modifiers" (warm/cool, drama, saturation, contrast).
   4. Sanity-check: avoid washout (all params maxed) or mud (all minned). Confirm hemi sky/ground colors and dir color are consistent with the mood.
-  5. Apply ALL keys in ONE modifyBoard({patch}) call (sky, skyColor?, exposure, hemiIntensity, hemiSkyColor, hemiGroundColor, dirLightEnabled, dirLightColor, dirLightIntensity, dirLightFollowCamera=false, dirLightAzimuth, dirLightElevation, fillStyle?). ONE patch — not multiple modifyBoard calls.
+  5. Apply ALL keys in ONE modifyScene({patch}) call (sky, skyColor?, exposure, hemiIntensity, hemiSkyColor, hemiGroundColor, dirLightEnabled, dirLightColor, dirLightIntensity, dirLightFollowCamera=false, dirLightAzimuth, dirLightElevation, fillStyle?). ONE patch — not multiple modifyScene calls.
   6. In the reply, briefly state which archetype + modifier you composed.
 
 Avoid:
-  - Calling modifyBoard with only "fillStyle" for atmospheric requests — that only changes 2D background and floor tint, NOT the 3D scene mood.
+  - Calling modifyScene with only "fillStyle" for atmospheric requests — that only changes 2D background and floor tint, NOT the 3D scene mood.
   - Mixing a sky preset with explicit skyColor (preset wins, skyColor ignored).
   - Setting dirLightAzimuth/Elevation while leaving dirLightFollowCamera=true (no effect — set follow=false first).
   - Using only canned presets when the user describes a custom mood — the guide enables synthesis beyond presets.
@@ -651,7 +651,7 @@ function buildBoardEditTools(knownTypes, exposure = {}) {
             }
         },
         {
-            name: 'modifyBoard',
+            name: 'modifyScene',
             description: "Modify the BOARD's OWN root-level properties — the board itself is the topmost parent (model-layer) and has its own attributes (NOT child components). Valid root keys (things-scene 의 model-layer 가 실제 인식하는 것만):\n  • Layout/Geometry: `width`, `height`, `fitMode` ('ratio'|'both'|'width'|'height'|'center'|'none'), `translate` ({x,y}), `scale` ({x,y})\n  • 2D 배경: `fillStyle` (string color or object)\n  • 3D Sky: `sky` (preset 이름), `skyColor` (preset 미지정 시 단색)\n  • 3D Tone: `exposure` (toneMappingExposure, 기본 1.0~1.2)\n  • 3D Hemisphere light: `hemiSkyColor`, `hemiGroundColor`, `hemiIntensity` (기본 4.0)\n  • 3D Directional light: `dirLightEnabled` (bool), `dirLightColor`, `dirLightIntensity` (기본 2.0), `dirLightFollowCamera` (bool, 기본 true), `dirLightAzimuth` (deg, follow=false 일 때만), `dirLightElevation` (deg, follow=false 일 때만)\n  • 3D Shadow: `dirShadowEnabled`, `dirShadowMapSize` (기본 2048), `dirShadowBias`\n  • 3D Camera: `cameraX`, `cameraY`, `cameraZ`, `cameraAutoPlay` ('orbit' 등), `autoRotate` (bool), `initialCameraView`\n\n⚠ 절대 사용 금지: `name` — Board *엔티티* 의 컬럼이지 scene MODEL 의 필드가 아님. things-scene 이 인식 안 함. 보드 라벨 변경은 GraphQL boardPatch 의 영역.\n\nDo NOT use for child component edits (use modifyComponentByRefid for those). Do NOT pass a `components` array here — children are managed by add/remove/modify ops separately.",
             parameters: {
                 type: 'object',
@@ -667,7 +667,7 @@ function buildBoardEditTools(knownTypes, exposure = {}) {
         },
         {
             name: 'replaceBoard',
-            description: 'Replace the entire board (use ONLY for fresh start or wholesale redesign — heavy operation that resets undo history). For just changing background or size, prefer modifyBoard. Provide width/height and the full components array.',
+            description: 'Replace the entire board (use ONLY for fresh start or wholesale redesign — heavy operation that resets undo history). For just changing background or size, prefer modifyScene. Provide width/height and the full components array.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -736,7 +736,7 @@ function buildBoardEditTools(knownTypes, exposure = {}) {
         },
         {
             name: 'getAtmosphereGuide',
-            description: "Get a comprehensive 3D atmosphere synthesis guide — parameter physics (sky / exposure / hemisphere / directional / shadow / floor / camera), sane ranges, color theory, time-of-day archetypes, and indoor/surreal mood recipes. Call this BEFORE applying atmospheric/styling changes via modifyBoard whenever the user describes a mood / scene / time-of-day in natural language (e.g. '심해 컬러', '황혼', '공장 분위기', '사이버펑크', '안개 자욱한 새벽'). The guide enables you to synthesize concrete parameter values yourself, beyond canned presets.",
+            description: "Get a comprehensive 3D atmosphere synthesis guide — parameter physics (sky / exposure / hemisphere / directional / shadow / floor / camera), sane ranges, color theory, time-of-day archetypes, and indoor/surreal mood recipes. Call this BEFORE applying atmospheric/styling changes via modifyScene whenever the user describes a mood / scene / time-of-day in natural language (e.g. '심해 컬러', '황혼', '공장 분위기', '사이버펑크', '안개 자욱한 새벽'). The guide enables you to synthesize concrete parameter values yourself, beyond canned presets.",
             parameters: { type: 'object', properties: {} }
         },
         {
@@ -1068,7 +1068,7 @@ const WRITE_TOOL_NAMES = new Set([
     'setShadowProperties',
     'clearStyle',
     'copyStyle',
-    'modifyBoard',
+    'modifyScene',
     'replaceBoard',
     // Phase 2 — model 차원 scene 조작 (좌표/구조/zorder)
     'alignComponents',
@@ -1085,7 +1085,7 @@ const WRITE_TOOL_NAMES = new Set([
 ]);
 /**
  * C-1 — ephemeral scene 조작 (selection / view / mode). model 변경 X, undo 영향 X.
- * 별도 ChatResponse.actions 채널로 전달 → 호스트가 board-action-execute 로 적용.
+ * 별도 ChatResponse.actions 채널로 전달 → 호스트가 scene-action-execute 로 적용.
  */
 const ACTION_TOOL_NAMES = new Set([
     'selectComponents',
@@ -1222,13 +1222,13 @@ function executeReadTool(call, currentBoard, selectedRefids) {
  *
  * 의도 — preset 한 단어로 끝나지 않는 사용자 요청 ("심해", "황혼", "1980 우주정거장",
  * "안개 새벽") 에 AI 가 구체적 파라미터 값을 직접 합성하도록 물리/색채/미학 지식
- * 동시 제공. AI 는 이 가이드를 받은 뒤 modifyBoard 로 한 번에 적용.
+ * 동시 제공. AI 는 이 가이드를 받은 뒤 modifyScene 로 한 번에 적용.
  *
- * things-scene 의 board model 에 들어가는 root level 키만 다룸 (modifyBoard 로
+ * things-scene 의 board model 에 들어가는 root level 키만 다룸 (modifyScene 로
  * 적용 가능한 것). camera position 같은 ephemeral 한 것은 별도 영역.
  */
 const ATMOSPHERE_GUIDE = {
-    overview: '3D 보드 분위기는 (1) sky preset 또는 단색 (2) tone mapping exposure (3) hemisphere ambient (4) directional sun/key (5) floor 의 조합. 모두 board root model 의 속성이라 modifyBoard 단일 op 로 한 번에 적용. 자연어 요청은 archetype 레시피를 base 로 잡고 modifier 로 fine-tune.',
+    overview: '3D 보드 분위기는 (1) sky preset 또는 단색 (2) tone mapping exposure (3) hemisphere ambient (4) directional sun/key (5) floor 의 조합. 모두 board root model 의 속성이라 modifyScene 단일 op 로 한 번에 적용. 자연어 요청은 archetype 레시피를 base 로 잡고 modifier 로 fine-tune.',
     parameters: {
         sky: {
             description: '3D 배경 + IBL (image-based lighting) 의 source. preset / "color" / "" 셋 중 하나.',
@@ -1553,7 +1553,7 @@ const ATMOSPHERE_GUIDE = {
         '2. archetypes 에서 가장 가까운 base 레시피 선택.',
         '3. modifiers 로 사용자 요청 뉘앙스 fine-tune (warm/cool/drama/...).',
         '4. sanity check — exposure × hemi × dir 어느 한쪽 극단 아닌지, hemi sky/ground 색 모순 없는지.',
-        "5. modifyBoard({ patch: { ...combined keys... } }) 한 번에 적용. 사용자에게 어떤 archetype + modifier 조합으로 갔는지 한 줄로 설명."
+        "5. modifyScene({ patch: { ...combined keys... } }) 한 번에 적용. 사용자에게 어떤 archetype + modifier 조합으로 갔는지 한 줄로 설명."
     ],
     pitfalls: [
         'sky preset 위에 skyColor 같이 지정하면 preset 이 우선 (skyColor 무시).',
@@ -1573,7 +1573,7 @@ const ATMOSPHERE_GUIDE = {
  * 사용 흐름:
  *   1. 사용자 의도 (산업 / 금융 / 의료 / SF / ...) 식별
  *   2. recommendations 에서 매칭 후보 1~2개 추림
- *   3. modifyBoard 로 board.fillStyle 을 palette.base 로 설정
+ *   3. modifyScene 로 board.fillStyle 을 palette.base 로 설정
  *   4. addPrefab / addComponent 시 palette 의 surface/accent/text 사용
  *   5. 일관된 룩 → 한 번 정한 팔레트 안에서만 색 선택
  *
@@ -1700,7 +1700,7 @@ const COLOR_PALETTES = {
     workflow: [
         '1. 사용자 도메인 / 분위기 키워드 식별 — 산업/금융/관제/의료/SF/프레젠테이션',
         '2. recommendations 에서 매칭 후보 추림. 사용자 모호하면 가장 흔한 industrial-steel 디폴트.',
-        "3. modifyBoard({ patch: { fillStyle: palette.base } }) 으로 보드 배경 set.",
+        "3. modifyScene({ patch: { fillStyle: palette.base } }) 으로 보드 배경 set.",
         '4. 이후 모든 add / addPrefab 호출 시 palette.surface / accent / text / border 사용. 자유 색 X.',
         '5. status 표시는 success / warning / danger / info 4종에서만 — 자체 hex 만들지 마라.'
     ],
@@ -1872,10 +1872,10 @@ function buildExternalCategoryDefinitions(filter) {
     }));
 }
 /**
- * Tool call → BoardActionOp 변환 (C-1 ephemeral scene 조작).
+ * Tool call → SceneActionOp 변환 (C-1 ephemeral scene 조작).
  * 잘못된 인자는 null — agentic loop 가 Unknown tool 비슷하게 처리.
  */
-function toolCallToBoardActionOp(tc, gate = buildToolGate()) {
+function toolCallToSceneActionOp(tc, gate = buildToolGate()) {
     const args = tc.arguments ?? {};
     /* 씬 조작 액션은 전부 코어(보드) 능력 — 노출 안 된 대화에서는 만들지 않는다.
      * loop 는 gate.isAction 으로 이미 걸러내지만, 다른 호출부의 오용도 막는다. */
@@ -1912,7 +1912,7 @@ function toolCallToBoardActionOp(tc, gate = buildToolGate()) {
             return null;
     }
 }
-// ── Tool call → BoardEditOp 변환 ───────────────────────────────────
+// ── Tool call → SceneEditOp 변환 ───────────────────────────────────
 /**
  * AIToolChatResult → ChatResponse.
  *
@@ -1924,7 +1924,7 @@ function toolCallToBoardActionOp(tc, gate = buildToolGate()) {
 function toolResultToChatResponse(result) {
     const ops = result.toolCalls
         .flatMap(call => {
-        const r = toolCallToBoardEditOp(call);
+        const r = toolCallToSceneEditOp(call);
         if (r === null)
             return [];
         return Array.isArray(r) ? r : [r];
@@ -1940,7 +1940,7 @@ function toolResultToChatResponse(result) {
     }
     return { reply, patch, followUp: undefined };
 }
-function toolCallToBoardEditOp(tc, components = [], gate = buildToolGate()) {
+function toolCallToSceneEditOp(tc, components = [], gate = buildToolGate()) {
     const args = tc.arguments ?? {};
     /* 노출되지 않은 코어(보드 편집) 도구는 op 를 만들지 않는다 — 정의를 숨겼어도 호출은 올 수 있다. */
     if (!gate.coreOn && !gate.spec(tc.name))
@@ -1953,7 +1953,7 @@ function toolCallToBoardEditOp(tc, components = [], gate = buildToolGate()) {
         return (0, registry_js_1.dispatchStylingTool)(tc.name, args, components);
     }
     // tool-registry plugin point — 외부 등록 'write' 카테고리 dispatch.
-    // builder 결과는 BoardEditOp[] | { ops, errors? } | null 셋 중 하나.
+    // builder 결과는 SceneEditOp[] | { ops, errors? } | null 셋 중 하나.
     // (read/external 카테고리는 별도 dispatch path — agentic loop 의 executeReadTool 이 직접 처리.)
     const registrySpec = gate.spec(tc.name);
     if (registrySpec && registrySpec.kind === 'write') {
@@ -1985,17 +1985,17 @@ function toolCallToBoardEditOp(tc, components = [], gate = buildToolGate()) {
         // 모든 styling tool (setFill/setStroke/setText/setFont/setShadow/setOpacity/
         // setVisible/setMaterial/setShadowProperties/clearStyle/copyStyle) 은 registry
         // 가 처리 — 상단 isStylingTool 분기 참조
-        case 'modifyBoard': {
+        case 'modifyScene': {
             if (!args.patch || typeof args.patch !== 'object' || Array.isArray(args.patch))
                 return null;
-            return { op: 'modifyBoard', patch: args.patch };
+            return { op: 'modifyScene', patch: args.patch };
         }
         case 'replaceBoard': {
             if (!Array.isArray(args.components))
                 return null;
             return {
                 op: 'replace',
-                board: {
+                model: {
                     width: typeof args.width === 'number' ? args.width : undefined,
                     height: typeof args.height === 'number' ? args.height : undefined,
                     fillStyle: typeof args.fillStyle === 'string' ? args.fillStyle : undefined,