@things-factory/figure-ui 10.1.115 → 10.1.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-ui",
-  "version": "10.1.115",
+  "version": "10.1.117",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -27,8 +27,8 @@
     "clean": "npm run clean:server && npm run clean:client"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.2.15",
-    "@hatiolab/things-scene": "^10.1.69",
+    "@hatiolab/figure-model": "^0.3.3",
+    "@hatiolab/things-scene": "^10.1.72",
     "@material/web": "^2.0.0",
     "@operato/data-grist": "^10.0.0",
     "@operato/graphql": "^10.0.0",
@@ -40,9 +40,9 @@
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.0.0",
-    "@things-factory/ai-assistant": "^10.1.114",
-    "@things-factory/figure-service": "^10.1.115",
+    "@things-factory/ai-assistant": "^10.1.116",
+    "@things-factory/figure-service": "^10.1.117",
     "three": "^0.185.1"
   },
-  "gitHead": "3d1f480028b680a6da3d0ae6a73c3121d644b64a"
+  "gitHead": "cab2426c1c6e63b53a0a2087eef28c9c55df71dd"
 }

package/test/browser/detail-page.js

@@ -0,0 +1,34 @@
+/* Isolated product detail: fixtures are in memory, never saved to the running app. */
+import 'figure-ui-client/viewparts/figure-detail-dock.js'
+import { i18next } from '@operato/i18n'
+import { addFigureBox, createFigureAsset, editFigurePart, applyFigureAuthoring, serializeFigureAsset } from '@hatiolab/figure-model'
+
+async function start() {
+  i18next.addResourceBundle('ko', 'translations', await fetch('/ko.json').then(r => r.json()), true, true)
+  await i18next.changeLanguage('ko')
+  let asset = addFigureBox(createFigureAsset('클립 시험'), { id: 'block', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  asset = applyFigureAuthoring(asset, { kind: 'set-joint', joint: {
+    id: 'block', type: 'prismatic', body0: { plane: 'mounting-plane' }, body1: { part: 'block', face: 'bottom' }, axis: 'X', lowerLimit: 0, upperLimit: 200, state: { id: 'shift', start: 0 }
+  } })
+  asset = editFigurePart(asset, { kind: 'set-driver', state: 'shift', clip: 'cycle', duration: 4, keys: [{ seconds: 0, value: 0 }, { seconds: 2, value: 200 }, { seconds: 4, value: 0 }] })
+  const source = serializeFigureAsset(asset)
+  const dock = document.createElement('figure-detail-dock')
+  let fail = true
+  dock.load = async id => {
+    if (id === 'retry' && fail) { fail = false; throw Error('test connection failure') }
+    if (id === 'slow') await new Promise(done => setTimeout(done, 1200))
+    return { saved: { id, name: id === 'slow' ? '늦은 이전 모델' : '클립 시험', type: 'DETAIL_TEST', state: 'draft', source }, released: id === 'invalid' ? { version: 1, source: 'broken json' } : undefined }
+  }
+  const controls = document.createElement('nav')
+  for (const [label, id] of [['클립 모델 열기','motion'],['연결 오류 시험','retry'],['깨진 발행판 시험','invalid'],['느린 모델 열기','slow']]) {
+    const button = document.createElement('button'); button.textContent = label
+    button.onclick = () => void dock.show(id); controls.append(button)
+  }
+  document.body.append(controls,dock)
+  await dock.show('motion')
+  const original = document.createElement('output'); original.setAttribute('aria-label','원본 보존')
+  const check = document.createElement('button'); check.textContent='원본 확인'
+  check.onclick=()=>original.textContent=serializeFigureAsset(asset)===source?'원본 그대로':'원본 변경됨'
+  controls.append(check,original)
+}
+start()

package/test/browser/serve-detail.mjs

@@ -0,0 +1,10 @@
+import { createServer } from 'node:http'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPage } from './build.mjs'
+const here=dirname(fileURLToPath(import.meta.url))
+const bundle=await buildPage('detail-page.js')
+const html=`<!doctype html><html><head><meta charset="utf-8"><title>Figure 상세 검증</title><link rel="stylesheet" href="/theme.css"><style>body{margin:0;font-family:sans-serif;display:flex;height:100vh}nav{flex:1;padding:24px;display:flex;flex-direction:column;gap:12px}nav button{padding:12px}figure-detail-dock{position:static!important;height:100%!important}output{display:block}</style></head><body><script type="module" src="/page.js"></script></body></html>`
+const routes={ '/page.js':[bundle,'text/javascript'], '/ko.json':[resolve(here,'../../translations/ko.json'),'application/json'], '/theme.css':[resolve(here,'../../client/harness-theme/light.css'),'text/css'] }
+createServer((req,res)=>{const match=routes[req.url];res.writeHead(200,{'Content-Type':match?.[1]??'text/html; charset=utf-8'});res.end(match?readFileSync(match[0]):html)}).listen(3394,'127.0.0.1',()=>console.log('Detail fixture: http://localhost:3394'))

package/test/command-preview.test.ts

@@ -104,7 +104,7 @@ test('the details fold, and what they hold that is not the default stays said --
 /* ADR-0097 §5.5 (Q2): the list stays flat; a part says what it is fastened to, beside its name. */
 test('the part list names what each part is fastened to, without reordering or nesting it', () => {
   const editor = read('../client/modeller/editor.ts')
-  assert.ok(editor.includes("'plane' in j.body0 ? i18next.t('figure.label.mounting-plane') : `${partLabelOf(j.body0.part)} · ${i18next.t(`figure.label.face-${j.body0.face}`)}`"))
+  assert.ok(editor.includes("'plane' in j.body0 ? i18next.t('figure.label.mounting-plane') : `${partLabelOf(j.body0.part)} · ${i18next.t(endPlaceKeyOf(j.body0))}`"))
   assert.ok(editor.includes('...(fastened.has(id) ? { fastenedTo: fastened.get(id)! } : {})'))
   const parts = read('../client/modeller/figure-parts.ts')
   assert.ok(parts.includes('<small fastened-to title=${i18next.t(\'figure.label.fastened-to\')}>${part.fastenedTo}</small>'))
@@ -122,7 +122,7 @@ test('detaching says what it would do: stays, what stays fastened to it, the cli
   /* Staying where it is is as expected: nothing is said then (user 2026-10-01); a move, a child kept, a clip lost are. */
   assert.ok(editor.includes(': /* It stays where it is: as expected, so nothing is said (user 2026-10-01). */ []'), 'nothing said when it stays')
   const links = read('../client/modeller/figure-links.ts')
-  assert.equal(links.match(/\$\{this\.renderDetachWords\(\)\}/g)?.length, 2, 'beside both buttons that detach')
+  assert.equal(links.match(/\$\{this\.renderDetachWords\(\)\}/g)?.length, 3, 'beside every button that detaches (a part at an origin has its own)')
   for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
     const t = JSON.parse(read(`../translations/${lang}.json`))
     for (const key of ['detach-moves', 'detach-keeps-children', 'detach-clips', 'detach-refused']) assert.ok(t[`figure.text.${key}`], `${lang} ${key}`)

package/test/detail-motion.test.ts

@@ -0,0 +1,26 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { addFigureBox, createFigureAsset, editFigurePart, serializeFigureAsset } from '@hatiolab/figure-model'
+import { moving } from './joints.ts'
+import { clipForControl, parametersForClip } from '../client/viewparts/detail-motion.ts'
+
+function machine() {
+  let asset = addFigureBox(createFigureAsset('Motion probe'), { id: 'block', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  asset = moving(asset, 'block', { kind: 'slide', axis: 'x', id: 'shift', min: 0, max: 200, start: 0 })
+  return editFigurePart(asset, { kind: 'set-driver', state: 'shift', clip: 'cycle', duration: 4, keys: [{ seconds: 0, value: 0 }, { seconds: 2, value: 200 }, { seconds: 4, value: 0 }] })
+}
+
+test('playing a clip releases manual values that would mask its drivers, retaining unrelated controls and the source', () => {
+  const asset = machine()
+  const source = serializeFigureAsset(asset)
+  const values = { shift: 75, other: 42 }
+  assert.deepEqual(parametersForClip(asset, values, 'cycle'), { other: 42 })
+  assert.deepEqual(values, { shift: 75, other: 42 })
+  assert.equal(serializeFigureAsset(asset), source)
+  assert.equal(clipForControl(asset, 'shift'), 'cycle')
+  assert.equal(clipForControl(asset, 'other'), undefined)
+})
+
+test('choosing a different clip cannot clear another clip’s manual control', () => {
+  assert.deepEqual(parametersForClip(machine(), { shift: 75 }, 'other'), { shift: 75 })
+})

package/test/joint-frames.test.ts

@@ -0,0 +1,293 @@
+/*
+ * **관절 틀 (ADR-0107 결정 1·4) 을 화면이 읽고 그대로 돌려 쓴다** — 어느 방향이든 되는 축, 부품 기준점에 놓인 관절 끝,
+ * `origin.pivot` · `offset` · `rotate`. 움직임 폼 · 붙이기 폼 · 기즈모 끌기 · 움직임 없애기가 이 값들을 바꾸지 않고, 저장하고
+ * 다시 열어도 그대로다. 그 틀이 없는 커널(0.3.2)에서는 옛 모양만 같은 길로 본다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { addFigureBox, applyFigureAuthoring, compileFigureAsset, createFigureAsset, parseFigureAsset, serializeFigureAsset } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureAuthoringAction, FigureJoint } from '@hatiolab/figure-model'
+
+import { jointAxisUnit, jointAxisWord } from '../client/modeller/joint-axis.ts'
+import { alignOf, endPlaceKeyOf, fasteningOf, fixedJointOf, motionFormOf, motionFormRefusalOf, motionJoint, motionOf, rowAxesOf, rowBlockOf } from '../client/modeller/links.ts'
+import { jointDragOf } from '../client/modeller/joint-drag.ts'
+import { jointFanOf } from '../client/modeller/joint-fan.ts'
+
+type Dynamic = any
+const set = (asset: FigureAsset, joint: Dynamic) => applyFigureAuthoring(asset, { kind: 'set-joint', joint } as FigureAuthoringAction)
+const box = (asset: FigureAsset, id: string, x: number, y: number, z: number, at = 0) => addFigureBox(asset, { id, size: { x, y, z }, position: { x: 0, y: at, z: 0 } })
+const drawn = (asset: FigureAsset, id: string, state: Record<string, number> = {}) =>
+  compileFigureAsset(asset).evaluate(state).geometry.find(g => g.id === id) as never as { id: string; pose: { t: number[]; r: number[][] } }
+
+/** Whether this kernel knows the joint frames: an axis that is a vector is refused by one that does not. */
+const FRAMES = (() => {
+  try {
+    let a = box(createFigureAsset('probe'), 'p', 10, 10, 10, 5)
+    a = set(a, { id: 'p', type: 'revolute', body0: { plane: 'mounting-plane' }, body1: { part: 'p', face: 'bottom' }, axis: { x: 0, y: 1, z: 0 } })
+    return !!a.joints?.some(j => typeof j.axis === 'object')
+  } catch {
+    return false
+  }
+})()
+const framesOnly = { skip: FRAMES ? false : 'the kernel has no ADR-0107 joint frames' }
+
+const SUMMED = { sum: [{ from: { of: 'part', part: 'link', axis: 'y' }, times: 0.5 }], plus: 10 }
+
+/**
+ * A base on the floor; a link turning on its top about (1, 1, 0), by the middle of its bottom, turned and moved; a tool at
+ * the link's origin, its frame moved by a summed offset and turned; a cap at the tool's origin by its centre, held.
+ */
+function framed(): FigureAsset {
+  let a = box(createFigureAsset('Frames'), 'base', 300, 100, 300, 50)
+  a = box(a, 'link', 100, 400, 100, 300)
+  a = box(a, 'tool', 60, 120, 40)
+  a = box(a, 'cap', 20, 20, 20)
+  a = set(a, { id: 'base', type: 'fixed', body0: { plane: 'mounting-plane' }, body1: { part: 'base', face: 'bottom' } })
+  a = set(a, { id: 'link', type: 'revolute', body0: { part: 'base', face: 'top' }, body1: { part: 'link', face: 'bottom' }, origin: { pivot: 'child-face', offset: { x: 20 }, rotate: { x: 10 } }, axis: { x: 1, y: 1, z: 0 }, lowerLimit: -90, upperLimit: 90 })
+  a = set(a, { id: 'tool', type: 'revolute', body0: { part: 'link', at: 'origin' }, body1: { part: 'tool', at: 'origin' }, origin: { offset: { x: 120, y: SUMMED, z: -30 }, rotate: { x: 15, y: -30, z: 60 } }, axis: 'Z', lowerLimit: -45, upperLimit: 45 })
+  return set(a, { id: 'cap', type: 'fixed', body0: { part: 'tool', at: 'origin' }, body1: { part: 'cap', face: 'centre' }, origin: { offset: { y: 40 } } })
+}
+
+/** The old shapes only: a token axis, face ends, a gap and an edge. */
+function plain(): FigureAsset {
+  let a = box(createFigureAsset('Plain'), 'base', 300, 100, 300, 50)
+  a = box(a, 'link', 100, 400, 100, 300)
+  a = set(a, { id: 'base', type: 'fixed', body0: { plane: 'mounting-plane' }, body1: { part: 'base', face: 'bottom' } })
+  return set(a, { id: 'link', type: 'revolute', body0: { part: 'base', face: 'top' }, body1: { part: 'link', face: 'bottom' }, origin: { gap: 5, align: { x: 'min' } }, axis: 'Y', lowerLimit: -90, upperLimit: 90 })
+}
+
+const reopen = (asset: FigureAsset) => parseFigureAsset(serializeFigureAsset(asset) as unknown as string)
+const jointOf = (asset: FigureAsset, id: string) => asset.joints!.find(j => j.id === id)! as Dynamic
+/** What the frames say of a joint: what no form path may change. */
+const frameOf = (j: Dynamic, keepType = true) => ({
+  ...(keepType ? { type: j.type, axis: j.axis } : {}),
+  body0: j.body0,
+  body1: j.body1,
+  pivot: j.origin?.pivot,
+  offset: j.origin?.offset,
+  rotate: j.origin?.rotate
+})
+
+/** The fastening form's 붙이기, as figure-links builds it from what `fasteningOf` reads; nothing where it writes none. */
+function fasteningSave(asset: FigureAsset, part: string): FigureAuthoringAction | null {
+  const f = fasteningOf(asset, part) as Dynamic
+  if (!f || f.atOrigin) return null
+  const aim = f.toPlane ? ('plane' as const) : { part: f.target, face: f.targetFace }
+  const align = alignOf(asset, part, aim, f.align, f.alignMm, !!f.twist, f.alignInput)
+  return {
+    kind: 'attach',
+    part,
+    face: f.face,
+    to: f.toPlane ? { plane: 'mounting-plane' } : { part: f.target, face: f.targetFace },
+    ...(f.toPlane ? {} : { facing: f.facing }),
+    ...(f.gap ? { gap: f.gap } : {}),
+    twist: f.twist,
+    ...(align ? { align } : {}),
+    replace: true
+  } as FigureAuthoringAction
+}
+
+/** Every form path that writes a joint, each applied, saved and opened again. */
+function roundTrips(asset: FigureAsset, id: string) {
+  const j = jointOf(asset, id)
+  const part = j.body1.part
+  const out: Record<string, FigureJoint> = {}
+  if (j.type !== 'fixed') out.motion = jointOf(reopen(set(asset, motionJoint(j, motionFormOf(j), part))), id)
+  const fasten = fasteningSave(asset, part)
+  if (fasten) out.fastening = jointOf(reopen(applyFigureAuthoring(asset, fasten)), id)
+  out.fixed = jointOf(reopen(set(asset, fixedJointOf(j))), id)
+  const at = drawn(asset, part)
+  /* 30 along Z: the figure's, or at an origin the parent's own Z, as the offset is measured. */
+  const z = 'at' in j.body0 ? [0, 1, 2].map(i => drawn(asset, j.body0.part).pose.r[i]![2]!) : [0, 0, 1]
+  const by = z.map(v => v * 30)
+  const drag = jointDragOf(asset, part, at as never, { position: at.pose.t.map((v, i) => v + by[i]!) as [number, number, number] }, {})
+  assert.equal(drag?.kind, 'joint', `${id}: ${JSON.stringify(drag)}`)
+  const dragged = reopen(set(asset, (drag as { joint: FigureJoint }).joint))
+  out.drag = jointOf(dragged, id)
+  /* The part lands where it was dragged to. */
+  const landed = drawn(dragged, part).pose.t
+  assert.ok(Math.max(...by.map((d, i) => Math.abs(landed[i]! - at.pose.t[i]! - d))) < 0.2, `${id}: landed ${landed}, from ${at.pose.t}`)
+  return out
+}
+
+test('the axis reader: a token is its axis, a vector its unit vector, unrounded; said as written', () => {
+  assert.deepEqual(jointAxisUnit('Y'), [0, 1, 0])
+  assert.deepEqual(jointAxisUnit('z'), [0, 0, 1])
+  assert.deepEqual(jointAxisUnit({ x: 0, y: 3, z: 4 }), [0, 0.6, 0.8])
+  const tilted = jointAxisUnit({ x: 1, y: 1, z: 0 })!
+  assert.ok(Math.abs(tilted[0] - Math.SQRT1_2) < 1e-15 && tilted[0] === tilted[1] && tilted[2] === 0, `not rounded to a token: ${tilted}`)
+  assert.equal(jointAxisUnit({ x: 0, y: 0, z: 0 }), undefined)
+  assert.equal(jointAxisUnit(undefined), undefined)
+  assert.equal(jointAxisWord('X'), 'X')
+  assert.equal(jointAxisWord({ x: 1, y: 1, z: 0 }), '(1, 1, 0)')
+})
+
+test('a follower is not a turn without end: it has no limits because its leader gives its range', () => {
+  let a = box(createFigureAsset('Pair'), 'a', 100, 100, 100, 50)
+  a = box(a, 'b', 50, 50, 50, 125)
+  a = set(a, { id: 'a', type: 'revolute', body0: { plane: 'mounting-plane' }, body1: { part: 'a', face: 'bottom' }, axis: 'Y', lowerLimit: -90, upperLimit: 90 })
+  a = set(a, { id: 'b', type: 'revolute', body0: { part: 'a', face: 'top' }, body1: { part: 'b', face: 'bottom' }, axis: 'Y', mimic: { joint: 'a', multiplier: -1 } })
+  assert.equal(motionOf(a, 'b')?.kind, 'turn')
+  assert.equal(motionFormOf(jointOf(a, 'b')).kind, 'turn')
+  assert.equal(motionOf(a, 'a')?.kind, 'turn')
+  const free = set(a, { id: 'a', type: 'revolute', body0: { plane: 'mounting-plane' }, body1: { part: 'a', face: 'bottom' }, axis: 'Y' })
+  assert.equal(motionOf(free, 'a')?.kind, 'continuous', 'a joint of its own without limits still turns without end')
+})
+
+test('a range need not hold 0; it needs its most above its least', () => {
+  const form = motionFormOf(jointOf(plain(), 'link'))
+  assert.equal(motionFormRefusalOf({ ...form, min: 10, max: 90 }, ''), undefined)
+  assert.equal(motionFormRefusalOf({ ...form, min: -90, max: -10 }, ''), undefined)
+  assert.equal(motionFormRefusalOf({ ...form, min: 90, max: 10 }, ''), 'range')
+  assert.equal(motionFormRefusalOf({ ...form, min: 10, max: 10 }, ''), 'range')
+  assert.equal(motionFormRefusalOf({ ...form, min: NaN, max: 10 }, ''), 'range')
+  assert.equal(motionFormRefusalOf({ ...form, multiplier: 0 }, 'other'), 'multiplier')
+  /* A new control takes it and starts at the nearest end. */
+  const still = set(plain(), fixedJointOf(jointOf(plain(), 'link')))
+  const fixed = jointOf(still, 'link')
+  const lifted = set(still, motionJoint(fixed, { ...motionFormOf(fixed), kind: 'turn', min: 10, max: 90 }, 'link'))
+  assert.equal(lifted.stateDefaults[jointOf(lifted, 'link').state.id], 10)
+  /* An existing control keeps its name and its stored value: a range that leaves that value out is the kernel's refusal (R1). */
+  const j = jointOf(plain(), 'link')
+  assert.throws(() => set(plain(), motionJoint(j, { ...motionFormOf(j), min: 10, max: 90 }, 'link')), /INPUT_RANGE/)
+})
+
+test('old shapes: every form path writes the joint back as it was, saved and reopened', () => {
+  const asset = plain()
+  const was = frameOf(jointOf(asset, 'link'))
+  const paths = roundTrips(asset, 'link')
+  assert.deepEqual(frameOf(paths.motion), was, 'motion form')
+  assert.deepEqual(frameOf(paths.fastening), was, 'fastening form')
+  assert.deepEqual(frameOf(paths.fixed, false), frameOf(was, false), 'remove motion')
+  assert.deepEqual(frameOf(paths.drag), was, 'drag')
+  assert.deepEqual((paths.drag.origin as Dynamic).align, { x: 'min', z: { mm: 30 } }, 'the edge kept')
+  assert.equal(paths.drag.origin?.gap, 5)
+})
+
+test('a vector axis: the form keeps it, the summary says it, saved and reopened it is the same vector', framesOnly, () => {
+  const asset = framed()
+  const form = motionFormOf(jointOf(asset, 'link'))
+  assert.deepEqual(form.axisVector, { x: 1, y: 1, z: 0 })
+  assert.deepEqual(motionOf(asset, 'link')?.vector, { x: 1, y: 1, z: 0 })
+  /* Changing the range leaves the axis alone. */
+  const saved = reopen(set(asset, motionJoint(jointOf(asset, 'link'), { ...form, min: -30, max: 60 }, 'link')))
+  assert.deepEqual(jointOf(saved, 'link').axis, { x: 1, y: 1, z: 0 })
+  assert.equal(jointOf(saved, 'link').upperLimit, 60)
+})
+
+test('frames: every form path keeps the vector axis, pivot, offset (summed too), rotate and origin ends, saved and reopened', framesOnly, () => {
+  const asset = framed()
+  for (const id of ['link', 'tool', 'cap']) {
+    const was = jointOf(asset, id)
+    const paths = roundTrips(asset, id)
+    if (paths.motion) assert.deepEqual(frameOf(paths.motion), frameOf(was), `${id}: motion form`)
+    if (paths.fastening) assert.deepEqual(frameOf(paths.fastening), frameOf(was), `${id}: fastening form`)
+    assert.deepEqual(frameOf(paths.fixed, false), frameOf(was, false), `${id}: remove motion`)
+    const dragged = frameOf(paths.drag)
+    if ('at' in was.body0) {
+      /* At an origin the drag moves the frame by its offset, in the parent's (turned) frame; the summed term stays. */
+      assert.deepEqual(dragged, { ...frameOf(was), offset: { ...was.origin.offset, z: (was.origin.offset.z ?? 0) + 30 } }, `${id}: drag`)
+    } else assert.deepEqual(dragged, frameOf(was), `${id}: drag`)
+  }
+  /* A summed offset term is not a number to add to: dragged across it, the drag is refused; along the others it stays. */
+  const tool = drawn(asset, 'tool')
+  const up = jointDragOf(asset, 'tool', tool as never, { position: [tool.pose.t[0]!, tool.pose.t[1]! + 30, tool.pose.t[2]!] }, {})
+  assert.deepEqual(up, { kind: 'refused', reason: 'origin-follows', joint: 'tool' })
+})
+
+test('placed by an origin: said as the origin, no row offered, and the fastening form writes nothing over it', framesOnly, () => {
+  const asset = framed()
+  assert.equal(endPlaceKeyOf(jointOf(asset, 'tool').body0), 'figure.label.joint-origin')
+  assert.equal(endPlaceKeyOf(jointOf(asset, 'link').body0), 'figure.label.face-top')
+  assert.equal((fasteningOf(asset, 'tool') as Dynamic).atOrigin, true)
+  assert.equal((fasteningOf(asset, 'cap') as Dynamic).atOrigin, true)
+  assert.equal((fasteningOf(asset, 'cap') as Dynamic).face, 'centre')
+  assert.equal((fasteningOf(asset, 'link') as Dynamic).atOrigin, undefined)
+  assert.equal(fasteningSave(asset, 'tool'), null)
+  assert.deepEqual(rowAxesOf(asset, 'cap'), [])
+  assert.equal(rowBlockOf(asset, 'cap'), 'at-origin')
+})
+
+test('a drag about a vector axis sets the value; off it, it is refused and the vector said', framesOnly, () => {
+  let a = box(createFigureAsset('Tilt'), 'post', 100, 200, 100, 100)
+  a = box(a, 'head', 60, 60, 60, 230)
+  a = set(a, { id: 'post', type: 'fixed', body0: { plane: 'mounting-plane' }, body1: { part: 'post', face: 'bottom' } })
+  a = set(a, { id: 'head', type: 'revolute', body0: { part: 'post', face: 'top' }, body1: { part: 'head', face: 'bottom' }, axis: { x: 0, y: 3, z: 4 }, lowerLimit: -90, upperLimit: 90 })
+  const at = drawn(a, 'head')
+  /* 30° about (0, 0.6, 0.8), as XYZ degrees. */
+  const q = [0, 0.6, 0.8].map(v => v * Math.sin(Math.PI / 12))
+  const w = Math.cos(Math.PI / 12)
+  const [x, y, z] = q as [number, number, number]
+  const rx = Math.atan2(2 * (w * x - y * z), 1 - 2 * (x * x + y * y))
+  const ry = Math.asin(Math.max(-1, Math.min(1, 2 * (w * y + x * z))))
+  const rz = Math.atan2(2 * (w * z - x * y), 1 - 2 * (y * y + z * z))
+  const deg = [rx, ry, rz].map(r => (r * 180) / Math.PI) as [number, number, number]
+  assert.deepEqual(jointDragOf(a, 'head', at as never, { rotation: deg }, {}), { kind: 'value', input: 'head', unit: 'deg', value: 30 })
+  assert.deepEqual(jointDragOf(a, 'head', at as never, { rotation: [40, 0, 0] }, {}), { kind: 'refused', reason: 'off-axis', joint: 'head', axis: '(0, 3, 4)' })
+  /* A slide along it: the distance along the vector. */
+  const slide = set(a, { ...jointOf(a, 'head'), type: 'prismatic', lowerLimit: -100, upperLimit: 100 })
+  const s = drawn(slide, 'head')
+  assert.deepEqual(jointDragOf(slide, 'head', s as never, { position: [s.pose.t[0]!, s.pose.t[1]! + 30, s.pose.t[2]! + 40] }, {}), { kind: 'value', input: 'head', unit: 'mm', value: 50 })
+})
+
+test('a rotated joint frame: a turn about its turned axis is its value, and a move is measured before the rotation', framesOnly, () => {
+  let a = box(createFigureAsset('Rotated'), 'post', 100, 200, 100, 100)
+  a = box(a, 'link', 60, 300, 60, 350)
+  a = set(a, { id: 'post', type: 'fixed', body0: { plane: 'mounting-plane' }, body1: { part: 'post', face: 'bottom' } })
+  a = set(a, { id: 'bend', type: 'revolute', body0: { part: 'post', face: 'top' }, body1: { part: 'link', face: 'bottom' }, origin: { rotate: { x: 90 } }, axis: 'Z', lowerLimit: -90, upperLimit: 90 })
+  /* Turned 90° about X, the frame's Z is the figure's -Y: 20° about -Y is 20 on the joint. */
+  const at = drawn(a, 'link', { bend: 10 })
+  const before = at.pose.r
+  const turnY = (deg: number) => {
+    const c = Math.cos((deg * Math.PI) / 180),
+      s = Math.sin((deg * Math.PI) / 180)
+    return [[c, 0, s], [0, 1, 0], [-s, 0, c]]
+  }
+  const r = turnY(-20).map(row => [0, 1, 2].map(j => row.reduce((sum, v, k) => sum + v * before[k]![j]!, 0)))
+  /* As XYZ Euler degrees. */
+  const ry = Math.asin(Math.max(-1, Math.min(1, r[0]![2]!)))
+  const rx = Math.atan2(-r[1]![2]!, r[2]![2]!)
+  const rz = Math.atan2(-r[0]![1]!, r[0]![0]!)
+  const drag = jointDragOf(a, 'link', at as never, { rotation: [rx, ry, rz].map(v => (v * 180) / Math.PI) as [number, number, number] }, { bend: 10 })
+  assert.deepEqual(drag, { kind: 'value', input: 'bend', unit: 'deg', value: 30 })
+  /* Held still, moved 30 along X: an offset across the post's top on X, not along the turned frame. */
+  const still = set(a, { ...jointOf(a, 'bend'), type: 'fixed', axis: undefined, lowerLimit: undefined, upperLimit: undefined })
+  const s = drawn(still, 'link')
+  const moved = jointDragOf(still, 'link', s as never, { position: [s.pose.t[0]!, s.pose.t[1]!, s.pose.t[2]! + 30] }, {}) as { joint: Dynamic }
+  assert.deepEqual(moved.joint.origin, { rotate: { x: 90 }, align: { z: { mm: 30 } } })
+  const up = jointDragOf(still, 'link', s as never, { position: [s.pose.t[0]!, s.pose.t[1]! + 25, s.pose.t[2]!] }, {}) as { joint: Dynamic }
+  assert.deepEqual(up.joint.origin, { rotate: { x: 90 }, gap: 25 })
+})
+
+test('a fan stands about a vector axis, as it does about the same token', framesOnly, () => {
+  let a = box(createFigureAsset('Fan'), 'base', 200, 100, 200, 50)
+  a = box(a, 'arm', 400, 50, 50, 125)
+  a = set(a, { id: 'base', type: 'fixed', body0: { plane: 'mounting-plane' }, body1: { part: 'base', face: 'bottom' } })
+  const arm = (axis: unknown) => set(a, { id: 'arm', type: 'revolute', body0: { part: 'base', face: 'top' }, body1: { part: 'arm', face: 'bottom' }, axis, lowerLimit: -45, upperLimit: 90 })
+  const token = jointFanOf(arm('Y'), 'arm') as never as { pose: { t: number[]; r: number[][] } }
+  const vector = jointFanOf(arm({ x: 0, y: 2, z: 0 }), 'arm') as never as { pose: { t: number[]; r: number[][] } }
+  assert.ok(token && vector, 'a fan for both')
+  const off = (p: number[][], q: number[][]) => Math.max(...p.flatMap((row, i) => row.map((v, j) => Math.abs(v - q[i]![j]!))))
+  assert.ok(off(token.pose.r, vector.pose.r) < 1e-9 && off([token.pose.t], [vector.pose.t]) < 1e-9)
+  const tilted = jointFanOf(arm({ x: 0, y: 3, z: 4 }), 'arm') as never as { pose: { r: number[][] } }
+  assert.ok(tilted, 'a tilted axis has a fan too')
+  /* The fan lies in its local X–Z: its local Y is the axis. */
+  const normal = [0, 1, 2].map(i => tilted.pose.r[i]![1]!)
+  assert.ok(Math.abs(Math.abs(normal[1]! * 0.6 + normal[2]! * 0.8) - 1) < 1e-9, `normal ${normal}`)
+})
+
+test('editing a motion keeps the control named after the joint when it has no state record', async () => {
+  const { motionFormOf, motionJoint } = await import('../client/modeller/links.ts')
+  const { applyFigureAuthoring, addFigureBox, createFigureAsset } = await import('@hatiolab/figure-model')
+  let a = createFigureAsset('Hinge')
+  a = addFigureBox(a, { id: 'base', size: { x: 200, y: 100, z: 200 }, position: { x: 0, y: 0, z: 0 } })
+  a = addFigureBox(a, { id: 'lid', size: { x: 200, y: 20, z: 200 }, position: { x: 0, y: 0, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { id: 'base', type: 'fixed', body0: { plane: 'mounting-plane' }, body1: { part: 'base', face: 'bottom' } } })
+  a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { id: 'lid', type: 'revolute', body0: { part: 'base', face: 'top' }, body1: { part: 'lid', face: 'bottom' }, axis: 'X', lowerLimit: -90, upperLimit: 90 } })
+  const lid = a.joints!.find(j => j.id === 'lid')!
+  const form = motionFormOf(lid)
+  assert.equal(form.id, 'lid', 'the form starts from the input the joint is driven by')
+  const edited = applyFigureAuthoring(a, { kind: 'set-joint', joint: motionJoint(lid, { ...form, max: 80 }, 'lid') })
+  assert.deepEqual(edited.document.model.inputs.filter(i => i.role === 'state').map(i => i.id), ['lid'], 'the control keeps its name after the edit')
+})

package/test/links.test.ts

@@ -371,7 +371,7 @@ test('따라 움직이는 관절 — 같은 방식으로 움직이고 제 조작
   assert.equal(x('left', 40) - x('left', 0), 40)
   assert.equal(x('right', 40) - x('right', 0), -40, '오른손은 거울로 따라 닫힌다')
   const { motionOf } = await import('../client/modeller/links.ts')
-  assert.deepEqual(motionOf(asset, 'right')?.follows, { joint: 'left', multiplier: -1 }, '화면은 무엇을 따르는지 읽는다')
+  assert.deepEqual(motionOf(asset, 'right')?.follows, { sum: [{ joint: 'left', multiplier: -1 }], offset: 0 }, '화면은 무엇을 따르는지 읽는다')
 })
 
 test('면은 도형이 정한다 — 문틀(portal)은 바깥 여섯에 개구부 셋, 공은 없음, 원뿔대는 위아래뿐 (2026-09-25)', async () => {
@@ -661,3 +661,22 @@ test('붙이기 칸은 부품 제 붙임으로 열린다 — 가운데로 붙은
   assert.ok(panel.includes('fasteningOf(this.asset, this.partId)'), '부품을 고르면 제 붙임으로 연다')
   assert.ok(panel.includes("...(f.toPlane ? [] : (['centre'] as const))"), '내 면에 가운데가 있다')
 })
+
+test('a follower of several leaders and a stroke that is a sum of lengths are written back unchanged by the motion form (ADR-0107)', async () => {
+  const { motionFormOf, motionJoint, motionOf } = await import('../client/modeller/links.ts')
+  const { palletizerRobotFigure } = await import('@hatiolab/figure-model')
+  const { asset } = palletizerRobotFigure()
+  const wrist = asset.joints!.find(j => j.id === 'wrist')!
+  const form = motionFormOf(wrist)
+  assert.equal(form.follow, '', 'no single leader to pick')
+  assert.deepEqual(form.followSum, [{ joint: 'j2', multiplier: -1 }, { joint: 'j3', multiplier: -1 }])
+  const saved = motionJoint(wrist, { ...form, axis: form.axis }, 'wrist')
+  assert.deepEqual(saved.mimic, { sum: [{ joint: 'j2', multiplier: -1 }, { joint: 'j3', multiplier: -1 }] }, 'saving the form keeps the follower a follower')
+  assert.equal(saved.state, undefined, 'and gives it no control of its own')
+  assert.deepEqual(motionOf(asset, 'wrist')?.follows, { sum: [{ joint: 'j2', multiplier: -1 }, { joint: 'j3', multiplier: -1 }], offset: 0 })
+
+  const reach = { ...wrist, id: 'reach', type: 'prismatic' as const, mimic: undefined, axis: 'X' as const, travel: { sum: [{ from: { of: 'part' as const, part: 'base', axis: 'x' as const } }, { from: { of: 'part' as const, part: 'turret', axis: 'x' as const }, times: 0.5 }] } }
+  const slide = motionFormOf(reach)
+  assert.equal(slide.travel, '')
+  assert.deepEqual(motionJoint(reach, slide, 'wrist').travel, reach.travel, 'saving keeps the summed stroke')
+})

package/test/modeller-route.test.ts

@@ -23,9 +23,11 @@ test('one modeller page at one address: the route and the shell table agree', ()
   assert.equal(config.match(/tagname: 'figure-modeller-page', page: 'figure-modeller'/g)?.length, 1)
 })
 
-test('the catalogue opens figures through the one path', () => {
+test('the catalogue opens details first; editing is an explicit action in the detail dock', () => {
   const list = read('../client/pages/figure-list-page.ts')
-  assert.match(list, /navigate\(modellerPathOf\(figure\)\)/)
+  assert.match(list, /openFigureDetail\(record\)/)
+  const detail = read('../client/viewparts/figure-detail-dock.ts')
+  assert.match(detail, /navigate\(modellerPathOf\(saved\)\)/)
 })
 
 test('reloading or closing the tab with unsaved work asks first — the shell does not ask canDeactivate then (09-26)', () => {

package/test/verdict.test.ts

@@ -12,7 +12,7 @@ import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-import { addFigureBox, createFigureAsset, figureCostOf } from '@hatiolab/figure-model'
+import { addFigureBox, createFigureAsset, editFigurePart, figureCostOf } from '@hatiolab/figure-model'
 
 import { capacityFrom, SCENE_BUDGET } from '../client/modeller/scene-budget.ts'
 
@@ -25,6 +25,8 @@ test('개수는 목록 카드와 같은 셈이다 — 원가를 같은 capacityF
   let asset = createFigureAsset('Probe')
   asset = addFigureBox(asset, { id: 'a', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
   asset = addFigureBox(asset, { id: 'b', size: { x: 100, y: 100, z: 100 }, position: { x: 200, y: 50, z: 0 } })
+  // The kernel batches static parts with the same material. Use two colours to test two draw groups.
+  asset = editFigurePart(asset, { kind: 'set-material', target: 'b', material: { token: 'palette.accent' }, palette: { 'palette.accent': '#f28c28' } })
   const cost = figureCostOf(asset)
 
   assert.equal(cost.groups, 2, '전제: 그려지는 부품 둘이 묶음 둘')

package/translations/en.json

@@ -61,7 +61,6 @@
   "figure.text.fasten-before-moving": "fasten it to another part or the floor first; then it can move.",
   "figure.text.motion-summary": "{part} · against {against} · {kind} along {axis}",
   "figure.text.motion-ends-shown": "The canvas shows the poses at both ends of the range ({min} … {max} {unit}), translucent. What lies between is not checked.",
-  "figure.text.joint-range-holds-zero": "the range must hold 0, the rest pose.",
   "figure.text.gizmo-joint-mimic": "the {joint} joint follows {leader}. move {leader}.",
   "figure.text.gizmo-joint-fixed-turn": "the {joint} joint does not turn. give it a turn in the motion tab.",
   "figure.text.gizmo-joint-turned-slide": "the {joint} joint only slides. use the move handle.",
@@ -707,6 +706,7 @@
   "figure.text.row-count-spreads": "A set count is spread evenly over the length. Check the spacing in the preview.",
   "figure.text.row-blocked-unfastened": "Fasten {part} to another part to arrange it in a row along that part.",
   "figure.text.row-blocked-on-plane": "Fasten it to another part, not the mounting plane, to arrange it in a row along that part.",
+  "figure.text.row-blocked-at-origin": "It stands at another part's origin. Fasten it to a face of that part to arrange it in a row along it.",
   "figure.text.row-blocked-holds-parts": "Parts are fastened to this part, so it cannot be arranged in a row. Arrange it first; parts fastened after ride every copy.",
   "figure.button.go-fasten": "go to fastening",
   "figure.text.row-count-pitch": "{count} × {part} · along {axis} · pitch {pitch} mm (centre to centre)",
@@ -965,5 +965,23 @@
   "figure.label.face-mapping-choose": "Choose",
   "figure.label.face-mapping-detach": "Let go (stays where it is)",
   "figure.button.face-mapping-cancel": "Cancel",
-  "figure.button.face-mapping-apply": "Move and apply"
+  "figure.button.face-mapping-apply": "Move and apply",
+  "figure.title.detail": "Figure details",
+  "figure.text.detail-loading": "Loading model…",
+  "figure.button.detail-retry": "Retry",
+  "figure.text.detail-load-failed": "Could not load the model. Check your connection and access, then retry.",
+  "figure.text.detail-no-source": "No saved model is available.",
+  "figure.text.detail-invalid-source": "This model format could not be read. Open the editor to inspect it.",
+  "figure.label.detail-source": "Model to view",
+  "figure.label.detail-released": "Released version {version}",
+  "figure.label.detail-saved": "Saved model",
+  "figure.text.detail-unreleased": "Not released yet. Showing the saved draft.",
+  "figure.button.detail-edit": "Open editor",
+  "figure.label.detail-size": "Placement size",
+  "figure.button.detail-reset": "Reset size and pose",
+  "figure.text.detail-transient": "Try sizes and motion here. The saved model stays unchanged.",
+  "figure.text.detail-no-motion": "No motion is defined.",
+  "figure.text.detail-playing": "Playing",
+  "figure.label.detail-summary": "Drawing cost of the selected model",
+  "figure.text.detail-paused": "Paused"
 }

package/translations/ja.json

@@ -61,7 +61,6 @@
   "figure.text.fasten-before-moving": "先に他の部品か床に取り付けると、動きを付けられます。",
   "figure.text.motion-summary": "{part} · {against} 基準 · {axis} 軸 {kind}",
   "figure.text.motion-ends-shown": "キャンバスに範囲の両端({min} … {max} {unit})の姿勢を半透明で表示します。その間は確認しません。",
-  "figure.text.joint-range-holds-zero": "範囲に 0(基本姿勢)を含めてください。",
   "figure.text.gizmo-joint-mimic": "{joint} 関節は {leader} に従います。{leader} を動かしてください。",
   "figure.text.gizmo-joint-fixed-turn": "{joint} 関節は回りません。動きタブで回転を付けてください。",
   "figure.text.gizmo-joint-turned-slide": "{joint} 関節はスライドのみです。移動ハンドルを使ってください。",
@@ -707,6 +706,7 @@
   "figure.text.row-count-spreads": "個数を決めると長さの中で均等に広がります。間隔はプレビューで確認してください。",
   "figure.text.row-blocked-unfastened": "{part} を別の部品に取り付けると、その部品に沿って列に並べられます。",
   "figure.text.row-blocked-on-plane": "取付平面ではなく別の部品に取り付けると、その部品に沿って列に並べられます。",
+  "figure.text.row-blocked-at-origin": "別の部品の基準点に置かれているため、列に並べられません。その部品の面に取り付けると列に並べられます。",
   "figure.text.row-blocked-holds-parts": "この部品に取り付いた部品があるため列に並べられません。先に列に並べてから取り付けると、コピーごとに付きます。",
   "figure.button.go-fasten": "取り付けへ",
   "figure.text.row-count-pitch": "{part} {count} 個 · {axis} 方向 · pitch {pitch} mm(中心間隔)",
@@ -965,5 +965,23 @@
   "figure.label.face-mapping-choose": "移動先",
   "figure.label.face-mapping-detach": "外しておく(今の位置のまま)",
   "figure.button.face-mapping-cancel": "やめる",
-  "figure.button.face-mapping-apply": "移して適用"
+  "figure.button.face-mapping-apply": "移して適用",
+  "figure.title.detail": "Figure の詳細",
+  "figure.text.detail-loading": "モデルを読み込み中…",
+  "figure.button.detail-retry": "再試行",
+  "figure.text.detail-load-failed": "モデルを読み込めませんでした。接続とアクセス権を確認して再試行してください。",
+  "figure.text.detail-no-source": "保存されたモデルがありません。",
+  "figure.text.detail-invalid-source": "このモデルの形式を読み取れません。編集画面で確認してください。",
+  "figure.label.detail-source": "表示するモデル",
+  "figure.label.detail-released": "公開版 {version}",
+  "figure.label.detail-saved": "保存版",
+  "figure.text.detail-unreleased": "まだ公開されていません。保存された下書きを表示します。",
+  "figure.button.detail-edit": "編集画面を開く",
+  "figure.label.detail-size": "配置サイズ",
+  "figure.button.detail-reset": "基準サイズと姿勢に戻す",
+  "figure.text.detail-transient": "サイズと動きはここでのみ試します。保存されたモデルは変更されません。",
+  "figure.text.detail-no-motion": "登録された動きがありません。",
+  "figure.text.detail-playing": "再生中",
+  "figure.label.detail-summary": "選択したモデルの描画コスト",
+  "figure.text.detail-paused": "一時停止"
 }

package/translations/ko.json

@@ -61,7 +61,6 @@
   "figure.text.fasten-before-moving": "먼저 다른 부품이나 바닥에 붙여야 움직임을 줄 수 있습니다.",
   "figure.text.motion-summary": "{part} · {against} 기준 · {axis}축 {kind}",
   "figure.text.motion-ends-shown": "캔버스에 범위 양 끝({min} … {max} {unit})의 자세를 반투명으로 보입니다. 그 사이는 확인하지 않습니다.",
-  "figure.text.joint-range-holds-zero": "범위에 0이 들어가야 합니다. 0이 기본 자세입니다.",
   "figure.text.gizmo-joint-mimic": "{joint} 관절은 {leader} 관절을 따라 움직입니다. {leader}을(를) 움직이세요.",
   "figure.text.gizmo-joint-fixed-turn": "{joint} 관절은 돌지 않습니다. 돌리려면 움직임 탭에서 회전을 주세요.",
   "figure.text.gizmo-joint-turned-slide": "{joint} 관절은 미끄러지기만 합니다. 이동 손잡이로 움직이세요.",
@@ -707,6 +706,7 @@
   "figure.text.row-count-spreads": "개수를 정하면 길이 안에 고르게 벌어집니다. 간격은 미리보기에서 확인하세요.",
   "figure.text.row-blocked-unfastened": "{part}을(를) 다른 부품에 붙이면 그 부품을 따라 줄로 배열할 수 있습니다.",
   "figure.text.row-blocked-on-plane": "장착 평면이 아니라 다른 부품에 붙여야 그 부품을 따라 줄로 배열할 수 있습니다.",
+  "figure.text.row-blocked-at-origin": "다른 부품의 기준점에 놓여 있어 줄로 배열할 수 없습니다. 그 부품의 면에 붙이면 줄로 배열할 수 있습니다.",
   "figure.text.row-blocked-holds-parts": "이 부품에 붙은 부품이 있어 줄로 배열할 수 없습니다. 먼저 줄로 배열한 뒤 붙이면 복사본마다 함께 붙습니다.",
   "figure.button.go-fasten": "붙이기로 가기",
   "figure.text.row-count-pitch": "{part} {count}개 · {axis} 방향 · pitch {pitch} mm (중심 간격)",
@@ -965,5 +965,23 @@
   "figure.label.face-mapping-choose": "옮길 곳",
   "figure.label.face-mapping-detach": "떼어 두기(지금 자리에 그대로)",
   "figure.button.face-mapping-cancel": "그만두기",
-  "figure.button.face-mapping-apply": "옮기고 적용"
+  "figure.button.face-mapping-apply": "옮기고 적용",
+  "figure.title.detail": "Figure 상세",
+  "figure.text.detail-loading": "모델을 불러오는 중…",
+  "figure.button.detail-retry": "다시 시도",
+  "figure.text.detail-load-failed": "모델을 불러오지 못했습니다. 연결과 접근 권한을 확인하고 다시 시도하세요.",
+  "figure.text.detail-no-source": "저장된 모델이 없습니다.",
+  "figure.text.detail-invalid-source": "이 모델의 형식을 읽을 수 없습니다. 편집 화면에서 확인하세요.",
+  "figure.label.detail-source": "보는 모델",
+  "figure.label.detail-released": "발행판 {version}",
+  "figure.label.detail-saved": "저장본",
+  "figure.text.detail-unreleased": "아직 발행되지 않았습니다. 저장된 초안을 보여줍니다.",
+  "figure.button.detail-edit": "편집 화면 열기",
+  "figure.label.detail-size": "배치 크기",
+  "figure.button.detail-reset": "기준 크기와 자세로",
+  "figure.text.detail-transient": "크기와 움직임은 여기서만 시험합니다. 저장된 모델은 바뀌지 않습니다.",
+  "figure.text.detail-no-motion": "등록된 움직임이 없습니다.",
+  "figure.text.detail-playing": "재생 중",
+  "figure.label.detail-summary": "선택한 모델의 그리기 비용",
+  "figure.text.detail-paused": "일시정지"
 }