@things-factory/figure-ui 10.1.48 → 10.1.50

package/client/modeller/v3-first-save.ts

@@ -0,0 +1,34 @@
+import { isPlaceholderType, TYPE_LENGTH, TYPE_PATTERN } from '@hatiolab/figure-model'
+
+/*
+ * The first save of a new figure asks for its type and name, as V2's page did. The type is the name a board places
+ * the figure by; it freezes when the figure is released (ADR-0063 decision 4). The V3 modeller saved a new figure
+ * under a temporary machine name instead and asked nothing -- the author had to find the field afterwards
+ * (user, 2026-09-25: V2 features are not to go missing).
+ */
+
+/** A type as typed, made into the shape a type has: letters, digits and underscores, upper case. */
+export function typeOf(raw: string): string {
+  return raw.trim().replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()
+}
+
+/**
+ * Whether this name could be released, by the format's own rules (`type-not-identifier`, `type-is-placeholder`).
+ * Saving under it is not blocked -- it can still change before release -- but the author hears it now.
+ */
+export function releasableType(type: string): boolean {
+  return !isPlaceholderType(type) && TYPE_PATTERN.test(type) && type.length >= TYPE_LENGTH.min && type.length <= TYPE_LENGTH.max
+}
+
+/** Why the first save cannot go on with this type, as an i18n key, or null when it can. */
+export function firstSaveRefusalOf(type: string, taken: readonly string[]): { key: string; type?: string } | null {
+  if (!type) return { key: 'figure.text.enter-a-type-name' }
+  if (taken.includes(type)) return { key: 'figure.text.type-name-already-taken', type }
+  return null
+}
+
+/** What the first save asks for. */
+export interface FirstSave {
+  type: string
+  name: string
+}

package/client/modeller/v3-gizmo.ts

@@ -17,6 +17,16 @@ export interface GizmoReach {
   scale: boolean
   /** The inputs sizing the part along X, Y and Z, when it can be sized. */
   sizes?: [string, string, string]
+  /**
+   * Per axis, the part's own measure, or null where the measure follows another (a square section's depth following
+   * its width): a scale drag writes the own ones and leaves a followed one to what it follows.
+   */
+  ownSizes?: (string | null)[]
+  /**
+   * A round part keeps its section round, as V2 kept it (`keepRound`): the radii across (X and Z) take the one factor
+   * the drag gave most; the length along Y takes its own. A sphere's three radii take one factor together.
+   */
+  round?: { across: string[]; along: string[] }
 }
 
 /** Shapes whose first three arguments are the extent along X, Y and Z. */
@@ -26,10 +36,11 @@ interface Node {
   id: string
   op: string
   args: string[]
+  outputs?: Record<string, string>
   params?: Record<string, unknown>
 }
 interface AssetLike {
-  document: { model: { nodes: Node[]; inputs: Array<{ id: string; role?: string }> } }
+  document: { model: { nodes: Node[]; inputs: Array<{ id: string; role?: string }>; constants?: Array<{ id: string; value: number }> } }
 }
 
 const AXES = ['x', 'y', 'z'] as const
@@ -53,14 +64,39 @@ export function gizmoReachOf(asset: AssetLike, part: string): GizmoReach {
     v3AttachmentsOf(asset as unknown as V3Asset)[part] === null
   const posed = direct || reseated
   const shape = nodes.find(node => node.id === `${part}.shape`)
+  const mine = (ids: string[]) => ids.every(id => id.startsWith(`${part}.`) && design.has(id))
+  const round =
+    shape?.op === 'cylinder-shape@1' && mine(shape.args.slice(0, 2))
+      ? { across: [shape.args[0]!], along: [shape.args[1]!] }
+      : shape?.op === 'frustum-shape@1' && mine(shape.args.slice(0, 3))
+        ? { across: shape.args.slice(0, 2), along: [shape.args[2]!] }
+        : shape?.op === 'sphere-shape@1' && mine(shape.args.slice(0, 3))
+          ? { across: shape.args.slice(0, 3), along: [] }
+          : undefined
   const extent = shape && BOXES.has(shape.op) ? shape.args.slice(0, 3) : []
   const sizes =
     extent.length === 3 && extent.every(id => id.startsWith(`${part}.`) && design.has(id)) ? (extent as [string, string, string]) : undefined
+  /*
+    The part's own measure, also when another reads it: a measure some other part follows is read through a node of its
+    own times 1 (`link-dimension`), and it is still the author's number -- the upper arm's width, which the forearm
+    follows, is the upper arm's to drag.
+  */
+  const constants = asset.document.model.constants ?? []
+  const ownMeasure = (id: string): string | null => {
+    if (id.startsWith(`${part}.`) && design.has(id)) return id
+    const writer = nodes.find(node => Object.values(node.outputs ?? {}).includes(id))
+    const one = writer?.op === 'mul@1' && writer.args.length === 2 && constants.find(c => c.id === writer.args[1])?.value === 1
+    return one && writer!.args[0]!.startsWith(`${part}.`) && design.has(writer!.args[0]!) ? writer!.args[0]! : null
+  }
+  const ownSizes = extent.length === 3 && !sizes ? extent.map(ownMeasure) : undefined
+  const someOwn = !!ownSizes?.some(Boolean)
   return {
     translate: posed && allDesign(own('position')) && own('position').every((id, i) => pose!.args[i] === id),
     rotate: posed && allDesign(own('rotation')) && own('rotation').every((id, i) => pose!.args[3 + i] === id),
-    scale: !!sizes,
-    ...(sizes ? { sizes } : {})
+    scale: !!sizes || !!round || someOwn,
+    ...(sizes ? { sizes } : {}),
+    ...(someOwn ? { ownSizes } : {}),
+    ...(round ? { round } : {})
   }
 }
 
@@ -87,5 +123,18 @@ export function gizmoChanges(part: string, reach: GizmoReach, result: GizmoResul
     reach.sizes.forEach((id, i) => {
       if (sizes[id] !== undefined) put(id, 'mm', Math.max(1, Math.round(sizes[id]! * result.scale![i]!)))
     })
+  if (result.scale && reach.scale && reach.ownSizes)
+    reach.ownSizes.forEach((id, i) => {
+      if (id && sizes[id] !== undefined && Math.abs(result.scale![i]! - 1) > 1e-4) put(id, 'mm', Math.max(1, Math.round(sizes[id]! * result.scale![i]!)))
+    })
+  if (result.scale && reach.scale && reach.round) {
+    const [sx, sy, sz] = result.scale
+    /* The factor the drag moved most: across for a cylinder (X or Z), any axis for a sphere. */
+    const most = (factors: number[]) => factors.reduce((a, b) => (Math.abs(b - 1) > Math.abs(a - 1) ? b : a), 1)
+    const sphere = reach.round.along.length === 0
+    const across = sphere ? most([sx!, sy!, sz!]) : most([sx!, sz!])
+    for (const id of reach.round.across) if (sizes[id] !== undefined) put(id, 'mm', Math.max(1, Math.round(sizes[id]! * across)))
+    for (const id of reach.round.along) if (sizes[id] !== undefined) put(id, 'mm', Math.max(1, Math.round(sizes[id]! * sy!)))
+  }
   return changes
 }

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

@@ -0,0 +1,116 @@
+import * as THREE from 'three'
+import { compileV3Asset } from '@hatiolab/figure-model'
+import type { V3Asset, V3Joint } from '@hatiolab/figure-model'
+
+import type { GizmoResult } from './v3-gizmo.js'
+import type { V3RenderPart } from './v3-renderer.js'
+
+/*
+ * A gizmo drag on a part that hangs from a joint edits the joint, not the part (ADR-0093; r3 §3: the modeller changes
+ * the inputs of the relation, and never breaks it because a computed place was moved):
+ *
+ *   - turning a part on a revolute or continuous joint sets the joint's value -- the turn about the joint's axis;
+ *   - sliding a part on a prismatic joint along its axis sets its value;
+ *   - moving a part any other way moves the joint's origin: the gap along the face it sits on, the offset across it.
+ *
+ * What would break a relation is refused and said: an origin that follows another part's size, a joint that mimics
+ * another, a turn on a joint that does not turn.
+ */
+
+export type JointDrag =
+  | { kind: 'value'; input: string; unit: 'deg' | 'mm' | 'ratio'; value: number }
+  | { kind: 'joint'; joint: V3Joint }
+  | { kind: 'refused'; reason: 'mimic' | 'fixed-turn' | 'origin-follows' | 'turned-slide' | 'off-axis'; joint: string; leader?: string; axis?: string }
+
+type Axis = 'x' | 'y' | 'z'
+const AXES: Axis[] = ['x', 'y', 'z']
+/** The axis each face faces along, and which way (as figure-model's `V3_FACES`). */
+const FACE_AXIS: Record<string, Axis> = { left: 'x', right: 'x', bottom: 'y', top: 'y', back: 'z', front: 'z' }
+const FACE_SIGN: Record<string, number> = { left: -1, right: 1, bottom: -1, top: 1, back: -1, front: 1 }
+
+const matrixOf = (r: number[][]) => new THREE.Matrix4().set(r[0]![0]!, r[0]![1]!, r[0]![2]!, 0, r[1]![0]!, r[1]![1]!, r[1]![2]!, 0, r[2]![0]!, r[2]![1]!, r[2]![2]!, 0, 0, 0, 0, 1)
+const eulerMatrix = (deg: number[]) => new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(...(deg.map(THREE.MathUtils.degToRad) as [number, number, number]), 'XYZ'))
+const unit = (axis: string) => new THREE.Vector3(/x/i.test(axis) ? 1 : 0, /y/i.test(axis) ? 1 : 0, /z/i.test(axis) ? 1 : 0)
+const round = (v: number, step: number) => Number((Math.round(v / step) * step).toFixed(Math.max(0, -Math.floor(Math.log10(step)))))
+
+/** The part's own quarter turn in the joint frame, as the record says it. */
+const turnMatrix = (j: V3Joint) => eulerMatrix(AXES.map(a => j.origin?.turn?.[a] ?? 0))
+
+/** 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: V3Joint, part: V3RenderPart, 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()
+  return now.multiply(own.invert()).multiply(turn.invert())
+}
+
+export function jointDragOf(asset: V3Asset, id: string, part: V3RenderPart, result: GizmoResult, values: Record<string, number>): JointDrag | null {
+  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
+  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
+
+  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: j.mimic.joint }
+    /* 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 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: j.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!)
+    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)
+
+  if (j.type === 'prismatic') {
+    if (j.mimic) return { kind: 'refused', reason: 'mimic', joint: j.id, leader: j.mimic.joint }
+    /* 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 at = (v: number) => {
+      const g = compileV3Asset(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 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) }
+    }
+  }
+
+  /* Moving the joint's origin: the change in the frame the joint sits in. */
+  const local = moved.clone().applyMatrix4(frame.clone().invert())
+  const normal: Axis = 'plane' in j.body0 ? 'y' : FACE_AXIS[j.body0.face]!
+  /* Which way a larger gap moves the part: out of the face it meets (on the plane: up when it stands, down when it hangs). */
+  const outward = 'plane' in j.body0 ? (j.body1.face === 'bottom' ? 1 : -1) : ((j.origin?.facing ?? 'meet') === 'meet' ? 1 : -1) * FACE_SIGN[j.body0.face]!
+  const origin: NonNullable<V3Joint['origin']> = { ...(j.origin ?? {}) }
+  const along = local[normal]
+  if (Math.abs(along) >= 0.5) {
+    const gap = origin.gap ?? 0
+    if (typeof gap !== 'number') return { kind: 'refused', reason: 'origin-follows', joint: j.id }
+    origin.gap = round(gap + outward * along, 1)
+  }
+  for (const axis of AXES.filter(a => a !== normal)) {
+    const d = local[axis]
+    if (Math.abs(d) < 0.5) continue
+    const how = origin.align?.[axis] ?? 'centre'
+    const was = how === 'centre' ? 0 : typeof how === 'object' && typeof how.mm === 'number' ? how.mm : null
+    if (was === null) return { kind: 'refused', reason: 'origin-follows', joint: j.id }
+    origin.align = { ...(origin.align ?? {}), [axis]: { mm: round(was + d, 1) } }
+  }
+  return { kind: 'joint', joint: { ...j, origin } }
+}

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

@@ -14,8 +14,7 @@ import type { V3RenderPart } from './v3-renderer.js'
  * 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 record (ADR-0093): at the joint's origin, about its axis;
  *   - 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
@@ -92,15 +91,29 @@ function turnOf(asset: V3Asset, part: string, values: Record<string, unknown>, b
     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 }
+  /*
+    A joint record (ADR-0093): the fan stands at the joint -- the point on the parent's face the child is fastened at --
+    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')
+  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
+  })()
+  if (record) {
+    const child = record.body1.part
+    const carrier = node(`${child}.world`) ? `${child}.world` : `${child}.chain`
+    const pose = valueOf(node(`${child}.pose`))
+    const motion = node(`${child}.motion`)
+    const control = controlOf(motion?.args[3])
+    if (!node(carrier) || !pose || !control) return null
+    /* 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(AXIS_NAMES.map(a => (a.toUpperCase() === record.axis ? 1 : 0))))
+    if (!axis) return null
+    return { carrier, pivot, axis, toward: [0, 0, 0], control, turnedPart: child }
   }
 
   /*

package/client/modeller/v3-keys.ts

@@ -5,7 +5,11 @@
  * 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 type KeyAction = 'undo' | 'redo' | 'duplicate' | 'remove' | 'deselect' | GizmoKey
+
+/** The gizmo's modes on W, E and R, as the scene has them. */
+export type GizmoKey = 'translate' | 'rotate' | 'scale'
+const GIZMO_KEYS: Record<string, GizmoKey> = { w: 'translate', e: 'rotate', r: 'scale' }
 
 export interface KeyLike {
   key: string
@@ -15,6 +19,12 @@ export interface KeyLike {
   altKey?: boolean
   /** The element the key was pressed in -- the first of the event's composed path. */
   target?: { tagName?: string; isContentEditable?: boolean } | null
+  /**
+   * Pressed with the canvas focused. The scene takes W, E and R there itself; they are passed on only from elsewhere
+   * -- a part picked in the parts list left the focus there, and the gizmo could not be had at all (2026-09-25).
+   * Passing a key the scene already took would toggle the gizmo off again.
+   */
+  inScene?: boolean
 }
 
 const TYPING = new Set(['INPUT', 'SELECT', 'TEXTAREA'])
@@ -30,5 +40,6 @@ export function keyActionOf(e: KeyLike, selected: string): KeyAction | null {
   if (mod && key === 'd') return 'duplicate'
   if (!mod && (key === 'delete' || key === 'backspace')) return 'remove'
   if (!mod && key === 'escape') return 'deselect'
+  if (!mod && !e.shiftKey && !e.inScene && GIZMO_KEYS[key]) return GIZMO_KEYS[key]
   return null
 }

package/client/modeller/v3-links.ts

@@ -1,6 +1,6 @@
-import { compileV3Graph, defaultInstanceSizeRange, foldInstanceSizeRange, v3AttachmentsOf, v3BindingsOf, v3InstanceSizeLimitsOf } from '@hatiolab/figure-model'
+import { V3_FACES, 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'
+import type { V3Asset, V3BindingPlace, V3Face, V3Joint } from '@hatiolab/figure-model'
 
 /*
  * What a V3 part is tied to — the readers behind the parts' size response, fastening and motion sections (parity rows
@@ -121,6 +121,30 @@ export function canFasten(asset: V3Asset, part: string): boolean {
   return canFollow(asset, part) || shape?.op === 'cylinder-shape@1'
 }
 
+/** Where a part sits across the face it is fastened to, on one axis: centred, level with an edge, or a distance off centre. */
+export type Alignment = 'centre' | 'min' | 'max' | 'mm'
+
+/**
+ * The axes across the face a part is fastened to — the two a fastening does not set by itself. On the plane the figure is
+ * mounted on these are X and Z, and the plane has no edges, so only centred or a distance is offered there.
+ */
+export function alignAxesOf(target: V3Face | 'plane'): { axis: Axis; edges: boolean }[] {
+  if (target === 'plane') return (['x', 'z'] as Axis[]).map(axis => ({ axis, edges: false }))
+  const along = V3_FACES[target] as Axis
+  return AXES.filter(axis => axis !== along).map(axis => ({ axis, edges: true }))
+}
+
+/** The `align` of an attach command from the form's choices: only the axes across that face, and centred ones left out. */
+export function alignOf(target: V3Face | 'plane', how: Partial<Record<Axis, Alignment>>, mm: Partial<Record<Axis, number>>) {
+  const align: Partial<Record<Axis, 'min' | 'max' | { mm: number }>> = {}
+  for (const { axis, edges } of alignAxesOf(target)) {
+    const one = how[axis] ?? 'centre'
+    if (one === 'mm' && mm[axis]) align[axis] = { mm: mm[axis]! }
+    else if ((one === 'min' || one === 'max') && edges) align[axis] = one
+  }
+  return Object.keys(align).length ? align : undefined
+}
+
 /**
  * The axes on which the part's position is worked out from other values rather than being its own number — the
  * converter writes V2's anchor rules that way. `fix-position` makes one its own number where it is now.
@@ -147,16 +171,20 @@ export function positionIsShare(asset: V3Asset, part: string, axis: Axis): boole
 
 /** How a part moves, if it does: slide or turn, along which axis, driven by which control. */
 export interface Motion {
-  kind: 'slide' | 'turn'
+  kind: 'slide' | 'turn' | 'continuous'
   axis: Axis | '?'
   control?: { id: string; unit?: string; min?: number; max?: number }
+  /** A joint that moves with another (URDF's mimic): the leader's value times `multiplier`, plus `offset`. */
+  follows?: { joint: string; multiplier: number; offset?: number }
 }
 
 export function motionOf(asset: V3Asset, part: string): Motion | undefined {
   const m = modelOf(asset)
   const node = m.nodes.find(n => n.id === `${part}.motion`)
   if (!node) return undefined
-  const kind = node.op === 'axis-turn@1' ? 'turn' : 'slide'
+  const record = asset.joints?.find(j => j.body1.part === part)
+  const endless = record?.type === 'revolute' && record.lowerLimit === undefined && record.upperLimit === undefined
+  const kind = endless ? 'continuous' : node.op === 'axis-turn@1' ? 'turn' : 'slide'
   const unit = node.args.slice(0, 3).map(ref => m.constants.find(c => c.id === ref)?.value)
   const axis = AXES[unit.findIndex(v => v !== undefined && v !== 0)] ?? '?'
   /* The quantity is the fourth argument, a state input directly or through the nodes that scale it. */
@@ -174,7 +202,46 @@ export function motionOf(asset: V3Asset, part: string): Motion | undefined {
     }
     return undefined
   }
-  return { kind, axis, control: control(quantity) }
+  return { kind, axis, control: control(quantity), ...(record?.mimic ? { follows: record.mimic } : {}) }
+}
+
+/** What the motion form holds: how the part moves, and either its own control or the joint it moves with. */
+export interface MotionForm {
+  kind: 'slide' | 'turn' | 'continuous'
+  axis: Axis
+  id: string
+  min: number
+  max: number
+  /** The joint this one moves with; empty for a joint with its own control. */
+  follow: string
+  multiplier: number
+  offset: number
+}
+
+/**
+ * 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.
+ */
+export function leadersFor(asset: V3Asset, part: string, kind: MotionForm['kind']): V3Joint[] {
+  return (asset.joints ?? []).filter(j => j.body1.part !== part && j.type !== 'fixed' && !j.mimic && (j.type === 'prismatic') === (kind === 'slide'))
+}
+
+/**
+ * The joint record the motion form writes for a part fastened by `joint`. A joint of its own gets its limits (none for
+ * a turn without end, as in USD) and a control; a follower gets the leader, the multiplier and the offset, and no
+ * control or limits of its own — its range is the leader's times the multiplier.
+ */
+export function motionJoint(joint: V3Joint, m: MotionForm, part: string): V3Joint {
+  const moving = {
+    id: joint.id,
+    body0: joint.body0,
+    body1: joint.body1,
+    ...(joint.origin ? { origin: joint.origin } : {}),
+    type: m.kind === 'slide' ? ('prismatic' as const) : ('revolute' as const),
+    axis: m.axis.toUpperCase() as 'X' | 'Y' | 'Z'
+  }
+  if (m.follow) return { ...moving, mimic: { joint: m.follow, multiplier: m.multiplier, ...(m.offset ? { offset: m.offset } : {}) } }
+  return { ...moving, ...(m.kind === 'continuous' ? {} : { lowerLimit: m.min, upperLimit: m.max }), state: { id: m.id || `${part}-${m.kind}` } }
 }
 
 /** The select's value for what a dimension follows now. */

package/client/modeller/v3-live.ts

@@ -77,3 +77,14 @@ export function scrubbed(start: number, pixels: number, step: number): number {
   const digits = Math.max(0, -Math.floor(Math.log10(step)))
   return Number(value.toFixed(digits))
 }
+
+/**
+ * The bodies to draw while a value is in hand, over every input as the session holds it now (`current`): the pose the
+ * author has already set with the other controls, and the design values. Drawing over the asset's saved defaults put
+ * every other joint back to its saved angle while one slider moved (user, 2026-09-24: the arm jumped on release).
+ */
+export function liveOverSession(asset: V3Asset, current: Record<string, number>, live: LiveValues): V3RenderPart[] | null {
+  if (!isLive(live)) return null
+  return livePartsOf(asset, { ...live, values: { ...current, ...live.values } })
+}
+

package/client/modeller/v3-product-session.ts

@@ -24,6 +24,8 @@ export interface V3ProductStore {
     creationId?: string
     /** The card's picture. Absent when the browser could not draw one; the source is saved either way. */
     thumbnail?: string
+    /** The type name a new figure is created under (the first save asks for it). Not sent for an existing one. */
+    type?: string
   }): Promise<V3ProductRecord>
 }
 
@@ -136,13 +138,13 @@ export function createV3ProductSession(store: V3ProductStore) {
      * nothing about drawing. A save with no picture is a save: a tab in the background cannot draw, and the
      * source matters more than the card (see `v3-thumbnail.ts`).
      */
-    async save({ thumbnail }: { thumbnail?: string } = {}) {
+    async save({ thumbnail, type }: { thumbnail?: string; type?: string } = {}) {
       const control = writable(),
         requestEpoch = epoch
       const exported = workspace.export(control)
       saving = true
       try {
-        const record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId, thumbnail })
+        const record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId, thumbnail, ...(id || !type ? {} : { type }) })
         if (requestEpoch !== epoch) return read()
         if (!record.id || (id !== undefined && record.id !== id)) throw Error('저장 응답의 Figure 대상이 다릅니다.')
         if (serializeV3Asset(parseV3Asset(record.source)) !== exported.text)

package/client/modeller/v3-refusals.ts

@@ -0,0 +1,21 @@
+/*
+ * A command refused because the figure could not be drawn at an end of its declared size range, in the author's words
+ * with the numbers and where to put it right -- not the kernel's English (user, 2026-09-24: 「what is this warning
+ * message means?」). Kept apart from the element so it is tested without a browser.
+ */
+
+type Say = (key: string, params: Record<string, string>) => string
+
+/** The refusal in words, or nothing for any other refusal. */
+export function sizeRangeRefusalOf(error: unknown, say: Say): string | null {
+  if ((error as { code?: string })?.code !== 'INSTANCE_SIZE_RANGE') return null
+  const message = error instanceof Error ? error.message : String(error)
+  const found = /size\.([xyz]):\s*(below|above) ([\d.]+) mm [^(;]*(?:\(([^)]+)\))?;/.exec(message)
+  if (!found) return null
+  const [, axis, side, mm, part] = found
+  return say(side === 'below' ? 'figure.text.size-range-too-small' : 'figure.text.size-range-too-large', {
+    axis: axis!.toUpperCase(),
+    mm: Number(mm).toLocaleString(undefined, { maximumFractionDigits: 1 }),
+    part: part ?? ''
+  })
+}

package/client/modeller/v3-stage-model.ts

@@ -126,6 +126,30 @@ export function gizmoResultOf(part: V3RenderPart, after: Record<string, unknown>
   return result
 }
 
+/**
+ * A drag as amounts, for a part whose place is worked out (`nudge-part`): how far its origin moved and how far each of
+ * its angles turned (rigid@1's order, degrees). Nothing on an axis that did not change.
+ */
+export function nudgeOf(part: V3RenderPart, result: GizmoResult): { by: Partial<Record<'x' | 'y' | 'z', number>>; turn: Partial<Record<'x' | 'y' | 'z', number>> } {
+  const axes = ['x', 'y', 'z'] as const
+  const by: Partial<Record<'x' | 'y' | 'z', number>> = {}
+  const turn: Partial<Record<'x' | 'y' | 'z', number>> = {}
+  if (result.position) axes.forEach((axis, i) => {
+    const d = round(result.position![i]! - (part.pose.t[i] as number))
+    if (Math.abs(d) > 1e-6) by[axis] = d
+  })
+  if (result.rotation) {
+    const r = part.pose.r
+    const now = new THREE.Euler().setFromRotationMatrix(new THREE.Matrix4().set(r[0]![0]!, r[0]![1]!, r[0]![2]!, 0, r[1]![0]!, r[1]![1]!, r[1]![2]!, 0, r[2]![0]!, r[2]![1]!, r[2]![2]!, 0, 0, 0, 0, 1), 'XYZ')
+    const was: number[] = [now.x, now.y, now.z].map(radians => (radians * 180) / Math.PI)
+    axes.forEach((axis, i) => {
+      const d = round(result.rotation![i]! - was[i]!)
+      if (Math.abs(d) > 1e-6) turn[axis] = d
+    })
+  }
+  return { by, turn }
+}
+
 /** The keys of `next` whose values differ from `current` -- only those are set, so the scene raises no echo. */
 export function changedKeys(current: Record<string, unknown>, next: Record<string, unknown>): Record<string, unknown> | null {
   const diff: Record<string, unknown> = {}

package/client/pages/figure-v3-modeller-page.ts

@@ -4,7 +4,7 @@ import { PageView } from '@operato/shell'
 import { createV3ProductSession } from '../modeller/v3-product-session.js'
 import { v3ProductStore } from '../graphql/v3-store.js'
 import { i18next } from '@operato/i18n'
-import { fetchFigure, updateFigure } from '../graphql/index.js'
+import { fetchFigure, fetchFigureTypeNames, updateFigure } from '../graphql/index.js'
 import { occupancyFromParts } from '../modeller/v3-occupancy.js'
 import type { V3AuthoringAction } from '@hatiolab/figure-model'
 import '../modeller/v3-editor.js'
@@ -13,6 +13,10 @@ import '../modeller/figure-history-panel.js'
 import '../modeller/figure-v3-verdict.js'
 import '../modeller/figure-v3-properties.js'
 import type { V3BudgetLine } from '../modeller/v3-maturity.js'
+import { OxPrompt } from '@operato/popup'
+import { openPopup } from '@operato/layout'
+import '../modeller/figure-v3-first-save.js'
+import type { FirstSave } from '../modeller/v3-first-save.js'
 
 /**
  * The V3 product page has exactly one authoritative workspace for UI and AI input transactions.
@@ -171,7 +175,16 @@ export class FigureV3ModellerPage extends PageView {
     const id = this.session.read().id
     const wanted = input.value.trim().replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()
     input.value = wanted
-    if (!id || !wanted || wanted === this.row.type) return
+    /*
+      A figure not saved yet has no row to rename: the type is held here and the first save's question opens with it.
+      The field was disabled until the first save, so a type typed there went nowhere and was asked for again
+      (2026-09-25).
+    */
+    if (!id) {
+      this.row = { ...this.row, type: wanted || undefined }
+      return
+    }
+    if (!wanted || wanted === this.row.type) return
     try {
       const result = await updateFigure(id, { type: wanted })
       this.typeError = ''
@@ -268,8 +281,17 @@ export class FigureV3ModellerPage extends PageView {
     const view = this.session.read()
     if (view.saving) return false
     if (!view.dirty) return true
-    // The shell invokes this while the edited model is still visible, before navigating away.
-    this.discardApproved = window.confirm('저장하지 않은 변경을 버리고 이동하시겠습니까?')
+    /*
+      The shell asks this while the edited model is still on screen. The app's own prompt, as V2 and every operato
+      screen ask -- not the browser's confirm box (user, 2026-09-24).
+    */
+    this.discardApproved = !!(await OxPrompt.open({
+      type: 'warning',
+      title: i18next.t('figure.text.unsaved-changes'),
+      text: i18next.t('figure.text.leave-without-saving'),
+      confirmButton: { text: i18next.t('figure.button.leave-without-saving') },
+      cancelButton: { text: i18next.t('figure.button.keep-editing') }
+    }))
     return this.discardApproved
   }
   async pageUpdated(changes: Record<string, unknown>, lifecycle: { resourceId?: string }) {
@@ -302,13 +324,31 @@ export class FigureV3ModellerPage extends PageView {
       this.error = error instanceof Error ? error.message : String(error)
     }
   }
+  /** The first save's question, over the names this domain already uses (V2 asked the same). */
+  private askFirstSave = async (name: string): Promise<FirstSave | undefined> => {
+    const taken = await fetchFigureTypeNames().catch(() => [] as string[])
+    return openPopup<FirstSave>(html`<figure-v3-first-save .type=${this.row.type ?? ''} .name=${name} .taken=${taken}></figure-v3-first-save>`, {
+      backdrop: true,
+      size: 'small',
+      title: i18next.t('figure.title.save-new-figure')
+    }).result
+  }
   get context() {
-    return { title: this.session.read().name ?? 'Figure', actions: [] }
+    return {
+      title: this.session.read().name ?? 'Figure',
+      actions: [],
+      /*
+        No heading line: the canvas is what this page is for, and the name is already in the properties' first section
+        (and the browser tab). The title stays, not emptied, because the MDI tab reads it too -- the heading is switched
+        off where it is drawn (`ox-page-title-bar`). V2's page did this; it was lost when that page was removed.
+      */
+      heading: false
+    }
   }
   render() {
     if (this.error) return html`<p role="alert" class="error">${this.error}</p>`
     const view = this.session.read()
-    return html`<figure-v3-editor .session=${this.session} .revision=${this.revision} .instances=${this.instances} .budget=${this.budget} @v3-changed=${this.changed}>
+    return html`<figure-v3-editor .session=${this.session} .firstSave=${this.askFirstSave} .revision=${this.revision} .instances=${this.instances} .budget=${this.budget} @v3-changed=${this.changed}>
       ${this.commandError ? html`<p slot="notice" fit-error role="alert">${this.commandError}</p>` : ''}
       <figure-v3-properties
         slot="figure"
@@ -326,7 +366,6 @@ export class FigureV3ModellerPage extends PageView {
               : html`<input
                   .value=${this.row.type ?? ''}
                   placeholder=${i18next.t('figure.text.figure-type-placeholder')}
-                  ?disabled=${!view.id}
                   @change=${this.renameType}
                 />`}
             ${this.typeError ? html`<small role="alert">${this.typeError}</small>` : ''}

package/dist-client/graphql/v3-store.js

@@ -12,13 +12,14 @@ export const v3ProductStore = {
     async save(request) {
         const response = await client.mutate({
             mutation: gql `
-        mutation SaveFigureV3($source: String!, $id: String, $expectedSource: String, $creationId: String, $thumbnail: String) {
+        mutation SaveFigureV3($source: String!, $id: String, $expectedSource: String, $creationId: String, $thumbnail: String, $type: String) {
           saveFigureV3(
             source: $source
             id: $id
             expectedSource: $expectedSource
             creationId: $creationId
             thumbnail: $thumbnail
+            type: $type
           ) {
             id
             source