@things-factory/figure-ui 10.1.15 → 10.1.17

package/client/modeller/figure-preview.ts

@@ -6,6 +6,9 @@ import { compile, validate } from '@hatiolab/figure-model'
 import type { FigureSource } from '@hatiolab/figure-model'
 import { create, registerFigure } from '@hatiolab/things-scene'
 
+import { DEFAULT_VIEW, sceneLook, WORKBENCH } from './figure-view.js'
+import type { ViewSettings } from './figure-view.js'
+
 /**
  * 저작 중인 것을 **보드에 놓았을 때**의 모습.
  *
@@ -29,9 +32,6 @@ import { create, registerFigure } from '@hatiolab/things-scene'
  * 뷰 모드로 세운다.
  */
 
-/** 배경. 편집 캔버스와 같은 값을 쓴다 — 갈리면 두 화면이 다른 도구처럼 보인다. */
-const WORKBENCH = '#7c7c7c'
-
 /** 얼마나 키워 보나. */
 export const PREVIEW_FACTOR = 2
 
@@ -57,6 +57,47 @@ export const PREVIEW_WAYS: readonly { name: string; axes: readonly ('x' | 'y' |
   { name: 'x·y·z', axes: ['x', 'y', 'z'] }
 ]
 
+/**
+ * 이 도형의 상자 **밑면**이 씬의 어느 높이에 오나.
+ *
+ * 배치 기준이 하는 일이 이것 하나다 — 좌표를 뒤집는 것이 아니라 **높이를 정하는 것.**
+ * 바닥 기반은 땅에 서고, 천정 기반은 천장에서 제 키만큼 내려온 자리에 매달리고,
+ * 중심 기반은 그 사이에 뜬다. `operato-scene` 의 archetype 이 같은 말을 한다
+ * (`archetypes.ts`: ceiling — *zPos derived from ceiling minus depth*).
+ */
+function bottomOf(placement: FigureSource['placement'], height: number, ceiling: number): number {
+  switch (placement) {
+    case 'ceiling':
+      return ceiling - height
+    case 'center':
+      return (ceiling - height) / 2
+    case 'floor':
+    default:
+      return 0
+  }
+}
+
+/**
+ * 밑면 높이를 씬이 받는 `zPos` 로 옮긴다.
+ *
+ * 씬은 부품 중심을 `zPos + geometricOffsetY` 에 놓고, 그 오프셋이 좌표 기준마다 다르다
+ * (`real-object.ts`). 그래서 같은 밑면을 말하는 `zPos` 가 기준마다 다른 수다 — 바닥
+ * 기준이면 밑면 그대로, 중심 기준이면 중심, 천장 기준이면 윗면.
+ *
+ * **여기가 유일하게 좌표 기준을 아는 자리다.** 저작한 값에는 이것이 안 들어간다.
+ */
+function zPosOf(bottom: number, height: number, reference: ViewSettings['placement']): number {
+  switch (reference) {
+    case 'space':
+      return bottom + height / 2
+    case 'inverted':
+      return bottom + height
+    case 'floor':
+    default:
+      return bottom
+  }
+}
+
 interface SceneHandle {
   dispose?: () => void
   resize?: () => void
@@ -64,6 +105,8 @@ interface SceneHandle {
   root?: {
     invalidate?: () => void
     fitCameraToModel?: (margin?: number) => void
+    /** 보기 설정을 넣는 자리. 씬이 스스로 반응한다. */
+    set?: (patch: Record<string, unknown>) => void
     /** 세워 둔 인스턴스들. clip 을 몰 때 전부에 같은 값을 준다. */
     components?: { set?: (property: string, value: unknown) => void }[]
   }
@@ -162,6 +205,14 @@ export class FigurePreview extends localize(i18next)(LitElement) {
   /** 저작 중인 것. 저장 형식으로 받는다 — 보드가 소비하는 것이 이 형식이다. */
   @property({ type: Object }) source?: FigureSource
 
+  /**
+   * 보기 설정. 저장되지 않는다(`figure-view.ts`).
+   *
+   * 한동안 이 화면만 조명과 환경을 **하드코딩**했다. 저작자가 환경 탭에서 무엇을 바꿔도
+   * 편집 캔버스만 달라지고 여기는 그대로였다 — 두 화면이 같은 것을 다르게 보여 주었다.
+   */
+  @property({ type: Object }) view: ViewSettings = DEFAULT_VIEW
+
   @query('div[stage]') private stage!: HTMLDivElement
 
   /** 세울 수 없는 사유. 없으면 세운 것이다. */
@@ -236,9 +287,33 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     }
   }
 
+  /**
+   * 보기 설정이 바뀌면 **다시 세우지 않고 씬에 넣는다** — 두 개만 빼고.
+   *
+   * 조명·환경·바탕은 씬이 스스로 반응한다(`three-capability` 의 `onchange`). 슬라이더를
+   * 끄는 동안 다시 세우면 카메라가 매 프레임 처음으로 돌아간다.
+   *
+   * 좌표 기준과 천장 높이는 다르다. 그 둘은 컴포넌트의 `zPos` 를 만들 때 쓰였으므로,
+   * 이미 세워 둔 것에 넣어 봐야 자리가 안 바뀐다. 그것만 다시 세운다.
+   */
   willUpdate(changed: Map<string, unknown>) {
     if (!this.hasUpdated) return
-    if (changed.has('source')) this.standUp()
+
+    if (changed.has('source')) {
+      this.standUp()
+      return
+    }
+
+    if (!changed.has('view')) return
+
+    const before = changed.get('view') as ViewSettings | undefined
+    const now = this.view ?? DEFAULT_VIEW
+    if (before?.placement !== now.placement || before?.ceilingHeight !== now.ceilingHeight) {
+      this.standUp()
+      return
+    }
+
+    this.scene?.root?.set?.(sceneLook(now))
   }
 
   firstUpdated() {
@@ -268,7 +343,9 @@ export class FigurePreview extends localize(i18next)(LitElement) {
       return
     }
 
-    const signature = JSON.stringify(source)
+    const view = this.view ?? DEFAULT_VIEW
+    /* 좌표 기준과 천장 높이가 컴포넌트의 `zPos` 를 만든다 — 서명에 안 넣으면 다시 세워도 그대로 선다. */
+    const signature = JSON.stringify([source, view.placement, view.ceilingHeight])
     if (this.scene && this.standing === signature) return
 
     const { errors } = validate(source)
@@ -304,24 +381,16 @@ export class FigurePreview extends localize(i18next)(LitElement) {
       const COLUMNS = 4
       const cell = { x: base.x * biggest * 1.25, z: base.z * biggest * 1.25 }
       const rows = Math.ceil(PREVIEW_WAYS.length / COLUMNS)
-      const board = {
-        width: Math.round(cell.x * COLUMNS),
-        height: Math.round(cell.z * rows),
-        /*
-          판의 높이도 가장 큰 인스턴스를 담아야 한다.
-
-          안 주면 카메라가 평면만 보고 자리를 잡아서, 키가 큰 모델은 밑동만 보인다.
-          시그널타워를 2 배로 놓으면 2200 인데 판이 그것을 모르면 받침만 화면에 든다.
-        */
-        depth: Math.round(base.y * biggest * 1.1)
-      }
-
       /*
         씬의 낱말이 형식과 다르다 — `width` 가 형식의 x, `height` 가 z, `depth` 가 y 다.
         옮기는 일을 여기 한 줄에 모아 둔다.
 
         `depth` 를 늘 적는 이유가 있다. 안 적으면 평면 두 축의 기하평균으로 잡혀서,
         「y 만 키운다」가 x·z 를 안 건드리는데도 높이가 안 오른다.
+
+        높이는 **배치 기준이 정한다.** 바닥 기반은 땅에서 올라오고, 천정 기반은 천장에
+        붙어 내려온다. 여덟을 나란히 세우는 자리라 이것이 눈에 바로 보인다 — 바닥 기반이면
+        밑면이, 천정 기반이면 윗면이 한 줄이 된다.
       */
       const components = PREVIEW_WAYS.map((way, at) => {
         const grow = growth(way)
@@ -329,6 +398,8 @@ export class FigurePreview extends localize(i18next)(LitElement) {
         const row = Math.floor(at / COLUMNS)
         const width = Math.round(base.x * grow.x)
         const height = Math.round(base.z * grow.z)
+        const tall = Math.round(base.y * grow.y)
+        const bottom = bottomOf(source.placement, tall, view.ceilingHeight)
 
         return {
           type: source.type,
@@ -338,23 +409,49 @@ export class FigurePreview extends localize(i18next)(LitElement) {
           top: Math.round(row * cell.z + (cell.z - height) / 2),
           width,
           height,
-          depth: Math.round(base.y * grow.y)
+          depth: tall,
+          zPos: Math.round(zPosOf(bottom, tall, view.placement))
         }
       })
 
+      const draft = {
+        width: Math.round(cell.x * COLUMNS),
+        height: Math.round(cell.z * rows),
+        /*
+          판의 높이도 가장 큰 인스턴스를 담아야 한다.
+
+          안 주면 카메라가 평면만 보고 자리를 잡아서, 키가 큰 모델은 밑동만 보인다.
+          시그널타워를 2 배로 놓으면 2200 인데 판이 그것을 모르면 받침만 화면에 든다.
+
+          가장 높은 **윗면**으로 잡는다. 천정 기반은 천장 높이에 매달리므로 제 키보다
+          훨씬 위에 있다 — 키만 보고 잡으면 천장에 걸린 것이 화면 밖으로 나간다.
+        */
+        depth: Math.round(
+          Math.max(...components.map(c => bottomOf(source.placement, c.depth, view.ceilingHeight) + c.depth)) * 1.1
+        )
+      }
+
       this.scene = create({
         target: this.stage,
         model: {
           type: 'model-layer',
-          width: board.width,
-          height: board.height,
-          depth: board.depth,
+          width: draft.width,
+          height: draft.height,
+          depth: draft.depth,
           threed: true,
-          environment: 'studio',
-          grid: true,
           sky: 'color',
-          skyColor: WORKBENCH,
-          floor: false,
+          /*
+            보기 설정을 그대로 싣는다.
+
+            여기만 조명·환경·바탕을 하드코딩하고 있었다. 저작자가 환경 탭에서 조명을
+            올려도 편집 캔버스만 밝아지고 이 화면은 그대로여서, 같은 것을 두 화면이
+            다르게 보여 주었다.
+
+            `sceneLook` 이 좌표 기준과 천장 높이를 빼고 준다 — 그 둘은 씬에 그대로 넣을
+            값이 아니라 위에서 `zPos` 를 정하는 데 쓴다. 좌표 기준만 여기 따로 싣는다.
+          */
+          ...sceneLook(view),
+          placement: view.placement,
           pixelRatio: Math.min(3, (window.devicePixelRatio || 1) * 2),
           components
         },

package/client/modeller/figure-report.ts

@@ -6,7 +6,7 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js'
 
 import { i18next, localize } from '@operato/i18n'
 import { ScrollbarStyles } from '@operato/styles'
-import { compile, costCurveSvg, costOf, scoreOf, sizingReport, validate } from '@hatiolab/figure-model'
+import { blocksRelease, compile, costCurveSvg, costOf, scoreOf, sizingReport, validate } from '@hatiolab/figure-model'
 import type { FigureCost, FigureScore, FigureSource } from '@hatiolab/figure-model'
 
 import { capacityOf } from './scene-budget.js'
@@ -439,7 +439,16 @@ export class FigureReport extends localize(i18next)(LitElement) {
   /** 추이 그림을 제 크기로 펼쳤나. */
   @state() private expanded = false
   @state() private errors: { code: string; message: string; at?: string }[] = []
-  @state() private violations: { code: string; message: string }[] = []
+  /**
+   * 형식이 권하지 않는 것 — **그중 둘은 발행을 막는다.**
+   *
+   * 등급을 형식에서 받는다(`blocksRelease`). 화면이 제 목록을 들면 형식에 코드가 하나 늘 때
+   * 조용히 「알림」으로 그려지고, 저작자는 발행이 막힌 것을 **눌러 보고 나서야** 안다.
+   *
+   * `actual` 은 얼마나 넘쳤나다. 「상자를 벗어난다」만으로는 2mm 인지 250mm 인지 모르고,
+   * 그 둘은 고치는 품이 다르다.
+   */
+  @state() private violations: { code: string; message: string; blocking: boolean; actual?: number }[] = []
   /**
    * 크기를 바꿔 봤을 때 갈라지는가 — **발행을 막는 것**이다.
    *
@@ -864,9 +873,13 @@ export class FigureReport extends localize(i18next)(LitElement) {
           )}
           ${this.violations.map(
             v => html`
-              <li violation>
-                <md-icon>info</md-icon>
-                <span>${v.message}</span>
+              <li ?violation=${!v.blocking}>
+                <md-icon>${v.blocking ? 'block' : 'info'}</md-icon>
+                <span>
+                  ${v.message}${v.blocking && v.actual !== undefined
+                    ? html` <code at>${v.actual}</code>`
+                    : ''}
+                </span>
               </li>
             `
           )}
@@ -909,7 +922,12 @@ export class FigureReport extends localize(i18next)(LitElement) {
 
     const result = validate(source)
     this.errors = result.errors.map(e => ({ code: e.code, message: e.message, at: e.path }))
-    this.violations = result.violations.map(v => ({ code: v.code, message: v.message }))
+    this.violations = result.violations.map(v => ({
+      code: v.code,
+      message: v.message,
+      blocking: blocksRelease(v.code),
+      actual: v.actual
+    }))
 
     if (this.errors.length > 0) {
       // 형식을 어겼으면 컴파일이 던진다. 셈을 비우고 오류만 보여 준다.

package/client/modeller/figure-settings.ts

@@ -4,7 +4,7 @@ import { customElement, property } from 'lit/decorators.js'
 import { i18next, localize } from '@operato/i18n'
 import { ScrollbarStyles } from '@operato/styles'
 
-import { DEFAULT_VIEW, ENVIRONMENTS } from './figure-view.js'
+import { DEFAULT_VIEW, ENVIRONMENTS, SCENE_REFERENCES } from './figure-view.js'
 import type { EnvironmentName, ViewSettings } from './figure-view.js'
 
 /**
@@ -99,6 +99,7 @@ export class FigureSettings extends localize(i18next)(LitElement) {
       }
 
       select,
+      input[type='number'],
       input[type='color'] {
         width: 100%;
         padding: 5px 6px;
@@ -158,10 +159,52 @@ export class FigureSettings extends localize(i18next)(LitElement) {
     const view = this.view ?? DEFAULT_VIEW
 
     return html`
+      <!--
+        놓이는 보드.
+
+        이 묶음이 맨 위인 것은, 나머지가 「어떻게 보이나」인데 이것은 「무엇으로 보고
+        있나」이기 때문이다. 미리보기가 보드에 놓인 모습을 말하는 자리이므로, 어떤 보드를
+        가정하는지가 먼저 정해져야 그 다음이 뜻을 갖는다.
+
+        도형 탭의 「배치 기준」과 짝이지 같은 것이 아니다. 저쪽은 이 도형이 어느 면에
+        붙는가(저장된다), 이쪽은 그 면을 가진 보드가 어느 쪽을 기준으로 재는가(저장 안 된다).
+      -->
       <section>
-        <h3>${i18next.t('figure.label.guides')}</h3>
+        <h3>${i18next.t('figure.label.assumed-board')}</h3>
         <p quiet>${i18next.t('figure.text.view-settings-are-not-saved')}</p>
 
+        <label field>
+          <span>${i18next.t('figure.label.scene-reference')}</span>
+          <select
+            .value=${view.placement}
+            @change=${(e: Event) =>
+              this.put({ placement: (e.target as HTMLSelectElement).value as ViewSettings['placement'] })}
+          >
+            ${SCENE_REFERENCES.map(
+              name => html`<option value=${name} ?selected=${view.placement === name}>
+                ${i18next.t(`figure.label.scene-reference-${name}`)}
+              </option>`
+            )}
+          </select>
+        </label>
+        <p quiet>${i18next.t('figure.text.scene-reference-explained')}</p>
+
+        <label field>
+          <span>${i18next.t('figure.label.ceiling-height')}</span>
+          <input
+            type="number"
+            min="0"
+            step="100"
+            .value=${String(view.ceilingHeight)}
+            @change=${(e: Event) => this.put({ ceilingHeight: Number((e.target as HTMLInputElement).value) || 0 })}
+          />
+        </label>
+        <p quiet>${i18next.t('figure.text.ceiling-height-explained')}</p>
+      </section>
+
+      <section>
+        <h3>${i18next.t('figure.label.guides')}</h3>
+
         ${this.toggle('grid', view.grid, i18next.t('figure.label.coordinate-ground'), i18next.t('figure.text.coordinate-ground-explained'))}
         ${this.toggle('gridLabels', view.gridLabels, i18next.t('figure.label.axis-labels'))}
         ${this.toggle('floor', view.floor, i18next.t('figure.label.scene-floor'), i18next.t('figure.text.floor-explained'))}

package/client/modeller/figure-side.ts

@@ -12,7 +12,7 @@ import { customElement, property, state } from 'lit/decorators.js'
 import { i18next, localize } from '@operato/i18n'
 import type { FigureSource } from '@hatiolab/figure-model'
 
-import type { BoardModel, PartModel } from './figure-source.js'
+import type { FigureDraft, PartModel } from './figure-source.js'
 import { DEFAULT_VIEW } from './figure-view.js'
 import type { ViewSettings } from './figure-view.js'
 
@@ -156,7 +156,7 @@ export class FigureSide extends localize(i18next)(LitElement) {
   @property({ type: Number }) figureVersion = 0
   @property({ type: Boolean }) dirty = false
 
-  @property({ type: Object }) board?: BoardModel
+  @property({ type: Object }) draft?: FigureDraft
   @property({ type: Array }) parts: PartModel[] = []
   @property({ type: Object }) source?: FigureSource
   @property({ type: Number }) selected = -1
@@ -175,7 +175,7 @@ export class FigureSide extends localize(i18next)(LitElement) {
    * 0 이면 아무것도 안 붙인다 — 「0」을 붙이면 없는 것이 있는 것처럼 자리를 차지한다.
    */
   private get clipCount(): number | undefined {
-    const n = this.board?.animations?.length ?? 0
+    const n = this.draft?.animations?.length ?? 0
     return n === 0 ? undefined : n
   }
 
@@ -196,20 +196,20 @@ export class FigureSide extends localize(i18next)(LitElement) {
         .figureName=${this.figureName}
         .figureCategory=${this.figureCategory}
         .figureTags=${this.figureTags}
-        .board=${this.board}
+        .draft=${this.draft}
         .parts=${this.parts}
         .selected=${this.selected}
       ></figure-inspector>
 
       <figure-capabilities
         ?off=${this.tab !== 'capability'}
-        .board=${this.board}
+        .draft=${this.draft}
         .parts=${this.parts}
       ></figure-capabilities>
 
       <figure-animations
         ?off=${this.tab !== 'animation'}
-        .board=${this.board}
+        .draft=${this.draft}
         .parts=${this.parts}
       ></figure-animations>
 

package/client/modeller/figure-source.ts

@@ -6,7 +6,7 @@ import { FIGURE_SOURCE_VERSION, type DetailLevel, type FigurePart, type FigurePl
  * ## Why this is the only place that converts
  *
  * While authoring, the source of truth is the **scene model** -- part
- * components sitting on a board. `FigureSource` is produced from it when the
+ * components sitting on a draft. `FigureSource` is produced from it when the
  * asset is saved or scored.
  *
  * The two use different vocabularies. The scene inherited 2D canvas terms
@@ -27,21 +27,21 @@ import { FIGURE_SOURCE_VERSION, type DetailLevel, type FigurePart, type FigurePl
  *
  * ## The mapping
  *
- * The board is the base box; its centre is the format's origin.
+ * The draft is the base box; its centre is the format's origin.
  *
  *     format            scene
  *     ────────────────  ──────────────────────────────
- *     base.x            board width
- *     base.y            board depth      <- height
- *     base.z            board height
+ *     base.x            draft width
+ *     base.y            draft depth      <- height
+ *     base.z            draft height
  *
  *     size.x            width
  *     size.y            depth
  *     size.z            height
  *
- *     position.x        left + width/2  - board width/2
- *     position.y        zPos + depth/2  - board depth/2      <- zPos is the underside
- *     position.z        top  + height/2 - board height/2
+ *     position.x        left + width/2  - draft width/2
+ *     position.y        zPos + depth/2  - draft depth/2      <- zPos is the underside
+ *     position.z        top  + height/2 - draft height/2
  *
  *     rotation.x        rotationX       (scene radians, format degrees)
  *     rotation.y        -rotation
@@ -62,16 +62,32 @@ import { FIGURE_SOURCE_VERSION, type DetailLevel, type FigurePart, type FigurePl
  * is the guard below actually earning its keep. The third showed up as a conveyor motor that stayed on the
  * floor no matter what the sample said; the fourth as a hollowed tray that
  * came out a solid block.
+ *
+ * All four passed the round-trip test, because the fixture it uses did not
+ * carry the field. So the test now reads the **field list the format declares**
+ * rather than trusting the fixture.
+ *
+ * `shape` is unpacked into `round`, `path` and `hollow` rather than carried
+ * whole, because the editor holds those as separate state. Every field added
+ * under `shape` costs a line here, and forgetting that line was the fourth
+ * of the four.
  */
 /** 판 컴포넌트의 상태. 씬의 용어 그대로다. */
-export interface BoardModel {
+export interface FigureDraft {
   /** 형식 버전. */
   version?: number
-  /** 가로 너비 (mm). 씬의 x 축. */
+  /*
+    The three sizes keep the scene component's names, and the scene assigns its axes differently
+    from the format: here `depth` is the vertical one. Naming the axis alone ("the y axis") does
+    not say which of the two conventions is meant, and this interface sits on the boundary between
+    them — so each field names the `FigureSource` field it becomes. `toFigureSource` and
+    `fromFigureSource` below are the only places that may disagree with these three lines.
+  */
+  /** 가로 너비 (mm) → `base.x`. */
   width: number
-  /** 세로 깊이 (mm). 씬의 y 축 (평면에서는 세로, 저작자가 위에서 내려다보는 세로). */
+  /** 앞뒤 깊이 (mm) → `base.z`. 저작자가 위에서 내려다볼 때의 세로다. */
   height: number
-  /** 높이 (mm). 씬의 z 축. */
+  /** 높이 (mm) → `base.y`. 서 있는 방향이다. */
   depth: number
   /** 컴포넌트 타입 이름. **저장되는 식별자다.** */
   figureType?: string
@@ -136,11 +152,21 @@ export interface PartModel {
 
   /** 색 토큰 이름 (`palette.primary` 등). */
   token?: string
-  preset?: FigurePart['material'] extends infer M ? (M extends { preset?: infer P } ? P : never) : never
+  /*
+    `FigurePart['material']` is required in the format, so these index into it directly. The
+    `NonNullable` on `shape` above is not the same case — `shape` is optional there.
+  */
+  preset?: FigurePart['material']['preset']
   flatShading?: boolean
   transparent?: boolean
-  emissive?: NonNullable<FigurePart['material']>['emissive']
-  surface?: NonNullable<FigurePart['material']>['surface']
+  /**
+   * 자체발광. 없으면 안 빛난다.
+   *
+   * 바깥의 `token` 이 **꺼진 모습**이고 이 안의 `token` 이 **켜진 모습**이다 — 꺼진
+   * 전구는 빨갛지 않고 어두운 플라스틱이다.
+   */
+  emissive?: FigurePart['material']['emissive']
+  surface?: FigurePart['material']['surface']
 
   /* 아직 아무 일도 안 하지만 잃어버리지 않는다. */
   materialSlot?: FigurePart['materialSlot']
@@ -173,7 +199,7 @@ function withoutEmpty<T extends object>(value: T): T {
 }
 
 /** 소수점 넷째 자리까지. 라디안↔도를 오가며 생기는 꼬리를 자른다. */
-function round4(value: number): number {
+export function round4(value: number): number {
   return Math.round(value * 1e4) / 1e4
 }
 
@@ -182,10 +208,30 @@ function round4(value: number): number {
  *
  * 축 이름은 **형식의 것**이다 — x 가로 · y 높이 · z 세로.
  */
-export function halfOf(board: BoardModel): Vec3 {
-  return { x: board.width / 2, y: board.depth / 2, z: board.height / 2 }
+export function halfOf(draft: FigureDraft): Vec3 {
+  return { x: draft.width / 2, y: draft.depth / 2, z: draft.height / 2 }
 }
 
+/*
+ * ── The placement is not in these numbers ────────────────────────────────────
+ *
+ * `placement` says which reference surface a figure of this kind attaches to — a conveyor stands
+ * on the floor, an OHT hangs from the ceiling. That is a fact about the figure *type*, and the
+ * scene acts on it when an instance is placed: `floor` puts the box on the ground, `ceiling` at
+ * the ceiling height less the figure's own height. Nothing about the authored shape changes.
+ *
+ * So the conversion below does not read it, and the editing canvas does not either. The box is
+ * always `0 … base.y` there and `zPos` is always the part's underside. Two figures with identical
+ * parts and different placements have identical `parts` arrays, which is what the format says.
+ *
+ * This used to be wired the other way: the canvas fed the figure's placement to the model layer's
+ * `state.placement`, which is a scene-wide coordinate mode ('floor' | 'space' | 'inverted') that
+ * flips what `zPos` names for everything in that layer. It stood in for the archetype because the
+ * modeller holds exactly one figure — and it cost a whole day of defects, because every number the
+ * author typed then meant a different face depending on a dropdown. That coordinate mode is now
+ * where it belongs: a workbench setting in `figure-view.ts`, applied to the preview alone.
+ */
+
 /**
  * 저작자가 보는 축이 씬의 어느 용어인가.
  *
@@ -201,34 +247,34 @@ export const AXIS_KEYS = {
 export type PlaneAxis = keyof typeof AXIS_KEYS
 
 /** 판이 그 축으로 얼마나 넓은가. */
-export function boardExtent(board: BoardModel, axis: PlaneAxis): number {
-  return axis === 'x' ? board.width : axis === 'y' ? board.depth : board.height
+export function draftExtent(draft: FigureDraft, axis: PlaneAxis): number {
+  return axis === 'x' ? draft.width : axis === 'y' ? draft.depth : draft.height
 }
 
 /** 부품 하나를 저장 형식으로 변환한다. 저작 화면이 저작자의 어휘로 보일 때 쓴다. */
-export function partToFigure(part: PartModel, board: BoardModel): FigurePart {
-  return partTo(part, halfOf(board))
+export function partToFigure(part: PartModel, draft: FigureDraft): FigurePart {
+  return partTo(part, halfOf(draft))
 }
 
 /** 부품 하나를 씬 용어로 되돌린다. */
-export function partFromFigure(part: FigurePart, board: BoardModel): PartModel {
-  return partFrom(part, halfOf(board))
+export function partFromFigure(part: FigurePart, draft: FigureDraft): PartModel {
+  return partFrom(part, halfOf(draft))
 }
 
 /** 씬 모델을 저장 형식으로 변환한다. */
-export function toFigureSource(board: BoardModel, parts: PartModel[]): FigureSource {
-  const half = halfOf(board)
+export function toFigureSource(draft: FigureDraft, parts: PartModel[]): FigureSource {
+  const half = halfOf(draft)
 
   return withoutEmpty({
-    version: board.version ?? FIGURE_SOURCE_VERSION,
-    type: board.figureType ?? '',
-    base: { x: board.width, y: board.depth, z: board.height },
-    placement: board.placement,
-    detailLevel: board.detailLevel,
-    styleKit: board.styleKit,
+    version: draft.version ?? FIGURE_SOURCE_VERSION,
+    type: draft.figureType ?? '',
+    base: { x: draft.width, y: draft.depth, z: draft.height },
+    placement: draft.placement,
+    detailLevel: draft.detailLevel,
+    styleKit: draft.styleKit,
     parts: parts.map(part => partTo(part, half)),
-    animations: board.animations,
-    capabilities: board.capabilities
+    animations: draft.animations,
+    capabilities: draft.capabilities
   }) as FigureSource
 }
 
@@ -282,10 +328,10 @@ function partTo(part: PartModel, half: Vec3): FigurePart {
 }
 
 /** 형식을 씬 모델로 편다. */
-export function fromFigureSource(source: FigureSource): { board: BoardModel; parts: PartModel[] } {
+export function fromFigureSource(source: FigureSource): { draft: FigureDraft; parts: PartModel[] } {
   const half: Vec3 = { x: source.base.x / 2, y: source.base.y / 2, z: source.base.z / 2 }
 
-  const board = withoutEmpty({
+  const draft = withoutEmpty({
     version: source.version,
     width: source.base.x,
     height: source.base.z,
@@ -296,9 +342,9 @@ export function fromFigureSource(source: FigureSource): { board: BoardModel; par
     styleKit: source.styleKit,
     animations: source.animations,
     capabilities: source.capabilities
-  }) as BoardModel
+  }) as FigureDraft
 
-  return { board, parts: source.parts.map(part => partFrom(part, half)) }
+  return { draft, parts: source.parts.map(part => partFrom(part, half)) }
 }
 
 function partFrom(part: FigurePart, half: Vec3): PartModel {

package/client/modeller/figure-thumbnail.ts

@@ -1,6 +1,6 @@
 import './figure-canvas.js'
 
-import type { BoardModel, PartModel } from './figure-source.js'
+import type { FigureDraft, PartModel } from './figure-source.js'
 
 /**
  * 카드에 쓸 그림을 찍는다 — **숨은 자리에 저작 캔버스를 하나 더 세워서.**
@@ -28,7 +28,7 @@ const WIDTH = 480
 const HEIGHT = 360
 
 interface Shooter extends HTMLElement {
-  board?: BoardModel
+  draft?: FigureDraft
   parts?: PartModel[]
   viewOnly?: boolean
   snapshot?: (width?: number, height?: number) => Promise<string | undefined>
@@ -71,10 +71,10 @@ function within<T>(work: Promise<T>, ms: number): Promise<T | undefined> {
 }
 
 export async function captureThumbnail(
-  board: BoardModel | undefined,
+  draft: FigureDraft | undefined,
   parts: PartModel[]
 ): Promise<string | undefined> {
-  if (!board || !parts.length) {
+  if (!draft || !parts.length) {
     return undefined
   }
 
@@ -89,7 +89,7 @@ export async function captureThumbnail(
 
   const shooter = document.createElement('figure-canvas') as Shooter
   shooter.viewOnly = true
-  shooter.board = board
+  shooter.draft = draft
   shooter.parts = parts
   shooter.style.cssText = 'display: block; width: 100%; height: 100%;'