@things-factory/board-import 10.0.0-beta.71 → 10.0.0-beta.73

package/server/service/index.ts

@@ -2,30 +2,40 @@
 import {
   entities as ImportSessionEntities,
   resolverClasses as ImportSessionResolverClasses
-} from './import-session/index.js'
-export * from './import-session/index.js'
+} from './import-session/index'
+export * from './import-session/index'
 
 export const entities = [...ImportSessionEntities]
 export const schema = { resolverClasses: [...ImportSessionResolverClasses] }
 
 // Pipeline (high-level)
-export { importBoard } from './pipeline/index.js'
-export type { ImportOptions, ImportResult } from './pipeline/index.js'
+export { importBoard } from './pipeline/index'
+export type { ImportOptions, ImportResult } from './pipeline/index'
 
 // Stage 별 (low-level)
-export { applyMapping, GENERIC_OBJECT_TYPE } from './pipeline/stage2-mapping.js'
-export { assembleBoard } from './pipeline/stage3-board.js'
-export { applyDataBinding } from './pipeline/stage4-binding.js'
-export type { BoardModel, BoardComponent, AssembleOptions } from './pipeline/stage3-board.js'
-export type { MappingOptions } from './pipeline/stage2-mapping.js'
-export type { BindingOptions } from './pipeline/stage4-binding.js'
+export {
+  applyMapping,
+  GENERIC_OBJECT_TYPE,
+  DEFAULT_CATEGORY_FALLBACK
+} from './pipeline/stage2-mapping'
+export { assembleBoard } from './pipeline/stage3-board'
+export { applyDataBinding } from './pipeline/stage4-binding'
+export type { BoardModel, BoardComponent, AssembleOptions } from './pipeline/stage3-board'
+export type { MappingOptions } from './pipeline/stage2-mapping'
+export type { BindingOptions } from './pipeline/stage4-binding'
 
 // Converters
-export { convertGenericTo, revertToGeneric } from './converters/generic-to.js'
-export type { ConvertOptions } from './converters/generic-to.js'
+export {
+  convertGenericTo,         // deprecated alias — keep for backward-compat
+  convertPlaceholderTo,
+  isPlaceholderType,
+  CORE_PLACEHOLDER_TYPES
+} from './converters/generic-to'
+export type { ConvertOptions } from './converters/generic-to'
 
 // Adapters
-export { DxfAdapter } from './adapters/dxf-adapter.js'
+export { DxfAdapter } from './adapters/dxf-adapter'
+export { ImageAdapter } from './adapters/image-adapter'
 
 // Registry
 export {
@@ -41,7 +51,7 @@ export {
   clearSubscriptionRules,
   clear3DPresets,
   clearAllRegistries
-} from './registry/index.js'
+} from './registry/index'
 
 // Types — Universal Entity
 export type {
@@ -60,7 +70,7 @@ export type {
   AdapterInput,
   FormatAdapter,
   AdapterCapabilities
-} from './types/index.js'
+} from './types/index'
 
 // Types — Registry
 export type {
@@ -76,14 +86,21 @@ export type {
   SubscriptionRule,
   MappingResult,
   MappingWarning
-} from './types/registry.js'
+} from './types/registry'
 
 // AI domain interface (Phase 3+) — provider 추상화는 @things-factory/ai-client-base
 export {
   setAIClient,
   getAIClient,
   DefaultBoardImportAI
-} from './ai/types.js'
+} from './ai/types'
+
+// LLM tool 노출 — board-ai 의 chat 흐름이 자동 dispatch 가능하도록 등록.
+// import 시 module side-effect 로 registerToolCategory 발동. 명시 호출도 가능.
+export {
+  registerBoardImportTools,
+  BOARD_IMPORT_TOOL_CATEGORY
+} from './import-tools'
 export type {
   BoardImportAI,
   AIClient, // deprecated alias for BoardImportAI
@@ -93,4 +110,4 @@ export type {
   LabeledEntity,
   EntityClassification,
   ImageParseOptions
-} from './ai/types.js'
+} from './ai/types'

package/server/service/pipeline/index.ts

@@ -9,12 +9,13 @@
  * const result = await importBoard({ file: buf, filename: 'plant.dxf', scopes: ['fmsim'] })
  * ```
  */
-import { DxfAdapter } from '../adapters/dxf-adapter.js'
-import type { AdapterInput, FormatAdapter, ParseOptions, ParseResult } from '../types/index.js'
-import type { MappingResult } from '../types/registry.js'
-import { applyMapping } from './stage2-mapping.js'
-import { assembleBoard, type AssembleOptions, type BoardModel } from './stage3-board.js'
-import { applyDataBinding } from './stage4-binding.js'
+import { DxfAdapter } from '../adapters/dxf-adapter'
+import { ImageAdapter } from '../adapters/image-adapter'
+import type { AdapterInput, BoundingBox, FormatAdapter, ParseOptions, ParseResult } from '../types/index'
+import type { MappingResult } from '../types/registry'
+import { applyMapping } from './stage2-mapping'
+import { assembleBoard, type AssembleOptions, type BoardModel } from './stage3-board'
+import { applyDataBinding } from './stage4-binding'
 
 export interface ImportOptions {
   file: AdapterInput
@@ -41,34 +42,128 @@ export interface ImportResult {
   parse: ParseResult
 }
 
-const DEFAULT_ADAPTERS: FormatAdapter[] = [new DxfAdapter()]
+/**
+ * 변환 시안 (variant) — AI 가 같은 도면을 다른 관점으로 해석한 결과. 사용자가 review 단계에서
+ * 시각 비교 후 선택. parse 가 multi-variant 응답하면 (현재 ImageAdapter), 각 variant 마다
+ * 독립 mapping + assemble. DXF 같은 single-variant adapter 는 1 boardModel 만.
+ */
+export interface VariantResult {
+  id: string
+  label: string
+  description?: string
+  /** 보드 정체성 — name 자동 추천 기반. */
+  subjectName?: string
+  /** 보드 정체성 — description 자동 추천 기반. */
+  subjectDescription?: string
+  /** AI 의 의도 narrative — review 카드 표시 (transient). */
+  importStrategy?: string
+  boardModel: BoardModel
+  /** mapping 통계 (시안별 — entities 가 다르므로 stats 도 다름). */
+  stats: MappingResult['stats']
+}
+
+export interface ImportVariantsResult {
+  variants: VariantResult[]
+  /** 각 시안의 mapping 결과 묶음. variants[i] 와 같은 인덱스. */
+  mappings: MappingResult[]
+  parse: ParseResult
+}
+
+// Adapter detection 순서가 중요: 정밀 형식 (DXF) 먼저, 폴백 / 비정형 (Image) 나중.
+// detect() 가 filename 확장자 우선이라 충돌은 거의 없지만, 시그니처 모호한 경우 (예:
+// 확장자 없는 binary stream) 도 정밀 형식이 먼저 잡히는 게 안전.
+//
+// import-tools.ts 의 listImportAdapters builder 가 본 배열을 inspect — 외부 export.
+export const DEFAULT_ADAPTERS: FormatAdapter[] = [new DxfAdapter(), new ImageAdapter()]
 
 export async function importBoard(opts: ImportOptions): Promise<ImportResult> {
+  // 단일 변형 — multi-variant adapter 라도 첫 시안만 반환. back-compat.
+  const result = await importBoardVariants(opts)
+  const first = result.variants[0]
+  if (!first) {
+    throw new Error('Import produced no variants.')
+  }
+  return {
+    boardModel: first.boardModel,
+    mapping: result.mappings[0],
+    parse: result.parse
+  }
+}
+
+/**
+ * 다중 시안 import — parse 1번 (비싼 VLM/DXF), 시안별 mapping + assemble.
+ *
+ * AI multi-variant adapter (ImageAdapter) 는 parse.variants 에 N 시안 반환 → 각각 mapping +
+ * assemble. Single-variant adapter (DxfAdapter) 는 parse.variants 미존재 → 단일 시안 1 boardModel.
+ */
+export async function importBoardVariants(opts: ImportOptions): Promise<ImportVariantsResult> {
   const adapter = opts.adapter ?? (await pickAdapter(opts.file, opts.filename))
   if (!adapter) throw new Error('지원되지 않는 도면 형식이거나 어댑터를 식별할 수 없습니다.')
 
   const parsed = await adapter.parse(opts.file, opts.parseOptions)
-  const mapping = applyMapping(parsed, { scopes: opts.scopes })
-
+  const importMeta = {
+    format: adapter.format,
+    sourceBbox: parsed.bbox,
+    units: parsed.units,
+    importedAt: new Date().toISOString()
+  }
   const assembleOptions: AssembleOptions = {
     scopes: opts.scopes,
     normalizeOrigin: opts.normalizeOrigin ?? true,
     flipY: opts.flipY ?? true,
     scale: opts.scale ?? 1,
-    importMeta: {
-      format: adapter.format,
-      sourceBbox: parsed.bbox,
-      units: parsed.units,
-      importedAt: new Date().toISOString()
+    importMeta
+  }
+
+  // multi-variant adapter — parse.variants 가 존재
+  if (Array.isArray(parsed.variants) && parsed.variants.length > 0) {
+    const variants: VariantResult[] = []
+    const mappings: MappingResult[] = []
+    for (const v of parsed.variants) {
+      // 각 시안의 entities 로 mapping (시안별로 다름)
+      const variantParsed: ParseResult = {
+        ...parsed,
+        entities: v.entities,
+        bbox: v.bbox ?? parsed.bbox
+      }
+      const mapping = applyMapping(variantParsed, { scopes: opts.scopes })
+      mappings.push(mapping)
+      let boardModel = assembleBoard(mapping.components, variantParsed.bbox, assembleOptions)
+      if (opts.applyBinding !== false) {
+        boardModel = applyDataBinding(boardModel, { scopes: opts.scopes })
+      }
+      variants.push({
+        id: v.id,
+        label: v.label,
+        description: v.description,
+        subjectName: v.subjectName,
+        subjectDescription: v.subjectDescription,
+        importStrategy: v.importStrategy,
+        boardModel,
+        stats: mapping.stats
+      })
     }
+    return { variants, mappings, parse: parsed }
   }
-  let boardModel = assembleBoard(mapping.components, parsed.bbox, assembleOptions)
 
+  // single-variant adapter (DXF 등) — 단일 boardModel
+  const mapping = applyMapping(parsed, { scopes: opts.scopes })
+  let boardModel = assembleBoard(mapping.components, parsed.bbox, assembleOptions)
   if (opts.applyBinding !== false) {
     boardModel = applyDataBinding(boardModel, { scopes: opts.scopes })
   }
-
-  return { boardModel, mapping, parse: parsed }
+  return {
+    variants: [
+      {
+        id: 'default',
+        label: 'default',
+        boardModel,
+        stats: mapping.stats
+      }
+    ],
+    mappings: [mapping],
+    parse: parsed
+  }
 }
 
 async function pickAdapter(
@@ -81,9 +176,9 @@ async function pickAdapter(
   return undefined
 }
 
-export { applyMapping } from './stage2-mapping.js'
-export { assembleBoard } from './stage3-board.js'
-export { applyDataBinding } from './stage4-binding.js'
-export type { BoardModel, BoardComponent, AssembleOptions } from './stage3-board.js'
-export type { MappingOptions } from './stage2-mapping.js'
-export type { BindingOptions } from './stage4-binding.js'
+export { applyMapping } from './stage2-mapping'
+export { assembleBoard } from './stage3-board'
+export { applyDataBinding } from './stage4-binding'
+export type { BoardModel, BoardComponent, AssembleOptions } from './stage3-board'
+export type { MappingOptions } from './stage2-mapping'
+export type { BindingOptions } from './stage4-binding'

package/server/service/pipeline/stage2-mapping.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Stage 2 매핑의 카테고리 폴백 회귀 테스트.
+ *
+ * - 코어 기본 폴백: 모든 카테고리 → placeholder
+ * - DEFAULT_CATEGORY_FALLBACK 의 매핑 정확성
+ * - categoryFallback override (도메인 패키지의 GenericTransport 등) 가 적용되는지
+ * - rule 매치된 entity 는 폴백을 거치지 않음 (회귀 방지)
+ * - placeholder draft state 가 convertPlaceholderTo 가 strip 하는 키 set 과 일치 (라운드트립)
+ */
+import { applyMapping, DEFAULT_CATEGORY_FALLBACK, GENERIC_OBJECT_TYPE } from './stage2-mapping'
+import { clearImportRules, registerImportRules } from '../registry/index'
+import type { ParseResult, UniversalEntity } from '../types/index'
+
+function makeEntity(uid: string, attribs: Record<string, any> = {}): UniversalEntity {
+  return {
+    uid,
+    kind: 'shape',
+    position: { x: 0, y: 0 },
+    size: { width: 100, height: 100 },
+    bbox: { min: { x: 0, y: 0 }, max: { x: 100, y: 100 } },
+    attribs
+  }
+}
+
+function parsedFrom(entities: UniversalEntity[]): ParseResult {
+  return {
+    entities,
+    metadata: { format: 'test' },
+    bbox: { min: { x: 0, y: 0 }, max: { x: 1000, y: 1000 } }
+  }
+}
+
+beforeEach(() => clearImportRules())
+
+describe('DEFAULT_CATEGORY_FALLBACK', () => {
+  test('모든 카테고리는 placeholder', () => {
+    for (const val of Object.values(DEFAULT_CATEGORY_FALLBACK)) {
+      expect(val).toBe(GENERIC_OBJECT_TYPE)
+    }
+  })
+})
+
+describe('applyMapping — 카테고리 폴백', () => {
+  test('categoryHint 없으면 GenericObject 로 (기존 동작)', () => {
+    const r = applyMapping(parsedFrom([makeEntity('e1', { name: 'whatever' })]))
+    expect(r.stats.matched).toBe(0)
+    expect(r.stats.generic).toBe(1)
+    expect(r.components[0].type).toBe(GENERIC_OBJECT_TYPE)
+    expect(r.components[0].category).toBe('unknown')
+  })
+
+  test('vehicle 힌트 → placeholder', () => {
+    const r = applyMapping(
+      parsedFrom([makeEntity('v1', { name: 'TX001', categoryHint: 'vehicle' })])
+    )
+    expect(r.components[0].type).toBe(GENERIC_OBJECT_TYPE)
+    expect(r.components[0].category).toBe('vehicle')
+  })
+
+  test('path 힌트 → placeholder (2D)', () => {
+    const r = applyMapping(
+      parsedFrom([makeEntity('p1', { layer: 'CONVEYOR', categoryHint: 'path' })])
+    )
+    expect(r.components[0].type).toBe('placeholder')
+    expect(r.components[0].category).toBe('path')
+  })
+
+  test('region 힌트 → placeholder (2D)', () => {
+    const r = applyMapping(parsedFrom([makeEntity('z1', { categoryHint: 'region' })]))
+    expect(r.components[0].type).toBe('placeholder')
+    expect(r.components[0].category).toBe('region')
+  })
+
+  test('equipment 힌트 → placeholder', () => {
+    const r = applyMapping(parsedFrom([makeEntity('m1', { categoryHint: 'equipment' })]))
+    expect(r.components[0].type).toBe(GENERIC_OBJECT_TYPE)
+    expect(r.components[0].category).toBe('equipment')
+  })
+
+  test('알 수 없는 힌트 (string 으로 들어왔지만 매핑 없음) → unknown 폴백', () => {
+    const r = applyMapping(parsedFrom([makeEntity('x1', { categoryHint: 'wat' as any })]))
+    expect(r.components[0].type).toBe(GENERIC_OBJECT_TYPE)
+  })
+})
+
+describe('applyMapping — categoryFallback override', () => {
+  test('vehicle → GenericTransport 로 override', () => {
+    const r = applyMapping(parsedFrom([makeEntity('v1', { categoryHint: 'vehicle' })]), {
+      categoryFallback: { vehicle: 'GenericTransport' }
+    })
+    expect(r.components[0].type).toBe('GenericTransport')
+    expect(r.components[0].category).toBe('vehicle')
+  })
+
+  test('override 안 한 카테고리는 기본값 그대로 (path → placeholder)', () => {
+    const r = applyMapping(parsedFrom([makeEntity('p1', { categoryHint: 'path' })]), {
+      categoryFallback: { vehicle: 'GenericTransport' }
+    })
+    expect(r.components[0].type).toBe('placeholder')
+  })
+})
+
+describe('applyMapping — rule 매치 회귀', () => {
+  test('rule 매치된 entity 는 폴백 미적용 — 카테고리 힌트가 있어도', () => {
+    registerImportRules('test', [
+      {
+        componentType: 'Stocker',
+        category: 'container',
+        match: { cad: { layer: 'STK' } },
+        build: {}
+      }
+    ])
+    const r = applyMapping(
+      parsedFrom([makeEntity('s1', { layer: 'STK', categoryHint: 'vehicle' })])
+    )
+    // 매치 → Stocker. 힌트 무시.
+    expect(r.stats.matched).toBe(1)
+    expect(r.stats.generic).toBe(0)
+    expect(r.components[0].type).toBe('Stocker')
+    expect(r.components[0].category).toBe('container')
+  })
+})
+
+describe('applyMapping — placeholder draft state', () => {
+  test('placeholder draft state 는 label/hint 만 — fillStyle/strokeStyle 미설정', () => {
+    // Shape.drawFill/drawStroke 가 state.fillStyle/strokeStyle 가 없으면 자체 가드로 skip 한다.
+    // renderPlaceholder 가 theme 으로 자체 시각화하므로 state 에 둘 필요 없음. 두면
+    // postrender 가 stale path 에 추가 적용해 보드 전체로 시각 leak 되는 회귀.
+    const r = applyMapping(
+      parsedFrom([
+        makeEntity('p1', { name: 'PATH-A', layer: 'CONV', categoryHint: 'path' })
+      ])
+    )
+    const c = r.components[0]
+    expect(c.state.fillStyle).toBeUndefined()
+    expect(c.state.strokeStyle).toBeUndefined()
+    expect(c.state.strokeDashArray).toBeUndefined()
+    expect(c.state.placeholderLabel).toBe('PATH-A')
+    expect(c.state.placeholderHint).toBe('CONV')
+  })
+
+  test('vehicle placeholder 도 동일 — label/hint 만', () => {
+    const r = applyMapping(
+      parsedFrom([makeEntity('v1', { name: 'TX001', categoryHint: 'vehicle' })])
+    )
+    const c = r.components[0]
+    expect(c.state.fillStyle).toBeUndefined()
+    expect(c.state.strokeStyle).toBeUndefined()
+    expect(c.state.placeholderLabel).toBe('TX001')
+  })
+})
+
+describe('applyMapping — 컴포넌트 ID 부여', () => {
+  test('VLM attribs.name 이 있으면 그것이 ID — 운영 식별자 보존', async () => {
+    const r = applyMapping(
+      parsedFrom([
+        makeEntity('e1', { name: 'STK_001', categoryHint: 'container' }),
+        makeEntity('e2', { name: 'AGV-3', categoryHint: 'vehicle' })
+      ])
+    )
+    expect(r.components[0].id).toBe('STK_001')
+    expect(r.components[1].id).toBe('AGV-3')
+  })
+
+  test('attribs.name 없으면 ID 미부여 (의미 없는 시퀀스 ID 부여 안 함)', async () => {
+    const r = applyMapping(
+      parsedFrom([
+        makeEntity('e1', { categoryHint: 'vehicle' }),
+        makeEntity('e2', { categoryHint: 'vehicle' })
+      ])
+    )
+    expect(r.components[0].id).toBeUndefined()
+    expect(r.components[1].id).toBeUndefined()
+  })
+
+  test('attribs.name 의 특수문자 정규화 — 공백 → 하이픈, 영숫자/하이픈/언더스코어만', async () => {
+    const r = applyMapping(parsedFrom([makeEntity('e1', { name: 'My Stocker #1!' })]))
+    // "My Stocker #1!" → 공백 → '-' → "My-Stocker-#1!" → 특수문자 제거 → "My-Stocker-1"
+    expect(r.components[0].id).toBe('My-Stocker-1')
+  })
+
+  test('중복 attribs.name → 두번째는 ID 미부여 (운영 ID 충돌 회피)', async () => {
+    const r = applyMapping(
+      parsedFrom([
+        makeEntity('e1', { name: 'duplicate' }),
+        makeEntity('e2', { name: 'duplicate' })
+      ])
+    )
+    expect(r.components[0].id).toBe('duplicate')
+    // 두 번째는 의미 있는 ID 부여 불가능 → undefined
+    expect(r.components[1].id).toBeUndefined()
+  })
+})
+
+describe('applyMapping — emitGeneric=false', () => {
+  test('카테고리 힌트 있어도 폴백 자체가 비활성이면 skip', () => {
+    const r = applyMapping(parsedFrom([makeEntity('v1', { categoryHint: 'vehicle' })]), {
+      emitGeneric: false
+    })
+    expect(r.stats.skipped).toBe(1)
+    expect(r.stats.generic).toBe(0)
+    expect(r.components.length).toBe(0)
+  })
+})

package/server/service/pipeline/stage2-mapping.ts

@@ -2,27 +2,54 @@
  * Stage 2 — Universal Entities → Component Drafts.
  * 등록된 ImportRule 들을 entity 마다 평가하여 컴포넌트 type 결정.
  */
-import { getImportRules } from '../registry/index.js'
-import type { ParseResult, UniversalEntity } from '../types/index.js'
+import { getImportRules } from '../registry/index'
+import type { ParseResult, UniversalEntity } from '../types/index'
 import type {
+  ComponentCategory,
   ComponentDraft,
   IdStrategy,
   ImportMatcher,
   MappingResult,
   MappingWarning
-} from '../types/registry.js'
+} from '../types/registry'
 
-/** 매핑되지 않은 entity 가 변환되는 placeholder 도메인 type. */
-export const GENERIC_OBJECT_TYPE = 'GenericObject'
+/**
+ * 매핑되지 않은 entity 가 변환되는 placeholder 도메인 type.
+ *
+ * 반드시 things-scene 의 `Component.register('placeholder', Placeholder)` 에서 쓰는
+ * **kebab-case** 와 일치해야 한다.
+ */
+export const GENERIC_OBJECT_TYPE = 'placeholder'
+
+/**
+ * 카테고리 힌트 → fallback placeholder type 의 코어 기본 매핑.
+ */
+export const DEFAULT_CATEGORY_FALLBACK: Record<ComponentCategory, string> = {
+  vehicle: 'placeholder',
+  equipment: 'placeholder',
+  container: 'placeholder',
+  io: 'placeholder',
+  structure: 'placeholder',
+  path: 'placeholder',
+  region: 'placeholder',
+  marker: 'placeholder',
+  unknown: GENERIC_OBJECT_TYPE
+}
 
 export interface MappingOptions {
   /** 어떤 scope 의 규칙을 사용할지 (생략 시 전부) */
   scopes?: string[]
   /**
-   * 매칭 안 된 entity 를 GenericObject 로 변환할지 여부 (default: true).
+   * 매칭 안 된 entity 를 placeholder 로 변환할지 여부 (default: true).
    * false 면 buffer 에서 제외되고 stats.skipped 로 카운트.
    */
   emitGeneric?: boolean
+  /**
+   * 카테고리 힌트(`entity.attribs.categoryHint`) → fallback placeholder type override.
+   * `DEFAULT_CATEGORY_FALLBACK` 와 머지되어 사용. 도메인 패키지가 자기 추상 type 을
+   * 사용하고 싶을 때 명시 (예: `{ vehicle: 'GenericTransport' }`).
+   */
+  categoryFallback?: Partial<Record<ComponentCategory, string>>
 }
 
 export function applyMapping(parsed: ParseResult, options: MappingOptions = {}): MappingResult {
@@ -36,6 +63,7 @@ export function applyMapping(parsed: ParseResult, options: MappingOptions = {}):
 
   const usedIds = new Map<string, number>()
   const emitGeneric = options.emitGeneric !== false
+  const fallbackTable = { ...DEFAULT_CATEGORY_FALLBACK, ...(options.categoryFallback || {}) }
 
   for (const entity of parsed.entities) {
     const rule = rules.find(r => matchRule(r.match, entity))
@@ -45,7 +73,9 @@ export function applyMapping(parsed: ParseResult, options: MappingOptions = {}):
         stats.skipped++
         continue
       }
-      const draft = makeGenericDraft(entity, usedIds)
+      const hint = (entity.attribs.categoryHint as ComponentCategory | undefined) || 'unknown'
+      const fallbackType = fallbackTable[hint] || fallbackTable.unknown
+      const draft = makeGenericDraft(entity, usedIds, fallbackType, hint)
       components.push(draft)
       stats.generic++
       continue
@@ -81,21 +111,37 @@ export function applyMapping(parsed: ParseResult, options: MappingOptions = {}):
 }
 
 /**
- * 매칭되지 않은 entity 를 GenericObject draft 로 변환.
+ * 매칭되지 않은 entity 를 placeholder draft 로 변환.
  * 좌표·크기·원본 attribs 모두 보존하여 사후 변환 가능하게 한다.
+ *
+ * - `type`: 카테고리 힌트 fallback 매핑으로 결정 (기본 GenericObject).
+ * - `category`: 힌트 그대로 (없으면 'unknown') — 3D Preset 폴백에 사용됨.
+ * - state: placeholderLabel / placeholderHint 만 — 시각 표현은 컴포넌트 자체 render 가 담당.
+ *   things-scene 의 GenericObject 의 renderPlaceholder 가 theme.fill / theme.stroke
+ *   를 자체 적용하므로 state.fillStyle / strokeStyle / strokeDashArray 를 두면 Shape.postrender
+ *   가 그것을 추가로 적용해 시각 leak (보드 전체에 stale path 가 칠해지는 회귀) 가 발생.
  */
-function makeGenericDraft(entity: UniversalEntity, usedIds: Map<string, number>): ComponentDraft {
-  const id = resolveId('auto', entity, GENERIC_OBJECT_TYPE, usedIds)
+function makeGenericDraft(
+  entity: UniversalEntity,
+  usedIds: Map<string, number>,
+  type: string = GENERIC_OBJECT_TYPE,
+  category: ComponentCategory = 'unknown'
+): ComponentDraft {
+  const id = resolveId('auto', entity, type, usedIds)
+  const placeholderLabel =
+    entity.attribs.name || entity.attribs.layer || entity.attribs.text || ''
+  const placeholderHint = entity.attribs.layer || entity.attribs.name
+
+  const baseState: Record<string, any> = {
+    placeholderLabel,
+    ...(placeholderHint ? { placeholderHint } : {})
+  }
+
   return {
-    category: 'unknown',
-    type: GENERIC_OBJECT_TYPE,
+    category,
+    type,
     id,
-    state: {
-      strokeStyle: '#888888',
-      strokeDashArray: '4 4',
-      fillStyle: 'rgba(128,128,128,0.15)',
-      label: entity.attribs.name || entity.attribs.layer || entity.attribs.text || ''
-    },
+    state: baseState,
     source: entity
   }
 }
@@ -157,12 +203,27 @@ function matchString(pattern: string | RegExp, value: string): boolean {
 
 // ── ID 부여 전략 ──────────────────────────────────────────────────
 
+/**
+ * 컴포넌트 ID 부여.
+ *
+ * **정책: 의미 있는 ID 만 부여한다.** 의미 없는 시퀀스 (`generic-object-1`, `STK_002`) 는
+ * 사용자/시스템 혼동만 야기하고 운영 가치가 없다 — 차라리 미부여 (undefined) 가 낫다.
+ *
+ *   - **fromAttribute / fromAdjacentText / fromIfcGlobalId**: 명시 strategy — 해당 출처
+ *     사용. 없으면 undefined.
+ *   - **auto / default**: VLM 이 도면 텍스트 라벨을 추출해 attribs.name 에 채웠으면 그것 사용.
+ *     없으면 undefined.
+ *   - **custom**: 호출자 정의. 빈 결과면 undefined.
+ *
+ * 중복 ID 는 두 번째부터 undefined (이미 운영 ID 로 정확히 일치하는 게 있으니 새로 부여하면
+ * 잘못된 동일성 매칭 야기).
+ */
 function resolveId(
   strategy: IdStrategy,
   entity: UniversalEntity,
-  type: string,
+  _type: string,
   usedIds: Map<string, number>
-): string {
+): string | undefined {
   let id: string | undefined
 
   if (typeof strategy === 'object' && 'custom' in strategy) {
@@ -180,16 +241,30 @@ function resolveId(
         break
       case 'auto':
       default:
-        id = undefined
+        // VLM 이 도면 텍스트 라벨 추출했으면 그것. 없으면 ID 미부여.
+        id = entity.attribs.name
     }
   }
 
-  if (!id) {
-    const seq = (usedIds.get(type) ?? 0) + 1
-    usedIds.set(type, seq)
-    id = `${type.toUpperCase()}_${String(seq).padStart(3, '0')}`
-  } else {
-    usedIds.set(id, (usedIds.get(id) ?? 0) + 1)
+  if (id) id = sanitizeId(id)
+
+  // 중복 회피 — 이미 사용된 ID 면 undefined (의미 없는 자동 변형 부여 X)
+  if (id && usedIds.has(id)) {
+    return undefined
   }
+  if (id) usedIds.set(id, 1)
   return id
 }
+
+/**
+ * ID 정규화 — 알파넘 + 하이픈/언더스코어 만 허용. 공백 → 하이픈, 다른 특수문자 제거.
+ * 빈 결과면 undefined.
+ */
+function sanitizeId(raw: string): string | undefined {
+  const cleaned = raw
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9_\-]/g, '')
+    .slice(0, 64)
+  return cleaned || undefined
+}