@things-factory/figure-ui 10.1.208 → 10.1.210

package/client/modeller/figure-size-editor.ts

@@ -0,0 +1,196 @@
+import { LitElement, html, css, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { live } from 'lit/directives/live.js'
+import { i18next, localize } from '@operato/i18n'
+import type { FigureAuthoringAction } from '@hatiolab/figure-model'
+import { SidePanelStyles } from '@things-factory/figure-viewer/dist-client/side-panel-styles.js'
+import type { FigureRevision } from './revision.js'
+import { AXES, followOf, followableAxes, measureNow, type Axis } from './links.js'
+import {
+  measureFactor,
+  sameSizeSource,
+  sizeInputOf,
+  sizeRelationOf,
+  sizeRelationSteps,
+  sourceMeasureOf,
+  suggestedSizeSource,
+  type SizeMode,
+  type SizeSource
+} from './size-response.js'
+
+/**
+ * A part's measures and what each follows, one row an axis (ADR-0159 3). Made to follow, a measure takes what the part
+ * hangs from, along the axis its own axis lies on as it stands -- the author turns it on, nothing more. Another source
+ * is there when asked for, or when there is no such axis (the part lies at an angle) or the measure already follows
+ * something else; each way of following says what it will do, in millimetres.
+ */
+@customElement('figure-size-editor')
+export class FigureSizeEditor extends localize(i18next)(LitElement) {
+  @property({ attribute: false }) revision?: FigureRevision
+  @property() partId = ''
+  @property({ type: Boolean }) locked = false
+  @state() private error = ''
+  /* Rows whose source the author asked to choose: `<part>:<axis>`. */
+  @state() private choosing = new Set<string>()
+  private equivalentModes = new Map<string, 'ratio' | 'difference'>()
+  static styles = [SidePanelStyles, css`
+    :host { display: block; min-width: 0; }
+    .heading, .fields {
+      display: grid;
+      grid-template-columns: 24px minmax(55px, .85fr) 32px minmax(65px, 1fr) 42px;
+      gap: 6px;
+      align-items: center;
+    }
+    .heading { color: var(--md-sys-color-on-surface-variant); padding-bottom: 6px; }
+    .dimension { padding: 3px 0; }
+    .variable { display: flex; align-items: center; justify-content: center; min-height: var(--figure-control-height); }
+    .source { grid-column: 4 / -1; display: flex; align-items: center; gap: 6px; min-width: 0; }
+    .source span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .modes { margin: 4px 0 2px 30px; }
+    .result { margin: 0 0 6px 30px; }
+    [role=alert] { color: var(--md-sys-color-error); }
+  `]
+  private apply(steps: FigureAuthoringAction[]) {
+    if (this.locked) return
+    this.error = ''
+    this.dispatchEvent(new CustomEvent('size-recipe', { detail: { steps }, bubbles: true, composed: true }))
+    this.requestUpdate()
+  }
+  private configure(axis: Axis, source: SizeSource, mode: 'ratio' | 'difference', mm?: number) {
+    if (this.locked || this.revision?.asset.sizing === 'uniform') return
+    try {
+      this.apply(sizeRelationSteps(this.revision!, this.partId, axis, source, mode, mm))
+      this.equivalentModes.set(`${this.partId}:${axis}`, mode)
+    } catch (e) {
+      this.error = i18next.t((e as Error).message === 'SIZE_VALUE' ? 'figure.text.size-invalid' : 'figure.text.size-unavailable-source')
+      this.requestUpdate()
+    }
+  }
+  private choose(key: string, on: boolean) {
+    const next = new Set(this.choosing)
+    if (on) next.add(key)
+    else next.delete(key)
+    this.choosing = next
+  }
+  /** What a source is called on the panel: the figure, or the part, with the axis it is measured along. */
+  private sourceWords(source: SizeSource) {
+    return `${source.of === 'instance' ? i18next.t('figure.label.size-figure') : source.part} ${source.axis.toUpperCase()}`
+  }
+  /** What following this way does, in millimetres: the share it is of its source, or the difference it keeps. */
+  private resultWords(revision: FigureRevision, source: SizeSource, mode: 'ratio' | 'difference', mm: number | undefined) {
+    const theirs = sourceMeasureOf(revision, source)
+    if (mm === undefined || theirs === undefined || !(theirs > 0)) return nothing
+    const words = { source: this.sourceWords(source), size: Number(theirs.toFixed(1)) }
+    if (mode === 'ratio') return i18next.t('figure.text.size-ratio-result', { ...words, pct: Number(((mm / theirs) * 100).toFixed(1)) })
+    const gap = Number((theirs - mm).toFixed(1))
+    if (Math.abs(gap) < 0.05) return i18next.t('figure.text.size-difference-same', words)
+    return i18next.t(gap > 0 ? 'figure.text.size-difference-less' : 'figure.text.size-difference-more', { ...words, gap: Math.abs(gap) })
+  }
+  render() {
+    const revision = this.revision
+    if (!revision) return nothing
+    const asset = revision.asset
+    const axes = followableAxes(asset, this.partId)
+    const targets = asset.appearance.map(a => a.target).filter(p => p !== this.partId && followableAxes(asset, p).length)
+    const uniform = asset.sizing === 'uniform'
+    return html`
+      <div class="heading" aria-hidden="true">
+        <span>${i18next.t('figure.label.size-axis')}</span><span>${i18next.t('figure.label.size-measure')}</span><span>${i18next.t('figure.label.size-follows')}</span><span>${i18next.t('figure.label.size-source')}</span><span></span>
+      </div>
+      ${axes.map(axis => {
+        const key = `${this.partId}:${axis}`
+        const mm = measureNow(revision, this.partId, axis)
+        const relation = sizeRelationOf(revision, this.partId, axis)
+        const f = followOf(asset, this.partId, axis)
+        const source = relation.source
+        const suggested = suggestedSizeSource(asset, this.partId, axis)
+        let mode: SizeMode = relation.mode
+        if (source && (f.of === 'instance' || f.of === 'part') && !f.plus) {
+          const same = (source.of === 'part' ? measureFactor(asset, source.part, source.axis) : 1) / measureFactor(asset, this.partId, axis)
+          if (Math.abs((f.times ?? 1) - same) < 1e-6) mode = this.equivalentModes.get(key) ?? mode
+        }
+        const currentMode = mode === 'custom' ? 'ratio' : mode
+        const input = sizeInputOf(asset, this.partId, axis)
+        const label = `${axis.toUpperCase()}${measureFactor(asset, this.partId, axis) === 2 ? ' · ' + i18next.t('figure.label.size-diameter') : ''}`
+        /* The selects show when asked for, or when what it follows is not what its fastening gives -- or nothing is. */
+        const choosing = relation.variable && (this.choosing.has(key) || !sameSizeSource(source, suggested))
+        const selectedSource = source ? (source.of === 'instance' ? '@figure' : source.part) : '@custom'
+        const sourceAxes = source?.of === 'part' ? followableAxes(asset, source.part) : AXES
+        const changeSize = (e: Event) => {
+          const value = (e.target as HTMLInputElement).valueAsNumber
+          if (!(Number.isFinite(value) && value > 0)) {
+            this.error = i18next.t('figure.text.size-invalid')
+            this.requestUpdate()
+            return
+          }
+          if (relation.variable && source && mode !== 'custom') this.configure(axis, source, mode, value)
+          else if (!relation.variable && input) {
+            this.error = ''
+            this.dispatchEvent(new CustomEvent('size-input', { detail: { input, value: value / measureFactor(asset, this.partId, axis), part: this.partId }, bubbles: true, composed: true }))
+            this.requestUpdate()
+          }
+        }
+        const follows = (e: Event) => {
+          if ((e.target as HTMLInputElement).checked) {
+            if (suggested) this.configure(axis, suggested, 'ratio')
+            else {
+              /* At an angle to what it hangs from: which of its measures it follows is the author's to pick. */
+              this.choose(key, true)
+              this.error = i18next.t('figure.text.size-unpaired')
+            }
+          } else if (mm !== undefined) {
+            this.choose(key, false)
+            this.apply([{ kind: 'unlink-dimension', part: this.partId, axis, mm: mm / measureFactor(asset, this.partId, axis) }])
+          }
+        }
+        return html`<div class="dimension" data-axis=${axis}>
+          <div class="fields">
+            <span>${label}</span>
+            <input type="number" step="any" min="0" aria-label=${`${this.partId} ${label} ${i18next.t('figure.label.size-measure')}`} .value=${live(mm === undefined ? '' : String(Number(mm.toFixed(6))))}
+              ?disabled=${this.locked} ?readonly=${relation.variable ? mode === 'custom' || uniform : !input} @change=${changeSize}>
+            <label class="variable"><input type="checkbox" aria-label=${`${this.partId} ${label} ${i18next.t('figure.label.size-follows')}`} .checked=${live(relation.variable || this.choosing.has(key))} ?disabled=${this.locked || uniform}
+              @change=${follows}></label>
+            ${choosing || (this.choosing.has(key) && !relation.variable)
+              ? html`
+                <select aria-label=${`${this.partId} ${label} ${i18next.t('figure.label.size-source')}`} .value=${live(selectedSource)} ?disabled=${this.locked || uniform}
+                  @change=${(e: Event) => {
+                    const target = (e.target as HTMLSelectElement).value
+                    const possible = target === '@figure' ? AXES : followableAxes(asset, target)
+                    const targetAxis = possible.includes(source?.axis ?? axis) ? (source?.axis ?? axis) : possible[0]!
+                    this.configure(axis, target === '@figure' ? { of: 'instance', axis: targetAxis } : { of: 'part', part: target, axis: targetAxis }, currentMode)
+                  }}>
+                  ${!source ? html`<option value="@custom" disabled>${i18next.t(relation.variable ? 'figure.label.size-existing-rule' : 'figure.label.size-pick-source')}</option>` : nothing}
+                  <option value="@figure" ?selected=${selectedSource === '@figure'}>${i18next.t('figure.label.size-figure')}</option>
+                  ${targets.map(p => html`<option value=${p} ?selected=${selectedSource === p}>${p}</option>`)}
+                </select>
+                <select aria-label=${`${this.partId} ${label} ${i18next.t('figure.label.size-source-axis')}`} .value=${live(source?.axis ?? axis)} ?disabled=${this.locked || uniform || !source}
+                  @change=${(e: Event) => source && this.configure(axis, { ...source, axis: (e.target as HTMLSelectElement).value as Axis }, currentMode)}>
+                  ${sourceAxes.map(a => html`<option value=${a} ?selected=${a === (source?.axis ?? axis)}>${a.toUpperCase()}</option>`)}
+                </select>`
+              : relation.variable && source
+                ? html`<div class="source">
+                    <span>${this.sourceWords(source)}</span>
+                    <button quiet ?disabled=${this.locked || uniform} @click=${() => this.choose(key, true)}>${i18next.t('figure.button.size-other-source')}</button>
+                  </div>`
+                : html`<span></span><span></span>`}
+          </div>
+          ${relation.variable
+            ? html`<div class="modes" choice-row>
+                  ${(['ratio', 'difference'] as const).map(
+                    m => html`<label toggle><input type="radio" name=${`mode-${this.partId}-${axis}`} .checked=${live(mode === m)} ?disabled=${this.locked || uniform || !source}
+                      @change=${() => source && this.configure(axis, source, m)}>${i18next.t(`figure.label.size-${m}`)}</label>`
+                  )}
+                </div>
+                ${mode === 'custom'
+                  ? html`<p hint>${i18next.t('figure.text.size-custom-rule')}</p>`
+                  : source
+                    ? html`<p hint class="result">${this.resultWords(revision, source, currentMode, mm)}</p>`
+                    : nothing}`
+            : nothing}
+        </div>`
+      })}
+      ${uniform ? html`<p hint>${i18next.t('figure.text.size-uniform')}</p>` : nothing}
+      ${this.error ? html`<p hint role="alert">${this.error}</p>` : nothing}
+    `
+  }
+}

package/client/modeller/joint-drag.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three'
-import { compileFigureAsset, figureMimicTermsOf } from '@hatiolab/figure-model'
+import { compileFigureAsset, figureMimicTermsOf, figureMotionsOf, motionStateIdOf, type FigureNamedMotion } from '@hatiolab/figure-model'
 import type { FigureAsset, FigureJoint } from '@hatiolab/figure-model'
 
 import type { GizmoResult } from './gizmo.js'
@@ -22,7 +22,7 @@ import type { FigureRenderPart } from './renderer.js'
 export type JointDrag =
   | { kind: 'value'; input: string; unit: 'deg' | 'mm' | 'ratio'; value: number }
   | { kind: 'joint'; joint: FigureJoint }
-  | { kind: 'refused'; reason: 'mimic' | 'fixed-turn' | 'origin-follows' | 'turned-slide' | 'off-axis'; joint: string; leader?: string; axis?: string }
+  | { kind: 'refused'; reason: 'mimic' | 'fixed-turn' | 'origin-follows' | 'turned-slide' | 'off-axis' | 'several-axes'; joint: string; leader?: string; axis?: string }
 
 type Axis = 'x' | 'y' | 'z'
 const AXES: Axis[] = ['x', 'y', 'z']
@@ -42,11 +42,11 @@ const eulerMatrixOrder = (deg: number[], order: THREE.EulerOrder) => new THREE.M
 /** The part's own pose on its end, any angle, as the record says it (`origin.childRotate`, Rz·Ry·Rx, ADR-0140 3.11). */
 const turnMatrix = (j: FigureJoint) => eulerMatrixOrder(AXES.map(a => j.origin?.childRotate?.[a] ?? 0), 'ZYX')
 
-/** The joint frame's rotation in the figure: the part's rotation now, less its own turn and less the joint's. */
-function jointFrameRotation(j: FigureJoint, part: FigureRenderPart, angle: number): THREE.Matrix4 {
+/** The joint frame's rotation in the figure: the part's rotation now, less its own turn and less its one axis's. */
+function jointFrameRotation(j: FigureJoint, a: FigureNamedMotion | undefined, part: FigureRenderPart, angle: number): THREE.Matrix4 {
   const now = matrixOf(part.pose.r as number[][])
   const own = turnMatrix(j)
-  const turn = j.type === 'revolute' ? new THREE.Matrix4().makeRotationAxis(unit(j.axis!), THREE.MathUtils.degToRad(angle)) : new THREE.Matrix4()
+  const turn = a?.type === 'revolute' ? new THREE.Matrix4().makeRotationAxis(unit(a.axis), THREE.MathUtils.degToRad(angle)) : new THREE.Matrix4()
   return now.multiply(own.invert()).multiply(turn.invert())
 }
 
@@ -54,47 +54,51 @@ export function jointDragOf(asset: FigureAsset, id: string, part: FigureRenderPa
   const j = asset.joints?.find(joint => joint.body1.part === id)
   /* A size is the part's own, not the joint's: a scale drag goes to the part's measures (the editor drops the shift). */
   if (!j || result.scale || (!result.rotation && !result.position)) return null
-  const stateId = j.state?.id ?? j.id
+  /* A drag moves one axis, or the joint's place: a joint of several axes (ADR-0159) is moved by its controls. */
+  const axes = figureMotionsOf(j)
+  if (axes.length > 1) return { kind: 'refused', reason: 'several-axes', joint: j.id }
+  const a = axes[0]
+  const stateId = a ? motionStateIdOf(a) : j.id
   const now = values[stateId] ?? asset.stateDefaults[stateId] ?? 0
-  const turns = j.type === 'revolute'
-  /* A revolute joint without limits turns without end (USD). */
-  const endless = turns && j.lowerLimit === undefined && j.upperLimit === undefined
+  const turns = a?.type === 'revolute'
+  /* A revolute axis without limits turns without end (USD). */
+  const endless = turns && a.lowerLimit === undefined && a.upperLimit === undefined
 
   if (result.rotation) {
-    if (!turns) return { kind: 'refused', reason: j.type === 'prismatic' ? 'turned-slide' : 'fixed-turn', joint: j.id }
-    if (j.mimic) return { kind: 'refused', reason: 'mimic', joint: j.id, leader: figureMimicTermsOf(j.mimic)!.sum.map(t => t.joint).join(', ') }
+    if (!turns) return { kind: 'refused', reason: a?.type === 'prismatic' ? 'turned-slide' : 'fixed-turn', joint: j.id }
+    if (a.mimic) return { kind: 'refused', reason: 'mimic', joint: j.id, leader: figureMimicTermsOf(a.mimic)!.sum.map(t => t.joint).join(', ') }
     /* The turn about the joint's axis (the twist of the change): the only turn the joint can make. */
     const before = new THREE.Quaternion().setFromRotationMatrix(matrixOf(part.pose.r as number[][]))
     const after = new THREE.Quaternion().setFromRotationMatrix(eulerMatrix(result.rotation))
     const change = after.multiply(before.invert())
-    const axis = unit(j.axis!).applyMatrix4(jointFrameRotation(j, part, now)).normalize()
+    const axis = unit(a.axis).applyMatrix4(jointFrameRotation(j, a, part, now)).normalize()
     const twist = 2 * Math.atan2(change.x * axis.x + change.y * axis.y + change.z * axis.z, change.w)
     /* Turned about another axis: the joint cannot make that turn, and nothing is written for it. */
     const whole = 2 * Math.acos(Math.min(1, Math.abs(change.w)))
-    if (Math.abs(twist) < whole * 0.5) return { kind: 'refused', reason: 'off-axis', joint: j.id, axis: jointAxisWord(j.axis) }
+    if (Math.abs(twist) < whole * 0.5) return { kind: 'refused', reason: 'off-axis', joint: j.id, axis: jointAxisWord(a.axis) }
     let value = now + THREE.MathUtils.radToDeg(twist)
     if (endless) value = ((((value + 180) % 360) + 360) % 360) - 180
-    else value = Math.min(Math.max(value, j.lowerLimit!), j.upperLimit!)
+    else value = Math.min(Math.max(value, a.lowerLimit!), a.upperLimit!)
     return { kind: 'value', input: stateId, unit: 'deg', value: round(value, 0.1) }
   }
 
   const moved = new THREE.Vector3(...result.position!).sub(new THREE.Vector3(...(part.pose.t as [number, number, number])))
   if (moved.length() < 0.5) return null
-  const frame = jointFrameRotation(j, part, turns ? now : 0)
+  const frame = jointFrameRotation(j, a, part, turns ? now : 0)
 
-  if (j.type === 'prismatic') {
-    if (j.mimic) return { kind: 'refused', reason: 'mimic', joint: j.id, leader: figureMimicTermsOf(j.mimic)!.sum.map(t => t.joint).join(', ') }
+  if (a?.type === 'prismatic') {
+    if (a.mimic) return { kind: 'refused', reason: 'mimic', joint: j.id, leader: figureMimicTermsOf(a.mimic)!.sum.map(t => t.joint).join(', ') }
     /* How far one unit of the value moves the part along its axis, measured on the figure itself (a ratio travels a length). */
-    const along = unit(j.axis!).applyMatrix4(frame).normalize()
+    const along = unit(a.axis).applyMatrix4(frame).normalize()
     const at = (v: number) => {
       const g = compileFigureAsset(asset).evaluate({ ...values, [stateId]: v }).geometry.find(g => g.id === id && 'pose' in g) as { pose: { t: number[] } } | undefined
       return g ? new THREE.Vector3(...(g.pose.t as [number, number, number])).dot(along) : 0
     }
-    const step = j.travel ? 0.01 : 1
+    const step = a.travel ? 0.01 : 1
     const rate = (at(now + step) - at(now)) / step
     if (Math.abs(rate) > 1e-9 && Math.abs(moved.dot(along)) >= moved.length() * 0.7) {
-      const value = Math.min(Math.max(now + moved.dot(along) / rate, j.lowerLimit!), j.upperLimit!)
-      return { kind: 'value', input: stateId, unit: j.travel ? 'ratio' : 'mm', value: round(value, j.travel ? 0.001 : 1) }
+      const value = Math.min(Math.max(now + moved.dot(along) / rate, a.lowerLimit!), a.upperLimit!)
+      return { kind: 'value', input: stateId, unit: a.travel ? 'ratio' : 'mm', value: round(value, a.travel ? 0.001 : 1) }
     }
   }
 

package/client/modeller/joint-fan.ts

@@ -98,10 +98,11 @@ function turnOf(asset: FigureAsset, part: string, values: Record<string, unknown
     about the joint's axis. A part that does not turn itself shows the joint that sits on it, when there is one: the
     elbow block shows the elbow (user, 2026-09-24: 「elbow-housing itself is a axis」).
   */
-  const turning = (asset.joints ?? []).filter(j => j.type === 'revolute')
+  /* A joint's fan is its first axis's (ADR-0159): `<child>.motion`. */
+  const turning = (asset.joints ?? []).filter(j => j.motion?.[0]?.type === 'revolute')
   const record = turning.find(j => j.body1.part === part) ?? (() => {
     const on = turning.filter(j => 'part' in j.body0 && j.body0.part === part)
-    return on.length === 1 && !(asset.joints ?? []).some(j => j.body1.part === part && j.type !== 'fixed') ? on[0] : undefined
+    return on.length === 1 && !(asset.joints ?? []).some(j => j.body1.part === part && j.motion?.length) ? on[0] : undefined
   })()
   if (record) {
     const child = record.body1.part
@@ -113,7 +114,7 @@ function turnOf(asset: FigureAsset, part: string, values: Record<string, unknown
     /* In the child's own frame: the joint is where its pose puts the seat's origin, the axis turned back by its pose. */
     const back = (v: number[]) => [0, 1, 2].map(i => pose.r[0]![i]! * v[0]! + pose.r[1]![i]! * v[1]! + pose.r[2]![i]! * v[2]!)
     const pivot = back(pose.t.map(v => -v))
-    const axis = norm(back(jointAxisUnit(record.axis) ?? [0, 0, 0]))
+    const axis = norm(back(jointAxisUnit(record.motion![0]!.axis) ?? [0, 0, 0]))
     if (!axis) return null
     return { carrier, pivot, axis, toward: [0, 0, 0], control, turnedPart: child }
   }

package/client/modeller/links.ts

@@ -1,6 +1,6 @@
-import { FIGURE_FACES, figureShapeFaces, figurePartsExtentOf, compileFigureAsset, figureFollowOf, proposeFigureProportion, figureAttachmentsOf, figureBindingsOf, figureInstanceSizeRangeOf, figureFollowableAxesOf, figureShapeProviderOf, figureMimicTermsOf, figureFastenKeptPlaceOf, figureFastenAxesOf, figureJointAsFixed, figureJointWithMotion, figureSurfaceOf } from '@hatiolab/figure-model'
+import { FIGURE_FACES, figureShapeFaces, figurePartsExtentOf, compileFigureAsset, figureFollowOf, proposeFigureProportion, figureAttachmentsOf, figureBindingsOf, figureInstanceSizeRangeOf, figureFollowableAxesOf, figureShapeProviderOf, figureMimicTermsOf, figureFastenKeptPlaceOf, figureFastenAxesOf, figureJointAsFixed, figureJointWithMotion, figureSurfaceOf, figureAxesOf, figureMotionsOf } from '@hatiolab/figure-model'
 import type { FigureFollow, FigureInstanceSizeRange } from '@hatiolab/figure-model'
-import type { FigureAsset, FigureAuthoringAction, FigureBindingPlace, FigureDimensionSource, FigureFace, FigureFacing, FigureJoint, FigureSurfacePlace } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureAuthoringAction, FigureBindingPlace, FigureDimensionSource, FigureFace, FigureFacing, FigureJoint, FigureJointMotion, FigureNamedMotion, FigureSurfacePlace } from '@hatiolab/figure-model'
 import { startingShapeKindOf } from './starting-shape.js'
 import { boxOf } from './align.js'
 import { graphValuesOf, type FigureRevision } from './revision.js'
@@ -535,7 +535,9 @@ export function motionOf(asset: FigureAsset, part: string): Motion | undefined {
   const m = modelOf(asset)
   const node = m.nodes.find(n => n.id === `${part}.motion`)
   if (!node) return undefined
-  const record = asset.joints?.find(j => j.body1.part === part)
+  const joint = asset.joints?.find(j => j.body1.part === part)
+  /* The motion the form shows is the joint's first axis, `<part>.motion` (ADR-0159). */
+  const record = joint && figureMotionsOf(joint)[0]
   /* A follower has no limits of its own: its range is its leaders', not a turn without end. */
   const endless = record?.type === 'revolute' && record.lowerLimit === undefined && record.upperLimit === undefined && !record.mimic
   const vector = jointAxisVectorOf(record?.axis)
@@ -587,30 +589,32 @@ export interface MotionForm {
    * a range or an axis does not turn a follower into a joint of its own or drop its stroke.
    */
   followSum?: Array<{ joint: string; multiplier: number }>
-  travelSum?: Extract<NonNullable<FigureJoint['travel']>, { sum: unknown }>
+  travelSum?: Extract<NonNullable<FigureJointMotion['travel']>, { sum: unknown }>
 }
 
 /**
  * The motion form filled from a joint as it is, so a motion can be changed where it is -- its range, the length it
  * travels by, what it follows -- rather than taken away and made again. Taking it away is refused while another joint
- * follows it, which left a leader's stroke fixed for good (the telescopic conveyor, 2026-09-25).
+ * follows it, which left a leader's stroke fixed for good (the telescopic conveyor, 2026-09-25). The form is the
+ * joint's first axis (ADR-0159); the axes after it are kept as they are when it is written (`motionJoint`).
  */
 export function motionFormOf(joint: FigureJoint): MotionForm {
-  const kind: MotionForm['kind'] = joint.type === 'prismatic' ? 'slide' : joint.lowerLimit === undefined && joint.upperLimit === undefined && !joint.mimic ? 'continuous' : 'turn'
-  const one = joint.travel && 'source' in joint.travel ? joint.travel : undefined
+  const a = figureMotionsOf(joint)[0]
+  const kind: MotionForm['kind'] = a?.type === 'prismatic' ? 'slide' : a?.lowerLimit === undefined && a?.upperLimit === undefined && !a?.mimic ? 'continuous' : 'turn'
+  const one = a?.travel && 'source' in a.travel ? a.travel : undefined
   const travel = one?.source && 'part' in one.source ? `${one.source.part}:${one.source.axis}` : ''
-  const travelSum = joint.travel && 'sum' in joint.travel ? joint.travel : undefined
-  const terms = figureMimicTermsOf(joint.mimic)
+  const travelSum = a?.travel && 'sum' in a.travel ? a.travel : undefined
+  const terms = figureMimicTermsOf(a?.mimic)
   const single = terms?.sum.length === 1 ? terms.sum[0] : undefined
-  const axisVector = jointAxisVectorOf(joint.axis)
+  const axisVector = jointAxisVectorOf(a?.axis)
   return {
     kind,
-    axis: jointAxisToken(joint.axis) ?? 'x',
+    axis: jointAxisToken(a?.axis) ?? 'x',
     ...(axisVector ? { axisVector } : {}),
-    /* A moving joint with no state record is driven by the input named after it (figure-model `stateIdOf`): keep that name, so an edit does not rename the control a board or a controller writes to. */
-    id: joint.state?.id ?? (joint.type !== 'fixed' && !joint.mimic ? joint.id : ''),
-    min: travel || travelSum ? 0 : (joint.lowerLimit ?? (kind === 'slide' ? 0 : -90)),
-    max: travel || travelSum ? 500 : (joint.upperLimit ?? (kind === 'slide' ? 500 : 90)),
+    /* An axis with no state record is driven by the input named after it (figure-model `motionStateIdOf`): keep that name, so an edit does not rename the control a board or a controller writes to. */
+    id: a?.state?.id ?? (a && !a.mimic ? a.id : ''),
+    min: travel || travelSum ? 0 : (a?.lowerLimit ?? (kind === 'slide' ? 0 : -90)),
+    max: travel || travelSum ? 500 : (a?.upperLimit ?? (kind === 'slide' ? 500 : 90)),
     follow: single?.joint ?? '',
     multiplier: single?.multiplier ?? 1,
     offset: terms?.offset ?? 0,
@@ -622,11 +626,13 @@ export function motionFormOf(joint: FigureJoint): MotionForm {
 }
 
 /**
- * The joints a part's joint can move with (URDF's mimic): a joint that moves the same way — a slide follows a slide, a
- * turn a turn — and has a control of its own, since a follower follows the joint that is driven.
+ * The axes a part's joint can move with (URDF's mimic): one of another part's that moves the same way — a slide follows
+ * a slide, a turn a turn — and has a control of its own, since a follower follows the axis that is driven (ADR-0159).
  */
-export function leadersFor(asset: FigureAsset, part: string, kind: MotionForm['kind']): FigureJoint[] {
-  return (asset.joints ?? []).filter(j => j.body1.part !== part && j.type !== 'fixed' && !j.mimic && (j.type === 'prismatic') === (kind === 'slide'))
+export function leadersFor(asset: FigureAsset, part: string, kind: MotionForm['kind']): Array<FigureNamedMotion & { part: string }> {
+  return figureAxesOf(asset.joints)
+    .filter(({ joint, motion }) => joint.body1.part !== part && !motion.mimic && (motion.type === 'prismatic') === (kind === 'slide'))
+    .map(({ joint, motion }) => ({ ...motion, part: joint.body1.part }))
 }
 
 /**
@@ -635,14 +641,20 @@ export function leadersFor(asset: FigureAsset, part: string, kind: MotionForm['k
  * control or limits of its own — its range is the leader's times the multiplier.
  */
 export function motionJoint(joint: FigureJoint, m: MotionForm, part: string): FigureJoint {
-  /* Where it is fastened -- its row and its frame's own words too -- is the kernel's to keep (`figureJointWithMotion`, ADR-0140 D6). */
+  /*
+    Where it is fastened -- its row and its frame's own words too -- is the kernel's to keep (`figureJointWithMotion`,
+    ADR-0140 D6). The form writes the first axis, under the name it had; the axes after it stay as they are (ADR-0159).
+  */
+  const was = joint.motion?.[0]
   const moving = {
+    ...(was?.id !== undefined ? { id: was.id } : {}),
     type: m.kind === 'slide' ? ('prismatic' as const) : ('revolute' as const),
-    axis: (m.axisVector ?? m.axis.toUpperCase()) as FigureJoint['axis']
+    axis: (m.axisVector ?? m.axis.toUpperCase()) as FigureJointMotion['axis'],
+    ...(was?.through ? { through: was.through } : {})
   }
-  const given = (motion: Omit<Parameters<typeof figureJointWithMotion>[1], 'type' | 'axis'>) => figureJointWithMotion(joint, { ...moving, ...motion })
-  if (m.follow) return given({ mimic: { joint: m.follow, multiplier: m.multiplier, ...(m.offset ? { offset: m.offset } : {}) } })
-  if (m.followSum) return given({ mimic: { sum: m.followSum, ...(m.offset ? { offset: m.offset } : {}) } })
+  const given = (motion: Omit<FigureJointMotion, 'type' | 'axis'>) => figureJointWithMotion(joint, [{ ...moving, ...motion }, ...(joint.motion?.slice(1) ?? [])])
+  if (m.follow) return given({ mimic: { motion: m.follow, multiplier: m.multiplier, ...(m.offset ? { offset: m.offset } : {}) } })
+  if (m.followSum) return given({ mimic: { sum: m.followSum.map(t => ({ motion: t.joint, multiplier: t.multiplier })), ...(m.offset ? { offset: m.offset } : {}) } })
   if (m.kind === 'slide' && m.travelSum && !m.travel) return given({ travel: m.travelSum, state: { id: m.id || `${part}-${m.kind}` } })
   if (m.kind === 'slide' && m.travel) {
     const [of, axis] = m.travel.split(':')

package/client/modeller/motion-ends.ts

@@ -1,4 +1,4 @@
-import { compileFigureAsset } from '@hatiolab/figure-model'
+import { compileFigureAsset, figureMotionsOf, motionStateIdOf } from '@hatiolab/figure-model'
 
 import { PREVIEW, TARGET_FACE } from './command-preview.js'
 import type { FigureRenderPart } from './renderer.js'
@@ -28,13 +28,17 @@ export interface MotionEnds {
 
 const samePose = (a: Pose, b: Pose) => [0, 1, 2].every(i => Math.abs(a.t[i]! - b.t[i]!) < 1e-6 && [0, 1, 2].every(k => Math.abs(a.r[i]![k]! - b.r[i]![k]!) < 1e-9))
 
-/** The ends of the selected part's own motion, or nothing: a part that does not move, follows another, or turns without end. */
+/**
+ * The ends of the selected part's own motion -- its joint's first axis (ADR-0159) -- or nothing: a part that does not
+ * move, follows another, or turns without end.
+ */
 export function motionEndsOf(revision: FigureRevision, part: string): MotionEnds | null {
   const asset = revision.asset
   const joint = asset.joints?.find(j => j.body1.part === part)
-  /* A turn without end is a revolute joint whose control has no range: the range check below leaves it out. */
-  if (!joint || joint.type === 'fixed' || joint.mimic) return null
-  const control = joint.state?.id ?? joint.id
+  const axis = joint && figureMotionsOf(joint)[0]
+  /* A turn without end is a revolute axis whose control has no range: the range check below leaves it out. */
+  if (!axis || axis.mimic) return null
+  const control = motionStateIdOf(axis)
   const input = asset.document.model.inputs.find(i => i.id === control && i.role === 'state')
   if (!input || typeof input.min !== 'number' || typeof input.max !== 'number' || input.min === input.max) return null
   /* The version's design values are its asset's; its pose is every control as set now, this one at each end. */
@@ -58,7 +62,7 @@ export function motionEndsOf(revision: FigureRevision, part: string): MotionEnds
   ]
   /* A slide: the line its own body travels, from the lowest value to the highest. */
   const own = moving.find(b => b.id === part)
-  if (joint.type === 'prismatic' && own) {
+  if (axis.type === 'prismatic' && own) {
     const from = own.pose.t
     const to = byId.get(part)!.pose.t
     const v = [0, 1, 2].map(i => to[i]! - from[i]!)

package/client/modeller/size-response.ts

@@ -0,0 +1,95 @@
+import { figureAxisPairsOf, figurePartsExtentOf, figureShapeProviderOf } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureAuthoringAction, FigureDimensionSource } from '@hatiolab/figure-model'
+import type { FigureRevision } from './revision.js'
+import { dimensionNow, followOf, followableAxes, measureNow, type Axis } from './links.js'
+
+export type SizeMode = 'ratio' | 'difference' | 'custom'
+export type SizeSource = Extract<FigureDimensionSource, { of: 'instance' | 'part' }>
+
+function editOf(asset: FigureAsset, part: string, axis: Axis) {
+  const shape = asset.document.model.nodes.find(n => n.id === `${part}.shape`)
+  const edit = shape && figureShapeProviderOf(shape)?.edit[axis]
+  return shape && edit && !('refused' in edit) ? { shape, edit } : undefined
+}
+export const measureFactor = (asset: FigureAsset, part: string, axis: Axis) => editOf(asset, part, axis)?.edit.k ?? 1
+
+/** Only expose direct own inputs (including the canonical identity wrapper). Never overwrite an arbitrary expression. */
+export function sizeInputOf(asset: FigureAsset, part: string, axis: Axis): string | undefined {
+  const e = editOf(asset, part, axis)
+  if (!e) return undefined
+  const model = asset.document.model
+  let ref = e.shape.args[e.edit.arg]
+  const seen = new Set<string>()
+  while (ref && !seen.has(ref)) {
+    seen.add(ref)
+    if (model.inputs.some(i => i.id === ref && i.role === 'design' && i.unit === 'mm') && ref.startsWith(`${part}.`)) return ref
+    const writer = model.nodes.find(n => Object.values(n.outputs).includes(ref!))
+    if (writer?.op !== 'mul@1' || model.constants.find(c => c.id === writer.args[1])?.value !== 1) return undefined
+    ref = writer.args[0]
+  }
+}
+export function sizeRelationOf(revision: FigureRevision, part: string, axis: Axis): { source?: SizeSource; mode: SizeMode; variable: boolean } {
+  const f = followOf(revision.asset, part, axis)
+  if (f.of === 'own') return { mode: 'ratio', variable: false }
+  if (f.of !== 'instance' && f.of !== 'part') return { mode: 'custom', variable: true }
+  const source: SizeSource = f.of === 'instance' ? { of: 'instance', axis: f.axis } : { of: 'part', part: f.part, axis: f.axis }
+  const equalFactor = (source.of === 'part' ? measureFactor(revision.asset, source.part, source.axis) : 1) / measureFactor(revision.asset, part, axis)
+  const mode = !(f.plus ?? 0) ? 'ratio' : Math.abs((f.times ?? 1) - equalFactor) < 1e-6 ? 'difference' : 'custom'
+  return { source, mode, variable: true }
+}
+
+/**
+ * What a measure follows when it is first made to follow (ADR-0159 3): what the part hangs from, along the axis its own
+ * axis lies on as it stands -- a roller laid on its side follows the frame's depth with its length, not the frame's
+ * height (the axes paired by figure-model, `figureAxisPairsOf`, never by their letters). On the mounting plane, or
+ * fastened to nothing, the figure's size. Nothing when it lies at an angle, or the parent has no measure along that
+ * axis: the author picks. Only a suggestion when a relation is made; a measure that already follows something keeps it.
+ */
+export function suggestedSizeSource(asset: FigureAsset, part: string, axis: Axis): SizeSource | undefined {
+  const { parent, along } = figureAxisPairsOf(asset, part)
+  const on = along[axis]?.axis
+  if (!on) return undefined
+  if (!parent) return { of: 'instance', axis: on }
+  return followableAxes(asset, parent).includes(on) ? { of: 'part', part: parent, axis: on } : undefined
+}
+
+/** Whether two sources are one: the same part, or the figure, and the same axis. */
+export const sameSizeSource = (a: SizeSource | undefined, b: SizeSource | undefined) =>
+  !!a && !!b && a.of === b.of && a.axis === b.axis && (a.of !== 'part' || (b.of === 'part' && a.part === b.part))
+
+/** How long the source is now, in millimetres as the panel shows it (a radius read as a diameter). */
+export function sourceMeasureOf(revision: FigureRevision, source: SizeSource): number | undefined {
+  if (source.of === 'instance') return revision.asset.designInputs[`size.${source.axis}`] ?? figurePartsExtentOf(revision.asset)[source.axis]
+  return measureNow(revision, source.part, source.axis)
+}
+
+/** Preserve the displayed size when choosing a source or mode. mm edits change only that row's relation. */
+export function sizeRelationSteps(revision: FigureRevision, part: string, axis: Axis, source: SizeSource, mode: Exclude<SizeMode, 'custom'>, mm = measureNow(revision, part, axis)): FigureAuthoringAction[] {
+  if (!(typeof mm === 'number' && Number.isFinite(mm) && mm > 0)) throw Error('SIZE_VALUE')
+  if (source.of === 'part' && source.part === part) throw Error('SIZE_SOURCE')
+  const asset = revision.asset
+  const steps: FigureAuthoringAction[] = []
+  let raw: number | undefined
+  let sourceFactor = 1
+  if (source.of === 'instance') {
+    const declared = asset.document.model.inputs.some(i => i.id === `size.${source.axis}` && i.role === 'design')
+    if (declared) raw = asset.designInputs[`size.${source.axis}`]
+    else {
+      // Do not replace an existing partial size declaration while configuring an unrelated axis.
+      if (asset.document.model.inputs.some(i => /^size\.[xyz]$/.test(i.id))) throw Error('SIZE_SOURCE')
+      const at = figurePartsExtentOf(asset)
+      steps.push({ kind: 'declare-instance-size', at })
+      raw = at[source.axis]
+    }
+  } else {
+    if (!followableAxes(asset, source.part).includes(source.axis)) throw Error('SIZE_SOURCE')
+    raw = dimensionNow(revision, source.part, source.axis)
+    sourceFactor = measureFactor(asset, source.part, source.axis)
+  }
+  if (!(typeof raw === 'number' && raw > 0 && Number.isFinite(raw))) throw Error('SIZE_SOURCE')
+  const ownFactor = measureFactor(asset, part, axis)
+  const times = mode === 'ratio' ? mm / ownFactor / raw : sourceFactor / ownFactor
+  const plus = mode === 'difference' ? (mm - raw * sourceFactor) / ownFactor : 0
+  steps.push({ kind: 'link-dimension', part, axis, source, times, ...(plus ? { plus } : {}), replace: true })
+  return steps
+}

package/dist-client/modeller/data-interface.d.ts

@@ -78,7 +78,7 @@ export interface EndlessJoint {
     label: string;
     unit: 'deg' | 'rad';
 }
-/** The joints that turn without end: revolute, with no limits, leading no one's mimic. */
+/** The axes that turn without end: revolute, with no limits, following no one (ADR-0159: every axis of every joint). */
 export declare function endlessJointsOf(asset: FigureAsset): EndlessJoint[];
 /** What the rotation card is told: the joint, and the data fields that turn it on, set its speed and its direction. */
 export interface RotationChoice {

package/dist-client/modeller/data-interface.js

@@ -4,7 +4,7 @@
  * of data is things-scene's; this only lists what there is to choose, drafts a binding the kernel then checks, and edits
  * the schema as a tree. Kept apart from the element so it is tested without a browser.
  */
-import { FIGURE_PART_ID, FIGURE_MOTION_SPEED_MAX, FigureContractError, figureDataRows, parseFigureAccessor } from '@hatiolab/figure-model';
+import { FIGURE_PART_ID, FIGURE_MOTION_SPEED_MAX, FigureContractError, figureAxesOf, figureDataRows, motionStateIdOf, parseFigureAccessor } from '@hatiolab/figure-model';
 import { FigureInputs } from '@hatiolab/things-scene';
 export const behaviorKeyOf = (b) => b.kind === 'state'
     ? `state:${b.input}`
@@ -269,13 +269,13 @@ export function motionWrittenByData(asset) {
     }
     return out;
 }
-/** The joints that turn without end: revolute, with no limits, leading no one's mimic. */
+/** The axes that turn without end: revolute, with no limits, following no one (ADR-0159: every axis of every joint). */
 export function endlessJointsOf(asset) {
     const out = [];
-    for (const j of asset.joints ?? []) {
-        if (j.type !== 'revolute' || j.lowerLimit !== undefined || j.upperLimit !== undefined || j.mimic)
+    for (const { motion: a } of figureAxesOf(asset.joints)) {
+        if (a.type !== 'revolute' || a.lowerLimit !== undefined || a.upperLimit !== undefined || a.mimic)
             continue;
-        const input = j.state?.id ?? j.id;
+        const input = motionStateIdOf(a);
         const unit = asset.document.model.inputs.find(i => i.id === input)?.unit;
         if (unit !== 'deg' && unit !== 'rad')
             continue;