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

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

@@ -0,0 +1,331 @@
+/**
+ * fill-tools — setFill 입력 → BoardEditOp[] 변환 검증.
+ *
+ * 4 modes (none/solid/gradient/pattern) 별 동작 + 검증 + multi-target.
+ *
+ * 출력 정책: refid 당 1 op. mode 변경 시에도 fillStyle 통째 교체.
+ * (이전 2-op (null + new) 방식은 중간 null 상태가 3D 텍스처 크래시 유발 → 폐지.)
+ */
+import { buildSetFillOps } from './fill-tools'
+
+describe('buildSetFillOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildSetFillOps({ refids: [], mode: 'solid', color: 'red' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildSetFillOps({
+      refids: [1, 'abc' as any, NaN, 2],
+      mode: 'solid',
+      color: 'red'
+    })
+    // refid 당 1 op → 2 valid * 1 = 2
+    expect(r.ops).toHaveLength(2)
+    expect(r.ops[0]).toMatchObject({ op: 'modify', refid: 1, patch: { fillStyle: '#ff0000' } })
+    expect(r.ops[1]).toMatchObject({ op: 'modify', refid: 2, patch: { fillStyle: '#ff0000' } })
+  })
+
+  test('아무 인자도 없으면 에러', () => {
+    const r = buildSetFillOps({ refids: [1] } as any)
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/No fill changes/)
+  })
+
+  test('잘못된 색상 → 에러', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'solid', color: 'reddish' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid color/)
+  })
+
+  test('opacity 범위 밖 → 에러', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'solid', color: 'red', opacity: 1.5 })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Opacity out of/)
+  })
+})
+
+describe('buildSetFillOps — solid mode (string fillStyle)', () => {
+  test('solid → fillStyle 색상 string', () => {
+    const r = buildSetFillOps({ refids: [35], mode: 'solid', color: 'red' })
+    expect(r.errors).toEqual([])
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0]).toEqual({ op: 'modify', refid: 35, patch: { fillStyle: '#ff0000' } })
+  })
+
+  test('opacity → rgba 문자열에 alpha 포함', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'solid', color: 'blue', opacity: 0.5 })
+    expect(r.ops[0].patch).toEqual({ fillStyle: 'rgba(0,0,255,0.5)' })
+  })
+
+  test('opacity 1 → alpha 안 포함 (그냥 hex)', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'solid', color: 'blue', opacity: 1 })
+    expect(r.ops[0].patch).toEqual({ fillStyle: '#0000ff' })
+  })
+
+  test('semantic 색상 (warm-red)', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'solid', color: 'warm-red' })
+    expect(r.ops[0].patch).toEqual({ fillStyle: '#e74c3c' })
+  })
+
+  test('multi-target — 3 refid * 1 op = 3', () => {
+    const r = buildSetFillOps({
+      refids: [10, 20, 30],
+      mode: 'solid',
+      color: 'green'
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops[0]).toMatchObject({ refid: 10, patch: { fillStyle: '#008000' } })
+    expect(r.ops[2]).toMatchObject({ refid: 30, patch: { fillStyle: '#008000' } })
+  })
+
+  test('color 없이 mode=solid → null', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'solid' })
+    expect(r.ops).toEqual([])
+  })
+})
+
+describe('buildSetFillOps — gradient mode (things-scene colorStops 형식)', () => {
+  test('명시 stops + rotation degrees → 라디안 변환', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'gradient',
+      colorStops: [
+        { color: 'red', position: 0 },
+        { color: 'blue', position: 1 }
+      ],
+      rotation: 90
+    })
+    expect(r.ops).toHaveLength(1)
+    const fs = (r.ops[0] as any).patch.fillStyle
+    expect(fs.type).toBe('gradient')
+    expect(fs.gradientType).toBe('linear')
+    expect(fs.colorStops).toEqual([
+      { position: 0, color: '#ff0000' },
+      { position: 1, color: '#0000ff' }
+    ])
+    expect(fs.rotation).toBeCloseTo(Math.PI / 2)
+    // 잘못된 stale 필드 (colors/stops) 없어야
+    expect(fs.colors).toBeUndefined()
+    expect(fs.stops).toBeUndefined()
+  })
+
+  test('color 만 → 자동 colorStops 생성 (어두운 변형)', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'gradient', color: 'red' })
+    expect(r.ops).toHaveLength(1)
+    const fs = (r.ops[0] as any).patch.fillStyle
+    expect(fs.type).toBe('gradient')
+    expect(fs.colorStops).toHaveLength(2)
+    expect(fs.colorStops[0]).toEqual({ position: 0, color: '#ff0000' })
+    expect(fs.colorStops[1].color).not.toBe('#ff0000') // 어두워야
+    expect(fs.colorStops[1].position).toBe(1)
+    // rotation 미지정 → 0 default (drawer 의 NaN 크래시 방지)
+    expect(fs.rotation).toBe(0)
+  })
+
+  test('rotation 미지정 시 0 default — createLinearGradient 크래시 방지', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'gradient',
+      colorStops: [
+        { color: 'red', position: 0 },
+        { color: 'blue', position: 1 }
+      ]
+    })
+    const fs = (r.ops[0] as any).patch.fillStyle
+    expect(fs.rotation).toBe(0)
+  })
+
+  test('radial 명시', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'gradient',
+      gradientType: 'radial',
+      colorStops: [
+        { color: 'white', position: 0 },
+        { color: 'black', position: 1 }
+      ]
+    })
+    expect((r.ops[0] as any).patch.fillStyle.gradientType).toBe('radial')
+  })
+
+  test('3 stops — 발리바다 시나리오', () => {
+    const r = buildSetFillOps({
+      refids: [14],
+      mode: 'gradient',
+      gradientType: 'linear',
+      rotation: 90,
+      colorStops: [
+        { color: '#00bfa5', position: 0 },
+        { color: '#00e5ff', position: 0.5 },
+        { color: '#0288d1', position: 1 }
+      ]
+    })
+    const fs = (r.ops[0] as any).patch.fillStyle
+    expect(fs.colorStops).toEqual([
+      { position: 0, color: '#00bfa5' },
+      { position: 0.5, color: '#00e5ff' },
+      { position: 1, color: '#0288d1' }
+    ])
+  })
+
+  test('stops position 범위 밖 → 에러', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'gradient',
+      colorStops: [
+        { color: 'red', position: 0 },
+        { color: 'blue', position: 1.5 }
+      ]
+    })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/position out of/)
+  })
+
+  test('stop 색상 잘못 → 에러', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'gradient',
+      colorStops: [
+        { color: 'invalid', position: 0 },
+        { color: 'blue', position: 1 }
+      ]
+    })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Invalid gradient stop color/)
+  })
+})
+
+describe('buildSetFillOps — pattern mode (things-scene 실제 필드)', () => {
+  test('기본 — image 만', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'pattern',
+      image: 'https://example.com/p.png'
+    })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({
+      fillStyle: { type: 'pattern', image: 'https://example.com/p.png' }
+    })
+  })
+
+  test('image 없으면 에러', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'pattern' })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/requires 'image'/)
+  })
+
+  test('fitPattern + align + offset 등 things-scene 필드 통과', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'pattern',
+      image: 'logo.png',
+      fitPattern: false,
+      align: 'center',
+      offsetX: 10,
+      offsetY: 5,
+      noRepeat: true,
+      opacity: 0.7,
+      color: 'navy'
+    })
+    expect((r.ops[0] as any).patch.fillStyle).toEqual({
+      type: 'pattern',
+      image: 'logo.png',
+      color: '#000080',
+      fitPattern: false,
+      noRepeat: true,
+      align: 'center',
+      offsetX: 10,
+      offsetY: 5,
+      opacity: 0.7
+    })
+  })
+
+  test('patternWidth / patternHeight → width / height 매핑', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'pattern',
+      image: 'p.png',
+      patternWidth: 100,
+      patternHeight: 50
+    })
+    expect((r.ops[0] as any).patch.fillStyle).toMatchObject({
+      width: 100,
+      height: 50
+    })
+  })
+})
+
+describe('buildSetFillOps — none mode', () => {
+  test('fillStyle 제거 의도 — null 시맨틱 (apply-patch 가 키 자체 제거)', () => {
+    const r = buildSetFillOps({ refids: [1], mode: 'none' })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ fillStyle: null })
+  })
+})
+
+describe('buildSetFillOps — 부분 update (mode 미지정 — string 출력)', () => {
+  test('color 만 변경 → fillStyle 색상 string', () => {
+    const r = buildSetFillOps({ refids: [1], color: 'green' })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ fillStyle: '#008000' })
+  })
+
+  test('opacity 만 (color 없음) → 의도 모호 → 무동작', () => {
+    const r = buildSetFillOps({ refids: [1], opacity: 0.3 })
+    expect(r.ops).toEqual([])
+  })
+
+  test('color + opacity → rgba 문자열', () => {
+    const r = buildSetFillOps({ refids: [1], color: 'navy', opacity: 0.8 })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ fillStyle: 'rgba(0,0,128,0.8)' })
+  })
+})
+
+describe('buildSetFillOps — 시나리오', () => {
+  test('대시보드 — 5개 게이지 동일 다크 배경', () => {
+    const r = buildSetFillOps({
+      refids: [10, 11, 12, 13, 14],
+      mode: 'solid',
+      color: '#0a1929',
+      opacity: 0.95
+    })
+    expect(r.ops).toHaveLength(5)
+    // opacity 0.95 → rgba 문자열
+    expect(r.ops.every(o => (o as any).patch.fillStyle === 'rgba(10,25,41,0.95)')).toBe(true)
+  })
+
+  test('점진 update — 빨강 단색 → 그라디언트 위→아래', () => {
+    const r = buildSetFillOps({
+      refids: [35],
+      mode: 'gradient',
+      gradientType: 'linear',
+      rotation: 90,
+      colorStops: [
+        { color: 'red', position: 0 },
+        { color: '#660000', position: 1 }
+      ]
+    })
+    expect(r.ops).toHaveLength(1)
+    const fs = (r.ops[0] as any).patch.fillStyle
+    expect(fs.type).toBe('gradient')
+    expect(fs.rotation).toBeCloseTo(Math.PI / 2)
+    expect(fs.colorStops).toEqual([
+      { position: 0, color: '#ff0000' },
+      { position: 1, color: '#660000' }
+    ])
+  })
+
+  test('alpha 채널 — solid + 50% opacity', () => {
+    const r = buildSetFillOps({
+      refids: [1],
+      mode: 'solid',
+      color: 'rgba(255, 0, 0, 0.5)'
+      // color 의 alpha 는 normalizeColor 가 무시 (hex 만 추출). opacity 별 인자로 줘야 적용.
+    })
+    expect(r.ops).toHaveLength(1)
+    expect((r.ops[0] as any).patch.fillStyle).toBe('#ff0000')
+  })
+})

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

@@ -0,0 +1,293 @@
+/**
+ * setFill — 컴포넌트 배경 (state.fillStyle) 변경.
+ *
+ * 4 modes 지원: none / solid / gradient / pattern.
+ *
+ * 출력 정책 — refid 당 1 op:
+ *   - solid: fillStyle = '#rrggbb' or 'rgba(...)' (string)
+ *   - gradient: fillStyle = { type:'gradient', gradientType, colorStops, rotation, ... }
+ *   - pattern: fillStyle = { type:'pattern', image, ... }
+ *   - none: fillStyle = { type:'none' }
+ *   - mode 미지정 + color 만: 부분 update (string 또는 object 병합)
+ *
+ * things-scene 실제 데이터 형식 (drawer/fill.ts 검증):
+ *   - gradient: { type, gradientType, colorStops: [{position, color}], rotation (라디안) }
+ *   - rotation 은 라디안 — `Math.cos(fRotation)` 직접 사용
+ *
+ * 이전 2-op (null + new) 방식은 중간 null 상태가 onchange / 3D texture
+ * 크래시 유발 → 제거. 정확한 colorStops 출력으로 stale 필드 문제는 자체 해결.
+ */
+import type { BoardEditOp } from '../types'
+import { parseColor, normalizeColor, validateColor } from './color-utils'
+
+export interface SetFillInput {
+  refids: number[]
+  mode?: 'none' | 'solid' | 'gradient' | 'pattern'
+  // solid
+  color?: string
+  // gradient
+  gradientType?: 'linear' | 'radial'
+  /** colorStops — things-scene 의 canonical 필드명 그대로. position 0..1, color hex/rgb/named. */
+  colorStops?: Array<{ color: string; position: number }>
+  /** 회전 — 입력은 degrees (사용자/AI 친화), 내부 변환 후 things-scene 의 라디안으로 저장. */
+  rotation?: number
+  // pattern (drawer/fill.ts:95~ 검증)
+  image?: string
+  /** pattern: 영역에 맞춰 비율 조정 (true) vs 원본 크기 사용 (false). */
+  fitPattern?: boolean
+  /** pattern: 반복 안 함 (true) — 1회만 그림. */
+  noRepeat?: boolean
+  /** pattern: 정렬. fitPattern=false 일 때만 적용. */
+  align?:
+    | 'center'
+    | 'left-top'
+    | 'left-bottom'
+    | 'right-top'
+    | 'right-bottom'
+    | 'left'
+    | 'right'
+    | 'top'
+    | 'bottom'
+  /** pattern: 영역 내 오프셋 (fitPattern=false 일 때). */
+  offsetX?: number
+  offsetY?: number
+  /** pattern: 패턴 크기 (기본은 이미지 원본 크기). */
+  patternWidth?: number
+  patternHeight?: number
+  // 공통
+  opacity?: number  // 0..1
+}
+
+export interface SetFillResult {
+  ops: BoardEditOp[]
+  errors: string[]  // refid 별 에러 (성공한 것은 op 만 발사)
+}
+
+/**
+ * setFill 입력 검증 + BoardEditOp[] 생성.
+ *
+ * 기본 정책:
+ *   - refids 비어있거나 mode 도 색도 없으면 에러
+ *   - 색상 입력은 normalizeColor 통과해야 적용
+ *   - mode='gradient' 인데 stops 없으면 자동 생성 (color → 어두운 변형)
+ */
+export function buildSetFillOps(input: SetFillInput): SetFillResult {
+  const errors: string[] = []
+  const ops: BoardEditOp[] = []
+
+  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 in input'] }
+  }
+
+  // mode 미지정 + 어떤 styling 인자도 없으면 무의미
+  if (
+    !input.mode &&
+    !input.color &&
+    !input.colorStops &&
+    !input.image &&
+    typeof input.opacity !== 'number'
+  ) {
+    return {
+      ops: [],
+      errors: ['No fill changes specified. Provide mode and/or color/opacity/etc.']
+    }
+  }
+
+  // 색상 검증
+  if (input.color !== undefined) {
+    const v = validateColor(input.color)
+    if (!v.valid) {
+      errors.push(v.error ?? `Invalid color: ${input.color}`)
+      return { ops: [], errors }
+    }
+  }
+
+  // gradient stops 검증
+  if (input.colorStops) {
+    for (const s of input.colorStops) {
+      if (typeof s.position !== 'number' || s.position < 0 || s.position > 1) {
+        errors.push(`Gradient stop position out of [0,1]: ${s.position}`)
+        return { ops: [], errors }
+      }
+      const v = validateColor(s.color)
+      if (!v.valid) {
+        errors.push(`Invalid gradient stop color: ${s.color}`)
+        return { ops: [], errors }
+      }
+    }
+  }
+
+  // opacity 검증
+  if (typeof input.opacity === 'number') {
+    if (input.opacity < 0 || input.opacity > 1) {
+      errors.push(`Opacity out of [0,1]: ${input.opacity}`)
+      return { ops: [], errors }
+    }
+  }
+
+  // pattern — image 필수
+  if (input.mode === 'pattern' && !input.image) {
+    errors.push(`Mode 'pattern' requires 'image' (URL or asset ref)`)
+    return { ops: [], errors }
+  }
+
+  // 각 refid 별 patch 생성
+  const patch = buildFillPatch(input)
+  if (!patch) {
+    return { ops: [], errors: ['Failed to build fill patch'] }
+  }
+
+  // 단일 op — apply-patch 의 deep merge 가 자연스럽게 처리:
+  //   - 새 fillStyle 이 string (solid) → 기존 object 통째 replace (typeof 매칭 X)
+  //   - 새 fillStyle 이 object → 같은 key (colorStops 배열 등) 는 array replace 됨
+  //   - 기존 부가 필드 (rotation 등) 가 새 patch 에 없으면 유지 — partial update 의도
+  // 이전 2-op (null + new) 방식은 중간 null 상태가 onchange / 3D texture trigger 해
+  // 크래시 유발 → 제거. 정확한 colorStops 출력으로 stale 필드 문제 자체가 해결됐음.
+  for (const refid of refids) {
+    ops.push({ op: 'modify', refid, patch })
+  }
+  return { ops, errors }
+}
+
+/**
+ * input → fillStyle patch 객체 생성.
+ *
+ * Mode 명시 시: fillStyle 통째 교체 → patch = { fillStyle: {...새 객체} }
+ * Mode 미지정 시: 기존 fillStyle 위에 색/opacity 만 병합 → patch = { fillStyle: { ...덮어쓸 필드 } }
+ *   (apply-patch 의 deep-merge 가 처리. fillStyle 이 객체라면.)
+ *
+ * mode='none' 의 경우 fillStyle 을 falsy 로 — 빈 객체 또는 type:'none' 명시.
+ */
+function buildFillPatch(input: SetFillInput): { fillStyle: any } | null {
+  const { mode } = input
+
+  if (mode === 'none') {
+    // fillStyle 제거 의도 — null 시맨틱 활용 (apply-patch 가 키 자체를 delete).
+    // drawer/fill.ts: fillStyle 없으면 falsy → 채우지 않음.
+    return { fillStyle: null as any }
+  }
+
+  if (mode === 'solid') {
+    // things-scene drawer/fill.ts:17 — fillStyle 이 string 이면 그대로 색상.
+    // 객체 형식 {type:'solid', color} 은 인터페이스에만 있는 stale.
+    // opacity 는 색상에 alpha 채널로 embedding (rgba).
+    const color = input.color ? normalizeColor(input.color) : undefined
+    if (!color) return null
+    let fillStyle: string = color
+    if (typeof input.opacity === 'number' && input.opacity < 1) {
+      fillStyle = withAlpha(color, input.opacity)
+    }
+    return { fillStyle: fillStyle as any }
+  }
+
+  if (mode === 'gradient') {
+    let stops = input.colorStops
+    // stops 미지정 시 — color 와 자동 생성 어두운 변형 (간단한 fallback)
+    if ((!stops || stops.length === 0) && input.color) {
+      const hex = normalizeColor(input.color)
+      if (hex) {
+        stops = [
+          { color: hex, position: 0 },
+          { color: darken(hex, 0.4), position: 1 }
+        ]
+      }
+    }
+    if (!stops || stops.length < 2) {
+      // gradient 인데 stops 부족 — 호출자가 명시 안 하면 만들어 주지 않음
+      return null
+    }
+    // things-scene 의 실제 필드: colorStops [{position, color}]
+    const colorStops = stops
+      .map(s => ({ position: s.position, color: normalizeColor(s.color)! }))
+      .filter(s => !!s.color)
+    if (colorStops.length < 2) return null
+    // rotation: 항상 명시 — drawer/fill.ts 가 default 없이 fillStyle.rotation 을 직접
+    // Math.cos / Math.sin 에 넘기므로 undefined 면 NaN → createLinearGradient 크래시.
+    // AI/사용자는 degrees 로 표현, 내부에서 라디안 변환. 미지정 시 0 default.
+    const rotationRad =
+      typeof input.rotation === 'number' ? (input.rotation * Math.PI) / 180 : 0
+    const fs: any = {
+      type: 'gradient',
+      gradientType: input.gradientType ?? 'linear',
+      colorStops,
+      rotation: rotationRad
+    }
+    if (typeof input.opacity === 'number') fs.opacity = input.opacity
+    return { fillStyle: fs }
+  }
+
+  if (mode === 'pattern') {
+    if (!input.image) return null
+    // things-scene 의 실제 pattern fillStyle (drawer/fill.ts:95~)
+    const fs: any = { type: 'pattern', image: input.image }
+    if (input.color) {
+      const c = normalizeColor(input.color)
+      if (c) fs.color = c // 패턴 뒤 배경색 (drawer 가 사용)
+    }
+    if (input.fitPattern !== undefined) fs.fitPattern = input.fitPattern
+    if (input.noRepeat !== undefined) fs.noRepeat = input.noRepeat
+    if (input.align) fs.align = input.align
+    if (typeof input.offsetX === 'number') fs.offsetX = input.offsetX
+    if (typeof input.offsetY === 'number') fs.offsetY = input.offsetY
+    if (typeof input.patternWidth === 'number') fs.width = input.patternWidth
+    if (typeof input.patternHeight === 'number') fs.height = input.patternHeight
+    if (typeof input.opacity === 'number') fs.opacity = input.opacity
+    return { fillStyle: fs }
+  }
+
+  // mode 미지정 — 부분 update.
+  // things-scene 의 fillStyle 은 string (solid) 또는 object (gradient/pattern).
+  // 부분 update 에서 색만 들어오면 solid string 으로 통째 set (가장 흔한 케이스).
+  // (gradient 의 부분 update 는 mode='gradient' 명시 사용 — 모드 명시 시 full replace.)
+  if (input.color) {
+    const c = normalizeColor(input.color)
+    if (!c) return null
+    const fillStyle =
+      typeof input.opacity === 'number' && input.opacity < 1 ? withAlpha(c, input.opacity) : c
+    return { fillStyle: fillStyle as any }
+  }
+  // color 없이 opacity 만 — 부분 update 어려움 (string 인지 object 인지 모름).
+  // 명확한 의도가 있으면 mode 명시 권장. 일단 무동작 (null).
+  return null
+}
+
+/**
+ * hex / 명명 색 + alpha (0..1) → rgba(r,g,b,a) 문자열.
+ * Canvas API 의 fillStyle 은 rgba string 그대로 사용 가능.
+ */
+function withAlpha(hexOrName: string, alpha: number): string {
+  // transparent
+  if (hexOrName === 'transparent') return 'rgba(0,0,0,0)'
+  // hex 예상 (#rrggbb)
+  if (hexOrName.startsWith('#') && hexOrName.length === 7) {
+    const r = parseInt(hexOrName.slice(1, 3), 16)
+    const g = parseInt(hexOrName.slice(3, 5), 16)
+    const b = parseInt(hexOrName.slice(5, 7), 16)
+    return `rgba(${r},${g},${b},${alpha})`
+  }
+  // 다른 형식이면 색을 그대로 두고 alpha 무시 (nullable 안전)
+  return hexOrName
+}
+
+/**
+ * 단순 hex 색상 어둡게 — gradient 자동 생성 시 fallback 두 번째 stop 용.
+ * lightness 기반 정확도 < HSL 변환이 정확하지만 의존성 줄이려 RGB linear blend 로 대체.
+ */
+function darken(hex: string, amount: number): string {
+  const p = parseColor(hex)
+  if (!p || p.hex === 'transparent') return hex
+  const h = p.hex.slice(1) // remove #
+  const r = parseInt(h.slice(0, 2), 16)
+  const g = parseInt(h.slice(2, 4), 16)
+  const b = parseInt(h.slice(4, 6), 16)
+  const factor = 1 - Math.max(0, Math.min(1, amount))
+  const r2 = Math.round(r * factor)
+  const g2 = Math.round(g * factor)
+  const b2 = Math.round(b * factor)
+  const toHex = (n: number) => n.toString(16).padStart(2, '0')
+  return `#${toHex(r2)}${toHex(g2)}${toHex(b2)}`
+}