@things-factory/figure-ui 10.1.26 → 10.1.28

package/client/modeller/figure-inspector.ts

@@ -16,13 +16,41 @@ import {
   FIGURE_PLACEMENTS,
   trianglesOf
 } from '@hatiolab/figure-model'
-import { ANCHOR_RULES, PART_ROLES, REPEAT_LIMIT, anchorOfPart, repeatPlanOfPart } from '@hatiolab/figure-model'
-import type { AnchorRule, Axis, FigurePart, FigurePlacement, MaterialPreset, PartRole, PrimitiveKind } from '@hatiolab/figure-model'
+import { ANCHOR_RULES, JOINT_TYPES, PART_ROLES, REPEAT_LIMIT, anchorOfPart, repeatPlanOfPart } from '@hatiolab/figure-model'
+import type {
+  AnchorRule,
+  Axis,
+  ContractChange,
+  FigurePart,
+  FigurePlacement,
+  JointType,
+  MaterialPreset,
+  PartRole,
+  PrimitiveKind,
+  Vec3
+} from '@hatiolab/figure-model'
 import { activePalette } from '@hatiolab/things-scene'
 
 import { partToFigure, partFromFigure } from './figure-source.js'
 import type { FigureDraft, PartModel } from './figure-source.js'
 import { canMirror } from './part-edits.js'
+import { jointOf, parentChoices, patchJoint, setJointType } from './joint-edits.js'
+import { baseFittingParts, baseOf, resizeBase } from './base-box.js'
+import type { BaseSize } from './base-box.js'
+
+/** Axis choices for a joint. Written as a direction the author reads, stored as a vector. */
+const JOINT_AXES: readonly { key: string; axis: Vec3 }[] = [
+  { key: '+x', axis: { x: 1, y: 0, z: 0 } },
+  { key: '-x', axis: { x: -1, y: 0, z: 0 } },
+  { key: '+y', axis: { x: 0, y: 1, z: 0 } },
+  { key: '-y', axis: { x: 0, y: -1, z: 0 } },
+  { key: '+z', axis: { x: 0, y: 0, z: 1 } },
+  { key: '-z', axis: { x: 0, y: 0, z: -1 } }
+]
+
+function axisKeyOf(axis: Vec3): string | undefined {
+  return JOINT_AXES.find(one => one.axis.x === axis.x && one.axis.y === axis.y && one.axis.z === axis.z)?.key
+}
 
 /**
  * 고른 부품의 속성.
@@ -291,9 +319,60 @@ export class FigureInspector extends localize(i18next)(LitElement) {
         grid-template-columns: repeat(3, 1fr);
         gap: 4px;
       }
+      /*
+        값이 둘인 줄은 셋으로 나누지 않는다. 가동 범위를 세 칸짜리 줄에 넣었더니 칸이 폭의 1/3 이라
+        「최소」라는 말과 -120 이 한 칸에 못 들어가 숫자가 잘렸다.
+      */
+      div[double] {
+        display: grid;
+        grid-template-columns: repeat(2, 1fr);
+        gap: 4px;
+      }
+      /* 칸 아래에 붙는 한 줄짜리 행동. 칸과 같은 폭으로 둬야 한 묶음으로 읽힌다. */
+      button[fit] {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        gap: 4px;
+        width: 100%;
+        margin-top: 4px;
+        padding: 3px 8px;
+        font: inherit;
+        font-size: 0.72rem;
+        color: var(--md-sys-color-on-surface);
+        background-color: var(--md-sys-color-surface-container);
+        border: 1px solid var(--md-sys-color-outline-variant);
+        border-radius: 6px;
+        cursor: pointer;
+      }
+      /* 고친 칸 바로 아래에 붙는 말. 막는 것은 오류 색, 알리는 것은 조용한 색. */
+      p[contract] {
+        display: flex;
+        gap: 4px;
+        margin: 4px 0 0;
+        font-size: 0.68rem;
+        line-height: 1.4;
+        color: var(--md-sys-color-on-surface-variant);
+      }
+      p[contract][blocking] {
+        color: var(--md-sys-color-error);
+      }
+      p[contract] md-icon {
+        --md-icon-size: 14px;
+        flex: none;
+      }
+
+      button[fit]:hover {
+        background-color: var(--md-sys-color-surface-container-high);
+      }
+      button[fit] md-icon {
+        --md-icon-size: 15px;
+      }
       div[field] + div[field],
       div[triple] + div[field],
       div[field] + div[triple],
+      div[double] + div[field],
+      div[field] + div[double],
       div[inline-field] + div[inline-field],
       div[inline-field] + div[field],
       div[field] + div[inline-field],
@@ -790,6 +869,16 @@ export class FigureInspector extends localize(i18next)(LitElement) {
   @property({ type: Object }) draft?: FigureDraft
   /** 초안 위의 부품들. 씬 모델 그대로다. */
   @property({ type: Array }) parts: PartModel[] = []
+
+  /**
+   * 이 고침이 이미 놓인 인스턴스에 무엇을 하나 — 발행된 도형에만 있다(ADR-0063 결정 3).
+   *
+   * 발행 문에서만 말하면 저작자는 열 군데를 고친 뒤에 듣는다. 고치는 칸 옆에서 말한다.
+   */
+  @property({ type: Array }) contract: ContractChange[] = []
+
+  /** 견주지 못한 까닭. 빈 목록과 뜻이 다르다 — 「깨지 않는다」가 아니라 「모른다」다. */
+  @property({ type: String }) contractFailure?: string
   @property({ type: Number }) selected = -1
 
   /** `part` 는 HTMLElement 의 속성(DOMTokenList)이다 — 가리면 형이 어긋난다. */
@@ -820,7 +909,7 @@ export class FigureInspector extends localize(i18next)(LitElement) {
       묶음은 아예 나오지 않는다 — 해 둬도 아무 일도 안 일어나는 칸을 보여 주지 않는다.
     */
     return html`
-      ${this.renderFigure(true)} ${this.renderIdentity(shown)} ${this.renderRole(shown)}
+      ${this.renderFigure(true)} ${this.renderIdentity(shown)} ${this.renderRole(shown)} ${this.renderJoint(shown)}
       ${this.renderPlacement(shown)} ${this.renderShape(shown)} ${this.renderMaterial(shown)}
       ${this.renderBehaviour(shown)}
     `
@@ -884,6 +973,185 @@ export class FigureInspector extends localize(i18next)(LitElement) {
     `
   }
 
+  /**
+   * How this part hangs from another and moves relative to it (ADR-0066).
+   *
+   * The parent is written on the part. The joint says how the part moves relative to that parent, and the
+   * parameter it comes with is what drives it; the preview shows that parameter as a slider.
+   */
+  private renderJoint(part: FigurePart) {
+    const joint = jointOf(this.draft, part.name)
+    const choices = parentChoices(this.parts, part.name)
+    const unit = joint?.type === 'prismatic' ? 'mm' : 'deg'
+    const axisKey = joint ? axisKeyOf(joint.axis) : undefined
+    const driver = joint
+      ? this.draft?.parameters?.find(one => one.clip?.channels?.some(channel => channel.target === joint.name))
+      : undefined
+
+    return html`
+      <section>
+        <h3>${i18next.t('figure.label.joint')}${this.help('figure.text.joint-explained')}</h3>
+
+        <div inline-field>
+          <label>${i18next.t('figure.label.joint-parent')}</label>
+          <select @change=${(e: Event) => this.setParent((e.target as HTMLSelectElement).value)}>
+            <option value="" ?selected=${part.parent === undefined}>${i18next.t('figure.label.joint-parent-none')}</option>
+            ${part.parent !== undefined && !choices.includes(part.parent)
+              ? html`<option value=${part.parent} selected>${part.parent}</option>`
+              : nothing}
+            ${choices.map(name => html`<option value=${name} ?selected=${name === part.parent}>${name}</option>`)}
+          </select>
+        </div>
+
+        <div inline-field>
+          <label>${i18next.t('figure.label.joint-type')}</label>
+          <select @change=${(e: Event) => this.setJointType(part, (e.target as HTMLSelectElement).value)}>
+            <option value="" ?selected=${!joint}>${i18next.t('figure.label.joint-type-none')}</option>
+            ${(JOINT_TYPES as readonly JointType[]).map(
+              type => html`<option value=${type} ?selected=${joint?.type === type}>${i18next.t('figure.label.joint-type-' + type)}</option>`
+            )}
+          </select>
+        </div>
+
+        ${joint
+          ? html`
+              <div inline-field>
+                <label>${i18next.t('figure.label.joint-axis')}</label>
+                <select @change=${(e: Event) => this.setJointAxis(joint.name, (e.target as HTMLSelectElement).value)}>
+                  ${axisKey === undefined
+                    ? html`<option value="" selected>${joint.axis.x}, ${joint.axis.y}, ${joint.axis.z}</option>`
+                    : nothing}
+                  ${JOINT_AXES.map(one => html`<option value=${one.key} ?selected=${one.key === axisKey}>${one.key.toUpperCase()}</option>`)}
+                </select>
+              </div>
+
+              <div vector-row>
+                <label>${i18next.t('figure.label.joint-origin')}</label>
+                <div triple>
+                  ${(['x', 'y', 'z'] as const).map(axis =>
+                    this.number(axis.toUpperCase(), joint.origin[axis], value =>
+                      this.tellDraft(patchJoint(this.draft!, joint.name, { origin: { ...joint.origin, [axis]: value } }))
+                    )
+                  )}
+                </div>
+              </div>
+
+              ${joint.limits
+                ? html`
+                    <div vector-row>
+                      <label>${i18next.t('figure.label.joint-limits-' + unit)}</label>
+                      <div double>
+                        ${this.number(i18next.t('figure.label.joint-limit-min'), joint.limits.min, value =>
+                          this.tellDraft(patchJoint(this.draft!, joint.name, { limits: { ...joint.limits!, min: value } }))
+                        )}
+                        ${this.number(i18next.t('figure.label.joint-limit-max'), joint.limits.max, value =>
+                          this.tellDraft(patchJoint(this.draft!, joint.name, { limits: { ...joint.limits!, max: value } }))
+                        )}
+                      </div>
+                    </div>
+                    ${joint.limits.min > 0 || joint.limits.max < 0
+                      ? html`<p warn>${i18next.t('figure.text.joint-limits-must-include-zero')}</p>`
+                      : nothing}
+                  `
+                : nothing}
+
+              <p quiet>
+                ${driver
+                  ? i18next.t('figure.text.joint-driven-by', { name: driver.label ?? driver.name })
+                  : i18next.t('figure.text.joint-not-driven')}
+              </p>
+            `
+          : nothing}
+      </section>
+    `
+  }
+
+  private setParent(name: string) {
+    this.change(part => {
+      const { parent: _dropped, ...rest } = part
+      return name === '' ? (rest as FigurePart) : { ...rest, parent: name }
+    })
+  }
+
+  /**
+   * 기준 상자를 고친다 — 부품은 저장되는 자리에 그대로 둔 채(`base-box.ts`).
+   *
+   * 초안과 부품이 함께 바뀌므로 둘을 한 번에 올린다. 따로 올리면 되돌리기가 둘로 갈리고, 그 사이
+   * 한 번만 되돌린 화면은 부품이 반쯤 밀린 모습이 된다.
+   */
+  /**
+   * 기준 상자를 고친 것이 **이미 놓인 인스턴스에 무엇을 하나** — 고친 칸 바로 아래에서 말한다.
+   *
+   * 막는 것과 알리는 것을 가른다. 비율이 달라지면 놓인 것이 찌그러지므로 발행이 막히고, 크기만
+   * 달라지는 것은 실척이 어긋날 뿐이라 알리기만 한다. 까닭은 형식이 적은 것을 그대로 옮긴다 —
+   * 여기서 다시 쓰면 두 벌이 되고 곧 갈린다.
+   */
+  private renderBaseContract() {
+    if (this.contractFailure) {
+      return html`<p contract>
+        <md-icon>help</md-icon>
+        <span>${i18next.t('figure.text.contract-not-compared', { why: this.contractFailure })}</span>
+      </p>`
+    }
+
+    const mine = this.contract.filter(one => one.code === 'base-ratio-changed' || one.code === 'base-size-changed')
+    if (mine.length === 0) return nothing
+
+    return html`${mine.map(
+      one => html`<p contract ?blocking=${one.blocking}>
+        <md-icon>${one.blocking ? 'block' : 'info'}</md-icon>
+        <span><b>${one.message}</b> ${one.why}</span>
+      </p>`
+    )}`
+  }
+
+  private resizeBase(patch: Partial<BaseSize>) {
+    if (!this.draft) return
+
+    const next = resizeBase(this.draft, this.parts, { ...baseOf(this.draft), ...patch })
+    if (next.draft === this.draft) return
+
+    this.dispatchEvent(
+      new CustomEvent('resize-base', {
+        detail: { draft: next.draft, parts: next.parts },
+        bubbles: true,
+        composed: true
+      })
+    )
+  }
+
+  /** 부품 전부를 감싸는 가장 작은 상자로. 맞출 것이 없으면 아무 일도 안 한다. */
+  private fitBaseToParts() {
+    if (!this.draft) return
+    const fitted = baseFittingParts(this.draft, this.parts)
+    if (fitted) this.resizeBase(fitted)
+  }
+
+  private setJointType(part: FigurePart, value: string) {
+    if (!this.draft) return
+
+    /* 붙은 부품을 함께 준다 — 새 관절이 둘이 맞닿는 자리에 서려면 그쪽 치수를 알아야 한다. */
+    const parent = part.parent ? this.parts.find(one => one.name === part.parent) : undefined
+    this.tellDraft(
+      setJointType(
+        this.draft,
+        part,
+        value === '' ? undefined : (value as JointType),
+        parent ? partToFigure(parent, this.draft) : undefined
+      )
+    )
+  }
+
+  private setJointAxis(name: string, key: string) {
+    const choice = JOINT_AXES.find(one => one.key === key)
+    if (!choice || !this.draft) return
+    this.tellDraft(patchJoint(this.draft, name, { axis: { ...choice.axis } }))
+  }
+
+  private tellDraft(draft: FigureDraft) {
+    this.dispatchEvent(new CustomEvent('update-draft', { detail: { draft }, bubbles: true, composed: true }))
+  }
+
   /**
    * 역할 하나를 켜고 끈다.
    *
@@ -1007,6 +1275,27 @@ export class FigureInspector extends localize(i18next)(LitElement) {
           ${this.helpHint('figure.text.placement-explained')}
         </div>
 
+        <!--
+          기준 상자 — **고치는 길이 화면에 있어야 한다.** 부품이 이 상자를 넘으면 발행이 막히고,
+          고치는 방법은 상자 숫자를 키우는 것이다(ADR-0044 ④). 그 칸이 없어서 저작자는 넘쳤다는
+          말만 듣고 고칠 자리를 못 찾았다.
+        -->
+        <div field>
+          <label>${i18next.t('figure.label.base-box')}${this.helpButton('figure.text.base-box-explained')}</label>
+          <div triple>
+            ${this.number('X', this.draft?.width ?? 0, value => this.resizeBase({ width: value }), 1)}
+            ${this.number('Y', this.draft?.depth ?? 0, value => this.resizeBase({ depth: value }), 1)}
+            ${this.number('Z', this.draft?.height ?? 0, value => this.resizeBase({ height: value }), 1)}
+          </div>
+          ${this.parts.length > 0
+            ? html`<button fit @click=${() => this.fitBaseToParts()} title=${i18next.t('figure.text.fit-base-explained')}>
+                <md-icon>fit_screen</md-icon>${i18next.t('figure.button.fit-base-to-parts')}
+              </button>`
+            : nothing}
+          ${this.renderBaseContract()}
+          ${this.helpHint('figure.text.base-box-explained')}
+        </div>
+
         <div inline-field>
           <label>${i18next.t('figure.label.category')}${this.helpButton('figure.text.category-explained')}</label>
           <input

package/client/modeller/figure-preview.ts

@@ -6,8 +6,10 @@ 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 { DEFAULT_VIEW, previewBoardDepth, sceneLook, WORKBENCH } from './figure-view.js'
 import type { ViewSettings } from './figure-view.js'
+import { poseChanges } from './pose-defaults.js'
+import type { FigureDraft } from './figure-source.js'
 
 /**
  * 저작 중인 것을 **도면에 놓았을 때**의 모습.
@@ -144,6 +146,24 @@ export class FigurePreview extends localize(i18next)(LitElement) {
       align-items: center;
       gap: 8px;
     }
+    /*
+      막대 위에 놓는 단추. 자세를 만든 자리에 있어야 「지금 이것을 기본으로」가 읽힌다.
+      앉힐 것이 있을 때만 나오므로, 늘 서 있는 칸이 아니다.
+    */
+    div[clips] button[pose] {
+      align-self: stretch;
+      padding: 4px 8px;
+      font: inherit;
+      font-size: 0.7rem;
+      color: rgba(255, 255, 255, 0.92);
+      background-color: rgba(255, 255, 255, 0.14);
+      border: 1px solid rgba(255, 255, 255, 0.22);
+      border-radius: 5px;
+      cursor: pointer;
+    }
+    div[clips] button[pose]:hover {
+      background-color: rgba(255, 255, 255, 0.24);
+    }
     div[clips] span[drive] {
       opacity: 0.6;
       font-size: 0.66rem;
@@ -176,6 +196,14 @@ export class FigurePreview extends localize(i18next)(LitElement) {
   /** 저작 중인 것. 저장 형식으로 받는다 — 도면이 소비하는 것이 이 형식이다. */
   @property({ type: Object }) source?: FigureSource
 
+  /**
+   * 저작 중인 초안. **기본값이 지금 무엇인지 알려고만 쥔다** — 고치지 않는다.
+   *
+   * `source` 로도 파라미터를 읽을 수 있지만, 후보를 미리 볼 때는 `source` 가 후보의 것이고
+   * 초안은 열려 있는 도형의 것이다. 「이 자세를 기본으로」는 열려 있는 도형에만 뜻이 있다.
+   */
+  @property({ type: Object }) draft?: FigureDraft
+
   /**
    * 보기 설정. 저장되지 않는다(`figure-view.ts`).
    *
@@ -226,8 +254,23 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     clips: NonNullable<FigureSource['animations']>,
     parameters: NonNullable<FigureSource['parameters']>
   ) {
+    /*
+      지금 세운 자세를 기본값으로 앉히는 자리. **막대 옆에 둔다** — 자세를 만든 곳이 여기라,
+      값을 읽어 파라미터 칸으로 옮겨 적는 왕복이 없어진다. 앉힐 것이 없으면 아예 안 나온다.
+    */
+    const changes = poseChanges(this.draft, this.giving)
+
     return html`
       <div clips>
+        ${changes.length > 0
+          ? html`<button
+              pose
+              title=${i18next.t('figure.text.pose-as-default-explained')}
+              @click=${() => this.poseAsDefault()}
+            >
+              ${i18next.t('figure.button.pose-as-default')}
+            </button>`
+          : ''}
         ${parameters.map(parameter => {
           const range = parameter.range
           const value = this.giving[parameter.name] ?? parameter.default ?? range?.min ?? 0
@@ -292,6 +335,18 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     this.tellInstances('parameters', this.giving)
   }
 
+  /**
+   * 세운 자세를 기본값으로 — **셈은 여기서 하지 않는다.**
+   *
+   * 초안을 쥐고 있는 것은 페이지이고, 되돌리기와 「저장 안 됨」도 거기서 매긴다. 여기서
+   * 초안을 만들어 보내면 그 셋이 두 곳으로 갈린다. 민 값만 올린다.
+   */
+  private poseAsDefault(): void {
+    this.dispatchEvent(
+      new CustomEvent('pose-as-default', { detail: { values: { ...this.giving } }, bubbles: true, composed: true })
+    )
+  }
+
   private tellInstances(key: 'clips' | 'parameters', values: Record<string, number>): void {
     for (const component of this.scene?.root?.components ?? []) {
       component.set?.(key, { ...values })
@@ -435,7 +490,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
           어느 경우에도 담기는 경계만 잡는다. 바닥 기반은 가장 큰 것의 키까지, 천정 기반은
           천장까지다. 배치를 높이로 옮기는 계산을 여기서 다시 쓰면 그것이 두 벌째가 된다.
         */
-        depth: Math.round(Math.max(view.ceilingHeight, base.y * biggest) * 1.1)
+        depth: previewBoardDepth(source, view.ceilingHeight, biggest)
       }
 
       this.scene = create({

package/client/modeller/figure-report.ts

@@ -9,7 +9,7 @@ import { ScrollbarStyles } from '@operato/styles'
 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'
+import { capacityOf, MEASURED } from './scene-budget.js'
 import { maturityOf } from './maturity.js'
 import type { MaturityAxis } from './maturity.js'
 import type { FigureCapacity } from './scene-budget.js'
@@ -507,8 +507,9 @@ export class FigureReport extends localize(i18next)(LitElement) {
    * 직접 답하지 않는다 — 형상이 선언된 한도 안인지를 말할 뿐이다. 그래서 개수를
    * 머리에 올리고 등급은 옆의 badge 로 내린다.
    *
-   * 근거를 함께 낸다. 이 개수의 분모는 실측이 아니라 설계 문서의 목표치이고(미결
-   * D-20), 그 사실이 화면에 없으면 재 본 값처럼 읽힌다.
+   * 근거를 함께 낸다. 묶음으로 갈리는 개수의 분모는 **실측**이고(2026-09-18, Apple M5), 잰
+   * 기계와 날짜를 함께 적는다 — 적지 않으면 어디서나 참인 수로 읽힌다. 삼각형 쪽은 아직 설계
+   * 문서의 목표치라 그렇다고 적는다.
    */
   private renderVerdict() {
     const score = this.score
@@ -544,7 +545,11 @@ export class FigureReport extends localize(i18next)(LitElement) {
             per: capacity.per.toLocaleString(),
             budget: capacity.budget.toLocaleString()
           })}
-          <em>${i18next.t('figure.text.budget-not-measured-yet')}</em>
+          <em>
+            ${capacity.bound === 'groups'
+              ? i18next.t('figure.text.budget-measured-on', { gpu: MEASURED.gpu, on: MEASURED.on })
+              : i18next.t('figure.text.budget-not-measured-yet')}
+          </em>
         </p>
       </section>
     `

package/client/modeller/figure-side.ts

@@ -10,7 +10,7 @@ import { css, html, LitElement } from 'lit'
 import { customElement, property, state } from 'lit/decorators.js'
 
 import { i18next, localize } from '@operato/i18n'
-import type { FigureSource } from '@hatiolab/figure-model'
+import type { ContractChange, FigureSource } from '@hatiolab/figure-model'
 
 import type { FigureDraft, PartModel } from './figure-source.js'
 import { DEFAULT_VIEW } from './figure-view.js'
@@ -159,6 +159,12 @@ export class FigureSide extends localize(i18next)(LitElement) {
   @property({ type: Object }) draft?: FigureDraft
   @property({ type: Array }) parts: PartModel[] = []
   @property({ type: Object }) source?: FigureSource
+
+  /** 이 고침이 이미 놓인 인스턴스에 무엇을 하나(ADR-0063 결정 3). 발행 전 도형에는 비어 있다. */
+  @property({ type: Array }) contract: ContractChange[] = []
+
+  /** 견주지 못한 까닭. 있으면 화면이 「확인하지 못했다」로 말한다. */
+  @property({ type: String }) contractFailure?: string
   @property({ type: Number }) selected = -1
   /** 저작 화면의 보기 설정. 자산이 아니라 작업대다 — 저장되지 않는다. */
   @property({ type: Object }) view: ViewSettings = DEFAULT_VIEW
@@ -198,6 +204,8 @@ export class FigureSide extends localize(i18next)(LitElement) {
         .figureTags=${this.figureTags}
         .draft=${this.draft}
         .parts=${this.parts}
+        .contract=${this.contract}
+        .contractFailure=${this.contractFailure}
         .selected=${this.selected}
       ></figure-inspector>
 

package/client/modeller/figure-source.ts

@@ -128,6 +128,12 @@ export interface FigureDraft {
    * 주나**를 말하는 다른 칸이다.
    */
   capabilities?: FigureSource['capabilities']
+  /**
+   * How parts move relative to their parents (ADR-0066). Kept in figure coordinates as stored, the same
+   * terms the inspector shows. Carried even when nothing edits them, so opening and saving never drops
+   * them.
+   */
+  joints?: FigureSource['joints']
 }
 
 /** 부품 컴포넌트의 상태. 씬의 용어 그대로다. */
@@ -168,6 +174,14 @@ export interface PartModel {
    */
   hidden?: boolean
 
+  /**
+   * 씬이 이것을 **집지 않는다** — 클릭·마퀴·기즈모 어디에도 안 걸린다.
+   *
+   * 저작면에만 서는 것(관절 부채꼴)이 쓴다. 저장 형식에는 없는 칸이라 `toFigureSource` 가
+   * 싣지 않는다.
+   */
+  locked?: boolean
+
   /** 색 토큰 이름 (`palette.primary` 등). */
   token?: string
   /*
@@ -202,6 +216,8 @@ export interface PartModel {
    * 청사진에서는 `groups` 가 아니라 `anchors` 로 간다.
    */
   capability?: FigurePart['capability']
+  /** The part this one is attached to (ADR-0066). The one place a parent is written. */
+  parent?: FigurePart['parent']
 }
 
 const RAD_TO_DEG = 180 / Math.PI
@@ -293,7 +309,8 @@ export function toFigureSource(draft: FigureDraft, parts: PartModel[]): FigureSo
     parts: parts.map(part => partTo(part, half)),
     animations: draft.animations,
     parameters: draft.parameters,
-    capabilities: draft.capabilities
+    capabilities: draft.capabilities,
+    joints: draft.joints?.length ? draft.joints : undefined
   }) as FigureSource
 }
 
@@ -342,7 +359,8 @@ function partTo(part: PartModel, half: Vec3): FigurePart {
     anchor: part.anchor,
     repeat: part.repeat,
     label: part.label,
-    capability: part.capability
+    capability: part.capability,
+    parent: part.parent
   }) as FigurePart
 }
 
@@ -362,7 +380,8 @@ export function fromFigureSource(source: FigureSource): { draft: FigureDraft; pa
     /* Opened as stored. A legacy `drive: 'hold'` clip is refused by the format now; stored ones were migrated. */
     animations: source.animations?.length ? source.animations : undefined,
     parameters: source.parameters?.length ? source.parameters : undefined,
-    capabilities: source.capabilities
+    capabilities: source.capabilities,
+    joints: source.joints?.length ? source.joints : undefined
   }) as FigureDraft
 
   return { draft, parts: source.parts.map(part => partFrom(part, half)) }
@@ -412,6 +431,7 @@ function partFrom(part: FigurePart, half: Vec3): PartModel {
     anchor: part.anchor,
     repeat: part.repeat,
     label: part.label,
-    capability: part.capability
+    capability: part.capability,
+    parent: part.parent
   }) as PartModel
 }

package/client/modeller/figure-view.ts

@@ -130,3 +130,23 @@ export const DEFAULT_VIEW: ViewSettings = {
   dirShadowEnabled: true,
   hemiIntensity: 4.0
 }
+
+/**
+ * How tall the preview board is: enough room for the tallest instance where the figure actually stands.
+ *
+ * A floor or center figure stands on the floor, so the tallest instance is the whole height. Only a
+ * ceiling figure needs the room up to the ceiling. The board used to reach the ceiling for every figure,
+ * which made a 920 tall AGV preview 4400 tall.
+ *
+ * This is an envelope, not a placement rule: where each instance goes is still the scene's
+ * (`FigureRealObject.effectiveZPos`), and the camera fits what the scene drew.
+ */
+export function previewBoardDepth(
+  figure: { placement?: 'floor' | 'ceiling' | 'center'; base: { y: number } },
+  ceilingHeight: number,
+  factor: number
+): number {
+  const tallest = figure.base.y * factor
+  const reach = figure.placement === 'ceiling' ? Math.max(ceilingHeight, tallest) : tallest
+  return Math.round(reach * 1.1)
+}