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

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

@@ -0,0 +1,270 @@
+/**
+ * Stage 2 — Universal Entities → Component Drafts.
+ * 등록된 ImportRule 들을 entity 마다 평가하여 컴포넌트 type 결정.
+ */
+import { getImportRules } from '../registry/index'
+import type { ParseResult, UniversalEntity } from '../types/index'
+import type {
+  ComponentCategory,
+  ComponentDraft,
+  IdStrategy,
+  ImportMatcher,
+  MappingResult,
+  MappingWarning
+} from '../types/registry'
+
+/**
+ * 매핑되지 않은 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 를 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 {
+  const rules = getImportRules(options.scopes)
+    .slice()
+    .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+
+  const components: ComponentDraft[] = []
+  const warnings: MappingWarning[] = []
+  const stats = { total: parsed.entities.length, matched: 0, generic: 0, skipped: 0 }
+
+  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))
+
+    if (!rule) {
+      if (!emitGeneric) {
+        stats.skipped++
+        continue
+      }
+      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
+    }
+
+    const id = resolveId(rule.build.idStrategy ?? 'auto', entity, rule.componentType, usedIds)
+    let draft: ComponentDraft = {
+      category: rule.category ?? 'unknown',
+      type: rule.componentType,
+      id,
+      state: { ...(rule.build.defaultState || {}) },
+      matchedBy: rule,
+      source: entity
+    }
+
+    if (rule.build.transform) {
+      try {
+        draft = rule.build.transform(entity, draft)
+      } catch (e) {
+        warnings.push({
+          level: 'warn',
+          entity,
+          message: `transform 실패 (${rule.componentType}): ${(e as Error).message}`
+        })
+      }
+    }
+
+    components.push(draft)
+    stats.matched++
+  }
+
+  return { components, stats, warnings }
+}
+
+/**
+ * 매칭되지 않은 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>,
+  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,
+    type,
+    id,
+    state: baseState,
+    source: entity
+  }
+}
+
+// ── 매칭 로직 ──────────────────────────────────────────────────────
+
+function matchRule(matcher: ImportMatcher, entity: UniversalEntity): boolean {
+  if (matcher.cad) {
+    const m = matcher.cad
+    let ok = true
+    if (m.blockNamePattern && !m.blockNamePattern.test(entity.attribs.name || '')) ok = false
+    if (m.layer && !matchString(m.layer, entity.attribs.layer || '')) ok = false
+    if (m.entityKinds && !m.entityKinds.includes(entity.kind)) ok = false
+    if (m.textAdjacent) {
+      const adjacentText = (entity.neighbors || [])
+        .filter(r => r.relation === 'labeled-by')
+        .map(r => r.uid)
+      if (!adjacentText.some(t => m.textAdjacent!.test(t))) ok = false
+    }
+    if (ok) return true
+  }
+
+  if (matcher.ifc) {
+    const m = matcher.ifc
+    let ok = true
+    if (m.ifcClass && !matchString(m.ifcClass, entity.attribs.semanticType || '')) ok = false
+    if (ok) return true
+  }
+
+  if (matcher.geometry) {
+    const g = matcher.geometry
+    let ok = true
+    if (g.shape && entity.attribs.shape !== g.shape) ok = false
+    if (g.sizeRange && entity.size) {
+      const area = entity.size.width * entity.size.height
+      if (g.sizeRange.minArea !== undefined && area < g.sizeRange.minArea) ok = false
+      if (g.sizeRange.maxArea !== undefined && area > g.sizeRange.maxArea) ok = false
+    }
+    if (g.aspectRatio && entity.size) {
+      const ratio = entity.size.height === 0 ? 1 : entity.size.width / entity.size.height
+      if (g.aspectRatio.min !== undefined && ratio < g.aspectRatio.min) ok = false
+      if (g.aspectRatio.max !== undefined && ratio > g.aspectRatio.max) ok = false
+    }
+    if (ok) return true
+  }
+
+  if (matcher.image && matcher.image.labels.length > 0) {
+    const label = entity.attribs.vlmLabel
+    if (label && matcher.image.labels.includes(label)) return true
+  }
+
+  return false
+}
+
+function matchString(pattern: string | RegExp, value: string): boolean {
+  if (typeof pattern === 'string') return pattern === value
+  return pattern.test(value)
+}
+
+// ── 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,
+  usedIds: Map<string, number>
+): string | undefined {
+  let id: string | undefined
+
+  if (typeof strategy === 'object' && 'custom' in strategy) {
+    id = strategy.custom(entity)
+  } else {
+    switch (strategy) {
+      case 'fromAttribute':
+        id = entity.attribs.name
+        break
+      case 'fromAdjacentText':
+        id = (entity.neighbors || []).find(r => r.relation === 'labeled-by')?.uid
+        break
+      case 'fromIfcGlobalId':
+        id = entity.attribs.ifcGlobalId
+        break
+      case 'auto':
+      default:
+        // VLM 이 도면 텍스트 라벨 추출했으면 그것. 없으면 ID 미부여.
+        id = entity.attribs.name
+    }
+  }
+
+  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
+}

package/server/service/pipeline/stage3-board.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Stage 3 — assembleBoard 의 컴포넌트 root 외곽 spill 방지 회귀 테스트.
+ *
+ * 검증 포인트:
+ *  - bbox 가 컴포넌트 position+size 보다 작아도 board 가 그것 cover
+ *  - normalizeOrigin + flipY 조합에서 컴포넌트 음수 좌표 회피 (root 위쪽 spill 방지)
+ *  - padding 으로 컴포넌트가 root 가장자리에 붙지 않음
+ *  - 빈 board 는 1000x1000 fallback
+ */
+import { assembleBoard } from './stage3-board'
+import type { ComponentDraft } from '../types/registry'
+import type { BoundingBox, UniversalEntity } from '../types/index'
+
+function entity(uid: string, x: number, y: number, w: number, h: number): UniversalEntity {
+  return {
+    uid,
+    kind: 'shape',
+    position: { x, y },
+    size: { width: w, height: h },
+    bbox: { min: { x, y }, max: { x: x + w, y: y + h } },
+    attribs: {}
+  }
+}
+
+function draft(src: UniversalEntity): ComponentDraft {
+  return {
+    category: 'unknown',
+    type: 'placeholder',
+    id: src.uid,
+    state: {},
+    source: src
+  }
+}
+
+describe('assembleBoard — board 크기 산정', () => {
+  test('컴포넌트 모두 root 안 — left/top 모두 0 이상, right/bottom 모두 board 크기 이하', () => {
+    const drafts = [draft(entity('a', 0, 0, 100, 80)), draft(entity('b', 200, 100, 60, 60))]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 260, y: 160 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: false, scale: 1 })
+
+    for (const c of board.components ?? []) {
+      expect(c.left).toBeGreaterThanOrEqual(0)
+      expect(c.top).toBeGreaterThanOrEqual(0)
+      expect(c.left + c.width).toBeLessThanOrEqual(board.width!)
+      expect(c.top + c.height).toBeLessThanOrEqual(board.height!)
+    }
+  })
+
+  test('bbox 가 컴포넌트 size 보다 작아도 board 가 컴포넌트 fully cover', () => {
+    // 의도적으로 bbox 를 entity 보다 작게 — VLM 이 lossy bbox 줬을 때 시뮬레이션
+    const drafts = [draft(entity('a', 0, 0, 500, 400))]
+    const tightBbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 100, y: 100 } }
+    const board = assembleBoard(drafts, tightBbox, {
+      normalizeOrigin: true,
+      flipY: false,
+      scale: 1
+    })
+
+    const c = board.components![0]
+    expect(c.left + c.width).toBeLessThanOrEqual(board.width!)
+    expect(c.top + c.height).toBeLessThanOrEqual(board.height!)
+    // board 는 컴포넌트 (500x400) + padding 2개 = 580 / 480 이상이어야 함
+    expect(board.width!).toBeGreaterThanOrEqual(500)
+    expect(board.height!).toBeGreaterThanOrEqual(400)
+  })
+
+  test('flipY=true 일 때 모든 컴포넌트 top 이 0 이상 (root 위쪽 spill 방지)', () => {
+    const drafts = [
+      draft(entity('a', 0, 0, 100, 100)),
+      draft(entity('b', 50, 50, 100, 100)),
+      draft(entity('c', 100, 200, 100, 100))
+    ]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 200, y: 300 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: true, scale: 1 })
+
+    for (const c of board.components ?? []) {
+      expect(c.top).toBeGreaterThanOrEqual(0)
+      expect(c.top + c.height).toBeLessThanOrEqual(board.height!)
+    }
+  })
+
+  test('빈 drafts → board 1000x1000 fallback', () => {
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }
+    const board = assembleBoard([], bbox, { normalizeOrigin: true, flipY: true, scale: 1 })
+    // 0 + padding 80 < 1000 fallback
+    expect(board.width).toBe(1000)
+    expect(board.height).toBe(1000)
+    expect(board.components).toEqual([])
+  })
+
+  test('padding 적용 — 컴포넌트 가장자리에 정확히 맞닿지 않고 약간의 여백', () => {
+    const drafts = [draft(entity('a', 0, 0, 100, 80))]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 100, y: 80 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: false, scale: 1 })
+
+    const c = board.components![0]
+    // 가장자리에 정확히 0 이 아니라 padding 만큼 안쪽
+    expect(c.left).toBeGreaterThan(0)
+    expect(c.top).toBeGreaterThan(0)
+    // 우측/하단도 padding 만큼 여유
+    expect(c.left + c.width).toBeLessThan(board.width!)
+    expect(c.top + c.height).toBeLessThan(board.height!)
+  })
+
+  test('normalizeOrigin=true 일 때 음수 entity 좌표도 root 안으로 끌어올림', () => {
+    // entity 가 음수 좌표 (e.g. CAD 의 임의 원점) — bbox 가 정확하면 normalizeOrigin 으로
+    // 0 이상으로 올려야 함.
+    const drafts = [draft(entity('a', -100, -50, 100, 100))]
+    const bbox: BoundingBox = { min: { x: -100, y: -50 }, max: { x: 0, y: 50 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: false, scale: 1 })
+
+    const c = board.components![0]
+    expect(c.left).toBeGreaterThanOrEqual(0)
+    expect(c.top).toBeGreaterThanOrEqual(0)
+  })
+
+  test('scale 적용 — 모든 좌표/크기가 비율대로', () => {
+    const drafts = [draft(entity('a', 10, 20, 100, 80))]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 200, y: 200 } }
+    const board = assembleBoard(drafts, bbox, {
+      normalizeOrigin: true,
+      flipY: false,
+      scale: 0.5
+    })
+
+    const c = board.components![0]
+    // scale=0.5 적용
+    expect(c.width).toBe(50)
+    expect(c.height).toBe(40)
+    // padding 은 scale 무관 (40 unit)
+    expect(c.left).toBe(10 * 0.5 + 40)
+  })
+})