@things-factory/figure-ui 10.1.16 → 10.1.17

package/client/modeller/figure-view.ts

@@ -19,6 +19,30 @@
  * 한동안 3D 를 세울 때만 읽혔다 — things-scene 10.1.5 에서 고쳤다.
  */
 export interface ViewSettings {
+  /**
+   * 어떤 보드에 놓인 것으로 보나 — 씬 전체의 좌표 모드.
+   *
+   * **도형의 `placement` 와 다른 것이다.** 도형의 것은 「이 종류는 바닥에 서나, 천장에
+   * 매달리나」이고, 이것은 「지금 보고 있는 보드가 어느 쪽을 기준으로 재나」다. 바닥
+   * 기준 보드에 천정 기반 OHT 를 놓으면 보드는 안 뒤집히고 OHT 가 천장 높이에 매달린다.
+   *
+   * 한동안 도형의 `placement` 를 이 자리에 흘려 넣었다. 모델러에 도형이 하나뿐이라
+   * 그럴듯해 보였지만, 그러면 도형의 성질이 씬 전체를 뒤집는다 — 보드에서는 성립할 수가
+   * 없고(보드에는 도형이 여럿이다), 저작 중에는 배치를 고를 때마다 저작자가 적어 둔
+   * 높이가 전부 다른 숫자로 보였다.
+   *
+   * 씬의 낱말 그대로다: `floor` 바닥 기준 · `space` 중심 기준(바닥 없음) · `inverted`
+   * 천장 기준. **미리보기에만 먹인다** — 편집 캔버스의 `zPos` 는 저작자가 직접 적는
+   * 숫자라 그 뜻이 보기 설정에 따라 바뀌면 안 된다.
+   */
+  placement: 'floor' | 'space' | 'inverted'
+  /**
+   * 천장 높이 (mm). 천정 기반 도형을 미리보기에서 어디에 매달 것인가.
+   *
+   * 도형은 제가 놓일 방의 높이를 모른다. 보드는 알지만 미리보기에는 보드가 없으므로,
+   * 저작자가 가정할 값을 여기서 정한다.
+   */
+  ceilingHeight: number
   /** 좌표 바탕(축 가이드). 원점과 눈금을 보인다. */
   grid: boolean
   /** 축 이름표(X · Y · Z). 눈금만 두고 글자를 끌 수 있다. */
@@ -57,6 +81,32 @@ export const ENVIRONMENTS = [
 ] as const
 export type EnvironmentName = (typeof ENVIRONMENTS)[number]
 
+/**
+ * 씬에 그대로 넣는 보기 설정 — **좌표 기준과 천장 높이는 빼고.**
+ *
+ * 나머지는 전부 `model-layer` 의 상태 이름이라 그대로 넣으면 씬이 알아서 반응한다.
+ * 그런데 `placement` 는 편집 캔버스에 들어가면 안 되고(거기는 늘 상자 기준이다),
+ * `ceilingHeight` 는 씬이 모르는 이름이다.
+ *
+ * **rest spread 로 넘기지 않으려고 이 함수가 있다.** 캔버스가 한동안
+ * `const { grid, ..., ...light } = view` 로 나머지를 통째로 넘겼는데, 그러면 설정을
+ * 하나 더할 때마다 그것이 두 화면에 **말없이** 실린다. 새로 더한 좌표 기준이 바로
+ * 그 길로 캔버스에 들어갈 뻔했다.
+ */
+export function sceneLook(view: ViewSettings): Record<string, unknown> {
+  const { placement, ceilingHeight, ...look } = view
+  return look
+}
+
+/**
+ * 씬의 좌표 기준 — **씬의 낱말 그대로 셋이다.**
+ *
+ * 형식의 `floor` · `center` · `ceiling` 과 짝이 맞지만 철자가 다르다. 옮겨 적는 표를 두지
+ * 않는 것이 이 파일의 규칙이므로 씬 쪽을 쓴다. 화면에는 둘 다 보인다 — 「천장 기준
+ * (inverted)」.
+ */
+export const SCENE_REFERENCES = ['floor', 'space', 'inverted'] as const
+
 /** 배경색 기본값. 회색이라 부품 색이 제 색으로 보인다. */
 export const WORKBENCH = '#7c7c7c'
 
@@ -67,6 +117,9 @@ export const WORKBENCH = '#7c7c7c'
  * 무엇이 설정 때문이고 무엇이 원래 그랬는지 갈리지 않는다.
  */
 export const DEFAULT_VIEW: ViewSettings = {
+  placement: 'floor',
+  /* 공장 천장의 흔한 높이. 반도체 fab 의 OHT 레일이 대체로 이 언저리다. */
+  ceilingHeight: 4000,
   grid: true,
   gridLabels: true,
   floor: false,

package/client/modeller/part-edits.ts

@@ -1,13 +1,13 @@
 import { EXTRUDE_PRIMITIVES, SEGMENTED_PRIMITIVES, SEGMENT_PRESETS, PART_LIMIT } from '@hatiolab/figure-model'
 import type { DetailLevel, PrimitiveKind } from '@hatiolab/figure-model'
 
-import { AXIS_KEYS, boardExtent } from './figure-source.js'
-import type { BoardModel, PartModel, PlaneAxis } from './figure-source.js'
+import { AXIS_KEYS, draftExtent } from './figure-source.js'
+import type { FigureDraft, PartModel, PlaneAxis } from './figure-source.js'
 
 /**
  * 부품 편집 규칙. **씬 모델의 용어로** 다룬다.
  *
- * 편집 중에 기준이 되는 데이터는 씬 모델이다 — 보드 위에 부품 컴포넌트가 놓인 상태.
+ * 편집 중에 기준이 되는 데이터는 씬 모델이다 — 기준 상자 위에 부품 컴포넌트가 놓인 상태.
  * 그래서 편집도 씬의 용어(`left`·`top`·`zPos`·`width`·`height`·`depth`)로 한다.
  * FigureSource 의 좌표계로 바꾸는 변환은 `figure-source.ts` 한 곳에서만 한다.
  *
@@ -27,33 +27,33 @@ function freeName(taken: Set<string>, base: string): string {
   }
 }
 
-/** 이 보드에 부품을 몇 개까지 넣을 수 있는지. 디테일 등급이 결정한다. */
-export function partLimit(board: BoardModel): number {
-  return PART_LIMIT[(board.detailLevel ?? 'M') as DetailLevel]
+/** 이 초안에 부품을 몇 개까지 넣을 수 있는지. 디테일 등급이 결정한다. */
+export function partLimit(draft: FigureDraft): number {
+  return PART_LIMIT[(draft.detailLevel ?? 'M') as DetailLevel]
 }
 
 /**
  * 새 부품 하나를 만든다.
  *
- * 보드의 3분의 1 크기로, **바닥 가운데**에 놓는다. 추가하자마자 화면에 보여야 한다 —
+ * 기준 상자의 3분의 1 크기로, **바닥 가운데**에 놓는다. 추가하자마자 화면에 보여야 한다 —
  * 크기 0 으로 놓으면 사용자에게는 아무 일도 일어나지 않은 것으로 보인다.
  */
-export function newPart(board: BoardModel, parts: PartModel[], primitive: PrimitiveKind): PartModel {
+export function newPart(draft: FigureDraft, parts: PartModel[], primitive: PrimitiveKind): PartModel {
   const taken = new Set(parts.map(part => part.name))
 
-  const width = Math.max(1, Math.round(board.width / 3))
-  const height = Math.max(1, Math.round(board.height / 3))
-  const depth = Math.max(1, Math.round(board.depth / 3))
+  const width = Math.max(1, Math.round(draft.width / 3))
+  const height = Math.max(1, Math.round(draft.height / 3))
+  const depth = Math.max(1, Math.round(draft.depth / 3))
 
   const part: PartModel = {
     type: 'figure-part',
     name: freeName(taken, primitive),
     primitive,
-    left: Math.round((board.width - width) / 2),
-    top: Math.round((board.height - height) / 2),
+    left: Math.round((draft.width - width) / 2),
+    top: Math.round((draft.height - height) / 2),
     width,
     height,
-    // 바닥에 붙인다. `zPos` 는 부피의 밑면이라 0 이 곧 보드 바닥이다.
+    // 바닥에 붙인다. `zPos` 는 부피의 밑면이라 0 이 곧 상자 바닥이다.
     zPos: 0,
     depth,
     // 팔레트 토큰은 기존 부품의 것을 물려받는다 — 토큰이 늘어날 때마다 재질 그룹이 하나씩 는다.
@@ -79,8 +79,8 @@ export function newPart(board: BoardModel, parts: PartModel[], primitive: Primit
   return part
 }
 
-export function addPart(board: BoardModel, parts: PartModel[], primitive: PrimitiveKind): PartModel[] {
-  return [...parts, newPart(board, parts, primitive)]
+export function addPart(draft: FigureDraft, parts: PartModel[], primitive: PrimitiveKind): PartModel[] {
+  return [...parts, newPart(draft, parts, primitive)]
 }
 
 export function removePart(parts: PartModel[], index: number): PartModel[] {
@@ -133,25 +133,25 @@ function putAt(parts: PartModel[], index: number, axis: PlaneAxis, value: number
   return put(parts, index, { [AXIS_KEYS[axis].at]: value } as Partial<PartModel>)
 }
 
-/** 부품을 보드의 해당 축 가운데로 옮긴다. */
-export function centerPart(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+/** 부품을 기준 상자의 해당 축 가운데로 옮긴다. */
+export function centerPart(draft: FigureDraft, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
   const part = parts[index]
   if (!part) return parts
 
-  return putAt(parts, index, axis, Math.round((boardExtent(board, axis) - part[AXIS_KEYS[axis].size]) / 2))
+  return putAt(parts, index, axis, Math.round((draftExtent(draft, axis) - part[AXIS_KEYS[axis].size]) / 2))
 }
 
-/** 부품을 보드 바닥(또는 해당 축의 시작)에 붙인다. */
+/** 부품을 상자 바닥(또는 해당 축의 시작)에 붙인다. */
 export function alignPartToStart(parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
   return putAt(parts, index, axis, 0)
 }
 
-/** 부품을 보드의 끝에 붙인다. */
-export function alignPartToEnd(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+/** 부품을 상자의 끝에 붙인다. */
+export function alignPartToEnd(draft: FigureDraft, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
   const part = parts[index]
   if (!part) return parts
 
-  return putAt(parts, index, axis, Math.round(boardExtent(board, axis) - part[AXIS_KEYS[axis].size]))
+  return putAt(parts, index, axis, Math.round(draftExtent(draft, axis) - part[AXIS_KEYS[axis].size]))
 }
 
 /**
@@ -160,22 +160,22 @@ export function alignPartToEnd(board: BoardModel, parts: PartModel[], index: num
  * 다리 넷, 팔 둘 같은 형상을 이것 없이 만들면 고생한다. 이름은 **어느 쪽인지 알 수
  * 있게** 붙인다 — `leg` 를 x 축으로 대칭하면 `leg-x`.
  */
-export function mirrorPart(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+export function mirrorPart(draft: FigureDraft, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
   const part = parts[index]
-  if (!part || !canMirror(board, parts, index, axis)) return parts
+  if (!part || !canMirror(draft, parts, index, axis)) return parts
 
   const copy = JSON.parse(JSON.stringify(part)) as PartModel
   copy.name = freeName(new Set(parts.map(p => p.name)), `${part.name}-${axis}`)
 
   const next = [...parts]
   next.splice(index + 1, 0, copy)
-  return putAt(next, index + 1, axis, mirroredAt(board, part, axis))
+  return putAt(next, index + 1, axis, mirroredAt(draft, part, axis))
 }
 
-/** 대칭했을 때의 위치. 보드의 해당 축 안에서 뒤집는다. */
-function mirroredAt(board: BoardModel, part: PartModel, axis: PlaneAxis): number {
+/** 대칭했을 때의 위치. 상자의 해당 축 안에서 뒤집는다. */
+function mirroredAt(draft: FigureDraft, part: PartModel, axis: PlaneAxis): number {
   const { at, size } = AXIS_KEYS[axis]
-  return Math.round(boardExtent(board, axis) - part[at] - part[size])
+  return Math.round(draftExtent(draft, axis) - part[at] - part[size])
 }
 
 /**
@@ -185,24 +185,24 @@ function mirroredAt(board: BoardModel, part: PartModel, axis: PlaneAxis): number
  * 아무 변화가 없어 보이는데 부품 수만 늘고, 겹친 면에서 z-fighting 이 일어난다.
  * 만들어 놓고 알리는 대신 미리 막는다.
  */
-export function canMirror(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): boolean {
+export function canMirror(draft: FigureDraft, parts: PartModel[], index: number, axis: PlaneAxis): boolean {
   const part = parts[index]
   if (!part) return false
 
-  return mirroredAt(board, part, axis) !== Math.round(part[AXIS_KEYS[axis].at])
+  return mirroredAt(draft, part, axis) !== Math.round(part[AXIS_KEYS[axis].at])
 }
 
 /**
  * 부품의 위치와 크기를 격자에 맞춘다.
  *
- * 격자 간격은 보드 크기에서 계산한다 — 고정 값이면 작은 형상에서는 너무 크고 큰
+ * 격자 간격은 상자 크기에서 계산한다 — 고정 값이면 작은 형상에서는 너무 크고 큰
  * 형상에서는 너무 잘다. 3D 바닥 격자와 같은 계산이라 화면에서 보이는 것과 일치한다.
  */
-export function snapPart(board: BoardModel, parts: PartModel[], index: number): PartModel[] {
+export function snapPart(draft: FigureDraft, parts: PartModel[], index: number): PartModel[] {
   const part = parts[index]
   if (!part) return parts
 
-  const step = gridStep(board)
+  const step = gridStep(draft)
   const round = (value: number) => Math.round(value / step) * step
 
   return put(parts, index, {
@@ -223,8 +223,8 @@ export function snapPart(board: BoardModel, parts: PartModel[], index: number):
  * (바닥 160 x 160, 높이 1100)는 평면 기준으로 간격이 20 이 나와서, 옆에서 보면 높이가
  * 격자 55 칸이 된다. 격자는 크기를 가늠하는 자이므로 모델 전체에 대해 읽혀야 한다.
  */
-export function gridStep(board: BoardModel): number {
-  return niceStep(Math.max(board.width, board.height, board.depth))
+export function gridStep(draft: FigureDraft): number {
+  return niceStep(Math.max(draft.width, draft.height, draft.depth))
 }
 
 /**

package/client/modeller/proposal.ts

@@ -21,20 +21,41 @@ import type { FigurePart, FigureSource } from '@hatiolab/figure-model'
  * 기준 치수와 디테일 등급도 목록에 넣는다. 부품만 골라 받으면 새 부품이 옛 기준
  * 상자 밖으로 나가 **검증에 걸릴 수 있다** — 무엇을 함께 받아야 하는지 보여야 한다.
  */
-export type ChangeKind = 'added' | 'changed' | 'removed' | 'base' | 'detail' | 'anchor' | 'styleKit'
+export type ChangeKind =
+  | 'added'
+  | 'changed'
+  | 'removed'
+  | 'base'
+  | 'placement'
+  | 'detail'
+  | 'styleKit'
+  | 'animations'
+  | 'capabilities'
 
 /**
  * 부품 밖에서 바뀔 수 있는 것 전부.
  *
  * 여기 없는 필드는 **조용히 버려진다** — 후보가 바꿔 왔어도 목록에 안 뜨고 받아도
  * 반영되지 않는다. 형식에 필드가 늘면 여기에 더해야 한다.
+ *
+ * 그 일이 실제로 났다(2026-09-15). `animations` · `capabilities` · `placement` 셋이 빠져 있었다.
+ * 후보가 애니메이션만 더해 오면 변경 목록이 **비어서** 「n건 반영」 단추가 잠기고, 저작자는
+ * 후보를 받지도 버리지도 못한 채 멈춘다. 다른 변경과 섞여 오면 단추는 눌리는데 애니메이션만
+ * 말없이 사라진다. 그리고 `anchor` 는 도형 수준 필드였다가 형식에서 없어진 것인데(2026-09-10)
+ * 여기 남아 있었다 — 이 목록이 형식을 따라가지 않은 것이 양쪽으로 드러난 셈이다.
+ *
+ * 형식의 `FigureSource` 는 `type` · `parts` 를 빼면 이 여섯이 전부다. `type` 은 저장되는
+ * 식별자라 후보가 바꿔 와도 받지 않고(`applyProposal` 참고), `version` 은 저작자가 고를 것이
+ * 아니라 저장할 때 서버가 찍는다.
  */
-const FIGURE_FIELDS = ['base', 'detailLevel', 'anchor', 'styleKit'] as const
+const FIGURE_FIELDS = ['base', 'placement', 'detailLevel', 'styleKit', 'animations', 'capabilities'] as const
 const FIELD_KIND: Record<(typeof FIGURE_FIELDS)[number], ChangeKind> = {
   base: 'base',
+  placement: 'placement',
   detailLevel: 'detail',
-  anchor: 'anchor',
-  styleKit: 'styleKit'
+  styleKit: 'styleKit',
+  animations: 'animations',
+  capabilities: 'capabilities'
 }
 
 export interface ProposalChange {