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

package/dist-client/server/service/prefab-registry.js

@@ -0,0 +1,252 @@
+const REGISTRY = new Map();
+/**
+ * Prefab 등록. 같은 name 은 덮어씀 (호스트가 자기 prefab 으로 default 를 교체 가능).
+ */
+export function registerBoardPrefab(prefab) {
+    if (!prefab || typeof prefab.name !== 'string' || prefab.name.length === 0) {
+        throw new Error('registerBoardPrefab: prefab.name is required');
+    }
+    if (typeof prefab.build !== 'function') {
+        throw new Error(`registerBoardPrefab(${prefab.name}): build() is required`);
+    }
+    REGISTRY.set(prefab.name, prefab);
+}
+/** 이름으로 조회. 없으면 undefined. */
+export function findBoardPrefab(name) {
+    return REGISTRY.get(name);
+}
+/** 등록된 prefab 의 메타데이터 (build 함수 제외) — getAvailablePrefabs 결과용. */
+export function listBoardPrefabs(filter) {
+    const items = [];
+    for (const p of REGISTRY.values()) {
+        if (filter?.category && p.category !== filter.category)
+            continue;
+        if (filter?.keywordPattern) {
+            const needle = filter.keywordPattern.toLowerCase();
+            const haystack = [
+                p.name,
+                p.description,
+                ...(p.keywords ?? [])
+            ]
+                .join(' ')
+                .toLowerCase();
+            if (!haystack.includes(needle))
+                continue;
+        }
+        items.push({
+            name: p.name,
+            category: p.category,
+            description: p.description,
+            keywords: p.keywords,
+            defaultSize: p.defaultSize
+        });
+    }
+    return items;
+}
+/** 테스트용 — 등록 상태 초기화. */
+export function clearBoardPrefabsForTest() {
+    REGISTRY.clear();
+}
+// ── 초기 예시 prefab ─────────────────────────────────────────────
+//
+// 패키지 차원 default — 진짜 polished 디자인은 operato / 도메인 패키지에서 register.
+// 여기서는 architecture 데모 + LLM 이 선택할 후보가 0 이 되지 않도록 최소 set.
+/**
+ * monitor-card — 라벨 + 큰 숫자값 + 부제 의 모니터링 타일.
+ * 가장 흔한 대시보드 단위. AGV 배터리 / 온도 / 가동률 등 한 줄 KPI 표시.
+ */
+const MONITOR_CARD = {
+    name: 'monitor-card',
+    category: 'monitoring',
+    description: 'KPI 모니터링 카드 — 상단에 라벨, 중앙에 큰 값, 하단에 부제. 단일 수치 한 줄 표시 (온도/가동률/배터리 등).',
+    keywords: ['모니터링', 'kpi', '카드', '값', 'value', 'card'],
+    defaultSize: { width: 200, height: 120 },
+    build(opts) {
+        const w = opts.width ?? 200;
+        const h = opts.height ?? 120;
+        const title = typeof opts.title === 'string' ? opts.title : 'Label';
+        const value = typeof opts.value === 'string' ? opts.value : '0';
+        const subtitle = typeof opts.subtitle === 'string' ? opts.subtitle : '';
+        const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#1a2332';
+        const accent = typeof opts.accent === 'string' ? opts.accent : '#4fc3f7';
+        return {
+            type: 'group',
+            left: opts.left,
+            top: opts.top,
+            width: w,
+            height: h,
+            name: 'monitor-card',
+            components: [
+                {
+                    type: 'rect',
+                    left: 0,
+                    top: 0,
+                    width: w,
+                    height: h,
+                    fillStyle: fill,
+                    strokeStyle: '#2a3a52',
+                    strokeWidth: 1
+                },
+                {
+                    type: 'text',
+                    left: 12,
+                    top: 10,
+                    width: w - 24,
+                    height: 16,
+                    text: title,
+                    fillStyle: '#94a3b8',
+                    fontSize: 12
+                },
+                {
+                    type: 'text',
+                    left: 12,
+                    top: 32,
+                    width: w - 24,
+                    height: h - 60,
+                    text: value,
+                    fillStyle: accent,
+                    fontSize: 32,
+                    fontWeight: 'bold'
+                },
+                {
+                    type: 'text',
+                    left: 12,
+                    top: h - 22,
+                    width: w - 24,
+                    height: 14,
+                    text: subtitle,
+                    fillStyle: '#64748b',
+                    fontSize: 11
+                }
+            ]
+        };
+    }
+};
+/**
+ * gauge-panel — 라벨 붙은 원형 게이지 패널.
+ * gauge-circle 컴포넌트가 things-scene에 있음을 전제. 진짜 게이지가 없으면 폴백으로 circle.
+ */
+const GAUGE_PANEL = {
+    name: 'gauge-panel',
+    category: 'monitoring',
+    description: '원형 게이지 + 라벨. 0~100 (또는 min/max) 범위의 단일 값 시각화 (CPU, 압력, 충전 등).',
+    keywords: ['게이지', 'gauge', '원형', '미터', 'meter', '센서'],
+    defaultSize: { width: 180, height: 200 },
+    build(opts) {
+        const w = opts.width ?? 180;
+        const h = opts.height ?? 200;
+        const title = typeof opts.title === 'string' ? opts.title : 'Gauge';
+        const value = typeof opts.value === 'number' ? opts.value : 50;
+        const min = typeof opts.min === 'number' ? opts.min : 0;
+        const max = typeof opts.max === 'number' ? opts.max : 100;
+        const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#1a2332';
+        return {
+            type: 'group',
+            left: opts.left,
+            top: opts.top,
+            width: w,
+            height: h,
+            name: 'gauge-panel',
+            components: [
+                {
+                    type: 'rect',
+                    left: 0,
+                    top: 0,
+                    width: w,
+                    height: h,
+                    fillStyle: fill,
+                    strokeStyle: '#2a3a52',
+                    strokeWidth: 1
+                },
+                {
+                    // gauge-circle 이 등록되어 있을 때 사용. 미등록 환경에서는 정상 추가는 되나
+                    // render 가 fallback. operato 패키지에서 normalizeComponent 가 default 채움.
+                    type: 'gauge-circle',
+                    left: 20,
+                    top: 20,
+                    width: w - 40,
+                    height: w - 40, // 정사각형 게이지
+                    value,
+                    min,
+                    max
+                },
+                {
+                    type: 'text',
+                    left: 12,
+                    top: h - 28,
+                    width: w - 24,
+                    height: 18,
+                    text: title,
+                    fillStyle: '#94a3b8',
+                    fontSize: 13
+                }
+            ]
+        };
+    }
+};
+/**
+ * stat-tile — 컬러 타일 + 큰 숫자. monitor-card 보다 강조된 단일 수치 표시.
+ * 사용자 시선이 가장 먼저 가는 위치에 배치.
+ */
+const STAT_TILE = {
+    name: 'stat-tile',
+    category: 'kpi',
+    description: '강조 컬러 타일 + 큰 숫자값 + 작은 라벨. monitor-card 보다 시각적 무게가 강함 — 핵심 KPI 1~3 개에만 사용.',
+    keywords: ['타일', 'tile', 'kpi', '강조', 'highlight'],
+    defaultSize: { width: 220, height: 140 },
+    build(opts) {
+        const w = opts.width ?? 220;
+        const h = opts.height ?? 140;
+        const title = typeof opts.title === 'string' ? opts.title : 'Total';
+        const value = typeof opts.value === 'string' ? opts.value : '0';
+        const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#0ea5e9';
+        const textColor = typeof opts.textColor === 'string' ? opts.textColor : '#ffffff';
+        return {
+            type: 'group',
+            left: opts.left,
+            top: opts.top,
+            width: w,
+            height: h,
+            name: 'stat-tile',
+            components: [
+                {
+                    type: 'rect',
+                    left: 0,
+                    top: 0,
+                    width: w,
+                    height: h,
+                    fillStyle: fill,
+                    strokeStyle: 'transparent',
+                    strokeWidth: 0
+                },
+                {
+                    type: 'text',
+                    left: 16,
+                    top: 16,
+                    width: w - 32,
+                    height: 18,
+                    text: title,
+                    fillStyle: textColor,
+                    fontSize: 13,
+                    opacity: 0.85
+                },
+                {
+                    type: 'text',
+                    left: 16,
+                    top: 40,
+                    width: w - 32,
+                    height: h - 56,
+                    text: value,
+                    fillStyle: textColor,
+                    fontSize: 40,
+                    fontWeight: 'bold'
+                }
+            ]
+        };
+    }
+};
+// 모듈 로드 시 자동 등록 (idempotent — 다시 register 해도 덮어쓰기)
+registerBoardPrefab(MONITOR_CARD);
+registerBoardPrefab(GAUGE_PANEL);
+registerBoardPrefab(STAT_TILE);
+//# sourceMappingURL=prefab-registry.js.map

package/dist-client/server/service/prefab-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefab-registry.js","sourceRoot":"","sources":["../../../server/service/prefab-registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Board Prefab Registry — 고품질 복합 컴포넌트 프리셋 카탈로그.\n *\n * 의도:\n *   - 보드 설계자가 실제로 원하는 단위는 rect/circle 같은 원시 도형이 아닌\n *     \"온도 모니터링 카드\", \"AGV 배터리 상태판\", \"공정 KPI 타일\" 같은 디자인된\n *     복합 모듈. 이 layer 가 그 단위를 시스템 차원에서 제공.\n *   - LLM 은 자유 작곡하지 않고 검증된 prefab 카탈로그에서 고름 → 결과 일관성 ↑,\n *     비용 ↓, 진입 장벽 낮춤.\n *\n * 통합:\n *   - 호스트 (operato 등) 가 패키지 로드 시 `registerBoardPrefab` 으로 자기 prefab\n *     등록. board-ai 는 registry 만 관리. 초기 예시 prefab 몇 개를 자체 등록 — 진짜\n *     디자인된 prefab 은 별도 패키지에서 추가.\n *   - LLM 도구 통합:\n *       getAvailablePrefabs (read)  → registry 의 메타데이터 반환\n *       addPrefab (write)           → name + 좌표/옵션 → 단일 BoardComponent (group)\n *\n * 식별자:\n *   - `name` 은 unique. 같은 name 으로 register 시 override (호스트가 자기 prefab 을\n *     커스터마이징할 수 있도록 의도적 허용).\n *   - 카테고리는 free-form string — registry 가 강제하지 않음. 사용자/운영 자율.\n */\nimport type { BoardComponent } from '@things-factory/board-import'\n\nexport interface BoardPrefab {\n  /** Unique 식별자 — 'kebab-case' 권장 */\n  name: string\n\n  /** 자유 분류 — 'monitoring' | 'control' | 'decoration' | 'kpi' 등 */\n  category?: string\n\n  /** 사용자 / LLM 이 이해할 한 문장 설명 */\n  description: string\n\n  /**\n   * 자연어 매칭 힌트 — '온도', '게이지', '카드' 등.\n   * findComponents 같은 검색이 아니라 LLM 의 의도 매칭용 메타데이터.\n   */\n  keywords?: string[]\n\n  /** 권장 기본 크기 — options 에 width/height 미지정 시 사용 */\n  defaultSize?: { width: number; height: number }\n\n  /**\n   * Prefab 의 컴포넌트 트리를 만든다. 단일 `BoardComponent` 반환 — 보통 group 타입이며\n   * `components` 자식을 가진다. 단일 add op 으로 매핑되어 undo 도 한 단위.\n   *\n   * options:\n   *   - left/top: anchor 좌표 (top-left 원점)\n   *   - width/height: 크기 (없으면 defaultSize)\n   *   - 추가 키: prefab 별 자유 (title 텍스트, 색상 등)\n   */\n  build(options: PrefabBuildOptions): BoardComponent\n}\n\nexport interface PrefabBuildOptions {\n  left: number\n  top: number\n  width?: number\n  height?: number\n  /** prefab 별 커스터마이징 — 자유 형태 */\n  [k: string]: any\n}\n\nconst REGISTRY = new Map<string, BoardPrefab>()\n\n/**\n * Prefab 등록. 같은 name 은 덮어씀 (호스트가 자기 prefab 으로 default 를 교체 가능).\n */\nexport function registerBoardPrefab(prefab: BoardPrefab): void {\n  if (!prefab || typeof prefab.name !== 'string' || prefab.name.length === 0) {\n    throw new Error('registerBoardPrefab: prefab.name is required')\n  }\n  if (typeof prefab.build !== 'function') {\n    throw new Error(`registerBoardPrefab(${prefab.name}): build() is required`)\n  }\n  REGISTRY.set(prefab.name, prefab)\n}\n\n/** 이름으로 조회. 없으면 undefined. */\nexport function findBoardPrefab(name: string): BoardPrefab | undefined {\n  return REGISTRY.get(name)\n}\n\n/** 등록된 prefab 의 메타데이터 (build 함수 제외) — getAvailablePrefabs 결과용. */\nexport function listBoardPrefabs(filter?: {\n  category?: string\n  keywordPattern?: string\n}): Array<Omit<BoardPrefab, 'build'>> {\n  const items: Array<Omit<BoardPrefab, 'build'>> = []\n  for (const p of REGISTRY.values()) {\n    if (filter?.category && p.category !== filter.category) continue\n    if (filter?.keywordPattern) {\n      const needle = filter.keywordPattern.toLowerCase()\n      const haystack = [\n        p.name,\n        p.description,\n        ...(p.keywords ?? [])\n      ]\n        .join(' ')\n        .toLowerCase()\n      if (!haystack.includes(needle)) continue\n    }\n    items.push({\n      name: p.name,\n      category: p.category,\n      description: p.description,\n      keywords: p.keywords,\n      defaultSize: p.defaultSize\n    })\n  }\n  return items\n}\n\n/** 테스트용 — 등록 상태 초기화. */\nexport function clearBoardPrefabsForTest(): void {\n  REGISTRY.clear()\n}\n\n// ── 초기 예시 prefab ─────────────────────────────────────────────\n//\n// 패키지 차원 default — 진짜 polished 디자인은 operato / 도메인 패키지에서 register.\n// 여기서는 architecture 데모 + LLM 이 선택할 후보가 0 이 되지 않도록 최소 set.\n\n/**\n * monitor-card — 라벨 + 큰 숫자값 + 부제 의 모니터링 타일.\n * 가장 흔한 대시보드 단위. AGV 배터리 / 온도 / 가동률 등 한 줄 KPI 표시.\n */\nconst MONITOR_CARD: BoardPrefab = {\n  name: 'monitor-card',\n  category: 'monitoring',\n  description:\n    'KPI 모니터링 카드 — 상단에 라벨, 중앙에 큰 값, 하단에 부제. 단일 수치 한 줄 표시 (온도/가동률/배터리 등).',\n  keywords: ['모니터링', 'kpi', '카드', '값', 'value', 'card'],\n  defaultSize: { width: 200, height: 120 },\n  build(opts) {\n    const w = opts.width ?? 200\n    const h = opts.height ?? 120\n    const title = typeof opts.title === 'string' ? opts.title : 'Label'\n    const value = typeof opts.value === 'string' ? opts.value : '0'\n    const subtitle = typeof opts.subtitle === 'string' ? opts.subtitle : ''\n    const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#1a2332'\n    const accent = typeof opts.accent === 'string' ? opts.accent : '#4fc3f7'\n\n    return {\n      type: 'group',\n      left: opts.left,\n      top: opts.top,\n      width: w,\n      height: h,\n      name: 'monitor-card',\n      components: [\n        {\n          type: 'rect',\n          left: 0,\n          top: 0,\n          width: w,\n          height: h,\n          fillStyle: fill,\n          strokeStyle: '#2a3a52',\n          strokeWidth: 1\n        },\n        {\n          type: 'text',\n          left: 12,\n          top: 10,\n          width: w - 24,\n          height: 16,\n          text: title,\n          fillStyle: '#94a3b8',\n          fontSize: 12\n        },\n        {\n          type: 'text',\n          left: 12,\n          top: 32,\n          width: w - 24,\n          height: h - 60,\n          text: value,\n          fillStyle: accent,\n          fontSize: 32,\n          fontWeight: 'bold'\n        },\n        {\n          type: 'text',\n          left: 12,\n          top: h - 22,\n          width: w - 24,\n          height: 14,\n          text: subtitle,\n          fillStyle: '#64748b',\n          fontSize: 11\n        }\n      ]\n    } as any as BoardComponent\n  }\n}\n\n/**\n * gauge-panel — 라벨 붙은 원형 게이지 패널.\n * gauge-circle 컴포넌트가 things-scene에 있음을 전제. 진짜 게이지가 없으면 폴백으로 circle.\n */\nconst GAUGE_PANEL: BoardPrefab = {\n  name: 'gauge-panel',\n  category: 'monitoring',\n  description:\n    '원형 게이지 + 라벨. 0~100 (또는 min/max) 범위의 단일 값 시각화 (CPU, 압력, 충전 등).',\n  keywords: ['게이지', 'gauge', '원형', '미터', 'meter', '센서'],\n  defaultSize: { width: 180, height: 200 },\n  build(opts) {\n    const w = opts.width ?? 180\n    const h = opts.height ?? 200\n    const title = typeof opts.title === 'string' ? opts.title : 'Gauge'\n    const value = typeof opts.value === 'number' ? opts.value : 50\n    const min = typeof opts.min === 'number' ? opts.min : 0\n    const max = typeof opts.max === 'number' ? opts.max : 100\n    const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#1a2332'\n\n    return {\n      type: 'group',\n      left: opts.left,\n      top: opts.top,\n      width: w,\n      height: h,\n      name: 'gauge-panel',\n      components: [\n        {\n          type: 'rect',\n          left: 0,\n          top: 0,\n          width: w,\n          height: h,\n          fillStyle: fill,\n          strokeStyle: '#2a3a52',\n          strokeWidth: 1\n        },\n        {\n          // gauge-circle 이 등록되어 있을 때 사용. 미등록 환경에서는 정상 추가는 되나\n          // render 가 fallback. operato 패키지에서 normalizeComponent 가 default 채움.\n          type: 'gauge-circle',\n          left: 20,\n          top: 20,\n          width: w - 40,\n          height: w - 40, // 정사각형 게이지\n          value,\n          min,\n          max\n        },\n        {\n          type: 'text',\n          left: 12,\n          top: h - 28,\n          width: w - 24,\n          height: 18,\n          text: title,\n          fillStyle: '#94a3b8',\n          fontSize: 13\n        }\n      ]\n    } as any as BoardComponent\n  }\n}\n\n/**\n * stat-tile — 컬러 타일 + 큰 숫자. monitor-card 보다 강조된 단일 수치 표시.\n * 사용자 시선이 가장 먼저 가는 위치에 배치.\n */\nconst STAT_TILE: BoardPrefab = {\n  name: 'stat-tile',\n  category: 'kpi',\n  description:\n    '강조 컬러 타일 + 큰 숫자값 + 작은 라벨. monitor-card 보다 시각적 무게가 강함 — 핵심 KPI 1~3 개에만 사용.',\n  keywords: ['타일', 'tile', 'kpi', '강조', 'highlight'],\n  defaultSize: { width: 220, height: 140 },\n  build(opts) {\n    const w = opts.width ?? 220\n    const h = opts.height ?? 140\n    const title = typeof opts.title === 'string' ? opts.title : 'Total'\n    const value = typeof opts.value === 'string' ? opts.value : '0'\n    const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#0ea5e9'\n    const textColor = typeof opts.textColor === 'string' ? opts.textColor : '#ffffff'\n\n    return {\n      type: 'group',\n      left: opts.left,\n      top: opts.top,\n      width: w,\n      height: h,\n      name: 'stat-tile',\n      components: [\n        {\n          type: 'rect',\n          left: 0,\n          top: 0,\n          width: w,\n          height: h,\n          fillStyle: fill,\n          strokeStyle: 'transparent',\n          strokeWidth: 0\n        },\n        {\n          type: 'text',\n          left: 16,\n          top: 16,\n          width: w - 32,\n          height: 18,\n          text: title,\n          fillStyle: textColor,\n          fontSize: 13,\n          opacity: 0.85\n        },\n        {\n          type: 'text',\n          left: 16,\n          top: 40,\n          width: w - 32,\n          height: h - 56,\n          text: value,\n          fillStyle: textColor,\n          fontSize: 40,\n          fontWeight: 'bold'\n        }\n      ]\n    } as any as BoardComponent\n  }\n}\n\n// 모듈 로드 시 자동 등록 (idempotent — 다시 register 해도 덮어쓰기)\nregisterBoardPrefab(MONITOR_CARD)\nregisterBoardPrefab(GAUGE_PANEL)\nregisterBoardPrefab(STAT_TILE)\n"]}

package/dist-client/server/service/styling/clear-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * clearStyle — 특정 styling aspect 들을 초기화 (제거).
+ *
+ * preset 적용 전 / 데이터 바인딩 적용 전 깨끗한 상태로 돌리기 위한 helper.
+ */
+import type { BoardEditOp } from '../types';
+export interface ClearStyleInput {
+    refids: number[];
+    aspects: Array<'fill' | 'stroke' | 'shadow' | 'material' | 'font' | 'opacity'>;
+}
+export interface OpsResult {
+    ops: BoardEditOp[];
+    errors: string[];
+}
+export declare function buildClearStyleOps(input: ClearStyleInput): OpsResult;

package/dist-client/server/service/styling/clear-tools.js

@@ -0,0 +1,50 @@
+const ASPECT_TO_PATCH = {
+    fill: { fillStyle: { type: 'none' } },
+    // stroke: strokeStyle 는 색상 문자열 (top-level), 굵기는 lineWidth (top-level).
+    // 굵기 0 으로 윤곽선 시각 제거 (색은 유지). 완전 제거는 strokeStyle: null 동시 set.
+    stroke: { lineWidth: 0 },
+    shadow: { shadow: { blur: 0, color: 'transparent' } },
+    material: { material3d: { preset: 'default' } },
+    // font: null = delete 시맨틱 (apply-patch.ts:233-243). 핵심 폰트 키 모두 제거 →
+    // component 가 기본 폰트 동작으로 복귀. 보존이 의도라면 font aspect 미선택.
+    font: {
+        fontSize: null,
+        fontFamily: null,
+        fontColor: null,
+        fontWeight: null,
+        fontStyle: null
+    },
+    opacity: { alpha: 1 }
+};
+export function buildClearStyleOps(input) {
+    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'] };
+    if (!Array.isArray(input.aspects) || input.aspects.length === 0) {
+        return { ops: [], errors: ['aspects must be a non-empty array'] };
+    }
+    const valid = ['fill', 'stroke', 'shadow', 'material', 'font', 'opacity'];
+    const unknown = input.aspects.filter(a => !valid.includes(a));
+    if (unknown.length > 0) {
+        return {
+            ops: [],
+            errors: [`Unknown aspect(s): ${unknown.join(', ')}. Valid: ${valid.join('/')}`]
+        };
+    }
+    // 모든 aspect 의 patch 를 하나로 병합 (한 refid 당 하나의 modify op)
+    const merged = {};
+    for (const a of input.aspects) {
+        Object.assign(merged, ASPECT_TO_PATCH[a]);
+    }
+    if (Object.keys(merged).length === 0) {
+        return { ops: [], errors: ['No effective patch — try other aspects'] };
+    }
+    return {
+        ops: refids.map(refid => ({ op: 'modify', refid, patch: merged })),
+        errors: []
+    };
+}
+//# sourceMappingURL=clear-tools.js.map

package/dist-client/server/service/styling/clear-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-tools.js","sourceRoot":"","sources":["../../../../server/service/styling/clear-tools.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * clearStyle — 특정 styling aspect 들을 초기화 (제거).\n *\n * preset 적용 전 / 데이터 바인딩 적용 전 깨끗한 상태로 돌리기 위한 helper.\n */\nimport type { BoardEditOp } from '../types'\n\nexport interface ClearStyleInput {\n  refids: number[]\n  aspects: Array<'fill' | 'stroke' | 'shadow' | 'material' | 'font' | 'opacity'>\n}\n\nexport interface OpsResult {\n  ops: BoardEditOp[]\n  errors: string[]\n}\n\nconst ASPECT_TO_PATCH: Record<string, any> = {\n  fill: { fillStyle: { type: 'none' } },\n  // stroke: strokeStyle 는 색상 문자열 (top-level), 굵기는 lineWidth (top-level).\n  // 굵기 0 으로 윤곽선 시각 제거 (색은 유지). 완전 제거는 strokeStyle: null 동시 set.\n  stroke: { lineWidth: 0 },\n  shadow: { shadow: { blur: 0, color: 'transparent' } },\n  material: { material3d: { preset: 'default' } },\n  // font: null = delete 시맨틱 (apply-patch.ts:233-243). 핵심 폰트 키 모두 제거 →\n  // component 가 기본 폰트 동작으로 복귀. 보존이 의도라면 font aspect 미선택.\n  font: {\n    fontSize: null,\n    fontFamily: null,\n    fontColor: null,\n    fontWeight: null,\n    fontStyle: null\n  },\n  opacity: { alpha: 1 }\n}\n\nexport function buildClearStyleOps(input: ClearStyleInput): OpsResult {\n  if (!Array.isArray(input.refids) || input.refids.length === 0) {\n    return { ops: [], errors: ['refids must be a non-empty array'] }\n  }\n  const refids = input.refids.filter(n => typeof n === 'number' && Number.isFinite(n))\n  if (refids.length === 0) return { ops: [], errors: ['No valid numeric refids'] }\n\n  if (!Array.isArray(input.aspects) || input.aspects.length === 0) {\n    return { ops: [], errors: ['aspects must be a non-empty array'] }\n  }\n  const valid = ['fill', 'stroke', 'shadow', 'material', 'font', 'opacity']\n  const unknown = input.aspects.filter(a => !valid.includes(a))\n  if (unknown.length > 0) {\n    return {\n      ops: [],\n      errors: [`Unknown aspect(s): ${unknown.join(', ')}. Valid: ${valid.join('/')}`]\n    }\n  }\n\n  // 모든 aspect 의 patch 를 하나로 병합 (한 refid 당 하나의 modify op)\n  const merged: any = {}\n  for (const a of input.aspects) {\n    Object.assign(merged, ASPECT_TO_PATCH[a])\n  }\n  if (Object.keys(merged).length === 0) {\n    return { ops: [], errors: ['No effective patch — try other aspects'] }\n  }\n\n  return {\n    ops: refids.map(refid => ({ op: 'modify', refid, patch: merged })),\n    errors: []\n  }\n}\n"]}

package/dist-client/server/service/styling/color-utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Color 파싱 / 정규화 유틸 — styling tool 들이 공통으로 사용.
+ *
+ * AI 가 자연어로 색상 표현하는 다양한 형태를 받아 표준 hex 또는 rgba 로 변환.
+ *
+ * 지원 입력:
+ *   - hex 6자리:  '#ff0000', '#FF0000'
+ *   - hex 3자리:  '#f00'  (→ '#ff0000')
+ *   - hex 8자리:  '#ff0000ff' (alpha 포함)
+ *   - rgb / rgba: 'rgb(255,0,0)', 'rgba(255,0,0,0.5)'
+ *   - CSS named: 'red', 'transparent', ...
+ *   - 시맨틱 alias: 'warm-red', 'forest-green', ...
+ *
+ * 출력 형태:
+ *   - normalizeColor(): 표준 hex (#rrggbb), opacity 는 별개로 분리 반환
+ *   - validateColor():  유효성만 체크 (boolean + 에러 메시지)
+ */
+/** Parse 결과 — color 와 alpha 분리. alpha 는 0..1. */
+export interface ParsedColor {
+    /** 표준 hex (#rrggbb, 소문자) 또는 'transparent' */
+    hex: string;
+    /** Alpha 채널 0..1. transparent 면 0, 명시 alpha 없으면 1. */
+    alpha: number;
+}
+/**
+ * 색상 입력을 정규 hex + alpha 로 변환.
+ * 잘못된 입력은 null — 호출자가 에러 처리.
+ */
+export declare function parseColor(input: string | null | undefined): ParsedColor | null;
+/**
+ * 단순 검증 — 정규화 가능 여부만.
+ * 에러 메시지에 정정 제안 포함 가능.
+ */
+export declare function validateColor(input: string | null | undefined): {
+    valid: boolean;
+    error?: string;
+    suggestion?: string;
+};
+/**
+ * 색상을 hex 문자열로 정규화 (저장용).
+ * 실패 시 null.
+ */
+export declare function normalizeColor(input: string | null | undefined): string | null;

package/dist-client/server/service/styling/color-utils.js

@@ -0,0 +1,205 @@
+/**
+ * Color 파싱 / 정규화 유틸 — styling tool 들이 공통으로 사용.
+ *
+ * AI 가 자연어로 색상 표현하는 다양한 형태를 받아 표준 hex 또는 rgba 로 변환.
+ *
+ * 지원 입력:
+ *   - hex 6자리:  '#ff0000', '#FF0000'
+ *   - hex 3자리:  '#f00'  (→ '#ff0000')
+ *   - hex 8자리:  '#ff0000ff' (alpha 포함)
+ *   - rgb / rgba: 'rgb(255,0,0)', 'rgba(255,0,0,0.5)'
+ *   - CSS named: 'red', 'transparent', ...
+ *   - 시맨틱 alias: 'warm-red', 'forest-green', ...
+ *
+ * 출력 형태:
+ *   - normalizeColor(): 표준 hex (#rrggbb), opacity 는 별개로 분리 반환
+ *   - validateColor():  유효성만 체크 (boolean + 에러 메시지)
+ */
+/** CSS named colors → hex (자주 쓰는 것만, 필요 시 확장) */
+const NAMED_COLORS = {
+    // 무채
+    white: '#ffffff',
+    black: '#000000',
+    gray: '#808080',
+    grey: '#808080',
+    silver: '#c0c0c0',
+    // 기본 컬러
+    red: '#ff0000',
+    green: '#008000',
+    blue: '#0000ff',
+    yellow: '#ffff00',
+    cyan: '#00ffff',
+    magenta: '#ff00ff',
+    orange: '#ffa500',
+    purple: '#800080',
+    pink: '#ffc0cb',
+    brown: '#a52a2a',
+    // 자주 쓰는 변형
+    navy: '#000080',
+    teal: '#008080',
+    lime: '#00ff00',
+    olive: '#808000',
+    maroon: '#800000',
+    // 투명
+    transparent: 'transparent'
+};
+/**
+ * 시맨틱 컬러 alias — AI 가 자연어 표현 사용 가능.
+ * Material 3 기반 톤 (brightness 적당, saturation 풍부).
+ */
+const SEMANTIC_COLORS = {
+    // warm reds
+    'warm-red': '#e74c3c',
+    'soft-red': '#ef4444',
+    'deep-red': '#b91c1c',
+    'dark-red': '#7f1d1d',
+    // greens
+    'forest-green': '#228b22',
+    'mint-green': '#10b981',
+    'olive-green': '#65a30d',
+    'lime-green': '#84cc16',
+    // blues
+    'sky-blue': '#0ea5e9',
+    'navy-blue': '#1e40af',
+    'royal-blue': '#3b82f6',
+    'powder-blue': '#bfdbfe',
+    // yellows / oranges
+    'amber': '#f59e0b',
+    'sunset-orange': '#f97316',
+    'gold': '#eab308',
+    'mustard': '#ca8a04',
+    // purples
+    'violet': '#7c3aed',
+    'lavender': '#c4b5fd',
+    // grays
+    'slate': '#64748b',
+    'charcoal': '#374151',
+    'cool-gray': '#6b7280',
+    'warm-gray': '#78716c',
+    // 시맨틱 의도
+    success: '#22c55e',
+    warning: '#f59e0b',
+    error: '#ef4444',
+    info: '#3b82f6'
+};
+/**
+ * 색상 입력을 정규 hex + alpha 로 변환.
+ * 잘못된 입력은 null — 호출자가 에러 처리.
+ */
+export function parseColor(input) {
+    if (typeof input !== 'string')
+        return null;
+    const s = input.trim().toLowerCase();
+    if (s.length === 0)
+        return null;
+    // transparent
+    if (s === 'transparent' || s === 'none') {
+        return { hex: 'transparent', alpha: 0 };
+    }
+    // hex
+    if (s.startsWith('#')) {
+        return parseHex(s);
+    }
+    // rgb / rgba
+    const rgbMatch = s.match(/^rgba?\s*\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/);
+    if (rgbMatch) {
+        const r = clampByte(rgbMatch[1]);
+        const g = clampByte(rgbMatch[2]);
+        const b = clampByte(rgbMatch[3]);
+        const a = rgbMatch[4] !== undefined ? clampUnit(rgbMatch[4]) : 1;
+        if (r === null || g === null || b === null || a === null)
+            return null;
+        return { hex: rgbToHex(r, g, b), alpha: a };
+    }
+    // CSS named
+    if (NAMED_COLORS[s]) {
+        return parseHex(NAMED_COLORS[s]);
+    }
+    // 시맨틱 alias
+    if (SEMANTIC_COLORS[s]) {
+        return parseHex(SEMANTIC_COLORS[s]);
+    }
+    return null;
+}
+function parseHex(s) {
+    const hex = s.startsWith('#') ? s.slice(1) : s;
+    if (hex === 'transparent')
+        return { hex: 'transparent', alpha: 0 };
+    if (!/^[0-9a-f]+$/i.test(hex))
+        return null;
+    if (hex.length === 3) {
+        // #abc → #aabbcc
+        const r = hex[0] + hex[0];
+        const g = hex[1] + hex[1];
+        const b = hex[2] + hex[2];
+        return { hex: `#${r}${g}${b}`.toLowerCase(), alpha: 1 };
+    }
+    if (hex.length === 4) {
+        // #abcd → #aabbccdd
+        const r = hex[0] + hex[0];
+        const g = hex[1] + hex[1];
+        const b = hex[2] + hex[2];
+        const a = parseInt(hex[3] + hex[3], 16) / 255;
+        return { hex: `#${r}${g}${b}`.toLowerCase(), alpha: round3(a) };
+    }
+    if (hex.length === 6) {
+        return { hex: `#${hex}`.toLowerCase(), alpha: 1 };
+    }
+    if (hex.length === 8) {
+        const rgb = hex.slice(0, 6);
+        const a = parseInt(hex.slice(6, 8), 16) / 255;
+        return { hex: `#${rgb}`.toLowerCase(), alpha: round3(a) };
+    }
+    return null;
+}
+function clampByte(s) {
+    const n = Number(s);
+    if (!Number.isFinite(n) || n < 0 || n > 255)
+        return null;
+    return Math.round(n);
+}
+function clampUnit(s) {
+    const n = Number(s);
+    if (!Number.isFinite(n) || n < 0 || n > 1)
+        return null;
+    return n;
+}
+function rgbToHex(r, g, b) {
+    const h = (n) => n.toString(16).padStart(2, '0');
+    return `#${h(r)}${h(g)}${h(b)}`;
+}
+function round3(n) {
+    return Math.round(n * 1000) / 1000;
+}
+/**
+ * 단순 검증 — 정규화 가능 여부만.
+ * 에러 메시지에 정정 제안 포함 가능.
+ */
+export function validateColor(input) {
+    if (typeof input !== 'string') {
+        return { valid: false, error: 'Color must be a string.' };
+    }
+    const parsed = parseColor(input);
+    if (parsed)
+        return { valid: true };
+    // 비슷한 named color 추천
+    const lower = input.trim().toLowerCase();
+    const allKnown = [...Object.keys(NAMED_COLORS), ...Object.keys(SEMANTIC_COLORS)];
+    const close = allKnown.find(k => k.includes(lower) || lower.includes(k));
+    return {
+        valid: false,
+        error: `Invalid color: '${input}'. Use hex (#ff0000), rgb(255,0,0), or named (red, warm-red, ...).`,
+        suggestion: close
+    };
+}
+/**
+ * 색상을 hex 문자열로 정규화 (저장용).
+ * 실패 시 null.
+ */
+export function normalizeColor(input) {
+    const parsed = parseColor(input);
+    if (!parsed)
+        return null;
+    return parsed.hex;
+}
+//# sourceMappingURL=color-utils.js.map

package/dist-client/server/service/styling/color-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-utils.js","sourceRoot":"","sources":["../../../../server/service/styling/color-utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Color 파싱 / 정규화 유틸 — styling tool 들이 공통으로 사용.\n *\n * AI 가 자연어로 색상 표현하는 다양한 형태를 받아 표준 hex 또는 rgba 로 변환.\n *\n * 지원 입력:\n *   - hex 6자리:  '#ff0000', '#FF0000'\n *   - hex 3자리:  '#f00'  (→ '#ff0000')\n *   - hex 8자리:  '#ff0000ff' (alpha 포함)\n *   - rgb / rgba: 'rgb(255,0,0)', 'rgba(255,0,0,0.5)'\n *   - CSS named: 'red', 'transparent', ...\n *   - 시맨틱 alias: 'warm-red', 'forest-green', ...\n *\n * 출력 형태:\n *   - normalizeColor(): 표준 hex (#rrggbb), opacity 는 별개로 분리 반환\n *   - validateColor():  유효성만 체크 (boolean + 에러 메시지)\n */\n\n/** CSS named colors → hex (자주 쓰는 것만, 필요 시 확장) */\nconst NAMED_COLORS: Record<string, string> = {\n  // 무채\n  white: '#ffffff',\n  black: '#000000',\n  gray: '#808080',\n  grey: '#808080',\n  silver: '#c0c0c0',\n  // 기본 컬러\n  red: '#ff0000',\n  green: '#008000',\n  blue: '#0000ff',\n  yellow: '#ffff00',\n  cyan: '#00ffff',\n  magenta: '#ff00ff',\n  orange: '#ffa500',\n  purple: '#800080',\n  pink: '#ffc0cb',\n  brown: '#a52a2a',\n  // 자주 쓰는 변형\n  navy: '#000080',\n  teal: '#008080',\n  lime: '#00ff00',\n  olive: '#808000',\n  maroon: '#800000',\n  // 투명\n  transparent: 'transparent'\n}\n\n/**\n * 시맨틱 컬러 alias — AI 가 자연어 표현 사용 가능.\n * Material 3 기반 톤 (brightness 적당, saturation 풍부).\n */\nconst SEMANTIC_COLORS: Record<string, string> = {\n  // warm reds\n  'warm-red': '#e74c3c',\n  'soft-red': '#ef4444',\n  'deep-red': '#b91c1c',\n  'dark-red': '#7f1d1d',\n  // greens\n  'forest-green': '#228b22',\n  'mint-green': '#10b981',\n  'olive-green': '#65a30d',\n  'lime-green': '#84cc16',\n  // blues\n  'sky-blue': '#0ea5e9',\n  'navy-blue': '#1e40af',\n  'royal-blue': '#3b82f6',\n  'powder-blue': '#bfdbfe',\n  // yellows / oranges\n  'amber': '#f59e0b',\n  'sunset-orange': '#f97316',\n  'gold': '#eab308',\n  'mustard': '#ca8a04',\n  // purples\n  'violet': '#7c3aed',\n  'lavender': '#c4b5fd',\n  // grays\n  'slate': '#64748b',\n  'charcoal': '#374151',\n  'cool-gray': '#6b7280',\n  'warm-gray': '#78716c',\n  // 시맨틱 의도\n  success: '#22c55e',\n  warning: '#f59e0b',\n  error: '#ef4444',\n  info: '#3b82f6'\n}\n\n/** Parse 결과 — color 와 alpha 분리. alpha 는 0..1. */\nexport interface ParsedColor {\n  /** 표준 hex (#rrggbb, 소문자) 또는 'transparent' */\n  hex: string\n  /** Alpha 채널 0..1. transparent 면 0, 명시 alpha 없으면 1. */\n  alpha: number\n}\n\n/**\n * 색상 입력을 정규 hex + alpha 로 변환.\n * 잘못된 입력은 null — 호출자가 에러 처리.\n */\nexport function parseColor(input: string | null | undefined): ParsedColor | null {\n  if (typeof input !== 'string') return null\n  const s = input.trim().toLowerCase()\n  if (s.length === 0) return null\n\n  // transparent\n  if (s === 'transparent' || s === 'none') {\n    return { hex: 'transparent', alpha: 0 }\n  }\n\n  // hex\n  if (s.startsWith('#')) {\n    return parseHex(s)\n  }\n\n  // rgb / rgba\n  const rgbMatch = s.match(/^rgba?\\s*\\(\\s*([\\d.]+)\\s*,\\s*([\\d.]+)\\s*,\\s*([\\d.]+)\\s*(?:,\\s*([\\d.]+)\\s*)?\\)$/)\n  if (rgbMatch) {\n    const r = clampByte(rgbMatch[1])\n    const g = clampByte(rgbMatch[2])\n    const b = clampByte(rgbMatch[3])\n    const a = rgbMatch[4] !== undefined ? clampUnit(rgbMatch[4]) : 1\n    if (r === null || g === null || b === null || a === null) return null\n    return { hex: rgbToHex(r, g, b), alpha: a }\n  }\n\n  // CSS named\n  if (NAMED_COLORS[s]) {\n    return parseHex(NAMED_COLORS[s])\n  }\n\n  // 시맨틱 alias\n  if (SEMANTIC_COLORS[s]) {\n    return parseHex(SEMANTIC_COLORS[s])\n  }\n\n  return null\n}\n\nfunction parseHex(s: string): ParsedColor | null {\n  const hex = s.startsWith('#') ? s.slice(1) : s\n  if (hex === 'transparent') return { hex: 'transparent', alpha: 0 }\n\n  if (!/^[0-9a-f]+$/i.test(hex)) return null\n\n  if (hex.length === 3) {\n    // #abc → #aabbcc\n    const r = hex[0] + hex[0]\n    const g = hex[1] + hex[1]\n    const b = hex[2] + hex[2]\n    return { hex: `#${r}${g}${b}`.toLowerCase(), alpha: 1 }\n  }\n  if (hex.length === 4) {\n    // #abcd → #aabbccdd\n    const r = hex[0] + hex[0]\n    const g = hex[1] + hex[1]\n    const b = hex[2] + hex[2]\n    const a = parseInt(hex[3] + hex[3], 16) / 255\n    return { hex: `#${r}${g}${b}`.toLowerCase(), alpha: round3(a) }\n  }\n  if (hex.length === 6) {\n    return { hex: `#${hex}`.toLowerCase(), alpha: 1 }\n  }\n  if (hex.length === 8) {\n    const rgb = hex.slice(0, 6)\n    const a = parseInt(hex.slice(6, 8), 16) / 255\n    return { hex: `#${rgb}`.toLowerCase(), alpha: round3(a) }\n  }\n  return null\n}\n\nfunction clampByte(s: string): number | null {\n  const n = Number(s)\n  if (!Number.isFinite(n) || n < 0 || n > 255) return null\n  return Math.round(n)\n}\n\nfunction clampUnit(s: string): number | null {\n  const n = Number(s)\n  if (!Number.isFinite(n) || n < 0 || n > 1) return null\n  return n\n}\n\nfunction rgbToHex(r: number, g: number, b: number): string {\n  const h = (n: number) => n.toString(16).padStart(2, '0')\n  return `#${h(r)}${h(g)}${h(b)}`\n}\n\nfunction round3(n: number): number {\n  return Math.round(n * 1000) / 1000\n}\n\n/**\n * 단순 검증 — 정규화 가능 여부만.\n * 에러 메시지에 정정 제안 포함 가능.\n */\nexport function validateColor(input: string | null | undefined): {\n  valid: boolean\n  error?: string\n  suggestion?: string\n} {\n  if (typeof input !== 'string') {\n    return { valid: false, error: 'Color must be a string.' }\n  }\n  const parsed = parseColor(input)\n  if (parsed) return { valid: true }\n\n  // 비슷한 named color 추천\n  const lower = input.trim().toLowerCase()\n  const allKnown = [...Object.keys(NAMED_COLORS), ...Object.keys(SEMANTIC_COLORS)]\n  const close = allKnown.find(k => k.includes(lower) || lower.includes(k))\n  return {\n    valid: false,\n    error: `Invalid color: '${input}'. Use hex (#ff0000), rgb(255,0,0), or named (red, warm-red, ...).`,\n    suggestion: close\n  }\n}\n\n/**\n * 색상을 hex 문자열로 정규화 (저장용).\n * 실패 시 null.\n */\nexport function normalizeColor(input: string | null | undefined): string | null {\n  const parsed = parseColor(input)\n  if (!parsed) return null\n  return parsed.hex\n}\n"]}