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

package/dist-client/client/components/board-ai-chat.d.ts

@@ -0,0 +1,277 @@
+/**
+ * <ox-board-ai-chat> — AI 주도 보드 모델링 채팅 컴포넌트 (Lit).
+ *
+ * 입력:
+ *   - sessionId: 영속 ChatSession 식별자 (없으면 ad-hoc 모드, 메시지 영속 안 됨)
+ *   - currentBoard: 현재 BoardModel JSON (호스트가 동기화)
+ *   - scopes / knownTypes / categories: 도메인 컨텍스트
+ *
+ * 출력 (이벤트):
+ *   - `board-edit-patch` { detail: { patch, summary, confidence, patchId } }
+ *     호스트가 받아서 보드 모델에 적용 (applyBoardEditPatch helper).
+ *   - `chat-followup` { detail: { question } }
+ *
+ * 모드 전환은 컨테이너 (워크스페이스) 의 책임. 이 컴포넌트는 자체로 풀 채팅 UX.
+ */
+import '@material/web/icon/icon.js';
+import { LitElement } from 'lit';
+import './mention-popup.js';
+import { type FilterResult } from './mention-popup.js';
+export declare class OxBoardAIChat extends LitElement {
+    /** 영속 세션 id. 없으면 ad-hoc (메시지 영속 안 됨). */
+    sessionId?: string;
+    /**
+     * 보드의 모든 ChatSession 리스트 — 다중 세션 활성화 시 탭 UI 로 표시.
+     *
+     * 빈 배열 / 미지정 → 단일 세션 UX (탭 안 보임). 한 보드 = 한 세션 가정의 기존 호출자
+     * 호환. host (board-modeller-page) 가 chatSessionsByBoard query 결과를 그대로 전달.
+     *
+     * 이 컴포넌트는 list 자체를 fetch 하지 않음 — 영속 모델 / 권한 / 페이지네이션 정책은
+     * host 책임. 본 컴포넌트는 표시 + 이벤트 emission 만.
+     */
+    sessions: Array<{
+        id: string;
+        name?: string;
+        createdAt?: string;
+    }>;
+    /**
+     * 현재 BoardModel — chat() 입력으로 그대로 전달.
+     *
+     * 주의: 호스트가 라이브 편집 가능한 캔버스(things-scene)를 갖고 있다면, 캔버스 안에서
+     * 일어나는 수작업 편집이 이 property 에는 자동 반영되지 않는다. 이 경우 `boardProvider`
+     * 콜백을 같이 넘기면 send() 시점에 라이브 보드를 pull 한다.
+     */
+    currentBoard?: any;
+    /**
+     * 라이브 보드 모델 공급자 (선택).
+     *
+     * 호스트가 things-scene 같은 캔버스를 사용 중이면 사용자가 캔버스에서 수작업 편집한
+     * 내용은 `currentBoard` property 에 자동 반영되지 않는다. 이 콜백을 등록하면 `send()`
+     * 직전에 호출해 가장 최신 보드를 pull → AI 가 항상 라이브 상태를 본다.
+     *
+     * 우선순위: boardProvider() ?? currentBoard.
+     */
+    boardProvider?: () => any;
+    /**
+     * `#` mention 검색 공급자 (선택). 호스트가 things-scene 의 SceneSearchEngine 으로 wrap.
+     *
+     * 호스트는 query 를 받아 popup 에 표시할 FilterResult[] 를 돌려준다 — chat 자체는
+     * things-scene 의존성을 갖지 않고 popup 표시 로직만 담당. 검색 우선순위 / 매칭 룰은
+     * SceneSearchEngine (F-Finder 와 공유) 에 위임 → 일관성 보장.
+     *
+     * 미설정 시 `currentBoard.components` 에서 단순 substring 매칭 (legacy fallback).
+     * 빈 query 에서는 호출되지 않음 — 빈 query 는 전체 후보 enumeration 이지 검색이 아님.
+     */
+    searchProvider?: (query: string) => FilterResult[];
+    /**
+     * `@` mention 도메인 사용자 공급자 (선택). 호스트가 `domainUsersForMention` query 로 wrap.
+     *
+     * 호스트는 query 문자열을 받아 도메인 사용자 후보 (id/name/email) 배열을 돌려준다.
+     * 미설정 시 `@` popup 은 빈 결과 (사용자가 멘션 못 함). 멀티유저 환경 활성화 정책에 따라
+     * 호스트가 set 해야 활성화. async 가 자연스러우므로 Promise 반환 가능.
+     */
+    userProvider?: (query: string) => Promise<Array<{
+        id: string;
+        name?: string | null;
+        email?: string | null;
+    }>> | Array<{
+        id: string;
+        name?: string | null;
+        email?: string | null;
+    }>;
+    /**
+     * 모델러에서 현재 선택된 컴포넌트의 `refid` 목록.
+     *
+     * refid 는 things-scene 이 모든 컴포넌트에 자동 발급하는 universal numeric handle.
+     * 호스트가 매 render 마다 `.selectedRefids=${...}` 로 갱신. AI 한테 selection 정보로
+     * 그대로 전달되어 "선택한" / "selected" / "this" 류 지시어 해석에 사용.
+     */
+    selectedRefids: number[];
+    /** board-import registry scopes. */
+    scopes?: string[];
+    knownTypes?: string[];
+    categories?: string[];
+    /**
+     * 컴포넌트 type 별 유효 속성 스킴.
+     * 형태: [{ type, description?, group?, properties? }]
+     * LLM 이 정확한 컴포넌트를 만들도록 mutation input 으로 forwarding.
+     */
+    componentSchemas?: Array<{
+        type: string;
+        description?: string;
+        group?: string;
+        properties?: Record<string, any>;
+    }>;
+    placeholder: string;
+    private lines;
+    private input;
+    /** 마지막 send 실패 시 보존 — 다시 시도 버튼 클릭 시 사용 */
+    private lastFailedInput?;
+    /** 되돌려진 patch id 들 — 한 번 revert 한 patch 는 버튼 비활성 */
+    private revertedPatchIds;
+    /** mini action — 인라인 예시 토글 */
+    private examplesOpen;
+    /** 복사 toast 표시 상태 */
+    private toastMessage?;
+    /** 복사 confirmation feedback (메시지 idx → 짧은 시간 동안 ✓ 표시) */
+    private copiedIdx?;
+    private busy;
+    private errorMessage?;
+    /** C4 presence/roster — 세션 참여자 목록. lastSeenAt 으로 online 판정. */
+    private participants;
+    /** roster online 재평가 트리거 — heartbeat tick 마다 갱신(시간 경과 반영). */
+    private _presenceTick;
+    private _heartbeatTimer?;
+    /** C4 그룹챗 — 메시지 실시간 방송 구독 핸들 + 에코 dedup. */
+    private _messageSub?;
+    /** 이미 transcript 에 반영된 서버 메시지 id 집합 — 자기 에코·중복 방송 차단. */
+    private _seenMessageIds;
+    /** optimistic 라인 임시 핸들 시퀀스 (index 비의존 reconcile 용). */
+    private _localSeq;
+    /** 현재 로그인 사용자 id — 그룹챗에서 내 메시지 vs 타인 메시지 구분 (발신자 표시). */
+    private get _myUserId();
+    /** Mention popup — `#` (컴포넌트) / `@` (카탈로그) / `/` (slash) 트리거 시 활성.
+     *  단일 popup 재사용 — mentionTrigger 로 활성 trigger 추적. */
+    private mentionOpen;
+    /** popup 표시용 — F-Finder 처럼 matchType + matchValue 동봉된 결과 */
+    private mentionResults;
+    private mentionActiveIndex;
+    /** filter cap (50) 으로 잘라낸 추가 매칭 수 — popup 의 'N more' 표시용 */
+    private mentionOverflow;
+    /** 현재 활성 mention 의 textarea 내 trigger 위치 */
+    private mentionHashPos;
+    /** 현재 활성 trigger char — '#' / '@' / '/'. popup 비활성 시 의미 없음. */
+    private mentionTrigger;
+    /** popup 열기 직전 사용자 selection 스냅샷 — Esc/blur close 시 원복용 */
+    private originalSelectedRefids;
+    /** popup 에서 명시 선택된 #mention 매핑 — {token: refid}.
+     *  사용자 textarea 에는 #token 만 보이지만 server 한테는 정확한 refid 전달.
+     *  send 시 mutation input.mentions 로 함께 전송. 사용자가 textarea 비우거나
+     *  새 채팅 시작하면 정리. */
+    private pickedMentions;
+    /** popup 에서 명시 선택된 @user 멘션 매핑 — {token: userId}.
+     *  textarea 에는 @username 만 보이지만 server 한테는 정확한 userId 전달.
+     *  send 시 mutation input.userMentions 로 함께 전송. */
+    private pickedUserMentions;
+    /** input 디바운스 timer — 150ms 후 refreshMentionPopup 실행 (F-Finder 와 동일) */
+    private inputDebounceTimer?;
+    /** centerTo 디바운스 timer — arrow nav / hover 빠를 때 카메라 애니메이션 race 방지 */
+    private centerDebounceTimer?;
+    /** Default 카탈로그 후보 캐시 — chat panel mount 시 1회 빌드 */
+    private cachedCatalogCandidates;
+    /** Default slash template 후보 캐시 — chat panel mount 시 1회 빌드 */
+    private cachedSlashCandidates;
+    /** `@` 마지막 query 의 도메인 사용자 후보 캐시 — userProvider 응답 도착 시 갱신.
+     *  query 별 캐시가 아니라 단순 "최근 결과" — async race 회피. */
+    private cachedUserCandidates;
+    /** 진행 중인 userProvider fetch token — 늦게 도착한 응답이 최신을 덮어쓰지 않도록 식별. */
+    private userFetchToken;
+    static styles: import("lit").CSSResult[];
+    connectedCallback(): void;
+    updated(changed: Map<string, any>): void;
+    disconnectedCallback(): void;
+    private _startPresence;
+    private _stopPresence;
+    private _startMessageSubscription;
+    private _stopMessageSubscription;
+    /** 서버 ChatMessage → ChatLine. */
+    private _msgToLine;
+    /**
+     * 원격(방송) 메시지 수신 — 에코·중복은 id 로 차단, 신규는 transcript 에 append.
+     * 자기 발신 메시지의 id 는 전송 reconcile 에서 이미 _seenMessageIds 에 등록됨.
+     */
+    private _onRemoteMessage;
+    /**
+     * 전송한 optimistic 라인을 서버 id 로 reconcile (index 비의존 — _localId 로 탐색).
+     * 에코가 응답보다 먼저 도착해 이미 append 됐으면 optimistic 중복 라인을 제거한다.
+     */
+    private _reconcileSentLine;
+    private _loadParticipants;
+    private _touchPresence;
+    /** lastSeenAt 이 TTL 이내면 online. (_presenceTick 의존으로 주기 재평가.) */
+    private _isOnline;
+    private loadHistory;
+    render(): import("lit-html").TemplateResult<1>;
+    private onKeyDown;
+    /** input 이벤트 — value 즉시 반영 + popup 갱신은 150ms 디바운스 (F-Finder 와 동일).
+     *  big board 에서 매 keystroke filter 비용 절감 + 한국어 IME 조합 중 깜빡임 완화. */
+    private onTextareaInput;
+    /** 현재 cursor 위치를 보고 mention popup 활성/비활성 + 후보 갱신.
+     *  `#` (컴포넌트) / `@` (카탈로그) / `/` (slash 템플릿) 한 번에 하나만 활성. */
+    private refreshMentionPopup;
+    /** `@` query 에 대한 userProvider 비동기 호출 — 응답 도착 시 popup 결과 갱신.
+     *  race 방지: token 으로 최신 호출 식별 (늦게 도착한 응답 무시). */
+    private refreshUserCandidatesAsync;
+    /** popup 후보들 outline highlight — 카메라/선택 변경 없음.
+     *  타이핑 직후 (refreshMentionPopup) 에서 호출 — 사용자가 active 를 명시 이동하지
+     *  않은 상태이므로 임의의 첫 항목을 선택하거나 카메라 이동시키지 않음.
+     *  # trigger 일 때만 활성. */
+    private highlightMatchedCandidates;
+    /** active 후보 live preview — 사용자가 ↑↓ 키 / popup 마우스 hover 로 명시적으로
+     *  active 를 옮긴 시점에 호출. F-Finder 동급 3-action: highlight + select + centerTo.
+     *  centerTo 는 150ms 디바운스 — 빠른 nav 시 카메라 애니메이션 race 방지.
+     *  # trigger 일 때만 활성. */
+    private previewActiveCandidate;
+    private dispatchActions;
+    /** 메시지 버블의 `<span class="mention">#token</span>` 클릭 — 컴포넌트로 select + centerTo.
+     *  resolve 룰은 pure helper `resolveMentionToken` 에 위임 (단위 테스트 가능). */
+    private onBubbleClick;
+    /** popup 닫기. commit=false (취소) 면 # 의 경우:
+     *   - highlight 정리 (highlightComponents [])
+     *   - 원래 selection 으로 원복
+     *  commit=true (확정) 면 현재 preview 상태 유지 + highlight 만 정리. */
+    private closeMentionPopup;
+    /** 후보 1개를 textarea 에 적용 + popup 닫고 cursor 재배치. */
+    private applyMention;
+    /** 예시 그룹 — i18n 키. localize mixin 이 언어 변경 시 자동 재렌더. */
+    private static readonly EXAMPLE_GROUPS;
+    /** 보드의 세션 탭 — 다중 세션 활성화 시 패널 상단. host 가 sessions 비워두면 표시 X.
+     *  레이블은 session.name 우선, 없으면 fallback "세션 N". */
+    private renderSessionTabs;
+    /** C4 roster — 세션 참여자 + online 표시. 참여자 2명 미만이면 숨김(혼자면 의미 없음). */
+    private renderRoster;
+    private _onSessionTabClick;
+    private _onSessionCreateClick;
+    private renderEmpty;
+    /** trigger chip 클릭 — textarea 에 trigger 문자 삽입 + focus + popup 자동 활성. */
+    private insertTrigger;
+    /** 예시 클릭 — 입력창에 채우고 포커스 (사용자가 수정 후 전송 가능) */
+    private useExample;
+    private renderInlineExamples;
+    private retryLastSend;
+    /**
+     * 메시지별 hover 액션 — 텍스트 chip 으로 명확.
+     *   user      : 액션 row 자체 X (자기 메시지에 시각 노이즈 X — 편집은 input 위 "새 대화" 흐름 또는 마우스 더블클릭)
+     *   assistant : 복사 + 재생성 + (patch 적용된 경우만) 되돌리기
+     *   system    : 없음
+     */
+    private renderMessageActions;
+    /**
+     * "AI 가 이런 도구를 사용했습니다" fold-able 박스.
+     *
+     * - 기본 닫힘 (toolUsagesOpen=false). 헤더 클릭 시 toggle.
+     * - 펼쳤을 때 도구 별로 name + arguments + result + read/write 색상 배지.
+     * - 디버그 / 신뢰도 향상용 — 사용자가 "왜 이렇게 답했지" 의문 가질 때 즉시 검증.
+     */
+    private renderToolUsages;
+    private toggleToolUsages;
+    private formatJson;
+    private copyMessage;
+    private showToast;
+    /**
+     * 사용자 메시지 편집 — 해당 메시지 + 이후 모두 UI 에서 제거하고 입력창에 채움.
+     * 서버 영속 history 는 그대로 유지 (다음 send 시 새 메시지로 추가).
+     */
+    private editUserMessage;
+    /**
+     * AI 응답 재생성 — 해당 assistant 메시지 + 이후 제거하고, 직전 user 메시지를 다시 send.
+     */
+    private regenerateAssistant;
+    private onRevertClick;
+    private send;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ox-board-ai-chat': OxBoardAIChat;
+    }
+}