@things-factory/figure-ui 10.1.46 → 10.1.48

package/client/modeller/v3-fields.ts

@@ -0,0 +1,84 @@
+/*
+ * The values a part or the figure is edited by, grouped as V2's inspector showed them: position, rotation and size
+ * as one row of three cells each (X · Y · Z read together), and the shape's own measures one to a line under their
+ * own title. Kept apart from the editor so the grouping is tested without a browser.
+ */
+export interface FieldLike {
+  id: string
+  unit: string
+  role?: string
+  value: number
+}
+
+export type Axis3 = 'x' | 'y' | 'z'
+const AXES: readonly Axis3[] = ['x', 'y', 'z']
+
+export type FieldGroup =
+  | { kind: 'vector'; name: 'position' | 'rotation' | 'size'; cells: Record<Axis3, FieldLike> }
+  | { kind: 'single'; name: string; field: FieldLike }
+
+/** The name a single value goes by: its id without the part, `dimension.` and corner numbers read as words. */
+function nameOf(rest: string): string {
+  return rest.replace(/^dimension\./, '')
+}
+
+/**
+ * The part's own values (`<part>.…`), or with no part the figure's (`size.x` …). Position, rotation and size come
+ * first, each only when all three of its axes are there; the rest follow in the order they are declared.
+ */
+export function groupFields(fields: readonly FieldLike[], part?: string): { vectors: FieldGroup[]; singles: FieldGroup[] } {
+  const prefix = part ? `${part}.` : ''
+  const own = fields.filter(f => (part ? f.id.startsWith(prefix) : !f.id.includes('.') || /^size\.[xyz]$/.test(f.id)))
+  const byId = new Map(own.map(f => [f.id, f]))
+  const used = new Set<string>()
+  const vectors: FieldGroup[] = []
+  for (const name of ['position', 'rotation', 'size'] as const) {
+    const ids = AXES.map(axis => `${prefix}${name}.${axis}`)
+    if (!ids.every(id => byId.has(id))) continue
+    ids.forEach(id => used.add(id))
+    vectors.push({ kind: 'vector', name, cells: { x: byId.get(ids[0]!)!, y: byId.get(ids[1]!)!, z: byId.get(ids[2]!)! } })
+  }
+  const singles: FieldGroup[] = own.filter(f => !used.has(f.id)).map(field => ({ kind: 'single', name: nameOf(field.id.slice(prefix.length)), field }))
+  return { vectors, singles }
+}
+
+/**
+ * The name a person reads for a body. A repeated body's id is its path through the repeats (`["roller.repeat",0,
+ * "roller.value"]`), which the list showed as it was; it reads as the repeat's name and the member's place counted
+ * from 1 -- `roller 1`, and `rack 2·3` inside two repeats. Any other id is its own name.
+ */
+export function partLabelOf(id: string): string {
+  if (!id.startsWith('[')) return id
+  let path: unknown
+  try {
+    path = JSON.parse(id)
+  } catch {
+    return id
+  }
+  if (!Array.isArray(path) || typeof path[0] !== 'string') return id
+  const places = path.filter((step): step is number => typeof step === 'number').map(n => n + 1)
+  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) return 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
+  }
+}
+

package/client/modeller/v3-help.ts

@@ -0,0 +1,41 @@
+import '@material/web/icon/icon.js'
+
+import { html, nothing, type ReactiveController, type ReactiveControllerHost } from 'lit'
+import { i18next } from '@operato/i18n'
+
+/**
+ * V2's help toggles: a small 「?」 beside a title opens the longer explanation under it. Explanations left open on every
+ * section made the side read as clutter (user, 2026-09-24); the author opens the one they want. What was opened stays
+ * open while the author moves between parts.
+ */
+export class HelpToggles implements ReactiveController {
+  private opened = new Set<string>()
+
+  constructor(private readonly host: ReactiveControllerHost) {
+    host.addController(this)
+  }
+
+  hostConnected() {}
+
+  isOpen(key: string) {
+    return this.opened.has(key)
+  }
+
+  toggle(key: string) {
+    if (this.opened.has(key)) this.opened.delete(key)
+    else this.opened.add(key)
+    this.host.requestUpdate()
+  }
+
+  /** The 「?」: it takes no line of its own, it sits in the title's spare width. */
+  button(key: string) {
+    const shown = this.opened.has(key)
+    return html`<button help aria-label=${i18next.t('figure.label.help')} aria-expanded=${shown ? 'true' : 'false'} @click=${() => this.toggle(key)}>
+      <md-icon>${shown ? 'help' : 'help_outline'}</md-icon>
+    </button>`
+  }
+
+  hint(key: string) {
+    return this.opened.has(key) ? html`<p hint>${i18next.t(key)}</p>` : nothing
+  }
+}

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
+}
+

package/client/modeller/v3-keys.ts

@@ -0,0 +1,34 @@
+/*
+ * The modeller's keys (V2 had undo and redo on Ctrl+Z / Ctrl+Y; these add what a person reaches for next). Read apart
+ * from the element so the rule is tested without a browser.
+ *
+ * Typing is never taken: a key pressed in a field belongs to the field -- Backspace in a name box deletes a letter,
+ * not the part.
+ */
+export type KeyAction = 'undo' | 'redo' | 'duplicate' | 'remove' | 'deselect'
+
+export interface KeyLike {
+  key: string
+  ctrlKey?: boolean
+  metaKey?: boolean
+  shiftKey?: boolean
+  altKey?: boolean
+  /** The element the key was pressed in -- the first of the event's composed path. */
+  target?: { tagName?: string; isContentEditable?: boolean } | null
+}
+
+const TYPING = new Set(['INPUT', 'SELECT', 'TEXTAREA'])
+
+export function keyActionOf(e: KeyLike, selected: string): KeyAction | null {
+  if (e.target && (TYPING.has(String(e.target.tagName).toUpperCase()) || e.target.isContentEditable)) return null
+  if (e.altKey) return null
+  const mod = !!(e.ctrlKey || e.metaKey)
+  const key = e.key.toLowerCase()
+  if (mod && key === 'z') return e.shiftKey ? 'redo' : 'undo'
+  if (mod && key === 'y') return 'redo'
+  if (!selected) return null
+  if (mod && key === 'd') return 'duplicate'
+  if (!mod && (key === 'delete' || key === 'backspace')) return 'remove'
+  if (!mod && key === 'escape') return 'deselect'
+  return null
+}

package/client/modeller/v3-links.ts

@@ -1,4 +1,5 @@
-import { v3AttachmentsOf, v3BindingsOf } from '@hatiolab/figure-model'
+import { compileV3Graph, defaultInstanceSizeRange, foldInstanceSizeRange, v3AttachmentsOf, v3BindingsOf, v3InstanceSizeLimitsOf } from '@hatiolab/figure-model'
+import type { V3SizeRange } from '@hatiolab/figure-model'
 import type { V3Asset, V3BindingPlace, V3Face } from '@hatiolab/figure-model'
 
 /*
@@ -21,7 +22,8 @@ const modelOf = (asset: V3Asset) =>
 /** What one dimension of a part is worked out from. */
 export type Follow =
   | { of: 'own' }
-  | { of: 'instance'; axis: Axis }
+  /** `times` 1 is the instance size itself; any other is a share of it -- V2's proportional rule. */
+  | { of: 'instance'; axis: Axis; times: number }
   | { of: 'part'; part: string; axis: Axis }
   | { of: 'input'; input: string }
   /** Worked out some other way (the converter writes expressions) — shown, not offered as a choice. */
@@ -34,15 +36,23 @@ export type Follow =
  */
 export function followOf(asset: V3Asset, part: string, axis: Axis): Follow {
   const m = modelOf(asset)
+  /*
+    A link routes the dimension through `<part>.dimension.<axis>`; before any link the shape reads its measure directly,
+    and that may already be worked out -- the converter writes V2's rules there (ROBOT_ARM's flange filled what was left).
+  */
   const node = m.nodes.find(n => n.id === `${part}.dimension.${axis}`)
-  if (!node) return { of: 'own' }
+  const start = node ? node.args[0] : m.nodes.find(n => n.id === `${part}.shape`)?.args[AXES.indexOf(axis)]
+  if (!start || m.constants.some(c => c.id === start)) return { of: 'own' }
   const writerOf = (ref: string) => m.nodes.find(n => Object.values(n.outputs).includes(ref))
   const seen = new Set<string>()
+  const constant = (ref: string) => m.constants.find(c => c.id === ref)
+  /* The constant factors met on the way back: a share of the instance size is `size × share`. */
+  let times = 1
   const walk = (ref: string): Follow => {
     if (seen.has(ref)) return { of: 'expression' }
     seen.add(ref)
     const instance = /^size\.([xyz])$/.exec(ref)
-    if (instance) return { of: 'instance', axis: instance[1] as Axis }
+    if (instance) return { of: 'instance', axis: instance[1] as Axis, times: Math.round(times * 1e6) / 1e6 }
     const other = /^(.+)\.dimension\.([xyz])\.value$/.exec(ref)
     if (other) return { of: 'part', part: other[1]!, axis: other[2] as Axis }
     const input = m.inputs.find(i => i.id === ref)
@@ -50,10 +60,19 @@ export function followOf(asset: V3Asset, part: string, axis: Axis): Follow {
     const writer = writerOf(ref)
     if (!writer) return { of: 'expression' }
     /* Follow the one argument that is not a constant factor. */
-    const onward = writer.args.filter(arg => !m.constants.some(c => c.id === arg))
-    return onward.length === 1 ? walk(onward[0]!) : { of: 'expression' }
+    const onward = writer.args.filter(arg => !constant(arg))
+    if (onward.length !== 1) return { of: 'expression' }
+    /*
+      Only a product is a share of its source. A sum with a number is not (V2's 「fill what is left」 is the size plus a
+      negative gap -- ROBOT_ARM's tool flange), nor anything else; those read as worked out some other way.
+    */
+    const factors = writer.args.filter(arg => constant(arg)).map(arg => constant(arg)!.value)
+    if (writer.op === 'mul@1') times *= factors.reduce((a, b) => a * b, 1)
+    else if (writer.op === 'div@1' && writer.args[0] === onward[0] && factors.length === 1 && factors[0] !== 0) times /= factors[0]!
+    else if (factors.some(v => v !== 0) || !['mul@1', 'div@1', 'add@1', 'sub@1'].includes(writer.op)) return { of: 'expression' }
+    return walk(onward[0]!)
   }
-  return walk(node.args[0]!)
+  return walk(start)
 }
 
 /** Whether the asset declares an instance size on an axis — only then can a dimension follow it. */
@@ -66,8 +85,34 @@ export function fastenedTo(asset: V3Asset, part: string): string | null {
 
 /** Whether a dimension of this part can follow something — box-shaped, whose three sizes are X, Y and Z. */
 export function canFollow(asset: V3Asset, part: string): boolean {
+  return followableAxes(asset, part).length > 0
+}
+
+/**
+ * The axes whose size can follow something, by the shape's own measures: a box's X · Y · Z; a cylinder's radius (read
+ * as X) and length (Y) -- its shape takes those two, so it has no Z of its own (V2's sizing cards had the cylinder's
+ * two as well).
+ */
+export function followableAxes(asset: V3Asset, part: string): Axis[] {
   const shape = modelOf(asset).nodes.find(n => n.id === `${part}.shape`)
-  return !!shape && (shape.op === 'box-shape@1' || shape.op === 'rounded-box@1')
+  if (!shape) return []
+  if (shape.op === 'box-shape@1' || shape.op === 'rounded-box@1') return [...AXES]
+  if (shape.op === 'cylinder-shape@1') return ['x', 'y']
+  return []
+}
+
+/** What a part's own measure on an axis is now (a box's side, a cylinder's radius or length), at the design as it stands. */
+export function dimensionNow(asset: V3Asset, part: string, axis: Axis): number | undefined {
+  const m = modelOf(asset)
+  const ref = m.nodes.find(n => n.id === `${part}.shape`)?.args[AXES.indexOf(axis)]
+  if (!ref) return undefined
+  try {
+    const values = compileV3Graph(asset.document.model as never).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values as Record<string, number>
+    const value = values[ref]
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+  } catch {
+    return undefined
+  }
 }
 
 /** Whether `attach` can take this part: a box, or a cylinder (figure-model measures its faces since 0.1.47). */
@@ -89,6 +134,17 @@ export function positionsWorkedOut(asset: V3Asset, part: string): Axis[] {
   return AXES.filter((_axis, i) => !own(pose.args[i]!) && !constant(pose.args[i]!))
 }
 
+/**
+ * Whether the part's position on an axis is a share of the instance size (`scale-position`): `size.<axis> × share`.
+ * Such a position is worked out too, but it already grows with the figure, so it is not offered again.
+ */
+export function positionIsShare(asset: V3Asset, part: string, axis: Axis): boolean {
+  const m = modelOf(asset)
+  const ref = m.nodes.find(n => n.id === `${part}.pose`)?.args[AXES.indexOf(axis)]
+  const writer = ref ? m.nodes.find(n => Object.values(n.outputs).includes(ref)) : undefined
+  return !!writer && writer.op === 'mul@1' && writer.args[0] === `size.${axis}` && m.constants.some(c => c.id === writer.args[1])
+}
+
 /** How a part moves, if it does: slide or turn, along which axis, driven by which control. */
 export interface Motion {
   kind: 'slide' | 'turn'
@@ -127,7 +183,7 @@ export function choiceOf(follow: Follow): string {
     case 'own':
       return 'own'
     case 'instance':
-      return `instance:${follow.axis}`
+      return follow.times === 1 ? `instance:${follow.axis}` : `share:${follow.axis}`
     case 'part':
       return `part:${follow.part}:${follow.axis}`
     case 'input':
@@ -168,3 +224,39 @@ export const holdsThings = (asset: V3Asset) => (asset.document.capabilities.name
 
 /** What `accepts` a person typed: names split on commas, trimmed, blanks and repeats dropped. */
 export const acceptsOf = (typed: string) => [...new Set(typed.split(',').map(one => one.trim()).filter(Boolean))]
+
+/**
+ * The sizes a board may give this figure: the range it declares now, and the range measured afresh -- the default
+ * (1 mm to ten times the authored size) narrowed only where the figure cannot follow, by the converter's own functions.
+ * A range measured when a part filled what the others left (ROBOT_ARM: Y from 1,854 mm) stays narrow after the part is
+ * made to grow with the figure; measuring again gives the figure its whole range back. Nothing when no size is declared.
+ */
+export function instanceRangeOf(asset: V3Asset): { declared: V3SizeRange; measured: V3SizeRange } | undefined {
+  const inputs = modelOf(asset).inputs
+  const declared = {} as V3SizeRange
+  const authored = {} as Record<Axis, number>
+  for (const axis of AXES) {
+    const input = inputs.find(i => i.id === `size.${axis}` && i.role === 'design')
+    const at = asset.designInputs[`size.${axis}`]
+    if (!input || typeof at !== 'number') return undefined
+    declared[axis] = { min: input.min ?? 0, max: input.max ?? Infinity }
+    authored[axis] = at
+  }
+  const start = defaultInstanceSizeRange(authored)
+  const measured = foldInstanceSizeRange(start, v3InstanceSizeLimitsOf(asset, start)).range
+  return { declared, measured }
+}
+
+/** Whether measuring again would change the declared range (to a micrometre). */
+export function rangeDiffers(a: V3SizeRange, b: V3SizeRange): boolean {
+  return AXES.some(axis => Math.abs(a[axis].min - b[axis].min) > 1e-3 || Math.abs(a[axis].max - b[axis].max) > 1e-3)
+}
+
+/**
+ * Whether the figure is a mechanism -- a part turns about a joint. Such a figure should grow by one ratio (chief
+ * architect's ruling 2026-09-24); the modeller proposes it, the author declares it.
+ */
+export function turnsAboutAJoint(asset: V3Asset): boolean {
+  return modelOf(asset).nodes.some(n => n.op === 'axis-turn@1')
+}
+