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

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

@@ -0,0 +1,152 @@
+/**
+ * copy-tools — copyStyle source → targets 복사.
+ */
+import { buildCopyStyleOps } from './copy-tools'
+
+const COMPONENTS = [
+  {
+    refid: 35,
+    type: 'rect',
+    fillStyle: { type: 'solid', color: '#ff0000' },
+    strokeStyle: { color: '#000', width: 2 },
+    shadow: { blur: 4 },
+    material3d: { preset: 'metal' },
+    fontFamily: 'Inter',
+    fontSize: 14,
+    alpha: 0.9,
+    hidden: false
+  },
+  { refid: 36, type: 'rect' }, // styling 없음
+  { refid: 37, type: 'rect' },
+  { refid: 38, type: 'circle' }
+]
+
+describe('buildCopyStyleOps — 검증', () => {
+  test('sourceRefid 비-숫자', () => {
+    const r = buildCopyStyleOps({} as any, COMPONENTS)
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/sourceRefid/)
+  })
+
+  test('targetRefids 빈 배열', () => {
+    const r = buildCopyStyleOps(
+      { sourceRefid: 35, targetRefids: [] },
+      COMPONENTS
+    )
+    expect(r.ops).toEqual([])
+  })
+
+  test('source 없음', () => {
+    const r = buildCopyStyleOps(
+      { sourceRefid: 999, targetRefids: [36] },
+      COMPONENTS
+    )
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Source.*not found/)
+  })
+
+  test('알 수 없는 aspect', () => {
+    const r = buildCopyStyleOps(
+      { sourceRefid: 35, targetRefids: [36], aspects: ['xyz' as any] },
+      COMPONENTS
+    )
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown aspect/)
+  })
+
+  test('source 가 target 에 포함되면 자동 제외', () => {
+    const r = buildCopyStyleOps(
+      { sourceRefid: 35, targetRefids: [35, 36, 37] },
+      COMPONENTS
+    )
+    expect(r.ops).toHaveLength(2) // 35 제외
+    expect(r.ops.map(o => (o as any).refid).sort()).toEqual([36, 37])
+  })
+})
+
+describe('buildCopyStyleOps — 정상 동작', () => {
+  test('default aspects (visibility 제외) — 모든 styling 복사', () => {
+    const r = buildCopyStyleOps(
+      { sourceRefid: 35, targetRefids: [36, 37] },
+      COMPONENTS
+    )
+    expect(r.ops).toHaveLength(2)
+    const patch = (r.ops[0] as any).patch
+    expect(patch.fillStyle).toEqual({ type: 'solid', color: '#ff0000' })
+    expect(patch.strokeStyle).toEqual({ color: '#000', width: 2 })
+    expect(patch.shadow).toEqual({ blur: 4 })
+    expect(patch.material3d).toEqual({ preset: 'metal' })
+    expect(patch.fontFamily).toBe('Inter')
+    expect(patch.fontSize).toBe(14)
+    expect(patch.alpha).toBe(0.9)
+    // visibility default 제외
+    expect(patch.hidden).toBeUndefined()
+  })
+
+  test('aspects 부분 — fill 만', () => {
+    const r = buildCopyStyleOps(
+      { sourceRefid: 35, targetRefids: [36], aspects: ['fill'] },
+      COMPONENTS
+    )
+    const patch = (r.ops[0] as any).patch
+    expect(patch.fillStyle).toBeDefined()
+    expect(patch.strokeStyle).toBeUndefined()
+    expect(patch.shadow).toBeUndefined()
+  })
+
+  test('aspects 다중 — fill + stroke', () => {
+    const r = buildCopyStyleOps(
+      {
+        sourceRefid: 35,
+        targetRefids: [36],
+        aspects: ['fill', 'stroke']
+      },
+      COMPONENTS
+    )
+    const patch = (r.ops[0] as any).patch
+    expect(patch.fillStyle).toBeDefined()
+    expect(patch.strokeStyle).toBeDefined()
+    expect(patch.shadow).toBeUndefined()
+    expect(patch.fontFamily).toBeUndefined()
+  })
+
+  test('source 가 styling 없는 aspect — patch 에 누락', () => {
+    const sparse = [
+      { refid: 100, type: 'rect', fillStyle: { color: 'red' } },
+      { refid: 101, type: 'rect' }
+    ]
+    const r = buildCopyStyleOps(
+      { sourceRefid: 100, targetRefids: [101] },
+      sparse
+    )
+    const patch = (r.ops[0] as any).patch
+    expect(patch.fillStyle).toBeDefined()
+    expect(patch.strokeStyle).toBeUndefined()
+  })
+
+  test('source 가 모든 aspect 비어있으면 — 에러', () => {
+    const empty = [
+      { refid: 200, type: 'rect' },
+      { refid: 201, type: 'rect' }
+    ]
+    const r = buildCopyStyleOps(
+      { sourceRefid: 200, targetRefids: [201] },
+      empty
+    )
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/no styling/)
+  })
+
+  test('visibility aspect 명시 → hidden 복사', () => {
+    const c = [
+      { refid: 1, type: 'rect', hidden: true },
+      { refid: 2, type: 'rect' }
+    ]
+    const r = buildCopyStyleOps(
+      { sourceRefid: 1, targetRefids: [2], aspects: ['visibility'] },
+      c
+    )
+    const patch = (r.ops[0] as any).patch
+    expect(patch.hidden).toBe(true)
+  })
+})

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

@@ -0,0 +1,115 @@
+/**
+ * copyStyle — 한 컴포넌트의 styling 을 다른 컴포넌트들에 복사.
+ *
+ * 자주 쓰는 패턴: "MOTOR1 처럼 다른 모터들도 같게 만들어줘"
+ *   AI: getComponentByRefid(MOTOR1) 또는 getComponentStyle(MOTOR1) → copyStyle(...)
+ *
+ * aspects 인자로 어느 styling 영역만 복사할지 선택 가능 — 부분 통일 (예: 색만 통일).
+ *
+ * 입력 — sourceRefid 의 실제 styling 값을 미리 알 필요 없음. server 가 components
+ * 에서 source 찾아 styling 추출 후 target 들에 patch 생성.
+ */
+import type { BoardEditOp } from '../types'
+
+export interface CopyStyleInput {
+  sourceRefid: number
+  targetRefids: number[]
+  aspects?: Array<'fill' | 'stroke' | 'shadow' | 'material' | 'font' | 'opacity' | 'visibility'>
+}
+
+export interface OpsResult {
+  ops: BoardEditOp[]
+  errors: string[]
+}
+
+const ASPECT_FIELDS: Record<string, string[]> = {
+  fill: ['fillStyle'],
+  stroke: ['strokeStyle'],
+  shadow: ['shadow'],
+  material: ['material3d'],
+  font: [
+    'fontFamily',
+    'fontSize',
+    'fontWeight',
+    'fontStyle',
+    'fontColor',
+    'textAlign',
+    'textBaseline',
+    'lineHeight'
+  ],
+  opacity: ['alpha'],
+  visibility: ['hidden']
+}
+
+const DEFAULT_ASPECTS: Array<keyof typeof ASPECT_FIELDS> = [
+  'fill',
+  'stroke',
+  'shadow',
+  'material',
+  'font',
+  'opacity'
+  // visibility 는 default 에서 제외 — 의도 없이 hidden 복사 위험
+]
+
+/**
+ * input + components 배열 → BoardEditOp[].
+ *
+ * components 는 board 의 모든 컴포넌트 (caller 가 전달). source 찾아 styling 추출.
+ */
+export function buildCopyStyleOps(
+  input: CopyStyleInput,
+  components: ReadonlyArray<any>
+): OpsResult {
+  if (typeof input.sourceRefid !== 'number') {
+    return { ops: [], errors: ['sourceRefid (number) required'] }
+  }
+  if (!Array.isArray(input.targetRefids) || input.targetRefids.length === 0) {
+    return { ops: [], errors: ['targetRefids must be a non-empty array'] }
+  }
+  const targets = input.targetRefids.filter(
+    n => typeof n === 'number' && Number.isFinite(n) && n !== input.sourceRefid
+  )
+  if (targets.length === 0) {
+    return { ops: [], errors: ['No valid target refids (excluding source)'] }
+  }
+
+  const source = components.find(
+    c => c && typeof c.refid === 'number' && c.refid === input.sourceRefid
+  )
+  if (!source) {
+    return {
+      ops: [],
+      errors: [`Source component refid=${input.sourceRefid} not found`]
+    }
+  }
+
+  const aspects = input.aspects && input.aspects.length > 0 ? input.aspects : DEFAULT_ASPECTS
+  const validAspects = Object.keys(ASPECT_FIELDS)
+  const unknown = aspects.filter(a => !validAspects.includes(a))
+  if (unknown.length > 0) {
+    return {
+      ops: [],
+      errors: [`Unknown aspect(s): ${unknown.join(', ')}. Valid: ${validAspects.join('/')}`]
+    }
+  }
+
+  // source 에서 aspect 별 필드 추출 → patch 합치기
+  const patch: any = {}
+  for (const aspect of aspects) {
+    const fields = ASPECT_FIELDS[aspect]
+    for (const field of fields) {
+      if (source[field] !== undefined) {
+        patch[field] = source[field]
+      }
+    }
+  }
+
+  if (Object.keys(patch).length === 0) {
+    return { ops: [], errors: ['Source has no styling for the requested aspects'] }
+  }
+
+  return {
+    ops: targets.map(refid => ({ op: 'modify', refid, patch })),
+    errors: []
+  }
+}

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

@@ -0,0 +1,277 @@
+/**
+ * effect-tools — setShadow / setOpacity / setVisible 테스트.
+ *
+ * shadow 의 canonical fields (CSS box-shadow / Canvas API 표준):
+ *   { color, offsetX, offsetY, blur }
+ * things-scene drawer 가 옛 이름 (left/top/blurSize) 도 backwards-compat 으로
+ * 읽지만, 새 코드는 canonical 만 사용.
+ *
+ * setOpacity → state.alpha (canonical), setVisible → state.hidden (visible 의 inverse).
+ */
+import { buildSetShadowOps, buildSetOpacityOps, buildSetVisibleOps } from './effect-tools'
+
+describe('buildSetShadowOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetShadowOps({ refids: [], color: 'black' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildSetShadowOps({
+      refids: [1, NaN, 'x' as any, 2],
+      color: 'black'
+    })
+    expect(r.ops).toHaveLength(2)
+  })
+
+  test('아무 인자도 없으면 에러', () => {
+    const r = buildSetShadowOps({ refids: [1] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/No shadow changes/)
+  })
+
+  test('잘못된 색상 → 에러', () => {
+    const r = buildSetShadowOps({ refids: [1], color: 'invalid-color' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid/)
+  })
+
+  test('blur 음수 → 에러', () => {
+    const r = buildSetShadowOps({ refids: [1], blur: -1 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid blur/)
+  })
+
+  test('blur Infinity → 에러', () => {
+    const r = buildSetShadowOps({ refids: [1], blur: Infinity })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid blur/)
+  })
+
+  test('blur 0 허용', () => {
+    const r = buildSetShadowOps({ refids: [1], blur: 0, color: 'black' })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ shadow: { color: '#000000', blur: 0 } })
+  })
+
+  test('offsetX NaN → 에러', () => {
+    const r = buildSetShadowOps({ refids: [1], offsetX: NaN })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid offsetX/)
+  })
+
+  test('offsetY Infinity → 에러', () => {
+    const r = buildSetShadowOps({ refids: [1], offsetY: Infinity })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid offsetY/)
+  })
+
+  test('offsetX 음수 허용 (CSS box-shadow 정상 사용)', () => {
+    const r = buildSetShadowOps({ refids: [1], offsetX: -3 })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ shadow: { offsetX: -3 } })
+  })
+})
+
+describe('buildSetShadowOps — canonical fields (CSS / Canvas 표준)', () => {
+  test('blur 검증', () => {
+    const r = buildSetShadowOps({ refids: [1], blur: 8 })
+    expect(r.ops[0].patch).toEqual({ shadow: { blur: 8 } })
+  })
+
+  test('offsetX 만', () => {
+    const r = buildSetShadowOps({ refids: [1], offsetX: 5 })
+    expect(r.ops[0].patch).toEqual({ shadow: { offsetX: 5 } })
+  })
+
+  test('offsetY 만', () => {
+    const r = buildSetShadowOps({ refids: [1], offsetY: 10 })
+    expect(r.ops[0].patch).toEqual({ shadow: { offsetY: 10 } })
+  })
+
+  test('color 정규화', () => {
+    const r = buildSetShadowOps({ refids: [1], color: 'red' })
+    expect(r.ops[0].patch).toEqual({ shadow: { color: '#ff0000' } })
+  })
+
+  test('전체 필드 — color/blur/offsetX/offsetY', () => {
+    const r = buildSetShadowOps({
+      refids: [1],
+      color: 'navy',
+      blur: 4,
+      offsetX: 3,
+      offsetY: 2
+    })
+    expect(r.ops[0].patch).toEqual({
+      shadow: {
+        color: '#000080',
+        blur: 4,
+        offsetX: 3,
+        offsetY: 2
+      }
+    })
+  })
+
+  test('offsetX/Y 0 명시 — 실제 0 으로 저장', () => {
+    const r = buildSetShadowOps({ refids: [1], offsetX: 0, offsetY: 0 })
+    expect(r.ops[0].patch).toEqual({ shadow: { offsetX: 0, offsetY: 0 } })
+  })
+})
+
+describe('buildSetShadowOps — enabled=false (그림자 제거)', () => {
+  test('enabled=false → blur 0 + transparent (drawer 가 안 그림)', () => {
+    const r = buildSetShadowOps({ refids: [1], enabled: false })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({
+      shadow: { blur: 0, color: 'transparent' }
+    })
+  })
+
+  test('enabled=false 가 다른 인자보다 우선 — color/blur 무시하고 제거', () => {
+    const r = buildSetShadowOps({
+      refids: [1],
+      enabled: false,
+      color: 'red',
+      blur: 8
+    })
+    expect(r.ops[0].patch).toEqual({
+      shadow: { blur: 0, color: 'transparent' }
+    })
+  })
+})
+
+describe('buildSetShadowOps — multi-target', () => {
+  test('동일 shadow 가 여러 refid 에 분배', () => {
+    const r = buildSetShadowOps({
+      refids: [10, 20, 30],
+      color: 'black',
+      blur: 6
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops[0].patch).toEqual({
+      shadow: { color: '#000000', blur: 6 }
+    })
+    expect(r.ops[2]).toMatchObject({
+      refid: 30,
+      patch: { shadow: { color: '#000000', blur: 6 } }
+    })
+  })
+})
+
+describe('buildSetOpacityOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetOpacityOps({ refids: [], alpha: 0.5 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('opacity 가 number 가 아니면 에러', () => {
+    const r = buildSetOpacityOps({ refids: [1], alpha: 'half' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/alpha must be 0..1/)
+  })
+
+  test('opacity > 1 → 에러', () => {
+    const r = buildSetOpacityOps({ refids: [1], alpha: 1.5 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/alpha must be 0..1/)
+  })
+
+  test('opacity < 0 → 에러', () => {
+    const r = buildSetOpacityOps({ refids: [1], alpha: -0.1 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/alpha must be 0..1/)
+  })
+
+  test('opacity 0 (완전 투명) 허용', () => {
+    const r = buildSetOpacityOps({ refids: [1], alpha: 0 })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ alpha: 0 })
+  })
+
+  test('opacity 1 (완전 불투명) 허용', () => {
+    const r = buildSetOpacityOps({ refids: [1], alpha: 1 })
+    expect(r.ops[0].patch).toEqual({ alpha: 1 })
+  })
+})
+
+describe('buildSetOpacityOps — alpha 매핑', () => {
+  test('opacity 0.5 → state.alpha 0.5', () => {
+    const r = buildSetOpacityOps({ refids: [1], alpha: 0.5 })
+    expect(r.ops[0].patch).toEqual({ alpha: 0.5 })
+  })
+
+  test('multi-target 동일 alpha', () => {
+    const r = buildSetOpacityOps({ refids: [1, 2, 3], alpha: 0.7 })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops.every(o => (o as any).patch.alpha === 0.7)).toBe(true)
+  })
+})
+
+describe('buildSetVisibleOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetVisibleOps({ refids: [], visible: true })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('visible 이 boolean 이 아니면 에러', () => {
+    const r = buildSetVisibleOps({ refids: [1], visible: 'yes' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/visible must be a boolean/)
+  })
+
+  test('visible=undefined → 에러', () => {
+    const r = buildSetVisibleOps({ refids: [1], visible: undefined as any })
+    expect(r.ops).toEqual([])
+  })
+})
+
+describe('buildSetVisibleOps — hidden = !visible', () => {
+  test('visible=true → hidden=false', () => {
+    const r = buildSetVisibleOps({ refids: [1], visible: true })
+    expect(r.ops[0].patch).toEqual({ hidden: false })
+  })
+
+  test('visible=false → hidden=true', () => {
+    const r = buildSetVisibleOps({ refids: [1], visible: false })
+    expect(r.ops[0].patch).toEqual({ hidden: true })
+  })
+
+  test('multi-target 일괄 hide', () => {
+    const r = buildSetVisibleOps({ refids: [1, 2, 3, 4, 5], visible: false })
+    expect(r.ops).toHaveLength(5)
+    expect(r.ops.every(o => (o as any).patch.hidden === true)).toBe(true)
+  })
+})
+
+describe('effect-tools — 시나리오', () => {
+  test('카드에 부드러운 그림자', () => {
+    const r = buildSetShadowOps({
+      refids: [42],
+      color: 'rgba(0,0,0,0.2)',
+      blur: 12,
+      offsetX: 0,
+      offsetY: 4
+    })
+    // rgba 는 정규화되어 hex 로 변환 (alpha 채널 손실, color-utils 의 정책)
+    expect(r.ops[0].patch.shadow).toMatchObject({
+      blur: 12,
+      offsetX: 0,
+      offsetY: 4
+    })
+  })
+
+  test('비활성 컴포넌트 — 50% 투명', () => {
+    const r = buildSetOpacityOps({ refids: [1, 2], alpha: 0.5 })
+    expect(r.ops).toHaveLength(2)
+    expect(r.ops[0].patch).toEqual({ alpha: 0.5 })
+  })
+
+  test('숨김 토글 — 다중 컴포넌트', () => {
+    const r = buildSetVisibleOps({ refids: [10, 11, 12], visible: false })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops[0].patch).toEqual({ hidden: true })
+  })
+})

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

@@ -0,0 +1,124 @@
+/**
+ * setShadow / setOpacity / setVisible — 효과 / 가시성 / 투명도.
+ *
+ * setShadow: state.shadow (color/blur/offsetX/offsetY)
+ * setOpacity: state.alpha (컴포넌트 전체 알파, 0..1)
+ * setVisible: state.hidden 토글 (true → 숨김)
+ */
+import type { BoardEditOp } from '../types'
+import { normalizeColor, validateColor } from './color-utils'
+
+export interface SetShadowInput {
+  refids: number[]
+  /** synthetic — false 면 blur=0 + color=transparent 매핑 (drawer 가 안 그림). 모델에 enabled 필드 없음. */
+  enabled?: boolean
+  /** state.shadow.color */
+  color?: string
+  /** Blur radius (CSS box-shadow 의 blur-radius, Canvas 의 shadowBlur). state.shadow.blur. */
+  blur?: number
+  /** Horizontal offset (CSS box-shadow 의 offset-x, Canvas 의 shadowOffsetX). state.shadow.offsetX. */
+  offsetX?: number
+  /** Vertical offset (CSS box-shadow 의 offset-y, Canvas 의 shadowOffsetY). state.shadow.offsetY. */
+  offsetY?: number
+}
+
+export interface SetOpacityInput {
+  refids: number[]
+  /** state.alpha 의 canonical 이름. 0..1. */
+  alpha: number
+}
+
+export interface SetVisibleInput {
+  refids: number[]
+  visible: boolean
+}
+
+export interface OpsResult {
+  ops: BoardEditOp[]
+  errors: string[]
+}
+
+/**
+ * setShadow — CSS box-shadow / Canvas API 표준 이름 (color/offsetX/offsetY/blur) 그대로
+ * state.shadow 에 set. things-scene drawer 는 옛 이름 (left/top/blurSize) 도
+ * backwards-compat 으로 읽지만 (effect/shadow.ts:36-47), 새 모델은 canonical 만 사용.
+ *
+ * synthetic enabled=false → blur 0 + transparent 매핑 (drawer 가 안 그림).
+ * 모델에 enabled 필드는 없음.
+ */
+export function buildSetShadowOps(input: SetShadowInput): 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.enabled === undefined &&
+    input.color === undefined &&
+    input.blur === undefined &&
+    input.offsetX === undefined &&
+    input.offsetY === undefined
+  if (noOp) return { ops: [], errors: ['No shadow changes specified'] }
+
+  if (input.enabled === false) {
+    // synthetic — false 면 blur 0 + transparent 으로 변환 (drawer 가 안 그림)
+    const patch = { shadow: { blur: 0, color: 'transparent' } }
+    return { ops: refids.map(refid => ({ op: 'modify', refid, patch })), errors: [] }
+  }
+
+  if (input.color !== undefined) {
+    const v = validateColor(input.color)
+    if (!v.valid) return { ops: [], errors: [v.error ?? 'Invalid shadow color'] }
+  }
+  if (input.blur !== undefined && (input.blur < 0 || !Number.isFinite(input.blur))) {
+    return { ops: [], errors: [`Invalid blur: ${input.blur}`] }
+  }
+  if (input.offsetX !== undefined && !Number.isFinite(input.offsetX)) {
+    return { ops: [], errors: [`Invalid offsetX: ${input.offsetX}`] }
+  }
+  if (input.offsetY !== undefined && !Number.isFinite(input.offsetY)) {
+    return { ops: [], errors: [`Invalid offsetY: ${input.offsetY}`] }
+  }
+
+  // CSS / Canvas 표준 canonical 이름 — rename 없음
+  const sh: Record<string, number | string> = {}
+  // validateColor 가 통과한 색만 도달 — normalizeColor 가 여기서 null 반환 안 함
+  if (input.color !== undefined) sh.color = normalizeColor(input.color)!
+  if (input.blur !== undefined) sh.blur = input.blur
+  if (input.offsetX !== undefined) sh.offsetX = input.offsetX
+  if (input.offsetY !== undefined) sh.offsetY = input.offsetY
+
+  const patch = { shadow: sh }
+  return { ops: refids.map(refid => ({ op: 'modify', refid, patch })), errors: [] }
+}
+
+export function buildSetOpacityOps(input: SetOpacityInput): OpsResult {
+  if (!Array.isArray(input.refids) || input.refids.length === 0) {
+    return { ops: [], errors: ['refids must be a non-empty array'] }
+  }
+  if (typeof input.alpha !== 'number' || input.alpha < 0 || input.alpha > 1) {
+    return { ops: [], errors: [`alpha must be 0..1: ${input.alpha}`] }
+  }
+  const refids = input.refids.filter(n => typeof n === 'number' && Number.isFinite(n))
+  if (refids.length === 0) return { ops: [], errors: ['No valid numeric refids'] }
+
+  // canonical 이름 그대로
+  const patch = { alpha: input.alpha }
+  return { ops: refids.map(refid => ({ op: 'modify', refid, patch })), errors: [] }
+}
+
+export function buildSetVisibleOps(input: SetVisibleInput): OpsResult {
+  if (!Array.isArray(input.refids) || input.refids.length === 0) {
+    return { ops: [], errors: ['refids must be a non-empty array'] }
+  }
+  if (typeof input.visible !== 'boolean') {
+    return { ops: [], errors: ['visible must be a boolean'] }
+  }
+  const refids = input.refids.filter(n => typeof n === 'number' && Number.isFinite(n))
+  if (refids.length === 0) return { ops: [], errors: ['No valid numeric refids'] }
+
+  // hidden 은 visible 의 inverse
+  const patch = { hidden: !input.visible }
+  return { ops: refids.map(refid => ({ op: 'modify', refid, patch })), errors: [] }
+}