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

package/server/service/component-tree.ts

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

package/server/service/index.ts

@@ -0,0 +1,32 @@
+import { BoardAIChatResolver } from './board-ai-resolver.js'
+import { ChatSessionResolver } from './chat-session-resolver.js'
+import { BoardPatchSubscription } from './patch-entry/board-patch-subscription.js'
+import { BoardChatMessageSubscription } from './chat-message/chat-message-subscription.js'
+import { entities as ChatSessionEntities } from './chat-session/index.js'
+import { entities as ChatMessageEntities } from './chat-message/index.js'
+import { entities as ChatSessionParticipantEntities } from './chat-session-participant/index.js'
+import { entities as PatchEntryEntities } from './patch-entry/index.js'
+
+export * from './types.js'
+export * from './assistant.js'
+export * from './apply-patch.js'
+export * from './prefab-registry.js'
+export * from './mention-resolver.js'
+export * from './catalog-resolver.js'
+export * from './board-ai-resolver.js'
+export * from './chat-session-resolver.js'
+export * from './chat-session/index.js'
+export * from './chat-message/index.js'
+export * from './chat-session-participant/index.js'
+export * from './patch-entry/index.js'
+
+export const entities = [
+  ...ChatSessionEntities,
+  ...ChatMessageEntities,
+  ...ChatSessionParticipantEntities,
+  ...PatchEntryEntities
+]
+
+export const schema = {
+  resolverClasses: [BoardAIChatResolver, ChatSessionResolver, BoardPatchSubscription, BoardChatMessageSubscription]
+}

package/server/service/mention-marker.extract.test.ts

@@ -0,0 +1,61 @@
+/**
+ * extractMentionUserIds — 단위 테스트 (초대 트리거 핵심).
+ * content 의 @user{userId:UUID} 마커에서 userId 집합 추출.
+ */
+import { extractMentionUserIds, newParticipantUserIds } from './mention-marker'
+
+describe('extractMentionUserIds', () => {
+  it('단일 @user 멘션', () => {
+    expect(extractMentionUserIds('@영희{userId:u-1} 봐줘')).toEqual(['u-1'])
+  })
+
+  it('복수 멘션 — 순서 보존', () => {
+    expect(extractMentionUserIds('@a{userId:u-1} @b{userId:u-2}')).toEqual(['u-1', 'u-2'])
+  })
+
+  it('중복 userId 제거 (같은 사람 여러 번)', () => {
+    expect(extractMentionUserIds('@a{userId:u-1} ... @a{userId:u-1}')).toEqual(['u-1'])
+  })
+
+  it('refid 마커는 무시 (userId 만)', () => {
+    expect(extractMentionUserIds('#모터{refid:35} @영희{userId:u-9}')).toEqual(['u-9'])
+  })
+
+  it('마커 없는 평문/빈/널 → 빈 배열', () => {
+    expect(extractMentionUserIds('그냥 @영희 (마커 없음)')).toEqual([])
+    expect(extractMentionUserIds('')).toEqual([])
+    expect(extractMentionUserIds(null)).toEqual([])
+    expect(extractMentionUserIds(undefined)).toEqual([])
+  })
+
+  it('UUID 형식 userId', () => {
+    const uuid = '550e8400-e29b-41d4-a716-446655440000'
+    expect(extractMentionUserIds(`@kim{userId:${uuid}}`)).toEqual([uuid])
+  })
+})
+
+describe('newParticipantUserIds (초대 차집합)', () => {
+  it('기존 참여자 제외', () => {
+    expect(newParticipantUserIds(['u1', 'u2', 'u3'], ['u2'])).toEqual(['u1', 'u3'])
+  })
+
+  it('자기 자신(inviter) 제외 — 자기 멘션으로 자가초대 안 함', () => {
+    expect(newParticipantUserIds(['u1', 'me'], [], 'me')).toEqual(['u1'])
+  })
+
+  it('멘션 내 중복 제거', () => {
+    expect(newParticipantUserIds(['u1', 'u1', 'u2'], [])).toEqual(['u1', 'u2'])
+  })
+
+  it('모두 기존이면 빈 배열 (재초대 불필요)', () => {
+    expect(newParticipantUserIds(['u1', 'u2'], ['u1', 'u2'])).toEqual([])
+  })
+
+  it('빈 멘션 → 빈 배열', () => {
+    expect(newParticipantUserIds([], ['u1'], 'me')).toEqual([])
+  })
+
+  it('falsy userId 무시', () => {
+    expect(newParticipantUserIds(['', 'u1'], [])).toEqual(['u1'])
+  })
+})

package/server/service/mention-marker.test.ts

@@ -0,0 +1,228 @@
+/**
+ * mention-marker — `#token{refid:N}` inline marker 단위 테스트.
+ *
+ * 핵심: 단일 source-of-truth (content 컬럼 한 곳) 보존, idempotent 주입,
+ * LLM 입력용 strip, AI 응답 자동 resolve + 주입.
+ */
+import {
+  stripMentionRefids,
+  injectMentionRefids,
+  injectMentionUserIds,
+  injectAiMentionRefids,
+  MENTION_MARKER_RE
+} from './mention-marker'
+
+const make = (components: any[] = []) => ({ width: 1000, height: 600, components })
+
+describe('stripMentionRefids — marker 제거', () => {
+  test('단일 marker 제거', () => {
+    expect(stripMentionRefids('#motor1{refid:35} 빨갛게')).toBe('#motor1 빨갛게')
+  })
+
+  test('다중 marker 제거', () => {
+    expect(stripMentionRefids('#a{refid:1} 와 #b{refid:2}')).toBe('#a 와 #b')
+  })
+
+  test('marker 없으면 원본 그대로', () => {
+    expect(stripMentionRefids('#motor1 빨갛게')).toBe('#motor1 빨갛게')
+    expect(stripMentionRefids('마커 없는 텍스트')).toBe('마커 없는 텍스트')
+  })
+
+  test('빈/널 안전', () => {
+    expect(stripMentionRefids('')).toBe('')
+    expect(stripMentionRefids(null)).toBe('')
+    expect(stripMentionRefids(undefined)).toBe('')
+  })
+
+  test('정규식 reset — 연속 호출 시 안전', () => {
+    // global 정규식이지만 .replace 는 lastIndex 영향 없음
+    const r1 = stripMentionRefids('#a{refid:1}')
+    const r2 = stripMentionRefids('#b{refid:2}')
+    expect(r1).toBe('#a')
+    expect(r2).toBe('#b')
+  })
+})
+
+describe('injectMentionRefids — popup picks 를 본문에 marker 주입', () => {
+  test('단일 token 주입', () => {
+    expect(
+      injectMentionRefids('#motor1 빨갛게', [{ token: 'motor1', refid: 35 }])
+    ).toBe('#motor1{refid:35} 빨갛게')
+  })
+
+  test('다중 token — 각각 주입', () => {
+    expect(
+      injectMentionRefids('#a 와 #b', [
+        { token: 'a', refid: 10 },
+        { token: 'b', refid: 20 }
+      ])
+    ).toBe('#a{refid:10} 와 #b{refid:20}')
+  })
+
+  test('미등록 token 은 건드리지 않음', () => {
+    expect(
+      injectMentionRefids('#motor1 와 #other', [{ token: 'motor1', refid: 35 }])
+    ).toBe('#motor1{refid:35} 와 #other')
+  })
+
+  test('이미 marker 있으면 덮어쓰기 안 함 (idempotent)', () => {
+    expect(
+      injectMentionRefids('#motor1{refid:99}', [{ token: 'motor1', refid: 35 }])
+    ).toBe('#motor1{refid:99}')
+  })
+
+  test('단어 중간 # 매칭 안 함', () => {
+    expect(
+      injectMentionRefids('foo#motor1', [{ token: 'motor1', refid: 35 }])
+    ).toBe('foo#motor1')
+  })
+
+  test('빈 picks / 빈 텍스트 안전', () => {
+    expect(injectMentionRefids('#a', [])).toBe('#a')
+    expect(injectMentionRefids('', [{ token: 'a', refid: 1 }])).toBe('')
+    expect(injectMentionRefids('#a', null)).toBe('#a')
+    expect(injectMentionRefids('#a', undefined)).toBe('#a')
+  })
+
+  test('한글 token 주입', () => {
+    expect(
+      injectMentionRefids('#경광등1 빨갛게', [{ token: '경광등1', refid: 42 }])
+    ).toBe('#경광등1{refid:42} 빨갛게')
+  })
+
+  test('동일 token 다중 등장 — 모두 주입', () => {
+    expect(
+      injectMentionRefids('#x 그리고 #x', [{ token: 'x', refid: 7 }])
+    ).toBe('#x{refid:7} 그리고 #x{refid:7}')
+  })
+})
+
+describe('injectAiMentionRefids — AI 응답 #token resolve + 주입', () => {
+  test('id 매칭으로 marker 주입', () => {
+    const board = make([{ refid: 35, type: 'rect', id: 'motor1' }])
+    expect(injectAiMentionRefids('#motor1 을 빨갛게 만들었습니다', board)).toBe(
+      '#motor1{refid:35} 을 빨갛게 만들었습니다'
+    )
+  })
+
+  test('한글 name 매칭', () => {
+    const board = make([{ refid: 42, type: 'rect', name: '경광등1' }])
+    expect(injectAiMentionRefids('#경광등1 위치 변경', board)).toBe(
+      '#경광등1{refid:42} 위치 변경'
+    )
+  })
+
+  test('매칭 안 되는 token — marker 없이 통과', () => {
+    const board = make([{ refid: 1, type: 'rect', id: 'a' }])
+    expect(injectAiMentionRefids('#a 처리, #unknown 못 찾음', board)).toBe(
+      '#a{refid:1} 처리, #unknown 못 찾음'
+    )
+  })
+
+  test('빈 보드 — 변경 없음', () => {
+    expect(injectAiMentionRefids('#a 처리', make([]))).toBe('#a 처리')
+  })
+
+  test('null/undefined board 안전', () => {
+    expect(injectAiMentionRefids('#a', null)).toBe('#a')
+    expect(injectAiMentionRefids('#a', undefined)).toBe('#a')
+  })
+
+  test('동일 token 여러 번 — 모두 주입', () => {
+    const board = make([{ refid: 7, type: 'rect', id: 'x' }])
+    expect(injectAiMentionRefids('#x 와 #x 처리', board)).toBe(
+      '#x{refid:7} 와 #x{refid:7} 처리'
+    )
+  })
+
+  test('이미 marker 있으면 그대로 (이중 처리 방지)', () => {
+    const board = make([{ refid: 35, type: 'rect', id: 'motor1' }])
+    expect(injectAiMentionRefids('#motor1{refid:99} 처리', board)).toBe(
+      '#motor1{refid:99} 처리'
+    )
+  })
+})
+
+describe('inject + strip 왕복 — round-trip 무결성', () => {
+  test('inject 후 strip → 원본 텍스트 (마커 없는 입력)', () => {
+    const original = '#motor1 빨갛게 #pump 이동'
+    const enriched = injectMentionRefids(original, [
+      { token: 'motor1', refid: 35 },
+      { token: 'pump', refid: 42 }
+    ])
+    expect(stripMentionRefids(enriched)).toBe(original)
+  })
+
+  test('strip 후 다시 inject — 같은 picks 면 동일 결과', () => {
+    const enriched = '#a{refid:1} 와 #b{refid:2}'
+    const stripped = stripMentionRefids(enriched)
+    const reInjected = injectMentionRefids(stripped, [
+      { token: 'a', refid: 1 },
+      { token: 'b', refid: 2 }
+    ])
+    expect(reInjected).toBe(enriched)
+  })
+})
+
+describe('injectMentionUserIds — `@user{userId:UUID}` 주입', () => {
+  test('단일 user 주입', () => {
+    expect(
+      injectMentionUserIds('@경철 도와줘', [{ token: '경철', userId: 'abc-123' }])
+    ).toBe('@경철{userId:abc-123} 도와줘')
+  })
+
+  test('이미 marker 있으면 idempotent', () => {
+    expect(
+      injectMentionUserIds('@경철{userId:old-id} 처리', [
+        { token: '경철', userId: 'new-id' }
+      ])
+    ).toBe('@경철{userId:old-id} 처리')
+  })
+
+  test('# 토큰은 영향 없음 (다른 trigger)', () => {
+    expect(
+      injectMentionUserIds('#motor1 와 @경철 같이', [
+        { token: 'motor1', userId: 'wrong-id' },
+        { token: '경철', userId: 'abc' }
+      ])
+    ).toBe('#motor1 와 @경철{userId:abc} 같이')
+  })
+
+  test('빈 picks / 빈 텍스트 안전', () => {
+    expect(injectMentionUserIds('@경철', [])).toBe('@경철')
+    expect(injectMentionUserIds('', [{ token: 'x', userId: 'a' }])).toBe('')
+    expect(injectMentionUserIds('@경철', null)).toBe('@경철')
+  })
+
+  test('단어 중간 @ 매칭 안 함', () => {
+    expect(
+      injectMentionUserIds('user@host', [{ token: 'host', userId: 'x' }])
+    ).toBe('user@host')
+  })
+})
+
+describe('stripMentionRefids — 다양한 마커 키 일반화 처리', () => {
+  test('refid + userId 마커 모두 strip', () => {
+    expect(
+      stripMentionRefids('#motor{refid:35} 와 @경철{userId:abc-123} 처리')
+    ).toBe('#motor 와 @경철 처리')
+  })
+
+  test('미래 마커 키도 strip — `{key:value}` 형식이면 모두', () => {
+    expect(stripMentionRefids('@bot{agentId:claude-1} hi')).toBe('@bot hi')
+    expect(stripMentionRefids('test{threadId:t1}done')).toBe('testdone')
+  })
+})
+
+describe('MENTION_MARKER_RE — 정규식 직접 검증', () => {
+  test('단일 매칭', () => {
+    const m = '#motor1{refid:35}'.match(/\{refid:(\d+)\}/)
+    expect(m?.[1]).toBe('35')
+  })
+
+  test('global flag — exec lastIndex 영향 받음 (호출 시 새 RegExp 권장)', () => {
+    // MENTION_MARKER_RE 자체가 g flag 라 exec 사용 시 주의 — replace 권장
+    const re = MENTION_MARKER_RE
+    expect(re.flags).toContain('g')
+  })
+})

package/server/service/mention-marker.ts

@@ -0,0 +1,184 @@
+/**
+ * `#token{refid:N}` inline marker — 채팅 메시지의 단일 source-of-truth.
+ *
+ * 설계 원칙:
+ *   - 메시지 영속은 `ChatMessage.content` 한 컬럼에 통합. token-refid 매핑은 본문 안에
+ *     `#motor1{refid:35}` 형태로 inline 마킹.
+ *   - 별도 컬럼이 없으니 두 데이터 사이 consistency 깨질 일 자체가 없음.
+ *   - LLM 한테는 `stripMentionRefids` 로 마커 제거 후 보냄 — 토큰 낭비 / 주의 분산 차단.
+ *   - 클라이언트 렌더는 `#token{refid:N}` 패턴을 추출해 `<span data-refid="N">#token</span>`
+ *     으로 변환 → 클릭 시 deterministic 한 컴포넌트 점프.
+ *
+ * 마커 형식:
+ *   - `#token{refid:N}` (N 은 정수)
+ *   - token 과 `{` 사이 공백 없음
+ *   - `{refid:N}` 자체는 사람도 디버그 시 읽기 쉬움 (zero-width 문자나 prefix 약어
+ *     보다 우선) — 렌더링 깨졌을 때 로그 / DB 직접 보고 파악 가능
+ */
+
+import type { BoardModel } from '@things-factory/board-import'
+import { findMentions, type MentionPick } from './mention-resolver'
+
+/**
+ * 인라인 마커 정규식 — `{key:value}` 형태. 현재 사용:
+ *   - `{refid:N}`     — `#component` 멘션 (things-scene refid)
+ *   - `{userId:UUID}` — `@user` 멘션 (도메인 사용자)
+ * 향후 새 종류 (agentId / threadId / 외부 시스템 id 등) 도 동일 형식으로 추가 가능.
+ */
+export const MENTION_MARKER_RE = /\{[a-zA-Z][a-zA-Z0-9]*:[^}\s]+\}/g
+
+/**
+ * 멘션된 userId 중 *아직 참여자가 아닌* + *자기 자신이 아닌* 신규만 (C4 초대 — 차집합).
+ * 순수 — 누구를 새로 참여자 등록할지 판정. (resolver 가 repo 작업과 분리해 테스트 가능.)
+ */
+export function newParticipantUserIds(
+  mentioned: ReadonlyArray<string>,
+  existing: ReadonlyArray<string>,
+  selfUserId?: string | null
+): string[] {
+  const have = new Set(existing)
+  if (selfUserId) have.add(selfUserId)
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const id of mentioned) {
+    if (!id || have.has(id) || seen.has(id)) continue
+    seen.add(id)
+    out.push(id)
+  }
+  return out
+}
+
+/**
+ * 본문에서 `@user{userId:UUID}` 마커의 *userId 집합* 추출 (C4 — 초대 트리거).
+ * 같은 user 중복 제거, 순서 보존(첫 등장순). 마커 없으면 빈 배열.
+ * 순수 — content 만으로 "이 메시지가 누구를 멘션했나" 판정.
+ */
+export function extractMentionUserIds(text: string | null | undefined): string[] {
+  if (!text) return []
+  const re = /\{userId:([^}\s]+)\}/g
+  const seen = new Set<string>()
+  const out: string[] = []
+  let m: RegExpExecArray | null
+  while ((m = re.exec(text)) !== null) {
+    const id = m[1]
+    if (!seen.has(id)) {
+      seen.add(id)
+      out.push(id)
+    }
+  }
+  return out
+}
+
+/**
+ * 본문에서 모든 `{key:value}` 인라인 마커 제거. LLM 입력 / textarea 편집 / 평문 표출 등.
+ * 토큰 자체 (#component, @user) 는 그대로 유지.
+ */
+export function stripMentionRefids(text: string | null | undefined): string {
+  if (!text) return ''
+  return text.replace(MENTION_MARKER_RE, '')
+}
+
+/** 토큰 매칭 정규식 빌더 — trigger 별로 build. */
+function buildTokenRegex(trigger: string, markerKey: string): RegExp {
+  const word =
+    '\\w\\p{Script=Hangul}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Han}'
+  // (앞경계)(트리거)(토큰)(이미 같은 markerKey 의 마커가 붙어있는지 — skip 판정용)
+  return new RegExp(
+    `(^|[^${word}])(${escapeRegex(trigger)})([${word}-]+)(\\{${markerKey}:[^}\\s]+\\})?`,
+    'gu'
+  )
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 일반화된 inline marker 주입 — trigger 와 markerKey 별로 picks 를 본문에 박음.
+ *
+ *   injectInlineMarkers(text, '#', 'refid', [{ token, value: 35 }])
+ *   injectInlineMarkers(text, '@', 'userId', [{ token, value: 'uuid' }])
+ *
+ * 룰:
+ *   - 정확 token 일치 (popup 명시 선택된 것만 — 자유 입력 토큰은 안 건드림)
+ *   - 동일 token 여러 번 등장하면 모두 marker 적용
+ *   - 이미 같은 markerKey 의 marker 가 붙어있으면 그대로 유지 (덮어쓰기 X)
+ */
+export function injectInlineMarkers(
+  text: string,
+  trigger: string,
+  markerKey: string,
+  picks: ReadonlyArray<{ token: string; value: string | number }> | null | undefined
+): string {
+  if (!text || !picks || picks.length === 0) return text ?? ''
+  const map = new Map<string, string | number>()
+  for (const p of picks) map.set(p.token, p.value)
+  const re = buildTokenRegex(trigger, markerKey)
+  return text.replace(re, (match, leading, trig, token, existingMarker) => {
+    if (existingMarker) return match
+    const value = map.get(token)
+    if (value === undefined) return match
+    return `${leading}${trig}${token}{${markerKey}:${value}}`
+  })
+}
+
+/**
+ * `#component` 멘션 picks 를 `{refid:N}` 마커로 주입 (호환 유지).
+ */
+export function injectMentionRefids(
+  text: string,
+  picks: ReadonlyArray<MentionPick> | null | undefined
+): string {
+  return injectInlineMarkers(
+    text,
+    '#',
+    'refid',
+    picks?.map(p => ({ token: p.token, value: p.refid }))
+  )
+}
+
+/**
+ * `@user` 멘션 picks 를 `{userId:UUID}` 마커로 주입.
+ * picks: [{token: 사용자_표시명, value: 사용자_id}]
+ */
+export function injectMentionUserIds(
+  text: string,
+  picks: ReadonlyArray<{ token: string; userId: string }> | null | undefined
+): string {
+  return injectInlineMarkers(
+    text,
+    '@',
+    'userId',
+    picks?.map(p => ({ token: p.token, value: p.userId }))
+  )
+}
+
+/**
+ * AI 응답 텍스트의 `#token` 들을 currentBoard 에 대해 resolve 해 inline marker 로 주입.
+ *
+ * - 매칭 룰: `findMentions` (= name/id/type/tag/class/text OR). 다중 일치 시 첫 결과.
+ * - 매칭 안 되면 marker 없이 통과 (예: AI 가 patch 로 새로 만든 컴포넌트는 input.currentBoard
+ *   에 없으므로 marker 못 박음 — 클라이언트 클릭 시 runtime fallback 으로 해석 가능).
+ * - 이미 marker 있으면 그대로.
+ */
+export function injectAiMentionRefids(
+  text: string,
+  currentBoard: BoardModel | null | undefined
+): string {
+  if (!text) return ''
+  const matches = findMentions(text, currentBoard ?? null)
+  if (matches.length === 0) return text
+
+  // token → 첫 매칭 refid 맵
+  const tokenToRefid = new Map<string, number>()
+  for (const m of matches) {
+    if (tokenToRefid.has(m.token)) continue
+    if (m.matched.length === 0) continue
+    tokenToRefid.set(m.token, m.matched[0].refid)
+  }
+  if (tokenToRefid.size === 0) return text
+
+  // 사용자 picks 와 동일한 injection 룰로 주입.
+  const picks = Array.from(tokenToRefid.entries()).map(([token, refid]) => ({ token, refid }))
+  return injectMentionRefids(text, picks)
+}