@things-factory/figure-ui 10.1.3

package/client/modeller/figure-view.ts

@@ -0,0 +1,79 @@
+/**
+ * 저작 화면의 **보기 설정**.
+ *
+ * ## 저장되지 않는다
+ *
+ * 이것은 자산이 아니라 **작업대**다. 조명을 밝게 하고 바닥을 켠 것은 그 사람이 지금
+ * 보기 편한 상태일 뿐, 그 자산의 성질이 아니다. 그래서 `FigureSource` 에 안 들어간다 —
+ * `toFigureSource` 는 판에서 `width` · `height` · `depth` 와 몇 가지만 집어 가고 나머지는
+ * 버린다.
+ *
+ * 다른 사람이 같은 자산을 열면 자기 설정으로 본다. 그것이 맞다.
+ *
+ * ## 씬이 아는 이름을 그대로 쓴다
+ *
+ * 여기 이름은 전부 `model-layer` 의 상태 이름이다. 옮겨 적는 표를 두지 않는다 — 표를
+ * 두면 씬이 새 설정을 받아도 이쪽이 모른다.
+ *
+ * 값이 바뀌면 씬이 스스로 반영한다(`three-capability` 의 `onchange`). 다만 `grid` 는
+ * 한동안 3D 를 세울 때만 읽혔다 — things-scene 10.1.5 에서 고쳤다.
+ */
+export interface ViewSettings {
+  /** 좌표 바탕(축 가이드). 원점과 눈금을 보인다. */
+  grid: boolean
+  /** 축 이름표(X · Y · Z). 눈금만 두고 글자를 끌 수 있다. */
+  gridLabels: boolean
+  /** 판의 바닥면. 좌표 바탕과 겹치므로 기본은 끈다. */
+  floor: boolean
+  /** Environment — 반사(IBL). 금속 재질이 무엇을 비출지 정한다. */
+  environment: EnvironmentName
+  /** Sky Color — 배경색. */
+  skyColor: string
+  /** Key Light Intensity. */
+  dirLightIntensity: number
+  /** Key Light — Follow Camera. 끄면 그림자 방향이 고정된다. */
+  dirLightFollowCamera: boolean
+  /** Key Light — Cast Shadow. */
+  dirShadowEnabled: boolean
+  /** Hemisphere Light Intensity — 그늘진 면을 들어올린다. */
+  hemiIntensity: number
+}
+
+/**
+ * 환경 프리셋 — **`scene-manager` 의 `SkyPreset` 과 같은 여덟이다.**
+ *
+ * 한동안 다섯만 적었다. 씬은 여덟을 다 받는데 이쪽이 셋을 몰라서 고를 수 없었다.
+ * operato-board 의 3D 씬 속성 패널도 같은 여덟을 보인다.
+ */
+export const ENVIRONMENTS = [
+  'studio',
+  'warehouse',
+  'factory',
+  'office',
+  'home',
+  'sunny',
+  'cloudy',
+  'rainy'
+] as const
+export type EnvironmentName = (typeof ENVIRONMENTS)[number]
+
+/** 배경색 기본값. 회색이라 부품 색이 제 색으로 보인다. */
+export const WORKBENCH = '#7c7c7c'
+
+/**
+ * 처음 값.
+ *
+ * **지금 저작 화면이 실제로 쓰던 값 그대로다.** 설정을 만들면서 화면이 달라지면
+ * 무엇이 설정 때문이고 무엇이 원래 그랬는지 갈리지 않는다.
+ */
+export const DEFAULT_VIEW: ViewSettings = {
+  grid: true,
+  gridLabels: true,
+  floor: false,
+  environment: 'studio',
+  skyColor: WORKBENCH,
+  dirLightIntensity: 2.0,
+  dirLightFollowCamera: true,
+  dirShadowEnabled: true,
+  hemiIntensity: 4.0
+}

package/client/modeller/maturity.ts

@@ -0,0 +1,288 @@
+import { LIMITS, PART_LIMIT, SEGMENT_PRESETS, materialKeyOf } from '@hatiolab/figure-model'
+import type { DetailLevel, FigureCost, FigureScore, FigureSource } from '@hatiolab/figure-model'
+
+import { capacityFrom } from './scene-budget.js'
+
+/**
+ * 성숙도 — 이 형상이 얼마나 잘 만들어졌나.
+ *
+ * ## 축이 여럿이어야 하는 이유
+ *
+ * 「몇 개까지 편한가」 하나로는 좋은 형상과 나쁜 형상이 구분되지 않는다. 부품 하나짜리
+ * 상자도 그 축에서는 만점이다. 잘 만들어졌다는 것은 **여러 물음에 각각 답하는 것**이고,
+ * 그것을 한 숫자로 뭉개면 무엇을 고쳐야 할지 알 수 없다.
+ *
+ * ## 축을 지어내지 않았다
+ *
+ * `docs/design/component-authoring-tool.md` 의 「인정받을 수 있는 최소 품질 — 기준선」
+ * 다섯이 이미 있다. 그것을 잴 수 있는 형태로 옮기고, 이미 셈이 있는 것(규모·되쓰기)을
+ * 더했다.
+ *
+ *   기준선 1 실루엣으로 알아본다      → readable   **아직 측정하지 못한다**
+ *   기준선 2 상태가 색으로 구분된다    → reactive   **아직 측정하지 못한다**
+ *   기준선 3 다른 자산과 한 세트로 보인다 → consistency
+ *   기준선 4 확대해도 안 깨진다        → consistency (텍스처 0)
+ *   기준선 5 라벨이 읽힌다            → reactive
+ *
+ * ## 못 재는 축을 지어내지 않는다
+ *
+ * 두 축은 지금 잴 수 없다. 하나는 그리기가 필요하고(실루엣), 하나는 형식에 길이
+ * 없다(상태 바인딩 — figure-model#2). **그것을 0점으로도 만점으로도 두지 않는다.**
+ * 「아직 측정하지 못한다」고 알리고 이유를 붙인다. 측정하지 못한 것을 점수로 만들면 그 점수가 거짓말을
+ * 한다.
+ *
+ * ## 이 파일은 임시다
+ *
+ * 셈은 figure-model 것이어야 한다 — 거기가 `costOf` · `scoreOf` 를 갖고 있다.
+ * 형식 쪽 결정(#2 · #4)이 서면 이 파일을 지우고 그쪽으로 옮긴다.
+ */
+
+export type AxisKey = 'scale' | 'consistency' | 'reuse' | 'detail' | 'reactive' | 'readable'
+
+export interface MaturityAxis {
+  key: AxisKey
+  /** 0~1. 못 재면 없다. */
+  ratio?: number
+  /** 지금 이 축의 값. 그대로 보여 준다. */
+  reading?: string
+  /** 값이 숫자가 아니라 말일 때의 문구 키. `reading` 과 함께 쓰지 않는다. */
+  readingKey?: string
+  /** 왜 이 값인가. */
+  because?: string
+  /** 못 재면 그 이유. 있으면 `ratio` 가 없다. */
+  blocked?: string
+}
+
+/** 한 도면에 이만큼 놓는 것을 본다. 설계 문서 §4.15 의 「자산 500 개」. */
+const BOARD_ASSETS = 500
+
+/**
+ * 여섯 축을 측정한다.
+ *
+ * 한 숫자로 합치지 않는다. 합치면 「무엇을 고쳐야 하나」가 사라진다 — 그것이 이
+ * 리포트의 존재 이유다.
+ */
+export function maturityOf(source: FigureSource, cost: FigureCost, score: FigureScore): MaturityAxis[] {
+  return [scale(cost), consistency(source, cost), reuse(score), detail(source, cost), reactive(source), readable(source, cost)]
+}
+
+/** 규모 — 한 도면에 얼마나 놓을 수 있나. */
+function scale(cost: FigureCost): MaturityAxis {
+  const capacity = capacityFrom(cost.groups, cost.triangles)
+  if (!capacity) {
+    return { key: 'scale', blocked: 'text.maturity-blocked-no-parts' }
+  }
+
+  return {
+    key: 'scale',
+    // 한 도면 목표치(500)를 채우면 1 이다. 그보다 많이 놓을 수 있어도 1 을 넘기지 않는다 —
+    // 목표를 넘긴 여유는 다른 축을 고치는 데 쓰는 편이 낫다.
+    ratio: Math.min(1, capacity.instances / BOARD_ASSETS),
+    reading: String(capacity.instances),
+    because: 'text.maturity-scale-because'
+  }
+}
+
+/**
+ * 한 세트로 보이나. 기준선 3·4.
+ *
+ * 셋을 본다. 팔레트 밖 표면이 없나(텍스처 0 — 확대해도 안 깨진다), 분할 수가
+ * 프리셋인가, 투명 재질을 아끼나. 셋 다 이미 형식이 위반으로 세고 있는 것들이다.
+ */
+function consistency(source: FigureSource, cost: FigureCost): MaturityAxis {
+  const offPreset = source.parts.filter(
+    part => part.segments !== undefined && !SEGMENT_PRESETS.includes(part.segments)
+  ).length
+
+  const faults =
+    (cost.surfaceTextures > 0 ? 1 : 0) +
+    (offPreset > 0 ? 1 : 0) +
+    (cost.distinctMaterials > LIMITS.materialGroups ? 1 : 0)
+
+  return {
+    key: 'consistency',
+    ratio: (3 - faults) / 3,
+    readingKey: faults === 0 ? 'text.maturity-consistency-clean' : 'text.maturity-consistency-faults',
+    because: 'text.maturity-consistency-because'
+  }
+}
+
+/**
+ * 되쓰나 — 같은 형상을 몇 번 다시 쓰나.
+ *
+ * `scoreOf` 가 이미 재고 있으나 **점수에는 넣지 않는다**고 선언돼 있다(한도가 아니라
+ * 덤이다). 축으로는 뜻이 있다 — 되쓰기가 많은 형상이 잘 짜인 형상이다. 다만 부품마다
+ * 형상이 달라도 잘못이 아니므로 **낮다고 나무라지 않는다.**
+ */
+function reuse(score: FigureScore): MaturityAxis {
+  const { distinct, parts, saved } = score.reuse
+  if (parts === 0) {
+    return { key: 'reuse', blocked: 'text.maturity-blocked-no-parts' }
+  }
+
+  return {
+    key: 'reuse',
+    // ratio 가 낮을수록 많이 되쓴다 — 뒤집어서 높은 쪽이 좋게 만든다
+    ratio: 1 - distinct / parts,
+    reading: String(saved),
+    because: 'text.maturity-reuse-because'
+  }
+}
+
+/**
+ * 정밀도 — 밝힌 등급에 걸맞게 만들어졌나.
+ *
+ * 등급(S·M·L)은 「어느 거리에서 읽히도록 만든 것인가」를 밝히는 것이다. 그런데 등급만
+ * 올려 놓고 부품 셋으로 끝내면 그 약속을 안 지킨 것이다. **한도를 얼마나 썼나**로 본다.
+ *
+ * 이 축은 「많이 쓸수록 좋다」가 아니다. 등급에 맞게 채웠나를 본다 — 그래서 넘치면
+ * 다시 내려간다.
+ */
+function detail(source: FigureSource, cost: FigureCost): MaturityAxis {
+  const level = (source.detailLevel ?? 'M') as DetailLevel
+  const limit = PART_LIMIT[level]
+  const used = cost.parts / limit
+
+  return {
+    key: 'detail',
+    // 절반쯤 쓴 것을 제일 좋게 본다. 텅 비어도, 넘쳐도 등급과 안 맞는다.
+    ratio: used > 1 ? Math.max(0, 2 - used) : Math.min(1, used * 2),
+    reading: `${cost.parts} / ${limit}`,
+    because: 'text.maturity-detail-because'
+  }
+}
+
+/**
+ * 살아 있나 — 기준선 2·5. 상태가 색으로 구분되고 라벨이 읽히나.
+ *
+ * **지금 잴 수 없다.** 형식에 `slot` 이 있지만 그리는 쪽이 읽지 않고(선언 한 줄이
+ * 전부다), 상태를 부품에 잇는 길 자체가 아직 정해지지 않았다(figure-model#2).
+ *
+ * 0 점으로 두지 않는다. 0 은 「이 형상이 상태를 안 보여 준다」는 뜻이 되는데, 사실은
+ * **아무 형상도 보여 줄 수 없는 상태**다. 축 자체가 아직 없는 것이다.
+ */
+function reactive(source: FigureSource): MaturityAxis {
+  return { key: 'reactive', blocked: 'text.maturity-blocked-no-binding' }
+}
+
+/**
+ * 식별성 — 기준선 1. 위에서 볼 때 무엇인지 알아보나.
+ *
+ * ## 시점 엔트로피를 빌린다
+ *
+ * 「어느 시점에서 얼마나 알아볼 수 있나」는 이미 연구된 물음이다. Vázquez 등의
+ * **viewpoint entropy** 는 시점에서 보이는 각 면의 투영 면적 비율로 섀넌 엔트로피를
+ * 낸다. 모든 면이 같은 면적으로 보일 때가 최대이고, 한 면이 화면을 다 덮으면 0 이다.
+ *
+ *     H = -Σ (Ai / At) · log(Ai / At)
+ *
+ * ## 다만 면으로 세지 않는다
+ *
+ * 그 문헌이 스스로 밝히는 한계가 **폴리곤 분할에 좌우된다**는 것이다 — 같은 형상도
+ * 잘게 쪼개면 엔트로피가 올라간다. 우리에게는 그 한계가 치명적이다. 분할 수를 8 에서
+ * 16 으로 올리는 것은 형상을 알아보기 쉽게 만드는 일이 아닌데, 면으로 세면 점수가
+ * 오른다.
+ *
+ * 그래서 **면이 아니라 색 구역으로 센다.** 눈이 구별하는 것은 삼각형이 아니라 색이
+ * 다른 덩어리다. 같은 토큰을 쓰는 부품 둘이 붙어 있으면 눈에는 한 덩어리다.
+ * 이렇게 하면 분할 수에 좌우되지 않으면서 원래 물음에 답한다.
+ *
+ * ## 기준값도 지어내지 않는다
+ *
+ * 정규화 분모를 `log(재질 group 한도 + 1)` 로 둔다. 이 형식이 허용하는 재질 group 이
+ * 셋이고 거기에 배경을 더하면 넷이므로, **이 형식에서 도달 가능한 최대**가 곧
+ * 기준이다. 임의로 고른 수가 아니다.
+ *
+ * ## 그리지 않고 셈으로 낸다
+ *
+ * 저작 중에 매번 렌더링할 수 없다. 대신 부품의 발자국(x·y·너비·높이)을 위에서
+ * 겹쳐 본다 — 위에 있는 것이 아래를 가린다. 축에 정렬된 상자이므로 격자에 찍어
+ * 세면 된다.
+ *
+ * 이 근사가 실제 렌더링과 맞는지는 하네스가 따로 확인한다
+ * (`test/browser/check-silhouette.mjs`).
+ */
+function readable(source: FigureSource, cost: FigureCost): MaturityAxis {
+  const regions = topViewRegions(source)
+  if (regions.total === 0) {
+    return { key: 'readable', blocked: 'text.maturity-blocked-no-parts' }
+  }
+
+  // 배경도 한 구역으로 센다 — 발자국을 얼마나 채우나가 식별성의 일부다.
+  // Vázquez 의 「열린 장면」 형태와 같다(최대가 log(면 수 + 1)).
+  const shares = [...regions.byMaterial.values(), regions.background]
+    .map(area => area / regions.footprint)
+    .filter(share => share > 0)
+
+  const entropy = -shares.reduce((sum, p) => sum + p * Math.log(p), 0)
+  const ceiling = Math.log(LIMITS.materialGroups + 1)
+
+  return {
+    key: 'readable',
+    ratio: Math.min(1, entropy / ceiling),
+    reading: `${regions.byMaterial.size}`,
+    because: 'text.maturity-readable-because'
+  }
+}
+
+/**
+ * 위에서 내려다볼 때 어느 재질이 얼마나 보이나.
+ *
+ * 부품 발자국을 격자에 찍되 **높은 것이 이긴다.** 축에 정렬된 상자만 다루므로
+ * 이것으로 충분하다 — 회전한 부품은 발자국을 크게 잡아 보수적으로 본다.
+ */
+function topViewRegions(source: FigureSource) {
+  const GRID = 64
+  const cells = new Array<string | null>(GRID * GRID).fill(null)
+  const height = new Float32Array(GRID * GRID)
+
+  // 톱뷰의 두 축은 x 와 z 다. y 는 높이라 위에서 보면 보이지 않는다.
+  // 원점은 기준 상자의 중심이므로 격자의 가운데가 0 이다.
+  const sx = GRID / source.base.x
+  const sz = GRID / source.base.z
+
+  for (const part of source.parts) {
+    const { position, size } = part.transform
+    const top = position.y + size.y / 2
+    const key = materialKeyOf(part)
+
+    const x0 = Math.max(0, Math.floor((position.x - size.x / 2 + source.base.x / 2) * sx))
+    const x1 = Math.min(GRID, Math.ceil((position.x + size.x / 2 + source.base.x / 2) * sx))
+    const y0 = Math.max(0, Math.floor((position.z - size.z / 2 + source.base.z / 2) * sz))
+    const y1 = Math.min(GRID, Math.ceil((position.z + size.z / 2 + source.base.z / 2) * sz))
+
+    for (let y = y0; y < y1; y++) {
+      for (let x = x0; x < x1; x++) {
+        // 원기둥·구는 발자국 상자를 다 채우지 않는다. 모서리를 깎아 근사한다.
+        if (ROUND_FOOTPRINT.includes(part.primitive)) {
+          const cxp = (x + 0.5 - (x0 + x1) / 2) / ((x1 - x0) / 2 || 1)
+          const cyp = (y + 0.5 - (y0 + y1) / 2) / ((y1 - y0) / 2 || 1)
+          if (cxp * cxp + cyp * cyp > 1) continue
+        }
+        const i = y * GRID + x
+        if (cells[i] === null || top > height[i]) {
+          cells[i] = key
+          height[i] = top
+        }
+      }
+    }
+  }
+
+  const byMaterial = new Map<string, number>()
+  let covered = 0
+  for (const key of cells) {
+    if (key === null) continue
+    covered++
+    byMaterial.set(key, (byMaterial.get(key) ?? 0) + 1)
+  }
+
+  return {
+    byMaterial,
+    total: covered,
+    background: GRID * GRID - covered,
+    footprint: GRID * GRID
+  }
+}
+
+/** 위에서 보면 발자국 상자를 다 채우지 않는 도형. */
+const ROUND_FOOTPRINT: string[] = ['cylinder', 'sphere']

package/client/modeller/part-edits.test.ts

@@ -0,0 +1,252 @@
+import {
+  addPart,
+  alignPartToEnd,
+  alignPartToStart,
+  canMirror,
+  centerPart,
+  duplicatePart,
+  gridStep,
+  mirrorPart,
+  movePart,
+  newPart,
+  niceStep,
+  partLimit,
+  removePart,
+  snapPart,
+  updatePart
+} from './part-edits'
+import { toFigureSource } from './figure-source'
+import type { BoardModel, PartModel } from './figure-source'
+import { validate } from '@hatiolab/figure-model'
+
+/**
+ * 씬 모델 용어로 부품을 편집하는 규칙.
+ *
+ * 편집 중의 기준 데이터는 씬 모델이므로 편집도 씬의 용어로 한다. 그런데 저장되는 것은
+ * FigureSource 다. 그래서 두 가지를 확인한다 — **씬 용어에서 규칙이 맞는지**, 그리고
+ * **변환했을 때 검증을 통과하는지**. 앞의 것만 보면 화면에서는 멀쩡한데 저장이 거부되는
+ * 상황이 생긴다.
+ */
+
+/** 보드 3000 x 2000 x 800 — 세 축이 모두 달라야 축을 바꿔 써도 테스트가 잡아낸다. */
+const BOARD: BoardModel = {
+  width: 3000,
+  height: 2000,
+  depth: 800,
+  figureType: 'AGV',
+  detailLevel: 'L'
+}
+
+const DECK: PartModel = {
+  type: 'figure-part',
+  name: 'deck',
+  primitive: 'cube',
+  left: 1200,
+  top: 900,
+  width: 800,
+  height: 600,
+  zPos: 500,
+  depth: 200,
+  token: 'palette.primary'
+}
+
+describe('부품 생성', () => {
+  it('보드의 3분의 1 크기로 생성된다 — 추가하자마자 보여야 한다', () => {
+    const part = newPart(BOARD, [], 'cube')
+
+    expect(part.width).toBe(1000)
+    expect(part.height).toBe(667)
+    expect(part.depth).toBe(267)
+  })
+
+  it('바닥 가운데에 놓인다', () => {
+    const part = newPart(BOARD, [], 'cube')
+
+    expect(part.zPos).toBe(0)
+    // 위치도 크기도 정수로 맞추므로 0.5 까지는 어긋난다
+    expect(Math.abs(part.left + part.width / 2 - BOARD.width / 2)).toBeLessThanOrEqual(0.5)
+    expect(Math.abs(part.top + part.height / 2 - BOARD.height / 2)).toBeLessThanOrEqual(0.5)
+  })
+
+  it('보드에 그대로 놓을 수 있는 씬 컴포넌트 타입을 갖는다', () => {
+    expect(newPart(BOARD, [], 'cube').type).toBe('figure-part')
+  })
+
+  it('이름이 중복되지 않는다 — 저장되는 식별자다', () => {
+    let parts: PartModel[] = []
+    for (let i = 0; i < 3; i++) parts = addPart(BOARD, parts, 'cube')
+
+    expect(parts.map(part => part.name)).toEqual(['cube', 'cube-2', 'cube-3'])
+  })
+
+  it('팔레트 토큰을 기존 부품에서 물려받는다 — 토큰이 늘면 재질 그룹이 하나씩 는다', () => {
+    const parts = addPart(BOARD, [{ ...DECK, token: 'palette.dark' }], 'sphere')
+    expect(parts[1].token).toBe('palette.dark')
+  })
+
+  it('곡면 도형은 분할 수를 갖고 생성된다', () => {
+    expect(newPart(BOARD, [], 'cylinder').segments).toBe(12)
+    expect(newPart(BOARD, [], 'cube').segments).toBeUndefined()
+  })
+
+  it('polygon 은 삼각형으로 생성된다 — 점이 3개보다 적으면 검증에서 막힌다', () => {
+    expect(newPart(BOARD, [], 'polygon').path).toHaveLength(3)
+  })
+
+  /*
+    화면에서 멀쩡해 보여도 저장이 거부되면 사용자는 이유를 알 수 없다. 새로 만든 부품은
+    손대지 않은 상태로도 검증을 통과해야 한다.
+  */
+  it('새로 만든 부품만으로도 검증을 통과한다', () => {
+    for (const kind of ['cube', 'wall', 'cylinder', 'sphere', 'rect', 'polygon'] as const) {
+      const source = toFigureSource(BOARD, [newPart(BOARD, [], kind)])
+      expect(validate(source).errors).toEqual([])
+    }
+  })
+})
+
+describe('목록 편집', () => {
+  const PARTS = [DECK, { ...DECK, name: 'mast' }, { ...DECK, name: 'wheel' }]
+
+  it('삭제한 것만 빠진다', () => {
+    expect(removePart(PARTS, 1).map(part => part.name)).toEqual(['deck', 'wheel'])
+  })
+
+  it('복제본이 바로 뒤에 오고 이름이 새로 붙는다', () => {
+    const next = duplicatePart(PARTS, 0)
+    expect(next.map(part => part.name)).toEqual(['deck', 'deck-copy', 'mast', 'wheel'])
+  })
+
+  it('복제본이 원본과 객체를 공유하지 않는다 — 수정하면 따로 움직여야 한다', () => {
+    const next = duplicatePart([{ ...DECK, path: [{ x: 0, y: 0 }] }], 0)
+    next[1].path![0].x = 99
+
+    expect(next[0].path![0].x).toBe(0)
+  })
+
+  it('순서를 바꾼다', () => {
+    expect(movePart(PARTS, 2, 0).map(part => part.name)).toEqual(['wheel', 'deck', 'mast'])
+  })
+
+  it('범위를 벗어나면 그대로 둔다', () => {
+    expect(movePart(PARTS, 0, -1)).toBe(PARTS)
+    expect(movePart(PARTS, 2, 3)).toBe(PARTS)
+  })
+
+  it('원본을 수정하지 않는다', () => {
+    const before = JSON.stringify(PARTS)
+    removePart(PARTS, 0)
+    duplicatePart(PARTS, 0)
+    updatePart(PARTS, 0, { ...DECK, left: 0 })
+
+    expect(JSON.stringify(PARTS)).toBe(before)
+  })
+
+  it('부품 수 한도는 디테일 등급이 결정한다', () => {
+    expect(partLimit({ ...BOARD, detailLevel: 'S' })).toBeLessThan(partLimit({ ...BOARD, detailLevel: 'L' }))
+  })
+})
+
+/*
+  정밀 배치 도구.
+
+  씬 모델은 원점이 **모서리**다(left·top 이 0 에서 시작하고 zPos 는 밑면이다).
+  FigureSource 는 원점이 중심이다. 이전 구현은 FigureSource 기준이라 '가운데로'가 곧
+  '0 으로'였는데, 씬 용어에서는 그렇지 않다 — 이 절이 그 차이를 확인한다.
+*/
+describe('정밀 배치 도구', () => {
+  it('가운데로 옮기면 변환했을 때 원점에 온다', () => {
+    const moved = centerPart(BOARD, [{ ...DECK, left: 0 }], 0, 'x')
+
+    expect(moved[0].left).toBe(1100)
+    expect(toFigureSource(BOARD, moved).parts[0].transform.position.x).toBe(0)
+  })
+
+  it('축마다 다른 속성을 바꾼다 — z 는 top 이고 y 는 zPos 다', () => {
+    expect(centerPart(BOARD, [DECK], 0, 'z')[0].top).toBe(700)
+    expect(centerPart(BOARD, [DECK], 0, 'y')[0].zPos).toBe(300)
+  })
+
+  it('바닥에 붙이면 zPos 가 0 이다 — 밑면이 곧 보드 바닥이다', () => {
+    expect(alignPartToStart([DECK], 0, 'y')[0].zPos).toBe(0)
+  })
+
+  it('끝에 붙이면 부품의 끝이 보드의 끝과 만난다', () => {
+    const moved = alignPartToEnd(BOARD, [DECK], 0, 'x')
+    expect(moved[0].left + moved[0].width).toBe(BOARD.width)
+  })
+
+  it('대칭 복제가 보드 안에서 반대쪽으로 간다', () => {
+    const parts = mirrorPart(BOARD, [{ ...DECK, left: 200 }], 0, 'x')
+
+    expect(parts).toHaveLength(2)
+    // 왼쪽 여백 200 → 오른쪽 여백도 200 이어야 한다
+    expect(parts[1].left).toBe(BOARD.width - 200 - DECK.width)
+  })
+
+  it('대칭 복제본이 어느 쪽인지 이름에 드러난다', () => {
+    expect(mirrorPart(BOARD, [{ ...DECK, left: 200 }], 0, 'x')[1].name).toBe('deck-x')
+  })
+
+  it('대칭 복제가 원본을 건드리지 않는다', () => {
+    const parts = mirrorPart(BOARD, [{ ...DECK, left: 200 }], 0, 'x')
+    expect(parts[0].left).toBe(200)
+  })
+
+  /*
+    이미 가운데면 사본이 같은 자리에 생긴다. 화면에는 아무 변화가 없어 보이는데 부품 수만
+    늘고 겹친 면에서 z-fighting 이 일어난다.
+  */
+  it('이미 가운데면 대칭 복제를 막는다', () => {
+    const centered = centerPart(BOARD, [DECK], 0, 'x')
+
+    expect(canMirror(BOARD, centered, 0, 'x')).toBe(false)
+    expect(mirrorPart(BOARD, centered, 0, 'x')).toHaveLength(1)
+  })
+
+  it('가운데가 아니면 대칭 복제할 수 있다', () => {
+    expect(canMirror(BOARD, [{ ...DECK, left: 200 }], 0, 'x')).toBe(true)
+  })
+
+  it('격자에 맞추면 위치와 크기가 격자 배수가 된다', () => {
+    const step = gridStep(BOARD)
+    const snapped = snapPart(BOARD, [{ ...DECK, left: 1213, width: 787 }], 0)
+
+    expect(snapped[0].left % step).toBe(0)
+    expect(snapped[0].width % step).toBe(0)
+  })
+
+  it('격자에 맞춰도 크기가 0 이 되지 않는다 — 사라진 것처럼 보인다', () => {
+    const snapped = snapPart(BOARD, [{ ...DECK, width: 1, height: 1, depth: 1 }], 0)
+
+    expect(snapped[0].width).toBeGreaterThan(0)
+    expect(snapped[0].height).toBeGreaterThan(0)
+    expect(snapped[0].depth).toBeGreaterThan(0)
+  })
+
+  it('없는 인덱스를 주면 목록을 그대로 반환한다', () => {
+    const parts = [DECK]
+    expect(centerPart(BOARD, parts, 7, 'x')).toBe(parts)
+    expect(snapPart(BOARD, parts, 7)).toBe(parts)
+    expect(mirrorPart(BOARD, parts, 7, 'x')).toBe(parts)
+    expect(canMirror(BOARD, parts, 7, 'x')).toBe(false)
+  })
+})
+
+describe('격자 간격', () => {
+  it('읽기 좋은 값이 나온다 — 27·33 같은 간격은 좌표를 읽을 수 없게 만든다', () => {
+    expect(niceStep(3000)).toBe(500)
+    expect(niceStep(1000)).toBe(200)
+    expect(niceStep(137)).toBe(20)
+    expect(niceStep(4)).toBe(1)
+  })
+
+  it('아무리 작아도 0 이 되지 않는다 — 0 으로 나누면 NaN 이 된다', () => {
+    expect(niceStep(0)).toBeGreaterThan(0)
+    expect(niceStep(-100)).toBeGreaterThan(0)
+  })
+
+  it('보드의 긴 쪽을 기준으로 잡는다 — 3D 바닥 격자와 같아야 한다', () => {
+    expect(gridStep(BOARD)).toBe(niceStep(3000))
+  })
+})