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

package/server/service/chat-session-participant/invite-notification.ts

@@ -0,0 +1,48 @@
+/**
+ * 협업 초대 알림 — 순수 payload 빌더.
+ *
+ * 부수효과(실제 발송)는 resolver 의 thin caller 가 `context.state.notify` 로 수행.
+ * 여기엔 "무엇을 보낼지"(payload) 결정 로직만 둔다 — DB·pubsub·notify 의존 없이 테스트 가능.
+ * (patch spine 의 board-patch-broadcast.ts 와 동일한 순수/부수효과 분리 컨벤션.)
+ */
+
+/** notification-middleware 의 notifier 가 받는 인자 형태 (필요한 키만). */
+export interface InviteNotification {
+  receivers: string[]
+  type: string
+  subject: string
+  title: string
+  body: string
+  url?: string
+  mode: 'background' | 'foreground'
+}
+
+/** 초대자 식별용 — User 엔티티에서 쓰는 필드만 (duck-typed). */
+export interface Inviter {
+  name?: string | null
+  email?: string | null
+}
+
+/**
+ * 초대된 사용자들에게 보낼 협업 초대 알림 payload 를 만든다.
+ * 받는 사람이 없으면 null (= 보낼 것 없음).
+ */
+export function buildInviteNotification(
+  userIds: string[],
+  boardId: string | undefined,
+  inviter: Inviter | undefined | null
+): InviteNotification | null {
+  if (!Array.isArray(userIds) || userIds.length === 0) return null
+
+  const who = inviter?.name || inviter?.email || 'someone'
+  return {
+    receivers: userIds,
+    type: 'board-collab-invite',
+    subject: 'info',
+    title: 'Board collaboration invite',
+    body: `${who} invited you to collaborate on a board.`,
+    // board 가 연결돼 있으면 모델러로 바로 가는 링크. 없으면 링크 생략.
+    url: boardId ? `board-modeller/${boardId}` : undefined,
+    mode: 'background'
+  }
+}

package/server/service/chat-session-participant/presence.test.ts

@@ -0,0 +1,39 @@
+/**
+ * presence.isOnline — 단위 테스트. lastSeenAt 기반 online 판정(시각 주입, 순수).
+ */
+import { isOnline, PRESENCE_TTL_MS } from './presence'
+
+const NOW = 1_000_000_000_000 // 고정 기준 시각(ms)
+
+describe('isOnline', () => {
+  it('ttl 이내 → online', () => {
+    expect(isOnline(new Date(NOW - 10_000), NOW)).toBe(true)
+  })
+
+  it('ttl 경계 — 정확히 ttl 은 online, 초과는 offline', () => {
+    expect(isOnline(new Date(NOW - PRESENCE_TTL_MS), NOW)).toBe(true)
+    expect(isOnline(new Date(NOW - PRESENCE_TTL_MS - 1), NOW)).toBe(false)
+  })
+
+  it('lastSeenAt 없음 → offline', () => {
+    expect(isOnline(null, NOW)).toBe(false)
+    expect(isOnline(undefined, NOW)).toBe(false)
+  })
+
+  it('잘못된 값 → offline', () => {
+    expect(isOnline('not-a-date', NOW)).toBe(false)
+  })
+
+  it('ISO 문자열도 수용', () => {
+    expect(isOnline(new Date(NOW - 5_000).toISOString(), NOW)).toBe(true)
+  })
+
+  it('미래 시각(클럭 스큐) → online 으로 관대', () => {
+    expect(isOnline(new Date(NOW + 60_000), NOW)).toBe(true)
+  })
+
+  it('커스텀 ttl', () => {
+    expect(isOnline(new Date(NOW - 20_000), NOW, 10_000)).toBe(false)
+    expect(isOnline(new Date(NOW - 5_000), NOW, 10_000)).toBe(true)
+  })
+})

package/server/service/chat-session-participant/presence.ts

@@ -0,0 +1,21 @@
+/*
+ * presence — lastSeenAt 기반 online 판정 (Phase Board-AI C4). 순수·결정적 → 테스트 가능.
+ * 클라이언트가 주기적 heartbeat(touchPresence)로 lastSeenAt 을 갱신하고, roster 는
+ * 이 판정으로 online/offline 표시. 시각(now)을 주입받아 시간 의존성을 제거.
+ */
+
+/** online 으로 간주할 기본 유예(ms) — heartbeat 주기의 ~2.5배 권장(주기 30s → 75s). */
+export const PRESENCE_TTL_MS = 75_000
+
+/** lastSeenAt 이 now 기준 ttl 이내면 online. lastSeenAt 없으면 offline. */
+export function isOnline(
+  lastSeenAt: Date | string | null | undefined,
+  now: number,
+  ttlMs: number = PRESENCE_TTL_MS
+): boolean {
+  if (!lastSeenAt) return false
+  const t = lastSeenAt instanceof Date ? lastSeenAt.getTime() : new Date(lastSeenAt).getTime()
+  if (!Number.isFinite(t)) return false
+  const age = now - t
+  return age >= 0 ? age <= ttlMs : true // 미래 시각(클럭 스큐)은 online 으로 관대 처리
+}

package/server/service/chat-session-resolver.ts

@@ -0,0 +1,312 @@
+/**
+ * ChatSession lifecycle resolver — start/get/recordDirectPatch/revertPatch + 메시지·패치 페이징 query.
+ *
+ * 핵심: `recordDirectPatch` — 사용자가 모델러에서 직접 편집 시 클라이언트가 호출.
+ * 이게 PatchEntry(source:'user-direct') + system 메시지 자동 추가 → AI 가 모든 변경을 인지.
+ */
+import { Resolver, Query, Mutation, Arg, Ctx, Directive, Int } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import { User } from '@things-factory/auth-base'
+import { buildDomainUsersQueryBuilder } from '@things-factory/auth-base/dist-server/utils/get-domain-users.js'
+
+import { getRepository } from '@things-factory/shell'
+
+import { ChatSession } from './chat-session/chat-session.js'
+import { ChatMessage } from './chat-message/chat-message.js'
+import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
+import { PatchEntry } from './patch-entry/patch-entry.js'
+import { publishBoardPatch } from './patch-entry/board-patch-subscription.js'
+import { publishChatMessage } from './chat-message/chat-message-publish.js'
+
+@Resolver()
+export class ChatSessionResolver {
+  @Query(() => ChatSession, { nullable: true, description: 'Get AI chat session by id.' })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatSession(
+    @Arg('id') id: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession | null> {
+    const { domain } = context.state
+    return (await getRepository(ChatSession).findOneBy({ id, domain: { id: domain.id } })) ?? null
+  }
+
+  @Query(() => ChatSession, { nullable: true, description: 'Get AI chat session by board id (returns first match — backward compat single-session lookup).' })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatSessionByBoard(
+    @Arg('boardId') boardId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession | null> {
+    const { domain } = context.state
+    return (
+      (await getRepository(ChatSession).findOneBy({ boardId, domain: { id: domain.id } })) ?? null
+    )
+  }
+
+  @Query(() => [ChatSession], {
+    description: 'List all AI chat sessions for a board (oldest first). Multi-session support — UI 탭으로 표시.'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatSessionsByBoard(
+    @Arg('boardId') boardId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession[]> {
+    const { domain } = context.state
+    return await getRepository(ChatSession).find({
+      where: { boardId, domain: { id: domain.id } },
+      order: { createdAt: 'ASC' }
+    })
+  }
+
+  @Query(() => [User], {
+    description:
+      'List users in the current domain for `@` mention popup. board-ai 권한이면 누구나 멘션용 검색 가능 (관리자 전용 users() 와 별도).'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async domainUsersForMention(
+    @Arg('query', { nullable: true, description: 'Substring to match against name/email (case-insensitive). Empty → all.' }) query: string | undefined,
+    @Arg('limit', () => Int, { nullable: true, defaultValue: 50 }) limit: number,
+    @Ctx() context: ResolverContext
+  ): Promise<User[]> {
+    const { domain } = context.state
+    const qb = buildDomainUsersQueryBuilder(domain.id, 'USER')
+    if (query?.trim()) {
+      const q = `%${query.trim().toLowerCase()}%`
+      qb.andWhere('(LOWER(USER.name) LIKE :q OR LOWER(USER.email) LIKE :q)', { q })
+    }
+    qb.orderBy('USER.name', 'ASC').limit(limit)
+    return await qb.getMany()
+  }
+
+  @Query(() => [ChatSessionParticipant], {
+    description: 'List participants of a ChatSession (members / owner).'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatSessionParticipants(
+    @Arg('sessionId') sessionId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSessionParticipant[]> {
+    const { domain } = context.state
+    const session = await getRepository(ChatSession).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) return []
+    return await getRepository(ChatSessionParticipant).find({
+      where: { session: { id: sessionId } as any, domain: { id: domain.id } },
+      order: { createdAt: 'ASC' }
+    })
+  }
+
+  @Mutation(() => Boolean, {
+    description: 'Presence heartbeat — bump current user\'s lastSeenAt in the session (online indicator).'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async touchPresence(@Arg('sessionId') sessionId: string, @Ctx() context: ResolverContext): Promise<boolean> {
+    const { domain, user } = context.state
+    const repo = getRepository(ChatSessionParticipant)
+    const part = await repo.findOne({
+      where: { session: { id: sessionId } as any, user: { id: user.id } as any, domain: { id: domain.id } as any }
+    })
+    if (!part) return false // 참여자가 아니면 heartbeat 무시 (초대 전)
+    await repo.update(part.id!, { lastSeenAt: new Date(), updater: user } as any)
+    return true
+  }
+
+  @Query(() => [ChatMessage], { description: 'List chat messages of a session, oldest first.' })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatMessages(
+    @Arg('sessionId') sessionId: string,
+    @Arg('limit', () => Int, { nullable: true, defaultValue: 100 }) limit: number,
+    @Arg('offset', () => Int, { nullable: true, defaultValue: 0 }) offset: number,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatMessage[]> {
+    const { domain } = context.state
+    const session = await getRepository(ChatSession).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) return []
+    return await getRepository(ChatMessage).find({
+      where: { session: { id: sessionId } as any },
+      // creator: 그룹챗 발신자 표시용 (id/name). 다른 참여자 메시지에 보낸이를 보여준다.
+      relations: { creator: true },
+      order: { createdAt: 'ASC' },
+      take: limit,
+      skip: offset
+    })
+  }
+
+  @Query(() => [PatchEntry], { description: 'List patch entries of a session, newest first.' })
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatPatches(
+    @Arg('sessionId') sessionId: string,
+    @Arg('limit', () => Int, { nullable: true, defaultValue: 100 }) limit: number,
+    @Ctx() context: ResolverContext
+  ): Promise<PatchEntry[]> {
+    const { domain } = context.state
+    const session = await getRepository(ChatSession).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) return []
+    return await getRepository(PatchEntry).find({
+      where: { session: { id: sessionId } as any },
+      order: { createdAt: 'DESC' },
+      take: limit
+    })
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => ChatSession, {
+    description: 'Start (or get existing) AI chat session for a board. Idempotent — returns first existing or creates one.'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async startBoardAISession(
+    @Arg('boardId') boardId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession> {
+    const { domain, user, tx } = context.state
+    const repo = getRepository(ChatSession, tx)
+
+    const existing = await repo.findOneBy({ boardId, domain: { id: domain.id } })
+    if (existing) return existing
+
+    const session = await repo.save({
+      domain,
+      boardId,
+      creator: user,
+      updater: user
+    } as any)
+    // creator 를 owner participant 로 자동 등록 — 다자간 채팅 기반.
+    await getRepository(ChatSessionParticipant, tx).save({
+      domain,
+      session: { id: session.id } as any,
+      user,
+      role: 'owner',
+      creator: user,
+      updater: user
+    } as any)
+    return session
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => ChatSession, {
+    description: 'Always create a new AI chat session for a board (no idempotent reuse). For multi-session UX — 새 탭 열기.'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async createChatSession(
+    @Arg('boardId') boardId: string,
+    @Arg('name', { nullable: true, description: 'Optional name (defaults to auto-generated `세션 N`).' }) name: string | undefined,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession> {
+    const { domain, user, tx } = context.state
+    const repo = getRepository(ChatSession, tx)
+
+    // 이름 미지정 시 자동 생성 — 보드의 기존 세션 수 + 1.
+    let finalName = name?.trim()
+    if (!finalName) {
+      const count = await repo.count({
+        where: { boardId, domain: { id: domain.id } }
+      })
+      finalName = `세션 ${count + 1}`
+    }
+
+    const session = await repo.save({
+      domain,
+      boardId,
+      creator: user,
+      updater: user,
+      name: finalName
+    } as any)
+    // creator 를 owner participant 로 자동 등록.
+    await getRepository(ChatSessionParticipant, tx).save({
+      domain,
+      session: { id: session.id } as any,
+      user,
+      role: 'owner',
+      creator: user,
+      updater: user
+    } as any)
+    return session
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, {
+    description: 'Rename a ChatSession (tab label).'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async renameChatSession(
+    @Arg('sessionId') sessionId: string,
+    @Arg('name') name: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user, tx } = context.state
+    const repo = getRepository(ChatSession, tx)
+    const session = await repo.findOneBy({ id: sessionId, domain: { id: domain.id } })
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+    await repo.update(sessionId, { name: name.trim() || null, updater: user } as any)
+    return true
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => PatchEntry, {
+    description: 'Record a patch from user direct edit. Adds a system message so AI sees the change next turn.'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async recordDirectPatch(
+    @Arg('sessionId') sessionId: string,
+    @Arg('ops', () => GraphQLJSON) ops: any[],
+    @Arg('summary', { nullable: true }) summary: string | undefined,
+    @Ctx() context: ResolverContext
+  ): Promise<PatchEntry> {
+    const { domain, tx, user } = context.state
+    const session = await getRepository(ChatSession, tx).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+
+    const entry = await getRepository(PatchEntry, tx).save({
+      session: { id: session.id } as any,
+      source: 'user-direct',
+      ops: JSON.stringify(ops || []),
+      summary,
+      reverted: false
+    } as any)
+
+    // AI 컨텍스트 흐름 — system 메시지 자동 추가. creator = 직접 편집한 사용자.
+    // parentMessage = 직전 in-session 메시지 (timeline 연속성 유지 — system 도 chain 에 합류).
+    const previousLast = await getRepository(ChatMessage, tx).findOne({
+      where: { session: { id: session.id } as any },
+      order: { createdAt: 'DESC' }
+    })
+    const sysMsg = await getRepository(ChatMessage, tx).save({
+      session: { id: session.id } as any,
+      role: 'system',
+      content: `User directly edited the board: ${summary ?? `${(ops || []).length} op(s)`}`,
+      relatedPatchId: entry.id,
+      creator: user,
+      updater: user,
+      parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
+    } as any)
+
+    // C1: user-direct 편집도 같은 board 구독자에게 방송 (AI·타참여자 실시간 반영). best-effort.
+    publishBoardPatch({ domainId: domain.id, boardId: session.boardId, patch: entry })
+    // C4: 직접편집 system 메시지를 같은 세션 구독자에게 방송 (transcript 실시간 일관성). best-effort.
+    publishChatMessage({ domainId: domain.id, sessionId: session.id, message: sysMsg })
+
+    return entry
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, { description: 'Mark a patch as reverted (does not undo, only flags).' })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async revertPatch(
+    @Arg('patchId') patchId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { tx } = context.state
+    await getRepository(PatchEntry, tx).update(patchId, { reverted: true })
+    return true
+  }
+}

package/server/service/component-tree.test.ts

@@ -0,0 +1,248 @@
+/**
+ * component-tree — collectAllComponents / findComponentByRefid 단위 테스트.
+ */
+import { collectAllComponents, findComponentByRefid } from './component-tree'
+
+const flat = (board: any) =>
+  collectAllComponents(board).map(f => ({
+    refid: f.refid,
+    parent: f.parentRefid,
+    depth: f.depth,
+    type: (f.component as any).type
+  }))
+
+describe('collectAllComponents — 평면화', () => {
+  test('빈 보드 — 빈 배열', () => {
+    expect(collectAllComponents({ width: 100, height: 100, components: [] })).toEqual([])
+  })
+
+  test('null/undefined 입력 — 빈 배열', () => {
+    expect(collectAllComponents(undefined)).toEqual([])
+    expect(collectAllComponents(null as any)).toEqual([])
+  })
+
+  test('components 키 없음 — 빈 배열', () => {
+    expect(collectAllComponents({ width: 100, height: 100 } as any)).toEqual([])
+  })
+
+  test('top-level 만 — 그대로 평면', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [
+        { type: 'rect', refid: 1 },
+        { type: 'circle', refid: 2 },
+        { type: 'text', refid: 3 }
+      ]
+    }
+    expect(flat(board)).toEqual([
+      { refid: 1, parent: undefined, depth: 0, type: 'rect' },
+      { refid: 2, parent: undefined, depth: 0, type: 'circle' },
+      { refid: 3, parent: undefined, depth: 0, type: 'text' }
+    ])
+  })
+
+  test('group 1단계 — 자식 노출 + parentRefid 표시', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [
+        { type: 'rect', refid: 1 },
+        {
+          type: 'group',
+          refid: 2,
+          components: [
+            { type: 'rect', refid: 3 },
+            { type: 'circle', refid: 4 }
+          ]
+        }
+      ]
+    }
+    expect(flat(board)).toEqual([
+      { refid: 1, parent: undefined, depth: 0, type: 'rect' },
+      { refid: 2, parent: undefined, depth: 0, type: 'group' },
+      { refid: 3, parent: 2, depth: 1, type: 'rect' },
+      { refid: 4, parent: 2, depth: 1, type: 'circle' }
+    ])
+  })
+
+  test('group 안 group (2단계) — 깊은 재귀', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [
+        {
+          type: 'group',
+          refid: 1,
+          components: [
+            { type: 'rect', refid: 2 },
+            {
+              type: 'group',
+              refid: 3,
+              components: [{ type: 'circle', refid: 4 }]
+            }
+          ]
+        }
+      ]
+    }
+    expect(flat(board)).toEqual([
+      { refid: 1, parent: undefined, depth: 0, type: 'group' },
+      { refid: 2, parent: 1, depth: 1, type: 'rect' },
+      { refid: 3, parent: 1, depth: 1, type: 'group' },
+      { refid: 4, parent: 3, depth: 2, type: 'circle' }
+    ])
+  })
+
+  test('빈 group — group 자체만 + 자식 0', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [{ type: 'group', refid: 1, components: [] }]
+    }
+    expect(flat(board)).toEqual([
+      { refid: 1, parent: undefined, depth: 0, type: 'group' }
+    ])
+  })
+
+  test('refid 없는 컴포넌트 — undefined refid', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [{ type: 'rect' /* no refid */ }]
+    }
+    const r = collectAllComponents(board as any)
+    expect(r).toHaveLength(1)
+    expect(r[0].refid).toBeUndefined()
+  })
+
+  test('비-object 컴포넌트 (null) — 건너뜀', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [{ type: 'rect', refid: 1 }, null, { type: 'circle', refid: 2 }]
+    }
+    expect(flat(board as any)).toEqual([
+      { refid: 1, parent: undefined, depth: 0, type: 'rect' },
+      { refid: 2, parent: undefined, depth: 0, type: 'circle' }
+    ])
+  })
+
+  test('path 정보 — root 부터 본 컴포넌트까지', () => {
+    const board = {
+      width: 100,
+      height: 100,
+      components: [
+        {
+          type: 'group',
+          refid: 1,
+          components: [
+            {
+              type: 'group',
+              refid: 2,
+              components: [{ type: 'rect', refid: 3 }]
+            }
+          ]
+        }
+      ]
+    }
+    const r = collectAllComponents(board)
+    expect(r.find(f => f.refid === 3)?.path).toEqual([1, 2, 3])
+    expect(r.find(f => f.refid === 1)?.path).toEqual([1])
+  })
+
+  test('maxDepth — 깊이 cap', () => {
+    // 4단계 중첩
+    const board: any = {
+      width: 100,
+      height: 100,
+      components: [
+        {
+          refid: 1,
+          components: [
+            {
+              refid: 2,
+              components: [
+                {
+                  refid: 3,
+                  components: [{ refid: 4 }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+    // depth 2 cap → refid 1, 2, 3 까지만 (depth 0, 1, 2)
+    const capped = collectAllComponents(board, { maxDepth: 2 })
+    expect(capped.map(f => f.refid)).toEqual([1, 2, 3])
+  })
+})
+
+describe('findComponentByRefid — deep search', () => {
+  const board = {
+    width: 100,
+    height: 100,
+    components: [
+      { type: 'rect', refid: 1 },
+      {
+        type: 'group',
+        refid: 2,
+        components: [
+          { type: 'rect', refid: 3 },
+          {
+            type: 'group',
+            refid: 4,
+            components: [{ type: 'circle', refid: 5 }]
+          }
+        ]
+      }
+    ]
+  }
+
+  test('top-level refid — 찾음', () => {
+    const r = findComponentByRefid(board, 1)
+    expect(r).toBeDefined()
+    expect(r!.component.refid).toBe(1)
+    expect(r!.parentArray).toBe(board.components)
+    expect(r!.index).toBe(0)
+  })
+
+  test('group 안 자식 (1단계) — 찾음', () => {
+    const r = findComponentByRefid(board, 3)
+    expect(r).toBeDefined()
+    expect(r!.component.refid).toBe(3)
+    expect(r!.parentArray).toBe(board.components[1].components)
+    expect(r!.index).toBe(0)
+  })
+
+  test('group 안 group 안 자식 (2단계) — 찾음', () => {
+    const r = findComponentByRefid(board, 5)
+    expect(r).toBeDefined()
+    expect(r!.component.refid).toBe(5)
+    expect(r!.parentArray).toBe(board.components[1].components![1].components)
+  })
+
+  test('group 자체 refid — 찾음', () => {
+    const r = findComponentByRefid(board, 4)
+    expect(r).toBeDefined()
+    expect(r!.component.type).toBe('group')
+  })
+
+  test('없는 refid — undefined', () => {
+    expect(findComponentByRefid(board, 999)).toBeUndefined()
+  })
+
+  test('null/undefined board — undefined', () => {
+    expect(findComponentByRefid(undefined, 1)).toBeUndefined()
+    expect(findComponentByRefid(null as any, 1)).toBeUndefined()
+  })
+
+  test('parent array 참조로 in-place mutation 가능', () => {
+    const local = JSON.parse(JSON.stringify(board))
+    const found = findComponentByRefid(local, 3)!
+    // index 위치를 새 컴포넌트로 교체
+    found.parentArray[found.index] = { type: 'rect', refid: 3, mutated: true } as any
+    // 실제 보드의 group 자식이 바뀌어야
+    expect(local.components[1].components[0].mutated).toBe(true)
+  })
+})