@things-factory/board-ai 10.1.20 → 10.1.25

package/server/service/types.ts

@@ -10,6 +10,11 @@
 import type { BoardComponent, BoardModel } from '@things-factory/board-import'
 
 /* 대화 한 줄은 도메인을 모른다 — 정의는 `@things-factory/ai-assistant` 에 있다(2026-09-10). */
+/*
+ * The edit vocabulary is not this package's. A person dragging a box produces the same
+ * operations, so they live in @operato/scene-ops with the two appliers that carry them out.
+ */
+import type { SceneActionOp, SceneEditPatch } from '@operato/scene-ops'
 import type { LLMMessage } from '@things-factory/ai-assistant'
 export type { LLMMessage }
 
@@ -121,7 +126,7 @@ import type { AIAnalysisClaim, GroundedAnalysisContract } from '@things-factory/
 export type { ToolUsage }
 
 /** Board-specific extension of the shared evidence/approval analysis boundary. */
-export interface BoardGroundedAnalysis extends GroundedAnalysisContract<any, AIAnalysisClaim, BoardEditPatch | BoardActionOp[]> {
+export interface BoardGroundedAnalysis extends GroundedAnalysisContract<any, AIAnalysisClaim, SceneEditPatch | SceneActionOp[]> {
   kind: 'board.analysis.v1'
 }
 
@@ -130,12 +135,12 @@ export interface ChatResponse {
   /** 사용자에게 보여줄 텍스트 응답 */
   reply: string
   /** 보드 변경이 있으면 patch */
-  patch?: BoardEditPatch
+  patch?: SceneEditPatch
   /**
    * Scene 조작 action (ephemeral — 모델 변경 없음 / undo 영향 없음).
    * 시간순 시퀀스로 호스트가 things-scene API 직접 실행.
    */
-  actions?: BoardActionOp[]
+  actions?: SceneActionOp[]
   /** 모호한 입력 시 명확화 질문 (patch 없음) */
   followUp?: string
   /** AI 가 응답 만드는 과정에서 호출한 도구들 (시간순). UI fold-able 박스용. */
@@ -158,119 +163,13 @@ export interface ChatResponse {
   analysis?: BoardGroundedAnalysis
 }
 
-export interface BoardEditPatch {
-  ops: BoardEditOp[]
-  /** 사용자 검수용 1-2 문장 요약 */
-  summary: string
-  /** 0..1 신뢰도 */
-  confidence: number
-}
-
-/**
- * 보드 변경 op.
- *
- * 식별자 정책 — 기존 컴포넌트 타깃팅은 `refid` (number) 만 사용.
- * things-scene 의 모든 컴포넌트는 `refid` 를 자동 발급받는다 (universal).
- * `model.id` 는 optional metadata 일 뿐 — 항상 존재하지 않으므로 targeting 에는
- * 부적합. 별개 개념이므로 BoardEditOp / tool 인자에서도 별개 식별자로 분리하지
- * 않고 refid 단일 채널로 일원화.
- *
- * 계층 — 보드는 **최상위 부모** (things-scene 의 model-layer) 이고 그 자체로 자기
- * 속성을 갖는다 (fillStyle, width, height, fitMode, translate, scale, sky, skyColor,
- * exposure, hemi/dirLight 계열, camera 계열). 자식 컴포넌트와 별개. 보드 속성 변경은
- * `modifyBoard`, 자식 변경은 `modify` (refid 기반).
- *
- * 주의 — `name` 은 보드 *엔티티* (DB row) 의 컬럼이지 scene MODEL 의 필드가 아니다.
- * things-scene 의 model-layer 가 인식 안 함. modifyBoard 로 name 을 보내면 model
- * JSON 에 죽은 필드로 박힐 뿐 렌더링/동작에 영향 없음. 보드 라벨 변경은 GraphQL
- * boardPatch (BoardPatch input 의 name 필드) 영역.
- *
- * style 변경 / 이동 / 크기 변경 등 자식 컴포넌트의 변경은 모두 `modify.patch` 안에
- * 흡수. 보드 root 속성 변경은 `modifyBoard.patch` 로.
- */
-/**
- * Phase 2 — Scene 조작 op 들. 모델 차원 (좌표 / 부모-자식 관계 / z-order) 변경이지만
- * things-scene 의 자체 API (align/distribute/group/ungroup/zorder) 가 일관된 결과를
- * 보장하므로 호스트가 직접 호출. 모델 차원 시뮬레이션 (apply-patch) 은 단순화 —
- * scene 호출 결과가 정본.
- */
-export type AlignDirection =
-  | 'left'
-  | 'right'
-  | 'center'
-  | 'top'
-  | 'middle'
-  | 'bottom'
-
-export type DistributeAxis = 'horizontal' | 'vertical'
-
-export type ZorderDirection = 'front' | 'back' | 'forward' | 'backward'
-
-/**
- * Sugar layout — `arrange` op 의 layout 종류.
- *
- * 의도: align/distribute 위에 얹는 high-level 의도 표현. AI 가 "3x2 그리드로",
- * "한 줄로", "세로로 일렬" 같은 자연어를 픽셀 노가다 없이 단일 op 로 표현.
- *
- * left/top 만 변경 — width/height 는 유지. AI 가 사이즈도 바꾸려면 별도 modify.
- *
- * 위치 계산은 호스트 (things-scene 측) 가 담당 — 각 컴포넌트의 현재 width/height 를
- * 정확히 알아야 하므로 model 차원 시뮬레이션은 SCENE_ONLY (apply-patch noop).
- */
-export type ArrangeLayout =
-  | { type: 'grid'; cols: number; gap?: number; anchor?: { left: number; top: number } }
-  | {
-      type: 'row'
-      gap?: number
-      anchor?: { left: number; top: number }
-      align?: 'start' | 'center' | 'end'
-    }
-  | {
-      type: 'column'
-      gap?: number
-      anchor?: { left: number; top: number }
-      align?: 'start' | 'center' | 'end'
-    }
-
-/**
- * C-1 — Scene 조작 action 들 (ephemeral). 모델 변경 X, 따라서 BoardEditOp 와 별개
- * 채널 (board-action-execute 이벤트). undo 히스토리 미영향, dirty flag 미영향.
- *
- * 종류:
- *   - selectComponents: scene.selected 직접 set (사용자 선택 변경)
- *   - centerToComponent: 특정 컴포넌트로 view 이동
- *   - fitToView: 보드 전체가 보이도록 fit
- *   - setSceneMode: edit / view 모드 전환
- */
-export type BoardActionOp =
-  | { action: 'selectComponents'; refids: number[] }
-  | { action: 'centerToComponent'; refid: number; animated?: boolean }
-  | { action: 'fitToView'; mode?: 'fit' | 'ratio' | 'width' | 'height' }
-  | { action: 'setSceneMode'; mode: 'edit' | 'view' }
-  /** 다중 컴포넌트 outline highlight — search/finder UX 의 "이게 모두 매칭이다" 시각화.
-   *  things-scene 의 highlightSearchResults API 위임 (2D/3D 모두 지원). */
-  | { action: 'highlightComponents'; refids: number[] }
-
-export type BoardEditOp =
-  | { op: 'add'; component: BoardComponent }
-  | { op: 'remove'; refid: number }
-  | { op: 'modify'; refid: number; patch: Partial<BoardComponent> }
-  | { op: 'modifyBoard'; patch: Partial<BoardModel> }
-  | { op: 'replace'; board: BoardModel }
-  | { op: 'align'; refids: number[]; direction: AlignDirection }
-  | { op: 'distribute'; refids: number[]; axis: DistributeAxis }
-  | { op: 'group'; refids: number[] }
-  | { op: 'ungroup'; refid: number }
-  | { op: 'zorder'; refid: number; direction: ZorderDirection }
-  | { op: 'arrange'; refids: number[]; layout: ArrangeLayout }
-
 /**
  * BoardAIAssistant — 자연어 채팅으로 보드를 다루는 단일 인터페이스.
  *
  * 사용:
  *   const ai = new DefaultBoardAIAssistant(baseClient, { scopes: ['fmsim'] })
  *   const r = await ai.chat([{ role: 'user', content: 'AGV 3대 추가' }], currentBoard)
- *   if (r.patch) currentBoard = applyBoardEditPatch(currentBoard, r.patch)
+ *   if (r.patch) currentBoard = applyScenePatch(currentBoard, r.patch)
  */
 export interface BoardAIAssistant {
   readonly id: string

package/server/service/validation/board-model-schema.test.ts

@@ -622,7 +622,7 @@ describe('실 사용자 발견 시나리오 (회귀 방지)', () => {
   })
 })
 
-describe('BoardPatchSchema — modifyBoard 의 patch 검증', () => {
+describe('BoardPatchSchema — modifyScene 의 patch 검증', () => {
   test('빈 patch 통과 (모든 필드 optional)', () => {
     expect(BoardPatchSchema.safeParse({}).success).toBe(true)
   })
@@ -650,7 +650,7 @@ describe('BoardPatchSchema — modifyBoard 의 patch 검증', () => {
   })
 
   test('★ fillStyle 안 gradientStops (stale 이름) — 거부 (FillStyleSchema strict)', () => {
-    // 본 사고의 핵심 회귀 방지 — modifyBoard 로 gradientStops 흘러들어오면 catch
+    // 본 사고의 핵심 회귀 방지 — modifyScene 로 gradientStops 흘러들어오면 catch
     const r = BoardPatchSchema.safeParse({
       fillStyle: {
         type: 'gradient',
@@ -682,7 +682,7 @@ describe('BoardPatchSchema — modifyBoard 의 patch 검증', () => {
   })
 
   test('shadow nested unknown key — 거부 (ShadowSchema strict)', () => {
-    // 다른 alias leak 시나리오 — setShadow 의 옛 이름 'blur' 가 modifyBoard 를 통해
+    // 다른 alias leak 시나리오 — setShadow 의 옛 이름 'blur' 가 modifyScene 를 통해
     // shadow 안에 박히려 할 때 (실제로는 root 에 shadow 가 없지만 검증 흐름 보존)
     const r = BoardPatchSchema.safeParse({
       shadow: { blur: 8, offsetX: 4 } as any

package/server/service/validation/board-model-schema.ts

@@ -336,7 +336,7 @@ export const ComponentSchema = ComponentBaseSchema.superRefine((component, ctx)
  *   • 식별: id, refid, type
  *
  * ⚠ `name` 은 things-scene model-layer 가 인식 안 함 — Board *엔티티* 의 컬럼이지
- * scene MODEL 의 필드가 아님. AI 가 modifyBoard 로 name 을 보내도 죽은 필드. 검증
+ * scene MODEL 의 필드가 아님. AI 가 modifyScene 로 name 을 보내도 죽은 필드. 검증
  * 시에도 제거 / 무시 정책.
  *
  * `passthrough` 인 이유 — 3D 광원/카메라/sky 등 키가 너무 많아 strict 로는 회귀 위험
@@ -384,14 +384,14 @@ export const ComponentPatchSchema = z
   .passthrough() // 위치 / 크기 / 컴포넌트 specific 통과
 
 /**
- * modifyBoard op 의 patch — 보드 root partial.
+ * modifyScene op 의 patch — 보드 root partial.
  *
  * 모든 root 필드 optional (BoardModelSchema 와 달리 width/height 도 optional).
  * passthrough 로 알려지지 않은 root 키 (3D atmosphere, sky, camera 등) 통과.
  * 다만 *알려진 nested object* (fillStyle 등) 는 strict schema 재사용 — 그 안에
  * unknown key 가 들어오면 거부 (예: fillStyle 안 gradientStops 같은 stale 이름).
  *
- * AI 가 setFill 등에서 학습한 vocabulary 를 modifyBoard 로 echo 시킬 때 stale
+ * AI 가 setFill 등에서 학습한 vocabulary 를 modifyScene 로 echo 시킬 때 stale
  * key 가 fillStyle / shadow 같은 sub-object 안에 끼면 본 schema 가 catch.
  */
 export const BoardPatchSchema = z
@@ -438,7 +438,7 @@ export function validateComponent(component: unknown): ValidationResult {
   return { valid: false, errors: formatIssues(r.error) }
 }
 
-/** modifyBoard op 의 patch 검증. 보드 root partial. */
+/** modifyScene op 의 patch 검증. 보드 root partial. */
 export function validateBoardPatch(patch: unknown): ValidationResult {
   const r = BoardPatchSchema.safeParse(patch)
   if (r.success) return { valid: true }

package/server/service/validation/tool-validation.ts

@@ -147,7 +147,7 @@ export function validateWriteToolCall(
       }
       return { valid: true }
     }
-    case 'modifyBoard': {
+    case 'modifyScene': {
       // 보드 root partial 검증 — fillStyle/shadow 같은 nested 의 strict schema 가
       // unknown key (e.g. fillStyle.gradientStops 같은 stale 이름) 를 거부.
       // 이게 마지막 방어선 — 다른 styling tool 에서 학습된 vocabulary 가 leak 되면 catch.
@@ -159,7 +159,7 @@ export function validateWriteToolCall(
         return {
           valid: false,
           errors: formatValidationErrors(v),
-          suggestion: modifyBoardSuggestion()
+          suggestion: modifySceneSuggestion()
         }
       }
       return { valid: true }
@@ -174,7 +174,7 @@ export function validateWriteToolCall(
         return {
           valid: false,
           errors: formatValidationErrors(v),
-          suggestion: modifyBoardSuggestion()
+          suggestion: modifySceneSuggestion()
         }
       }
       return { valid: true }
@@ -186,9 +186,9 @@ export function validateWriteToolCall(
   }
 }
 
-function modifyBoardSuggestion(): string {
+function modifySceneSuggestion(): string {
   return (
-    'modifyBoard 의 patch 는 things-scene 의 model-layer 가 인식하는 root key 만 사용. ' +
+    'modifyScene 의 patch 는 things-scene 의 model-layer 가 인식하는 root key 만 사용. ' +
     'fillStyle / strokeStyle / shadow 같은 nested object 의 안쪽 필드는 canonical 이름 (colorStops 등) 정확히 사용. ' +
     'rect 등 자식 컴포넌트 변경은 modifyComponentByRefid 로 분리.'
   )