@things-factory/ai-assistant 10.1.6

package/client/components/mention-popup.ts

@@ -0,0 +1,238 @@
+/**
+ * <ox-mention-popup> — Mention 후보 리스트 popup overlay.
+ *
+ * board-ai-chat 의 textarea 위에 absolute 로 띄움. plain `<textarea>` + popup 분리 패턴
+ * (한국어 IME 함정 회피 — contenteditable 사용 안 함).
+ *
+ * 키보드 네비게이션은 호스트 (board-ai-chat) 가 textarea keydown 으로 처리하고
+ * activeIndex 만 동기화. 마우스 클릭은 popup 자체에서 처리.
+ *
+ * Pure helper (extractMentionContext / filterMentionCandidates 등) 는
+ * `mention-popup-helpers.ts` 에 분리 — 단위 테스트 가능.
+ */
+import { LitElement, css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import type { FilterResult, MentionCandidate } from './mention-popup-helpers.js'
+
+export type {
+  MentionCandidate,
+  FilterResult
+} from './mention-popup-helpers.js'
+export {
+  buildMentionCandidates,
+  buildCatalogCandidates,
+  buildSlashCandidates,
+  buildUserCandidates,
+  extractMentionContext,
+  filterMentionCandidates,
+  applyMentionSelection,
+  resolveMentionToken,
+  type CatalogEntry,
+  type SlashTemplate,
+  type ResolveMentionTokenOptions
+} from './mention-popup-helpers.js'
+
+/** match type 라벨 — things-scene SearchOverlay 의 MATCH_TYPE_LABELS 와 동일. */
+const MATCH_TYPE_LABEL: Record<string, string> = {
+  id: 'ID',
+  name: 'Name',
+  tag: 'Tag',
+  type: 'Type',
+  class: 'Class',
+  text: 'Text',
+  data: 'Data',
+  property: 'Prop',
+  description: 'Desc'
+}
+
+@customElement('ox-mention-popup')
+export class OxMentionPopup extends LitElement {
+  @property({ type: Array }) results: FilterResult[] = []
+  @property({ type: Number }) activeIndex = 0
+  /** filter cap 후 표시 안 된 추가 매칭 수 ("...and N more" 표기용) */
+  @property({ type: Number }) overflow = 0
+
+  static styles = css`
+    :host {
+      display: block;
+      position: absolute;
+      z-index: 1000;
+      background: var(--md-sys-color-surface, #ffffff);
+      border: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      border-radius: 6px;
+      box-shadow: 0 6px 18px rgba(0, 0, 0, 0.10);
+      max-height: 220px;
+      overflow-y: auto;
+      /* 폭은 호스트가 left/right 로 결정. */
+    }
+    .empty {
+      padding: 8px 10px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      font-size: 11px;
+    }
+    /* dense 한 단일 행 — scene Finder 톤. label / hint / type-chip inline. */
+    .item {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 8px;
+      cursor: pointer;
+      font-size: 11.5px;
+      line-height: 1.4;
+      color: var(--md-sys-color-on-surface, #0f172a);
+      border-bottom: 1px solid var(--md-sys-color-outline-variant, #f1f5f9);
+    }
+    .item:last-child {
+      border-bottom: 0;
+    }
+    .item:hover {
+      background: var(--md-sys-color-surface-container, #f8fafc);
+    }
+    .item.active {
+      background: var(--md-sys-color-primary-container, rgba(37, 99, 235, 0.10));
+    }
+    .match-badge {
+      flex-shrink: 0;
+      background: var(--md-sys-color-primary-container, rgba(37, 99, 235, 0.15));
+      color: var(--md-sys-color-on-primary-container, #1e40af);
+      padding: 0 5px;
+      border-radius: 3px;
+      font-size: 9px;
+      font-weight: 600;
+      letter-spacing: 0.04em;
+      min-width: 32px;
+      text-align: center;
+    }
+    /* badge 가 비어있을 때 (matchType=label) — 자리는 reserve 해서 모든 행 정렬 일치 */
+    .match-badge.invisible {
+      visibility: hidden;
+    }
+    .label {
+      flex: 1;
+      min-width: 0;
+      font-weight: 500;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      color: var(--md-sys-color-on-surface, #0f172a);
+    }
+    .hint {
+      font-size: 10px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      flex-shrink: 0;
+      white-space: nowrap;
+      max-width: 45%;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .type {
+      flex-shrink: 0;
+      background: var(--md-sys-color-surface-container, #f1f5f9);
+      padding: 0 5px;
+      border-radius: 3px;
+      font-size: 9.5px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      letter-spacing: 0.02em;
+    }
+    /* 상태 footer — 'N matches' 카운터 + cap 초과 안내 */
+    .status {
+      padding: 3px 8px;
+      font-size: 9.5px;
+      color: var(--md-sys-color-outline, #94a3b8);
+      border-top: 1px solid var(--md-sys-color-outline-variant, #e2e8f0);
+      background: var(--md-sys-color-surface-container-low, #fafbfc);
+      display: flex;
+      justify-content: space-between;
+      gap: 8px;
+    }
+    .more {
+      color: var(--md-sys-color-outline, #94a3b8);
+    }
+  `
+
+  render() {
+    if (this.results.length === 0) {
+      return html`<div class="empty">매칭 없음</div>`
+    }
+    const totalShown = this.results.length
+    const totalAll = totalShown + this.overflow
+    return html`
+      ${this.results.map((r, i) => {
+        // 행 layout:
+        //   [matchType-badge] [type-chip] [label] [secondary hint when 의미 있을 때]
+        // - label = 항상 사람-친화적 1차 식별 (component=id, user=name, catalog=name 등)
+        // - secondary hint = matchValue 가 label 과 다른 경우 (예: tag/text 매칭) 또는
+        //   user 의 email 같은 부가 정보. 없으면 생략.
+        const matchType = r.matchType
+        const badgeText = matchType ? MATCH_TYPE_LABEL[matchType] ?? '' : ''
+        const label = r.candidate.label
+        // matchValue 가 label 과 같으면 redundant 라 hint 안 함
+        const matchHint = r.matchValue && r.matchValue !== label ? r.matchValue : ''
+        // user 후보이고 hint 가 비어있으면 email 을 hint 로 (보조 식별)
+        const fallbackHint =
+          !matchHint && r.candidate.type === 'user' && r.candidate.email !== label
+            ? r.candidate.email ?? ''
+            : ''
+        const hint = matchHint || fallbackHint
+        return html`
+          <div
+            class="item ${i === this.activeIndex ? 'active' : ''}"
+            @mouseenter=${() => this._setActive(i)}
+            @mousedown=${(e: MouseEvent) => this._select(e, r.candidate)}>
+            <span class="match-badge ${badgeText ? '' : 'invisible'}"
+              >${badgeText || '·'}</span
+            >
+            <span class="type">${r.candidate.type}</span>
+            <span class="label">${label}</span>
+            ${hint ? html`<span class="hint">${hint}</span>` : ''}
+          </div>
+        `
+      })}
+      <div class="status">
+        <span>${totalShown} / ${totalAll} matches</span>
+        ${this.overflow > 0
+          ? html`<span class="more">+${this.overflow} more — narrow query</span>`
+          : ''}
+      </div>
+    `
+  }
+
+  private _select(e: MouseEvent, candidate: MentionCandidate) {
+    e.preventDefault() // textarea blur 방지
+    this.dispatchEvent(
+      new CustomEvent('mention-select', {
+        detail: { candidate },
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  /** 마우스 hover 로 active 이동 — host 가 받아 keyboard nav 와 동일하게 처리. */
+  private _setActive(index: number) {
+    if (index === this.activeIndex) return
+    this.dispatchEvent(
+      new CustomEvent('mention-active-change', {
+        detail: { index },
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  /** activeIndex 가 바뀌면 해당 항목을 view 로 스크롤 — popup 의 overflow-y:auto
+   *  영역에서 키보드 네비 시 active 가 가려지지 않도록. */
+  protected updated(changed: Map<string, unknown>) {
+    if (changed.has('activeIndex') || changed.has('results')) {
+      const items = this.renderRoot.querySelectorAll('.item')
+      const active = items[this.activeIndex] as HTMLElement | undefined
+      active?.scrollIntoView({ block: 'nearest' })
+    }
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ox-mention-popup': OxMentionPopup
+  }
+}

package/client/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@things-factory/ai-assistant` — 대화면.
+ *
+ * `<ox-board-ai-chat>` 은 **이름을 안 바꿨다.** 커스텀 엘리먼트 이름은 소비처 여덟 곳의 템플릿에
+ * 박혀 있고, 그것을 같은 커밋에서 함께 바꾸면 무엇이 깨졌는지 못 가린다. 이름은 별도로 옮긴다.
+ */
+export * from './components/board-ai-chat.js'
+export * from './components/chat-defaults.js'
+export * from './components/markdown.js'
+export * from './components/chat-echo-dedup.js'
+export * from './components/chat-input-builder.js'
+export * from './components/mention-popup.js'
+export * from './components/mention-popup-helpers.js'
+export * from './utils/board-edit-patch.js'

package/client/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig-base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "declaration": true,
+    "module": "esnext",
+    "outDir": "../dist-client",
+    "baseUrl": "./"
+  },
+  "include": ["./**/*"]
+}

package/client/utils/board-edit-patch.ts

@@ -0,0 +1,374 @@
+/**
+ * Client-side BoardEditPatch types + applier.
+ *
+ * NOTE: 동일 정의가 server/service/types.ts + apply-patch.ts 에 있음.
+ * client 번들이 server 코드를 import 하지 않도록 분리. 변경 시 양쪽 동기화 필요.
+ */
+
+/**
+ * 컴포넌트 타깃팅은 항상 `refid` (things-scene universal numeric handle).
+ * `id` 는 데이터 바인딩 이름이며 unique 가 아니므로 targeting 에 사용하지 않는다.
+ *
+ * 보드는 최상위 부모 — 자체 속성 (fillStyle / width / height / name 등) 을 갖고,
+ * `modifyBoard` 로 변경. 자식 컴포넌트 변경 (`modify`) 와 분리.
+ *
+ * Phase 2 — Scene 조작 op (align/distribute/group/ungroup/zorder). model 차원
+ * 시뮬레이션은 noop 이고 things-scene API 가 정본.
+ */
+export type AlignDirection =
+  | 'left'
+  | 'right'
+  | 'center'
+  | 'top'
+  | 'middle'
+  | 'bottom'
+
+export type DistributeAxis = 'horizontal' | 'vertical'
+
+export type ZorderDirection = 'front' | 'back' | 'forward' | 'backward'
+
+/**
+ * Sugar layout — `arrange` op 의 layout 종류.
+ * Server-side types.ts 의 ArrangeLayout 와 일치 — drift test 가 검증.
+ */
+export type ArrangeLayout =
+  | { type: 'grid'; cols: number; gap?: number; anchor?: { left: number; top: number } }
+  | {
+      type: 'row'
+      gap?: number
+      anchor?: { left: number; top: number }
+      align?: 'start' | 'center' | 'end'
+    }
+  | {
+      type: 'column'
+      gap?: number
+      anchor?: { left: number; top: number }
+      align?: 'start' | 'center' | 'end'
+    }
+
+export type BoardEditOp =
+  | { op: 'add'; component: any }
+  | { op: 'remove'; refid: number }
+  | { op: 'modify'; refid: number; patch: any }
+  | { op: 'modifyBoard'; patch: any }
+  | { op: 'replace'; board: any }
+  | { op: 'align'; refids: number[]; direction: AlignDirection }
+  | { op: 'distribute'; refids: number[]; axis: DistributeAxis }
+  | { op: 'group'; refids: number[] }
+  | { op: 'ungroup'; refid: number }
+  | { op: 'zorder'; refid: number; direction: ZorderDirection }
+  | { op: 'arrange'; refids: number[]; layout: ArrangeLayout }
+
+/**
+ * C-1 — Scene 조작 action (ephemeral). 모델 변경 X, undo 영향 X.
+ * 호스트가 board-action-execute 이벤트로 받아서 things-scene API 직접 호출.
+ */
+export type BoardActionOp =
+  | { action: 'selectComponents'; refids: number[] }
+  | { action: 'centerToComponent'; refid: number; animated?: boolean }
+  | { action: 'fitToView'; mode?: 'fit' | 'ratio' | 'width' | 'height' }
+  | { action: 'setSceneMode'; mode: 'edit' | 'view' }
+  | { action: 'highlightComponents'; refids: number[] }
+
+export interface BoardEditPatch {
+  ops: BoardEditOp[]
+  summary: string
+  confidence: number
+}
+
+export interface PatchApplyReport {
+  /** 패치 적용 후 보드. 모든 op 가 noop 이어도 입력 그대로 반환. */
+  board: any
+  /** 실제로 보드를 바꾼 op 들. */
+  applied: BoardEditOp[]
+  /** id 매칭 실패 등으로 noop 이 된 op 들 — 호출자가 사용자에게 알릴 단서. */
+  missed: BoardEditOp[]
+}
+
+const EMPTY_BOARD = { width: 1000, height: 600, components: [] as any[] }
+
+/**
+ * Patch 를 BoardModel 에 적용 (pure, board 를 mutate 하지 않음).
+ */
+export function applyBoardEditPatch(board: any | undefined, patch: BoardEditPatch): any {
+  return applyBoardEditPatchVerbose(board, patch).board
+}
+
+/**
+ * Verbose 변형 — 각 op 의 적용 여부를 보고.
+ *
+ * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다. LLM 이 잘못된
+ * id 를 만들어 보내면 사용자에게 "수정했습니다" 라고 답하지만 실제로는 아무 변화도
+ * 없는 상황이 발생 — 호스트가 missed 를 보고 사용자에게 경고할 수 있도록 별도
+ * entry point 제공.
+ */
+export function applyBoardEditPatchVerbose(
+  board: any | undefined,
+  patch: BoardEditPatch
+): PatchApplyReport {
+  let result: any = board ?? EMPTY_BOARD
+  const applied: BoardEditOp[] = []
+  const missed: BoardEditOp[] = []
+
+  for (const op of patch.ops) {
+    if (SCENE_ONLY_OPS.has(op.op)) {
+      // scene-only — model 차원 noop, scene 차원 적용. applied 분류.
+      applied.push(op)
+      continue
+    }
+    const next = applyOp(result, op)
+    // componentsUnchanged 는 components 배열 동일 + width/height/fillStyle 동일 만 본다.
+    // modify / remove 의 silent no-op (ghost refid) 검출 전용 — modifyBoard 가 sky
+    // 등 다른 root 키만 바꿀 때 false negative 로 missed 분류되는 회귀 방지.
+    const componentMutating = op.op === 'modify' || op.op === 'remove'
+    if (next === result || (componentMutating && componentsUnchanged(result, next))) {
+      missed.push(op)
+    } else {
+      applied.push(op)
+      result = next
+    }
+  }
+
+  return { board: result, applied, missed }
+}
+
+function componentsUnchanged(prev: any, next: any): boolean {
+  // applyOp 는 항상 새 객체를 만든다. 따라서 reference 비교가 안 되고 내용 비교 필요.
+  // components 는 map/filter 결과 reference 도 다를 수 있으므로 length + 요소 ref 비교.
+  const a = prev.components ?? []
+  const b = next.components ?? []
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return prev.width === next.width && prev.height === next.height && prev.fillStyle === next.fillStyle
+}
+
+const SCENE_ONLY_OPS = new Set<BoardEditOp['op']>([
+  'align',
+  'distribute',
+  'group',
+  'ungroup',
+  'zorder',
+  'arrange'
+])
+
+function applyOp(board: any, op: BoardEditOp): any {
+  switch (op.op) {
+    case 'replace':
+      return op.board
+    case 'add':
+      return { ...board, components: [...(board.components || []), op.component] }
+    case 'remove':
+      // 자식 (group/container 안) refid 도 매칭 — deep search.
+      return {
+        ...board,
+        components: removeComponentDeep(board.components || [], op.refid)
+      }
+    case 'modify':
+      // 자식 refid 도 매칭 — group/container 안의 컴포넌트 수정 가능.
+      return {
+        ...board,
+        components: modifyComponentDeep(board.components || [], op.refid, op.patch)
+      }
+    case 'modifyBoard': {
+      const patch = { ...(op.patch || {}) }
+      delete patch.components // 자식 변경은 별도 op
+      return mergeComponent(board, patch) // 최상위 board 자체에 deep-merge
+    }
+    case 'align':
+    case 'distribute':
+    case 'group':
+    case 'ungroup':
+    case 'zorder':
+    case 'arrange':
+      // scene-only — model 차원 noop. things-scene API 가 정본.
+      return board
+    default:
+      return board
+  }
+}
+
+/**
+ * 주어진 board 상태에서 op 의 inverse 를 계산.
+ *
+ * Revert 기능 — patch 적용 직전 board + op 로 역연산을 만든다. 호스트가
+ * 누적해두면 나중에 역순 실행만으로 복원.
+ *
+ * add 의 inverse 는 새로 발급될 refid 를 알아야 → 모델 단계에서 계산 불가.
+ * 호스트가 scene.add 직후 refid 를 캡처해 직접 만들 것.
+ */
+export function computeInverseOp(board: any, op: BoardEditOp): BoardEditOp | null {
+  if (!board) return null
+  const components = board.components ?? []
+
+  switch (op.op) {
+    case 'add':
+      return null
+
+    case 'remove': {
+      // 자식 refid 도 매칭 (deep search)
+      const target = findComponentDeep(components, op.refid)
+      if (!target) return null
+      return { op: 'add', component: JSON.parse(JSON.stringify(target)) }
+    }
+
+    case 'modify': {
+      // 자식 refid 도 매칭 (deep search)
+      const target = findComponentDeep(components, op.refid)
+      if (!target) return null
+      const oldValues: any = {}
+      for (const k of Object.keys(op.patch || {})) {
+        const v = (target as any)[k]
+        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+      }
+      return { op: 'modify', refid: op.refid, patch: oldValues }
+    }
+
+    case 'modifyBoard': {
+      const oldValues: any = {}
+      const patch = op.patch || {}
+      for (const k of Object.keys(patch)) {
+        if (k === 'components') continue
+        const v = (board as any)[k]
+        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+      }
+      return { op: 'modifyBoard', patch: oldValues }
+    }
+
+    case 'replace':
+      return { op: 'replace', board: JSON.parse(JSON.stringify(board)) }
+
+    case 'zorder': {
+      // forward ↔ backward / front ↔ back. front/back 의 inverse 는 정확하지
+      // 않을 수 있음 (best-effort) — 정확 inverse 는 호스트가 zorder 직전 index
+      // 를 캡처해서 명시 modify 시퀀스로 만들어야.
+      const opp: Record<string, 'front' | 'back' | 'forward' | 'backward'> = {
+        forward: 'backward',
+        backward: 'forward',
+        front: 'back',
+        back: 'front'
+      }
+      const dir = opp[op.direction]
+      if (!dir) return null
+      return { op: 'zorder', refid: op.refid, direction: dir }
+    }
+
+    case 'align':
+    case 'distribute':
+    case 'group':
+    case 'ungroup':
+    case 'arrange':
+      // scene 호출 후에야 변경 결과 알 수 있음. 호스트가 직접 inverse 만든다.
+      return null
+
+    default:
+      return null
+  }
+}
+
+/**
+ * 컴포넌트에 부분 patch 를 적용 (deep merge).
+ * threeD 등 nested object 는 deep merge — 색만 바꾸려고 했을 때 geometry 까지 사라지지 않도록.
+ *
+ * patch 내 `null` 의 시맨틱 — **"이 키를 제거하라"**:
+ *   - fillStyle/strokeStyle 처럼 `string | object | undefined` 인 필드는 null 로
+ *     set 하면 typeof null === 'object' 함정에 빠져 다운스트림 (3D 텍스처 등) 이 크래시.
+ *   - computeInverseOp 가 base 에 키가 없던 (`undefined`) 경우 inverse 를 null 로
+ *     발급하므로, 이 시맨틱과 정확히 일치 — inverse 가 자연스럽게 올바로 동작.
+ *
+ * host (board-modeller-page) 에서 things-scene 의 component.set(merged) 호출 전에 사용.
+ */
+export function mergeComponent(base: any, patch: any): any {
+  const out: any = { ...base }
+  for (const key of Object.keys(patch)) {
+    const patchVal = patch[key]
+    if (patchVal === null) {
+      delete out[key]
+    } else if (isPlainObject(base[key]) && isPlainObject(patchVal)) {
+      out[key] = deepMerge(base[key], patchVal)
+    } else {
+      out[key] = patchVal
+    }
+  }
+  return out
+}
+
+function deepMerge(a: any, b: any): any {
+  const out: any = { ...a }
+  for (const key of Object.keys(b)) {
+    const bv = b[key]
+    if (bv === null) {
+      delete out[key]
+    } else if (isPlainObject(a[key]) && isPlainObject(bv)) {
+      out[key] = deepMerge(a[key], bv)
+    } else {
+      out[key] = bv
+    }
+  }
+  return out
+}
+
+function isPlainObject(v: any): boolean {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}
+
+// ── 자식 컴포넌트 (group/container 안) 까지 매칭 — deep search ─
+// server/service/apply-patch.ts 와 동일 로직. drift test 가 동등성 보장.
+
+function findComponentDeep(components: any[], refid: number): any | undefined {
+  for (const c of components) {
+    if (!c) continue
+    if (c.refid === refid) return c
+    if (Array.isArray(c.components) && c.components.length > 0) {
+      const sub = findComponentDeep(c.components, refid)
+      if (sub) return sub
+    }
+  }
+  return undefined
+}
+
+function modifyComponentDeep(components: any[], refid: number, patch: any): any[] {
+  let changed = false
+  const out = components.map(c => {
+    if (!c) return c
+    if (c.refid === refid) {
+      changed = true
+      return mergeComponent(c, patch)
+    }
+    if (Array.isArray(c.components) && c.components.length > 0) {
+      const updated = modifyComponentDeep(c.components, refid, patch)
+      if (updated !== c.components) {
+        changed = true
+        return { ...c, components: updated }
+      }
+    }
+    return c
+  })
+  return changed ? out : components
+}
+
+function removeComponentDeep(components: any[], refid: number): any[] {
+  let changed = false
+  const out: any[] = []
+  for (const c of components) {
+    if (!c) {
+      out.push(c)
+      continue
+    }
+    if (c.refid === refid) {
+      changed = true
+      continue
+    }
+    if (Array.isArray(c.components) && c.components.length > 0) {
+      const updated = removeComponentDeep(c.components, refid)
+      if (updated !== c.components) {
+        changed = true
+        out.push({ ...c, components: updated })
+        continue
+      }
+    }
+    out.push(c)
+  }
+  return changed ? out : components
+}