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

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

@@ -0,0 +1,245 @@
+/**
+ * stroke-tools — buildSetStrokeOps 입력 → BoardEditOp[] 변환 검증.
+ *
+ * things-scene canonical fields (모두 top-level): strokeStyle (string color), lineWidth,
+ * lineDash (preset 이름 string), lineCap, lineJoin. tool 파라미터 이름이 engine 필드와
+ * 1:1 (rename 없음). dash 만 CSS-친화 alias (dashed/dotted/dashdot) → preset 매핑.
+ */
+import { buildSetStrokeOps } from './stroke-tools'
+
+describe('buildSetStrokeOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetStrokeOps({ refids: [], strokeStyle: 'red' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildSetStrokeOps({
+      refids: [1, 'abc' as any, NaN, 2],
+      strokeStyle: 'red'
+    })
+    expect(r.ops).toHaveLength(2)
+    expect(r.ops[0]).toMatchObject({ refid: 1, patch: { strokeStyle: '#ff0000' } })
+    expect(r.ops[1]).toMatchObject({ refid: 2, patch: { strokeStyle: '#ff0000' } })
+  })
+
+  test('아무 인자도 없으면 에러 — 의도 모호', () => {
+    const r = buildSetStrokeOps({ refids: [1] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/No stroke changes/)
+  })
+
+  test('잘못된 색상 → 에러', () => {
+    const r = buildSetStrokeOps({ refids: [1], strokeStyle: 'reddish' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid/i)
+  })
+
+  test('lineWidth 음수 → 에러', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineWidth: -1 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid lineWidth/)
+  })
+
+  test('lineWidth 0 은 허용 — 명시적 hide 의도와 구분되는 의도된 두께 0', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineWidth: 0 })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ lineWidth: 0 })
+  })
+
+  test('lineWidth Infinity → 에러', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineWidth: Infinity })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid lineWidth/)
+  })
+})
+
+describe('buildSetStrokeOps — strokeStyle (canonical, no rename)', () => {
+  test('hex → 정규화된 hex 문자열', () => {
+    const r = buildSetStrokeOps({ refids: [1], strokeStyle: '#ff0000' })
+    expect(r.ops[0].patch).toEqual({ strokeStyle: '#ff0000' })
+  })
+
+  test('CSS named → hex', () => {
+    const r = buildSetStrokeOps({ refids: [1], strokeStyle: 'red' })
+    expect(r.ops[0].patch).toEqual({ strokeStyle: '#ff0000' })
+  })
+
+  test('semantic alias (warm-red)', () => {
+    const r = buildSetStrokeOps({ refids: [1], strokeStyle: 'warm-red' })
+    expect(r.ops[0].patch).toEqual({ strokeStyle: '#e74c3c' })
+  })
+})
+
+describe('buildSetStrokeOps — lineWidth (canonical, no rename)', () => {
+  test('lineWidth 만 변경', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineWidth: 3 })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ lineWidth: 3 })
+  })
+
+  test('strokeStyle + lineWidth 동시', () => {
+    const r = buildSetStrokeOps({ refids: [1], strokeStyle: 'navy', lineWidth: 2 })
+    expect(r.ops[0].patch).toEqual({ strokeStyle: '#000080', lineWidth: 2 })
+  })
+})
+
+describe('buildSetStrokeOps — dash 정규화 (alias → preset)', () => {
+  test('AI 친화 alias dashed → dash', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'dashed' })
+    expect(r.ops[0].patch).toEqual({ lineDash: 'dash' })
+  })
+
+  test('AI 친화 alias dotted → square-dot', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'dotted' })
+    expect(r.ops[0].patch).toEqual({ lineDash: 'square-dot' })
+  })
+
+  test('AI 친화 alias dashdot → dash-dot', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'dashdot' })
+    expect(r.ops[0].patch).toEqual({ lineDash: 'dash-dot' })
+  })
+
+  test('things-scene preset 그대로 통과 (solid)', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'solid' })
+    expect(r.ops[0].patch).toEqual({ lineDash: 'solid' })
+  })
+
+  test('long-dash-dot-dot 같은 긴 preset', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'long-dash-dot-dot' })
+    expect(r.ops[0].patch).toEqual({ lineDash: 'long-dash-dot-dot' })
+  })
+
+  test('round-dot preset', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'round-dot' })
+    expect(r.ops[0].patch).toEqual({ lineDash: 'round-dot' })
+  })
+
+  test('알 수 없는 dash → 에러 + 유효 목록 제시', () => {
+    const r = buildSetStrokeOps({ refids: [1], dash: 'wave' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown dash/)
+    expect(r.errors[0]).toMatch(/solid/)
+  })
+})
+
+describe('buildSetStrokeOps — lineCap / lineJoin', () => {
+  test('lineCap=round', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineCap: 'round' })
+    expect(r.ops[0].patch).toEqual({ lineCap: 'round' })
+  })
+
+  test('lineJoin=miter', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineJoin: 'miter' })
+    expect(r.ops[0].patch).toEqual({ lineJoin: 'miter' })
+  })
+
+  test('cap + join + lineWidth + strokeStyle 조합', () => {
+    const r = buildSetStrokeOps({
+      refids: [1],
+      strokeStyle: '#333',
+      lineWidth: 2,
+      lineCap: 'round',
+      lineJoin: 'bevel'
+    })
+    expect(r.ops[0].patch).toEqual({
+      strokeStyle: '#333333',
+      lineWidth: 2,
+      lineCap: 'round',
+      lineJoin: 'bevel'
+    })
+  })
+
+  test('잘못된 lineCap → 에러 + 유효 목록 제시', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineCap: 'flat' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown lineCap.*flat/)
+    expect(r.errors[0]).toMatch(/butt/)
+  })
+
+  test('잘못된 lineJoin → 에러 + 유효 목록 제시', () => {
+    const r = buildSetStrokeOps({ refids: [1], lineJoin: 'sharp' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown lineJoin.*sharp/)
+    expect(r.errors[0]).toMatch(/miter/)
+  })
+})
+
+describe('buildSetStrokeOps — enabled=false (synthetic helper, stroke 제거)', () => {
+  test('enabled=false → lineWidth 0 (drawer/stroke.ts 가 안 그림)', () => {
+    const r = buildSetStrokeOps({ refids: [1], enabled: false })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ lineWidth: 0 })
+  })
+
+  test('enabled=false 가 명시 lineWidth 보다 우선', () => {
+    // 모순 입력: 사용자가 enabled=false 라고 했으면 lineWidth 무시하고 0
+    const r = buildSetStrokeOps({ refids: [1], enabled: false, lineWidth: 5 })
+    expect(r.ops[0].patch).toEqual({ lineWidth: 0 })
+  })
+
+  test('enabled=true 단독 — 다른 필드 없으면 patch 비어있는 op 안 만듦', () => {
+    // 현재 구현: enabled=true 단독은 noOp 가 아니지만 patch 가 비어 있음
+    const r = buildSetStrokeOps({ refids: [1], enabled: true })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({})
+  })
+})
+
+describe('buildSetStrokeOps — multi-target', () => {
+  test('동일 patch 가 여러 refid 에 분배', () => {
+    const r = buildSetStrokeOps({
+      refids: [10, 20, 30],
+      strokeStyle: 'red',
+      lineWidth: 2
+    })
+    expect(r.ops).toHaveLength(3)
+    const expectedPatch = { strokeStyle: '#ff0000', lineWidth: 2 }
+    expect(r.ops[0]).toEqual({ op: 'modify', refid: 10, patch: expectedPatch })
+    expect(r.ops[1]).toEqual({ op: 'modify', refid: 20, patch: expectedPatch })
+    expect(r.ops[2]).toEqual({ op: 'modify', refid: 30, patch: expectedPatch })
+  })
+
+  test('5 컴포넌트 동일 dashed 라인', () => {
+    const r = buildSetStrokeOps({
+      refids: [1, 2, 3, 4, 5],
+      strokeStyle: '#888',
+      lineWidth: 1,
+      dash: 'dashed'
+    })
+    expect(r.ops).toHaveLength(5)
+    expect(r.ops.every(o => (o as any).patch.lineDash === 'dash')).toBe(true)
+    expect(r.ops.every(o => (o as any).patch.strokeStyle === '#888888')).toBe(true)
+  })
+})
+
+describe('buildSetStrokeOps — 시나리오', () => {
+  test('테두리 강조 — 흰색 두께 3', () => {
+    const r = buildSetStrokeOps({ refids: [42], strokeStyle: 'white', lineWidth: 3 })
+    expect(r.ops[0].patch).toEqual({ strokeStyle: '#ffffff', lineWidth: 3 })
+  })
+
+  test('점선 가이드 — 회색 1px dashed', () => {
+    const r = buildSetStrokeOps({
+      refids: [42],
+      strokeStyle: '#aaa',
+      lineWidth: 1,
+      dash: 'dashed'
+    })
+    expect(r.ops[0].patch).toEqual({
+      strokeStyle: '#aaaaaa',
+      lineWidth: 1,
+      lineDash: 'dash'
+    })
+  })
+
+  test('테마 적용 — strokeStyle 만 (테마 정책 준수)', () => {
+    // 테마 요청 시 색상 만 변경, lineWidth/dash 는 건드리지 않음
+    const r = buildSetStrokeOps({ refids: [1, 2], strokeStyle: 'navy' })
+    expect(r.ops).toHaveLength(2)
+    expect(r.ops[0].patch).toEqual({ strokeStyle: '#000080' })
+    expect((r.ops[0] as any).patch.lineWidth).toBeUndefined()
+    expect((r.ops[0] as any).patch.lineDash).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,145 @@
+/**
+ * setStroke — 컴포넌트 테두리 / 라인 스타일.
+ *
+ * **things-scene 의 실제 데이터 형식 (drawer/stroke.ts 검증):**
+ *   - `state.strokeStyle: string` (색상 — Canvas API 의 strokeStyle 에 직접 대입되는 CSS color)
+ *   - `state.lineWidth: number` (top-level)
+ *   - `state.lineDash: string` (top-level — preset 이름. drawer 가 lineWidth 기반으로 배열 변환)
+ *     valid: 'solid' | 'round-dot' | 'square-dot' | 'dash' | 'dash-dot' | 'long-dash' | 'long-dash-dot' | 'long-dash-dot-dot'
+ *   - `state.lineCap: 'butt' | 'round' | 'square'` (top-level)
+ *   - `state.lineJoin: 'miter' | 'round' | 'bevel'` (top-level)
+ *
+ * 인터페이스의 `StrokeStyle` 객체 구조는 stale. 사용처는 모두 top-level 직접 접근.
+ *
+ * 입력 단순화 — AI 친화적 alias 도 받아 things-scene preset 으로 매핑:
+ *   AI 'dashed' → 'dash', 'dotted' → 'square-dot', 'dashdot' → 'dash-dot'.
+ */
+import type { BoardEditOp } from '../types'
+import { normalizeColor, validateColor } from './color-utils'
+
+export interface SetStrokeInput {
+  refids: number[]
+  /** synthetic — false 면 lineWidth=0 으로 매핑 (drawer 가 안 그림). 모델에 enabled 필드는 안 박힘. */
+  enabled?: boolean
+  /** state.strokeStyle 의 canonical 이름. CSS color string. */
+  strokeStyle?: string
+  /** state.lineWidth 의 canonical 이름. pixels. */
+  lineWidth?: number
+  /** preset 이름. AI 친화 alias 자동 매핑 — 'dashed' / 'dotted' / 'dashdot' 도 가능. */
+  dash?:
+    | 'solid'
+    | 'dashed'
+    | 'dotted'
+    | 'dashdot'
+    | 'round-dot'
+    | 'square-dot'
+    | 'dash'
+    | 'dash-dot'
+    | 'long-dash'
+    | 'long-dash-dot'
+    | 'long-dash-dot-dot'
+    | string
+  lineCap?: 'butt' | 'round' | 'square'
+  lineJoin?: 'miter' | 'round' | 'bevel'
+}
+
+export interface SetStrokeResult {
+  ops: BoardEditOp[]
+  errors: string[]
+}
+
+/** AI 친화 alias → things-scene 의 실제 preset 이름. */
+const DASH_ALIASES: Record<string, string> = {
+  dashed: 'dash',
+  dotted: 'square-dot',
+  dashdot: 'dash-dot'
+}
+
+const VALID_DASH = new Set([
+  'solid',
+  'round-dot',
+  'square-dot',
+  'dash',
+  'dash-dot',
+  'long-dash',
+  'long-dash-dot',
+  'long-dash-dot-dot'
+])
+
+// Canvas CanvasRenderingContext2D 가 허용하는 lineCap / lineJoin 만.
+// 잘못된 값은 Canvas 가 silent ignore → AI 가 'flat' / 'cap' 등을 보내도
+// 효과 없음. 명시 검증으로 ops 미실행 + 명확한 에러.
+const VALID_LINE_CAP = new Set(['butt', 'round', 'square'])
+const VALID_LINE_JOIN = new Set(['miter', 'round', 'bevel'])
+
+export function buildSetStrokeOps(input: SetStrokeInput): SetStrokeResult {
+  if (!Array.isArray(input.refids) || input.refids.length === 0) {
+    return { ops: [], errors: ['refids must be a non-empty array of numbers'] }
+  }
+  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.strokeStyle === undefined &&
+    input.lineWidth === undefined &&
+    input.dash === undefined &&
+    input.lineCap === undefined &&
+    input.lineJoin === undefined
+  if (noOp) {
+    return { ops: [], errors: ['No stroke changes specified'] }
+  }
+
+  // 검증
+  if (input.strokeStyle !== undefined) {
+    const v = validateColor(input.strokeStyle)
+    if (!v.valid) return { ops: [], errors: [v.error ?? 'Invalid strokeStyle'] }
+  }
+  if (input.lineWidth !== undefined && (input.lineWidth < 0 || !Number.isFinite(input.lineWidth))) {
+    return { ops: [], errors: [`Invalid lineWidth: ${input.lineWidth}`] }
+  }
+  if (input.lineCap !== undefined && !VALID_LINE_CAP.has(input.lineCap)) {
+    return {
+      ops: [],
+      errors: [`Unknown lineCap: '${input.lineCap}'. Valid: ${[...VALID_LINE_CAP].join(' / ')}.`]
+    }
+  }
+  if (input.lineJoin !== undefined && !VALID_LINE_JOIN.has(input.lineJoin)) {
+    return {
+      ops: [],
+      errors: [`Unknown lineJoin: '${input.lineJoin}'. Valid: ${[...VALID_LINE_JOIN].join(' / ')}.`]
+    }
+  }
+
+  // dash 정규화 — alias → 실제 preset → 검증
+  let dashValue: string | undefined
+  if (input.dash !== undefined) {
+    const raw = String(input.dash)
+    const resolved = DASH_ALIASES[raw] ?? raw
+    if (!VALID_DASH.has(resolved)) {
+      return {
+        ops: [],
+        errors: [
+          `Unknown dash: '${input.dash}'. Valid: ${[...VALID_DASH].join(' / ')} (or alias: dashed/dotted/dashdot).`
+        ]
+      }
+    }
+    dashValue = resolved
+  }
+
+  // patch 구성 — canonical 이름 그대로. 매핑 X. (color 만 normalizeColor 통과 — 입력 정규화는 mapping 이 아닌 처리)
+  const patch: any = {}
+  if (input.strokeStyle !== undefined) patch.strokeStyle = normalizeColor(input.strokeStyle)
+  if (input.lineWidth !== undefined) patch.lineWidth = input.lineWidth
+  if (dashValue !== undefined) patch.lineDash = dashValue
+  if (input.lineCap !== undefined) patch.lineCap = input.lineCap
+  if (input.lineJoin !== undefined) patch.lineJoin = input.lineJoin
+
+  // synthetic enabled — false 면 lineWidth 0 으로 변환 (drawer 가 안 그림 — drawer/stroke.ts:9)
+  if (input.enabled === false) {
+    patch.lineWidth = 0
+  }
+
+  const ops: BoardEditOp[] = refids.map(refid => ({ op: 'modify', refid, patch }))
+  return { ops, errors: [] }
+}

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

@@ -0,0 +1,253 @@
+/**
+ * text-tools — buildSetTextOps + buildSetFontOps.
+ *
+ * setText: state.text (콘텐츠 변경)
+ * setFont: state.fontFamily / fontSize / fontWeight / fontStyle / fontColor /
+ *          textAlign / textBaseline / lineHeight (시각 스타일 변경)
+ *
+ * 두 tool 분리 — 콘텐츠 vs 시각 스타일 의도가 다름.
+ */
+import { buildSetTextOps, buildSetFontOps } from './text-tools'
+
+describe('buildSetTextOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetTextOps({ refids: [], text: 'hi' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('text 가 string 이 아니면 에러', () => {
+    const r = buildSetTextOps({ refids: [1], text: 42 as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/text must be a string/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildSetTextOps({
+      refids: [1, NaN, 'x' as any, 2],
+      text: 'hello'
+    })
+    expect(r.ops).toHaveLength(2)
+  })
+
+  test('빈 문자열도 허용 (텍스트 비우기 의도)', () => {
+    const r = buildSetTextOps({ refids: [1], text: '' })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ text: '' })
+  })
+})
+
+describe('buildSetTextOps — text 매핑', () => {
+  test('단순 한국어', () => {
+    const r = buildSetTextOps({ refids: [1], text: '안녕' })
+    expect(r.ops[0]).toEqual({ op: 'modify', refid: 1, patch: { text: '안녕' } })
+  })
+
+  test('multi-target 동일 텍스트', () => {
+    const r = buildSetTextOps({ refids: [1, 2, 3], text: 'OK' })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops.every(o => (o as any).patch.text === 'OK')).toBe(true)
+  })
+
+  test('개행 / 특수문자 그대로 통과', () => {
+    const text = 'Line 1\nLine 2\t<특수>'
+    const r = buildSetTextOps({ refids: [1], text })
+    expect((r.ops[0] as any).patch.text).toBe(text)
+  })
+})
+
+describe('buildSetFontOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetFontOps({ refids: [], fontSize: 12 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildSetFontOps({
+      refids: [1, NaN, 'x' as any, 2],
+      fontSize: 14
+    })
+    expect(r.ops).toHaveLength(2)
+  })
+
+  test('아무 인자도 없으면 에러', () => {
+    const r = buildSetFontOps({ refids: [1] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/No font changes/)
+  })
+
+  test('fontSize 0 → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], fontSize: 0 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid fontSize/)
+  })
+
+  test('fontSize 음수 → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], fontSize: -1 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid fontSize/)
+  })
+
+  test('fontSize Infinity → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], fontSize: Infinity })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid fontSize/)
+  })
+
+  test('lineHeight 0 → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], lineHeight: 0 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid lineHeight/)
+  })
+
+  test('잘못된 fontColor → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], fontColor: 'invalid' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid/)
+  })
+
+  test('잘못된 fontStyle → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], fontStyle: 'serif' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown fontStyle/)
+  })
+
+  test('잘못된 textAlign (Canvas 비표준 justify) → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], textAlign: 'justify' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown textAlign/)
+  })
+
+  test('잘못된 textBaseline → 에러', () => {
+    const r = buildSetFontOps({ refids: [1], textBaseline: 'center' as any })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown textBaseline/)
+  })
+})
+
+describe('buildSetFontOps — 필드 매핑', () => {
+  test('fontFamily 만', () => {
+    const r = buildSetFontOps({ refids: [1], fontFamily: 'Arial' })
+    expect(r.ops[0].patch).toEqual({ fontFamily: 'Arial' })
+  })
+
+  test('fontSize 만', () => {
+    const r = buildSetFontOps({ refids: [1], fontSize: 16 })
+    expect(r.ops[0].patch).toEqual({ fontSize: 16 })
+  })
+
+  test('fontWeight 숫자 → string 화', () => {
+    const r = buildSetFontOps({ refids: [1], fontWeight: 600 })
+    expect(r.ops[0].patch).toEqual({ fontWeight: '600' })
+  })
+
+  test("fontWeight 'bold' 그대로", () => {
+    const r = buildSetFontOps({ refids: [1], fontWeight: 'bold' })
+    expect(r.ops[0].patch).toEqual({ fontWeight: 'bold' })
+  })
+
+  test('fontStyle italic', () => {
+    const r = buildSetFontOps({ refids: [1], fontStyle: 'italic' })
+    expect(r.ops[0].patch).toEqual({ fontStyle: 'italic' })
+  })
+
+  test('fontColor 정규화 (named → hex)', () => {
+    const r = buildSetFontOps({ refids: [1], fontColor: 'red' })
+    expect(r.ops[0].patch).toEqual({ fontColor: '#ff0000' })
+  })
+
+  test('fontColor semantic alias', () => {
+    const r = buildSetFontOps({ refids: [1], fontColor: 'warm-red' })
+    expect(r.ops[0].patch).toEqual({ fontColor: '#e74c3c' })
+  })
+
+  test('textAlign / textBaseline', () => {
+    const r = buildSetFontOps({
+      refids: [1],
+      textAlign: 'center',
+      textBaseline: 'middle'
+    })
+    expect(r.ops[0].patch).toEqual({
+      textAlign: 'center',
+      textBaseline: 'middle'
+    })
+  })
+
+  test('lineHeight 양수', () => {
+    const r = buildSetFontOps({ refids: [1], lineHeight: 1.5 })
+    expect(r.ops[0].patch).toEqual({ lineHeight: 1.5 })
+  })
+
+  test('전체 필드 한 번에', () => {
+    const r = buildSetFontOps({
+      refids: [1],
+      fontFamily: 'Helvetica',
+      fontSize: 14,
+      fontWeight: 'bold',
+      fontStyle: 'normal',
+      fontColor: 'navy',
+      textAlign: 'left',
+      textBaseline: 'alphabetic',
+      lineHeight: 1.2
+    })
+    expect(r.ops[0].patch).toEqual({
+      fontFamily: 'Helvetica',
+      fontSize: 14,
+      fontWeight: 'bold',
+      fontStyle: 'normal',
+      fontColor: '#000080',
+      textAlign: 'left',
+      textBaseline: 'alphabetic',
+      lineHeight: 1.2
+    })
+  })
+})
+
+describe('buildSetFontOps — multi-target', () => {
+  test('동일 폰트 스타일이 여러 refid 에 분배', () => {
+    const r = buildSetFontOps({
+      refids: [1, 2, 3],
+      fontSize: 18,
+      fontColor: 'black'
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops[0].patch).toEqual({
+      fontSize: 18,
+      fontColor: '#000000'
+    })
+    expect(r.ops[2]).toMatchObject({
+      refid: 3,
+      patch: { fontSize: 18, fontColor: '#000000' }
+    })
+  })
+})
+
+describe('text-tools — 시나리오', () => {
+  test('테마 적용 — fontColor 만 (테마 정책 준수)', () => {
+    // 테마 요청 시 fontColor 만 변경, fontSize/fontFamily 는 안 건드림
+    const r = buildSetFontOps({ refids: [1, 2], fontColor: '#444' })
+    expect(r.ops[0].patch).toEqual({ fontColor: '#444444' })
+    expect((r.ops[0] as any).patch.fontSize).toBeUndefined()
+    expect((r.ops[0] as any).patch.fontFamily).toBeUndefined()
+  })
+
+  test('명시 폰트 변경 — 사용자가 요청한 경우만', () => {
+    const r = buildSetFontOps({
+      refids: [42],
+      fontFamily: 'Pretendard',
+      fontSize: 24,
+      fontWeight: 'bold'
+    })
+    expect(r.ops[0].patch).toEqual({
+      fontFamily: 'Pretendard',
+      fontSize: 24,
+      fontWeight: 'bold'
+    })
+  })
+
+  test('레이블 텍스트 변경', () => {
+    const r = buildSetTextOps({ refids: [1], text: '온도: 23°C' })
+    expect(r.ops[0].patch).toEqual({ text: '온도: 23°C' })
+  })
+})