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

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

@@ -0,0 +1,446 @@
+/**
+ * BoardModel zod schema — 영속 / patch 적용 boundary 에서 데이터 무결성 검증.
+ *
+ * 핵심 정책:
+ *   - things-scene 의 실제 drawer / setter 구현을 진실로 봄 (인터페이스 declaration X)
+ *   - Component schema 는 `.passthrough()` — 알려진 필드 검증 + 미지 필드 통과
+ *     (사용자 정의 / 데이터 바인딩 / 컴포넌트별 specific 속성 허용)
+ *   - 그러나 styling sub-objects (FillStyle / Shadow 등) 는 `.strict()` — unknown key
+ *     거부. stale 잔재 필드 (예: colorStops + colors 공존) 자동 발견.
+ *   - validation 실패 시 silent 누락 X — caller 가 명시적 에러 / 로그
+ *
+ * 적용 지점:
+ *   1. server `UpdateBoard` mutation 진입 → DB 영속 직전 마지막 방어선
+ *   2. server `BoardAIChat` mutation 응답 직전 — AI 가 만든 patch 의 안전성
+ *   3. (선택) client apply-patch 적용 후 — 메모리 상태 무결성
+ */
+import { z } from 'zod'
+
+// ── Color ────────────────────────────────────────────────────────
+
+/**
+ * 색상 — hex (#rgb / #rgba / #rrggbb / #rrggbbaa) / rgb / rgba / CSS named / 'transparent'.
+ * 정규식은 느슨 — 정확한 검증은 normalizeColor 가, 여기선 형식만.
+ */
+const ColorSchema = z.string().min(1).max(50)
+
+// ── FillStyle (state.fillStyle) ──────────────────────────────────
+//
+// 실제 형식 (drawer/fill.ts 검증):
+//   - solid: 색상 string 그대로
+//   - gradient: { type: 'gradient', gradientType, colorStops: [{position, color}], rotation?, opacity? }
+//   - pattern:  { type: 'pattern', image, ...옵션들 }
+//   - none: undefined / null
+
+const GradientStopSchema = z
+  .object({
+    position: z.number().min(0).max(1),
+    color: ColorSchema
+  })
+  .strict()
+
+const FillStyleGradientSchema = z
+  .object({
+    type: z.literal('gradient'),
+    gradientType: z.enum(['linear', 'radial']).optional(),
+    colorStops: z.array(GradientStopSchema).min(2),
+    rotation: z.number().optional(),
+    opacity: z.number().min(0).max(1).optional(),
+    center: z
+      .enum([
+        'center',
+        'left-top',
+        'left-bottom',
+        'right-top',
+        'right-bottom',
+        'left',
+        'right',
+        'top',
+        'bottom'
+      ])
+      .optional()
+  })
+  .strict()
+
+const FillStylePatternSchema = z
+  .object({
+    type: z.literal('pattern'),
+    image: z.union([z.string(), z.unknown()]),
+    color: ColorSchema.optional(),
+    fitPattern: z.boolean().optional(),
+    noRepeat: z.boolean().optional(),
+    align: z
+      .enum([
+        'center',
+        'left-top',
+        'left-bottom',
+        'right-top',
+        'right-bottom',
+        'left',
+        'right',
+        'top',
+        'bottom'
+      ])
+      .optional(),
+    offsetX: z.number().optional(),
+    offsetY: z.number().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    opacity: z.number().min(0).max(1).optional(),
+    guideOnly: z.boolean().optional()
+  })
+  .strict()
+
+/** 'none' type — fillStyle 제거 의도 표현 (state.fillStyle = {type:'none'} 도 허용). */
+const FillStyleNoneSchema = z.object({ type: z.literal('none') }).strict()
+
+export const FillStyleSchema = z.union([
+  ColorSchema, // solid: '#xxx'
+  FillStyleGradientSchema,
+  FillStylePatternSchema,
+  FillStyleNoneSchema,
+  z.null()
+])
+
+// ── Shadow (state.shadow) ────────────────────────────────────────
+//
+// Canonical (CSS box-shadow / Canvas API 표준): { color, offsetX, offsetY, blur }
+// Backwards-compat aliases (옛 이름, drawer 가 fallback 으로 읽음): left / top / blurSize.
+// 영속된 옛 데이터 호환을 위해 두 이름 다 schema 통과 — 새 코드는 canonical 사용.
+
+export const ShadowSchema = z
+  .object({
+    color: ColorSchema.optional(),
+    // canonical (CSS / Canvas 표준)
+    offsetX: z.number().optional(),
+    offsetY: z.number().optional(),
+    blur: z.number().min(0).optional(),
+    // legacy aliases — 옛 things-scene 데이터 호환용. 새 코드는 위 canonical 사용.
+    left: z.number().optional(),
+    top: z.number().optional(),
+    blurSize: z.number().min(0).optional()
+  })
+  .strict()
+
+// ── Material3D (state.material3d) ────────────────────────────────
+//
+// `things-scene/src/threed/material-3d.ts` 의 Material3D 인터페이스와 일치.
+
+export const Material3DSchema = z
+  .object({
+    preset: z
+      .enum(['default', 'metal', 'glass', 'plastic', 'wood', 'ceramic', 'rubber', 'custom'])
+      .optional(),
+    metalness: z.number().min(0).max(1).optional(),
+    roughness: z.number().min(0).max(1).optional(),
+    emissive: ColorSchema.optional(),
+    emissiveIntensity: z.number().min(0).max(5).optional(),
+    opacity: z.number().min(0).max(1).optional(),
+    envMapIntensity: z.number().min(0).max(3).optional(),
+    side: z.enum(['double', 'front', 'back']).optional(),
+    castShadow: z.boolean().optional(),
+    receiveShadow: z.boolean().optional()
+  })
+  .strict()
+
+// ── DataMapping (state.mappings) ─────────────────────────────────
+//
+// 데이터 바인딩 — `interfaces/data.ts` Mapping. rule / target / accessor / converter / param.
+
+export const MappingSchema = z
+  .object({
+    rule: z.string().optional(),
+    target: z.string(),
+    property: z.string().optional(),
+    accessor: z.string().optional(),
+    source: z.unknown().optional(),
+    converter: z.union([z.string(), z.unknown()]).optional(),
+    param: z.unknown().optional()
+  })
+  .passthrough() // mapping 의 자유 필드 (converter args 등) 허용
+
+// ── Component (one component in board.components) ────────────────
+//
+// 핵심 styling 필드는 명시 검증, 나머지는 passthrough — 컴포넌트별 specific 속성 자유.
+
+const LineDashSchema = z.enum([
+  'solid',
+  'round-dot',
+  'square-dot',
+  'dash',
+  'dash-dot',
+  'long-dash',
+  'long-dash-dot',
+  'long-dash-dot-dot'
+])
+
+/**
+ * 컴포넌트가 *어떤 형태든* 유효한 geometry 를 가졌는지 확인.
+ *
+ * things-scene 의 컴포넌트 type 별로 geometry 필드가 다양함 (rect 는 box,
+ * line 은 endpoints, polyline 은 vertices/path 등). type → 필드 매핑을 strict
+ * 하게 enumerate 하면 신규 type 등록 시 schema 도 동시 업데이트 필요 → forward
+ * compatibility 손해.
+ *
+ * 대신 "최소한 어떤 geometry 형식이라도 있어야 한다" 는 약한 보장 — 빈 컴포넌트
+ * (`{type:'rect'}` 만) 또는 type 에 안 맞는 geometry 구성 (`{type:'rect', cx:10, cy:20}`)
+ * 같은 명백한 오류만 차단. 실제 렌더링 정합성은 things-scene 자체가 검증.
+ */
+function componentHasValidGeometry(component: any): boolean {
+  if (!component || typeof component !== 'object') return false
+
+  // Box geometry — left/top 둘 다 있어야 (width/height 는 optional)
+  const hasBox = typeof component.left === 'number' && typeof component.top === 'number'
+
+  // Circle/ellipse geometry — cx/cy 둘 다 있어야
+  const hasCircle = typeof component.cx === 'number' && typeof component.cy === 'number'
+
+  // Line endpoints
+  const hasLineEndpoints =
+    typeof component.x1 === 'number' &&
+    typeof component.y1 === 'number' &&
+    typeof component.x2 === 'number' &&
+    typeof component.y2 === 'number'
+
+  // Path / points / vertices 계열
+  const hasPath = typeof component.path === 'string' || Array.isArray(component.path)
+  const hasPoints = Array.isArray(component.points) && component.points.length > 0
+  const hasVertices =
+    (Array.isArray(component.vertices) && component.vertices.length > 0) ||
+    (Array.isArray(component.verticles) && component.verticles.length > 0)  // legacy 오타
+
+  // line connector — startPoint / endPoint 형태 (anchor 기반 line)
+  const hasConnector =
+    component.from && typeof component.from === 'object' &&
+    component.to && typeof component.to === 'object'
+
+  return hasBox || hasCircle || hasLineEndpoints || hasPath || hasPoints || hasVertices || hasConnector
+}
+
+/** type 이 'gauge' 또는 'gauge-*' 면 value 필드 필요 (선택: min/max). */
+function isGaugeType(type: string): boolean {
+  return type === 'gauge' || type.startsWith('gauge-')
+}
+
+/** type 이 'chart' 또는 'chart-*' 면 data 필드 필요. */
+function isChartType(type: string): boolean {
+  return type === 'chart' || type.startsWith('chart-')
+}
+
+const ComponentBaseSchema = z
+  .object({
+    type: z.string().min(1),
+    refid: z.number().int().optional(), // 신규 컴포넌트 추가 시점엔 미할당 가능
+    // 위치 / 크기 — 컴포넌트 타입에 따라 다름. 본 schema 는 optional 로 두고
+    // refinement 가 *어떤 형태든* 있는지만 검사.
+    left: z.number().optional(),
+    top: z.number().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    cx: z.number().optional(),
+    cy: z.number().optional(),
+    rx: z.number().optional(),
+    ry: z.number().optional(),
+    radius: z.number().optional(),
+    x1: z.number().optional(),
+    y1: z.number().optional(),
+    x2: z.number().optional(),
+    y2: z.number().optional(),
+    rotation: z.number().optional(),
+    // styling
+    fillStyle: FillStyleSchema.optional(),
+    strokeStyle: ColorSchema.optional(), // top-level string
+    lineWidth: z.number().min(0).optional(),
+    lineDash: LineDashSchema.optional(),
+    lineCap: z.enum(['butt', 'round', 'square']).optional(),
+    lineJoin: z.enum(['miter', 'round', 'bevel']).optional(),
+    shadow: ShadowSchema.optional(),
+    material3d: Material3DSchema.optional(),
+    // text / font — top-level
+    text: z.string().optional(),
+    fontFamily: z.string().optional(),
+    fontSize: z.number().positive().optional(),
+    fontWeight: z.union([z.string(), z.number()]).optional(),
+    fontStyle: z.string().optional(),
+    fontColor: ColorSchema.optional(),
+    textAlign: z.enum(['left', 'center', 'right', 'start', 'end', 'justify']).optional(),
+    textBaseline: z
+      .enum(['top', 'middle', 'bottom', 'hanging', 'alphabetic', 'ideographic'])
+      .optional(),
+    lineHeight: z.number().positive().optional(),
+    // visibility / opacity
+    alpha: z.number().min(0).max(1).optional(),
+    hidden: z.boolean().optional(),
+    // misc — 검증 안 함
+    id: z.string().optional(),
+    class: z.string().optional(),
+    tag: z.string().optional(),
+    // 데이터 바인딩
+    mappings: z.array(MappingSchema).optional()
+  })
+  .passthrough() // 컴포넌트별 specific 속성 (vehicle wheels, gauge needle, points/path 등) 허용
+
+/**
+ * Component schema — base 위에 type-aware refinement 두 가지:
+ *
+ *   1. 모든 컴포넌트는 *어떤 형태든* 유효한 geometry 가 있어야
+ *      (left+top / cx+cy / x1y1x2y2 / path / points / vertices / from+to)
+ *   2. gauge-* type 은 value 필요, chart-* type 은 data 필요 (soft check —
+ *      일부 prefab 이 미리 채워주는 케이스도 있어 strict 거부보다 미리 잡기 목적)
+ *
+ * 이 refinement 들이 LLM 의 잘못된 geometry (rect 에 cx/cy만, line 에 left/top만)
+ * 를 영속 직전 차단.
+ */
+export const ComponentSchema = ComponentBaseSchema.superRefine((component, ctx) => {
+  if (!componentHasValidGeometry(component)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message:
+        `Component '${component.type}' has no valid geometry — provide left+top (box), cx+cy (circle/ellipse), x1+y1+x2+y2 (line), path / points / vertices, or from+to (connector).`
+    })
+  }
+
+  if (isGaugeType(component.type) && component.value === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['value'],
+      message: `Component '${component.type}' requires 'value' (current sensor reading or display number).`
+    })
+  }
+
+  if (isChartType(component.type) && component.data === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['data'],
+      message: `Component '${component.type}' requires 'data' (chart datapoints array or object).`
+    })
+  }
+})
+
+// ── BoardModel (top-level) ───────────────────────────────────────
+
+/**
+ * BoardModel — things-scene 의 model-layer (보드 root).
+ *
+ * 인식되는 root 속성 (model-layer 의 NATURE.properties + 실제 코드에서 state.* 로
+ * 참조되는 키):
+ *   • Layout: width, height, fitMode, translate, scale
+ *   • 2D 배경: fillStyle
+ *   • 3D Sky: sky, skyColor
+ *   • 3D Tone: exposure
+ *   • 3D Hemisphere: hemiSkyColor, hemiGroundColor, hemiIntensity
+ *   • 3D Directional light: dirLightEnabled, dirLightColor, dirLightIntensity,
+ *                           dirLightFollowCamera, dirLightAzimuth, dirLightElevation
+ *   • 3D Shadow: dirShadowEnabled, dirShadowMapSize, dirShadowBias
+ *   • 3D Camera: cameraX, cameraY, cameraZ, cameraAutoPlay, autoRotate, initialCameraView
+ *   • 식별: id, refid, type
+ *
+ * ⚠ `name` 은 things-scene model-layer 가 인식 안 함 — Board *엔티티* 의 컬럼이지
+ * scene MODEL 의 필드가 아님. AI 가 modifyBoard 로 name 을 보내도 죽은 필드. 검증
+ * 시에도 제거 / 무시 정책.
+ *
+ * `passthrough` 인 이유 — 3D 광원/카메라/sky 등 키가 너무 많아 strict 로는 회귀 위험
+ * 큼. 대신 패키지 외부 (operato 등) 가 임의 root 키 추가하는 걸 막지 않음.
+ */
+export const BoardModelSchema = z
+  .object({
+    width: z.number().positive(),
+    height: z.number().positive(),
+    fillStyle: FillStyleSchema.optional(), // 보드 배경
+    components: z.array(ComponentSchema).optional()
+  })
+  .passthrough() // 보드 레벨 자유 필드 (3D atmosphere / sky / camera 등)
+
+// ── Patch op schemas — modify op 의 patch 가 invalid 이면 거부 ───
+
+/**
+ * modify op 의 patch — 컴포넌트 partial. 모든 필드 optional. styling sub-object
+ * 만 strict 하게 검증해 stale key 잔존 차단.
+ */
+export const ComponentPatchSchema = z
+  .object({
+    fillStyle: FillStyleSchema.nullable().optional(),
+    strokeStyle: ColorSchema.nullable().optional(),
+    lineWidth: z.number().min(0).optional(),
+    lineDash: LineDashSchema.optional(),
+    lineCap: z.enum(['butt', 'round', 'square']).optional(),
+    lineJoin: z.enum(['miter', 'round', 'bevel']).optional(),
+    shadow: ShadowSchema.nullable().optional(),
+    material3d: Material3DSchema.nullable().optional(),
+    text: z.string().optional(),
+    fontFamily: z.string().optional(),
+    fontSize: z.number().positive().optional(),
+    fontWeight: z.union([z.string(), z.number()]).optional(),
+    fontStyle: z.string().optional(),
+    fontColor: ColorSchema.optional(),
+    textAlign: z.enum(['left', 'center', 'right', 'start', 'end', 'justify']).optional(),
+    textBaseline: z
+      .enum(['top', 'middle', 'bottom', 'hanging', 'alphabetic', 'ideographic'])
+      .optional(),
+    lineHeight: z.number().positive().optional(),
+    alpha: z.number().min(0).max(1).optional(),
+    hidden: z.boolean().optional()
+  })
+  .passthrough() // 위치 / 크기 / 컴포넌트 specific 통과
+
+/**
+ * modifyBoard 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
+ * key 가 fillStyle / shadow 같은 sub-object 안에 끼면 본 schema 가 catch.
+ */
+export const BoardPatchSchema = z
+  .object({
+    width: z.number().positive().optional(),
+    height: z.number().positive().optional(),
+    fillStyle: FillStyleSchema.nullable().optional(),
+    components: z.array(ComponentSchema).optional()
+  })
+  .passthrough() // root 의 자유 필드 (sky / exposure / hemi*/ dirLight* / camera* 등)
+
+// ── 검증 헬퍼 ────────────────────────────────────────────────────
+
+export interface ValidationResult {
+  valid: boolean
+  errors?: Array<{ path: string; message: string }>
+}
+
+function formatIssues(error: z.ZodError): Array<{ path: string; message: string }> {
+  return error.issues.map(issue => ({
+    path: issue.path.join('.'),
+    message: issue.message
+  }))
+}
+
+/** BoardModel 전체 검증. 영속 / 로드 시 사용. */
+export function validateBoardModel(model: unknown): ValidationResult {
+  const r = BoardModelSchema.safeParse(model)
+  if (r.success) return { valid: true }
+  return { valid: false, errors: formatIssues(r.error) }
+}
+
+/** modify patch 검증. AI 가 만든 patch 가 styling spec 에 맞는지. */
+export function validateComponentPatch(patch: unknown): ValidationResult {
+  const r = ComponentPatchSchema.safeParse(patch)
+  if (r.success) return { valid: true }
+  return { valid: false, errors: formatIssues(r.error) }
+}
+
+/** 한 컴포넌트 검증. addComponent 시 사용. */
+export function validateComponent(component: unknown): ValidationResult {
+  const r = ComponentSchema.safeParse(component)
+  if (r.success) return { valid: true }
+  return { valid: false, errors: formatIssues(r.error) }
+}
+
+/** modifyBoard op 의 patch 검증. 보드 root partial. */
+export function validateBoardPatch(patch: unknown): ValidationResult {
+  const r = BoardPatchSchema.safeParse(patch)
+  if (r.success) return { valid: true }
+  return { valid: false, errors: formatIssues(r.error) }
+}

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

@@ -0,0 +1,228 @@
+/**
+ * Write tool 의 사전 검증 — agentic loop 의 retry 메커니즘.
+ *
+ * 흐름:
+ *   1. LLM 이 write tool 호출
+ *   2. 본 함수가 args 검증 (styling tool 의 build* 함수 또는 schema 직접)
+ *   3. 실패 시 errors 반환 → caller 가 tool_result 에 error 메시지 담아 LLM 한테
+ *   4. LLM 다음 turn 에서 정정 후 재호출 (자기 회복)
+ *
+ * 이게 silent 데이터 손상을 막는 마지막 능동 방어선. 검증 통과한 args 만 누적
+ * → patch 로 변환되므로 깨진 데이터가 영속까지 못 감.
+ */
+import type { AIToolCall } from '@things-factory/ai-client-base'
+import {
+  validateComponentPatch,
+  validateComponent,
+  validateBoardPatch,
+  type ValidationResult
+} from './board-model-schema'
+import { buildSetFillOps } from '../styling/fill-tools'
+import { buildSetStrokeOps } from '../styling/stroke-tools'
+import { buildSetTextOps, buildSetFontOps } from '../styling/text-tools'
+import {
+  buildSetShadowOps,
+  buildSetOpacityOps,
+  buildSetVisibleOps
+} from '../styling/effect-tools'
+import {
+  buildSetMaterialOps,
+  buildSetShadowPropertiesOps
+} from '../styling/material-tools'
+import { buildClearStyleOps } from '../styling/clear-tools'
+import { buildCopyStyleOps } from '../styling/copy-tools'
+
+export interface ToolValidationResult {
+  /** 검증 통과 — 누적 진행 가능 */
+  valid: boolean
+  /** 실패 시 LLM 한테 보일 에러 메시지 (자기 회복 정보 포함) */
+  errors?: string[]
+  /** LLM 한테 정정 가이드 — 가능한 경우 어떤 형식이 맞는지 */
+  suggestion?: string
+}
+
+/**
+ * write tool 의 args 사전 검증.
+ *
+ * 정책:
+ *   - styling tool: 해당 build* 함수가 errors 반환 — 그대로 LLM 한테
+ *   - modifyComponentByRefid: ComponentPatchSchema 로 검증 (raw fallback 영역)
+ *   - addComponent: ComponentSchema 로 검증
+ *   - 그 외: 기존 dispatcher 의 자체 검증에 위임 (재시도 보장 X)
+ */
+export function validateWriteToolCall(
+  tc: AIToolCall,
+  components: ReadonlyArray<any> = []
+): ToolValidationResult {
+  const args = tc.arguments ?? {}
+
+  // Styling tool 들 — 각 build 함수가 detailed errors 반환
+  switch (tc.name) {
+    case 'setFill': {
+      const r = buildSetFillOps(args as any)
+      if (r.errors.length > 0)
+        return {
+          valid: false,
+          errors: r.errors,
+          suggestion: setFillSuggestion()
+        }
+      return { valid: true }
+    }
+    case 'setStroke': {
+      const r = buildSetStrokeOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setText': {
+      const r = buildSetTextOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setFont': {
+      const r = buildSetFontOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setShadow': {
+      const r = buildSetShadowOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setOpacity': {
+      const r = buildSetOpacityOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setVisible': {
+      const r = buildSetVisibleOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setMaterial': {
+      const r = buildSetMaterialOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'setShadowProperties': {
+      const r = buildSetShadowPropertiesOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'clearStyle': {
+      const r = buildClearStyleOps(args as any)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+    case 'copyStyle': {
+      const r = buildCopyStyleOps(args as any, components)
+      if (r.errors.length > 0) return { valid: false, errors: r.errors }
+      return { valid: true }
+    }
+
+    // raw fallback — schema 검증
+    case 'modifyComponentByRefid': {
+      if (typeof args.refid !== 'number') {
+        return { valid: false, errors: ['refid (number) is required'] }
+      }
+      if (!args.patch || typeof args.patch !== 'object') {
+        return { valid: false, errors: ['patch (object) is required'] }
+      }
+      const v = validateComponentPatch(args.patch)
+      if (!v.valid) {
+        return {
+          valid: false,
+          errors: formatValidationErrors(v),
+          suggestion: modifyPatchSuggestion()
+        }
+      }
+      return { valid: true }
+    }
+    case 'addComponent': {
+      const v = validateComponent(args)
+      if (!v.valid) {
+        return {
+          valid: false,
+          errors: formatValidationErrors(v)
+        }
+      }
+      return { valid: true }
+    }
+    case 'modifyBoard': {
+      // 보드 root partial 검증 — fillStyle/shadow 같은 nested 의 strict schema 가
+      // unknown key (e.g. fillStyle.gradientStops 같은 stale 이름) 를 거부.
+      // 이게 마지막 방어선 — 다른 styling tool 에서 학습된 vocabulary 가 leak 되면 catch.
+      if (!args.patch || typeof args.patch !== 'object' || Array.isArray(args.patch)) {
+        return { valid: false, errors: ['patch (object) is required'] }
+      }
+      const v = validateBoardPatch(args.patch)
+      if (!v.valid) {
+        return {
+          valid: false,
+          errors: formatValidationErrors(v),
+          suggestion: modifyBoardSuggestion()
+        }
+      }
+      return { valid: true }
+    }
+    case 'replaceBoard': {
+      // 보드 통째 교체 — 영속 직전 가장 강력한 검증 필요. components 까지 한 번에
+      // 검사. 자식 컴포넌트의 fillStyle.gradientStops 같은 stale 키도 즉시 catch.
+      // (BoardPatchSchema 는 component 도 array 로 통과시키되 ComponentSchema 가
+      // strict styling sub-objects 로 stale 차단.)
+      const v = validateBoardPatch(args)
+      if (!v.valid) {
+        return {
+          valid: false,
+          errors: formatValidationErrors(v),
+          suggestion: modifyBoardSuggestion()
+        }
+      }
+      return { valid: true }
+    }
+
+    // 그 외 — 기존 dispatcher 검증에 위임
+    default:
+      return { valid: true }
+  }
+}
+
+function modifyBoardSuggestion(): string {
+  return (
+    'modifyBoard 의 patch 는 things-scene 의 model-layer 가 인식하는 root key 만 사용. ' +
+    'fillStyle / strokeStyle / shadow 같은 nested object 의 안쪽 필드는 canonical 이름 (colorStops 등) 정확히 사용. ' +
+    'rect 등 자식 컴포넌트 변경은 modifyComponentByRefid 로 분리.'
+  )
+}
+
+function formatValidationErrors(v: ValidationResult): string[] {
+  if (v.valid || !v.errors) return []
+  return v.errors.map(e => `${e.path || '<root>'}: ${e.message}`)
+}
+
+/**
+ * setFill 정정 가이드 — 자주 실수하는 패턴 + 올바른 예시.
+ */
+function setFillSuggestion(): string {
+  return [
+    'Valid setFill patterns:',
+    "  - Solid: { refids:[35], mode:'solid', color:'#ff0000' }",
+    "  - Gradient: { refids:[35], mode:'gradient', gradientType:'linear', " +
+      "colorStops:[{position:0,color:'#ff0000'},{position:1,color:'#0000ff'}], rotation:90 }",
+    "  - Pattern: { refids:[35], mode:'pattern', image:'url' }",
+    "  - Partial color update: { refids:[35], color:'green' }  // mode 미지정",
+    'Notes:',
+    '  - rotation 은 degrees 로 입력 (서버가 라디안으로 변환해 fillStyle.rotation 에 저장)',
+    '  - colorStops 는 { position: 0..1, color: hex/rgb/named } 객체 배열',
+    '  - 옛 이름 (colors / stops / gradientStops) 사용 금지 — engine canonical 은 colorStops'
+  ].join('\n')
+}
+
+function modifyPatchSuggestion(): string {
+  return [
+    'modifyComponentByRefid is the raw fallback — prefer specific styling tools (setFill/setStroke/setText/setFont/setShadow/setMaterial/setOpacity/setVisible) for any styling change.',
+    'If you must use raw modify:',
+    '  - fillStyle string (solid) or {type:"gradient",gradientType,colorStops:[{position,color}]} or {type:"pattern",image,...}',
+    '  - shadow {color, offsetX, offsetY, blur}  (CSS box-shadow / Canvas 표준 이름)',
+    '  - lineDash STRING preset only (NOT number array)'
+  ].join('\n')
+}

package/things-factory.config.js

@@ -0,0 +1 @@
+export default {}