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

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

@@ -0,0 +1,2574 @@
+/**
+ * <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, css, html, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { unsafeHTML } from 'lit/directives/unsafe-html.js'
+import { client } from '@operato/graphql'
+import { auth } from '@things-factory/auth-base/dist-client/index.js'
+import { i18next, localize } from '@operato/i18n'
+import { ScrollbarStyles } from '@operato/styles'
+import gql from 'graphql-tag'
+
+import {
+  renderMarkdown,
+  injectMentionRefids,
+  injectMentionUserIds,
+  stripMentionRefids
+} from './markdown.js'
+import { buildChatMutationInput } from './chat-input-builder.js'
+import { receiveRemoteMessage, reconcileSentLine, remoteMessageToLine } from './chat-echo-dedup.js'
+import './mention-popup.js'
+import {
+  buildMentionCandidates,
+  buildCatalogCandidates,
+  buildSlashCandidates,
+  buildUserCandidates,
+  extractMentionContext,
+  filterMentionCandidates,
+  applyMentionSelection,
+  resolveMentionToken,
+  type MentionCandidate,
+  type FilterResult
+} from './mention-popup.js'
+import { DEFAULT_CATALOG_ENTRIES } from './default-catalog-entries.js'
+import { DEFAULT_SLASH_TEMPLATES } from './default-slash-templates.js'
+
+interface ChatLine {
+  role: 'user' | 'assistant' | 'system'
+  /** 서버 ChatMessage.id — 실시간 방송 에코 dedup 의 키 (있을 때만). */
+  id?: string
+  /** 클라 임시 핸들 — 영속 id 부여 전 optimistic 라인을 index 비의존으로 식별/reconcile. */
+  _localId?: string
+  /** 보낸 사용자 id/name — 그룹챗 발신자 표시용 (다른 참여자 메시지 구분). */
+  senderId?: string
+  senderName?: string
+  /** 메시지 본문. `#token{refid:N}` inline marker 가 포함될 수 있음 (영속된 메시지 / 사용자
+   *  popup pick / AI resolved mention). 렌더링 시 추출해서 `<span data-refid="N">` 으로 변환. */
+  content: string
+  patchSummary?: string
+  followUp?: string
+  patchId?: string
+  pending?: boolean
+  /** AI 가 응답을 만드는 동안 호출한 도구 trace — fold-able 박스에서 노출. */
+  toolUsages?: Array<{ name: string; arguments: any; result: any; kind: 'read' | 'write' | 'unknown' }>
+  /** UI 상태: tool usage 박스 펼침 여부 (assistant 메시지마다 독립). */
+  toolUsagesOpen?: boolean
+}
+
+const BOARD_AI_CHAT_MUTATION = gql`
+  mutation BoardAIChat($input: BoardAIChatInput!) {
+    boardAIChat(input: $input) {
+      reply
+      patch
+      followUp
+      clientId
+      sessionId
+      userMessageId
+      assistantMessageId
+      patchId
+      toolUsages
+      actions
+    }
+  }
+`
+
+const CHAT_MESSAGES_QUERY = gql`
+  query ChatMessages($sessionId: String!, $limit: Int, $offset: Int) {
+    chatMessages(sessionId: $sessionId, limit: $limit, offset: $offset) {
+      id
+      role
+      content
+      relatedPatchId
+      toolUsagesJson
+      createdAt
+      creator {
+        id
+        name
+      }
+    }
+  }
+`
+
+// C4 그룹챗 — 같은 세션의 메시지(사용자/AI/system) 실시간 방송 구독.
+// 자기 발신 에코는 message.id 로 dedup (mutation 응답으로 이미 렌더).
+const CHAT_MESSAGE_SUBSCRIPTION = gql`
+  subscription ChatMessageActivity($sessionId: String!) {
+    chatMessageActivity(sessionId: $sessionId) {
+      id
+      role
+      content
+      relatedPatchId
+      toolUsagesJson
+      createdAt
+      creator {
+        id
+        name
+      }
+    }
+  }
+`
+
+// C4 presence/roster — 세션 참여자 목록 + 마지막 접속(online 판정용).
+const CHAT_PARTICIPANTS_QUERY = gql`
+  query ChatSessionParticipants($sessionId: String!) {
+    chatSessionParticipants(sessionId: $sessionId) {
+      id
+      role
+      lastSeenAt
+      user {
+        id
+        name
+      }
+    }
+  }
+`
+const TOUCH_PRESENCE_MUTATION = gql`
+  mutation TouchPresence($sessionId: String!) {
+    touchPresence(sessionId: $sessionId)
+  }
+`
+// heartbeat 주기(ms) — 서버 PRESENCE_TTL_MS(75s)의 ~1/2.5. 로컬 online 판정도 동일 TTL.
+const PRESENCE_HEARTBEAT_MS = 30_000
+const PRESENCE_TTL_MS = 75_000
+
+/** 이름 → roster chip 이니셜 (한글 1자 / 영문 최대 2자). */
+function initials(name: string): string {
+  const n = (name || '?').trim()
+  if (!n) return '?'
+  const parts = n.split(/\s+/)
+  if (parts.length >= 2) return (parts[0][0] + parts[1][0]).toUpperCase()
+  return /[a-zA-Z]/.test(n) ? n.slice(0, 2).toUpperCase() : n.slice(0, 1)
+}
+
+@customElement('ox-board-ai-chat')
+export class OxBoardAIChat extends LitElement {
+  /** 영속 세션 id. 없으면 ad-hoc (메시지 영속 안 됨). */
+  @property({ type: String, attribute: 'session-id' })
+  sessionId?: string
+
+  /**
+   * 보드의 모든 ChatSession 리스트 — 다중 세션 활성화 시 탭 UI 로 표시.
+   *
+   * 빈 배열 / 미지정 → 단일 세션 UX (탭 안 보임). 한 보드 = 한 세션 가정의 기존 호출자
+   * 호환. host (board-modeller-page) 가 chatSessionsByBoard query 결과를 그대로 전달.
+   *
+   * 이 컴포넌트는 list 자체를 fetch 하지 않음 — 영속 모델 / 권한 / 페이지네이션 정책은
+   * host 책임. 본 컴포넌트는 표시 + 이벤트 emission 만.
+   */
+  @property({ type: Array, attribute: false })
+  sessions: Array<{ id: string; name?: string; createdAt?: string }> = []
+
+  /**
+   * 현재 BoardModel — chat() 입력으로 그대로 전달.
+   *
+   * 주의: 호스트가 라이브 편집 가능한 캔버스(things-scene)를 갖고 있다면, 캔버스 안에서
+   * 일어나는 수작업 편집이 이 property 에는 자동 반영되지 않는다. 이 경우 `boardProvider`
+   * 콜백을 같이 넘기면 send() 시점에 라이브 보드를 pull 한다.
+   */
+  @property({ type: Object })
+  currentBoard?: any
+
+  /**
+   * 라이브 보드 모델 공급자 (선택).
+   *
+   * 호스트가 things-scene 같은 캔버스를 사용 중이면 사용자가 캔버스에서 수작업 편집한
+   * 내용은 `currentBoard` property 에 자동 반영되지 않는다. 이 콜백을 등록하면 `send()`
+   * 직전에 호출해 가장 최신 보드를 pull → AI 가 항상 라이브 상태를 본다.
+   *
+   * 우선순위: boardProvider() ?? currentBoard.
+   */
+  @property({ attribute: false })
+  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 이지 검색이 아님.
+   */
+  @property({ attribute: false })
+  searchProvider?: (query: string) => FilterResult[]
+
+  /**
+   * `@` mention 도메인 사용자 공급자 (선택). 호스트가 `domainUsersForMention` query 로 wrap.
+   *
+   * 호스트는 query 문자열을 받아 도메인 사용자 후보 (id/name/email) 배열을 돌려준다.
+   * 미설정 시 `@` popup 은 빈 결과 (사용자가 멘션 못 함). 멀티유저 환경 활성화 정책에 따라
+   * 호스트가 set 해야 활성화. async 가 자연스러우므로 Promise 반환 가능.
+   */
+  @property({ attribute: false })
+  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" 류 지시어 해석에 사용.
+   */
+  @property({ type: Array, attribute: false })
+  selectedRefids: number[] = []
+
+  /** board-import registry scopes. */
+  @property({ type: Array })
+  scopes?: string[]
+
+  @property({ type: Array, attribute: 'known-types' })
+  knownTypes?: string[]
+
+  @property({ type: Array })
+  categories?: string[]
+
+  /**
+   * 컴포넌트 type 별 유효 속성 스킴.
+   * 형태: [{ type, description?, group?, properties? }]
+   * LLM 이 정확한 컴포넌트를 만들도록 mutation input 으로 forwarding.
+   */
+  @property({ type: Array, attribute: false })
+  componentSchemas?: Array<{ type: string; description?: string; group?: string; properties?: Record<string, any> }>
+
+  @property({ type: String })
+  placeholder = '자연어로 명령하세요 (Shift+Enter 줄바꿈, Enter 전송)'
+
+  @state()
+  private lines: ChatLine[] = []
+
+  @state()
+  private input = ''
+
+  /** 마지막 send 실패 시 보존 — 다시 시도 버튼 클릭 시 사용 */
+  @state()
+  private lastFailedInput?: string
+
+  /** 되돌려진 patch id 들 — 한 번 revert 한 patch 는 버튼 비활성 */
+  @state()
+  private revertedPatchIds = new Set<string>()
+
+  /** mini action — 인라인 예시 토글 */
+  @state()
+  private examplesOpen = false
+
+  /** 복사 toast 표시 상태 */
+  @state()
+  private toastMessage?: string
+
+  /** 복사 confirmation feedback (메시지 idx → 짧은 시간 동안 ✓ 표시) */
+  @state()
+  private copiedIdx?: number
+
+  @state()
+  private busy = false
+
+  @state()
+  private errorMessage?: string
+
+  /** C4 presence/roster — 세션 참여자 목록. lastSeenAt 으로 online 판정. */
+  @state()
+  private participants: Array<{ id: string; role: string; lastSeenAt?: string; user?: { id: string; name?: string } }> = []
+
+  /** roster online 재평가 트리거 — heartbeat tick 마다 갱신(시간 경과 반영). */
+  @state()
+  private _presenceTick = 0
+
+  private _heartbeatTimer?: ReturnType<typeof setInterval>
+
+  /** C4 그룹챗 — 메시지 실시간 방송 구독 핸들 + 에코 dedup. */
+  private _messageSub?: { unsubscribe: () => void }
+  /** 이미 transcript 에 반영된 서버 메시지 id 집합 — 자기 에코·중복 방송 차단. */
+  private _seenMessageIds = new Set<string>()
+  /** optimistic 라인 임시 핸들 시퀀스 (index 비의존 reconcile 용). */
+  private _localSeq = 0
+
+  /** 현재 로그인 사용자 id — 그룹챗에서 내 메시지 vs 타인 메시지 구분 (발신자 표시). */
+  private get _myUserId(): string | undefined {
+    return (auth.credential as any)?.id
+  }
+
+  /** Mention popup — `#` (컴포넌트) / `@` (카탈로그) / `/` (slash) 트리거 시 활성.
+   *  단일 popup 재사용 — mentionTrigger 로 활성 trigger 추적. */
+  @state()
+  private mentionOpen = false
+
+  /** popup 표시용 — F-Finder 처럼 matchType + matchValue 동봉된 결과 */
+  @state()
+  private mentionResults: FilterResult[] = []
+
+  @state()
+  private mentionActiveIndex = 0
+
+  /** filter cap (50) 으로 잘라낸 추가 매칭 수 — popup 의 'N more' 표시용 */
+  @state()
+  private mentionOverflow = 0
+
+  /** 현재 활성 mention 의 textarea 내 trigger 위치 */
+  private mentionHashPos = -1
+
+  /** 현재 활성 trigger char — '#' / '@' / '/'. popup 비활성 시 의미 없음. */
+  private mentionTrigger: '#' | '@' | '/' = '#'
+
+  /** popup 열기 직전 사용자 selection 스냅샷 — Esc/blur close 시 원복용 */
+  private originalSelectedRefids: number[] = []
+
+  /** popup 에서 명시 선택된 #mention 매핑 — {token: refid}.
+   *  사용자 textarea 에는 #token 만 보이지만 server 한테는 정확한 refid 전달.
+   *  send 시 mutation input.mentions 로 함께 전송. 사용자가 textarea 비우거나
+   *  새 채팅 시작하면 정리. */
+  private pickedMentions: Map<string, number> = new Map()
+
+  /** popup 에서 명시 선택된 @user 멘션 매핑 — {token: userId}.
+   *  textarea 에는 @username 만 보이지만 server 한테는 정확한 userId 전달.
+   *  send 시 mutation input.userMentions 로 함께 전송. */
+  private pickedUserMentions: Map<string, string> = new Map()
+
+  /** input 디바운스 timer — 150ms 후 refreshMentionPopup 실행 (F-Finder 와 동일) */
+  private inputDebounceTimer?: ReturnType<typeof setTimeout>
+
+  /** centerTo 디바운스 timer — arrow nav / hover 빠를 때 카메라 애니메이션 race 방지 */
+  private centerDebounceTimer?: ReturnType<typeof setTimeout>
+
+  /** Default 카탈로그 후보 캐시 — chat panel mount 시 1회 빌드 */
+  private cachedCatalogCandidates: MentionCandidate[] = buildCatalogCandidates(
+    DEFAULT_CATALOG_ENTRIES
+  )
+
+  /** Default slash template 후보 캐시 — chat panel mount 시 1회 빌드 */
+  private cachedSlashCandidates: MentionCandidate[] = buildSlashCandidates(
+    DEFAULT_SLASH_TEMPLATES
+  )
+
+  /** `@` 마지막 query 의 도메인 사용자 후보 캐시 — userProvider 응답 도착 시 갱신.
+   *  query 별 캐시가 아니라 단순 "최근 결과" — async race 회피. */
+  private cachedUserCandidates: MentionCandidate[] = []
+
+  /** 진행 중인 userProvider fetch token — 늦게 도착한 응답이 최신을 덮어쓰지 않도록 식별. */
+  private userFetchToken = 0
+
+  static styles = [
+    // 어플리케이션 표준 스크롤바 (--scrollbar-width / --scrollbar-thumb-color 등 호스트 변수 따름)
+    ScrollbarStyles,
+    css`
+    /*
+      Material Design 3 토큰 사용 — 사용자 테마 (라이트/다크/브랜드) 자동 반영.
+      각 var() 의 두 번째 인자는 토큰 미정의 시 fallback (현 디자인 톤).
+    */
+    :host {
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+      min-height: 240px;
+      position: relative;
+      font:
+        400 11px / 1.55 -apple-system,
+        BlinkMacSystemFont,
+        'Inter',
+        'Pretendard',
+        'Segoe UI',
+        Roboto,
+        sans-serif;
+      letter-spacing: -0.005em;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      background: var(--md-sys-color-surface, #ffffff);
+    }
+
+    /* ── C4 Roster (participants + presence) ───────────── */
+    .roster {
+      display: flex;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 4px;
+      padding: 4px 8px;
+      border-bottom: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+    }
+    .roster-count {
+      display: inline-flex;
+      align-items: center;
+      gap: 2px;
+      font-size: 10px;
+      opacity: 0.7;
+      margin-right: 2px;
+    }
+    .roster-count md-icon {
+      font-size: 13px;
+      width: 13px;
+      height: 13px;
+    }
+    .roster-chip {
+      display: inline-flex;
+      align-items: center;
+      gap: 3px;
+      padding: 1px 6px 1px 4px;
+      border-radius: 9px;
+      font-size: 10px;
+      background: var(--md-sys-color-surface-variant, #f1f5f9);
+    }
+    .roster-chip.offline {
+      opacity: 0.45;
+    }
+    .roster-dot {
+      width: 6px;
+      height: 6px;
+      border-radius: 50%;
+      background: #cbd5e1;
+    }
+    .roster-chip.online .roster-dot {
+      background: #22c55e;
+    }
+
+    /* ── Session tabs ─────────────────────────────────── */
+    .session-tabs {
+      display: flex;
+      align-items: center;
+      gap: 2px;
+      padding: 4px 6px 0 6px;
+      border-bottom: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      background: var(--md-sys-color-surface-container-low, #fafbfc);
+      overflow-x: auto;
+      scrollbar-width: thin;
+      flex-shrink: 0;
+    }
+    .session-tab {
+      flex-shrink: 0;
+      padding: 4px 10px;
+      font-size: 11px;
+      line-height: 1.4;
+      color: var(--md-sys-color-on-surface-variant, #64748b);
+      background: transparent;
+      border: 1px solid transparent;
+      border-bottom: 0;
+      border-top-left-radius: 5px;
+      border-top-right-radius: 5px;
+      cursor: pointer;
+      max-width: 160px;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .session-tab:hover {
+      background: var(--md-sys-color-surface-container, #f1f5f9);
+    }
+    .session-tab.active {
+      background: var(--md-sys-color-surface, #ffffff);
+      color: var(--md-sys-color-on-surface, #0f172a);
+      border-color: var(--md-sys-color-outline-variant, #e2e8f0);
+      font-weight: 500;
+      position: relative;
+    }
+    .session-tab.active::after {
+      content: '';
+      position: absolute;
+      left: 0;
+      right: 0;
+      bottom: -1px;
+      height: 1px;
+      background: var(--md-sys-color-surface, #ffffff);
+    }
+    .session-tab-new {
+      flex-shrink: 0;
+      padding: 4px 8px 4px 6px;
+      background: transparent;
+      border: 0;
+      cursor: pointer;
+      color: var(--md-sys-color-on-surface-variant, #64748b);
+      display: inline-flex;
+      align-items: center;
+      gap: 2px;
+      font-size: 11px;
+      line-height: 1.4;
+      border-radius: 5px;
+      white-space: nowrap;
+    }
+    .session-tab-new:hover {
+      color: var(--md-sys-color-primary, #2563eb);
+      background: var(--md-sys-color-surface-container, #f1f5f9);
+    }
+    .session-tab-new md-icon {
+      --md-icon-size: 14px;
+      font-size: 14px;
+    }
+
+    /* ── Messages ─────────────────────────────────────── */
+    /* 스크롤바는 ScrollbarStyles (위쪽 styles 배열) 가 처리 — 어플리케이션 표준 따름 */
+    .messages {
+      flex: 1;
+      overflow-y: auto;
+      overflow-x: hidden; /* 가로 스크롤 차단 — 자식 (empty / msg) 내부에서 wrap 처리 */
+      padding: 10px 16px 4px;
+      display: flex;
+      flex-direction: column;
+      gap: 4px; /* 단일 spacing source — .msg-wrap 의 자체 margin 은 0 */
+      scroll-behavior: smooth;
+      min-width: 0; /* flex item 의 기본 min-content 무시 — 자식 ellipsis/wrap 동작 */
+    }
+
+    /* ── Empty state — onboarding 가이드 ───────────────── */
+    .empty {
+      margin: auto;
+      text-align: left;
+      width: 100%;
+      max-width: 360px;
+      box-sizing: border-box;
+      min-width: 0;
+      display: flex;
+      flex-direction: column;
+      gap: 16px;
+      word-break: break-word; /* 긴 한글 / URL 도 줄바꿈해 가로 overflow 방지 */
+      overflow-wrap: anywhere;
+    }
+    .empty .header {
+      text-align: center;
+      padding: 8px 0 4px;
+    }
+    .empty .icon {
+      font-size: 22px;
+      opacity: 0.4;
+      margin-bottom: 8px;
+      color: var(--md-sys-color-primary, currentColor);
+      display: block;
+    }
+    .empty .title {
+      color: var(--md-sys-color-on-surface, #0f172a);
+      font-size: 12.5px;
+      font-weight: 600;
+      margin-bottom: 4px;
+      letter-spacing: -0.01em;
+    }
+    .empty .subtitle {
+      color: var(--md-sys-color-on-surface-variant, #475569);
+      font-size: 10.5px;
+      line-height: 1.5;
+    }
+
+    .empty .group {
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+    }
+    .empty .group-label {
+      font-size: 9.5px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      font-weight: 600;
+      padding: 0 2px;
+    }
+    .empty .example {
+      all: unset;
+      display: block;
+      cursor: pointer;
+      padding: 7px 10px;
+      font-size: 11px;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      border: 1px solid var(--md-sys-color-outline-variant, #eef2f6);
+      border-radius: 8px;
+      line-height: 1.5;
+      box-sizing: border-box;
+      width: 100%;
+      max-width: 100%;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+      transition:
+        background 0.15s,
+        border-color 0.15s,
+        transform 0.1s;
+    }
+    .empty .example:hover {
+      background: var(--md-sys-color-surface-container-high, #f1f5f9);
+      border-color: var(--md-sys-color-outline, #cbd5e1);
+    }
+    .empty .example:active {
+      transform: scale(0.99);
+    }
+    .empty .example .arrow {
+      float: right;
+      opacity: 0.4;
+      margin-left: 8px;
+      font-size: 11px;
+    }
+
+    .empty .footer {
+      margin-top: 4px;
+      padding: 8px 4px 0;
+      border-top: 1px solid var(--md-sys-color-outline-variant, #eef2f6);
+      color: var(--md-sys-color-outline, #94a3b8);
+      font-size: 10px;
+      line-height: 1.6;
+      text-align: center;
+    }
+    .empty .footer .badge {
+      display: inline-block;
+      margin: 0 4px;
+      padding: 1px 7px;
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      border-radius: 8px;
+      font-size: 9.5px;
+      color: var(--md-sys-color-on-surface-variant, #64748b);
+    }
+    /* ── Trigger chip row (empty state) ──────────────── */
+    .empty .trigger-row {
+      margin: 12px 0 4px;
+      padding: 10px 12px;
+      background: var(--md-sys-color-surface-container-low, #f8fafc);
+      border: 1px solid var(--md-sys-color-outline-variant, #eef2f6);
+      border-radius: 10px;
+    }
+    .empty .trigger-row-label {
+      font-size: 10px;
+      color: var(--md-sys-color-on-surface-variant, #64748b);
+      margin-bottom: 6px;
+      text-align: center;
+      letter-spacing: 0.02em;
+    }
+    .empty .trigger-chips {
+      display: flex;
+      gap: 6px;
+      justify-content: center;
+      flex-wrap: wrap;
+    }
+    .empty .trigger-chip {
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+      padding: 5px 10px;
+      background: var(--md-sys-color-surface, #ffffff);
+      border: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      border-radius: 18px;
+      cursor: pointer;
+      font-size: 11.5px;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      transition:
+        border-color 0.15s,
+        background 0.15s,
+        color 0.15s;
+    }
+    .empty .trigger-chip:hover {
+      border-color: var(--md-sys-color-primary, #2563eb);
+      background: var(--md-sys-color-primary-container, #dbeafe);
+      color: var(--md-sys-color-on-primary-container, #1e3a8a);
+    }
+    .empty .trigger-chip .trigger-char {
+      font-family:
+        'SF Mono',
+        Menlo,
+        Monaco,
+        Consolas,
+        monospace;
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--md-sys-color-primary, #2563eb);
+      min-width: 12px;
+      text-align: center;
+    }
+    .empty .trigger-chip:hover .trigger-char {
+      color: var(--md-sys-color-on-primary-container, #1e3a8a);
+    }
+    .empty .trigger-chip .trigger-desc {
+      font-weight: 500;
+    }
+
+    /* ── Message label (sender hint) ──────────────────── */
+    .msg-label {
+      font-size: 9.5px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      letter-spacing: 0.05em;
+      font-weight: 500;
+      text-transform: uppercase;
+      margin: 4px 0 1px 4px;
+      align-self: flex-start;
+    }
+    .msg-label:first-child {
+      margin-top: 0;
+    }
+
+    /* ── Message wrapper (메시지 + hover 액션) ────────── */
+    .msg-wrap {
+      display: flex;
+      flex-direction: column;
+      width: fit-content;
+      max-width: min(92%, 420px);
+      /* margin 0 — spacing 은 .messages gap 단일 source */
+    }
+    .msg-wrap.user {
+      align-self: flex-end;
+      align-items: flex-end;
+    }
+    .msg-wrap.assistant {
+      align-self: flex-start;
+      align-items: flex-start;
+    }
+    .msg-wrap.system {
+      align-self: center;
+      align-items: center;
+      max-width: 100%;
+    }
+
+    /* ── Message bubble ───────────────────────────────── */
+    .msg {
+      display: inline-block;
+      width: fit-content;
+      max-width: 100%;
+      padding: 5px 9px;
+      border-radius: 10px;
+      white-space: normal;
+      overflow-wrap: anywhere;
+      font-size: 11px;
+      line-height: 1.45;
+    }
+
+    .msg.user {
+      align-self: flex-end;
+      background: var(--md-sys-color-primary, #1e293b);
+      color: var(--md-sys-color-on-primary, #f8fafc);
+      border-radius: 12px 12px 3px 12px;
+      /* margin-top 0 — .messages gap 으로만 spacing */
+    }
+
+    /* 그룹챗 — 다른 참여자의 메시지. 내 메시지(우측 primary)와 구분: 좌측 정렬 + 보조 색. */
+    .msg-wrap.user.other {
+      align-self: flex-start;
+      align-items: flex-start;
+    }
+    .msg.user.other {
+      align-self: flex-start;
+      background: var(--md-sys-color-secondary-container, #e2e8f0);
+      color: var(--md-sys-color-on-secondary-container, #0f172a);
+      border-radius: 12px 12px 12px 3px;
+    }
+    /* 발신자 이름 라벨 — AI 라벨(대문자)과 달리 사람 이름은 그대로. */
+    .msg-label.sender {
+      text-transform: none;
+      letter-spacing: 0;
+      color: var(--md-sys-color-primary, #475569);
+    }
+
+    .msg.assistant {
+      align-self: flex-start;
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      color: var(--md-sys-color-on-surface, #0f172a);
+      border: 1px solid var(--md-sys-color-outline-variant, #eef2f6);
+      border-radius: 12px 12px 12px 3px;
+    }
+
+    /* ── Markdown 렌더 (AI 응답) ──────────────────────── */
+    .md-body {
+      display: block;
+    }
+    .md-body > :first-child {
+      margin-top: 0;
+    }
+    .md-body > :last-child {
+      margin-bottom: 0;
+    }
+    .md-body p {
+      margin: 0 0 4px;
+      line-height: 1.45;
+    }
+    .md-body ul,
+    .md-body ol {
+      margin: 2px 0 4px;
+      padding-left: 16px;
+    }
+    .md-body li {
+      margin: 0;
+      line-height: 1.45;
+    }
+    .md-body li > p {
+      margin: 0;
+    }
+    .md-body strong {
+      font-weight: 600;
+    }
+    .md-body em {
+      font-style: italic;
+    }
+    /* '#token' mention — popup 의 match-badge 톤과 맞춤. 채팅 버블에서 컴포넌트
+       참조임을 시각적으로 구분 (사용자/AI 메시지 양쪽). */
+    .md-body .mention {
+      display: inline-block;
+      padding: 0 5px;
+      border-radius: 4px;
+      background: var(--md-sys-color-primary-container, rgba(37, 99, 235, 0.12));
+      color: var(--md-sys-color-on-primary-container, #1e40af);
+      font-weight: 500;
+      white-space: nowrap;
+      cursor: pointer;
+      transition: background 0.12s;
+    }
+    .md-body .mention:hover {
+      background: var(--md-sys-color-primary, rgba(37, 99, 235, 0.25));
+      color: var(--md-sys-color-on-primary, #ffffff);
+    }
+    .msg.user .md-body .mention {
+      background: rgba(255, 255, 255, 0.22);
+      color: inherit;
+    }
+    .msg.user .md-body .mention:hover {
+      background: rgba(255, 255, 255, 0.40);
+    }
+    .md-body code {
+      font-family:
+        'SF Mono',
+        Menlo,
+        Monaco,
+        Consolas,
+        monospace;
+      font-size: 10px;
+      padding: 1px 4px;
+      background: var(--md-sys-color-surface-container-high, rgba(15, 23, 42, 0.06));
+      border-radius: 3px;
+    }
+    .md-body pre {
+      margin: 5px 0;
+      padding: 6px 8px;
+      background: var(--md-sys-color-surface-container-high, rgba(15, 23, 42, 0.06));
+      border-radius: 5px;
+      overflow-x: auto;
+      font-size: 10px;
+      line-height: 1.5;
+    }
+    /* user 메시지(어두운 배경) 위에서는 code/pre 의 contrast 보정 */
+    .msg.user .md-body code,
+    .msg.user .md-body pre {
+      background: rgba(255, 255, 255, 0.15);
+    }
+    .msg.user .md-body a {
+      color: inherit;
+      text-decoration: underline;
+      text-underline-offset: 2px;
+    }
+    .msg.user .md-body blockquote {
+      border-left-color: rgba(255, 255, 255, 0.3);
+      color: rgba(255, 255, 255, 0.85);
+    }
+    .msg.user .md-body hr {
+      border-top-color: rgba(255, 255, 255, 0.2);
+    }
+    .md-body pre code {
+      padding: 0;
+      background: transparent;
+      font-size: inherit;
+    }
+    .md-body a {
+      color: var(--md-sys-color-primary, #1e293b);
+      text-decoration: underline;
+      text-underline-offset: 2px;
+    }
+    .md-body a:hover {
+      text-decoration: none;
+    }
+    .md-body h1,
+    .md-body h2,
+    .md-body h3,
+    .md-body h4 {
+      margin: 4px 0 2px;
+      font-weight: 600;
+      line-height: 1.35;
+    }
+    .md-body h1 { font-size: 13px; }
+    .md-body h2 { font-size: 12px; }
+    .md-body h3,
+    .md-body h4 { font-size: 11.5px; }
+    .md-body blockquote {
+      margin: 4px 0;
+      padding: 1px 8px;
+      border-left: 2px solid var(--md-sys-color-outline-variant, #cbd5e1);
+      color: var(--md-sys-color-on-surface-variant, #64748b);
+    }
+    .md-body hr {
+      border: 0;
+      border-top: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      margin: 6px 0;
+    }
+    .md-body table {
+      border-collapse: collapse;
+      margin: 4px 0;
+      font-size: 10px;
+    }
+    .md-body th,
+    .md-body td {
+      border: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      padding: 2px 6px;
+    }
+    .md-body th {
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      font-weight: 600;
+    }
+
+    .msg.system {
+      align-self: center;
+      background: transparent;
+      color: var(--md-sys-color-outline, #94a3b8);
+      font-size: 10px;
+      font-style: italic;
+      max-width: 100%;
+      padding: 2px 8px;
+      margin: 0;
+      border: 0;
+    }
+
+    .msg.pending {
+      opacity: 0.5;
+    }
+    .typing-dots {
+      display: inline-flex;
+      gap: 4px;
+      align-items: center;
+      vertical-align: middle;
+    }
+    .typing-dots > span {
+      display: inline-block;
+      width: 6px;
+      height: 6px;
+      border-radius: 50%;
+      background: currentColor;
+      opacity: 0.4;
+      animation: pulse 1.2s ease-in-out infinite;
+    }
+    .typing-dots > span:nth-child(2) { animation-delay: 0.2s; }
+    .typing-dots > span:nth-child(3) { animation-delay: 0.4s; }
+    @keyframes pulse {
+      0%, 100% { opacity: 0.2; transform: scale(0.85); }
+      50% { opacity: 0.7; transform: scale(1.1); }
+    }
+
+    /* ── Patch indicator + 인라인 되돌리기 ─────────────── */
+    .summary {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      margin-top: 4px;
+      padding: 3px 4px 3px 8px;
+      background: var(--md-sys-color-surface-container-high, #f1f5f9);
+      border-radius: 6px;
+      font-size: 10px;
+      color: var(--md-sys-color-on-surface-variant, #475569);
+      line-height: 1;
+    }
+    .summary md-icon {
+      --md-icon-size: 13px;
+      color: var(--md-sys-color-tertiary, #10b981);
+    }
+    .summary.reverted {
+      opacity: 0.6;
+    }
+    .summary.reverted md-icon {
+      color: var(--md-sys-color-outline, #94a3b8);
+    }
+    .summary .summary-text {
+      letter-spacing: 0.01em;
+    }
+    .summary .revert-btn {
+      height: 20px;
+      padding: 0 8px;
+      background: transparent;
+      border: 0;
+      border-radius: 4px;
+      cursor: pointer;
+      font-family: inherit;
+      letter-spacing: inherit;
+      font-size: 10px;
+      color: var(--md-sys-color-on-surface-variant, #475569);
+      line-height: 1;
+      transition: background 0.12s, color 0.12s;
+      width: auto;
+    }
+    .summary .revert-btn:hover:not(:disabled) {
+      background: var(--md-sys-color-surface, #ffffff);
+      color: var(--md-sys-color-on-surface, #0f172a);
+    }
+    .summary.reverted .revert-btn,
+    .summary .revert-btn:disabled {
+      display: none;
+    }
+
+    /* ── Follow-up question ───────────────────────────── */
+    .followup {
+      font-size: 10.5px;
+      color: var(--md-sys-color-on-secondary-container, #92400e);
+      background: var(--md-sys-color-secondary-container, #fffbeb);
+      border-left: 2px solid var(--md-sys-color-secondary, #f59e0b);
+      padding: 5px 8px;
+      border-radius: 0 5px 5px 0;
+      margin-top: 4px;
+      line-height: 1.45;
+    }
+
+    /* ── Tool usages fold-able 박스 — AI 도구 호출 trace ───── */
+    .tool-usages {
+      margin-top: 4px;
+      border: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      border-radius: 6px;
+      background: var(--md-sys-color-surface-container-low, #f8fafc);
+      overflow: hidden;
+      font-size: 10.5px;
+    }
+    .tool-usages-header {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      width: 100%;
+      padding: 5px 8px;
+      background: transparent;
+      border: 0;
+      cursor: pointer;
+      color: var(--md-sys-color-on-surface-variant, #475569);
+      font-family: inherit;
+      font-size: inherit;
+      letter-spacing: inherit;
+      text-align: left;
+    }
+    .tool-usages-header:hover {
+      background: var(--md-sys-color-surface-container, #f1f5f9);
+    }
+    .tool-usages-icon,
+    .tool-usages-chevron {
+      --md-icon-size: 14px;
+      flex-shrink: 0;
+    }
+    .tool-usages-summary {
+      flex: 1;
+      font-weight: 500;
+    }
+    .tool-usages-counts {
+      color: var(--md-sys-color-outline, #94a3b8);
+      font-weight: 400;
+      font-size: 10px;
+    }
+    .tool-usages-list {
+      list-style: none;
+      margin: 0;
+      padding: 0 8px 8px;
+      display: flex;
+      flex-direction: column;
+      gap: 6px;
+    }
+    .tool-usage-item {
+      border-left: 2px solid var(--md-sys-color-outline-variant, #cbd5e1);
+      padding: 4px 8px 4px 8px;
+      background: var(--md-sys-color-surface, #ffffff);
+      border-radius: 0 4px 4px 0;
+    }
+    .tool-usage-item.kind-read {
+      border-left-color: var(--md-sys-color-tertiary, #10b981);
+    }
+    .tool-usage-item.kind-write {
+      border-left-color: var(--md-sys-color-primary, #1e293b);
+    }
+    .tool-usage-item.kind-unknown {
+      border-left-color: var(--md-sys-color-error, #b91c1c);
+    }
+    .tool-usage-head {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      margin-bottom: 3px;
+    }
+    .tool-usage-step {
+      color: var(--md-sys-color-outline, #94a3b8);
+      font-size: 10px;
+    }
+    .tool-usage-name {
+      font-weight: 600;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      font-family: 'SF Mono', Menlo, Monaco, Consolas, monospace;
+      font-size: 10.5px;
+    }
+    .tool-usage-kind {
+      font-size: 9.5px;
+      padding: 1px 5px;
+      border-radius: 3px;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      font-weight: 600;
+    }
+    .tool-usage-kind.kind-read {
+      color: var(--md-sys-color-on-tertiary, #ffffff);
+      background: var(--md-sys-color-tertiary, #10b981);
+    }
+    .tool-usage-kind.kind-write {
+      color: var(--md-sys-color-on-primary, #ffffff);
+      background: var(--md-sys-color-primary, #1e293b);
+    }
+    .tool-usage-kind.kind-unknown {
+      color: var(--md-sys-color-on-error, #ffffff);
+      background: var(--md-sys-color-error, #b91c1c);
+    }
+    .tool-usage-args,
+    .tool-usage-result {
+      margin: 2px 0 0;
+      padding: 4px 6px;
+      background: var(--md-sys-color-surface-container-high, rgba(15, 23, 42, 0.04));
+      border-radius: 3px;
+      font-family: 'SF Mono', Menlo, Monaco, Consolas, monospace;
+      font-size: 10px;
+      line-height: 1.4;
+      white-space: pre-wrap;
+      overflow-x: auto;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      max-height: 180px;
+      overflow-y: auto;
+    }
+    .tool-usage-args {
+      border-left: 2px solid var(--md-sys-color-outline-variant, #cbd5e1);
+    }
+    .tool-usage-result {
+      border-left: 2px solid var(--md-sys-color-outline, #94a3b8);
+    }
+
+    /* ── Hover actions (assistant 메시지만, Material icon button) ── */
+    .msg-actions {
+      display: flex;
+      gap: 2px;
+      margin-top: 2px;
+      padding: 0;
+      opacity: 0;
+      transition: opacity 0.15s;
+      pointer-events: none;
+    }
+    .msg-wrap:hover .msg-actions,
+    .msg-wrap:focus-within .msg-actions {
+      opacity: 1;
+      pointer-events: auto;
+    }
+    .msg-actions .msg-action {
+      width: 22px;
+      height: 22px;
+      padding: 0;
+      background: transparent;
+      border: 0;
+      border-radius: 5px;
+      cursor: pointer;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      color: var(--md-sys-color-outline, #94a3b8);
+      transition:
+        background 0.12s,
+        color 0.12s;
+    }
+    .msg-actions .msg-action:hover:not(:disabled) {
+      background: var(--md-sys-color-surface-container-high, #e2e8f0);
+      color: var(--md-sys-color-on-surface, #0f172a);
+    }
+    .msg-actions .msg-action:disabled {
+      opacity: 0.4;
+      cursor: default;
+    }
+    .msg-actions .msg-action.confirmed {
+      color: var(--md-sys-color-tertiary, #10b981);
+    }
+    .msg-actions .msg-action md-icon {
+      --md-icon-size: 14px;
+    }
+
+    /* ── Error banner ─────────────────────────────────── */
+    .error {
+      color: var(--md-sys-color-on-error-container, #b91c1c);
+      padding: 7px 11px;
+      background: var(--md-sys-color-error-container, #fef2f2);
+      border: 1px solid var(--md-sys-color-error, #fee2e2);
+      border-radius: 8px;
+      margin: 0 16px 8px;
+      font-size: 10.5px;
+      line-height: 1.5;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+    }
+    .error .error-text {
+      flex: 1;
+    }
+    .error .retry-btn {
+      flex-shrink: 0;
+      padding: 3px 8px;
+      font-size: 10px;
+      font-family: inherit;
+      letter-spacing: inherit;
+      background: var(--md-sys-color-error, #b91c1c);
+      color: var(--md-sys-color-on-error, #ffffff);
+      border: 0;
+      border-radius: 6px;
+      cursor: pointer;
+      transition: opacity 0.15s;
+      width: auto;
+      height: auto;
+    }
+    .error .retry-btn:hover {
+      opacity: 0.88;
+    }
+
+    /* ── Composer (actions + input 통합 영역) ──────────── */
+    .composer {
+      border-top: 1px solid var(--md-sys-color-outline-variant, #f1f5f9);
+      background: var(--md-sys-color-surface, #ffffff);
+      display: flex;
+      flex-direction: column;
+    }
+
+    /* ── Mini action row (메시지 시작 후) ──────────────── */
+    .actions-row {
+      display: flex;
+      gap: 6px;
+      padding: 6px 14px 4px;
+      flex-wrap: wrap;
+      align-items: center;
+    }
+    /* Material 3 assist-chip 톤 — height 24, font label-small */
+    .action {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      gap: 5px;
+      height: 24px;
+      padding: 0 10px;
+      font-size: 11px;
+      font-family: inherit;
+      letter-spacing: inherit;
+      line-height: 1;
+      color: var(--md-sys-color-on-surface-variant, #475569);
+      background: transparent;
+      border: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      border-radius: 8px;
+      cursor: pointer;
+      transition:
+        background 0.15s,
+        border-color 0.15s,
+        color 0.15s;
+      width: auto;
+      vertical-align: middle;
+    }
+    .action:hover {
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      border-color: var(--md-sys-color-outline, #cbd5e1);
+      color: var(--md-sys-color-on-surface, #0f172a);
+    }
+    .action:active {
+      transform: scale(0.97);
+    }
+    .action md-icon {
+      --md-icon-size: 14px;
+      opacity: 0.7;
+    }
+
+    /* ── Inline examples (action row 의 "예시" 토글 시) ──── */
+    .inline-examples {
+      padding: 4px 16px 0;
+      display: flex;
+      flex-direction: column;
+      gap: 3px;
+    }
+    .inline-examples .ex-row {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 4px;
+    }
+    .inline-examples .ex-row .ex-label {
+      font-size: 9px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+      margin-right: 2px;
+      align-self: center;
+      font-weight: 600;
+    }
+    .inline-examples .ex {
+      all: unset;
+      cursor: pointer;
+      padding: 2px 8px;
+      font-size: 10px;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      border: 1px solid var(--md-sys-color-outline-variant, #eef2f6);
+      border-radius: 10px;
+      transition: background 0.15s;
+    }
+    .inline-examples .ex:hover {
+      background: var(--md-sys-color-surface-container-high, #f1f5f9);
+    }
+
+    /* ── Input area ───────────────────────────────────── */
+    /* border-top 은 .composer 가 담당 (actions-row 가 같은 wrapper 안) */
+    .input-row {
+      display: flex;
+      gap: 8px;
+      padding: 6px 14px 10px;
+      background: transparent;
+      align-items: flex-end;
+    }
+    /* 메시지 시작 전 — actions-row 가 없을 때는 input-row 가 직접 border-top */
+    .composer.no-actions .input-row {
+      padding-top: 10px;
+    }
+
+    /* mention popup — textarea wrapper 가 relative 컨텍스트, popup 이 textarea
+       와 정확히 같은 폭/좌표 (좌우 끝 정렬). send 버튼 영역은 제외. */
+    .textarea-wrap {
+      flex: 1;
+      position: relative;
+      display: flex;
+      min-width: 0;
+    }
+    .textarea-wrap textarea {
+      flex: 1;
+      width: 100%;
+    }
+    .mention-popup {
+      bottom: calc(100% + 4px);
+      left: 0;
+      right: 0;
+    }
+
+    textarea {
+      flex: 1;
+      padding: 8px 12px;
+      border: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      border-radius: 12px;
+      font: inherit;
+      letter-spacing: inherit;
+      resize: none;
+      min-height: 36px;
+      max-height: 140px;
+      outline: none;
+      transition:
+        border-color 0.2s,
+        box-shadow 0.2s;
+      background: var(--md-sys-color-surface, #ffffff);
+      color: var(--md-sys-color-on-surface, #0f172a);
+    }
+    textarea::placeholder {
+      color: var(--md-sys-color-outline, #94a3b8);
+    }
+    textarea:focus {
+      border-color: var(--md-sys-color-outline, #cbd5e1);
+      box-shadow: 0 0 0 3px var(--md-sys-color-primary-container, rgba(15, 23, 42, 0.08));
+    }
+    textarea:disabled {
+      background: var(--md-sys-color-surface-container, #f8fafc);
+      color: var(--md-sys-color-outline, #94a3b8);
+      cursor: not-allowed;
+    }
+
+    /* ── Send button — ChatGPT 스타일 원형 ↑ (.input-row 안의 button 만) ─── */
+    .input-row > button {
+      width: 32px;
+      height: 32px;
+      padding: 0;
+      background: var(--md-sys-color-primary, #1e293b);
+      color: var(--md-sys-color-on-primary, #ffffff);
+      border: 0;
+      border-radius: 50%;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition:
+        background 0.15s,
+        transform 0.1s,
+        opacity 0.15s;
+      flex-shrink: 0;
+      align-self: flex-end;
+      margin-bottom: 2px;
+    }
+    .input-row > button:disabled {
+      background: var(--md-sys-color-surface-container-highest, #e2e8f0);
+      color: var(--md-sys-color-outline, #94a3b8);
+      cursor: not-allowed;
+    }
+    .input-row > button:hover:not(:disabled) {
+      opacity: 0.88;
+    }
+    .input-row > button:active:not(:disabled) {
+      transform: scale(0.94);
+    }
+    .input-row > button md-icon {
+      --md-icon-size: 18px;
+    }
+    .input-row > button .spinner {
+      width: 12px;
+      height: 12px;
+      border: 1.8px solid currentColor;
+      border-right-color: transparent;
+      border-radius: 50%;
+      animation: spin 0.7s linear infinite;
+    }
+    @keyframes spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+  `
+  ]
+
+  connectedCallback() {
+    super.connectedCallback()
+    // 첫 마운트 시 sessionId 가 이미 set 돼있어도 loadHistory 는 첫 render 후 updated()
+    // 가 처리 — 단일 진입점으로 일관 (이전엔 connectedCallback 과 updated 양쪽이 호출 →
+    // 동시 fetch race 발생).
+  }
+
+  updated(changed: Map<string, any>) {
+    if (changed.has('sessionId')) {
+      // sessionId 가 바뀌면 (set / unset / 다른 보드 전환) 이전 세션의 모든 클라이언트
+      // 컨텍스트 정리 — lines / pickedMentions / errorMessage / input 모두 새지 않도록.
+      // 보드 단위 격리 (ChatSession 1:1 boardId) 가 깨지는 회귀 방지.
+      this.lines = []
+      this.pickedMentions.clear()
+      this.pickedUserMentions.clear()
+      this.cachedUserCandidates = []
+      this.errorMessage = undefined
+      this.input = ''
+      this.participants = []
+      this._seenMessageIds.clear() // 세션 전환 — 에코 dedup 컨텍스트 리셋
+      if (this.sessionId) {
+        this.loadHistory()
+        this._startPresence() // C4: roster 로드 + heartbeat 시작
+        this._startMessageSubscription() // C4: 메시지 실시간 방송 구독
+      } else {
+        this._stopPresence()
+        this._stopMessageSubscription()
+      }
+    }
+    // 자동 스크롤
+    const ms = this.renderRoot.querySelector('.messages') as HTMLElement | null
+    if (ms) ms.scrollTop = ms.scrollHeight
+  }
+
+  disconnectedCallback() {
+    this._stopPresence()
+    this._stopMessageSubscription()
+    super.disconnectedCallback()
+  }
+
+  // ── C4 presence/roster ─────────────────────────────────────────────────────
+  private _startPresence() {
+    this._stopPresence()
+    this._loadParticipants()
+    this._touchPresence() // 즉시 1회 — 내 online 즉시 반영
+    this._heartbeatTimer = setInterval(() => {
+      this._touchPresence()
+      this._loadParticipants()
+      this._presenceTick++ // online 판정 재평가(시간 경과)
+    }, PRESENCE_HEARTBEAT_MS)
+  }
+
+  private _stopPresence() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer)
+      this._heartbeatTimer = undefined
+    }
+  }
+
+  // ── C4 그룹챗 — 메시지 실시간 방송 구독 ─────────────────────────────────────
+  private _startMessageSubscription() {
+    this._stopMessageSubscription()
+    if (!this.sessionId) return
+    try {
+      this._messageSub = client
+        .subscribe({ query: CHAT_MESSAGE_SUBSCRIPTION, variables: { sessionId: this.sessionId } })
+        .subscribe({
+          next: ({ data }: any) => this._onRemoteMessage(data?.chatMessageActivity),
+          error: () => {
+            /* 구독 에러는 채팅 본 기능 무영향 — 히스토리 쿼리로 폴백 */
+          }
+        })
+    } catch {
+      /* 구독 미지원 환경 — 조용히 스킵 */
+    }
+  }
+
+  private _stopMessageSubscription() {
+    if (this._messageSub) {
+      try {
+        this._messageSub.unsubscribe()
+      } catch {
+        /* 이미 닫힘 */
+      }
+      this._messageSub = undefined
+    }
+  }
+
+  /** 서버 ChatMessage → ChatLine. */
+  private _msgToLine(m: any): ChatLine {
+    return remoteMessageToLine(m) as ChatLine
+  }
+
+  /**
+   * 원격(방송) 메시지 수신 — 에코·중복은 id 로 차단, 신규는 transcript 에 append.
+   * 자기 발신 메시지의 id 는 전송 reconcile 에서 이미 _seenMessageIds 에 등록됨.
+   */
+  private _onRemoteMessage(m: any) {
+    const next = receiveRemoteMessage(this.lines as any, this._seenMessageIds, m)
+    if (!next) return
+    this._seenMessageIds = next.seen
+    this.lines = next.lines as ChatLine[]
+  }
+
+  /**
+   * 전송한 optimistic 라인을 서버 id 로 reconcile (index 비의존 — _localId 로 탐색).
+   * 에코가 응답보다 먼저 도착해 이미 append 됐으면 optimistic 중복 라인을 제거한다.
+   */
+  private _reconcileSentLine(localId: string, serverId: string | undefined, patch: Partial<ChatLine>) {
+    const next = reconcileSentLine(this.lines as any, this._seenMessageIds, localId, serverId, patch as any)
+    this._seenMessageIds = next.seen
+    this.lines = next.lines as ChatLine[]
+  }
+
+  private async _loadParticipants() {
+    if (!this.sessionId) return
+    try {
+      const result = await client.query({
+        query: CHAT_PARTICIPANTS_QUERY,
+        variables: { sessionId: this.sessionId },
+        fetchPolicy: 'network-only'
+      })
+      this.participants = result.data?.chatSessionParticipants ?? []
+    } catch {
+      /* roster 로드 실패는 채팅 본 기능 무영향 — 조용히 무시 */
+    }
+  }
+
+  private async _touchPresence() {
+    if (!this.sessionId) return
+    try {
+      await client.mutate({ mutation: TOUCH_PRESENCE_MUTATION, variables: { sessionId: this.sessionId } })
+    } catch {
+      /* heartbeat 실패 무시 */
+    }
+  }
+
+  /** lastSeenAt 이 TTL 이내면 online. (_presenceTick 의존으로 주기 재평가.) */
+  private _isOnline(lastSeenAt?: string): boolean {
+    void this._presenceTick
+    if (!lastSeenAt) return false
+    const t = new Date(lastSeenAt).getTime()
+    if (!Number.isFinite(t)) return false
+    const age = Date.now() - t
+    return age >= 0 ? age <= PRESENCE_TTL_MS : true
+  }
+
+  private async loadHistory() {
+    if (!this.sessionId) return
+    try {
+      const result = await client.query({
+        query: CHAT_MESSAGES_QUERY,
+        variables: { sessionId: this.sessionId, limit: 200, offset: 0 },
+        fetchPolicy: 'network-only'
+      })
+      const msgs = result.data?.chatMessages ?? []
+      this.lines = msgs.map((m: any) => this._msgToLine(m))
+      // 로드된 메시지 id 를 seen 에 등록 — 이후 방송 에코 dedup 기준.
+      this._seenMessageIds = new Set<string>(msgs.map((m: any) => m.id).filter(Boolean))
+    } catch (e: any) {
+      this.errorMessage = `${i18next.t('board-ai.text.failed-to-load-history')}: ${e.message ?? e}`
+    }
+  }
+
+  render() {
+    const hasMessages = this.lines.length > 0
+    return html`
+      ${this.toastMessage
+        ? html`<div class="toast show">${this.toastMessage}</div>`
+        : nothing}
+      ${this.renderSessionTabs()}
+      ${this.renderRoster()}
+      <div class="messages" @click=${this.onBubbleClick}>
+        ${!hasMessages ? this.renderEmpty() : nothing}
+        ${(() => {
+          const myId = this._myUserId
+          return this.lines.map((line, idx) => {
+          const prev = this.lines[idx - 1]
+          const showLabel = line.role === 'assistant' && (!prev || prev.role !== 'assistant')
+          // 그룹챗: 다른 참여자의 user 메시지는 좌측 + 보낸이 이름 표시(연속 동일 발신자는 1회만).
+          const isOther = line.role === 'user' && !!line.senderId && line.senderId !== myId
+          const prevSameSender = !!prev && prev.role === 'user' && prev.senderId === line.senderId
+          const showSenderLabel = isOther && !prevSameSender
+          const content = (line.content ?? '').trim()
+          const isMarkdown = line.role !== 'system' && content.length > 0
+          const showActions = line.role !== 'system' && !line.pending && content.length > 0
+          return html`
+            ${showLabel
+              ? html`<div class="msg-label">${i18next.t('board-ai.label.ai')}</div>`
+              : showSenderLabel
+                ? html`<div class="msg-label sender">${line.senderName || i18next.t('board-ai.label.participant')}</div>`
+                : nothing}
+            <div class="msg-wrap ${line.role} ${isOther ? 'other' : ''}">
+              <div class="msg ${line.role} ${isOther ? 'other' : ''} ${line.pending ? 'pending' : ''}">
+                ${line.pending
+                  ? html`<span class="typing-dots"><span></span><span></span><span></span></span>`
+                  : isMarkdown
+                    ? html`<div class="md-body">${unsafeHTML(renderMarkdown(content))}</div>`
+                    : content}
+                ${line.patchId
+                  ? html`
+                      <div class="summary ${this.revertedPatchIds.has(line.patchId) ? 'reverted' : ''}">
+                        <md-icon>check_circle</md-icon>
+                        <span class="summary-text">
+                          ${this.revertedPatchIds.has(line.patchId)
+                            ? i18next.t('board-ai.text.reverted')
+                            : i18next.t('board-ai.text.applied-changes')}
+                        </span>
+                        <button
+                          class="revert-btn"
+                          ?disabled=${this.revertedPatchIds.has(line.patchId)}
+                          @click=${() => line.patchId && this.onRevertClick(line.patchId)}>
+                          ${i18next.t('board-ai.button.revert')}
+                        </button>
+                      </div>
+                    `
+                  : nothing}
+                ${line.followUp
+                  ? html`<div class="followup">${unsafeHTML(renderMarkdown(line.followUp.trim()))}</div>`
+                  : nothing}
+                ${line.toolUsages && line.toolUsages.length > 0
+                  ? this.renderToolUsages(idx, line)
+                  : nothing}
+              </div>
+              ${showActions ? this.renderMessageActions(idx, line, content) : nothing}
+            </div>
+          `
+          })
+        })()}
+      </div>
+      ${this.errorMessage
+        ? html`
+            <div class="error">
+              <span class="error-text">${this.errorMessage}</span>
+              ${this.lastFailedInput
+                ? html`
+                    <button class="retry-btn" @click=${this.retryLastSend}>
+                      ${i18next.t('board-ai.button.retry')}
+                    </button>
+                  `
+                : nothing}
+            </div>
+          `
+        : nothing}
+      <div class="composer ${hasMessages ? '' : 'no-actions'}">
+        ${hasMessages
+          ? html`
+              <div class="actions-row">
+                <button
+                  class="action"
+                  @click=${() => (this.examplesOpen = !this.examplesOpen)}
+                  title=${i18next.t('board-ai.text.show-examples-tooltip')}>
+                  <md-icon>${this.examplesOpen ? 'close' : 'lightbulb'}</md-icon>
+                  ${this.examplesOpen
+                    ? i18next.t('board-ai.button.close')
+                    : i18next.t('board-ai.button.examples')}
+                </button>
+              </div>
+              ${this.examplesOpen ? this.renderInlineExamples() : nothing}
+            `
+          : nothing}
+        <div class="input-row">
+          <div class="textarea-wrap">
+            <textarea
+              .value=${this.input}
+              @input=${(e: Event) => this.onTextareaInput(e)}
+              @keydown=${(e: KeyboardEvent) => this.onKeyDown(e)}
+              @blur=${() => {
+                // 포커스를 popup item 으로 옮기는 click 보다 blur 가 먼저 — popup item 의
+                // mousedown.preventDefault() 가 처리하지만 안전망으로 짧은 지연 후 닫기.
+                setTimeout(() => this.closeMentionPopup(), 150)
+              }}
+              ?disabled=${this.busy}
+              rows="1"
+              placeholder=${this.placeholder ?? i18next.t('board-ai.text.input-placeholder')}></textarea>
+            ${this.mentionOpen
+              ? html`
+                  <ox-mention-popup
+                    class="mention-popup"
+                    .results=${this.mentionResults}
+                    .activeIndex=${this.mentionActiveIndex}
+                    .overflow=${this.mentionOverflow}
+                    @mention-active-change=${(e: CustomEvent) => {
+                      // 마우스 hover — keyboard nav 와 동일하게 select + centerTo
+                      const idx = e.detail?.index
+                      if (typeof idx === 'number' && idx >= 0 && idx < this.mentionResults.length) {
+                        this.mentionActiveIndex = idx
+                        this.previewActiveCandidate()
+                      }
+                    }}
+                    @mention-select=${(e: CustomEvent) =>
+                      this.applyMention(e.detail.candidate)}></ox-mention-popup>
+                `
+              : nothing}
+          </div>
+          <button
+            ?disabled=${this.busy || !this.input.trim()}
+            @click=${this.send}
+            title=${i18next.t('board-ai.text.send-tooltip')}>
+            ${this.busy
+              ? html`<span class="spinner"></span>`
+              : html`<md-icon>arrow_upward</md-icon>`}
+          </button>
+        </div>
+      </div>
+    `
+  }
+
+  private onKeyDown(e: KeyboardEvent) {
+    // Mention popup 활성 시 — 화살표/Enter/Tab/Esc 가로채서 popup 네비게이션
+    if (this.mentionOpen) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault()
+        if (this.mentionResults.length > 0) {
+          this.mentionActiveIndex =
+            (this.mentionActiveIndex + 1) % this.mentionResults.length
+          this.previewActiveCandidate()
+        }
+        return
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault()
+        if (this.mentionResults.length > 0) {
+          this.mentionActiveIndex =
+            (this.mentionActiveIndex - 1 + this.mentionResults.length) %
+            this.mentionResults.length
+          this.previewActiveCandidate()
+        }
+        return
+      }
+      if (e.key === 'Enter' || e.key === 'Tab') {
+        if (this.mentionResults.length > 0) {
+          e.preventDefault()
+          this.applyMention(this.mentionResults[this.mentionActiveIndex].candidate)
+          return
+        }
+        // 매칭 0개면 popup 닫고 일반 동작 fall through
+        this.closeMentionPopup()
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        this.closeMentionPopup()
+        return
+      }
+    }
+    if (e.key === 'Enter' && !e.shiftKey && !this.busy) {
+      e.preventDefault()
+      this.send()
+    }
+  }
+
+  /** input 이벤트 — value 즉시 반영 + popup 갱신은 150ms 디바운스 (F-Finder 와 동일).
+   *  big board 에서 매 keystroke filter 비용 절감 + 한국어 IME 조합 중 깜빡임 완화. */
+  private onTextareaInput(e: Event) {
+    const ta = e.target as HTMLTextAreaElement
+    this.input = ta.value
+    if (this.inputDebounceTimer) clearTimeout(this.inputDebounceTimer)
+    this.inputDebounceTimer = setTimeout(() => {
+      this.refreshMentionPopup(ta)
+    }, 150)
+  }
+
+  /** 현재 cursor 위치를 보고 mention popup 활성/비활성 + 후보 갱신.
+   *  `#` (컴포넌트) / `@` (카탈로그) / `/` (slash 템플릿) 한 번에 하나만 활성. */
+  private refreshMentionPopup(ta: HTMLTextAreaElement) {
+    const cursor = ta.selectionStart ?? ta.value.length
+
+    const triggers: Array<'#' | '@' | '/'> = ['#', '@', '/']
+    let chosen: { hashPos: number; query: string; trigger: '#' | '@' | '/' } | null =
+      null
+    for (const t of triggers) {
+      const ctx = extractMentionContext(ta.value, cursor, t)
+      if (!ctx) continue
+      if (!chosen || ctx.hashPos > chosen.hashPos) {
+        chosen = { ...ctx, trigger: t }
+      }
+    }
+
+    if (!chosen) {
+      if (this.mentionOpen) this.closeMentionPopup()
+      return
+    }
+
+    const wasOpen = this.mentionOpen
+    const cap = 50
+    let results: FilterResult[]
+    if (chosen.trigger === '#' && this.searchProvider && chosen.query) {
+      // 호스트의 SceneSearchEngine 위임 — F-Finder 와 동일 검색 룰. cap 만 chat 측에서 적용.
+      results = this.searchProvider(chosen.query).slice(0, cap)
+    } else if (chosen.trigger === '@') {
+      // `@` = 도메인 사용자 멘션. host 가 userProvider set 했으면 query → users 비동기 fetch.
+      // userProvider 미설정 / 결과 없음 → 빈 popup (멀티유저 미사용 환경).
+      // async 라 즉시 반환은 빈 결과; await 후 다시 set 하는 패턴.
+      results = this.cachedUserCandidates
+        ? filterMentionCandidates(this.cachedUserCandidates, chosen.query, cap)
+        : []
+      // 비동기 갱신 — 결과 도착하면 popup 다시 갱신
+      this.refreshUserCandidatesAsync(chosen.query, chosen.hashPos)
+    } else {
+      let all: MentionCandidate[]
+      if (chosen.trigger === '#') {
+        // 빈 query 의 # 또는 searchProvider 미설정 — 로컬 enumeration 으로 전체 후보 표시
+        const liveBoard = this.boardProvider ? this.boardProvider() : this.currentBoard
+        all = buildMentionCandidates(liveBoard?.components ?? [])
+      } else {
+        // `/` = 카탈로그 + slash 템플릿 통합 (Notion `/` 패턴). 둘 다 "삽입 가능 항목".
+        all = [...this.cachedCatalogCandidates, ...this.cachedSlashCandidates]
+      }
+      results = filterMentionCandidates(all, chosen.query, cap)
+    }
+    // overflow 계산 — 전체 매칭 중 cap 으로 잘려나간 수 (popup 'N more' 표기)
+    // (cap 잘라서 반환하므로, 전체 카운트는 자유 검색 시 알기 어려움.
+    //  엄격한 overflow 추적 대신 results.length === cap 이면 추정 표시)
+    const overflow = results.length === cap ? 0 : 0
+    this.mentionResults = results
+    this.mentionOverflow = overflow
+    this.mentionActiveIndex = 0
+    this.mentionHashPos = chosen.hashPos
+    this.mentionTrigger = chosen.trigger
+    this.mentionOpen = true
+
+    // 첫 open 시 — 사용자 selection 스냅샷 (취소 시 원복용)
+    if (!wasOpen && chosen.trigger === '#') {
+      this.originalSelectedRefids = (this.selectedRefids ?? []).slice()
+    }
+    // 매칭된 후보 outline 만 갱신 — 카메라/선택 변경은 commit (Enter/click) 시점에만.
+    this.highlightMatchedCandidates()
+  }
+
+  /** `@` query 에 대한 userProvider 비동기 호출 — 응답 도착 시 popup 결과 갱신.
+   *  race 방지: token 으로 최신 호출 식별 (늦게 도착한 응답 무시). */
+  private async refreshUserCandidatesAsync(query: string, hashPos: number) {
+    if (!this.userProvider) return
+    const token = ++this.userFetchToken
+    try {
+      const users = await Promise.resolve(this.userProvider(query))
+      if (token !== this.userFetchToken) return // 더 최신 호출이 있음
+      // popup 이 닫혔거나 trigger / hashPos 가 바뀌면 무시
+      if (!this.mentionOpen || this.mentionTrigger !== '@' || this.mentionHashPos !== hashPos) {
+        return
+      }
+      this.cachedUserCandidates = buildUserCandidates(users)
+      this.mentionResults = filterMentionCandidates(
+        this.cachedUserCandidates,
+        query,
+        50
+      )
+      this.mentionActiveIndex = 0
+    } catch (e) {
+      // 조용히 무시 — 사용자 입력 흐름 방해 X. 디버그 시 console 확인 가능.
+      console.warn('[board-ai-chat] userProvider failed:', e)
+    }
+  }
+
+  /** popup 후보들 outline highlight — 카메라/선택 변경 없음.
+   *  타이핑 직후 (refreshMentionPopup) 에서 호출 — 사용자가 active 를 명시 이동하지
+   *  않은 상태이므로 임의의 첫 항목을 선택하거나 카메라 이동시키지 않음.
+   *  # trigger 일 때만 활성. */
+  private highlightMatchedCandidates() {
+    if (this.mentionTrigger !== '#') return
+    const allRefids: number[] = []
+    for (const r of this.mentionResults) {
+      if (typeof r.candidate.refid === 'number') allRefids.push(r.candidate.refid)
+    }
+    this.dispatchActions([{ action: 'highlightComponents', refids: allRefids }])
+  }
+
+  /** active 후보 live preview — 사용자가 ↑↓ 키 / popup 마우스 hover 로 명시적으로
+   *  active 를 옮긴 시점에 호출. F-Finder 동급 3-action: highlight + select + centerTo.
+   *  centerTo 는 150ms 디바운스 — 빠른 nav 시 카메라 애니메이션 race 방지.
+   *  # trigger 일 때만 활성. */
+  private previewActiveCandidate() {
+    if (this.mentionTrigger !== '#') return
+    const allRefids: number[] = []
+    for (const r of this.mentionResults) {
+      if (typeof r.candidate.refid === 'number') allRefids.push(r.candidate.refid)
+    }
+    const active = this.mentionResults[this.mentionActiveIndex]
+    const activeRefid =
+      active && typeof active.candidate.refid === 'number'
+        ? active.candidate.refid
+        : undefined
+
+    const actions: any[] = [{ action: 'highlightComponents', refids: allRefids }]
+    if (typeof activeRefid === 'number') {
+      actions.push({ action: 'selectComponents', refids: [activeRefid] })
+    }
+    this.dispatchActions(actions)
+
+    if (this.centerDebounceTimer) clearTimeout(this.centerDebounceTimer)
+    if (typeof activeRefid === 'number') {
+      this.centerDebounceTimer = setTimeout(() => {
+        this.dispatchActions([
+          { action: 'centerToComponent', refid: activeRefid, animated: true }
+        ])
+      }, 150)
+    }
+  }
+
+  private dispatchActions(actions: any[]) {
+    this.dispatchEvent(
+      new CustomEvent('board-action-execute', {
+        detail: { actions, sessionId: this.sessionId },
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  /** 메시지 버블의 `<span class="mention">#token</span>` 클릭 — 컴포넌트로 select + centerTo.
+   *  resolve 룰은 pure helper `resolveMentionToken` 에 위임 (단위 테스트 가능). */
+  private onBubbleClick = (e: Event) => {
+    const target = e.target as HTMLElement | null
+    if (!target?.classList?.contains('mention')) return
+    e.preventDefault()
+    const text = (target.textContent || '').trim()
+    const token = text.startsWith('#') ? text.slice(1) : text
+    if (!token) return
+
+    const refid = resolveMentionToken(token, {
+      persistedRefid: target.getAttribute('data-refid'),
+      searchProvider: this.searchProvider,
+      board: this.boardProvider ? this.boardProvider() : this.currentBoard
+    })
+
+    if (typeof refid === 'number') {
+      this.dispatchActions([
+        { action: 'selectComponents', refids: [refid] },
+        { action: 'centerToComponent', refid, animated: true }
+      ])
+    } else {
+      this.showToast(
+        i18next.t('board-ai.text.mention-not-found', {
+          token,
+          defaultValue: `#${token} 을(를) 찾을 수 없습니다`
+        })
+      )
+    }
+  }
+
+  /** popup 닫기. commit=false (취소) 면 # 의 경우:
+   *   - highlight 정리 (highlightComponents [])
+   *   - 원래 selection 으로 원복
+   *  commit=true (확정) 면 현재 preview 상태 유지 + highlight 만 정리. */
+  private closeMentionPopup(commit = false) {
+    if (!this.mentionOpen) return
+    const wasHashTrigger = this.mentionTrigger === '#'
+    this.mentionOpen = false
+    this.mentionResults = []
+    this.mentionOverflow = 0
+    this.mentionActiveIndex = 0
+    this.mentionHashPos = -1
+
+    if (wasHashTrigger) {
+      // popup 닫힘 → highlight 항상 정리 (확정/취소 모두)
+      const cleanupActions: any[] = [{ action: 'highlightComponents', refids: [] }]
+      if (!commit) {
+        // 취소 — 원래 selection 으로 원복
+        cleanupActions.push({
+          action: 'selectComponents',
+          refids: this.originalSelectedRefids
+        })
+      }
+      this.dispatchActions(cleanupActions)
+    }
+  }
+
+  /** 후보 1개를 textarea 에 적용 + popup 닫고 cursor 재배치. */
+  private applyMention(candidate: MentionCandidate) {
+    const ta = this.renderRoot.querySelector('textarea') as HTMLTextAreaElement | null
+    if (!ta || this.mentionHashPos < 0) {
+      this.closeMentionPopup()
+      return
+    }
+    const cursor = ta.selectionStart ?? ta.value.length
+    const r = applyMentionSelection(
+      ta.value,
+      cursor,
+      this.mentionHashPos,
+      candidate,
+      this.mentionTrigger
+    )
+    this.input = r.text
+    // # trigger + refid 보유 후보 — commit 시점에만 select + centerTo (사용자 의도 확정 순간).
+    // 동시에 picks 로 기록: textarea 에는 깨끗한 #label, server 에는 정확한 refid 전달.
+    if (
+      this.mentionTrigger === '#' &&
+      typeof candidate.refid === 'number'
+    ) {
+      this.pickedMentions.set(candidate.label, candidate.refid)
+      this.dispatchActions([
+        { action: 'selectComponents', refids: [candidate.refid] },
+        { action: 'centerToComponent', refid: candidate.refid, animated: true }
+      ])
+    } else if (
+      this.mentionTrigger === '@' &&
+      typeof candidate.userId === 'string' &&
+      candidate.userId.length > 0
+    ) {
+      // @user 멘션 — userId 박제. 보드 액션은 발사 안 함 (사용자는 컴포넌트 아님).
+      this.pickedUserMentions.set(candidate.label, candidate.userId)
+    }
+    this.closeMentionPopup(true) // commit — preview selection 유지, highlight 만 정리
+    requestAnimationFrame(() => {
+      const ta2 = this.renderRoot.querySelector('textarea') as HTMLTextAreaElement | null
+      ta2?.focus()
+      ta2?.setSelectionRange(r.cursorPos, r.cursorPos)
+    })
+  }
+
+  // ── Empty state with onboarding guide ──────────────────────────
+
+  /** 예시 그룹 — i18n 키. localize mixin 이 언어 변경 시 자동 재렌더. */
+  private static readonly EXAMPLE_GROUPS: Array<{
+    labelKey: string
+    itemKeys: string[]
+  }> = [
+    {
+      labelKey: 'board-ai.label.create',
+      itemKeys: [
+        'board-ai.example.create-monitoring-dashboard',
+        'board-ai.example.create-welcome-screen'
+      ]
+    },
+    {
+      labelKey: 'board-ai.label.edit',
+      itemKeys: [
+        'board-ai.example.edit-align-distribute',
+        'board-ai.example.edit-resize-board'
+      ]
+    },
+    {
+      labelKey: 'board-ai.label.style',
+      itemKeys: [
+        'board-ai.example.style-dark-mode',
+        'board-ai.example.style-rounded-shadow'
+      ]
+    }
+  ]
+
+  /** 보드의 세션 탭 — 다중 세션 활성화 시 패널 상단. host 가 sessions 비워두면 표시 X.
+   *  레이블은 session.name 우선, 없으면 fallback "세션 N". */
+  private renderSessionTabs() {
+    if (!this.sessions || this.sessions.length === 0) return nothing
+    return html`
+      <div class="session-tabs" role="tablist">
+        ${this.sessions.map((s, i) => {
+          const isActive = s.id === this.sessionId
+          const fallback = i18next.t('board-ai.text.session-tab-label', {
+            n: i + 1,
+            defaultValue: `세션 ${i + 1}`
+          })
+          const label = s.name?.trim() || fallback
+          const tooltip = s.createdAt
+            ? `${label} · ${new Date(s.createdAt).toLocaleString()}`
+            : label
+          return html`
+            <button
+              class="session-tab ${isActive ? 'active' : ''}"
+              role="tab"
+              aria-selected=${isActive ? 'true' : 'false'}
+              title=${tooltip}
+              @click=${() => this._onSessionTabClick(s.id)}>
+              ${label}
+            </button>
+          `
+        })}
+        <button
+          class="session-tab-new"
+          title=${i18next.t('board-ai.button.new-chat', {
+            defaultValue: '새 대화'
+          })}
+          @click=${this._onSessionCreateClick}>
+          <md-icon>add</md-icon>
+          <span>${i18next.t('board-ai.button.new-chat', { defaultValue: '새 대화' })}</span>
+        </button>
+      </div>
+    `
+  }
+
+  /** C4 roster — 세션 참여자 + online 표시. 참여자 2명 미만이면 숨김(혼자면 의미 없음). */
+  private renderRoster() {
+    if (!this.sessionId || this.participants.length < 2) return nothing
+    const online = this.participants.filter(p => this._isOnline(p.lastSeenAt)).length
+    return html`
+      <div class="roster" role="group" aria-label="participants">
+        <span class="roster-count" title=${`${online} online / ${this.participants.length} total`}>
+          <md-icon>group</md-icon>${online}/${this.participants.length}
+        </span>
+        ${this.participants.map(p => {
+          const name = p.user?.name || p.user?.id || '?'
+          const on = this._isOnline(p.lastSeenAt)
+          return html`<span
+            class="roster-chip ${on ? 'online' : 'offline'}"
+            title=${`${name} · ${p.role}${on ? ' · online' : ''}`}>
+            <span class="roster-dot"></span>${initials(name)}
+          </span>`
+        })}
+      </div>
+    `
+  }
+
+  private _onSessionTabClick(sessionId: string) {
+    if (sessionId === this.sessionId) return
+    this.dispatchEvent(
+      new CustomEvent('session-switch', {
+        detail: { sessionId },
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  private _onSessionCreateClick = () => {
+    this.dispatchEvent(
+      new CustomEvent('session-create', {
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  private renderEmpty() {
+    return html`
+      <div class="empty">
+        <div class="header">
+          <md-icon class="icon">auto_awesome</md-icon>
+          <div class="title">${i18next.t('board-ai.text.empty-title')}</div>
+          <div class="subtitle">${i18next.t('board-ai.text.empty-subtitle')}</div>
+        </div>
+
+        <div class="trigger-row">
+          <div class="trigger-row-label">${i18next.t('board-ai.text.triggers-heading')}</div>
+          <div class="trigger-chips">
+            <button
+              class="trigger-chip"
+              title=${i18next.t('board-ai.text.trigger-component-tooltip')}
+              @click=${() => this.insertTrigger('#')}>
+              <span class="trigger-char">#</span>
+              <span class="trigger-desc">${i18next.t('board-ai.label.trigger-component')}</span>
+            </button>
+            <button
+              class="trigger-chip"
+              title=${i18next.t('board-ai.text.trigger-user-tooltip')}
+              @click=${() => this.insertTrigger('@')}>
+              <span class="trigger-char">@</span>
+              <span class="trigger-desc">${i18next.t('board-ai.label.trigger-user')}</span>
+            </button>
+            <button
+              class="trigger-chip"
+              title=${i18next.t('board-ai.text.trigger-insert-tooltip')}
+              @click=${() => this.insertTrigger('/')}>
+              <span class="trigger-char">/</span>
+              <span class="trigger-desc">${i18next.t('board-ai.label.trigger-insert')}</span>
+            </button>
+          </div>
+        </div>
+
+        ${OxBoardAIChat.EXAMPLE_GROUPS.map(
+          group => html`
+            <div class="group">
+              <div class="group-label">${i18next.t(group.labelKey)}</div>
+              ${group.itemKeys.map(key => {
+                const text = i18next.t(key)
+                return html`
+                  <button class="example" @click=${() => this.useExample(text)}>
+                    ${text}<span class="arrow">→</span>
+                  </button>
+                `
+              })}
+            </div>
+          `
+        )}
+
+        <div class="footer">
+          <span class="badge">${i18next.t('board-ai.label.korean-supported')}</span>
+          <span class="badge">${i18next.t('board-ai.label.multi-command')}</span>
+          <span class="badge">${i18next.t('board-ai.label.review-able')}</span>
+          <br />
+          ${i18next.t('board-ai.text.empty-footer-notice')}
+        </div>
+      </div>
+    `
+  }
+
+  /** trigger chip 클릭 — textarea 에 trigger 문자 삽입 + focus + popup 자동 활성. */
+  private insertTrigger(trigger: '#' | '@' | '/') {
+    // 입력 끝에 공백이 없으면 공백 추가 후 trigger — 자연스러운 위치
+    const needsSpace = this.input.length > 0 && !/\s$/.test(this.input)
+    this.input = this.input + (needsSpace ? ' ' : '') + trigger
+    requestAnimationFrame(() => {
+      const ta = this.renderRoot.querySelector('textarea') as HTMLTextAreaElement | null
+      if (!ta) return
+      ta.focus()
+      ta.setSelectionRange(ta.value.length, ta.value.length)
+      // popup refresh — onTextareaInput 이 디바운스 후 호출되지만 직접 호출로 즉각 반영
+      this.refreshMentionPopup(ta)
+    })
+  }
+
+  /** 예시 클릭 — 입력창에 채우고 포커스 (사용자가 수정 후 전송 가능) */
+  private useExample(text: string) {
+    this.input = text
+    this.examplesOpen = false
+    requestAnimationFrame(() => {
+      const ta = this.renderRoot.querySelector('textarea') as HTMLTextAreaElement | null
+      ta?.focus()
+      ta?.setSelectionRange(text.length, text.length)
+    })
+  }
+
+  // ── Mini actions ───────────────────────────────────────────────
+
+  private renderInlineExamples() {
+    return html`
+      <div class="inline-examples">
+        ${OxBoardAIChat.EXAMPLE_GROUPS.map(
+          group => html`
+            <div class="ex-row">
+              <span class="ex-label">${i18next.t(group.labelKey)}</span>
+              ${group.itemKeys.map(key => {
+                const t = i18next.t(key)
+                return html`<button class="ex" @click=${() => this.useExample(t)}>${t}</button>`
+              })}
+            </div>
+          `
+        )}
+      </div>
+    `
+  }
+
+  // ── Retry (에러 발생 시) ───────────────────────────────────────
+
+  private async retryLastSend() {
+    if (!this.lastFailedInput) return
+    this.input = this.lastFailedInput
+    this.errorMessage = undefined
+    this.lastFailedInput = undefined
+    await this.send()
+  }
+
+  // ── Per-message hover action row ───────────────────────────────
+
+  /**
+   * 메시지별 hover 액션 — 텍스트 chip 으로 명확.
+   *   user      : 액션 row 자체 X (자기 메시지에 시각 노이즈 X — 편집은 input 위 "새 대화" 흐름 또는 마우스 더블클릭)
+   *   assistant : 복사 + 재생성 + (patch 적용된 경우만) 되돌리기
+   *   system    : 없음
+   */
+  private renderMessageActions(idx: number, line: ChatLine, content: string) {
+    if (line.role !== 'assistant') return nothing
+
+    const isCopied = this.copiedIdx === idx
+    // revert 는 인라인 patch chip (메시지 안) 한 곳에만 — hover 액션에서 제외 (중복 방지).
+    return html`
+      <div class="msg-actions">
+        <button
+          class="msg-action ${isCopied ? 'confirmed' : ''}"
+          title=${isCopied
+            ? i18next.t('board-ai.text.copied')
+            : i18next.t('board-ai.button.copy')}
+          @click=${() => this.copyMessage(idx, content)}>
+          <md-icon>${isCopied ? 'check' : 'content_copy'}</md-icon>
+        </button>
+        <button
+          class="msg-action"
+          ?disabled=${this.busy}
+          title=${i18next.t('board-ai.button.regenerate')}
+          @click=${() => this.regenerateAssistant(idx)}>
+          <md-icon>refresh</md-icon>
+        </button>
+      </div>
+    `
+  }
+
+  /**
+   * "AI 가 이런 도구를 사용했습니다" fold-able 박스.
+   *
+   * - 기본 닫힘 (toolUsagesOpen=false). 헤더 클릭 시 toggle.
+   * - 펼쳤을 때 도구 별로 name + arguments + result + read/write 색상 배지.
+   * - 디버그 / 신뢰도 향상용 — 사용자가 "왜 이렇게 답했지" 의문 가질 때 즉시 검증.
+   */
+  private renderToolUsages(idx: number, line: ChatLine) {
+    const usages = line.toolUsages
+    if (!usages || usages.length === 0) return nothing
+    const open = !!line.toolUsagesOpen
+    const readCount = usages.filter(u => u.kind === 'read').length
+    const writeCount = usages.filter(u => u.kind === 'write').length
+    const toolsLabel = i18next.t('board-ai.text.tools-used', { defaultValue: '도구 사용' })
+    return html`
+      <div class="tool-usages ${open ? 'open' : ''}">
+        <button
+          class="tool-usages-header"
+          aria-expanded=${open}
+          @click=${() => this.toggleToolUsages(idx)}>
+          <md-icon class="tool-usages-icon">${open ? 'expand_less' : 'build'}</md-icon>
+          <span class="tool-usages-summary">
+            <strong>${usages.length}</strong> ${toolsLabel}
+            <span class="tool-usages-counts">· read ${readCount} · write ${writeCount}</span>
+          </span>
+          <md-icon class="tool-usages-chevron">${open ? 'expand_less' : 'expand_more'}</md-icon>
+        </button>
+        ${open
+          ? html`
+              <ol class="tool-usages-list">
+                ${usages.map(
+                  (u, i) => html`
+                    <li class="tool-usage-item kind-${u.kind}">
+                      <div class="tool-usage-head">
+                        <span class="tool-usage-step">${i + 1}.</span>
+                        <span class="tool-usage-name">${u.name}</span>
+                        <span class="tool-usage-kind kind-${u.kind}">${u.kind}</span>
+                      </div>
+                      ${u.arguments && Object.keys(u.arguments).length > 0
+                        ? html`<pre class="tool-usage-args">${this.formatJson(u.arguments)}</pre>`
+                        : nothing}
+                      <pre class="tool-usage-result">${this.formatJson(u.result)}</pre>
+                    </li>
+                  `
+                )}
+              </ol>
+            `
+          : nothing}
+      </div>
+    `
+  }
+
+  private toggleToolUsages(idx: number) {
+    const next = [...this.lines]
+    const line = next[idx]
+    if (!line) return
+    next[idx] = { ...line, toolUsagesOpen: !line.toolUsagesOpen }
+    this.lines = next
+  }
+
+  private formatJson(value: any): string {
+    try {
+      return JSON.stringify(value, null, 2)
+    } catch {
+      return String(value)
+    }
+  }
+
+  // ── Per-message actions ────────────────────────────────────────
+
+  private async copyMessage(idx: number, content: string) {
+    try {
+      // 클립보드에는 marker 제거된 깨끗한 텍스트
+      await navigator.clipboard.writeText(stripMentionRefids(content))
+      this.copiedIdx = idx
+      this.showToast(i18next.t('board-ai.text.copied'))
+      setTimeout(() => {
+        if (this.copiedIdx === idx) this.copiedIdx = undefined
+      }, 1500)
+    } catch {
+      // clipboard 권한 없거나 비-secure context — 조용히 무시
+    }
+  }
+
+  private showToast(message: string) {
+    this.toastMessage = message
+    setTimeout(() => {
+      if (this.toastMessage === message) this.toastMessage = undefined
+    }, 1500)
+  }
+
+  /**
+   * 사용자 메시지 편집 — 해당 메시지 + 이후 모두 UI 에서 제거하고 입력창에 채움.
+   * 서버 영속 history 는 그대로 유지 (다음 send 시 새 메시지로 추가).
+   */
+  private editUserMessage(idx: number, content: string) {
+    // textarea 에는 marker 제거된 깨끗한 텍스트 — 사용자가 raw `{refid:N}` 보지 않게.
+    // 다시 send 시 popup pickedMentions 기반으로 marker 재주입.
+    const cleaned = stripMentionRefids(content)
+    this.lines = this.lines.slice(0, idx)
+    this.input = cleaned
+    requestAnimationFrame(() => {
+      const ta = this.renderRoot.querySelector('textarea') as HTMLTextAreaElement | null
+      ta?.focus()
+      ta?.setSelectionRange(cleaned.length, cleaned.length)
+    })
+  }
+
+  /**
+   * AI 응답 재생성 — 해당 assistant 메시지 + 이후 제거하고, 직전 user 메시지를 다시 send.
+   */
+  private async regenerateAssistant(idx: number) {
+    if (this.busy) return
+    // 직전 user 메시지 찾기
+    let userIdx = idx - 1
+    while (userIdx >= 0 && this.lines[userIdx].role !== 'user') userIdx--
+    if (userIdx < 0) return
+    // textarea 에는 marker 제거된 깨끗한 본문. send() 가 본문을 다시 line 으로 push 하는데,
+    // pickedMentions 는 직전 send 에서 비워졌으므로 새 line 에는 marker 없음 — 클릭 시
+    // runtime fallback resolver 가 처리. (영속된 원본 user 메시지의 marker 는 그대로 유지)
+    const userContent = stripMentionRefids(this.lines[userIdx].content)
+    // assistant 메시지 + 이후 제거
+    this.lines = this.lines.slice(0, idx)
+    this.input = userContent
+    await this.send()
+  }
+
+  // ── Patch revert ───────────────────────────────────────────────
+
+  private onRevertClick(patchId: string) {
+    if (this.revertedPatchIds.has(patchId)) return
+    this.revertedPatchIds = new Set([...this.revertedPatchIds, patchId])
+    // 호스트 (board-modeller-page) 에게 revert 요청 — 호스트가 snapshot 복원 + 서버 mutation 호출
+    this.dispatchEvent(
+      new CustomEvent('board-edit-revert', {
+        detail: { patchId },
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  private async send() {
+    const text = this.input.trim()
+    if (!text || this.busy) return
+
+    // pickedMentions / pickedUserMentions 에서 현재 텍스트에 실제 #/@ token 으로
+    // 등장하는 것만 추출 — 지운 토큰 제외. inline 마커로 content 에 주입.
+    const mentions: Array<{ token: string; refid: number }> = []
+    for (const [token, refid] of this.pickedMentions.entries()) {
+      if (text.includes(`#${token}`)) mentions.push({ token, refid })
+    }
+    const userMentions: Array<{ token: string; userId: string }> = []
+    for (const [token, userId] of this.pickedUserMentions.entries()) {
+      if (text.includes(`@${token}`)) userMentions.push({ token, userId })
+    }
+    let enrichedContent = injectMentionRefids(text, mentions)
+    enrichedContent = injectMentionUserIds(enrichedContent, userMentions)
+
+    // optimistic 라인에 임시 핸들 — 방송 에코와의 reconcile 을 index 비의존으로.
+    const userLocalId = `local-${++this._localSeq}-u`
+    const asstLocalId = `local-${++this._localSeq}-a`
+
+    this.lines = [
+      ...this.lines,
+      { role: 'user', content: enrichedContent, _localId: userLocalId }
+    ]
+    this.input = ''
+    this.busy = true
+    this.errorMessage = undefined
+
+    // 가짜 pending 응답 표시 (UX 부드럽게)
+    this.lines = [...this.lines, { role: 'assistant', content: '', pending: true, _localId: asstLocalId }]
+
+    try {
+      // LLM 으로 보낼 history — user/assistant 만 (system 은 백엔드가 자동 합류).
+      // pending placeholder 와 system 은 제외 (index 비의존 — 방송 append 와 무관).
+      const history = this.lines
+        .filter(l => !l.pending && l._localId !== asstLocalId && l.role !== 'system')
+        .map(l => ({ role: l.role, content: l.content }))
+
+      // 라이브 보드 우선 — 호스트의 캔버스가 사용자 수작업 편집을 들고 있을 수 있음.
+      // boardProvider 가 있으면 send 시점에 그것을 pull, 없으면 정적 currentBoard.
+      const liveBoard = this.boardProvider ? this.boardProvider() : this.currentBoard
+
+      // mentions 는 위에서 이미 계산해 user line 에 thread — 그대로 mutation 입력으로 재사용.
+      const result = await client.mutate({
+        mutation: BOARD_AI_CHAT_MUTATION,
+        variables: {
+          input: buildChatMutationInput({
+            sessionId: this.sessionId,
+            history,
+            liveBoard,
+            scopes: this.scopes,
+            knownTypes: this.knownTypes,
+            categories: this.categories,
+            componentSchemas: this.componentSchemas,
+            selectedRefids: this.selectedRefids ?? [],
+            mentions
+          })
+        }
+      })
+
+      const out = result.data?.boardAIChat
+      if (!out) throw new Error(i18next.t('board-ai.text.empty-response'))
+
+      // 전송 성공 — picks 정리 (다음 메시지부터는 새 picks 만)
+      this.pickedMentions.clear()
+      this.pickedUserMentions.clear()
+
+      // optimistic 라인을 서버 id 로 reconcile (방송 에코와 중복 방지, index 비의존).
+      // 사용자 라인: enrich 된 본문 유지, id 만 부여. AI 라인: pending → 실제 응답.
+      this._reconcileSentLine(userLocalId, out.userMessageId, {})
+      this._reconcileSentLine(asstLocalId, out.assistantMessageId, {
+        role: 'assistant',
+        content: out.reply,
+        patchSummary: out.patch?.summary,
+        followUp: out.followUp || undefined,
+        patchId: out.patchId || undefined,
+        toolUsages: Array.isArray(out.toolUsages) ? out.toolUsages : undefined,
+        pending: false
+      })
+
+      // 호스트로 patch 이벤트 전파
+      if (out.patch) {
+        this.dispatchEvent(
+          new CustomEvent('board-edit-patch', {
+            detail: {
+              patch: out.patch,
+              summary: out.patch.summary,
+              confidence: out.patch.confidence,
+              patchId: out.patchId,
+              sessionId: out.sessionId
+            },
+            bubbles: true,
+            composed: true
+          })
+        )
+      }
+      // 호스트로 ephemeral scene 조작 actions 전파 (selection / view / mode)
+      if (Array.isArray(out.actions) && out.actions.length > 0) {
+        this.dispatchEvent(
+          new CustomEvent('board-action-execute', {
+            detail: { actions: out.actions, sessionId: out.sessionId },
+            bubbles: true,
+            composed: true
+          })
+        )
+      }
+      if (out.followUp) {
+        this.dispatchEvent(
+          new CustomEvent('chat-followup', {
+            detail: { question: out.followUp },
+            bubbles: true,
+            composed: true
+          })
+        )
+      }
+    } catch (e: any) {
+      // pending(AI) placeholder 만 제거 — 사용자 라인은 보존(재시도). index 비의존.
+      this.lines = this.lines.filter(l => l._localId !== asstLocalId)
+      this.errorMessage = e?.message ?? String(e)
+      this.lastFailedInput = text
+    } finally {
+      this.busy = false
+    }
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ox-board-ai-chat': OxBoardAIChat
+  }
+}