@things-factory/figure-ui 10.1.26 → 10.1.27

package/client/modeller/figure-animations.ts

@@ -6,7 +6,7 @@ import { i18next, localize } from '@operato/i18n'
 import { ScrollbarStyles } from '@operato/styles'
 
 import { AXES, CHANNEL_PATHS, INTERPOLATIONS, LIMITS } from '@hatiolab/figure-model'
-import type { ChannelPath, Vec3 } from '@hatiolab/figure-model'
+import type { ChannelPath, JointChannel, PartChannel, Vec3 } from '@hatiolab/figure-model'
 
 import type { FigureDraft, PartModel } from './figure-source.js'
 
@@ -44,7 +44,13 @@ import type { FigureDraft, PartModel } from './figure-source.js'
 type Clip = NonNullable<FigureDraft['animations']>[number]
 type Parameter = NonNullable<FigureDraft['parameters']>[number]
 type Channel = Clip['channels'][number]
-type Keyframe = Channel['keys'][number]
+type Keyframe = PartChannel['keys'][number]
+type JointKey = JointChannel['keys'][number]
+
+/** A channel that drives a joint names the joint and carries one number per key (ADR-0066). */
+function isJointChannel(channel: Channel): channel is JointChannel {
+  return channel.path === undefined
+}
 
 /** 어느 목록의 몇째인가. 채널·키 편집기가 둘을 함께 쓴다. */
 type MotionKind = 'clip' | 'parameter'
@@ -357,6 +363,11 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
     return this.parts.map(part => part.name).filter(name => !!name)
   }
 
+  /** Joints a channel can drive instead of a part (ADR-0066). */
+  private get joints(): NonNullable<FigureDraft['joints']> {
+    return this.draft?.joints ?? []
+  }
+
   /**
    * 몇 부품이 움직이나 — 채널이 가리키는 **서로 다른 부품**의 수.
    *
@@ -594,24 +605,48 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
    * 검증은 저장할 때 말하고 여기서는 **그 자리에서** 보여 준다.
    */
   private renderChannel(kind: MotionKind, channel: Channel, at: number, j: number): TemplateResult {
-    const orphan = !this.partNames.includes(channel.target)
+    const joint = this.joints.find(one => one.name === channel.target)
+    const orphan = !this.partNames.includes(channel.target) && !joint
+    const target = html`
+      <div row>
+        <label>${i18next.t('figure.label.channel-target')}</label>
+        <select
+          .value=${live(channel.target ?? '')}
+          @change=${(e: Event) => this.retarget(kind, at, j, (e.target as HTMLSelectElement).value)}
+        >
+          ${orphan ? html`<option value=${channel.target}>${channel.target}</option>` : nothing}
+          <optgroup label=${i18next.t('figure.label.channel-target-parts')}>
+            ${this.partNames.map(name => html`<option value=${name}>${name}</option>`)}
+          </optgroup>
+          ${this.joints.length > 0
+            ? html`<optgroup label=${i18next.t('figure.label.channel-target-joints')}>
+                ${this.joints.map(one => html`<option value=${one.name}>${one.name}</option>`)}
+              </optgroup>`
+            : nothing}
+        </select>
+        <button plain @click=${() => this.removeChannel(kind, at, j)} title=${i18next.t('figure.button.remove')}>
+          <md-icon>close</md-icon>
+        </button>
+      </div>
+    `
+
+    /* A joint channel has no path or pivot: the joint says what moves. Each key is the joint coordinate. */
+    if (isJointChannel(channel)) {
+      const unit = joint?.type === 'prismatic' ? 'mm' : 'deg'
+      return html`
+        <div channel ?orphan=${orphan}>
+          ${target} ${orphan ? html`<p warn>${i18next.t('figure.text.channel-target-is-gone')}</p>` : nothing}
+          <p quiet>${i18next.t('figure.text.joint-channel-value-' + unit)}</p>
+          ${this.renderJointKeys(kind, channel, at, j, joint?.limits)}
+        </div>
+      `
+    }
+
     const turning = channel.path === 'rotation'
 
     return html`
       <div channel ?orphan=${orphan}>
-        <div row>
-          <label>${i18next.t('figure.label.channel-target')}</label>
-          <select
-            .value=${live(channel.target ?? '')}
-            @change=${(e: Event) => this.setChannel(kind, at, j, { target: (e.target as HTMLSelectElement).value })}
-          >
-            ${orphan ? html`<option value=${channel.target}>${channel.target}</option>` : nothing}
-            ${this.partNames.map(name => html`<option value=${name}>${name}</option>`)}
-          </select>
-          <button plain @click=${() => this.removeChannel(kind, at, j)} title=${i18next.t('figure.button.remove')}>
-            <md-icon>close</md-icon>
-          </button>
-        </div>
+        ${target}
 
         ${orphan ? html`<p warn>${i18next.t('figure.text.channel-target-is-gone')}</p>` : nothing}
 
@@ -649,7 +684,7 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
    * 그래서 경로가 rotation 일 때만 낸다. 언제나 내면 저작자가 옮김·배율에도 적고, 검증이
    * 저장할 때 「쓰이지 않는다」고 알린다. 안 보이면 적을 일이 없다.
    */
-  private renderPivot(kind: MotionKind, channel: Channel, at: number, j: number): TemplateResult {
+  private renderPivot(kind: MotionKind, channel: PartChannel, at: number, j: number): TemplateResult {
     const pivot = channel.pivot
     const on = pivot !== undefined
 
@@ -691,7 +726,76 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
    * 시각이 오름차순이어야 하는 것도 형식의 규칙이다. 여기서는 어긋난 줄을 붉게 내고 값을
    * 고치지는 않는다 — 저작자가 3 을 1 로 고치던 중일 수 있다.
    */
-  private renderKeys(kind: MotionKind, channel: Channel, at: number, j: number): TemplateResult {
+  /**
+   * Keys of a joint channel: a position and one joint coordinate each. A value outside the joint's limits
+   * is marked and left as typed; the format refuses it on save.
+   */
+  private renderJointKeys(
+    kind: MotionKind,
+    channel: JointChannel,
+    at: number,
+    j: number,
+    limits?: { min: number; max: number }
+  ): TemplateResult {
+    const keys = channel.keys ?? []
+    const onValues = kind === 'parameter'
+    const beyond = (key: JointKey) => !!limits && (key.value < limits.min || key.value > limits.max)
+
+    return html`
+      <table keys>
+        <tr>
+          <th>${i18next.t(onValues ? 'figure.label.key-at-value' : 'figure.label.key-at')}</th>
+          <th>${i18next.t('figure.label.joint-value')}</th>
+          <th></th>
+        </tr>
+        ${keys.map((key, k) => {
+          const backwards = k > 0 && key.at <= (keys[k - 1]!.at ?? 0)
+          return html`
+            <tr>
+              <td>
+                <input
+                  type="number"
+                  step=${onValues ? '0.05' : '0.1'}
+                  min="0"
+                  max=${onValues ? '1' : nothing}
+                  ?bad=${backwards || key.at < 0 || (onValues && key.at > 1)}
+                  .value=${live(String(key.at))}
+                  @change=${(e: Event) =>
+                    this.setJointKey(kind, at, j, k, { at: Math.max(0, Number((e.target as HTMLInputElement).value) || 0) })}
+                />
+              </td>
+              <td>
+                <input
+                  type="number"
+                  step="1"
+                  ?bad=${beyond(key)}
+                  .value=${live(String(key.value))}
+                  title=${beyond(key) ? i18next.t('figure.text.joint-value-beyond-limits') : ''}
+                  @change=${(e: Event) => this.setJointKey(kind, at, j, k, { value: Number((e.target as HTMLInputElement).value) || 0 })}
+                />
+              </td>
+              <td drop>
+                <button
+                  plain
+                  ?disabled=${keys.length <= 2}
+                  title=${keys.length <= 2 ? i18next.t('figure.text.two-keys-at-least') : i18next.t('figure.button.remove')}
+                  @click=${() => this.removeKey(kind, at, j, k)}
+                >
+                  <md-icon>close</md-icon>
+                </button>
+              </td>
+            </tr>
+          `
+        })}
+      </table>
+      ${keys.some(beyond) ? html`<p warn>${i18next.t('figure.text.joint-value-beyond-limits')}</p>` : nothing}
+      <button @click=${() => this.addKey(kind, at, j)}>
+        <md-icon>add</md-icon>${i18next.t('figure.button.add-key')}
+      </button>
+    `
+  }
+
+  private renderKeys(kind: MotionKind, channel: PartChannel, at: number, j: number): TemplateResult {
     const keys = channel.keys ?? []
     /*
       Keys on a parameter curve sit on the 0..1 value span (ADR-0051). A key above 1 is unreachable and
@@ -948,11 +1052,36 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
     ])
   }
 
-  private setChannel(kind: MotionKind, at: number, j: number, patch: Partial<Channel>): void {
+  /**
+   * Points a channel at another part or joint. Crossing between the two changes the channel's shape: a
+   * joint channel has no path and one number per key, a part channel a path and a vector. The key positions
+   * are kept, since they are the author's timing; values restart at the rest pose.
+   */
+  private retarget(kind: MotionKind, at: number, j: number, target: string): void {
     const channel = this.channelsOf(kind, at)[j]
     if (!channel) return
+    const toJoint = this.joints.some(one => one.name === target)
+
+    if (toJoint && !isJointChannel(channel)) {
+      const next: JointChannel = { target, keys: channel.keys.map(key => ({ at: key.at, value: 0 })) }
+      if (channel.interpolation !== undefined) next.interpolation = channel.interpolation
+      this.patchChannel(kind, at, j, next)
+      return
+    }
+    if (!toJoint && isJointChannel(channel)) {
+      const next: PartChannel = { target, path: 'translation', keys: channel.keys.map(key => ({ at: key.at, value: startValue('translation') })) }
+      if (channel.interpolation !== undefined) next.interpolation = channel.interpolation
+      this.patchChannel(kind, at, j, next)
+      return
+    }
+    this.patchChannel(kind, at, j, { ...channel, target } as Channel)
+  }
 
-    const next: Channel = { ...channel, ...patch }
+  private setChannel(kind: MotionKind, at: number, j: number, patch: Partial<PartChannel>): void {
+    const channel = this.channelsOf(kind, at)[j]
+    if (!channel || isJointChannel(channel)) return
+
+    const next: PartChannel = { ...channel, ...patch }
     /* `undefined` 를 얹는 것은 지우는 뜻이다. 남겨 두면 저장 형식에 빈 칸이 실린다. */
     if ('pivot' in patch && patch.pivot === undefined) delete next.pivot
     this.patchChannel(kind, at, j, next)
@@ -967,10 +1096,10 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
    */
   private setPath(kind: MotionKind, at: number, j: number, path: ChannelPath): void {
     const channel = this.channelsOf(kind, at)[j]
-    if (!channel) return
+    if (!channel || isJointChannel(channel)) return
 
     const crossing = (channel.path === 'scale') !== (path === 'scale')
-    const next: Channel = {
+    const next: PartChannel = {
       ...channel,
       path,
       keys: crossing ? channel.keys.map(key => ({ at: key.at, value: startValue(path) })) : channel.keys
@@ -994,6 +1123,19 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
     const channel = this.channelsOf(kind, at)[j]
     if (!channel) return
 
+    if (isJointChannel(channel)) {
+      const keys = channel.keys
+      const end = keys[keys.length - 1]
+      if (kind === 'parameter' && keys.length >= 2) {
+        const before = keys[keys.length - 2]!
+        const middle: JointKey = { at: (before.at + end!.at) / 2, value: before.value }
+        this.patchChannel(kind, at, j, { ...channel, keys: [...keys.slice(0, -1), middle, end!] })
+        return
+      }
+      this.patchChannel(kind, at, j, { ...channel, keys: [...keys, { at: (end?.at ?? 0) + 1, value: end?.value ?? 0 }] })
+      return
+    }
+
     const last = channel.keys[channel.keys.length - 1]
 
     /*
@@ -1010,9 +1152,15 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
     this.patchChannel(kind, at, j, { ...channel, keys: [...channel.keys, key] })
   }
 
+  private setJointKey(kind: MotionKind, at: number, j: number, k: number, patch: Partial<JointKey>): void {
+    const channel = this.channelsOf(kind, at)[j]
+    if (!channel || !isJointChannel(channel)) return
+    this.patchChannel(kind, at, j, { ...channel, keys: channel.keys.map((key, i) => (i === k ? { ...key, ...patch } : key)) })
+  }
+
   private setKey(kind: MotionKind, at: number, j: number, k: number, patch: Partial<Keyframe>): void {
     const channel = this.channelsOf(kind, at)[j]
-    if (!channel) return
+    if (!channel || isJointChannel(channel)) return
     this.patchChannel(kind, at, j, {
       ...channel,
       keys: channel.keys.map((key, i) => (i === k ? { ...key, ...patch } : key))
@@ -1023,6 +1171,6 @@ export class FigureAnimations extends localize(i18next)(LitElement) {
   private removeKey(kind: MotionKind, at: number, j: number, k: number): void {
     const channel = this.channelsOf(kind, at)[j]
     if (!channel || channel.keys.length <= 2) return
-    this.patchChannel(kind, at, j, { ...channel, keys: channel.keys.filter((_, i) => i !== k) })
+    this.patchChannel(kind, at, j, { ...channel, keys: (channel.keys as { at: number }[]).filter((_, i) => i !== k) } as Channel)
   }
 }

package/client/modeller/figure-inspector.ts

@@ -16,13 +16,38 @@ 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,
+  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'
+
+/** 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
+}
 
 /**
  * 고른 부품의 속성.
@@ -820,7 +845,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 +909,121 @@ 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 triple>
+                        ${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 }
+    })
+  }
+
+  private setJointType(part: FigurePart, value: string) {
+    if (!this.draft) return
+    this.tellDraft(setJointType(this.draft, part, value === '' ? undefined : (value as JointType)))
+  }
+
+  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 }))
+  }
+
   /**
    * 역할 하나를 켜고 끈다.
    *

package/client/modeller/figure-preview.ts

@@ -6,7 +6,7 @@ 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'
 
 /**
@@ -435,7 +435,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-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']
 }
 
 /** 부품 컴포넌트의 상태. 씬의 용어 그대로다. */
@@ -202,6 +208,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 +301,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 +351,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 +372,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 +423,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)
+}