@things-factory/figure-ui 10.1.47 → 10.1.49

package/client/modeller/v3-editor.ts

@@ -3,6 +3,7 @@ import { i18next } from '@operato/i18n'
 import type { OxThreePane } from '@operato/layout'
 import '@operato/layout'
 import { customElement, property, state } from 'lit/decorators.js'
+import { PART_LIMIT, v3PartCountOf } from '@hatiolab/figure-model'
 import type { V3Asset, V3AuthoringAction, V3InputChange, V3PartEdit, V3PrimitiveCreation } from '@hatiolab/figure-model'
 import type { V3ProductSession } from './v3-product-session.js'
 import { captureV3Thumbnail } from './v3-thumbnail.js'
@@ -19,14 +20,17 @@ import { DEFAULT_VIEW, type ViewSettings } from './figure-view.js'
 import './figure-v3-capability.js'
 import { gizmoChanges, gizmoReachOf, type GizmoReach, type GizmoResult } from './v3-gizmo.js'
 import { keyActionOf } from './v3-keys.js'
-import { groupFields, type FieldLike, type FieldGroup } from './v3-fields.js'
+import { groupFields, ownerOf, partLabelOf, repeatOf, type FieldLike, type FieldGroup } from './v3-fields.js'
 import { SidePanelStyles } from './side-panel-styles.js'
 import { alignChanges, boxOf, canMirror, mirrorChanges, type AlignTool } from './v3-align.js'
 import type { V3PaletteKind, V3PartRow } from './figure-v3-parts.js'
 import { paletteRecipe } from './v3-palette.js'
 import type { FigureV3Canvas } from './v3-canvas.js'
+import { nudgeOf } from './v3-stage-model.js'
+import type { V3RenderPart } from './v3-renderer.js'
 import type { V3BudgetLine } from './v3-maturity.js'
-import { instanceRangeOf, rangeDiffers } from './v3-links.js'
+import { instanceRangeOf, rangeDiffers, turnsAboutAJoint } from './v3-links.js'
+import { jointFanOf } from './v3-joint-fan.js'
 import { isLive, livePartsOf, NOTHING_LIVE, scrubbed, scrubStep, type LiveValues } from './v3-live.js'
 
 
@@ -287,7 +291,7 @@ export class FigureV3Editor extends LitElement {
       this.error = ''
       this.hiddenParts = new Set()
     }
-    if (view && !view.geometry.some(g => g.id === this.selected)) this.selected = ''
+    if (view && !view.geometry.some(g => ownerOf(g.id) === this.selected)) this.selected = ''
   }
   private run(action: () => unknown) {
     try {
@@ -304,7 +308,19 @@ export class FigureV3Editor extends LitElement {
   /** What the canvas draws: the figure with the value in hand when there is one, and without the parts hidden on the workbench. */
   private drawnParts(geometry: Parameters<typeof drawableV3Parts>[0] | undefined, asset: unknown) {
     const parts = (isLive(this.live) && asset ? livePartsOf(asset as V3Asset, this.live) : null) ?? drawableV3Parts(geometry ?? [])
-    return parts.filter(body => !this.hiddenParts.has((body as { id: string }).id))
+    return parts.filter(body => !this.hiddenParts.has(ownerOf((body as { id: string }).id)))
+  }
+  /**
+   * Where the selected part turns and how far, with the pose as it is drawn now -- a value in hand included, so the
+   * fan follows the arm while a control is dragged. Its size comes from what the joint turns (`v3-joint-fan`).
+   */
+  private fanOf(asset: V3Asset | undefined) {
+    if (!asset || !this.selected || this.hiddenParts.has(this.selected)) return null
+    try {
+      return jointFanOf(asset, this.selected, this.live.values)
+    } catch {
+      return null
+    }
   }
   /** A value in hand: an input's value (design or pose) or a part edit. Nothing is recorded. */
   private hold(values: Record<string, number>, edit?: V3PartEdit) {
@@ -384,7 +400,8 @@ export class FigureV3Editor extends LitElement {
   /** What the gizmo may write for the selected part — read off the asset being edited. */
   private reachOf(id: string): GizmoReach {
     const none = { translate: false, rotate: false, scale: false }
-    if (!id || !this.session) return none
+    /* A repeat is moved and sized through its row, not by a gizmo on one copy. */
+    if (!id || !this.session || !this.session.read().geometry.some(g => g.id === id)) return none
     try {
       return gizmoReachOf(JSON.parse(this.session.source()), id)
     } catch {
@@ -396,8 +413,36 @@ export class FigureV3Editor extends LitElement {
     const view = this.session!.read()
     const sizes = Object.fromEntries(view.fields.map(field => [field.id, field.value as number]))
     const changes = gizmoChanges(id, this.reachOf(id), result, sizes)
-    if (changes.length) this.run(() => this.session!.apply(changes))
-    else this.requestUpdate()
+    if (changes.length) {
+      this.run(() => this.session!.apply(changes))
+      return
+    }
+    /*
+      A part whose place is worked out (a converted one) has no numbers for the gizmo to write: the drag is added beside
+      its rule (`nudge-part`). A part a joint or a fastening places, or a size that is worked out, is refused -- said in
+      words, not by the part silently springing back (user, 2026-09-24: 「기즈모 컨트롤도 전혀 작동이 안되는군」).
+    */
+    const body = view.geometry.find(g => g.id === id) as unknown as V3RenderPart | undefined
+    if (!body) return this.requestUpdate()
+    if (result.scale && !result.position && !result.rotation) {
+      this.error = i18next.t('figure.text.gizmo-size-worked-out', { part: partLabelOf(id) })
+      return this.requestUpdate()
+    }
+    const { by, turn } = nudgeOf(body, result)
+    if (!Object.keys(by).length && !Object.keys(turn).length) return this.requestUpdate()
+    try {
+      this.session!.command({ kind: 'nudge-part', part: id, ...(Object.keys(by).length ? { by } : {}), ...(Object.keys(turn).length ? { turn } : {}) })
+      this.error = ''
+      this.changed()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      this.error = /carried by a joint/.test(message)
+        ? i18next.t('figure.text.gizmo-joint-places', { part: partLabelOf(id) })
+        : /is fastened to/.test(message)
+          ? i18next.t('figure.text.gizmo-fastening-places', { part: partLabelOf(id) })
+          : message
+      this.requestUpdate()
+    }
   }
   /** 맞추기 — one tool, one step of the history, through the same inputs as the gizmo. */
   private align(tool: AlignTool) {
@@ -454,6 +499,14 @@ export class FigureV3Editor extends LitElement {
    * A part's name — the V2 part name field. It renames every value the part owns, and what refers to them follows
    * (figure-model's rename-part), as one step of the history.
    */
+  /**
+   * A repeated body is one of its repeat's copies and is named after it -- the list and this field read `roller 15`, not
+   * its path through the repeat (user, 2026-09-24: 「부품 이름 ???」). A copy has no name of its own to change.
+   */
+  private renderRepeatNote(geometry: readonly unknown[] | undefined) {
+    const repeat = repeatOf(this.selected, geometry)
+    return repeat?.index ? html`<p hint>${i18next.t('figure.text.repeat-member', { name: repeat.name, count: repeat.count, index: repeat.index })}</p>` : nothing
+  }
   private renamePart(input: HTMLInputElement) {
     const name = input.value.trim()
     const from = this.selected
@@ -637,11 +690,131 @@ export class FigureV3Editor extends LitElement {
               <md-icon>straighten</md-icon>${i18next.t('figure.button.remeasure-range')}
             </button>`
         : nothing}
+      ${this.renderSizingRule(asset, unavailable)}
     </section>`
   }
+  /**
+   * How the figure grows. One ratio (`sizing: 'uniform'`) is said as it is; a figure with joints that has not declared
+   * it is offered it -- a mechanism does not shear -- and the author decides (chief architect's ruling 2026-09-24).
+   */
+  private renderSizingRule(asset: V3Asset, unavailable: boolean) {
+    if (asset.sizing === 'uniform') return html`<div inline-field><label>${i18next.t('figure.label.sizing-rule')}</label><span>${i18next.t('figure.label.sizing-uniform')}</span></div>`
+    return html`${turnsAboutAJoint(asset) ? html`<p hint>${i18next.t('figure.text.sizing-uniform-proposed')}</p>` : nothing}
+      <button act ?disabled=${unavailable} title=${i18next.t('figure.text.sizing-uniform-explained')} @click=${() => this.linkCommand({ kind: 'scale-uniformly' })}>
+        <md-icon>aspect_ratio</md-icon>${i18next.t('figure.button.scale-uniformly')}
+      </button>`
+  }
+  /**
+   * The parts list, one row per part the author made: a repeat is one row with how many copies it makes now (V2 listed
+   * its parts the same way; user, 2026-09-24: the conveyor's sixteen rollers were sixteen rows).
+   */
+  private partRows(geometry: readonly { id: string }[]): V3PartRow[] {
+    const rows = new Map<string, V3PartRow>()
+    for (const g of geometry) {
+      const id = ownerOf(g.id)
+      const row = rows.get(id)
+      if (row) {
+        row.copies = (row.copies ?? 1) + 1
+        continue
+      }
+      rows.set(id, {
+        id,
+        provider: (g as { shape?: { provider?: string } }).shape?.provider ?? '',
+        hidden: this.hiddenParts.has(id),
+        invisible: (g as { visible?: boolean }).visible === false,
+        ...(id !== g.id ? { copies: 1 } : {})
+      })
+    }
+    return [...rows.values()]
+  }
+  /** The detail level's part budget for the list's head, from figure-model's count (a repeat once). */
+  private partBudgetOf(asset: V3Asset | undefined) {
+    if (!asset) return undefined
+    try {
+      return { level: asset.detailLevel ?? null, used: v3PartCountOf(asset), limit: asset.detailLevel ? PART_LIMIT[asset.detailLevel] : null }
+    } catch {
+      return undefined
+    }
+  }
+  /**
+   * A repeat: which way its copies run, how many there are now, and how far apart -- V2's `repeat: { axis, pitch }`.
+   * The pitch of a row that fills its length is edited as a number (`set-repeat` makes it the part's own the first
+   * time); a row of a fixed count says its pitch cannot be set yet (figure-model refuses it the same way).
+   */
+  private renderRepeat(asset: V3Asset | undefined, geometry: readonly { id: string }[], unavailable: boolean) {
+    const repeat = repeatOf(this.selected, geometry)
+    if (!asset || !repeat || repeat.index) return nothing
+    const model = asset.document.model as unknown as {
+      nodes: { id: string; op: string; args: string[]; params?: Record<string, string> }[]
+      constants: { id: string; value: number }[]
+      inputs: { id: string; max?: number }[]
+    }
+    const layout = model.nodes.find(n => n.id === `${this.selected}.layout`)
+    const axis = model.nodes.find(n => n.id === `${this.selected}.repeat`)?.params?.axis ?? '?'
+    const own = `${this.selected}.repeat.pitch`
+    const pitch = asset.designInputs[own] ?? model.constants.find(c => c.id === layout?.args[4])?.value
+    const fits = layout?.op === 'fit-pitch@1'
+    /* What the pitch gives, in numbers: this many copies at the length it is authored, and how long it may be placed. */
+    const lengthRef = layout?.args[0] ?? ''
+    const length = asset.designInputs[lengthRef]
+    const longest = model.inputs.find(i => i.id === lengthRef)?.max
+    const limit = model.constants.find(c => c.id === layout?.args[6])?.value
+    const field = { id: own, unit: 'mm' as const, role: 'design', value: pitch ?? 0 }
+    return html`<section>
+      <h3>${i18next.t('figure.label.repeat')}</h3>
+      <div inline-field><label>${i18next.t('figure.label.repeat-axis')}</label><span value>${axis.toUpperCase()}</span></div>
+      <div inline-field><label>${i18next.t('figure.label.repeat-count')}</label><span value>${repeat.count}</span></div>
+      <div inline-field>
+        <label>${i18next.t('figure.label.repeat-gap')} <span unit>mm</span></label>
+        <input
+          type="number"
+          step="any"
+          aria-label=${own}
+          .value=${String(pitch ?? '')}
+          ?disabled=${unavailable || !fits}
+          @change=${(e: Event) => this.setPitch(field, e)}
+        />
+      </div>
+      <p hint>
+        ${fits && length !== undefined && longest !== undefined && limit !== undefined
+          ? i18next.t('figure.text.repeat-what-pitch-gives', {
+              length: length.toLocaleString(),
+              count: repeat.count,
+              longest: longest.toLocaleString(),
+              limit
+            })
+          : i18next.t(fits ? 'figure.text.repeat-fits-length' : 'figure.text.repeat-fixed-count')}
+      </p>
+    </section>`
+  }
+  /**
+   * A pitch always goes through `set-repeat`: the command moves the longest length with it (at most `limit` copies),
+   * which a plain input edit would not. Refused only when the authored length would already hold more copies than
+   * that -- said with the numbers.
+   */
+  private setPitch(field: { id: string; value: number }, event: Event) {
+    const input = event.target as HTMLInputElement
+    const pitch = input.valueAsNumber
+    if (!Number.isFinite(pitch) || pitch === field.value) return
+    try {
+      this.session!.command({ kind: 'set-repeat', part: this.selected, pitch })
+      this.error = ''
+      this.changed()
+    } catch (error) {
+      input.value = String(field.value)
+      const code = (error as { code?: string })?.code
+      const message = error instanceof Error ? error.message : String(error)
+      const found = /\((\d[\d.]*) mm\) a pitch under ([\d.]+) mm makes more than (\d+)/.exec(message)
+      this.error =
+        code === 'INPUT_RANGE' && found
+          ? i18next.t('figure.text.repeat-pitch-too-small', { length: Number(found[1]).toLocaleString(), min: found[2], limit: found[3] })
+          : message
+    }
+  }
   /** Choose a part, from the list, the canvas or a place row. A figure-level tab gives way to the part's properties. */
   private choose(id: string) {
-    this.selected = id
+    /* A copy on the canvas selects its repeat: the part the author made. */
+    this.selected = id ? ownerOf(id) : id
     if (id && (this.tab === 'verdict' || this.tab === 'view' || this.tab === 'history')) this.tab = 'properties'
   }
   private asset(): unknown {
@@ -674,11 +847,12 @@ export class FigureV3Editor extends LitElement {
     const view = this.session?.read()
     if (!view) return html`<p>${i18next.t('figure.text.opening-model')}</p>`
     const unavailable = view.loading || !!view.error || view.saving || !view.context
-    const part = view.geometry.find(g => g.id === this.selected)
+    const part = view.geometry.find(g => ownerOf(g.id) === this.selected)
     /* The controls (state inputs) have their own place in the motion tab; these are the design values. */
     const design = view.fields.filter(i => i.role !== 'state')
-    const own = design.filter(i => this.selected && i.id.startsWith(this.selected + '.'))
-    const common = design.filter(i => !view.geometry.some(g => i.id.startsWith(g.id + '.')))
+    /* A repeat's own row values (its pitch) have their own section, not the shape's. */
+    const own = design.filter(i => this.selected && i.id.startsWith(this.selected + '.') && !i.id.startsWith(this.selected + '.repeat.'))
+    const common = design.filter(i => !view.geometry.some(g => i.id.startsWith(ownerOf(g.id) + '.')))
     const status = view.loading
       ? 'figure.text.loading-figure'
       : view.saving
@@ -714,21 +888,16 @@ export class FigureV3Editor extends LitElement {
           slot="start"
           .budget=${this.budget}
           @show-maturity=${() => (this.tab = 'verdict')}
-          .parts=${view.geometry.map(
-            (g): V3PartRow => ({
-              id: g.id,
-              provider: (g as { shape?: { provider?: string } }).shape?.provider ?? '',
-              hidden: this.hiddenParts.has(g.id),
-              invisible: (g as { visible?: boolean }).visible === false
-            })
-          )}
+          .parts=${this.partRows(view.geometry)}
+          .partBudget=${this.partBudgetOf(asset as V3Asset | undefined)}
+          @set-detail-level=${(e: CustomEvent) => this.linkCommand({ kind: 'set-detail-level', level: e.detail.level })}
           .selected=${this.selected}
           ?locked=${unavailable}
           @add-part=${(e: CustomEvent) => this.add(e.detail.kind)}
           @select-part=${(e: CustomEvent) => this.choose(e.detail.id)}
           @toggle-part-hidden=${(e: CustomEvent) => this.toggleHiddenPart(e.detail.id)}
           @set-all-parts-hidden=${(e: CustomEvent) =>
-            (this.hiddenParts = e.detail.hidden ? new Set(view.geometry.map(g => g.id)) : new Set())}
+            (this.hiddenParts = e.detail.hidden ? new Set(view.geometry.map(g => ownerOf(g.id))) : new Set())}
           @move-part-up=${(e: CustomEvent) => this.movePart(e.detail.id, e.detail.to)}
           @move-part-down=${(e: CustomEvent) => this.movePart(e.detail.id, e.detail.to)}
           @duplicate-part=${(e: CustomEvent) => this.duplicatePart(e.detail.id)}
@@ -744,6 +913,7 @@ export class FigureV3Editor extends LitElement {
           : html`<figure-v3-canvas
           .view=${this.view}
           .parts=${this.drawnParts(view.geometry, asset)}
+          .fan=${this.fanOf(asset as V3Asset | undefined)}
           .palette=${view.palette ?? {}}
           .context=${view.context ?? ''}
           .selected=${this.selected}
@@ -774,16 +944,18 @@ export class FigureV3Editor extends LitElement {
                       <input
                         name-field
                         aria-label=${i18next.t('figure.label.name')}
-                        .value=${this.selected}
-                        ?disabled=${unavailable}
+                        .value=${partLabelOf(this.selected)}
+                        ?disabled=${unavailable || !!repeatOf(this.selected, view.geometry)}
                         @change=${(e: Event) => this.renamePart(e.target as HTMLInputElement)}
                       />
                     </div>
+                    ${this.renderRepeatNote(view.geometry)}
                   </section>
-                  ${this.renderGroups(groupFields(design, this.selected), 'figure.label.group-placement-size', 'figure.label.group-shape', unavailable, this.renderTools(unavailable))}
+                  ${this.renderRepeat(asset as V3Asset | undefined, view.geometry, unavailable)}
+                  ${this.renderGroups(groupFields(own, this.selected), 'figure.label.group-placement-size', 'figure.label.group-shape', unavailable, this.renderTools(unavailable))}
                   ${this.renderLinks(unavailable, 'shape')}
                   <figure-v3-material
-                    .body=${part}
+                    .body=${{ ...part, id: this.selected }}
                     .palette=${view.palette ?? {}}
                     ?locked=${unavailable}
                     @v3-part-edit=${(e: CustomEvent) => this.run(() => this.session!.edit(e.detail.edit))}

package/client/modeller/v3-fields.ts

@@ -60,3 +60,39 @@ export function partLabelOf(id: string): string {
   return places.length ? `${path[0].replace(/\.repeat$/, '')} ${places.join('·')}` : id
 }
 
+/**
+ * The repeat a body is a copy of: its name, how many copies it makes, and which copy this is (counted from 1). Nothing
+ * for a body that is not a copy.
+ */
+export function repeatOf(id: string, geometry: readonly unknown[] | undefined): { name: string; count: number; index: number } | null {
+  const path = pathOf(id)
+  if (!path) {
+    /* The repeat itself, by its name: how many copies it makes now. */
+    const copies = (geometry ?? []).filter(g => pathOf((g as { id?: string }).id ?? '')?.[0] === `${id}.repeat`).length
+    return copies ? { name: id, count: copies, index: 0 } : null
+  }
+  const count = (geometry ?? []).filter(g => pathOf((g as { id?: string }).id ?? '')?.[0] === path[0]).length
+  const index = path.find((step): step is number => typeof step === 'number')
+  return { name: String(path[0]).replace(/\.repeat$/, ''), count, index: (index ?? 0) + 1 }
+}
+
+function pathOf(id: string): unknown[] | null {
+  if (!id.startsWith('[')) return null
+  try {
+    const path = JSON.parse(id)
+    return Array.isArray(path) && typeof path[0] === 'string' ? path : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The authored part a body belongs to: a repeat's copy belongs to its repeat (`roller`), any other body is its own. The
+ * editor selects, lists, hides and names parts by this -- what the author made, not every body the kernel draws
+ * (user, 2026-09-24: the conveyor's sixteen rollers were sixteen rows).
+ */
+export function ownerOf(id: string): string {
+  const path = pathOf(id)
+  return path ? String(path[0]).replace(/\.repeat$/, '') : id
+}
+

package/client/modeller/v3-joint-fan.ts

@@ -0,0 +1,292 @@
+import { compileV3Asset, compileV3Graph, v3WorldBoxesOf, v3WritersOf } from '@hatiolab/figure-model'
+import type { V3Asset } from '@hatiolab/figure-model'
+
+import type { V3RenderPart } from './v3-renderer.js'
+
+/*
+ * Where the selected part turns, and how far -- a translucent fan on the editing board (V2's joint gizmo, inventory
+ * 3.38). An axis name says nothing about which way a part swings; on a six-axis arm the author went to the preview and
+ * pushed each slider to its end to find out. The fan lies in the plane the part turns in, at the pivot, open from the
+ * control's lowest value to its highest; the edge at the value the figure holds now is where the part is.
+ *
+ * It is found by evaluating, not by reading the graph's shape: the frame that carries the part is sampled across the
+ * control's range, and a point at a fixed distance from the pivot traces the fan. So the direction is right whatever
+ * the slope of the control, and a joint inside other joints is drawn where its parents put it.
+ *
+ * Two ways a part turns are read:
+ *   - a motion made in the modeller (`add-motion`): `<part>.motion`, the frame it moves is its seat, the pivot the
+ *     seat's origin;
+ *   - a joint the converter wrote from V2 (`<joint>.motion` · `<joint>.chain`): the part is composed on the joint's
+ *     chain, the pivot is the joint's origin (`<joint>.frameOnParent`).
+ * A slide has no fan. Nothing is drawn when the turn cannot be found -- a fan in some guessed plane would point the
+ * wrong way.
+ */
+
+/** The fan's name on the board. It is not a part: not in the list, not saved, not picked. */
+export const JOINT_FAN = '__joint-fan'
+
+/** How thick the fan is: thin enough not to hide the part, thick enough to be seen edge-on. */
+const THICKNESS = 6
+/** About one segment every six degrees, so a full turn reads as a circle. */
+const STEP_DEG = 6
+
+type Pose = { r: number[][]; t: number[] }
+interface Node {
+  id: string
+  op: string
+  args: string[]
+  outputs: Record<string, string>
+  params?: Record<string, string>
+}
+
+const apply = (p: Pose, v: number[]) => [0, 1, 2].map(i => p.r[i]![0]! * v[0]! + p.r[i]![1]! * v[1]! + p.r[i]![2]! * v[2]! + p.t[i]!)
+const sub = (a: number[], b: number[]) => a.map((v, i) => v - b[i]!)
+const dot = (a: number[], b: number[]) => a.reduce((s, v, i) => s + v * b[i]!, 0)
+const cross = (a: number[], b: number[]) => [a[1]! * b[2]! - a[2]! * b[1]!, a[2]! * b[0]! - a[0]! * b[2]!, a[0]! * b[1]! - a[1]! * b[0]!]
+const norm = (a: number[]) => {
+  const l = Math.hypot(...a)
+  return l > 1e-9 ? a.map(v => v / l) : null
+}
+
+/** How far outside a part's box a pivot may lie and still be on the part: the kernel's contact skin. */
+const SEAM = 1
+/** An origin this deep in a part's box (a share of its half-measure, on every axis) is housed by the part. */
+const HOUSED = 0.5
+const AXIS_NAMES = ['x', 'y', 'z'] as const
+type WorldBox = { centre: Record<'x' | 'y' | 'z', number>; extent: Record<'x' | 'y' | 'z', number> }
+
+interface Turn {
+  /** The node whose value carries the moving frame into the figure's frame. */
+  carrier: string
+  /** The pivot, in the moving frame. */
+  pivot: number[]
+  /** The axis, in the moving frame. */
+  axis: number[]
+  /** Where the part sits, in the moving frame -- which way the fan's reference edge points. */
+  toward: number[]
+  /** The part the joint turns -- the fan is sized from it, so a joint shows one fan whichever part is selected. */
+  turnedPart: string
+  /** The state input that turns it. */
+  control: { id: string; min: number; max: number }
+}
+
+function turnOf(asset: V3Asset, part: string, values: Record<string, unknown>, box: WorldBox | undefined): Turn | null {
+  const m = asset.document.model as unknown as { nodes: Node[]; constants: { id: string; value: number }[]; inputs: { id: string; role?: string; min?: number; max?: number }[] }
+  const node = (id: string) => m.nodes.find(n => n.id === id)
+  const constant = (ref: string) => m.constants.find(c => c.id === ref)?.value
+  const valueOf = (n: Node | undefined) => (n ? values[Object.values(n.outputs)[0]!] : undefined) as Pose | undefined
+  const controlOf = (ref: string | undefined, seen = new Set<string>()): Turn['control'] | null => {
+    if (!ref || seen.has(ref)) return null
+    seen.add(ref)
+    const input = m.inputs.find(i => i.id === ref && i.role === 'state')
+    if (input) return { id: input.id, min: input.min ?? 0, max: input.max ?? 0 }
+    const writer = m.nodes.find(n => Object.values(n.outputs).includes(ref))
+    for (const arg of writer?.args ?? []) {
+      const found = controlOf(arg, seen)
+      if (found) return found
+    }
+    return null
+  }
+  const axisOf = (motion: Node) => {
+    const axis = motion.args.slice(0, 3).map(constant)
+    return axis.every(v => typeof v === 'number') ? norm(axis as number[]) : null
+  }
+
+  /* Made in the modeller: the part's own motion turns its seat about the seat's origin. */
+  const own = node(`${part}.motion`)
+  if (own) {
+    if (own.op !== 'axis-turn@1') return null
+    const axis = axisOf(own)
+    const control = controlOf(own.args[3])
+    const at = valueOf(node(`${part}.pose`))
+    if (!axis || !control || !at) return null
+    return { carrier: own.id, pivot: [0, 0, 0], axis, toward: at.t, control, turnedPart: part }
+  }
+
+  /*
+    Written by the converter: a joint (`<joint>.motion`, its origin `<joint>.frameOnParent`) carries its own part and
+    everything fastened below it, through its chain (the first joint of a chain has only its attachment). A part shows
+    the joint it is to that part of the mechanism (user, 2026-09-24: 「elbow-housing itself is a axis」 · 「please check
+    all that logic and concept」), tested in this order on the joints as they stand now:
+      1. housing -- a joint's origin lies deep inside the part, which is centred on it: the shoulder housing shows the
+         shoulder and the elbow housing the elbow, though another joint carries them;
+      2. turned -- the joint that carries the part, when its axis passes through the part: through its middle for a
+         body that rolls on it (the wrist roll, the tool flange, the gripper body), through its root for a link (the
+         upper arm, the forearm);
+      3. otherwise none: the pedestal (the base's axis runs through it but turns it not), the fingers.
+    An axis passing through a part is not enough by itself: the wrist roll's axis runs the forearm's length and the
+    tool roll's through the wrist pitch, and neither turns them (an earlier rule said so, and was wrong).
+  */
+  if (!box) return null
+  const carrierOf = (joint: string) => (node(`${joint}.chain`) ? `${joint}.chain` : `${joint}.attach`)
+  const mine = node(`${part}.moved`)?.args.find(arg => /\.(chain|attach)\.value$/.test(arg))?.replace(/\.value$/, '')
+  const centre = AXIS_NAMES.map(a => box.centre[a])
+  const half = AXIS_NAMES.map(a => box.extent[a] / 2)
+  const joints = m.nodes
+    .filter(n => n.op === 'axis-turn@1' && n.id.endsWith('.motion') && node(n.id.replace(/\.motion$/, '.frameOnParent')))
+    .map(motion => {
+      const joint = motion.id.replace(/\.motion$/, '')
+      const carrier = carrierOf(joint)
+      const frame = valueOf(node(carrier))
+      const origin = valueOf(node(`${joint}.frameOnParent`))
+      const local = axisOf(motion)
+      if (!frame || !origin || !local) return null
+      const at = apply(frame, origin.t)
+      const along = norm([0, 1, 2].map(i => dot(frame.r[i]!, local)))
+      if (!along) return null
+      const off = sub(centre, at)
+      return {
+        joint,
+        motion,
+        carrier,
+        origin,
+        /* How deep the origin lies: 0 at the centre, 1 on the box's face, on the axis where it is shallowest. */
+        depth: Math.max(...[0, 1, 2].map(i => Math.abs(off[i]!) / (half[i]! + SEAM))),
+        fromCentre: Math.hypot(...off),
+        through: lineMeetsBox(at, along, centre, half)
+      }
+    })
+    .filter((c): c is NonNullable<typeof c> => !!c)
+  const housing = joints.filter(c => c.depth <= HOUSED).sort((a, b) => a.fromCentre - b.fromCentre)[0]
+  const carrying = joints.find(c => c.carrier === mine)
+  const chosen = housing ?? (carrying && carrying.through ? carrying : undefined)
+  if (!chosen) return null
+  const axis = axisOf(chosen.motion)
+  const control = controlOf(chosen.motion.args[3])
+  if (!axis || !control) return null
+  /* The reference edge points at what the joint turns: of the parts it carries, the one farthest off its axis. */
+  const flatOff = (t: number[]) => {
+    const rel = sub(t, chosen.origin.t)
+    return Math.hypot(...sub(rel, axis.map(v => v * dot(rel, axis))))
+  }
+  const turned = m.nodes
+    .filter(n => n.id.endsWith('.moved') && n.args.includes(`${chosen.carrier}.value`))
+    .map(n => ({ id: n.id.replace(/\.moved$/, ''), t: valueOf(node(n.id.replace(/\.moved$/, '.pose')))?.t }))
+    .filter((one): one is { id: string; t: number[] } => !!one.t)
+    .sort((a, b) => flatOff(b.t) - flatOff(a.t))[0]
+  return { carrier: chosen.carrier, pivot: chosen.origin.t, axis, toward: turned?.t ?? chosen.origin.t, control, turnedPart: turned?.id ?? part }
+}
+
+/**
+ * The fan for the part, as a body to stand on the board, or null when the part does not turn. `values` are the
+ * inputs the figure is drawn with now (a pose in hand included), so the fan follows the arm as it is posed.
+ */
+export function jointFanOf(asset: V3Asset, part: string, values: Record<string, number> = {}): V3RenderPart | null {
+  if (!part) return null
+  let graph: ReturnType<typeof compileV3Graph>
+  try {
+    graph = compileV3Graph(asset.document.model as never)
+  } catch {
+    return null
+  }
+  const inputs = { ...asset.designInputs, ...asset.stateDefaults, ...values }
+  const at = (over: Record<string, number>) => graph.evaluate({ ...inputs, ...over }).values as Record<string, unknown>
+  let now: Record<string, unknown>
+  try {
+    now = at({})
+  } catch {
+    return null
+  }
+  let box: WorldBox | undefined
+  try {
+    box = v3WorldBoxesOf(
+      compileV3Asset({ ...asset, designInputs: { ...asset.designInputs, ...pick(values, asset.designInputs) }, stateDefaults: { ...asset.stateDefaults, ...pick(values, asset.stateDefaults) } })
+        .evaluate()
+        .geometry.filter(g => g.id === part),
+      v3WritersOf(asset)
+    )[0]
+  } catch {
+    box = undefined
+  }
+  const turn = turnOf(asset, part, now, box)
+  if (!turn) return null
+  const carrierRef = Object.values(asset.document.model.nodes.find(n => n.id === turn.carrier)!.outputs)[0]!
+  const carrierNow = now[carrierRef] as Pose | undefined
+  if (!carrierNow) return null
+
+  /* The reference edge points from the pivot toward the part, in the plane it turns in; any perpendicular if it sits on the axis. */
+  const rel = sub(turn.toward, turn.pivot)
+  const inPlane = sub(rel, turn.axis.map(v => v * dot(rel, turn.axis)))
+  const d = norm(inPlane) ?? norm(cross(turn.axis, Math.abs(turn.axis[0]!) < 0.9 ? [1, 0, 0] : [0, 1, 0]))!
+  /*
+    Sized from what the joint turns, as V2 sized it from the joint's child: selecting the elbow housing or the forearm
+    shows the elbow's one fan, not a smaller one for the smaller part (user, 2026-09-24).
+  */
+  const radius = Math.max(60, Math.round(Math.max(largestMeasureOf(asset, turn.turnedPart, inputs), Math.hypot(...inPlane)) * 0.6))
+  const edge = turn.pivot.map((v, i) => v + d[i]! * radius)
+
+  const { min, max } = turn.control
+  if (!(max > min)) return null
+  const steps = Math.max(2, Math.ceil((max - min) / STEP_DEG))
+  const pivot = apply(carrierNow, turn.pivot)
+  const traced: number[][] = []
+  try {
+    for (let i = 0; i <= steps; i++) {
+      const s = min + ((max - min) * i) / steps
+      traced.push(apply(at({ [turn.control.id]: s })[carrierRef] as Pose, edge))
+    }
+  } catch {
+    return null
+  }
+
+  /* The fan's own frame: x toward the first traced point, y along the axis as it stands now, z completing them. */
+  const axisNow = norm([0, 1, 2].map(i => dot(carrierNow.r[i]!, turn.axis)))
+  const first = norm(sub(traced[0]!, pivot))
+  if (!axisNow || !first) return null
+  const zAxis = cross(first, axisNow)
+  const r = [0, 1, 2].map(i => [first[i]!, axisNow[i]!, zAxis[i]!])
+  const local = (p: number[]) => {
+    const v = sub(p, pivot)
+    return { x: dot(v, first), y: dot(v, zAxis) }
+  }
+  const full = max - min >= 359.999
+  const profile = [...(full ? [] : [{ x: 0, y: 0 }]), ...traced.map(local)].map(p => ({ x: Math.round(p.x * 1000) / 1000, y: Math.round(p.y * 1000) / 1000 }))
+
+  return {
+    id: JOINT_FAN,
+    shape: { provider: 'polygon', dimensions: { height: THICKNESS }, profile },
+    pose: { t: pivot, r },
+    material: { token: '__joint-fan', transparent: true },
+    /** Which control turns it: the joint the fan shows. */
+    turns: turn.control.id
+  } as unknown as V3RenderPart
+}
+
+/** The values in hand that belong to a record's keys (design inputs, or state defaults). */
+function pick(values: Record<string, number>, of: Record<string, number>): Record<string, number> {
+  return Object.fromEntries(Object.entries(values).filter(([id]) => id in of))
+}
+
+/** A part's largest own measure (a box side, a diameter, a length) at the inputs given; 0 when it cannot be read. */
+function largestMeasureOf(asset: V3Asset, part: string, inputs: Record<string, number>): number {
+  try {
+    const body = compileV3Asset({ ...asset, designInputs: pick(inputs, asset.designInputs), stateDefaults: pick(inputs, asset.stateDefaults) })
+      .evaluate()
+      .geometry.find(g => g.id === part) as { shape?: { dimensions?: Record<string, number> } } | undefined
+    const dims = Object.entries(body?.shape?.dimensions ?? {}).map(([k, v]) => (k.startsWith('radius') ? v * 2 : v))
+    return dims.length ? Math.max(...dims) : 0
+  } catch {
+    return 0
+  }
+}
+
+/** Whether the line through `at` along `along` passes through the box (centre, half-measures), within the skin. */
+function lineMeetsBox(at: number[], along: number[], centre: number[], half: number[]): boolean {
+  let lo = -Infinity,
+    hi = Infinity
+  for (let i = 0; i < 3; i++) {
+    const min = centre[i]! - half[i]! - SEAM,
+      max = centre[i]! + half[i]! + SEAM
+    if (Math.abs(along[i]!) < 1e-12) {
+      if (at[i]! < min || at[i]! > max) return false
+      continue
+    }
+    const t1 = (min - at[i]!) / along[i]!,
+      t2 = (max - at[i]!) / along[i]!
+    lo = Math.max(lo, Math.min(t1, t2))
+    hi = Math.min(hi, Math.max(t1, t2))
+    if (lo > hi) return false
+  }
+  return true
+}
+