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

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

@@ -0,0 +1,778 @@
+/**
+ * BoardModel schema 검증 테스트 — 데이터 무결성 layer 의 핵심.
+ *
+ * 사용자 발견 케이스 회귀 방지:
+ *   - 발리바다 stale colorStops + colors 공존 (StyleOptions 의 dead 필드)
+ *   - shadow.offsetX (stale) — 실제는 left
+ *   - JSON 깨진 컬러 문자열
+ */
+import {
+  FillStyleSchema,
+  ShadowSchema,
+  Material3DSchema,
+  ComponentSchema,
+  ComponentPatchSchema,
+  BoardModelSchema,
+  BoardPatchSchema,
+  validateBoardModel,
+  validateBoardPatch,
+  validateComponentPatch,
+  validateComponent
+} from './board-model-schema'
+
+describe('FillStyleSchema', () => {
+  test('solid string — pass', () => {
+    expect(FillStyleSchema.safeParse('#ff0000').success).toBe(true)
+    expect(FillStyleSchema.safeParse('rgba(0,0,0,0.5)').success).toBe(true)
+    expect(FillStyleSchema.safeParse('red').success).toBe(true)
+  })
+
+  test('gradient with colorStops — pass', () => {
+    const r = FillStyleSchema.safeParse({
+      type: 'gradient',
+      gradientType: 'linear',
+      colorStops: [
+        { position: 0, color: '#ff0000' },
+        { position: 1, color: '#0000ff' }
+      ],
+      rotation: 1.5
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('gradient with stale `colors` field — fail (strict 거부)', () => {
+    const r = FillStyleSchema.safeParse({
+      type: 'gradient',
+      gradientType: 'linear',
+      colorStops: [
+        { position: 0, color: '#ff0000' },
+        { position: 1, color: '#0000ff' }
+      ],
+      colors: ['#ff0000', '#0000ff'], // ← stale 필드
+      stops: [0, 1]
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('gradient stops 미만 → 에러', () => {
+    const r = FillStyleSchema.safeParse({
+      type: 'gradient',
+      colorStops: [{ position: 0, color: '#ff0000' }] // 1개만
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('gradient stop position 범위 밖 → 에러', () => {
+    const r = FillStyleSchema.safeParse({
+      type: 'gradient',
+      colorStops: [
+        { position: 0, color: '#ff0000' },
+        { position: 1.5, color: '#0000ff' } // 1.5
+      ]
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('pattern 기본 — pass', () => {
+    expect(
+      FillStyleSchema.safeParse({
+        type: 'pattern',
+        image: 'logo.png'
+      }).success
+    ).toBe(true)
+  })
+
+  test('pattern 의 fitPattern / align / offsetX/Y — pass', () => {
+    expect(
+      FillStyleSchema.safeParse({
+        type: 'pattern',
+        image: 'p.png',
+        fitPattern: false,
+        align: 'center',
+        offsetX: 10,
+        offsetY: 5
+      }).success
+    ).toBe(true)
+  })
+
+  test('알 수 없는 type → 에러', () => {
+    const r = FillStyleSchema.safeParse({
+      type: 'unknown',
+      color: '#ff0000'
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('null fillStyle 허용 (제거 의도)', () => {
+    expect(FillStyleSchema.safeParse(null).success).toBe(true)
+  })
+})
+
+describe('ShadowSchema', () => {
+  test('정상 — left/top/blurSize', () => {
+    const r = ShadowSchema.safeParse({
+      color: '#000',
+      left: 2,
+      top: 4,
+      blurSize: 8
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('canonical offsetX/offsetY/blur — 통과 (CSS / Canvas 표준 + things-scene drawer 가 fallback 으로 읽음)', () => {
+    const r = ShadowSchema.safeParse({
+      color: '#000',
+      offsetX: 2,
+      offsetY: 4,
+      blur: 8
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('blurSize 음수 → 거부', () => {
+    expect(ShadowSchema.safeParse({ blurSize: -1 }).success).toBe(false)
+  })
+})
+
+describe('Material3DSchema', () => {
+  test('preset 만 — pass', () => {
+    expect(Material3DSchema.safeParse({ preset: 'metal' }).success).toBe(true)
+  })
+
+  test('preset + override — pass', () => {
+    const r = Material3DSchema.safeParse({
+      preset: 'glass',
+      opacity: 0.4
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('알 수 없는 preset → 거부', () => {
+    expect(Material3DSchema.safeParse({ preset: 'foobar' }).success).toBe(false)
+  })
+
+  test('metalness 범위 밖 → 거부', () => {
+    expect(Material3DSchema.safeParse({ metalness: 2 }).success).toBe(false)
+  })
+
+  test('알 수 없는 필드 — strict 거부', () => {
+    expect(
+      Material3DSchema.safeParse({
+        preset: 'metal',
+        unknownField: 'xyz' // strict 거부
+      }).success
+    ).toBe(false)
+  })
+})
+
+describe('ComponentSchema', () => {
+  test('완전한 rect — pass', () => {
+    const c = {
+      type: 'rect',
+      refid: 35,
+      left: 100,
+      top: 100,
+      width: 200,
+      height: 100,
+      fillStyle: '#ff0000',
+      strokeStyle: '#000',
+      lineWidth: 2,
+      lineDash: 'solid'
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(true)
+  })
+
+  test('미지 필드 통과 (passthrough)', () => {
+    const c = {
+      type: 'gauge',
+      refid: 1,
+      // 필수: geometry + gauge 의 value
+      left: 10,
+      top: 10,
+      width: 100,
+      height: 100,
+      value: 75,
+      // 미지 필드 — passthrough
+      gaugeColor: 'red',
+      needleStyle: 'thin'
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(true)
+  })
+
+  test('lineDash 잘못된 preset → 거부', () => {
+    const c = {
+      type: 'rect',
+      lineDash: 'wavy' // invalid
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(false)
+  })
+
+  test('shadow 의 정말 unknown 키 → 거부 (canonical/legacy 외)', () => {
+    const c = {
+      type: 'rect',
+      left: 0,
+      top: 0,
+      shadow: { dropDistance: 5 } as any  // 유효한 이름 어디에도 매칭 안 됨
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(false)
+  })
+
+  test('shadow canonical (offsetX/offsetY/blur) 통과', () => {
+    const c = {
+      type: 'rect',
+      left: 0,
+      top: 0,
+      shadow: { offsetX: 2, offsetY: 4, blur: 8, color: '#000' }
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(true)
+  })
+
+  test('shadow legacy (left/top/blurSize) 도 통과 — 옛 데이터 호환', () => {
+    const c = {
+      type: 'rect',
+      left: 0,
+      top: 0,
+      shadow: { left: 2, top: 4, blurSize: 8, color: '#000' }
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(true)
+  })
+
+  test('JSON 깨진 색상 (non-string) → 거부', () => {
+    const c = {
+      type: 'rect',
+      fillStyle: 12345 // 숫자
+    }
+    expect(ComponentSchema.safeParse(c).success).toBe(false)
+  })
+})
+
+describe('validateComponentPatch — modify op', () => {
+  test('정상 — pass', () => {
+    const r = validateComponentPatch({
+      fillStyle: '#ff0000',
+      lineWidth: 2
+    })
+    expect(r.valid).toBe(true)
+  })
+
+  test('null fillStyle 허용 (clear 의도)', () => {
+    const r = validateComponentPatch({ fillStyle: null })
+    expect(r.valid).toBe(true)
+  })
+
+  test('shadow canonical 필드 (offsetX/offsetY/blur) → 통과', () => {
+    const r = validateComponentPatch({
+      shadow: { offsetX: 5, blur: 10 }
+    })
+    expect(r.valid).toBe(true)
+  })
+
+  test('shadow 진짜 unknown 키 (canonical/legacy 외) → 실패', () => {
+    const r = validateComponentPatch({
+      shadow: { madeUpKey: 5 } as any
+    })
+    expect(r.valid).toBe(false)
+  })
+
+  test('lineDash number array → 실패 (string preset 만 허용)', () => {
+    const r = validateComponentPatch({ lineDash: [4, 4] as any })
+    expect(r.valid).toBe(false)
+  })
+})
+
+describe('ComponentSchema — geometry 검증 (refinement)', () => {
+  test('rect with box geometry (left/top/width/height) — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'rect',
+      left: 10,
+      top: 10,
+      width: 100,
+      height: 50
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('rect with only left/top (width/height 생략) — 통과', () => {
+    // width/height 는 optional — left/top 만 있으면 box 인정
+    const r = ComponentSchema.safeParse({ type: 'rect', left: 0, top: 0 })
+    expect(r.success).toBe(true)
+  })
+
+  test('rect 가 cx/cy 만 — 거부 (잘못된 geometry 매칭)', () => {
+    const r = ComponentSchema.safeParse({ type: 'rect', cx: 50, cy: 50 })
+    // cx/cy 는 ellipse 형 geometry — rect 가 cx/cy 만 갖는 건 valid pattern 이 아님
+    // 다만 cx/cy 자체는 valid geometry 시그니처 → 통과. type 미스매치는 things-scene 책임.
+    // (본 schema 는 "어떤 형태든 geometry 가 있는가" 만 검증)
+    expect(r.success).toBe(true)
+  })
+
+  test('geometry 전혀 없음 — 거부', () => {
+    const r = ComponentSchema.safeParse({ type: 'rect' })
+    expect(r.success).toBe(false)
+    if (!r.success) {
+      expect(r.error.issues[0].message).toMatch(/no valid geometry/i)
+    }
+  })
+
+  test('빈 객체에 type 만 — 거부', () => {
+    const r = ComponentSchema.safeParse({ type: 'circle' })
+    expect(r.success).toBe(false)
+  })
+
+  test('left 만 있고 top 없음 — 거부 (box 짝 부족)', () => {
+    const r = ComponentSchema.safeParse({ type: 'rect', left: 10 })
+    expect(r.success).toBe(false)
+  })
+
+  test('cx 만 있고 cy 없음 — 거부 (circle 짝 부족)', () => {
+    const r = ComponentSchema.safeParse({ type: 'ellipse', cx: 50 })
+    expect(r.success).toBe(false)
+  })
+
+  test('circle/ellipse with cx/cy — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'ellipse',
+      cx: 100,
+      cy: 100,
+      rx: 30,
+      ry: 20
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('line with x1/y1/x2/y2 — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'line',
+      x1: 0,
+      y1: 0,
+      x2: 100,
+      y2: 100
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('line with x1/y1 만 (endpoints 짝 부족) — 거부', () => {
+    const r = ComponentSchema.safeParse({ type: 'line', x1: 0, y1: 0 })
+    expect(r.success).toBe(false)
+  })
+
+  test('polyline with points — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'polyline',
+      points: [[0, 0], [50, 50], [100, 0]]
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('polyline with empty points — 거부', () => {
+    const r = ComponentSchema.safeParse({ type: 'polyline', points: [] })
+    expect(r.success).toBe(false)
+  })
+
+  test('polygon with path string — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'polygon',
+      path: 'M0 0 L100 100 L50 50 Z'
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('vertices array — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'curve',
+      vertices: [[0, 0], [50, 50], [100, 0]]
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('legacy verticles 오타 — 통과 (호환성)', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'curve',
+      verticles: [[0, 0], [50, 50]]
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('connector (from + to) — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'ortholine',
+      from: { component: 1, anchor: 'RIGHT' },
+      to: { component: 2, anchor: 'LEFT' }
+    })
+    expect(r.success).toBe(true)
+  })
+})
+
+describe('ComponentSchema — gauge type 의 value 검증', () => {
+  test('gauge with value — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'gauge',
+      left: 0,
+      top: 0,
+      value: 75
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('gauge without value — 거부', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'gauge',
+      left: 0,
+      top: 0
+    })
+    expect(r.success).toBe(false)
+    if (!r.success) {
+      expect(r.error.issues.some(i => i.message.includes('value'))).toBe(true)
+    }
+  })
+
+  test('gauge-radial-* (variant) without value — 거부', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'gauge-radial-blue',
+      left: 0,
+      top: 0
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('gauge-* with value 0 — 통과 (0 도 유효한 value)', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'gauge-linear',
+      left: 0,
+      top: 0,
+      value: 0
+    })
+    expect(r.success).toBe(true)
+  })
+})
+
+describe('ComponentSchema — chart type 의 data 검증', () => {
+  test('chart with data — 통과', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'chart',
+      left: 0,
+      top: 0,
+      width: 200,
+      height: 100,
+      data: [1, 2, 3]
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('chart without data — 거부', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'chart',
+      left: 0,
+      top: 0
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('chart-bar variant without data — 거부', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'chart-bar',
+      left: 0,
+      top: 0
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('chart with empty data array — 통과 (refinement 는 존재만 확인)', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'chart',
+      left: 0,
+      top: 0,
+      data: []
+    })
+    expect(r.success).toBe(true)
+  })
+})
+
+describe('ComponentSchema — 비-gauge / 비-chart type 은 영향 없음', () => {
+  test('rect 는 value/data 안 봐도 통과', () => {
+    expect(
+      ComponentSchema.safeParse({ type: 'rect', left: 0, top: 0 }).success
+    ).toBe(true)
+  })
+
+  test('text 는 text 가 없어도 통과 (현재 정책 — content 검증 없음)', () => {
+    expect(
+      ComponentSchema.safeParse({ type: 'text', left: 0, top: 0 }).success
+    ).toBe(true)
+  })
+
+  test('image 는 src 가 없어도 통과 (현재 정책)', () => {
+    expect(
+      ComponentSchema.safeParse({ type: 'image', left: 0, top: 0 }).success
+    ).toBe(true)
+  })
+})
+
+describe('ComponentSchema — 실 사용자 시나리오 (회귀 방지)', () => {
+  test('rect 에 cx/cy 만 보내는 LLM 환각 — geometry 자체는 valid 패턴', () => {
+    // 이 케이스는 geometry refinement 통과 (cx/cy 가 valid 시그니처).
+    // type/geometry 미스매치는 things-scene 책임. 우리 schema 는 *완전 누락만* 차단.
+    const r = ComponentSchema.safeParse({
+      type: 'rect',
+      cx: 50,
+      cy: 50
+    })
+    expect(r.success).toBe(true)
+  })
+
+  test('AI 가 geometry 빠뜨림 — 차단', () => {
+    const r = ComponentSchema.safeParse({
+      type: 'rect',
+      fillStyle: '#ff0000',
+      strokeStyle: '#000'
+    })
+    expect(r.success).toBe(false)
+    expect(validateComponent({
+      type: 'rect',
+      fillStyle: '#ff0000'
+    }).errors?.[0].message).toMatch(/no valid geometry/i)
+  })
+
+  test('AI 가 gauge 만들면서 value 빠뜨림 — 차단', () => {
+    const r = validateComponent({
+      type: 'gauge-radial-green',
+      left: 100,
+      top: 100,
+      width: 200,
+      height: 200,
+      min: 0,
+      max: 100
+      // value 누락
+    })
+    expect(r.valid).toBe(false)
+    expect(r.errors?.[0].path).toBe('value')
+  })
+})
+
+describe('BoardModelSchema — top-level', () => {
+  test('정상 보드', () => {
+    const m = {
+      width: 1920,
+      height: 1080,
+      fillStyle: '#0a1929',
+      components: [
+        { type: 'rect', refid: 1, left: 10, top: 10, width: 50, height: 50, fillStyle: '#ff0000' },
+        { type: 'circle', refid: 2, cx: 100, cy: 100, rx: 30, ry: 30 }
+      ]
+    }
+    expect(validateBoardModel(m).valid).toBe(true)
+  })
+
+  test('width/height 누락 — 거부', () => {
+    expect(validateBoardModel({ components: [] }).valid).toBe(false)
+  })
+
+  test('width 음수 — 거부', () => {
+    expect(validateBoardModel({ width: -1, height: 100 }).valid).toBe(false)
+  })
+
+  test('component 의 styling 잘못 — 거부 + 상세 에러', () => {
+    const r = validateBoardModel({
+      width: 100,
+      height: 100,
+      components: [
+        {
+          type: 'rect',
+          left: 0,
+          top: 0,
+          shadow: { madeUpKey: 2 } as any  // canonical/legacy 어디에도 안 매칭
+        }
+      ]
+    })
+    expect(r.valid).toBe(false)
+    expect(r.errors).toBeDefined()
+    // path 에 components.0.shadow 가 포함되어야 (어디서 깨졌는지 정확히)
+    const paths = r.errors!.map(e => e.path)
+    expect(paths.some(p => p.includes('shadow'))).toBe(true)
+  })
+})
+
+describe('실 사용자 발견 시나리오 (회귀 방지)', () => {
+  test('발리바다 — colors/stops 잔재 차단', () => {
+    const r = validateComponentPatch({
+      fillStyle: {
+        type: 'gradient',
+        gradientType: 'linear',
+        colorStops: [
+          { position: 0, color: '#000000' },
+          { position: 1, color: '#ffffff' }
+        ],
+        // 이 두 줄이 stale (이전 버그) — strict 거부해야
+        colors: ['#00bfa5', '#00e5ff', '#0288d1'],
+        stops: [0, 0.5, 1]
+      } as any
+    })
+    expect(r.valid).toBe(false)
+  })
+
+  test('ortholine top-level lineWidth + strokeStyle string — pass', () => {
+    expect(
+      validateComponentPatch({
+        strokeStyle: '#ffffff',
+        lineWidth: 4,
+        lineDash: 'solid',
+        lineCap: 'butt'
+      }).valid
+    ).toBe(true)
+  })
+})
+
+describe('BoardPatchSchema — modifyBoard 의 patch 검증', () => {
+  test('빈 patch 통과 (모든 필드 optional)', () => {
+    expect(BoardPatchSchema.safeParse({}).success).toBe(true)
+  })
+
+  test('width 만 통과', () => {
+    expect(BoardPatchSchema.safeParse({ width: 1920 }).success).toBe(true)
+  })
+
+  test('fillStyle string 통과', () => {
+    expect(BoardPatchSchema.safeParse({ fillStyle: '#0a1929' }).success).toBe(true)
+  })
+
+  test('fillStyle 정상 gradient 통과', () => {
+    expect(
+      BoardPatchSchema.safeParse({
+        fillStyle: {
+          type: 'gradient',
+          colorStops: [
+            { position: 0, color: '#000' },
+            { position: 1, color: '#fff' }
+          ]
+        }
+      }).success
+    ).toBe(true)
+  })
+
+  test('★ fillStyle 안 gradientStops (stale 이름) — 거부 (FillStyleSchema strict)', () => {
+    // 본 사고의 핵심 회귀 방지 — modifyBoard 로 gradientStops 흘러들어오면 catch
+    const r = BoardPatchSchema.safeParse({
+      fillStyle: {
+        type: 'gradient',
+        gradientStops: [
+          { position: 0, color: '#000' },
+          { position: 1, color: '#fff' }
+        ]
+      }
+    })
+    expect(r.success).toBe(false)
+  })
+
+  test('3D atmosphere root keys (sky/exposure/dirLight*) — passthrough 통과', () => {
+    expect(
+      BoardPatchSchema.safeParse({
+        sky: 'studio',
+        exposure: 1.2,
+        hemiSkyColor: '#fffbf0',
+        dirLightAzimuth: 135,
+        dirLightElevation: 65
+      }).success
+    ).toBe(true)
+  })
+
+  test('알려지지 않은 root key — passthrough (forward compat)', () => {
+    expect(
+      BoardPatchSchema.safeParse({ futureFeatureFlag: true }).success
+    ).toBe(true)
+  })
+
+  test('shadow nested unknown key — 거부 (ShadowSchema strict)', () => {
+    // 다른 alias leak 시나리오 — setShadow 의 옛 이름 'blur' 가 modifyBoard 를 통해
+    // shadow 안에 박히려 할 때 (실제로는 root 에 shadow 가 없지만 검증 흐름 보존)
+    const r = BoardPatchSchema.safeParse({
+      shadow: { blur: 8, offsetX: 4 } as any
+    } as any)
+    // BoardPatchSchema 에 shadow 가 명시 없어 passthrough 통과 — root level shadow 는
+    // 보드의 정식 root key 가 아님. (만약 shadow 가 root key 였다면 strict 검증 받음)
+    // 본 schema 의 보호 영역은 fillStyle 등 *명시된* nested 만
+    expect(r.success).toBe(true)
+  })
+
+  test('fillStyle pattern 의 unknown key — 거부', () => {
+    const r = BoardPatchSchema.safeParse({
+      fillStyle: {
+        type: 'pattern',
+        image: 'x.png',
+        unknownPatternProp: 'oops' as any
+      }
+    } as any)
+    expect(r.success).toBe(false)
+  })
+
+  test('validateBoardPatch helper — 정상', () => {
+    expect(validateBoardPatch({ fillStyle: '#000' }).valid).toBe(true)
+  })
+
+  test('validateBoardPatch helper — gradientStops 거부 + 에러 path 표시', () => {
+    const r = validateBoardPatch({
+      fillStyle: {
+        type: 'gradient',
+        gradientStops: [
+          { position: 0, color: '#000' },
+          { position: 1, color: '#fff' }
+        ]
+      }
+    } as any)
+    expect(r.valid).toBe(false)
+    expect(r.errors).toBeDefined()
+    expect(r.errors!.some(e => e.path.includes('fillStyle'))).toBe(true)
+  })
+
+  test('components 배열 — 통과 (검증 후 자식 element 별 검증)', () => {
+    expect(
+      validateBoardPatch({
+        components: [{ type: 'rect', left: 0, top: 0 }]
+      }).valid
+    ).toBe(true)
+  })
+
+  test('★ replaceBoard 시나리오 — 자식 컴포넌트의 fillStyle.gradientStops 도 catch', () => {
+    // 사용자 발견 시나리오 — replaceBoard 가 자식 안 stale 키 들고 들어옴
+    const r = validateBoardPatch({
+      width: 1600,
+      height: 1200,
+      fillStyle: '#fff',
+      components: [
+        {
+          type: 'rect',
+          left: 0,
+          top: 0,
+          fillStyle: {
+            type: 'gradient',
+            gradientStops: [
+              { position: 0, color: '#000' },
+              { position: 1, color: '#fff' }
+            ]
+          }
+        }
+      ]
+    } as any)
+    expect(r.valid).toBe(false)
+  })
+
+  test('★ root fillStyle 의 gradientStops — 본 사고 직접 케이스', () => {
+    // 사용자 JSON 시나리오 — 보드 root fillStyle 안 gradientStops
+    const r = validateBoardPatch({
+      width: 1600,
+      height: 1200,
+      fillStyle: {
+        type: 'gradient',
+        gradientStops: [
+          { position: 0, color: '#002395' },
+          { position: 0.5, color: '#fff' },
+          { position: 1, color: '#ed2939' }
+        ],
+        rotation: 0,
+        gradientType: 'linear'
+      } as any
+    })
+    expect(r.valid).toBe(false)
+    // formatIssues 가 union error 의 nested 정보를 collapse 시킴 — 최소 fillStyle path 노출
+    expect(r.errors!.some(e => e.path.includes('fillStyle'))).toBe(true)
+  })
+})