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

package/server/service/styling/material-tools.test.ts

@@ -0,0 +1,294 @@
+/**
+ * material-tools — setMaterial / setShadowProperties (3D PBR 재질).
+ *
+ * preset 만 줘도 변경 가능 (resolveMaterial3d 가 default 위 override 적용).
+ * 출력 patch.material3d 는 things-scene 의 Material3D 와 1:1 매핑.
+ */
+import { buildSetMaterialOps, buildSetShadowPropertiesOps } from './material-tools'
+
+describe('buildSetMaterialOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetMaterialOps({ refids: [], preset: 'metal' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildSetMaterialOps({
+      refids: [1, NaN, 'x' as any, 2],
+      preset: 'metal'
+    })
+    expect(r.ops).toHaveLength(2)
+  })
+
+  test('아무 인자도 없으면 에러', () => {
+    const r = buildSetMaterialOps({ refids: [1] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/No material changes/)
+  })
+
+  test('알 수 없는 preset → 에러 + 유효 목록 제시', () => {
+    const r = buildSetMaterialOps({ refids: [1], preset: 'silk' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown preset/)
+    expect(r.errors[0]).toMatch(/metal/)
+  })
+
+  test('알 수 없는 side → 에러', () => {
+    const r = buildSetMaterialOps({ refids: [1], side: 'inside' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown side/)
+  })
+
+  test('잘못된 emissive 색상 → 에러', () => {
+    const r = buildSetMaterialOps({
+      refids: [1],
+      preset: 'metal',
+      emissive: 'glowy' as any
+    })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid/)
+  })
+})
+
+describe('buildSetMaterialOps — 범위 검증', () => {
+  test.each([
+    ['metalness', { metalness: 1.5 }],
+    ['metalness', { metalness: -0.1 }],
+    ['roughness', { roughness: 1.5 }],
+    ['roughness', { roughness: -0.1 }],
+    ['opacity', { opacity: 1.5 }],
+    ['opacity', { opacity: -0.1 }],
+    ['emissiveIntensity', { emissiveIntensity: 5.5 }],
+    ['emissiveIntensity', { emissiveIntensity: -0.1 }],
+    ['envMapIntensity', { envMapIntensity: 3.5 }],
+    ['envMapIntensity', { envMapIntensity: -0.1 }]
+  ])('%s 범위 밖 (%o) → 에러', (field, override) => {
+    const r = buildSetMaterialOps({ refids: [1], ...(override as any) })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(new RegExp(field))
+  })
+
+  test('경계값 0 / 1 / 5 / 3 통과', () => {
+    expect(buildSetMaterialOps({ refids: [1], metalness: 0 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], metalness: 1 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], roughness: 0 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], roughness: 1 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], opacity: 0 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], opacity: 1 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], emissiveIntensity: 0 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], emissiveIntensity: 5 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], envMapIntensity: 0 }).ops).toHaveLength(1)
+    expect(buildSetMaterialOps({ refids: [1], envMapIntensity: 3 }).ops).toHaveLength(1)
+  })
+})
+
+describe('buildSetMaterialOps — preset 8종', () => {
+  test.each(['default', 'metal', 'glass', 'plastic', 'wood', 'ceramic', 'rubber', 'custom'])(
+    'preset %s → patch.material3d.preset',
+    preset => {
+      const r = buildSetMaterialOps({ refids: [1], preset: preset as any })
+      expect(r.ops).toHaveLength(1)
+      expect((r.ops[0] as any).patch.material3d).toEqual({ preset })
+    }
+  )
+})
+
+describe('buildSetMaterialOps — preset + 속성 override', () => {
+  test('preset metal + metalness/roughness override', () => {
+    const r = buildSetMaterialOps({
+      refids: [1],
+      preset: 'metal',
+      metalness: 0.9,
+      roughness: 0.2
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'metal',
+      metalness: 0.9,
+      roughness: 0.2
+    })
+  })
+
+  test('preset 없이 속성만 — partial update', () => {
+    // resolveMaterial3d 가 default 위 override 적용. preset 없어도 OK.
+    const r = buildSetMaterialOps({ refids: [1], roughness: 0.5 })
+    expect((r.ops[0] as any).patch.material3d).toEqual({ roughness: 0.5 })
+  })
+
+  test('emissive 색상 정규화', () => {
+    const r = buildSetMaterialOps({
+      refids: [1],
+      preset: 'plastic',
+      emissive: 'red',
+      emissiveIntensity: 1.5
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'plastic',
+      emissive: '#ff0000',
+      emissiveIntensity: 1.5
+    })
+  })
+
+  test('side 통과 — double/front/back', () => {
+    expect(
+      (buildSetMaterialOps({ refids: [1], side: 'double' }).ops[0] as any).patch.material3d
+    ).toEqual({ side: 'double' })
+    expect(
+      (buildSetMaterialOps({ refids: [1], side: 'front' }).ops[0] as any).patch.material3d
+    ).toEqual({ side: 'front' })
+    expect(
+      (buildSetMaterialOps({ refids: [1], side: 'back' }).ops[0] as any).patch.material3d
+    ).toEqual({ side: 'back' })
+  })
+
+  test('opacity (3D-only) 와 envMapIntensity 통과', () => {
+    const r = buildSetMaterialOps({
+      refids: [1],
+      preset: 'glass',
+      opacity: 0.4,
+      envMapIntensity: 2
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'glass',
+      opacity: 0.4,
+      envMapIntensity: 2
+    })
+  })
+
+  test('전체 필드 한 번에', () => {
+    const r = buildSetMaterialOps({
+      refids: [1],
+      preset: 'custom',
+      metalness: 0.5,
+      roughness: 0.3,
+      emissive: 'navy',
+      emissiveIntensity: 2,
+      opacity: 0.8,
+      envMapIntensity: 1.5,
+      side: 'double'
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'custom',
+      metalness: 0.5,
+      roughness: 0.3,
+      emissive: '#000080',
+      emissiveIntensity: 2,
+      opacity: 0.8,
+      envMapIntensity: 1.5,
+      side: 'double'
+    })
+  })
+})
+
+describe('buildSetMaterialOps — multi-target', () => {
+  test('동일 material 가 여러 refid 에 분배', () => {
+    const r = buildSetMaterialOps({
+      refids: [10, 20, 30],
+      preset: 'metal'
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops.every(o => (o as any).patch.material3d.preset === 'metal')).toBe(true)
+  })
+})
+
+describe('buildSetShadowPropertiesOps — 3D 그림자 동작', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetShadowPropertiesOps({ refids: [], castShadow: true })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('두 인자 모두 없으면 에러', () => {
+    const r = buildSetShadowPropertiesOps({ refids: [1] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Specify castShadow/)
+  })
+
+  test('castShadow 만', () => {
+    const r = buildSetShadowPropertiesOps({ refids: [1], castShadow: true })
+    expect((r.ops[0] as any).patch.material3d).toEqual({ castShadow: true })
+  })
+
+  test('receiveShadow 만', () => {
+    const r = buildSetShadowPropertiesOps({ refids: [1], receiveShadow: false })
+    expect((r.ops[0] as any).patch.material3d).toEqual({ receiveShadow: false })
+  })
+
+  test('둘 다', () => {
+    const r = buildSetShadowPropertiesOps({
+      refids: [1],
+      castShadow: true,
+      receiveShadow: true
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      castShadow: true,
+      receiveShadow: true
+    })
+  })
+
+  test('multi-target', () => {
+    const r = buildSetShadowPropertiesOps({
+      refids: [1, 2, 3],
+      castShadow: false
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(
+      r.ops.every(o => (o as any).patch.material3d.castShadow === false)
+    ).toBe(true)
+  })
+})
+
+describe('material-tools — 시나리오', () => {
+  test('금속 외관 — preset metal + 거울처럼 매끄럽게', () => {
+    const r = buildSetMaterialOps({
+      refids: [1, 2],
+      preset: 'metal',
+      metalness: 0.95,
+      roughness: 0.1
+    })
+    expect(r.ops).toHaveLength(2)
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'metal',
+      metalness: 0.95,
+      roughness: 0.1
+    })
+  })
+
+  test('네온 발광 — emissive 강조', () => {
+    const r = buildSetMaterialOps({
+      refids: [42],
+      preset: 'plastic',
+      emissive: '#00ffff',
+      emissiveIntensity: 3
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'plastic',
+      emissive: '#00ffff',
+      emissiveIntensity: 3
+    })
+  })
+
+  test('투명 유리', () => {
+    const r = buildSetMaterialOps({
+      refids: [1],
+      preset: 'glass',
+      opacity: 0.3
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      preset: 'glass',
+      opacity: 0.3
+    })
+  })
+
+  test('대형 컨테이너 — 그림자 받기만', () => {
+    const r = buildSetShadowPropertiesOps({
+      refids: [1],
+      castShadow: false,
+      receiveShadow: true
+    })
+    expect((r.ops[0] as any).patch.material3d).toEqual({
+      castShadow: false,
+      receiveShadow: true
+    })
+  })
+})

package/server/service/styling/material-tools.ts

@@ -0,0 +1,114 @@
+/**
+ * setMaterial / setShadowProperties — 3D PBR 재질 + 그림자 동작.
+ *
+ * Material3D (`things-scene/src/threed/material-3d.ts`) 와 1:1 매핑.
+ * preset 만 줘도 변경 가능 (resolveMaterial3d 가 default 위 override 적용).
+ */
+import type { BoardEditOp } from '../types'
+import { normalizeColor, validateColor } from './color-utils'
+
+const MATERIAL_PRESETS = ['default', 'metal', 'glass', 'plastic', 'wood', 'ceramic', 'rubber', 'custom'] as const
+const SIDE_VALUES = ['double', 'front', 'back'] as const
+
+export interface SetMaterialInput {
+  refids: number[]
+  preset?: typeof MATERIAL_PRESETS[number]
+  metalness?: number       // 0..1
+  roughness?: number       // 0..1
+  emissive?: string
+  emissiveIntensity?: number  // 0..5
+  opacity?: number         // 0..1 (3D-only)
+  envMapIntensity?: number // 0..3
+  side?: typeof SIDE_VALUES[number]
+}
+
+export interface SetShadowPropertiesInput {
+  refids: number[]
+  castShadow?: boolean
+  receiveShadow?: boolean
+}
+
+export interface OpsResult {
+  ops: BoardEditOp[]
+  errors: string[]
+}
+
+export function buildSetMaterialOps(input: SetMaterialInput): OpsResult {
+  if (!Array.isArray(input.refids) || input.refids.length === 0) {
+    return { ops: [], errors: ['refids must be a non-empty array'] }
+  }
+  const refids = input.refids.filter(n => typeof n === 'number' && Number.isFinite(n))
+  if (refids.length === 0) return { ops: [], errors: ['No valid numeric refids'] }
+
+  const noOp = !(
+    input.preset ||
+    input.metalness !== undefined ||
+    input.roughness !== undefined ||
+    input.emissive !== undefined ||
+    input.emissiveIntensity !== undefined ||
+    input.opacity !== undefined ||
+    input.envMapIntensity !== undefined ||
+    input.side !== undefined
+  )
+  if (noOp) return { ops: [], errors: ['No material changes specified'] }
+
+  if (input.preset && !MATERIAL_PRESETS.includes(input.preset)) {
+    return {
+      ops: [],
+      errors: [`Unknown preset: '${input.preset}'. Valid: ${MATERIAL_PRESETS.join('/')}`]
+    }
+  }
+  if (input.metalness !== undefined && (input.metalness < 0 || input.metalness > 1)) {
+    return { ops: [], errors: [`metalness out of [0,1]: ${input.metalness}`] }
+  }
+  if (input.roughness !== undefined && (input.roughness < 0 || input.roughness > 1)) {
+    return { ops: [], errors: [`roughness out of [0,1]: ${input.roughness}`] }
+  }
+  if (input.opacity !== undefined && (input.opacity < 0 || input.opacity > 1)) {
+    return { ops: [], errors: [`opacity out of [0,1]: ${input.opacity}`] }
+  }
+  if (input.emissiveIntensity !== undefined && (input.emissiveIntensity < 0 || input.emissiveIntensity > 5)) {
+    return { ops: [], errors: [`emissiveIntensity out of [0,5]: ${input.emissiveIntensity}`] }
+  }
+  if (input.envMapIntensity !== undefined && (input.envMapIntensity < 0 || input.envMapIntensity > 3)) {
+    return { ops: [], errors: [`envMapIntensity out of [0,3]: ${input.envMapIntensity}`] }
+  }
+  if (input.emissive !== undefined) {
+    const v = validateColor(input.emissive)
+    if (!v.valid) return { ops: [], errors: [v.error ?? 'Invalid emissive color'] }
+  }
+  if (input.side && !SIDE_VALUES.includes(input.side)) {
+    return { ops: [], errors: [`Unknown side: '${input.side}'. Valid: ${SIDE_VALUES.join('/')}`] }
+  }
+
+  const m: any = {}
+  if (input.preset) m.preset = input.preset
+  if (input.metalness !== undefined) m.metalness = input.metalness
+  if (input.roughness !== undefined) m.roughness = input.roughness
+  if (input.emissive !== undefined) m.emissive = normalizeColor(input.emissive)
+  if (input.emissiveIntensity !== undefined) m.emissiveIntensity = input.emissiveIntensity
+  if (input.opacity !== undefined) m.opacity = input.opacity
+  if (input.envMapIntensity !== undefined) m.envMapIntensity = input.envMapIntensity
+  if (input.side) m.side = input.side
+
+  const patch = { material3d: m }
+  return { ops: refids.map(refid => ({ op: 'modify', refid, patch })), errors: [] }
+}
+
+export function buildSetShadowPropertiesOps(input: SetShadowPropertiesInput): OpsResult {
+  if (!Array.isArray(input.refids) || input.refids.length === 0) {
+    return { ops: [], errors: ['refids must be a non-empty array'] }
+  }
+  const refids = input.refids.filter(n => typeof n === 'number' && Number.isFinite(n))
+  if (refids.length === 0) return { ops: [], errors: ['No valid numeric refids'] }
+
+  const noOp = input.castShadow === undefined && input.receiveShadow === undefined
+  if (noOp) return { ops: [], errors: ['Specify castShadow and/or receiveShadow'] }
+
+  const m: any = {}
+  if (input.castShadow !== undefined) m.castShadow = input.castShadow
+  if (input.receiveShadow !== undefined) m.receiveShadow = input.receiveShadow
+
+  const patch = { material3d: m }
+  return { ops: refids.map(refid => ({ op: 'modify', refid, patch })), errors: [] }
+}

package/server/service/styling/read-tools.test.ts

@@ -0,0 +1,78 @@
+/**
+ * read-tools — getComponentStyle / buildComponentStyleSummary.
+ */
+import { buildComponentStyleSummary } from './read-tools'
+
+describe('buildComponentStyleSummary', () => {
+  test('full summary — 모든 aspect', () => {
+    const c = {
+      refid: 35,
+      type: 'rect',
+      fillStyle: { type: 'solid', color: '#ff0000' },
+      strokeStyle: { color: '#000', width: 2 },
+      shadow: { blur: 4, color: 'rgba(0,0,0,0.3)' },
+      material3d: { preset: 'metal' },
+      fontFamily: 'Inter',
+      fontSize: 14,
+      alpha: 0.8,
+      hidden: false,
+      text: 'Hello'
+    }
+    const s = buildComponentStyleSummary(c)
+    expect(s.refid).toBe(35)
+    expect(s.fillStyle).toEqual({ type: 'solid', color: '#ff0000' })
+    expect(s.strokeStyle).toEqual({ color: '#000', width: 2 })
+    expect(s.shadow).toEqual({ blur: 4, color: 'rgba(0,0,0,0.3)' })
+    expect(s.material3d).toEqual({ preset: 'metal' })
+    expect(s.alpha).toBe(0.8)
+    expect(s.hidden).toBe(false)
+    expect(s.text).toBe('Hello')
+    expect(s.font).toEqual({ fontFamily: 'Inter', fontSize: 14 })
+  })
+
+  test('aspects 부분 — fill 만', () => {
+    const c = {
+      refid: 1,
+      fillStyle: { type: 'solid', color: '#abc' },
+      strokeStyle: { width: 1 },
+      alpha: 0.5
+    }
+    const s = buildComponentStyleSummary(c, ['fill'])
+    expect(s.fillStyle).toBeDefined()
+    expect(s.strokeStyle).toBeUndefined()
+    expect(s.alpha).toBeUndefined()
+  })
+
+  test('aspects 다중 부분', () => {
+    const c = {
+      refid: 1,
+      fillStyle: { color: 'red' },
+      shadow: { blur: 2 },
+      hidden: true,
+      alpha: 0.7
+    }
+    const s = buildComponentStyleSummary(c, ['fill', 'shadow', 'visibility'])
+    expect(s.fillStyle).toBeDefined()
+    expect(s.shadow).toBeDefined()
+    expect(s.hidden).toBe(true)
+    expect(s.alpha).toBeUndefined() // opacity 미요청
+  })
+
+  test('컴포넌트가 styling 없으면 — refid 만', () => {
+    const c = { refid: 99, type: 'rect' }
+    const s = buildComponentStyleSummary(c)
+    expect(s).toEqual({ refid: 99 })
+  })
+
+  test('font 부분 — 일부만 set', () => {
+    const c = { refid: 1, fontSize: 16, fontColor: '#0080ff' }
+    const s = buildComponentStyleSummary(c, ['font'])
+    expect(s.font).toEqual({ fontSize: 16, fontColor: '#0080ff' })
+  })
+
+  test('font 모두 비어있으면 font 키 자체 없음', () => {
+    const c = { refid: 1, type: 'rect' }
+    const s = buildComponentStyleSummary(c, ['font'])
+    expect(s.font).toBeUndefined()
+  })
+})

package/server/service/styling/read-tools.ts

@@ -0,0 +1,67 @@
+/**
+ * getComponentStyle — 컴포넌트의 현재 styling 상태 조회 (read tool).
+ *
+ * AI 가 변경 전 현재 상태 파악용 — "이미 빨간 모터를 더 빨갛게" 같은 모호 명령
+ * 정확 처리. iteration loop 의 핵심 기반.
+ *
+ * 반환 형태: { fillStyle, strokeStyle, shadow, material3d, font, alpha, hidden, text }
+ *   - aspects 인자로 부분 조회 가능 (토큰 절감)
+ */
+export interface GetComponentStyleInput {
+  refid: number
+  aspects?: Array<'fill' | 'stroke' | 'shadow' | 'material' | 'font' | 'opacity' | 'visibility' | 'text'>
+}
+
+export interface ComponentStyleSummary {
+  refid: number
+  fillStyle?: any
+  strokeStyle?: any
+  shadow?: any
+  material3d?: any
+  font?: {
+    fontFamily?: string
+    fontSize?: number
+    fontWeight?: string
+    fontStyle?: string
+    fontColor?: string
+    textAlign?: string
+    textBaseline?: string
+    lineHeight?: number
+  }
+  alpha?: number
+  hidden?: boolean
+  text?: string
+}
+
+export function buildComponentStyleSummary(
+  component: any,
+  aspects?: GetComponentStyleInput['aspects']
+): ComponentStyleSummary {
+  const all = !aspects || aspects.length === 0
+  const want = (a: string) => all || aspects!.includes(a as any)
+
+  const out: ComponentStyleSummary = { refid: component.refid }
+
+  if (want('fill') && component.fillStyle !== undefined) out.fillStyle = component.fillStyle
+  if (want('stroke') && component.strokeStyle !== undefined) out.strokeStyle = component.strokeStyle
+  if (want('shadow') && component.shadow !== undefined) out.shadow = component.shadow
+  if (want('material') && component.material3d !== undefined) out.material3d = component.material3d
+  if (want('opacity') && typeof component.alpha === 'number') out.alpha = component.alpha
+  if (want('visibility') && component.hidden !== undefined) out.hidden = component.hidden
+  if (want('text') && typeof component.text === 'string') out.text = component.text
+
+  if (want('font')) {
+    const font: any = {}
+    if (component.fontFamily) font.fontFamily = component.fontFamily
+    if (component.fontSize !== undefined) font.fontSize = component.fontSize
+    if (component.fontWeight !== undefined) font.fontWeight = component.fontWeight
+    if (component.fontStyle) font.fontStyle = component.fontStyle
+    if (component.fontColor) font.fontColor = component.fontColor
+    if (component.textAlign) font.textAlign = component.textAlign
+    if (component.textBaseline) font.textBaseline = component.textBaseline
+    if (component.lineHeight !== undefined) font.lineHeight = component.lineHeight
+    if (Object.keys(font).length > 0) out.font = font
+  }
+
+  return out
+}