@things-factory/figure-ui 10.1.49 → 10.1.51

package/client/modeller/v3-editor.ts

@@ -22,16 +22,20 @@ import { gizmoChanges, gizmoReachOf, type GizmoReach, type GizmoResult } from '.
 import { keyActionOf } from './v3-keys.js'
 import { groupFields, ownerOf, partLabelOf, repeatOf, type FieldLike, type FieldGroup } from './v3-fields.js'
 import { SidePanelStyles } from './side-panel-styles.js'
+import { ScrollbarStyles } from '@operato/styles'
 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 { sizeRangeRefusalOf } from './v3-refusals.js'
 import type { V3RenderPart } from './v3-renderer.js'
 import type { V3BudgetLine } from './v3-maturity.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'
+import { jointDragOf } from './v3-joint-drag.js'
+import type { FirstSave } from './v3-first-save.js'
+import { isLive, livePartsOf, liveOverSession, NOTHING_LIVE, scrubbed, scrubStep, type LiveValues } from './v3-live.js'
 
 
 /**
@@ -44,7 +48,8 @@ type SideTab = 'properties' | 'capability' | 'motion' | 'verdict' | 'view' | 'hi
 /** Product editor surface. The injected session is shared by page persistence and AI commands. */
 @customElement('figure-v3-editor')
 export class FigureV3Editor extends LitElement {
-  static styles = [SidePanelStyles, css`
+  /* The operato scrollbar, as every scrolling panel of the app has it -- the side panel scrolled with the browser's own. */
+  static styles = [ScrollbarStyles, SidePanelStyles, css`
     :host {
       display: flex;
       flex-direction: column;
@@ -226,6 +231,11 @@ export class FigureV3Editor extends LitElement {
   @property({ type: Number }) instances?: number
   /** The cost line the parts list shows, from the maturity report. */
   @property({ attribute: false }) budget?: V3BudgetLine
+  /**
+   * Asks the type and name of a figure saved for the first time (the host has the catalogue's names); undefined
+   * when the author cancels, and then nothing is saved. Without it a new figure is saved under a temporary type.
+   */
+  @property({ attribute: false }) firstSave?: (name: string) => Promise<FirstSave | undefined>
   @state() private selected = ''
   @state() private error = ''
   @state() private tab: SideTab = 'properties'
@@ -262,14 +272,26 @@ export class FigureV3Editor extends LitElement {
   /** A value in hand -- typed, held on a spinner, scrubbed, dragged -- drawn at once and recorded on release. */
   @state() private live: LiveValues = NOTHING_LIVE
   private lastContext: string | null = null
-  /** The modeller's keys (`v3-keys.ts`): undo, redo, duplicate, remove, back to the whole figure. */
+  /** The modeller's keys (`v3-keys.ts`): undo, redo, duplicate, remove, back to the whole figure, the gizmo's modes. */
   private onKey = (e: KeyboardEvent) => {
     const view = this.session?.read()
     if (!view || view.loading || view.saving || !view.context || !this.isConnected) return
-    const action = keyActionOf({ key: e.key, ctrlKey: e.ctrlKey, metaKey: e.metaKey, shiftKey: e.shiftKey, altKey: e.altKey, target: e.composedPath()[0] as HTMLElement }, this.selected)
+    const canvas = this.renderRoot.querySelector<FigureV3Canvas>('figure-v3-canvas')
+    const path = e.composedPath()
+    const action = keyActionOf(
+      { key: e.key, ctrlKey: e.ctrlKey, metaKey: e.metaKey, shiftKey: e.shiftKey, altKey: e.altKey, target: path[0] as HTMLElement, inScene: !!canvas && path.includes(canvas) },
+      this.selected
+    )
     if (!action) return
     e.preventDefault()
-    if (action === 'undo') view.canUndo && this.run(() => this.session!.undo())
+    /*
+      The session's history is the only one. With the canvas focused the scene took Ctrl+Z as well, undoing on its own
+      board the last value the canvas had written -- which the canvas then told as a drag: an undo of a drag on a
+      converted part wrote the drag again (2026-09-25). Heard first (capture) and kept from the scene.
+    */
+    e.stopPropagation()
+    if (action === 'translate' || action === 'rotate' || action === 'scale') canvas?.gizmo(action)
+    else if (action === 'undo') view.canUndo && this.run(() => this.session!.undo())
     else if (action === 'redo') view.canRedo && this.run(() => this.session!.redo())
     else if (action === 'duplicate') this.duplicatePart(this.selected)
     else if (action === 'remove') this.removePart(this.selected)
@@ -277,10 +299,10 @@ export class FigureV3Editor extends LitElement {
   }
   connectedCallback() {
     super.connectedCallback()
-    window.addEventListener('keydown', this.onKey)
+    window.addEventListener('keydown', this.onKey, true)
   }
   disconnectedCallback() {
-    window.removeEventListener('keydown', this.onKey)
+    window.removeEventListener('keydown', this.onKey, true)
     super.disconnectedCallback()
   }
   protected willUpdate(_changed: PropertyValues) {
@@ -299,7 +321,7 @@ export class FigureV3Editor extends LitElement {
       this.error = ''
       this.changed()
     } catch (error) {
-      this.error = error instanceof Error ? error.message : String(error)
+      this.error = sizeRangeRefusalOf(error, (key, params) => i18next.t(key, params)) ?? (error instanceof Error ? error.message : String(error))
     } finally {
       /* Committed or refused, the value in hand is gone: the figure as it stands is drawn again. */
       this.live = NOTHING_LIVE
@@ -307,7 +329,7 @@ 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 ?? [])
+    const parts = (asset ? liveOverSession(asset as V3Asset, this.currentInputs(), this.live) : null) ?? drawableV3Parts(geometry ?? [])
     return parts.filter(body => !this.hiddenParts.has(ownerOf((body as { id: string }).id)))
   }
   /**
@@ -317,11 +339,20 @@ export class FigureV3Editor extends LitElement {
   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)
+      return jointFanOf(asset, this.selected, { ...this.currentInputs(), ...this.live.values })
     } catch {
       return null
     }
   }
+  /**
+   * Every input as the session holds it now -- the pose the author has set with the controls, and design values. The
+   * asset's source carries only the saved defaults, so drawing a value in hand over it put every other joint back to its
+   * saved angle while one slider moved, and the arm jumped when released (user, 2026-09-24).
+   */
+  private currentInputs(): Record<string, number> {
+    const view = this.session?.read()
+    return view ? Object.fromEntries(view.fields.map(field => [field.id, field.value as number])) : {}
+  }
   /** 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) {
     this.live = { values: { ...this.live.values, ...values }, ...(edit ? { edit } : this.live.edit ? { edit: this.live.edit } : {}) }
@@ -338,9 +369,20 @@ export class FigureV3Editor extends LitElement {
         not from the one on screen, which stands wherever the author left it turned. A picture that cannot
         be taken is not an error: the save goes on without it (see `v3-thumbnail.ts`).
       */
+      let type: string | undefined
+      if (!this.session.read().id && this.firstSave) {
+        const answer = await this.firstSave(this.session.read().name ?? '')
+        if (!answer) return
+        /* The name is the figure's own, in the asset: one step of the history, like typing it in the properties. */
+        if (answer.name !== this.session.read().name) {
+          this.session.command({ kind: 'rename', name: answer.name })
+          this.changed()
+        }
+        type = answer.type
+      }
       const view = this.session.read()
       const thumbnail = await captureV3Thumbnail(drawableV3Parts(view.geometry ?? []), view.palette ?? {})
-      const promise = this.session.save({ thumbnail })
+      const promise = this.session.save({ thumbnail, type })
       this.changed()
       await promise
       this.error = ''
@@ -411,12 +453,37 @@ export class FigureV3Editor extends LitElement {
   /** A drag, written back as the part's own inputs — one step of the history, like typing the numbers. */
   private transformed(id: string, result: GizmoResult) {
     const view = this.session!.read()
+    /* A part hanging from a joint: the drag edits the joint -- its value, or where it sits (ADR-0093). */
+    const asset = JSON.parse(this.session!.source()) as V3Asset
+    const drawn = view.geometry.find(g => g.id === id) as unknown as V3RenderPart | undefined
+    const drag = drawn ? jointDragOf(asset, ownerOf(id), drawn, result, this.currentInputs()) : null
+    if (drag) {
+      if (drag.kind === 'value') this.run(() => this.session!.apply([{ kind: 'set-state', input: drag.input, unit: drag.unit, value: drag.value }]))
+      else if (drag.kind === 'joint') this.run(() => this.session!.command({ kind: 'set-joint', joint: drag.joint }))
+      else {
+        this.error = i18next.t(`figure.text.gizmo-joint-${drag.reason}`, { joint: drag.joint, leader: drag.leader ?? '', axis: drag.axis ?? '' })
+        this.requestUpdate()
+      }
+      return
+    }
     const sizes = Object.fromEntries(view.fields.map(field => [field.id, field.value as number]))
-    const changes = gizmoChanges(id, this.reachOf(id), result, sizes)
+    /*
+      A part a joint places, scaled: only its measures change. The shift of its centre that an anchored scale makes is
+      the joint's to give -- the face on the joint stays there by itself (user, 2026-09-25: 「'R'모드에서 크기가 변하지 않는다」;
+      the shift had been taken for a move of the joint, and the size was dropped).
+    */
+    const jointed = !!asset.joints?.some(j => j.body1.part === ownerOf(id))
+    const changes = gizmoChanges(id, this.reachOf(id), jointed && result.scale ? { scale: result.scale } : result, sizes)
     if (changes.length) {
       this.run(() => this.session!.apply(changes))
       return
     }
+    if (jointed && result.scale) {
+      /* Only measures that follow another were pulled: the relation says their size, and it is not broken here. */
+      const axes = (['x', 'y', 'z'] as const).filter((_, i) => Math.abs(result.scale![i]! - 1) > 1e-4)
+      this.error = i18next.t('figure.text.gizmo-size-follows', { part: partLabelOf(id), axis: axes.join(', ').toUpperCase() })
+      return this.requestUpdate()
+    }
     /*
       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
@@ -424,14 +491,19 @@ export class FigureV3Editor extends LitElement {
     */
     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()
+    /* A size worked out from the figure's: the drag's factor beside its rule, so it still follows (V2 scaled any part). */
+    const grow: Partial<Record<'x' | 'y' | 'z', number>> = {}
+    if (result.scale) (['x', 'y', 'z'] as const).forEach((axis, i) => Math.abs(result.scale![i]! - 1) > 1e-6 && (grow[axis] = Math.round(result.scale![i]! * 1e6) / 1e6))
+    if (!Object.keys(by).length && !Object.keys(turn).length && !Object.keys(grow).length) return this.requestUpdate()
     try {
-      this.session!.command({ kind: 'nudge-part', part: id, ...(Object.keys(by).length ? { by } : {}), ...(Object.keys(turn).length ? { turn } : {}) })
+      this.session!.command({
+        kind: 'nudge-part',
+        part: id,
+        ...(Object.keys(by).length ? { by } : {}),
+        ...(Object.keys(turn).length ? { turn } : {}),
+        ...(Object.keys(grow).length ? { grow } : {})
+      })
       this.error = ''
       this.changed()
     } catch (error) {
@@ -593,9 +665,7 @@ export class FigureV3Editor extends LitElement {
           ? i18next.t('figure.text.follow-would-loop')
           : code === 'FASTEN_CYCLE' || code === 'ATTACH_CYCLE'
             ? i18next.t('figure.text.fasten-would-loop')
-            : error instanceof Error
-              ? error.message
-              : String(error)
+            : sizeRangeRefusalOf(error, (key, params) => i18next.t(key, params)) ?? (error instanceof Error ? error.message : String(error))
     }
   }
   private changeField(field: { id: string; unit: V3InputChange['unit']; role?: string }, event: Event) {
@@ -785,6 +855,11 @@ export class FigureV3Editor extends LitElement {
             })
           : i18next.t(fits ? 'figure.text.repeat-fits-length' : 'figure.text.repeat-fixed-count')}
       </p>
+      ${asset.joints?.some(j => j.body1.part === this.selected && j.repeat)
+        ? html`<button act ?disabled=${unavailable} @click=${() => this.run(() => this.session!.command({ kind: 'remove-repeat', part: this.selected }))}>
+            <md-icon>close</md-icon>${i18next.t('figure.button.remove-repeat')}
+          </button>`
+        : nothing}
     </section>`
   }
   /**

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
 }