@things-factory/ai-assistant 10.1.6

package/dist-client/components/mention-popup-helpers.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Mention popup pure helpers — Lit / DOM 의존 없음. 단위 테스트 가능.
+ *
+ * Lit 엘리먼트 (ox-mention-popup) 와 분리 — jest 의 node 환경에서 'lit' import 가
+ * ESM 변환 없이 실패하므로 chat-input-builder 패턴과 동일하게 helper 분리.
+ */
+export interface MentionCandidate {
+    /** popup 에 보일 1차 식별 라벨 */
+    label: string;
+    /** 카테고리 — 컴포넌트 type / 카탈로그 kind ('prefab'/'palette'/'layout') / 'template' / 'user' */
+    type: string;
+    /** 컴포넌트 후보 — things-scene refid (popup 표시 안 함, AI 내부 reference) */
+    refid?: number;
+    /** 사용자 멘션 후보 — 도메인 사용자 id (UUID). popup 표시 안 함. */
+    userId?: string;
+    /** 사용자 멘션 후보 — 이메일 (라벨 부가 정보 / 검색 대상) */
+    email?: string;
+    /** 선택 시 trigger+label 대신 삽입할 전체 텍스트 (slash template 용) */
+    replacementText?: string;
+    /** F-Finder 검색 필드 — things-scene 컴포넌트의 실제 키. 'name' 없음. */
+    id?: string;
+    tag?: string;
+    class?: string;
+    text?: string;
+    /** 카탈로그/슬래시 후보용 — description 도 검색 대상 */
+    description?: string;
+}
+/** filter 결과 — 매칭됐을 때만 matchType + matchValue 동봉.
+ *  matchType union 은 things-scene SearchResult 와 동일 (id/name/tag/type/class/
+ *  text/data/property) + 자체 'description' (catalog/slash). */
+export interface FilterResult {
+    candidate: MentionCandidate;
+    matchType?: 'id' | 'name' | 'tag' | 'type' | 'class' | 'text' | 'data' | 'property' | 'description';
+    matchValue?: string;
+}
+/**
+ * 보드의 컴포넌트를 popup 후보로 변환. things-scene 컴포넌트 state 키만 사용:
+ * id / type / tag / class / text. 'name' 같은 별도 개념 도입 안 함.
+ *
+ * Label: id 있으면 id, 없으면 type. refid 는 popup 에 표시 안 함 (시스템 핸들).
+ */
+export declare function buildMentionCandidates(components: any): MentionCandidate[];
+/**
+ * 도메인 사용자 → MentionCandidate. server `domainUsersForMention` 결과를 popup 표시용
+ * 으로 변환.
+ *   - label   : 화면 표시 + textarea 삽입 토큰 (공백 / 비-단어 문자 불가 → 이메일 username 으로
+ *               fallback 또는 underscore 치환)
+ *   - userId  : 영속용 UUID (inline marker `{userId:UUID}` 로 박힘)
+ *
+ * mention 토큰 정규식은 word char 만 허용하므로 공백 / 점 / 하이픈 같은 문자 들어간 name 은
+ * 그대로 쓰면 토큰이 첫 단어에서 끊김. 안전한 토큰 우선순위:
+ *   1. name (공백 / 비-단어 문자 없음)
+ *   2. email 의 username (공백 / 비-단어 문자 없음)
+ *   3. name 의 공백을 underscore 로 치환
+ *   4. id (UUID — 마지막 폴백)
+ */
+export declare function buildUserCandidates(users: ReadonlyArray<{
+    id: string;
+    name?: string | null;
+    email?: string | null;
+}>): MentionCandidate[];
+export interface CatalogEntry {
+    /** 카탈로그 식별자 — '@token' 으로 사용 + addPrefab/modifyBoard 인자에 전달 */
+    name: string;
+    /** 종류 — UI 표시 + server-side disambiguation 과 일치 */
+    kind: 'prefab' | 'palette' | 'layout';
+    /** 한 줄 설명 (사용자 popup 에 보임) */
+    description?: string;
+}
+/**
+ * 카탈로그 항목 묶음 → MentionCandidate[]. 클라이언트가 chat panel mount 시 1회만
+ * 빌드 후 캐시. 이름 + kind 가 unique 여야 함 — 동일 name 다른 kind 는 카탈로그
+ * resolver 가 disambiguation 처리.
+ *
+ * 정렬: kind 우선 (prefab → palette → layout), 그 안에서 name asc.
+ */
+export declare function buildCatalogCandidates(entries: CatalogEntry[]): MentionCandidate[];
+export interface SlashTemplate {
+    /** 식별자 — '/grid' 의 'grid'. trigger 빠진 형태 */
+    name: string;
+    /** 사용자에게 보일 한 줄 설명 */
+    description?: string;
+    /** 선택 시 textarea 에 삽입될 전체 자연어 텍스트 (trigger+name 영역 교체) */
+    template: string;
+}
+/**
+ * Slash template 묶음 → MentionCandidate[] (replacementText 사용).
+ *
+ * 정렬: name asc.
+ *
+ * Slash 는 component/catalog 와 달리 LLM 우회 명령이 아니라 사용자에게 미리 작성된
+ * 자연어 prompt 를 빠르게 끼워넣는 용도. AI 는 변환 결과를 그대로 자연어로 처리.
+ */
+export declare function buildSlashCandidates(templates: SlashTemplate[]): MentionCandidate[];
+/**
+ * cursor 직전의 trigger char (`#` or `@`) + token 추출. popup 활성 여부 판단.
+ *
+ * 활성 조건:
+ *   - cursor 이전에 trigger 가 존재
+ *   - trigger 와 cursor 사이에 공백 / 줄바꿈 / 동일 trigger 없음
+ *   - trigger 직전이 문자열 시작 또는 공백/줄바꿈/구두점 (단어 중간 trigger 무시)
+ *
+ * 반환 — 활성 시 { hashPos, query } (hashPos 는 trigger 위치 — # 또는 @) /
+ * 비활성 시 null.
+ *
+ * trigger default '#' — 기존 호출자 호환.
+ */
+export declare function extractMentionContext(text: string, cursorPos: number, trigger?: string): {
+    hashPos: number;
+    query: string;
+} | null;
+/**
+ * query 로 후보 필터 — F-Finder 스타일 multi-field.
+ *
+ * 검색 문법:
+ *   - 빈 query → 전체 반환 (cap 까지). matchType: 'label', matchValue: candidate.label
+ *   - 자유 substring → 우선순위 (id > name > tag > type > class > text > label > description)
+ *     로 첫 매치 필드 발견. matchType + matchValue 동봉
+ *   - field:value → 해당 field 만 매칭
+ *     * `id:` / `i:` — id
+ *     * `name:` / `n:` — name
+ *     * `type:` / `t:` — type
+ *     * `tag:` — tag (신규)
+ *     * `class:` / `c:` — class (신규)
+ *     * `text:` — text (신규)
+ *
+ * cap default 50 (F-Finder 표준). label 길이 짧은 순 정렬.
+ */
+export declare function filterMentionCandidates(candidates: MentionCandidate[], query: string, cap?: number): FilterResult[];
+export interface ResolveMentionTokenOptions {
+    /** 메시지 버블의 `<span data-refid>` 값. 작성 시점에 박제된 refid (가장 정확). */
+    persistedRefid?: string | null;
+    /** 호스트의 SceneSearchEngine 위임 — 작성 시점 refid 없거나 stale 일 때 fallback. */
+    searchProvider?: (query: string) => FilterResult[];
+    /** 보드 모델 — components.find(id) 직접 매칭 최후 fallback. */
+    board?: {
+        components?: any[];
+    } | null;
+}
+/**
+ * `#token` 클릭 시 token → refid resolve. 우선순위:
+ *   1. `persistedRefid` (data-refid 속성, 작성 시점 박제)
+ *   2. `searchProvider` — 'id' 정확 일치 → 첫 결과
+ *   3. `board.components.find(c => c.id === token)` — id 직접 매칭
+ *
+ * 모두 실패하면 `undefined`. UI 측에서 not-found 처리 (toast 등).
+ *
+ * Pure 함수 — DOM/Lit 의존 없음, 단위 테스트 가능.
+ */
+export declare function resolveMentionToken(token: string, opts: ResolveMentionTokenOptions): number | undefined;
+/**
+ * 선택된 후보로 textarea text 갱신 — trigger + query 영역을 교체.
+ *
+ * 두 모드:
+ *   - 일반 (component / catalog): trigger + label + 공백 으로 교체
+ *   - slash template: candidate.replacementText 가 있으면 그걸로 통째 교체
+ *
+ * 새 cursor 위치도 같이 반환.
+ *
+ * trigger default '#' — 기존 호출자 호환.
+ */
+export declare function applyMentionSelection(text: string, cursorPos: number, hashPos: number, candidate: MentionCandidate, trigger?: string): {
+    text: string;
+    cursorPos: number;
+};

package/dist-client/components/mention-popup-helpers.js

@@ -0,0 +1,330 @@
+/**
+ * Mention popup pure helpers — Lit / DOM 의존 없음. 단위 테스트 가능.
+ *
+ * Lit 엘리먼트 (ox-mention-popup) 와 분리 — jest 의 node 환경에서 'lit' import 가
+ * ESM 변환 없이 실패하므로 chat-input-builder 패턴과 동일하게 helper 분리.
+ */
+/** 검색 시 시도할 field 순서.
+ *   - 컴포넌트: id 우선 (F-Finder 와 동일 — id/tag/type/class/text)
+ *   - user 후보: id 없으니 label/email 로 매칭
+ *   - catalog/slash: label/description 로 매칭
+ *
+ * 'label' 이 fallback 으로 들어있어 모든 candidate 가 최소 1개 매칭 가능. */
+const SEARCH_FIELDS = [
+    { key: 'id', type: 'id' },
+    { key: 'label', type: 'name' },
+    { key: 'email', type: 'data' },
+    { key: 'tag', type: 'tag' },
+    { key: 'type', type: 'type' },
+    { key: 'class', type: 'class' },
+    { key: 'text', type: 'text' },
+    { key: 'description', type: 'description' }
+];
+/**
+ * 보드의 컴포넌트를 popup 후보로 변환. things-scene 컴포넌트 state 키만 사용:
+ * id / type / tag / class / text. 'name' 같은 별도 개념 도입 안 함.
+ *
+ * Label: id 있으면 id, 없으면 type. refid 는 popup 에 표시 안 함 (시스템 핸들).
+ */
+export function buildMentionCandidates(components) {
+    const list = Array.isArray(components) ? components : [];
+    const out = [];
+    for (const c of list) {
+        if (!c || typeof c.refid !== 'number')
+            continue;
+        const refid = c.refid;
+        const id = strField(c, 'id');
+        const type = typeof c.type === 'string' ? c.type : 'unknown';
+        const tag = strField(c, 'tag');
+        const cls = strField(c, 'class');
+        const text = strField(c, 'text');
+        const label = id || type;
+        out.push({ refid, label, type, id, tag, class: cls, text });
+    }
+    return out;
+}
+function strField(c, key) {
+    const v = c[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+// ── User (`@`) 후보 ─────────────────────────────────────────────────
+/**
+ * 도메인 사용자 → MentionCandidate. server `domainUsersForMention` 결과를 popup 표시용
+ * 으로 변환.
+ *   - label   : 화면 표시 + textarea 삽입 토큰 (공백 / 비-단어 문자 불가 → 이메일 username 으로
+ *               fallback 또는 underscore 치환)
+ *   - userId  : 영속용 UUID (inline marker `{userId:UUID}` 로 박힘)
+ *
+ * mention 토큰 정규식은 word char 만 허용하므로 공백 / 점 / 하이픈 같은 문자 들어간 name 은
+ * 그대로 쓰면 토큰이 첫 단어에서 끊김. 안전한 토큰 우선순위:
+ *   1. name (공백 / 비-단어 문자 없음)
+ *   2. email 의 username (공백 / 비-단어 문자 없음)
+ *   3. name 의 공백을 underscore 로 치환
+ *   4. id (UUID — 마지막 폴백)
+ */
+export function buildUserCandidates(users) {
+    const out = [];
+    for (const u of users) {
+        if (!u || typeof u.id !== 'string')
+            continue;
+        const name = typeof u.name === 'string' && u.name.trim() ? u.name.trim() : undefined;
+        const email = typeof u.email === 'string' && u.email.trim() ? u.email.trim() : undefined;
+        out.push({
+            label: deriveUserToken(u.id, name, email),
+            type: 'user',
+            userId: u.id,
+            email
+        });
+    }
+    return out;
+}
+/** 토큰 안전 검사 — mention 정규식 (word char + 한/일/중) 으로만 구성됐는지. */
+function isSafeMentionToken(s) {
+    return /^[\w\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}-]+$/u.test(s);
+}
+function deriveUserToken(id, name, email) {
+    if (name && isSafeMentionToken(name))
+        return name;
+    if (email) {
+        const local = email.split('@')[0];
+        if (local && isSafeMentionToken(local))
+            return local;
+    }
+    if (name) {
+        // 공백 / 비-단어 문자 underscore 치환 — 시각적 우선순위 유지
+        const sanitized = name.replace(/[^\w\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}-]+/gu, '_');
+        if (sanitized.length > 0)
+            return sanitized;
+    }
+    return id;
+}
+/**
+ * 카탈로그 항목 묶음 → MentionCandidate[]. 클라이언트가 chat panel mount 시 1회만
+ * 빌드 후 캐시. 이름 + kind 가 unique 여야 함 — 동일 name 다른 kind 는 카탈로그
+ * resolver 가 disambiguation 처리.
+ *
+ * 정렬: kind 우선 (prefab → palette → layout), 그 안에서 name asc.
+ */
+export function buildCatalogCandidates(entries) {
+    const KIND_ORDER = { prefab: 0, palette: 1, layout: 2 };
+    const sorted = entries.slice().sort((a, b) => {
+        const ka = KIND_ORDER[a.kind] ?? 99;
+        const kb = KIND_ORDER[b.kind] ?? 99;
+        if (ka !== kb)
+            return ka - kb;
+        return a.name.localeCompare(b.name);
+    });
+    return sorted.map(e => ({
+        label: e.name,
+        type: e.kind,
+        description: e.description
+    }));
+}
+/**
+ * Slash template 묶음 → MentionCandidate[] (replacementText 사용).
+ *
+ * 정렬: name asc.
+ *
+ * Slash 는 component/catalog 와 달리 LLM 우회 명령이 아니라 사용자에게 미리 작성된
+ * 자연어 prompt 를 빠르게 끼워넣는 용도. AI 는 변환 결과를 그대로 자연어로 처리.
+ */
+export function buildSlashCandidates(templates) {
+    const sorted = templates.slice().sort((a, b) => a.name.localeCompare(b.name));
+    return sorted.map(t => ({
+        label: t.name,
+        type: 'template',
+        description: t.description,
+        replacementText: t.template
+    }));
+}
+/**
+ * cursor 직전의 trigger char (`#` or `@`) + token 추출. popup 활성 여부 판단.
+ *
+ * 활성 조건:
+ *   - cursor 이전에 trigger 가 존재
+ *   - trigger 와 cursor 사이에 공백 / 줄바꿈 / 동일 trigger 없음
+ *   - trigger 직전이 문자열 시작 또는 공백/줄바꿈/구두점 (단어 중간 trigger 무시)
+ *
+ * 반환 — 활성 시 { hashPos, query } (hashPos 는 trigger 위치 — # 또는 @) /
+ * 비활성 시 null.
+ *
+ * trigger default '#' — 기존 호출자 호환.
+ */
+export function extractMentionContext(text, cursorPos, trigger = '#') {
+    if (!text || cursorPos < 0 || cursorPos > text.length)
+        return null;
+    if (!trigger || trigger.length !== 1)
+        return null;
+    // cursor 에서 뒤로 이동하며 trigger 찾기 — 공백/줄바꿈 만나면 중단
+    let i = cursorPos - 1;
+    while (i >= 0) {
+        const ch = text.charAt(i);
+        if (ch === trigger)
+            break;
+        if (ch === ' ' || ch === '\n' || ch === '\t')
+            return null;
+        i--;
+    }
+    if (i < 0)
+        return null;
+    // i 가 trigger 위치. 직전 글자 검사 (단어 중간 trigger 거부)
+    if (i > 0) {
+        const prev = text.charAt(i - 1);
+        // 알파벳/숫자/한글 같은 word char 직후는 mention 으로 안 봄 (예: 'foo#bar', 'user@host')
+        if (!/[\s\n\t.,!?;:()[\]{}'"`]/.test(prev))
+            return null;
+    }
+    return { hashPos: i, query: text.slice(i + 1, cursorPos) };
+}
+/**
+ * query 로 후보 필터 — F-Finder 스타일 multi-field.
+ *
+ * 검색 문법:
+ *   - 빈 query → 전체 반환 (cap 까지). matchType: 'label', matchValue: candidate.label
+ *   - 자유 substring → 우선순위 (id > name > tag > type > class > text > label > description)
+ *     로 첫 매치 필드 발견. matchType + matchValue 동봉
+ *   - field:value → 해당 field 만 매칭
+ *     * `id:` / `i:` — id
+ *     * `name:` / `n:` — name
+ *     * `type:` / `t:` — type
+ *     * `tag:` — tag (신규)
+ *     * `class:` / `c:` — class (신규)
+ *     * `text:` — text (신규)
+ *
+ * cap default 50 (F-Finder 표준). label 길이 짧은 순 정렬.
+ */
+export function filterMentionCandidates(candidates, query, cap = 50) {
+    // Empty query / 'type:' 같은 빈 needle 도 일반 매칭 경로와 동일 로직.
+    // 각 candidate 의 가장 prominent 한 field 를 default match 로 — 모든 행이
+    // 항상 동일 layout (badge + label + value 가능 시) 으로 일관 표시.
+    if (!query) {
+        return candidates.slice(0, cap).map(c => defaultMatchFor(c));
+    }
+    const parsed = parseQuery(query);
+    if (parsed.field && !parsed.needle) {
+        // 'type:' 만 입력 — 전체 반환, 일반 default
+        return candidates.slice(0, cap).map(c => defaultMatchFor(c));
+    }
+    const out = [];
+    if (parsed.field) {
+        const fieldKey = parsed.field;
+        for (const c of candidates) {
+            const v = c[fieldKey];
+            if (typeof v === 'string' && v.toLowerCase().includes(parsed.needle)) {
+                out.push({ candidate: c, matchType: parsed.field, matchValue: v });
+            }
+        }
+    }
+    else {
+        // 자유 검색 — 우선순위 필드 순회, 첫 매치 찾으면 break
+        const q = parsed.needle;
+        for (const c of candidates) {
+            for (const f of SEARCH_FIELDS) {
+                const v = c[f.key];
+                if (typeof v === 'string' && v.toLowerCase().includes(q)) {
+                    out.push({ candidate: c, matchType: f.type, matchValue: v });
+                    break;
+                }
+            }
+        }
+    }
+    out.sort((a, b) => a.candidate.label.length - b.candidate.label.length);
+    return out.slice(0, cap);
+}
+/**
+ * Candidate 의 default match — 우선순위 (id → name → tag → type → ...) 로 첫 non-empty
+ * field 를 matchType + matchValue 로 사용. Empty query 시 popup row 가 filter 시와
+ * 같은 layout 으로 보이도록 (badge + label + value).
+ */
+function defaultMatchFor(c) {
+    for (const f of SEARCH_FIELDS) {
+        const v = c[f.key];
+        if (typeof v === 'string' && v.length > 0) {
+            return { candidate: c, matchType: f.type, matchValue: v };
+        }
+    }
+    // 모든 field 비어있는 희귀 케이스 — matchType 없이 그냥 candidate
+    return { candidate: c };
+}
+/**
+ * query 를 'field:value' 형태로 파싱.
+ * field 가 인식되지 않으면 자유 검색 (field=undefined).
+ */
+function parseQuery(query) {
+    const m = /^([a-zA-Z]+):(.*)$/.exec(query);
+    if (m) {
+        const f = m[1].toLowerCase();
+        const map = {
+            i: 'id',
+            id: 'id',
+            t: 'type',
+            type: 'type',
+            tag: 'tag',
+            c: 'class',
+            class: 'class',
+            text: 'text'
+        };
+        if (map[f]) {
+            return { field: map[f], needle: m[2].toLowerCase() };
+        }
+    }
+    return { needle: query.toLowerCase() };
+}
+/**
+ * `#token` 클릭 시 token → refid resolve. 우선순위:
+ *   1. `persistedRefid` (data-refid 속성, 작성 시점 박제)
+ *   2. `searchProvider` — 'id' 정확 일치 → 첫 결과
+ *   3. `board.components.find(c => c.id === token)` — id 직접 매칭
+ *
+ * 모두 실패하면 `undefined`. UI 측에서 not-found 처리 (toast 등).
+ *
+ * Pure 함수 — DOM/Lit 의존 없음, 단위 테스트 가능.
+ */
+export function resolveMentionToken(token, opts) {
+    if (!token)
+        return undefined;
+    // 1. 작성 시점 박제 refid
+    if (opts.persistedRefid) {
+        const n = Number(opts.persistedRefid);
+        if (Number.isFinite(n))
+            return n;
+    }
+    // 2. searchProvider — 'id' 정확 일치 우선
+    if (opts.searchProvider) {
+        const results = opts.searchProvider(token);
+        const exact = results.find(r => r.matchType === 'id' && r.matchValue === token);
+        const hit = (exact ?? results[0])?.candidate.refid;
+        if (typeof hit === 'number' && Number.isFinite(hit))
+            return hit;
+    }
+    // 3. board.components — id 직접 매칭
+    const components = opts.board?.components;
+    if (Array.isArray(components)) {
+        const hit = components.find((c) => c?.id === token);
+        if (hit && typeof hit.refid === 'number' && Number.isFinite(hit.refid)) {
+            return hit.refid;
+        }
+    }
+    return undefined;
+}
+/**
+ * 선택된 후보로 textarea text 갱신 — trigger + query 영역을 교체.
+ *
+ * 두 모드:
+ *   - 일반 (component / catalog): trigger + label + 공백 으로 교체
+ *   - slash template: candidate.replacementText 가 있으면 그걸로 통째 교체
+ *
+ * 새 cursor 위치도 같이 반환.
+ *
+ * trigger default '#' — 기존 호출자 호환.
+ */
+export function applyMentionSelection(text, cursorPos, hashPos, candidate, trigger = '#') {
+    const before = text.slice(0, hashPos);
+    const after = text.slice(cursorPos);
+    const insert = candidate.replacementText ?? `${trigger}${candidate.label} `;
+    return {
+        text: before + insert + after,
+        cursorPos: before.length + insert.length
+    };
+}
+//# sourceMappingURL=mention-popup-helpers.js.map

package/dist-client/components/mention-popup-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-popup-helpers.js","sourceRoot":"","sources":["../../client/components/mention-popup-helpers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Mention popup pure helpers — Lit / DOM 의존 없음. 단위 테스트 가능.\n *\n * Lit 엘리먼트 (ox-mention-popup) 와 분리 — jest 의 node 환경에서 'lit' import 가\n * ESM 변환 없이 실패하므로 chat-input-builder 패턴과 동일하게 helper 분리.\n */\n\nexport interface MentionCandidate {\n  /** popup 에 보일 1차 식별 라벨 */\n  label: string\n  /** 카테고리 — 컴포넌트 type / 카탈로그 kind ('prefab'/'palette'/'layout') / 'template' / 'user' */\n  type: string\n  /** 컴포넌트 후보 — things-scene refid (popup 표시 안 함, AI 내부 reference) */\n  refid?: number\n  /** 사용자 멘션 후보 — 도메인 사용자 id (UUID). popup 표시 안 함. */\n  userId?: string\n  /** 사용자 멘션 후보 — 이메일 (라벨 부가 정보 / 검색 대상) */\n  email?: string\n  /** 선택 시 trigger+label 대신 삽입할 전체 텍스트 (slash template 용) */\n  replacementText?: string\n  /** F-Finder 검색 필드 — things-scene 컴포넌트의 실제 키. 'name' 없음. */\n  id?: string\n  tag?: string\n  class?: string\n  text?: string\n  /** 카탈로그/슬래시 후보용 — description 도 검색 대상 */\n  description?: string\n}\n\n/** filter 결과 — 매칭됐을 때만 matchType + matchValue 동봉.\n *  matchType union 은 things-scene SearchResult 와 동일 (id/name/tag/type/class/\n *  text/data/property) + 자체 'description' (catalog/slash). */\nexport interface FilterResult {\n  candidate: MentionCandidate\n  matchType?:\n    | 'id'\n    | 'name'\n    | 'tag'\n    | 'type'\n    | 'class'\n    | 'text'\n    | 'data'\n    | 'property'\n    | 'description'\n  matchValue?: string\n}\n\n/** 검색 시 시도할 field 순서.\n *   - 컴포넌트: id 우선 (F-Finder 와 동일 — id/tag/type/class/text)\n *   - user 후보: id 없으니 label/email 로 매칭\n *   - catalog/slash: label/description 로 매칭\n *\n * 'label' 이 fallback 으로 들어있어 모든 candidate 가 최소 1개 매칭 가능. */\nconst SEARCH_FIELDS: Array<{\n  key: keyof MentionCandidate\n  type: NonNullable<FilterResult['matchType']>\n}> = [\n  { key: 'id', type: 'id' },\n  { key: 'label', type: 'name' },\n  { key: 'email', type: 'data' },\n  { key: 'tag', type: 'tag' },\n  { key: 'type', type: 'type' },\n  { key: 'class', type: 'class' },\n  { key: 'text', type: 'text' },\n  { key: 'description', type: 'description' }\n]\n\n/**\n * 보드의 컴포넌트를 popup 후보로 변환. things-scene 컴포넌트 state 키만 사용:\n * id / type / tag / class / text. 'name' 같은 별도 개념 도입 안 함.\n *\n * Label: id 있으면 id, 없으면 type. refid 는 popup 에 표시 안 함 (시스템 핸들).\n */\nexport function buildMentionCandidates(components: any): MentionCandidate[] {\n  const list = Array.isArray(components) ? components : []\n  const out: MentionCandidate[] = []\n  for (const c of list) {\n    if (!c || typeof (c as any).refid !== 'number') continue\n    const refid = (c as any).refid\n    const id = strField(c, 'id')\n    const type = typeof (c as any).type === 'string' ? (c as any).type : 'unknown'\n    const tag = strField(c, 'tag')\n    const cls = strField(c, 'class')\n    const text = strField(c, 'text')\n    const label = id || type\n    out.push({ refid, label, type, id, tag, class: cls, text })\n  }\n  return out\n}\n\nfunction strField(c: any, key: string): string | undefined {\n  const v = c[key]\n  return typeof v === 'string' && v.length > 0 ? v : undefined\n}\n\n// ── User (`@`) 후보 ─────────────────────────────────────────────────\n\n/**\n * 도메인 사용자 → MentionCandidate. server `domainUsersForMention` 결과를 popup 표시용\n * 으로 변환.\n *   - label   : 화면 표시 + textarea 삽입 토큰 (공백 / 비-단어 문자 불가 → 이메일 username 으로\n *               fallback 또는 underscore 치환)\n *   - userId  : 영속용 UUID (inline marker `{userId:UUID}` 로 박힘)\n *\n * mention 토큰 정규식은 word char 만 허용하므로 공백 / 점 / 하이픈 같은 문자 들어간 name 은\n * 그대로 쓰면 토큰이 첫 단어에서 끊김. 안전한 토큰 우선순위:\n *   1. name (공백 / 비-단어 문자 없음)\n *   2. email 의 username (공백 / 비-단어 문자 없음)\n *   3. name 의 공백을 underscore 로 치환\n *   4. id (UUID — 마지막 폴백)\n */\nexport function buildUserCandidates(\n  users: ReadonlyArray<{ id: string; name?: string | null; email?: string | null }>\n): MentionCandidate[] {\n  const out: MentionCandidate[] = []\n  for (const u of users) {\n    if (!u || typeof u.id !== 'string') continue\n    const name = typeof u.name === 'string' && u.name.trim() ? u.name.trim() : undefined\n    const email = typeof u.email === 'string' && u.email.trim() ? u.email.trim() : undefined\n    out.push({\n      label: deriveUserToken(u.id, name, email),\n      type: 'user',\n      userId: u.id,\n      email\n    })\n  }\n  return out\n}\n\n/** 토큰 안전 검사 — mention 정규식 (word char + 한/일/중) 으로만 구성됐는지. */\nfunction isSafeMentionToken(s: string): boolean {\n  return /^[\\w\\p{Script=Hangul}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Han}-]+$/u.test(s)\n}\n\nfunction deriveUserToken(id: string, name?: string, email?: string): string {\n  if (name && isSafeMentionToken(name)) return name\n  if (email) {\n    const local = email.split('@')[0]\n    if (local && isSafeMentionToken(local)) return local\n  }\n  if (name) {\n    // 공백 / 비-단어 문자 underscore 치환 — 시각적 우선순위 유지\n    const sanitized = name.replace(/[^\\w\\p{Script=Hangul}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Han}-]+/gu, '_')\n    if (sanitized.length > 0) return sanitized\n  }\n  return id\n}\n\n// ── Catalog (`/` 와 함께) 후보 ──────────────────────────────────────\n\nexport interface CatalogEntry {\n  /** 카탈로그 식별자 — '@token' 으로 사용 + addPrefab/modifyBoard 인자에 전달 */\n  name: string\n  /** 종류 — UI 표시 + server-side disambiguation 과 일치 */\n  kind: 'prefab' | 'palette' | 'layout'\n  /** 한 줄 설명 (사용자 popup 에 보임) */\n  description?: string\n}\n\n/**\n * 카탈로그 항목 묶음 → MentionCandidate[]. 클라이언트가 chat panel mount 시 1회만\n * 빌드 후 캐시. 이름 + kind 가 unique 여야 함 — 동일 name 다른 kind 는 카탈로그\n * resolver 가 disambiguation 처리.\n *\n * 정렬: kind 우선 (prefab → palette → layout), 그 안에서 name asc.\n */\nexport function buildCatalogCandidates(entries: CatalogEntry[]): MentionCandidate[] {\n  const KIND_ORDER: Record<string, number> = { prefab: 0, palette: 1, layout: 2 }\n  const sorted = entries.slice().sort((a, b) => {\n    const ka = KIND_ORDER[a.kind] ?? 99\n    const kb = KIND_ORDER[b.kind] ?? 99\n    if (ka !== kb) return ka - kb\n    return a.name.localeCompare(b.name)\n  })\n  return sorted.map(e => ({\n    label: e.name,\n    type: e.kind,\n    description: e.description\n  }))\n}\n\n// ── Slash (`/`) 템플릿 ──────────────────────────────────────────────\n\nexport interface SlashTemplate {\n  /** 식별자 — '/grid' 의 'grid'. trigger 빠진 형태 */\n  name: string\n  /** 사용자에게 보일 한 줄 설명 */\n  description?: string\n  /** 선택 시 textarea 에 삽입될 전체 자연어 텍스트 (trigger+name 영역 교체) */\n  template: string\n}\n\n/**\n * Slash template 묶음 → MentionCandidate[] (replacementText 사용).\n *\n * 정렬: name asc.\n *\n * Slash 는 component/catalog 와 달리 LLM 우회 명령이 아니라 사용자에게 미리 작성된\n * 자연어 prompt 를 빠르게 끼워넣는 용도. AI 는 변환 결과를 그대로 자연어로 처리.\n */\nexport function buildSlashCandidates(templates: SlashTemplate[]): MentionCandidate[] {\n  const sorted = templates.slice().sort((a, b) => a.name.localeCompare(b.name))\n  return sorted.map(t => ({\n    label: t.name,\n    type: 'template',\n    description: t.description,\n    replacementText: t.template\n  }))\n}\n\n/**\n * cursor 직전의 trigger char (`#` or `@`) + token 추출. popup 활성 여부 판단.\n *\n * 활성 조건:\n *   - cursor 이전에 trigger 가 존재\n *   - trigger 와 cursor 사이에 공백 / 줄바꿈 / 동일 trigger 없음\n *   - trigger 직전이 문자열 시작 또는 공백/줄바꿈/구두점 (단어 중간 trigger 무시)\n *\n * 반환 — 활성 시 { hashPos, query } (hashPos 는 trigger 위치 — # 또는 @) /\n * 비활성 시 null.\n *\n * trigger default '#' — 기존 호출자 호환.\n */\nexport function extractMentionContext(\n  text: string,\n  cursorPos: number,\n  trigger: string = '#'\n): { hashPos: number; query: string } | null {\n  if (!text || cursorPos < 0 || cursorPos > text.length) return null\n  if (!trigger || trigger.length !== 1) return null\n  // cursor 에서 뒤로 이동하며 trigger 찾기 — 공백/줄바꿈 만나면 중단\n  let i = cursorPos - 1\n  while (i >= 0) {\n    const ch = text.charAt(i)\n    if (ch === trigger) break\n    if (ch === ' ' || ch === '\\n' || ch === '\\t') return null\n    i--\n  }\n  if (i < 0) return null\n  // i 가 trigger 위치. 직전 글자 검사 (단어 중간 trigger 거부)\n  if (i > 0) {\n    const prev = text.charAt(i - 1)\n    // 알파벳/숫자/한글 같은 word char 직후는 mention 으로 안 봄 (예: 'foo#bar', 'user@host')\n    if (!/[\\s\\n\\t.,!?;:()[\\]{}'\"`]/.test(prev)) return null\n  }\n  return { hashPos: i, query: text.slice(i + 1, cursorPos) }\n}\n\n/**\n * query 로 후보 필터 — F-Finder 스타일 multi-field.\n *\n * 검색 문법:\n *   - 빈 query → 전체 반환 (cap 까지). matchType: 'label', matchValue: candidate.label\n *   - 자유 substring → 우선순위 (id > name > tag > type > class > text > label > description)\n *     로 첫 매치 필드 발견. matchType + matchValue 동봉\n *   - field:value → 해당 field 만 매칭\n *     * `id:` / `i:` — id\n *     * `name:` / `n:` — name\n *     * `type:` / `t:` — type\n *     * `tag:` — tag (신규)\n *     * `class:` / `c:` — class (신규)\n *     * `text:` — text (신규)\n *\n * cap default 50 (F-Finder 표준). label 길이 짧은 순 정렬.\n */\nexport function filterMentionCandidates(\n  candidates: MentionCandidate[],\n  query: string,\n  cap = 50\n): FilterResult[] {\n  // Empty query / 'type:' 같은 빈 needle 도 일반 매칭 경로와 동일 로직.\n  // 각 candidate 의 가장 prominent 한 field 를 default match 로 — 모든 행이\n  // 항상 동일 layout (badge + label + value 가능 시) 으로 일관 표시.\n  if (!query) {\n    return candidates.slice(0, cap).map(c => defaultMatchFor(c))\n  }\n  const parsed = parseQuery(query)\n  if (parsed.field && !parsed.needle) {\n    // 'type:' 만 입력 — 전체 반환, 일반 default\n    return candidates.slice(0, cap).map(c => defaultMatchFor(c))\n  }\n\n  const out: FilterResult[] = []\n  if (parsed.field) {\n    const fieldKey = parsed.field\n    for (const c of candidates) {\n      const v = c[fieldKey]\n      if (typeof v === 'string' && v.toLowerCase().includes(parsed.needle)) {\n        out.push({ candidate: c, matchType: parsed.field, matchValue: v })\n      }\n    }\n  } else {\n    // 자유 검색 — 우선순위 필드 순회, 첫 매치 찾으면 break\n    const q = parsed.needle\n    for (const c of candidates) {\n      for (const f of SEARCH_FIELDS) {\n        const v = c[f.key]\n        if (typeof v === 'string' && v.toLowerCase().includes(q)) {\n          out.push({ candidate: c, matchType: f.type, matchValue: v })\n          break\n        }\n      }\n    }\n  }\n  out.sort((a, b) => a.candidate.label.length - b.candidate.label.length)\n  return out.slice(0, cap)\n}\n\n/**\n * Candidate 의 default match — 우선순위 (id → name → tag → type → ...) 로 첫 non-empty\n * field 를 matchType + matchValue 로 사용. Empty query 시 popup row 가 filter 시와\n * 같은 layout 으로 보이도록 (badge + label + value).\n */\nfunction defaultMatchFor(c: MentionCandidate): FilterResult {\n  for (const f of SEARCH_FIELDS) {\n    const v = c[f.key]\n    if (typeof v === 'string' && v.length > 0) {\n      return { candidate: c, matchType: f.type, matchValue: v }\n    }\n  }\n  // 모든 field 비어있는 희귀 케이스 — matchType 없이 그냥 candidate\n  return { candidate: c }\n}\n\n/**\n * query 를 'field:value' 형태로 파싱.\n * field 가 인식되지 않으면 자유 검색 (field=undefined).\n */\nfunction parseQuery(query: string): {\n  field?: 'id' | 'type' | 'tag' | 'class' | 'text'\n  needle: string\n} {\n  const m = /^([a-zA-Z]+):(.*)$/.exec(query)\n  if (m) {\n    const f = m[1].toLowerCase()\n    const map: Record<string, 'id' | 'type' | 'tag' | 'class' | 'text'> = {\n      i: 'id',\n      id: 'id',\n      t: 'type',\n      type: 'type',\n      tag: 'tag',\n      c: 'class',\n      class: 'class',\n      text: 'text'\n    }\n    if (map[f]) {\n      return { field: map[f], needle: m[2].toLowerCase() }\n    }\n  }\n  return { needle: query.toLowerCase() }\n}\n\n// ── Click resolve (메시지 버블의 #token 클릭 → refid) ──────────────\n\nexport interface ResolveMentionTokenOptions {\n  /** 메시지 버블의 `<span data-refid>` 값. 작성 시점에 박제된 refid (가장 정확). */\n  persistedRefid?: string | null\n  /** 호스트의 SceneSearchEngine 위임 — 작성 시점 refid 없거나 stale 일 때 fallback. */\n  searchProvider?: (query: string) => FilterResult[]\n  /** 보드 모델 — components.find(id) 직접 매칭 최후 fallback. */\n  board?: { components?: any[] } | null\n}\n\n/**\n * `#token` 클릭 시 token → refid resolve. 우선순위:\n *   1. `persistedRefid` (data-refid 속성, 작성 시점 박제)\n *   2. `searchProvider` — 'id' 정확 일치 → 첫 결과\n *   3. `board.components.find(c => c.id === token)` — id 직접 매칭\n *\n * 모두 실패하면 `undefined`. UI 측에서 not-found 처리 (toast 등).\n *\n * Pure 함수 — DOM/Lit 의존 없음, 단위 테스트 가능.\n */\nexport function resolveMentionToken(\n  token: string,\n  opts: ResolveMentionTokenOptions\n): number | undefined {\n  if (!token) return undefined\n\n  // 1. 작성 시점 박제 refid\n  if (opts.persistedRefid) {\n    const n = Number(opts.persistedRefid)\n    if (Number.isFinite(n)) return n\n  }\n\n  // 2. searchProvider — 'id' 정확 일치 우선\n  if (opts.searchProvider) {\n    const results = opts.searchProvider(token)\n    const exact = results.find(\n      r => r.matchType === 'id' && r.matchValue === token\n    )\n    const hit = (exact ?? results[0])?.candidate.refid\n    if (typeof hit === 'number' && Number.isFinite(hit)) return hit\n  }\n\n  // 3. board.components — id 직접 매칭\n  const components = opts.board?.components\n  if (Array.isArray(components)) {\n    const hit = components.find((c: any) => c?.id === token)\n    if (hit && typeof hit.refid === 'number' && Number.isFinite(hit.refid)) {\n      return hit.refid\n    }\n  }\n\n  return undefined\n}\n\n/**\n * 선택된 후보로 textarea text 갱신 — trigger + query 영역을 교체.\n *\n * 두 모드:\n *   - 일반 (component / catalog): trigger + label + 공백 으로 교체\n *   - slash template: candidate.replacementText 가 있으면 그걸로 통째 교체\n *\n * 새 cursor 위치도 같이 반환.\n *\n * trigger default '#' — 기존 호출자 호환.\n */\nexport function applyMentionSelection(\n  text: string,\n  cursorPos: number,\n  hashPos: number,\n  candidate: MentionCandidate,\n  trigger: string = '#'\n): { text: string; cursorPos: number } {\n  const before = text.slice(0, hashPos)\n  const after = text.slice(cursorPos)\n  const insert = candidate.replacementText ?? `${trigger}${candidate.label} `\n  return {\n    text: before + insert + after,\n    cursorPos: before.length + insert.length\n  }\n}\n"]}

package/dist-client/components/mention-popup.d.ts

@@ -0,0 +1,35 @@
+/**
+ * <ox-mention-popup> — Mention 후보 리스트 popup overlay.
+ *
+ * board-ai-chat 의 textarea 위에 absolute 로 띄움. plain `<textarea>` + popup 분리 패턴
+ * (한국어 IME 함정 회피 — contenteditable 사용 안 함).
+ *
+ * 키보드 네비게이션은 호스트 (board-ai-chat) 가 textarea keydown 으로 처리하고
+ * activeIndex 만 동기화. 마우스 클릭은 popup 자체에서 처리.
+ *
+ * Pure helper (extractMentionContext / filterMentionCandidates 등) 는
+ * `mention-popup-helpers.ts` 에 분리 — 단위 테스트 가능.
+ */
+import { LitElement } from 'lit';
+import type { FilterResult } from './mention-popup-helpers.js';
+export type { MentionCandidate, FilterResult } from './mention-popup-helpers.js';
+export { buildMentionCandidates, buildCatalogCandidates, buildSlashCandidates, buildUserCandidates, extractMentionContext, filterMentionCandidates, applyMentionSelection, resolveMentionToken, type CatalogEntry, type SlashTemplate, type ResolveMentionTokenOptions } from './mention-popup-helpers.js';
+export declare class OxMentionPopup extends LitElement {
+    results: FilterResult[];
+    activeIndex: number;
+    /** filter cap 후 표시 안 된 추가 매칭 수 ("...and N more" 표기용) */
+    overflow: number;
+    static styles: import("lit").CSSResult;
+    render(): import("lit-html").TemplateResult<1>;
+    private _select;
+    /** 마우스 hover 로 active 이동 — host 가 받아 keyboard nav 와 동일하게 처리. */
+    private _setActive;
+    /** activeIndex 가 바뀌면 해당 항목을 view 로 스크롤 — popup 의 overflow-y:auto
+     *  영역에서 키보드 네비 시 active 가 가려지지 않도록. */
+    protected updated(changed: Map<string, unknown>): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ox-mention-popup': OxMentionPopup;
+    }
+}