@things-factory/figure-service 10.1.13 → 10.1.15

package/logs/.08636eb59927f12972f6774f5947c8507b3564c2-audit.json

@@ -0,0 +1,15 @@
+{
+    "keep": {
+        "days": true,
+        "amount": 2
+    },
+    "auditLog": "logs/.08636eb59927f12972f6774f5947c8507b3564c2-audit.json",
+    "files": [
+        {
+            "date": 1789397538290,
+            "name": "logs/application-2026-09-14-23.log",
+            "hash": "69c3188e63ed8031b901bd7314adfe3a91152378397ce14edd2f4fafb5a8770e"
+        }
+    ],
+    "hashType": "sha256"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.13",
+  "version": "10.1.15",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -23,14 +23,15 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.16",
+    "@hatiolab/figure-model": "^0.1.17",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.8",
     "@things-factory/auth-base": "^10.1.7",
     "@things-factory/env": "^10.1.3",
     "@things-factory/shell": "^10.1.7",
+    "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "f2cd3d27e32e71cca1d3af5499ef54249b1cc111"
+  "gitHead": "0186eb7ec008781fd9f80b6f59379a91e0908820"
 }

package/server/service/figure/figure-blueprint-query.test.ts

@@ -0,0 +1,178 @@
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let FigureQuery: any
+let testDomain: any
+
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', `${modulePath}.js`)
+
+  if (!existsSync(resolved)) {
+    throw new Error(
+      `figure-service 산출물이 없다: ${resolved}\n` +
+        `이 시험은 tsc 산출물을 든다. 먼저 빌드할 것:\n` +
+        `  yarn workspace @things-factory/figure-service build:server`
+    )
+  }
+
+  return require(resolved)
+}
+
+const sampleSource = JSON.stringify({
+  version: 1,
+  type: 'TEST_BOX',
+  base: { x: 100, y: 100, z: 100 },
+  parts: [
+    {
+      name: 'box-1',
+      primitive: 'cube',
+      transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+      material: { token: 'palette.primary' }
+    }
+  ]
+})
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  FigureQuery = loadCompiled('service/figure/figure-query').FigureQuery
+
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    logging: false
+  })
+
+  await dataSource.initialize()
+  shell.addDataSource('default', dataSource)
+  shell.addDataSource('tx', dataSource)
+})
+
+beforeEach(async () => {
+  await dataSource!.synchronize(true)
+  testDomain = await dataSource!.getRepository(shell.Domain).save({
+    name: 'test-domain',
+    subdomain: 'test-domain'
+  })
+})
+
+afterAll(async () => {
+  if (!dataSource) return
+  shell.removeDataSource('default')
+  shell.removeDataSource('tx')
+  await dataSource.destroy()
+  dataSource = null
+})
+
+function makeContext() {
+  return {
+    state: {
+      domain: testDomain,
+      user: { id: 'user-1' }
+    }
+  } as any
+}
+
+describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)를 위한 청사진 전달', () => {
+  it('존재하지 않는 타입은 null을 반환한다', async () => {
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('NON_EXISTENT', makeContext())
+    expect(result).toBeNull()
+  })
+
+  it('초안(draft) 상태이고 발행 이력이 없는 Figure는 null을 반환한다 (초안 유출 차단)', async () => {
+    const repo = dataSource!.getRepository(Figure)
+    await repo.save({
+      domain: testDomain,
+      type: 'DRAFT_FIGURE',
+      name: '초안 도형',
+      state: 'draft',
+      source: sampleSource,
+      version: 0
+    })
+
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('DRAFT_FIGURE', makeContext())
+    expect(result).toBeNull()
+  })
+
+  it('발행된(released) Figure는 올바르게 컴파일된 Blueprint를 반환한다', async () => {
+    const repo = dataSource!.getRepository(Figure)
+    await repo.save({
+      domain: testDomain,
+      type: 'RELEASED_FIGURE',
+      name: '발행 도형',
+      state: 'released',
+      source: sampleSource,
+      version: 1
+    })
+
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('RELEASED_FIGURE', makeContext())
+    expect(result).not.toBeNull()
+    expect(result.type).toBe('TEST_BOX')
+    expect(result.groups).toBeDefined()
+    expect(result.groups.length).toBe(1)
+    expect(result.groups[0].members[0].name).toBe('box-1')
+  })
+
+  it('현재 저작 중(draft)이더라도 과거 발행판(FigureHistory)이 있으면 최신 발행판을 컴파일해 반환한다', async () => {
+    const repo = dataSource!.getRepository(Figure)
+    const historyRepo = dataSource!.getRepository(FigureHistory)
+
+    const v1Source = sampleSource
+    const v2DraftSource = JSON.stringify({
+      version: 1,
+      type: 'UPDATING_FIGURE',
+      base: { x: 200, y: 200, z: 200 },
+      parts: [
+        {
+          name: 'box-modified',
+          primitive: 'cube',
+          transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 200, y: 200, z: 200 } },
+          material: { token: 'palette.primary' }
+        }
+      ]
+    })
+
+    const figure = await repo.save({
+      domain: testDomain,
+      type: 'UPDATING_FIGURE',
+      name: '수정 중인 도형',
+      state: 'draft',
+      source: v2DraftSource,
+      version: 1
+    })
+
+    // 과거 발행된 v1 이력
+    await historyRepo.save({
+      domain: testDomain,
+      originalId: figure.id,
+      type: 'UPDATING_FIGURE',
+      name: 'v1 발행판',
+      state: 'released',
+      version: 1,
+      source: v1Source
+    })
+
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('UPDATING_FIGURE', makeContext())
+
+    expect(result).not.toBeNull()
+    // 소비처는 수정 중인 초안(box-modified, size 200)이 아니라 기발행된 판(box-1, size 100)을 본다!
+    expect(result.groups[0].members[0].name).toBe('box-1')
+    expect(result.groups[0].members[0].transform.size.x).toBe(100)
+  })
+})

package/server/service/figure/figure-propose.ts

@@ -7,6 +7,7 @@ import {
   PRIMITIVE_KINDS,
   SEGMENT_PRESETS,
   SIZING_RULES,
+  FIGURE_PLACEMENTS,
   compile,
   costOf,
   scoreOf,
@@ -131,13 +132,14 @@ export function rulesPrompt(palette: string[]): string {
     'Answer with a single JSON object and nothing else — no prose, no code fence.',
     '',
     'The JSON is a FigureSource:',
-    '  { type, base: {x,y,z}, detailLevel, parts: [...] }',
+    '  { type, base: {x,y,z}, placement?, detailLevel, parts: [...] }',
     '',
     'A part is:',
     '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
     '    material: {token, preset?}, segments?, shape?, sizing? }',
     '',
     'Hard vocabulary — anything outside these is rejected:',
+    `  placement   ${FIGURE_PLACEMENTS.join(' | ')} (floor: default, ground equipment; ceiling: overhead hoist/OHT; center: airborne/drone/sensor)`,
     `  primitive   ${PRIMITIVE_KINDS.join(' | ')}`,
     `  segments    ${SEGMENT_PRESETS.join(' | ')} (only for cylinder and sphere)`,
     `  material.token  ${palette.join(' | ')}`,

package/server/service/figure/figure-query.ts

@@ -1,5 +1,7 @@
 import { In } from 'typeorm'
 import { Args, Arg, Ctx, Directive, Query, Resolver } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import { compile } from '@hatiolab/figure-model'
 
 import { Domain, getQueryBuilderFromListParams, getRepository, ListParam } from '@things-factory/shell'
 
@@ -126,4 +128,70 @@ export class FigureQuery {
 
     return rows.map(r => r.type).filter(Boolean)
   }
+
+  /**
+   * 소비처(operato-board, operato-twin, things-scene)를 위한 컴파일된 청사진(FigureBlueprint) 질의.
+   *
+   * ## 규칙
+   * 1. 소비처는 초안(draft)을 볼 수 없다 — **반드시 발행된(released) 판만 전달**한다.
+   * 2. 현재 Figure가 released 상태이면 현재 source를 컴파일한다.
+   * 3. 현재 Figure가 저작 중(draft)이더라도 이전에 발행된 이력(FigureHistory)이 있으면
+   *    가장 최근의 released 판본을 컴파일하여 하위 호환성을 유지한다.
+   * 4. 한 번도 발행된 적 없는 초안 자산이거나 존재하지 않는 타입인 경우 null을 반환하여
+   *    미완성 자산이 씬 화면에 유출되는 것을 엄격히 차단한다.
+   * 5. 도메인 상속 시 자식 도메인의 타입이 부모 도메인의 동일 타입을 항상 오버라이드한다.
+   * 6. 소비처(board, twin, things-scene) 사용자에게 저작 권한(figure:query)이 없어도
+   *    발행된 청사진을 열람할 수 있도록 도메인 인증 상태에서 열람을 허용한다.
+   */
+  @Query(returns => GraphQLJSON, {
+    nullable: true,
+    description: 'Compiled FigureBlueprint for external consumers (board, twin, things-scene). Only returns released figures.'
+  })
+  async figureBlueprint(
+    @Arg('type') type: string,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const { domain } = context.state
+
+    // 자식 도메인 자산 우선 탐색 후, 부모 도메인 표준 자산으로 폴백 (오버라이드 보장)
+    let figure = await getRepository(Figure).findOne({
+      where: { domain: { id: domain.id }, type }
+    })
+    if (!figure && domain.parentId) {
+      figure = await getRepository(Figure).findOne({
+        where: { domain: { id: domain.parentId }, type }
+      })
+    }
+
+    if (!figure) {
+      return null
+    }
+
+    let sourceToCompile: string | null = null
+
+    if (figure.state === 'released' && figure.source) {
+      sourceToCompile = figure.source
+    } else if (figure.id) {
+      // 저작 중(draft)인 경우 최근 발행 이력(FigureHistory)을 확인한다
+      const latestReleased = await getRepository(FigureHistory).findOne({
+        where: { domain: { id: figure.domain?.id ?? domain.id }, originalId: figure.id, state: 'released' },
+        order: { version: 'DESC' }
+      })
+      if (latestReleased && latestReleased.source) {
+        sourceToCompile = latestReleased.source
+      }
+    }
+
+    if (!sourceToCompile) {
+      return null
+    }
+
+    try {
+      const parsed = typeof sourceToCompile === 'string' ? JSON.parse(sourceToCompile) : sourceToCompile
+      return compile(parsed)
+    } catch (err) {
+      console.error(`[figureBlueprint] 타입 '${type}' (figure id: ${figure.id}) 청사진 컴파일 실패:`, err)
+      return null
+    }
+  }
 }

package/server/service/figure/figure-source.test.ts

@@ -24,6 +24,7 @@ function part(over: Record<string, unknown> = {}) {
 /** 온전한 정본 하나. */
 function source(over: Record<string, unknown> = {}) {
   return {
+    version: 1,
     type: 'MIXER',
     base: { x: 300, y: 800, z: 300 },
     detailLevel: 'M',
@@ -59,22 +60,21 @@ describe('figure-source — 들어오는 문', () => {
     it('형식을 어기면 던지고, figure-model 의 코드를 그대로 전한다', () => {
       let thrown: FigureSourceError | undefined
       try {
-        // 부품이 없는 정본
         parseSource(json(source({ parts: [] })))
       } catch (e) {
         thrown = e as FigureSourceError
       }
 
       expect(thrown).toBeInstanceOf(FigureSourceError)
-      expect(thrown!.findings.length).toBeGreaterThan(0)
-      // 코드를 서버가 다시 짓지 않는다 — figure-model 의 것을 그대로 쓴다
-      for (const f of thrown!.findings) {
-        expect(typeof f.code).toBe('string')
-        expect(f.code.length).toBeGreaterThan(0)
-      }
+      expect(thrown!.findings[0].code).toBe('missing-parts')
+    })
+
+    it('필수 필드가 빠지면 던진다', () => {
+      // type 없음
+      expect(() => parseSource(json({ base: { x: 1, y: 1, z: 1 }, parts: [part()] }))).toThrow(FigureSourceError)
     })
 
-    it('어디서 났는지(path)를 함께 전한다 — 화면이 그 자리를 가리킬 수 있게', () => {
+    it('오류의 위치(at)를 알린다 — 어느 부품인지 저작 화면이 짚을 수 있다', () => {
       let thrown: FigureSourceError | undefined
       try {
         parseSource(json(source({ parts: [part({ transform: { position: { x: 0, y: 0, z: 0 }, size: { x: -1, y: 1, z: 1 } } })] })))
@@ -94,10 +94,16 @@ describe('figure-source — 들어오는 문', () => {
     })
 
     it('정본을 다시 직렬화하지 않는다 — 들어온 문자열을 그대로 저장한다', () => {
-      // 다시 만들면 키 순서·공백이 바뀌어 「고치지 않았는데 바뀌었다」가 된다
+      // 이미 version이 있는 정본은 키 순서·공백을 그대로 보존한다
       const raw = json(source())
       expect(parseSource(raw).source).toBe(raw)
     })
+
+    it('version이 누락된 구형/외부 정본은 FIGURE_SOURCE_VERSION으로 보정 직렬화한다', () => {
+      const withoutVersion = json({ type: 'MIXER', base: { x: 300, y: 800, z: 300 }, detailLevel: 'M', parts: [part()] })
+      const parsed = JSON.parse(parseSource(withoutVersion).source)
+      expect(parsed.version).toBe(1)
+    })
   })
 
   describe('파생값은 서버가 계산한다', () => {

package/server/service/figure/figure-source.ts

@@ -1,4 +1,4 @@
-import { compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
+import { FIGURE_SOURCE_VERSION, compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
 
 import { FigureFinding } from './figure-type.js'
 
@@ -24,7 +24,7 @@ import { FigureFinding } from './figure-type.js'
  * 목록 화면이 실물과 다른 것을 보여 준다. 정본에서 계산한다.
  */
 export interface ParsedSource {
-  /** 저장할 정본 JSON 문자열. 들어온 것을 그대로 쓴다 — 다시 직렬화하지 않는다. */
+  /** 저장할 정본 JSON 문자열. 들어온 것을 그대로 쓴다 — 단, version 누락 시에만 정규화 직렬화한다. */
   source: string
   /** 목록 화면이 정렬·필터에 쓰는 파생값. */
   derived: { score: number; triangles: number; groups: number }
@@ -65,6 +65,14 @@ export function parseSource(sourceJson: string): ParsedSource {
     )
   }
 
+  // version이 누락된 구형/외부 입력의 경우 FIGURE_SOURCE_VERSION을 부여하여 스키마를 정규화한다.
+  // 이미 version이 있는 정본은 포맷 훼손을 막기 위해 sourceJson 원본을 그대로 보존한다.
+  let normalizedSource = sourceJson
+  if (parsed && typeof parsed === 'object' && (parsed as any).version === undefined) {
+    (parsed as any).version = FIGURE_SOURCE_VERSION
+    normalizedSource = JSON.stringify(parsed, null, 2)
+  }
+
   // 여기까지 왔으면 형식은 맞다. 청사진을 만들어 셈에 쓴다.
   // 청사진 자체는 **저장하지 않는다** — 파생 캐시이므로 소비하는 쪽이 다시 만든다.
   const blueprint = compile(parsed as any)
@@ -72,7 +80,7 @@ export function parseSource(sourceJson: string): ParsedSource {
   const score = scoreOf(blueprint)
 
   return {
-    source: sourceJson,
+    source: normalizedSource,
     derived: {
       score: score.score,
       triangles: cost.triangles,

package/server/service/figure/figure-tools.test.ts

@@ -246,6 +246,27 @@ describe('대화면 문맥에서 대상을 해소한다', () => {
       )
     ).rejects.toThrow(/does not match Figure/)
   })
+
+  it('재현: 기존 도형 편집 중 미저장 초안의 type이 FIGURE여도 현재 도형 초안으로 허용해야 한다', async () => {
+    // DB의 row는 MIXER(또는 OHT)이지만, 캔버스/도크의 초안 type은 일반 'FIGURE'일 수 있음
+    const result = await toolNamed('getFigureSource').builder(
+      {},
+      ctx({ figureId: 'fig-1', palette: ['palette.primary'], draftSource: { ...SOURCE, type: 'FIGURE' } })
+    )
+    expect(result.draft).toBe(true)
+    expect(result.type).toBe('MIXER')
+  })
+
+  it('재현: LLM이 새 미저장 모델의 임시 타입(FIGURE_MTZO5R10)을 figureId로 전달해도 초안을 읽어야 한다', async () => {
+    const tempDraft = { ...SOURCE, type: 'FIGURE_MTZO5R10' }
+    const host = { editorMode: 'new', draftSource: tempDraft, palette: ['palette.primary'] }
+    const result = await toolNamed('getFigureSource').builder(
+      { figureId: 'FIGURE_MTZO5R10' },
+      ctx(host)
+    )
+    expect(result.draft).toBe(true)
+    expect(result.type).toBe('FIGURE_MTZO5R10')
+  })
 })
 
 /*

package/server/service/figure/figure-tools.ts

@@ -93,6 +93,48 @@ async function figureInDomain(figureId: string, domainId: string): Promise<any>
   return found
 }
 
+/**
+ * figureId 또는 hostContext로부터 대상 Figure row(또는 미저장 초안 가상 row)를 해소한다.
+ */
+async function resolveFigureTarget(figureId: string | undefined, domainId: string, host: any): Promise<any> {
+  if (
+    host?.editorMode === 'new' &&
+    host?.draftSource &&
+    (!figureId || figureId === host.draftSource.type || figureId.startsWith('FIGURE'))
+  ) {
+    return unsavedFigure(host)
+  }
+
+  if (figureId) {
+    const { getRepository, Figure } = getDeps()
+    let found = await getRepository(Figure).findOne({
+      where: { id: figureId, domain: { id: domainId } }
+    })
+    if (!found) {
+      found = await getRepository(Figure).findOne({
+        where: { type: figureId, domain: { id: domainId } }
+      })
+    }
+    if (!found) {
+      if (
+        host?.editorMode === 'new' ||
+        (host?.draftSource &&
+          (host.draftSource.type === figureId ||
+            figureId.startsWith('FIGURE') ||
+            !host.figureId ||
+            host.figureId === figureId))
+      ) {
+        const unsaved = unsavedFigure(host)
+        if (unsaved) return unsaved
+      }
+      throw new Error(`figure not found in this tenant: ${figureId}`)
+    }
+    return found
+  }
+
+  return unsavedFigure(host)
+}
+
 /**
  * 모델러가 아직 저장하지 않은 source를 도구가 읽는 유일한 길.
  *
@@ -101,7 +143,8 @@ async function figureInDomain(figureId: string, domainId: string): Promise<any>
  * 프롬프트로 옮기면 비용만 태우고, DB에 있던 Figure와 다른 것을 고친다고 잘못 말할 수 있다.
  */
 function sourceForTool(row: any, host: any): { source: any; draft: boolean } {
-  const draft = host?.figureId === row.id ? host?.draftSource : undefined
+  const isMatch = host?.figureId === row.id || (!row.id && host?.editorMode === 'new') || (!row.id && !host?.figureId)
+  const draft = isMatch ? host?.draftSource : undefined
   if (!draft) {
     return { source: row.source ? JSON.parse(row.source) : null, draft: false }
   }
@@ -120,11 +163,20 @@ function sourceForTool(row: any, host: any): { source: any; draft: boolean } {
   if (checked.errors.length > 0) {
     throw new Error(`the unsaved draft is invalid: ${checked.errors.map((one: any) => one.message).join(' · ')}`)
   }
+
+  let normalizedDraft = draft
   if (draft.type !== row.type) {
-    throw new Error(`the unsaved draft type '${draft.type}' does not match Figure '${row.type}'`)
+    // 템플릿 기본값 'FIGURE', 임시 draftType('FIGURE_...'), 또는 빈 값인 경우
+    // 현재 열려 있는 Figure의 실제 type으로 보정/정규화한다.
+    const isGenericOrTempType = !draft.type || draft.type === 'FIGURE' || draft.type.startsWith('FIGURE_')
+    if (isGenericOrTempType && row.type) {
+      normalizedDraft = { ...draft, type: row.type }
+    } else {
+      throw new Error(`the unsaved draft type '${draft.type}' does not match Figure '${row.type}'`)
+    }
   }
 
-  return { source: draft, draft: true }
+  return { source: normalizedDraft, draft: true }
 }
 
 /**
@@ -134,8 +186,14 @@ function sourceForTool(row: any, host: any): { source: any; draft: boolean } {
  * 도메인에서 Figure를 찾은 뒤, `proposeFigure`가 다시 길이·형식을 정리할 참고 데이터만 건넨다.
  */
 function feedbackForTool(host: any, figureId?: string): unknown[] | undefined {
-  if (!figureId || host?.figureId !== figureId || !Array.isArray(host?.proposalFeedback)) return undefined
-  return host.proposalFeedback.slice(-5)
+  if (!Array.isArray(host?.proposalFeedback)) return undefined
+  if (figureId && host?.figureId === figureId) {
+    return host.proposalFeedback.slice(-5)
+  }
+  if (host?.editorMode === 'new' || !host?.figureId) {
+    return host.proposalFeedback.slice(-5)
+  }
+  return undefined
 }
 
 /**
@@ -163,8 +221,8 @@ function missingFigureTarget() {
 }
 
 function unsavedFigure(host: any): any | undefined {
-  if (host?.editorMode !== 'new' || host?.figureId || !host?.draftSource) return undefined
-  const row = { id: host.figureId, type: host.draftSource.type, name: '', state: 'draft' }
+  if (host?.editorMode !== 'new' || !host?.draftSource) return undefined
+  const row = { id: host.figureId, type: host.draftSource.type || 'FIGURE', name: '', state: 'draft' }
   // Reuse size, shape and vocabulary validation before trusting browser content.
   const current = sourceForTool(row, host)
   return { ...row, source: JSON.stringify(current.source) }
@@ -223,7 +281,7 @@ function figureToolSpecs(): ToolSpec[] {
       builder: async (args: any, ctx: any) => {
         const domainId = requireDomainId(ctx?.state)
         const figureId = figureIdFrom(args, ctx?.host)
-        const row = figureId ? await figureInDomain(figureId, domainId) : unsavedFigure(ctx?.host)
+        const row = await resolveFigureTarget(figureId, domainId, ctx?.host)
         if (!row) return missingFigureTarget()
 
         const current = sourceForTool(row, ctx?.host)
@@ -258,7 +316,7 @@ function figureToolSpecs(): ToolSpec[] {
       builder: async (args: any, ctx: any) => {
         const domainId = requireDomainId(ctx?.state)
         const figureId = figureIdFrom(args, ctx?.host)
-        const row = figureId ? await figureInDomain(figureId, domainId) : unsavedFigure(ctx?.host)
+        const row = await resolveFigureTarget(figureId, domainId, ctx?.host)
         if (!row) return missingFigureTarget()
 
         const current = sourceForTool(row, ctx?.host)
@@ -308,12 +366,9 @@ function figureToolSpecs(): ToolSpec[] {
         let base: unknown
         if (!args?.create && args?.figureId !== null) {
           const open = typeof args?.figureId === 'string' ? args.figureId : ctx?.host?.figureId
-          if (typeof open === 'string' && open.trim()) {
-            const row = await figureInDomain(open.trim(), domainId)
+          const row = await resolveFigureTarget(open ? open.trim() : undefined, domainId, ctx?.host)
+          if (row) {
             base = sourceForTool(row, ctx?.host).source ?? undefined
-          } else {
-            const draft = unsavedFigure(ctx?.host)
-            if (draft) base = JSON.parse(draft.source)
           }
         }
 
@@ -328,13 +383,23 @@ function figureToolSpecs(): ToolSpec[] {
 
         const { proposeFigure } = getDeps()
         const feedback = feedbackForTool(ctx?.host, base ? figureIdFrom(args, ctx?.host) : undefined)
+
+        let hostImage: { data: Buffer; mediaType: any } | undefined
+        const rawImage = ctx?.host?.image || (Array.isArray(ctx?.host?.attachments) ? ctx.host.attachments.find((a: any) => a?.mediaType?.startsWith('image/')) : undefined)
+        if (rawImage?.data) {
+          const rawData = typeof rawImage.data === 'string' ? rawImage.data.replace(/^data:image\/[a-zA-Z]+;base64,/, '') : rawImage.data
+          const buf = typeof rawData === 'string' ? Buffer.from(rawData, 'base64') : Buffer.from(rawData)
+          hostImage = { data: buf, mediaType: rawImage.mediaType || 'image/png' }
+        }
+
         const result = await proposeFigure({
           prompt,
           palette,
           base,
           type: typeof args?.type === 'string' ? args.type : undefined,
           feedback,
-          refine: !!feedback?.length
+          refine: !!feedback?.length,
+          image: hostImage
         })
 
         /*
@@ -351,6 +416,13 @@ function figureToolSpecs(): ToolSpec[] {
           reason:
             `등급 ${result.score.grade} · 삼각형 ${result.cost.triangles} · ` +
             `한 도면 ${result.cost.at.drawCalls}회 · ${result.attempts}번에 만들었다`,
+          choices: [
+            { id: 'save', action: 'save', label: '초안 저장', icon: 'save', primary: true },
+            { id: 'repropose', action: 'prompt', label: '다른 콘셉트 재제안', icon: 'refresh', prompt: '현재 제안과 완전히 다른 스타일과 콘셉트로 새로 제안해줘' },
+            { id: 'slim', action: 'prompt', label: '비율 슬림 조정', icon: 'aspect_ratio', prompt: '전체적인 가로세로 비율을 좀 더 슬림하고 날렵하게 조정해줘' },
+            { id: 'palette', action: 'prompt', label: '색상 테마 변경', icon: 'palette', prompt: '다른 팔레트 색상 테마로 부품 색상을 변경해줘' },
+            { id: 'detail', action: 'prompt', label: '디테일 보강', icon: 'extension', prompt: '주요 디테일과 센서 부품을 좀 더 풍부하게 보강해줘' }
+          ],
           args: {
             baseSource: base ? JSON.stringify(base) : undefined,
             prompt, figureId: base ? figureIdFrom(args, ctx?.host) : undefined,