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

package/dist-client/server/service/component-tree.js

@@ -0,0 +1,68 @@
+/**
+ * 보드의 모든 컴포넌트를 재귀 walk 해 평면 list 로 반환.
+ *
+ * 순서: depth-first pre-order — 부모 먼저, 그 다음 자식. 사용자/AI 가 보드를
+ * 좌상단부터 시각적으로 읽는 순서와 일치.
+ *
+ * 재귀 깊이 안전 — 일반적인 보드 (depth < 10) 에서 stack overflow 없음.
+ * 비정상적으로 깊은 (cycle 가능성?) 케이스는 maxDepth 로 cap.
+ */
+export function collectAllComponents(board, options = {}) {
+    if (!board || !Array.isArray(board.components))
+        return [];
+    const maxDepth = options.maxDepth ?? 32;
+    const out = [];
+    walk(board.components, undefined, 0, [], maxDepth, out);
+    return out;
+}
+function walk(components, parentRefid, depth, parentPath, maxDepth, out) {
+    if (depth > maxDepth)
+        return;
+    for (const c of components) {
+        if (!c || typeof c !== 'object')
+            continue;
+        const refid = typeof c.refid === 'number' ? c.refid : undefined;
+        const path = refid !== undefined ? [...parentPath, refid] : parentPath;
+        out.push({ component: c, refid, parentRefid, depth, path });
+        // 자식 컴포넌트 — group / container 의 components 배열
+        const children = c.components;
+        if (Array.isArray(children) && children.length > 0) {
+            walk(children, refid, depth + 1, path, maxDepth, out);
+        }
+    }
+}
+export function findComponentByRefid(board, refid) {
+    if (!board || !Array.isArray(board.components))
+        return undefined;
+    return findInArray(board.components, refid);
+}
+function findInArray(arr, refid) {
+    for (let i = 0; i < arr.length; i++) {
+        const c = arr[i];
+        if (!c || typeof c !== 'object')
+            continue;
+        if (c.refid === refid) {
+            return { component: c, parentArray: arr, index: i };
+        }
+        const children = c.components;
+        if (Array.isArray(children) && children.length > 0) {
+            const sub = findInArray(children, refid);
+            if (sub)
+                return sub;
+        }
+    }
+    return undefined;
+}
+/**
+ * collectAllComponents 결과를 LLM 표시용으로 가볍게 요약 — 메타만.
+ * 본 컴포넌트 데이터는 별도 summarize 단계에서 처리.
+ */
+export function describeComponentMeta(flat) {
+    return {
+        refid: flat.refid,
+        type: typeof flat.component.type === 'string' ? flat.component.type : 'unknown',
+        parentRefid: flat.parentRefid,
+        depth: flat.depth
+    };
+}
+//# sourceMappingURL=component-tree.js.map

package/dist-client/server/service/component-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-tree.js","sourceRoot":"","sources":["../../../server/service/component-tree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 보드의 컴포넌트 트리 walk helper.\n *\n * things-scene 의 보드 모델은 group / container 같은 부모 컴포넌트가 자기\n * `components` 배열로 자식을 갖는 *재귀 구조*. AI / styling tool 의 입장에선\n * \"어떤 컴포넌트가 어디에 있든\" 동일하게 다뤄야 함 — depth 와 parent 정보만\n * 메타로 첨부해 *평면 list* 로 펼쳐 노출.\n *\n * 본 모듈은 *순수* 함수만 — board model 입력만으로 결과 결정. mutation 없음.\n */\nimport type { BoardComponent, BoardModel } from '@things-factory/board-import'\n\n/**\n * 평면화된 컴포넌트 — 원본 컴포넌트 + 메타 (parent, depth, path).\n *\n * 메타는 원본을 mutate 하지 않고 별도로 노출 — LLM 이 \"어느 group 안인지\" 알\n * 수 있되 영속 데이터엔 영향 없음.\n */\nexport interface FlatComponent {\n  /** 원본 컴포넌트 (참조 — 변경 시 보드에 반영). */\n  component: BoardComponent\n  /** 컴포넌트의 refid (없으면 undefined). 타깃팅 용도. */\n  refid: number | undefined\n  /** 부모 컴포넌트의 refid (root 직속이면 undefined). */\n  parentRefid: number | undefined\n  /** 0=root 직속, 1=group 안, 2=group 안 group 안, ... */\n  depth: number\n  /** 부모-자식 chain 의 refid 시퀀스 (root 부터). 본 컴포넌트의 refid 도 끝에 포함. */\n  path: number[]\n}\n\n/**\n * 보드의 모든 컴포넌트를 재귀 walk 해 평면 list 로 반환.\n *\n * 순서: depth-first pre-order — 부모 먼저, 그 다음 자식. 사용자/AI 가 보드를\n * 좌상단부터 시각적으로 읽는 순서와 일치.\n *\n * 재귀 깊이 안전 — 일반적인 보드 (depth < 10) 에서 stack overflow 없음.\n * 비정상적으로 깊은 (cycle 가능성?) 케이스는 maxDepth 로 cap.\n */\nexport function collectAllComponents(\n  board: BoardModel | null | undefined,\n  options: { maxDepth?: number } = {}\n): FlatComponent[] {\n  if (!board || !Array.isArray(board.components)) return []\n  const maxDepth = options.maxDepth ?? 32\n  const out: FlatComponent[] = []\n  walk(board.components, undefined, 0, [], maxDepth, out)\n  return out\n}\n\nfunction walk(\n  components: BoardComponent[],\n  parentRefid: number | undefined,\n  depth: number,\n  parentPath: number[],\n  maxDepth: number,\n  out: FlatComponent[]\n): void {\n  if (depth > maxDepth) return\n  for (const c of components) {\n    if (!c || typeof c !== 'object') continue\n    const refid = typeof (c as any).refid === 'number' ? (c as any).refid : undefined\n    const path = refid !== undefined ? [...parentPath, refid] : parentPath\n    out.push({ component: c, refid, parentRefid, depth, path })\n\n    // 자식 컴포넌트 — group / container 의 components 배열\n    const children = (c as any).components\n    if (Array.isArray(children) && children.length > 0) {\n      walk(children, refid, depth + 1, path, maxDepth, out)\n    }\n  }\n}\n\n/**\n * 보드 트리 안에서 refid 로 컴포넌트 찾기 — 깊은 search.\n *\n * apply-patch 의 modify / remove 가 자식 refid 도 매칭하도록 해주는 핵심 helper.\n * top-level 만 보던 기존 동작과 달리 group 안 자식도 찾는다.\n *\n * 반환: 찾은 컴포넌트 + 그 컴포넌트가 들어있는 array (parent 또는 board.components)\n *       + array 내 index. parent 정보로 in-place mutation 가능.\n */\nexport interface FoundComponent {\n  component: BoardComponent\n  /** 본 컴포넌트가 속한 array (부모의 components 또는 board.components). 직접 mutation 가능. */\n  parentArray: BoardComponent[]\n  /** parentArray 내에서의 index. */\n  index: number\n}\n\nexport function findComponentByRefid(\n  board: BoardModel | null | undefined,\n  refid: number\n): FoundComponent | undefined {\n  if (!board || !Array.isArray(board.components)) return undefined\n  return findInArray(board.components, refid)\n}\n\nfunction findInArray(\n  arr: BoardComponent[],\n  refid: number\n): FoundComponent | undefined {\n  for (let i = 0; i < arr.length; i++) {\n    const c = arr[i]\n    if (!c || typeof c !== 'object') continue\n    if ((c as any).refid === refid) {\n      return { component: c, parentArray: arr, index: i }\n    }\n    const children = (c as any).components\n    if (Array.isArray(children) && children.length > 0) {\n      const sub = findInArray(children, refid)\n      if (sub) return sub\n    }\n  }\n  return undefined\n}\n\n/**\n * collectAllComponents 결과를 LLM 표시용으로 가볍게 요약 — 메타만.\n * 본 컴포넌트 데이터는 별도 summarize 단계에서 처리.\n */\nexport function describeComponentMeta(flat: FlatComponent): {\n  refid: number | undefined\n  type: string\n  parentRefid: number | undefined\n  depth: number\n} {\n  return {\n    refid: flat.refid,\n    type: typeof flat.component.type === 'string' ? flat.component.type : 'unknown',\n    parentRefid: flat.parentRefid,\n    depth: flat.depth\n  }\n}\n"]}

package/dist-client/server/service/mention-resolver.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `#token` 멘션 해석 (things-factory 식별자 컨벤션 준수).
+ *
+ * things-factory 정책:
+ *   - `#` 은 사용자가 컴포넌트를 가리키는 SELECTOR. things-scene Finder 의
+ *     CSS 셀렉터 컨셉과 같은 맥락 — 와이드 검색 (name / id / type 셋 다 OR).
+ *   - **refid 는 시스템 내부 핸들** — 사용자에게 노출 금지. 사용자가 본 적도
+ *     없는 숫자라 `(refid 35)` 같은 표기는 혼란만 가중.
+ *   - id 는 데이터 바인딩 식별자 (human-readable). unique 제약 없음.
+ *   - name 은 사용자 라벨. 가장 친숙.
+ *
+ * Resolver 정책:
+ *   - 본문의 `#token` 은 LITERAL 보존 (refid 본문 노출 0)
+ *   - 매칭 결과는 본문 끝에 구조화된 "mention map" 블록으로 첨부
+ *   - AI 는 시스템 프롬프트의 안내에 따라 mention map 의 refid 를 tool
+ *     호출 인자로만 사용. 사용자 답변 텍스트에서는 name/id 로 지칭.
+ *
+ * Token 매칭 (모두 시도, OR):
+ *   - name 정확 일치 (case-insensitive)
+ *   - id 정확 일치 (case-insensitive)
+ *   - type 정확 일치 (case-insensitive) — `#rect` 같이 모든 type 가리키기
+ *
+ * 부분 / fuzzy 매칭 안 함 — popup 측에서 사용자가 정확한 식별자 선택.
+ *
+ * Token 정규식: /#([^\s#]+)/g (한글/영문/하이픈/언더스코어/숫자).
+ */
+import type { BoardModel } from '@things-factory/board-import';
+/** 매칭된 컴포넌트의 핵심 정보 — refid 는 시스템 핸들, 나머지는 사용자 친화적 식별.
+ *  things-scene F-Finder 와 동일한 검색 필드 (id/name/type/tag/class/text)
+ *  + position (AI 가 식별 + 조작 좌표 판단에 활용). */
+export interface MentionedComponent {
+    refid: number;
+    name?: string;
+    id?: string;
+    type: string;
+    tag?: string;
+    class?: string;
+    text?: string;
+    /** 중심 좌표 (rect: left+w/2, top+h/2 / circle: cx, cy) — 정수 반올림 */
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/** popup 에서 사용자가 명시 선택한 컴포넌트 — server 가 정확한 매칭에 사용. */
+export interface MentionPick {
+    /** 사용자 텍스트의 #token 부분 (예: '경광등1') */
+    token: string;
+    /** popup 에서 선택된 정확한 refid */
+    refid: number;
+}
+export interface ResolveMentionsOptions {
+    /** popup 에서 명시 선택된 mentions — 해당 token 은 fallback 매칭 안 거치고 정확한 refid 로 즉시 해석 */
+    picks?: MentionPick[];
+}
+export interface MentionMatch {
+    /** 사용자가 입력한 #token 의 token 부분 */
+    token: string;
+    /** 토큰 위치 (start: '#' 위치, end: 마지막 글자 다음) */
+    start: number;
+    end: number;
+    /** name/id/type 매칭으로 발견한 컴포넌트들 */
+    matched: MentionedComponent[];
+}
+/**
+ * 텍스트의 모든 #token 을 보드에서 매칭. UI / 디버그 / 테스트용.
+ */
+export declare function findMentions(text: string, currentBoard: BoardModel | null | undefined, options?: ResolveMentionsOptions): MentionMatch[];
+/**
+ * Token 으로 컴포넌트 매칭 — name/id/type/tag/class/text OR (things-scene F-Finder
+ * 동일 필드 셋). 여러 기준에서 동시 일치하더라도 같은 refid 는 한 번만 반환 (dedup).
+ *
+ * picks 에 해당 token 이 있으면 fallback 안 거치고 그 refid 로 직접 매칭 (popup 에서
+ * 사용자가 명시 선택한 결정적 매핑). 그 refid 가 보드에 없으면 fallback 으로.
+ */
+export declare function lookupComponents(token: string, components: readonly any[], picks?: readonly MentionPick[]): MentionedComponent[];
+/**
+ * 텍스트의 #token 을 LLM 친화 형태로 변환.
+ *
+ * 본문은 그대로 + 매칭 성공한 토큰의 mention map 을 끝에 첨부:
+ *
+ *   "[원본 본문]
+ *
+ *    --- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---
+ *    #경광등1 →
+ *      { name='경광등1', id='motor-1', type='rect', refid=35 }
+ *    #펌프 →
+ *      { name='펌프A', id='pump-1', type='rect', refid=42 }
+ *      { name='펌프B', id='pump-2', type='rect', refid=51 }"
+ *
+ * AI 는 system prompt 안내에 따라 refid 를 tool 호출 인자로만 사용. 답변
+ * 텍스트에서는 refid 직접 언급 금지.
+ *
+ * 매칭 0 → 변경 없음 (본문 그대로 반환).
+ */
+export declare function resolveMentions(text: string, currentBoard: BoardModel | null | undefined, options?: ResolveMentionsOptions): string;

package/dist-client/server/service/mention-resolver.js

@@ -0,0 +1,172 @@
+const MENTION_PATTERN = /#([^\s#]+)/g;
+/**
+ * 텍스트의 모든 #token 을 보드에서 매칭. UI / 디버그 / 테스트용.
+ */
+export function findMentions(text, currentBoard, options = {}) {
+    if (!text || typeof text !== 'string')
+        return [];
+    const components = currentBoard?.components ?? [];
+    return collectMatches(text, components, options.picks);
+}
+/**
+ * Token 으로 컴포넌트 매칭 — name/id/type/tag/class/text OR (things-scene F-Finder
+ * 동일 필드 셋). 여러 기준에서 동시 일치하더라도 같은 refid 는 한 번만 반환 (dedup).
+ *
+ * picks 에 해당 token 이 있으면 fallback 안 거치고 그 refid 로 직접 매칭 (popup 에서
+ * 사용자가 명시 선택한 결정적 매핑). 그 refid 가 보드에 없으면 fallback 으로.
+ */
+export function lookupComponents(token, components, picks) {
+    if (!token || components.length === 0)
+        return [];
+    // picks 우선 — popup 으로 명시 선택된 token 은 그 refid 로 직접 매칭
+    if (picks) {
+        const pick = picks.find(p => p.token === token);
+        if (pick) {
+            const c = components.find((x) => x && typeof x.refid === 'number' && x.refid === pick.refid);
+            if (c) {
+                const fields = readSearchFields(c);
+                return [
+                    {
+                        refid: pick.refid,
+                        name: fields.name,
+                        id: fields.id,
+                        type: fields.type,
+                        tag: fields.tag,
+                        class: fields.cls,
+                        text: fields.text,
+                        position: extractPosition(c)
+                    }
+                ];
+            }
+            // pick 이 stale (refid 가 더 이상 보드에 없음) — fallback 으로 진행
+        }
+    }
+    const lower = token.toLowerCase();
+    const out = [];
+    const seen = new Set();
+    for (const c of components) {
+        if (!c || typeof c.refid !== 'number')
+            continue;
+        const refid = c.refid;
+        if (seen.has(refid))
+            continue;
+        const fields = readSearchFields(c);
+        if ((fields.name && fields.name.toLowerCase() === lower) ||
+            (fields.id && fields.id.toLowerCase() === lower) ||
+            fields.type.toLowerCase() === lower ||
+            (fields.tag && fields.tag.toLowerCase() === lower) ||
+            (fields.cls && fields.cls.toLowerCase() === lower) ||
+            (fields.text && fields.text.toLowerCase() === lower)) {
+            seen.add(refid);
+            out.push({
+                refid,
+                name: fields.name,
+                id: fields.id,
+                type: fields.type,
+                tag: fields.tag,
+                class: fields.cls,
+                text: fields.text,
+                position: extractPosition(c)
+            });
+        }
+    }
+    return out;
+}
+/** 컴포넌트 중심 좌표 — rect: left+w/2 / circle: cx,cy. */
+function extractPosition(c) {
+    if (typeof c.cx === 'number' && typeof c.cy === 'number') {
+        return { x: Math.round(c.cx), y: Math.round(c.cy) };
+    }
+    if (typeof c.left === 'number' && typeof c.top === 'number') {
+        const w = typeof c.width === 'number' ? c.width : 0;
+        const h = typeof c.height === 'number' ? c.height : 0;
+        return { x: Math.round(c.left + w / 2), y: Math.round(c.top + h / 2) };
+    }
+    return undefined;
+}
+function readSearchFields(c) {
+    const str = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
+    return {
+        name: str(c.name),
+        id: str(c.id),
+        type: typeof c.type === 'string' ? c.type : 'unknown',
+        tag: str(c.tag),
+        cls: str(c.class),
+        text: str(c.text)
+    };
+}
+/**
+ * 텍스트의 #token 을 LLM 친화 형태로 변환.
+ *
+ * 본문은 그대로 + 매칭 성공한 토큰의 mention map 을 끝에 첨부:
+ *
+ *   "[원본 본문]
+ *
+ *    --- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---
+ *    #경광등1 →
+ *      { name='경광등1', id='motor-1', type='rect', refid=35 }
+ *    #펌프 →
+ *      { name='펌프A', id='pump-1', type='rect', refid=42 }
+ *      { name='펌프B', id='pump-2', type='rect', refid=51 }"
+ *
+ * AI 는 system prompt 안내에 따라 refid 를 tool 호출 인자로만 사용. 답변
+ * 텍스트에서는 refid 직접 언급 금지.
+ *
+ * 매칭 0 → 변경 없음 (본문 그대로 반환).
+ */
+export function resolveMentions(text, currentBoard, options = {}) {
+    if (!text || typeof text !== 'string')
+        return text;
+    const components = currentBoard?.components ?? [];
+    if (components.length === 0)
+        return text;
+    const matches = collectMatches(text, components, options.picks);
+    const resolved = matches.filter(m => m.matched.length > 0);
+    if (resolved.length === 0)
+        return text;
+    const block = [
+        '',
+        '--- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---'
+    ];
+    for (const m of resolved) {
+        block.push(`#${m.token} →`);
+        for (const c of m.matched) {
+            block.push(`  ${formatComponentRef(c)}`);
+        }
+    }
+    return text + '\n' + block.join('\n');
+}
+function collectMatches(text, components, picks) {
+    const out = [];
+    const pattern = new RegExp(MENTION_PATTERN.source, 'g');
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+        const token = m[1];
+        out.push({
+            token,
+            start: m.index,
+            end: m.index + m[0].length,
+            matched: lookupComponents(token, components, picks)
+        });
+    }
+    return out;
+}
+function formatComponentRef(c) {
+    const parts = [];
+    if (c.name)
+        parts.push(`name='${c.name}'`);
+    if (c.id)
+        parts.push(`id='${c.id}'`);
+    parts.push(`type='${c.type}'`);
+    if (c.tag)
+        parts.push(`tag='${c.tag}'`);
+    if (c.class)
+        parts.push(`class='${c.class}'`);
+    if (c.text)
+        parts.push(`text='${c.text}'`);
+    if (c.position)
+        parts.push(`pos=(${c.position.x},${c.position.y})`);
+    parts.push(`refid=${c.refid}`);
+    return `{ ${parts.join(', ')} }`;
+}
+//# sourceMappingURL=mention-resolver.js.map

package/dist-client/server/service/mention-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-resolver.js","sourceRoot":"","sources":["../../../server/service/mention-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `#token` 멘션 해석 (things-factory 식별자 컨벤션 준수).\n *\n * things-factory 정책:\n *   - `#` 은 사용자가 컴포넌트를 가리키는 SELECTOR. things-scene Finder 의\n *     CSS 셀렉터 컨셉과 같은 맥락 — 와이드 검색 (name / id / type 셋 다 OR).\n *   - **refid 는 시스템 내부 핸들** — 사용자에게 노출 금지. 사용자가 본 적도\n *     없는 숫자라 `(refid 35)` 같은 표기는 혼란만 가중.\n *   - id 는 데이터 바인딩 식별자 (human-readable). unique 제약 없음.\n *   - name 은 사용자 라벨. 가장 친숙.\n *\n * Resolver 정책:\n *   - 본문의 `#token` 은 LITERAL 보존 (refid 본문 노출 0)\n *   - 매칭 결과는 본문 끝에 구조화된 \"mention map\" 블록으로 첨부\n *   - AI 는 시스템 프롬프트의 안내에 따라 mention map 의 refid 를 tool\n *     호출 인자로만 사용. 사용자 답변 텍스트에서는 name/id 로 지칭.\n *\n * Token 매칭 (모두 시도, OR):\n *   - name 정확 일치 (case-insensitive)\n *   - id 정확 일치 (case-insensitive)\n *   - type 정확 일치 (case-insensitive) — `#rect` 같이 모든 type 가리키기\n *\n * 부분 / fuzzy 매칭 안 함 — popup 측에서 사용자가 정확한 식별자 선택.\n *\n * Token 정규식: /#([^\\s#]+)/g (한글/영문/하이픈/언더스코어/숫자).\n */\nimport type { BoardModel } from '@things-factory/board-import'\n\nconst MENTION_PATTERN = /#([^\\s#]+)/g\n\n/** 매칭된 컴포넌트의 핵심 정보 — refid 는 시스템 핸들, 나머지는 사용자 친화적 식별.\n *  things-scene F-Finder 와 동일한 검색 필드 (id/name/type/tag/class/text)\n *  + position (AI 가 식별 + 조작 좌표 판단에 활용). */\nexport interface MentionedComponent {\n  refid: number\n  name?: string\n  id?: string\n  type: string\n  tag?: string\n  class?: string\n  text?: string\n  /** 중심 좌표 (rect: left+w/2, top+h/2 / circle: cx, cy) — 정수 반올림 */\n  position?: { x: number; y: number }\n}\n\n/** popup 에서 사용자가 명시 선택한 컴포넌트 — server 가 정확한 매칭에 사용. */\nexport interface MentionPick {\n  /** 사용자 텍스트의 #token 부분 (예: '경광등1') */\n  token: string\n  /** popup 에서 선택된 정확한 refid */\n  refid: number\n}\n\nexport interface ResolveMentionsOptions {\n  /** popup 에서 명시 선택된 mentions — 해당 token 은 fallback 매칭 안 거치고 정확한 refid 로 즉시 해석 */\n  picks?: MentionPick[]\n}\n\nexport interface MentionMatch {\n  /** 사용자가 입력한 #token 의 token 부분 */\n  token: string\n  /** 토큰 위치 (start: '#' 위치, end: 마지막 글자 다음) */\n  start: number\n  end: number\n  /** name/id/type 매칭으로 발견한 컴포넌트들 */\n  matched: MentionedComponent[]\n}\n\n/**\n * 텍스트의 모든 #token 을 보드에서 매칭. UI / 디버그 / 테스트용.\n */\nexport function findMentions(\n  text: string,\n  currentBoard: BoardModel | null | undefined,\n  options: ResolveMentionsOptions = {}\n): MentionMatch[] {\n  if (!text || typeof text !== 'string') return []\n  const components = currentBoard?.components ?? []\n  return collectMatches(text, components, options.picks)\n}\n\n\n/**\n * Token 으로 컴포넌트 매칭 — name/id/type/tag/class/text OR (things-scene F-Finder\n * 동일 필드 셋). 여러 기준에서 동시 일치하더라도 같은 refid 는 한 번만 반환 (dedup).\n *\n * picks 에 해당 token 이 있으면 fallback 안 거치고 그 refid 로 직접 매칭 (popup 에서\n * 사용자가 명시 선택한 결정적 매핑). 그 refid 가 보드에 없으면 fallback 으로.\n */\nexport function lookupComponents(\n  token: string,\n  components: readonly any[],\n  picks?: readonly MentionPick[]\n): MentionedComponent[] {\n  if (!token || components.length === 0) return []\n\n  // picks 우선 — popup 으로 명시 선택된 token 은 그 refid 로 직접 매칭\n  if (picks) {\n    const pick = picks.find(p => p.token === token)\n    if (pick) {\n      const c = components.find(\n        (x: any) => x && typeof x.refid === 'number' && x.refid === pick.refid\n      )\n      if (c) {\n        const fields = readSearchFields(c)\n        return [\n          {\n            refid: pick.refid,\n            name: fields.name,\n            id: fields.id,\n            type: fields.type,\n            tag: fields.tag,\n            class: fields.cls,\n            text: fields.text,\n            position: extractPosition(c)\n          }\n        ]\n      }\n      // pick 이 stale (refid 가 더 이상 보드에 없음) — fallback 으로 진행\n    }\n  }\n\n  const lower = token.toLowerCase()\n  const out: MentionedComponent[] = []\n  const seen = new Set<number>()\n  for (const c of components) {\n    if (!c || typeof (c as any).refid !== 'number') continue\n    const refid = (c as any).refid\n    if (seen.has(refid)) continue\n    const fields = readSearchFields(c)\n    if (\n      (fields.name && fields.name.toLowerCase() === lower) ||\n      (fields.id && fields.id.toLowerCase() === lower) ||\n      fields.type.toLowerCase() === lower ||\n      (fields.tag && fields.tag.toLowerCase() === lower) ||\n      (fields.cls && fields.cls.toLowerCase() === lower) ||\n      (fields.text && fields.text.toLowerCase() === lower)\n    ) {\n      seen.add(refid)\n      out.push({\n        refid,\n        name: fields.name,\n        id: fields.id,\n        type: fields.type,\n        tag: fields.tag,\n        class: fields.cls,\n        text: fields.text,\n        position: extractPosition(c)\n      })\n    }\n  }\n  return out\n}\n\n/** 컴포넌트 중심 좌표 — rect: left+w/2 / circle: cx,cy. */\nfunction extractPosition(c: any): { x: number; y: number } | undefined {\n  if (typeof c.cx === 'number' && typeof c.cy === 'number') {\n    return { x: Math.round(c.cx), y: Math.round(c.cy) }\n  }\n  if (typeof c.left === 'number' && typeof c.top === 'number') {\n    const w = typeof c.width === 'number' ? c.width : 0\n    const h = typeof c.height === 'number' ? c.height : 0\n    return { x: Math.round(c.left + w / 2), y: Math.round(c.top + h / 2) }\n  }\n  return undefined\n}\n\nfunction readSearchFields(c: any): {\n  name?: string\n  id?: string\n  type: string\n  tag?: string\n  cls?: string\n  text?: string\n} {\n  const str = (v: any): string | undefined =>\n    typeof v === 'string' && v.length > 0 ? v : undefined\n  return {\n    name: str(c.name),\n    id: str(c.id),\n    type: typeof c.type === 'string' ? c.type : 'unknown',\n    tag: str(c.tag),\n    cls: str(c.class),\n    text: str(c.text)\n  }\n}\n\n/**\n * 텍스트의 #token 을 LLM 친화 형태로 변환.\n *\n * 본문은 그대로 + 매칭 성공한 토큰의 mention map 을 끝에 첨부:\n *\n *   \"[원본 본문]\n *\n *    --- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---\n *    #경광등1 →\n *      { name='경광등1', id='motor-1', type='rect', refid=35 }\n *    #펌프 →\n *      { name='펌프A', id='pump-1', type='rect', refid=42 }\n *      { name='펌프B', id='pump-2', type='rect', refid=51 }\"\n *\n * AI 는 system prompt 안내에 따라 refid 를 tool 호출 인자로만 사용. 답변\n * 텍스트에서는 refid 직접 언급 금지.\n *\n * 매칭 0 → 변경 없음 (본문 그대로 반환).\n */\nexport function resolveMentions(\n  text: string,\n  currentBoard: BoardModel | null | undefined,\n  options: ResolveMentionsOptions = {}\n): string {\n  if (!text || typeof text !== 'string') return text\n  const components = currentBoard?.components ?? []\n  if (components.length === 0) return text\n\n  const matches = collectMatches(text, components, options.picks)\n  const resolved = matches.filter(m => m.matched.length > 0)\n  if (resolved.length === 0) return text\n\n  const block: string[] = [\n    '',\n    '--- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---'\n  ]\n  for (const m of resolved) {\n    block.push(`#${m.token} →`)\n    for (const c of m.matched) {\n      block.push(`  ${formatComponentRef(c)}`)\n    }\n  }\n  return text + '\\n' + block.join('\\n')\n}\n\nfunction collectMatches(\n  text: string,\n  components: readonly any[],\n  picks?: readonly MentionPick[]\n): MentionMatch[] {\n  const out: MentionMatch[] = []\n  const pattern = new RegExp(MENTION_PATTERN.source, 'g')\n  let m: RegExpExecArray | null\n  while ((m = pattern.exec(text)) !== null) {\n    const token = m[1]\n    out.push({\n      token,\n      start: m.index,\n      end: m.index + m[0].length,\n      matched: lookupComponents(token, components, picks)\n    })\n  }\n  return out\n}\n\nfunction formatComponentRef(c: MentionedComponent): string {\n  const parts: string[] = []\n  if (c.name) parts.push(`name='${c.name}'`)\n  if (c.id) parts.push(`id='${c.id}'`)\n  parts.push(`type='${c.type}'`)\n  if (c.tag) parts.push(`tag='${c.tag}'`)\n  if (c.class) parts.push(`class='${c.class}'`)\n  if (c.text) parts.push(`text='${c.text}'`)\n  if (c.position) parts.push(`pos=(${c.position.x},${c.position.y})`)\n  parts.push(`refid=${c.refid}`)\n  return `{ ${parts.join(', ')} }`\n}\n"]}

package/dist-client/server/service/prefab-registry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Board Prefab Registry — 고품질 복합 컴포넌트 프리셋 카탈로그.
+ *
+ * 의도:
+ *   - 보드 설계자가 실제로 원하는 단위는 rect/circle 같은 원시 도형이 아닌
+ *     "온도 모니터링 카드", "AGV 배터리 상태판", "공정 KPI 타일" 같은 디자인된
+ *     복합 모듈. 이 layer 가 그 단위를 시스템 차원에서 제공.
+ *   - LLM 은 자유 작곡하지 않고 검증된 prefab 카탈로그에서 고름 → 결과 일관성 ↑,
+ *     비용 ↓, 진입 장벽 낮춤.
+ *
+ * 통합:
+ *   - 호스트 (operato 등) 가 패키지 로드 시 `registerBoardPrefab` 으로 자기 prefab
+ *     등록. board-ai 는 registry 만 관리. 초기 예시 prefab 몇 개를 자체 등록 — 진짜
+ *     디자인된 prefab 은 별도 패키지에서 추가.
+ *   - LLM 도구 통합:
+ *       getAvailablePrefabs (read)  → registry 의 메타데이터 반환
+ *       addPrefab (write)           → name + 좌표/옵션 → 단일 BoardComponent (group)
+ *
+ * 식별자:
+ *   - `name` 은 unique. 같은 name 으로 register 시 override (호스트가 자기 prefab 을
+ *     커스터마이징할 수 있도록 의도적 허용).
+ *   - 카테고리는 free-form string — registry 가 강제하지 않음. 사용자/운영 자율.
+ */
+import type { BoardComponent } from '@things-factory/board-import';
+export interface BoardPrefab {
+    /** Unique 식별자 — 'kebab-case' 권장 */
+    name: string;
+    /** 자유 분류 — 'monitoring' | 'control' | 'decoration' | 'kpi' 등 */
+    category?: string;
+    /** 사용자 / LLM 이 이해할 한 문장 설명 */
+    description: string;
+    /**
+     * 자연어 매칭 힌트 — '온도', '게이지', '카드' 등.
+     * findComponents 같은 검색이 아니라 LLM 의 의도 매칭용 메타데이터.
+     */
+    keywords?: string[];
+    /** 권장 기본 크기 — options 에 width/height 미지정 시 사용 */
+    defaultSize?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Prefab 의 컴포넌트 트리를 만든다. 단일 `BoardComponent` 반환 — 보통 group 타입이며
+     * `components` 자식을 가진다. 단일 add op 으로 매핑되어 undo 도 한 단위.
+     *
+     * options:
+     *   - left/top: anchor 좌표 (top-left 원점)
+     *   - width/height: 크기 (없으면 defaultSize)
+     *   - 추가 키: prefab 별 자유 (title 텍스트, 색상 등)
+     */
+    build(options: PrefabBuildOptions): BoardComponent;
+}
+export interface PrefabBuildOptions {
+    left: number;
+    top: number;
+    width?: number;
+    height?: number;
+    /** prefab 별 커스터마이징 — 자유 형태 */
+    [k: string]: any;
+}
+/**
+ * Prefab 등록. 같은 name 은 덮어씀 (호스트가 자기 prefab 으로 default 를 교체 가능).
+ */
+export declare function registerBoardPrefab(prefab: BoardPrefab): void;
+/** 이름으로 조회. 없으면 undefined. */
+export declare function findBoardPrefab(name: string): BoardPrefab | undefined;
+/** 등록된 prefab 의 메타데이터 (build 함수 제외) — getAvailablePrefabs 결과용. */
+export declare function listBoardPrefabs(filter?: {
+    category?: string;
+    keywordPattern?: string;
+}): Array<Omit<BoardPrefab, 'build'>>;
+/** 테스트용 — 등록 상태 초기화. */
+export declare function clearBoardPrefabsForTest(): void;