@things-factory/figure-ui 10.1.46 → 10.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-ui",
-  "version": "10.1.46",
+  "version": "10.1.48",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -26,19 +26,19 @@
     "clean": "npm run clean:server && npm run clean:client"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.48",
-    "@hatiolab/things-scene": "^10.1.26",
+    "@hatiolab/figure-model": "^0.1.54",
+    "@hatiolab/things-scene": "^10.1.32",
     "@material/web": "^2.0.0",
     "@operato/data-grist": "^10.0.0",
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
-    "@operato/layout": "^10.0.0",
+    "@operato/layout": "^10.28.0",
     "@operato/p13n": "^10.0.0",
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.0.0",
-    "@things-factory/figure-service": "^10.1.46",
+    "@things-factory/figure-service": "^10.1.48",
     "three": "^0.185.1"
   },
-  "gitHead": "d3467cde550453f3348fed0ed6c79a12a6ba0db4"
+  "gitHead": "448b0d568a1816d25aa49f3b6233d8086d6011f9"
 }

package/test/v3-clips.test.ts

@@ -0,0 +1,70 @@
+/*
+ * **클립 — V2 의 애니메이션** (V3 동등표 ⑥, 2026-09-24).
+ *
+ * 조작값을 시간에 따라 움직이는 자리다. 읽는 값은 figure-model 편집을 실제로 적용한 자산에서 재고, 배선은 소스에서 본다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { addV3Box, applyV3Authoring, createV3Asset, editV3Part } from '@hatiolab/figure-model'
+import type { V3Asset } from '@hatiolab/figure-model'
+
+import { clipsOf, poseAt, trackEdit, undrivenOf, withKey, withoutKey } from '../client/modeller/v3-clips.ts'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+const machine = (): V3Asset => {
+  let asset = createV3Asset('Machine')
+  asset = addV3Box(asset, { id: 'block', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'add-motion', part: 'block', motion: { kind: 'slide', axis: 'x' }, state: { id: 'shift', unit: 'mm', min: 0, max: 60, start: 0 } })
+  asset = addV3Box(asset, { id: 'arm', size: { x: 40, y: 200, z: 40 }, position: { x: 0, y: 200, z: 0 } })
+  return applyV3Authoring(asset, { kind: 'add-motion', part: 'arm', motion: { kind: 'turn', axis: 'y' }, state: { id: 'spin', unit: 'deg', min: -180, max: 180, start: 0 } })
+}
+
+test('클립마다 길이와 트랙을, 트랙마다 키를 초로 읽는다', () => {
+  let asset = editV3Part(machine(), { kind: 'set-state-input', input: 'shift', label: '밀기' })
+  asset = editV3Part(asset, { kind: 'set-driver', state: 'shift', clip: 'cycle', duration: 4, keys: [{ seconds: 0, value: 0 }, { seconds: 2, value: 60 }, { seconds: 4, value: 0 }] })
+  assert.deepEqual(undrivenOf(asset), ['spin'], '재생하지 않는 조작값만 새 트랙이 된다')
+  const [clip] = clipsOf(asset)
+  assert.equal(clip!.name, 'cycle')
+  assert.equal(clip!.duration, 4)
+  assert.deepEqual(clip!.tracks.map(t => [t.state, t.label, t.unit, t.keys]), [['shift', '밀기', 'mm', [{ seconds: 0, value: 0 }, { seconds: 2, value: 60 }, { seconds: 4, value: 0 }]]])
+})
+
+test('막대를 옮기면 그 순간의 자세를 한 묶음으로 — 드라이버와 같은 값', () => {
+  const asset = editV3Part(machine(), { kind: 'set-driver', state: 'shift', clip: 'cycle', duration: 4, keys: [{ seconds: 0, value: 0 }, { seconds: 4, value: 60 }] })
+  assert.deepEqual(poseAt(asset, 'cycle', 1), [{ kind: 'set-state', input: 'shift', unit: 'mm', value: 15 }])
+  assert.deepEqual(poseAt(asset, 'nothing', 1), [])
+})
+
+test('키를 그 순간에 더하고 빼며, 쓰면 figure-model 이 받는다 — 양 끝은 남는다', () => {
+  let asset = editV3Part(machine(), { kind: 'set-driver', state: 'shift', clip: 'cycle', duration: 4, keys: [{ seconds: 0, value: 0 }, { seconds: 4, value: 60 }] })
+  const [clip] = clipsOf(asset)
+  const track = clip!.tracks[0]!
+  const keys = withKey(track.keys, { seconds: 2, value: 30 })
+  assert.deepEqual(keys.map(k => k.seconds), [0, 2, 4])
+  assert.deepEqual(withKey(keys, { seconds: 2, value: 45 }).map(k => k.value), [0, 45, 60], '같은 순간이면 바꾼다')
+  asset = editV3Part(asset, trackEdit(clip!, track, { keys }))
+  assert.equal(clipsOf(asset)[0]!.tracks[0]!.keys.length, 3)
+  assert.equal(withoutKey(track.keys, 1), null, '두 개뿐이면 뺄 수 없다')
+  assert.equal(withoutKey(keys, 0), null, '처음 키(0초)는 뺄 수 없다')
+  assert.deepEqual(withoutKey(keys, 1)!.map(k => k.seconds), [0, 4])
+})
+
+test('움직임 탭에 서고, 막대는 입력 한 묶음 · 나머지는 부품 편집으로 편집기에 닿는다', () => {
+  const editor = read('../client/modeller/v3-editor.ts')
+  const start = editor.indexOf('<figure-v3-clips')
+  const block = editor.slice(start, editor.indexOf('</figure-v3-clips>', start))
+  assert.ok(start >= 0)
+  assert.ok(block.includes('@v3-states=${(e: CustomEvent) => this.run(() => this.session!.apply(e.detail.changes))}'))
+  assert.ok(block.includes('@v3-part-edit=${(e: CustomEvent) => this.run(() => this.session!.edit(e.detail.edit))}'))
+  const clips = read('../client/modeller/figure-v3-clips.ts')
+  assert.ok(clips.includes("@change=${(e: Event) => this.scrub(clip, number(e))}"), '막대는 놓을 때 한 번')
+  const keys = [...clips.matchAll(/'(figure\.[a-z.-]*[a-z])'/g)].map(m => m[1])
+  for (const lang of ['ko', 'en', 'ja', 'zh', 'ms']) {
+    const table = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of keys) assert.ok(table[key], `${lang}: ${key}`)
+  }
+})

package/test/v3-controls.test.ts

@@ -0,0 +1,68 @@
+/*
+ * **조작값 — V2 의 파라미터와 자세 도구** (V3 동등표 ⑥, 2026-09-24).
+ *
+ * 보드가 값을 바꿔 도형을 움직이는 자리다. 화면이 읽는 값을 명령을 실제로 적용한 자산에서 재고, 화면의 배선은
+ * 소스에서 확인한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { addV3Box, applyV3Authoring, createV3Asset, editV3Part } from '@hatiolab/figure-model'
+import type { V3Asset } from '@hatiolab/figure-model'
+
+import { controlsOf, poseAsDefault, poseDiffers } from '../client/modeller/v3-controls.ts'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+const slider = (): V3Asset => {
+  let asset = createV3Asset('Slider')
+  asset = addV3Box(asset, { id: 'block', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'add-motion', part: 'block', motion: { kind: 'slide', axis: 'x' }, state: { id: 'shift', unit: 'mm', min: 0, max: 60, start: 20 } })
+  asset = addV3Box(asset, { id: 'arm', size: { x: 40, y: 200, z: 40 }, position: { x: 0, y: 200, z: 0 } })
+  return applyV3Authoring(asset, { kind: 'add-motion', part: 'arm', motion: { kind: 'turn', axis: 'y' }, state: { id: 'spin', unit: 'deg', min: -90, max: 90, start: 0 } })
+}
+
+test('조작값마다 이름 · 단위 · 범위 · 지금 값 · 시작 값 · 이동 시간을 읽는다', () => {
+  let asset = slider()
+  asset = editV3Part(asset, { kind: 'set-state-input', input: 'shift', label: '밀기', sweep: 2 })
+  const [shift, spin] = controlsOf(asset, { shift: 45 })
+  assert.deepEqual(
+    { ...shift, step: undefined },
+    { id: 'shift', label: '밀기', named: true, unit: 'mm', min: 0, max: 60, value: 45, start: 20, sweep: 2, step: undefined }
+  )
+  assert.equal(shift!.step, 0.6, '길이는 범위의 백분의 일씩')
+  assert.equal(spin!.label, 'spin', '이름이 없으면 id')
+  assert.equal(spin!.named, false)
+  assert.equal(spin!.step, 1, '각도는 1도씩')
+  assert.equal(spin!.value, 0, '편집기 값이 없으면 시작 값')
+})
+
+test('지금 자세를 기본으로 — 보고 있는 자세가 시작 자세와 다를 때만, 한 번의 편집으로', () => {
+  const asset = slider()
+  assert.equal(poseDiffers(controlsOf(asset)), false)
+  const looking = controlsOf(asset, { shift: 50, spin: 30 })
+  assert.equal(poseDiffers(looking), true)
+  const kept = editV3Part(asset, poseAsDefault(looking))
+  assert.deepEqual([kept.stateDefaults['shift'], kept.stateDefaults['spin']], [50, 30])
+  assert.equal(poseDiffers(controlsOf(kept, { shift: 50, spin: 30 })), false)
+})
+
+test('편집기에 닿는다 — 값 바꾸기는 입력으로, 이름 · 범위 · 시간 · 기본 자세는 부품 편집으로', () => {
+  const editor = read('../client/modeller/v3-editor.ts')
+  const start = editor.indexOf('<figure-v3-controls')
+  const block = editor.slice(start, editor.indexOf('</figure-v3-controls>', start))
+  assert.ok(start >= 0)
+  assert.ok(block.includes("@v3-state=${(e: CustomEvent) => this.run(() => this.session!.apply([{ kind: 'set-state'"))
+  assert.ok(block.includes('@v3-part-edit=${(e: CustomEvent) => this.run(() => this.session!.edit(e.detail.edit))}'))
+  assert.ok(editor.includes("const design = view.fields.filter(i => i.role !== 'state')"), '조작값은 설계 값 칸에 두 번 나오지 않는다')
+
+  const controls = read('../client/modeller/figure-v3-controls.ts')
+  assert.ok(controls.includes("@change=${(e: Event) => this.try(c, number(e))}"), '슬라이더는 놓을 때 한 번 — 끄는 동안 기록이 쌓이지 않는다')
+  const keys = [...controls.matchAll(/'(figure\.[a-z.-]*[a-z])'/g)].map(m => m[1])
+  for (const lang of ['ko', 'en', 'ja', 'zh', 'ms']) {
+    const table = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of keys) assert.ok(table[key], `${lang}: ${key}`)
+  }
+})

package/test/v3-fields.test.ts

@@ -0,0 +1,71 @@
+/*
+ * **값 칸의 묶음 — V2 인스펙터처럼** (사용자 2026-09-24: 「적절한 그루핑이 없어서 가시성이 좋지 않다. 크기는 왜
+ * 한줄씩 차지하는가」). 위치 · 회전 · 크기는 X · Y · Z 세 칸 한 줄, 형상의 나머지 치수는 제 제목 아래 한 줄씩.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { groupFields, partLabelOf, repeatOf } from '../client/modeller/v3-fields.ts'
+
+const f = (id: string, value = 1, unit = 'mm') => ({ id, unit, value, role: 'design' })
+
+test('부품의 위치 · 회전 · 크기는 세 칸 한 줄씩, 나머지는 한 줄씩', () => {
+  const fields = [
+    f('arm.position.x'), f('arm.position.y'), f('arm.position.z'),
+    f('arm.rotation.x', 0, 'deg'), f('arm.rotation.y', 0, 'deg'), f('arm.rotation.z', 0, 'deg'),
+    f('arm.dimension.radius'), f('arm.dimension.length'),
+    f('other.position.x'), f('size.x')
+  ]
+  const { vectors, singles } = groupFields(fields, 'arm')
+  assert.deepEqual(vectors.map(g => g.kind === 'vector' && g.name), ['position', 'rotation'])
+  assert.deepEqual(singles.map(g => g.kind === 'single' && g.name), ['radius', 'length'], '다른 부품 · 도형의 값은 섞이지 않는다')
+})
+
+test('도형은 크기(size.x · y · z)가 세 칸 한 줄', () => {
+  const { vectors, singles } = groupFields([f('size.x'), f('size.y'), f('size.z'), f('opening'), f('arm.position.x')])
+  assert.deepEqual(vectors.map(g => g.kind === 'vector' && g.name), ['size'])
+  assert.deepEqual(singles.map(g => g.kind === 'single' && g.name), ['opening'])
+})
+
+test('오른쪽 칸은 한 벌의 규격 — 요소마다 제 제목 · 칸 · 단추 규칙을 두지 않는다', () => {
+  for (const file of ['v3-editor', 'figure-v3-properties', 'figure-v3-links', 'figure-v3-material', 'figure-v3-controls', 'figure-v3-clips', 'figure-v3-capability']) {
+    const source = readFileSync(fileURLToPath(new URL(`../client/modeller/${file}.ts`, import.meta.url)), 'utf8')
+    assert.ok(source.includes('SidePanelStyles'), `${file} 가 공용 규격을 쓴다`)
+    const styles = source.slice(source.indexOf('static styles'), source.indexOf('`]', source.indexOf('static styles')))
+    assert.doesNotMatch(styles, /\n    h3 \{|\n    button\[act\] \{|\n    div\[form\] \{/, `${file} 가 제 규칙을 다시 적는다`)
+  }
+})
+
+test('긴 설명은 제목 옆 「?」 로 연다 — 늘 펼쳐 두지 않는다 (V2)', () => {
+  for (const [file, key] of [
+    ['figure-v3-links', 'figure.text.motion-explained'],
+    ['figure-v3-links', 'figure.text.place-explained'],
+    ['figure-v3-links', 'figure.text.fastening-explained'],
+    ['figure-v3-clips', 'figure.text.clips-explained']
+  ]) {
+    const source = readFileSync(fileURLToPath(new URL(`../client/modeller/${file}.ts`, import.meta.url)), 'utf8')
+    assert.ok(source.includes(`this.help.button('${key}')`) && source.includes(`this.help.hint('${key}')`), `${file}: ${key}`)
+    assert.ok(!source.includes(`<p hint>\${i18next.t('${key}')}</p>`), `${file}: ${key} 가 늘 펼쳐져 있다`)
+  }
+})
+
+test('되풀이한 부품은 되풀이의 이름과 몇 번째인지로 읽는다 — 날 id 를 보이지 않는다', () => {
+  assert.equal(partLabelOf('["roller.repeat",0,"roller.value"]'), 'roller 1')
+  assert.equal(partLabelOf('["rack.repeat",1,"shelf.repeat",2,"shelf.value"]'), 'rack 2·3')
+  assert.equal(partLabelOf('deck'), 'deck', '보통 부품은 제 이름')
+  assert.equal(partLabelOf('[not json'), '[not json')
+  const parts = readFileSync(fileURLToPath(new URL('../client/modeller/figure-v3-parts.ts', import.meta.url)), 'utf8')
+  assert.ok(parts.includes('>${partLabelOf(part.id)}'), '목록이 이 이름으로 그린다')
+})
+
+test('되풀이한 부품의 속성 이름 칸도 사람의 이름이고, 몇 개 중 몇 번째인지 말한다 — 날 id 를 보이지 않는다', () => {
+  const geometry = Array.from({ length: 16 }, (_, i) => ({ id: JSON.stringify(['roller.repeat', i, 'roller.value']) })).concat([{ id: 'deck' }])
+  assert.deepEqual(repeatOf('["roller.repeat",14,"roller.value"]', geometry), { name: 'roller', count: 16, index: 15 })
+  assert.equal(repeatOf('deck', geometry), null)
+  const editor = readFileSync(fileURLToPath(new URL('../client/modeller/v3-editor.ts', import.meta.url)), 'utf8')
+  assert.ok(editor.includes('.value=${partLabelOf(this.selected)}'), '사용자 2026-09-24: 「부품 이름 ???」')
+  assert.ok(editor.includes('?disabled=${unavailable || !!repeatOf(this.selected, view.geometry)}'), '복사본에는 바꿀 제 이름이 없다')
+})
+

package/test/v3-gizmo.test.ts

@@ -81,12 +81,10 @@ test('끈 것은 세션의 한 걸음이다 — 한 번의 되돌리기로 돌
   assert.match(editor, /if \(changes\.length\) this\.run\(\(\) => this\.session!\.apply\(changes\)\)/)
 })
 
-test('캔버스 — W · E · R, 끄는 동안 궤도 조작을 멈추고, 놓는 순간은 고르기가 아니다', () => {
+test('캔버스 — 기즈모 · W E R · 스냅은 씬의 편집 모드가 한다, V2 처럼', () => {
   const canvas = read('../client/modeller/v3-canvas.ts')
-  assert.match(canvas, /\{ w: 'translate', e: 'rotate', r: 'scale' \}/)
-  assert.match(canvas, /this\.controls\.enabled = !on/)
-  assert.match(canvas, /if \(this\.justDragged \|\| this\.transform\?\.dragging\) return/)
-  assert.match(canvas, /setFromQuaternion\(this\.proxy\.quaternion, 'XYZ'\)/)
+  assert.match(canvas, /mode: 1\n/)
+  assert.doesNotMatch(canvas, /TransformControls|OrbitControls/)
 })
 
 test('기즈모의 말은 다섯 말 모두에 있다', () => {

package/test/v3-joint-fan.test.ts

@@ -0,0 +1,210 @@
+/*
+ * **고른 부품이 어디서 얼마나 도는지** (사용자 2026-09-24: 「로봇암은 편집기에서 원래는 부품을 선택했을 때, 가변 각도가
+ * 표현이 되었었는데」). V2 는 관절의 가동 범위를 부채꼴로 저작면에 그렸다. 부채꼴의 두 끝이 제어값의 최솟값과 최댓값에서
+ * 부품이 실제로 가는 쪽을 가리키는지를 — 평가해서 — 본다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { addV3Box, applyV3Authoring, compileV3Asset, convertV2ToV3, createV3Asset } from '@hatiolab/figure-model'
+import type { V3Asset } from '@hatiolab/figure-model'
+
+import { JOINT_FAN, jointFanOf } from '../client/modeller/v3-joint-fan.ts'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+function arm(): V3Asset {
+  let asset = createV3Asset('Probe')
+  asset = addV3Box(asset, { id: 'base', size: { x: 200, y: 100, z: 200 }, position: { x: 0, y: 50, z: 0 } })
+  asset = addV3Box(asset, { id: 'arm', size: { x: 400, y: 50, z: 50 }, position: { x: 200, y: 125, z: 0 } })
+  return applyV3Authoring(asset, { kind: 'add-motion', part: 'arm', motion: { kind: 'turn', axis: 'y' }, state: { id: 'arm.turn', unit: 'deg', min: -45, max: 90 } })
+}
+
+/** The fan's profile point in the figure's frame. The polygon lies in its local X–Z: profile (x, y) is local (x, 0, y). */
+const world = (fan: { pose: { t: number[]; r: number[][] } }, p: { x: number; y: number }) =>
+  [0, 1, 2].map(i => fan.pose.t[i]! + fan.pose.r[i]![0]! * p.x + fan.pose.r[i]![2]! * p.y)
+
+const direction = (v: number[]) => {
+  const l = Math.hypot(v[0]!, v[2]!)
+  return [v[0]! / l, v[2]! / l]
+}
+
+test('a part that turns gets a fan from the lowest value to the highest, where the part really goes', () => {
+  const asset = arm()
+  const fan = jointFanOf(asset, 'arm') as unknown as { id: string; shape: { provider: string; profile: { x: number; y: number }[] }; pose: { t: number[]; r: number[][] } }
+  assert.ok(fan)
+  assert.equal(fan.id, JOINT_FAN)
+  assert.equal(fan.shape.provider, 'polygon')
+  const profile = fan.shape.profile
+  assert.deepEqual(profile[0], { x: 0, y: 0 }, 'not a full turn: the fan starts at the pivot')
+
+  const armAt = (deg: number) => {
+    const body = compileV3Asset({ ...asset, stateDefaults: { ...asset.stateDefaults, 'arm.turn': deg } }).evaluate().geometry.find(g => g.id === 'arm')!
+    return direction((body as unknown as { pose: { t: number[] } }).pose.t)
+  }
+  const first = direction(world(fan, profile[1]!))
+  const last = direction(world(fan, profile[profile.length - 1]!))
+  for (const [got, want] of [
+    [first, armAt(-45)],
+    [last, armAt(90)]
+  ] as const) {
+    assert.ok(Math.abs(got[0]! - want[0]!) < 1e-6 && Math.abs(got[1]! - want[1]!) < 1e-6, `${got} ≈ ${want}`)
+  }
+})
+
+test('a fan is as large as what turns, and never smaller than 60 mm', () => {
+  const big = jointFanOf(arm(), 'arm') as unknown as { shape: { profile: { x: number; y: number }[] } }
+  const radius = Math.max(...big.shape.profile.map(p => Math.hypot(p.x, p.y)))
+  assert.ok(Math.abs(radius - 240) < 1e-3, `0.6 × 400 — ${radius}`)
+})
+
+test('no fan for a part that does not turn, nor for a slide -- a fan in a guessed plane would point the wrong way', () => {
+  assert.equal(jointFanOf(arm(), 'base'), null)
+  assert.equal(jointFanOf(arm(), ''), null)
+  let slider = createV3Asset('Probe')
+  slider = addV3Box(slider, { id: 'block', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  slider = applyV3Authoring(slider, { kind: 'add-motion', part: 'block', motion: { kind: 'slide', axis: 'x' }, state: { id: 'shift', unit: 'mm', min: 0, max: 60 } })
+  assert.equal(jointFanOf(slider, 'block'), null)
+})
+
+test('the editor draws it for the selected part, with the pose in hand; the canvas never lets it be picked', () => {
+  const editor = read('../client/modeller/v3-editor.ts')
+  assert.ok(editor.includes('.fan=${this.fanOf(asset as V3Asset | undefined)}'))
+  assert.ok(editor.includes('return jointFanOf(asset, this.selected, this.live.values)'))
+  const canvas = read('../client/modeller/v3-canvas.ts')
+  assert.ok(canvas.includes('{ ...fan, capturable: false, locked: true }'))
+})
+
+/* ── Joints the converter wrote (user 2026-09-24: 「로봇암 axis와 관절의 각도 표현을 다시 검증해보라」) ───────── */
+
+/** A V2 column: a link on a hinge at the root, a tip on a wrist inside it -- a first joint and a nested one. */
+function column(): V3Asset {
+  const source = {
+    version: 2,
+    type: 'COLUMN',
+    base: { x: 200, y: 700, z: 200 },
+    parts: [
+      { name: 'base', primitive: 'cube', transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 200, y: 100, z: 200 } }, material: { token: 'palette.dark' } },
+      { name: 'link', primitive: 'cube', transform: { position: { x: 0, y: 300, z: 0 }, size: { x: 80, y: 400, z: 80 } }, material: { token: 'palette.primary' }, parent: 'base' },
+      { name: 'tip', primitive: 'cube', transform: { position: { x: 0, y: 600, z: 0 }, size: { x: 60, y: 200, z: 60 } }, material: { token: 'palette.primary' }, parent: 'link' },
+      /* Rides the hinge, centred on the wrist's axis -- the wrist's housing, as ROBOT_ARM's elbow-housing is the elbow's. */
+      { name: 'housing', primitive: 'cube', transform: { position: { x: 0, y: 500, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.dark' }, parent: 'link' },
+      /* Rides the hinge and holds no pivot. */
+      { name: 'badge', primitive: 'cube', transform: { position: { x: 60, y: 300, z: 0 }, size: { x: 10, y: 40, z: 40 } }, material: { token: 'palette.dark' }, parent: 'link' }
+    ],
+    joints: [
+      { name: 'hinge', child: 'link', type: 'revolute', origin: { x: 0, y: 100, z: 0 }, axis: { x: 1, y: 0, z: 0 }, limits: { min: -90, max: 60 } },
+      { name: 'wrist', child: 'tip', type: 'revolute', origin: { x: 0, y: 500, z: 0 }, axis: { x: 0, y: 0, z: 1 }, limits: { min: -120, max: 120 } }
+    ]
+  }
+  const result = convertV2ToV3(source, { palette: { 'palette.dark': '#333333', 'palette.primary': '#3366cc' } } as never)
+  assert.equal(result.status, 'converted', JSON.stringify((result as { refusals?: unknown }).refusals))
+  return (result as unknown as { asset: V3Asset }).asset
+}
+
+const sub = (a: number[], b: number[]) => a.map((v, i) => v - b[i]!)
+const dot = (a: number[], b: number[]) => a.reduce((s, v, i) => s + v * b[i]!, 0)
+const angle = (a: number[], b: number[]) => (Math.acos(Math.max(-1, Math.min(1, dot(a, b) / (Math.hypot(...a) * Math.hypot(...b))))) * 180) / Math.PI
+const turnOf = (r1: number[][], r2: number[][]) => {
+  let trace = 0
+  for (let i = 0; i < 3; i++) for (let k = 0; k < 3; k++) trace += r1[k]![i]! * r2[k]![i]!
+  return (Math.acos(Math.max(-1, Math.min(1, (trace - 1) / 2))) * 180) / Math.PI
+}
+
+/*
+  Checked against the motion, not against the fan's own sampling: where the part's centre really is at the control's
+  ends, and how far its orientation really turns, summed in small steps.
+*/
+for (const [part, joint] of [
+  ['link', 'hinge'],
+  ['tip', 'wrist']
+] as const) {
+  test(`${part} on ${joint}: the axis holds the part's plane, the fan's ends are where it goes, the fan opens as far as it turns`, () => {
+    const asset = column()
+    const fan = jointFanOf(asset, part) as unknown as { pose: { t: number[]; r: number[][] }; shape: { profile: { x: number; y: number }[] } }
+    assert.ok(fan, 'a fan -- the first joint of a chain included')
+    const input = asset.document.model.inputs.find(i => i.id === joint)!
+    const pivot = fan.pose.t
+    const axis = [0, 1, 2].map(i => fan.pose.r[i]![1]!)
+    const at = (s: number) =>
+      compileV3Asset({ ...asset, stateDefaults: { ...asset.stateDefaults, [joint]: s } }).evaluate().geometry.find(g => g.id === part) as unknown as { pose: { t: number[]; r: number[][] } }
+    const onFan = (p: { x: number; y: number }) => [0, 1, 2].map(i => pivot[i]! + fan.pose.r[i]![0]! * p.x + fan.pose.r[i]![2]! * p.y)
+    const flat = (v: number[]) => sub(v, axis.map(a => a * dot(v, axis)))
+
+    const axial = [input.min!, 0, input.max!].map(s => dot(sub(at(s).pose.t, pivot), axis))
+    assert.ok(Math.max(...axial) - Math.min(...axial) < 1e-6, `the part stays in the fan's plane: ${axial}`)
+
+    const edges = fan.shape.profile.filter(p => p.x !== 0 || p.y !== 0)
+    assert.ok(angle(flat(sub(onFan(edges[0]!), pivot)), flat(sub(at(input.min!).pose.t, pivot))) < 0.01, 'the first edge is where the part is at the lowest value (the profile is kept to a micrometre)')
+    assert.ok(angle(flat(sub(onFan(edges[edges.length - 1]!), pivot)), flat(sub(at(input.max!).pose.t, pivot))) < 0.01, 'the last edge, at the highest')
+
+    let opens = 0,
+      turns = 0
+    for (let i = 1; i < edges.length; i++) opens += angle(sub(onFan(edges[i - 1]!), pivot), sub(onFan(edges[i]!), pivot))
+    for (let i = 1; i <= 60; i++) {
+      const s = (k: number) => input.min! + ((input.max! - input.min!) * k) / 60
+      turns += turnOf(at(s(i - 1)).pose.r, at(s(i)).pose.r)
+    }
+    assert.ok(Math.abs(opens - turns) < 0.01 && Math.abs(turns - (input.max! - input.min!)) < 0.01, `opens ${opens}, turns ${turns}`)
+  })
+}
+
+test('a housing shows the joint it houses, not the one that carries it; a part that holds no pivot shows none', () => {
+  const asset = column()
+  const turns = (part: string) => (jointFanOf(asset, part) as unknown as { turns?: string } | null)?.turns ?? null
+  assert.equal(turns('housing'), 'wrist', 'user 2026-09-24: 「elbow-housing itself is a axis」 -- it rides the hinge, it houses the wrist')
+  assert.equal(turns('link'), 'hinge', 'a link with pivots only at its ends shows the joint that turns it')
+  assert.equal(turns('tip'), 'wrist')
+  assert.equal(turns('badge'), null)
+  assert.equal(turns('base'), null)
+
+  /* The housing's fan is the wrist's: its ends are where the tip goes. */
+  const fan = jointFanOf(asset, 'housing') as unknown as { pose: { t: number[]; r: number[][] }; shape: { profile: { x: number; y: number }[] } }
+  const axis = [0, 1, 2].map(i => fan.pose.r[i]![1]!)
+  const flat = (v: number[]) => sub(v, axis.map(a => a * dot(v, axis)))
+  const onFan = (p: { x: number; y: number }) => [0, 1, 2].map(i => fan.pose.t[i]! + fan.pose.r[i]![0]! * p.x + fan.pose.r[i]![2]! * p.y)
+  const tipAt = (s: number) => (compileV3Asset({ ...asset, stateDefaults: { ...asset.stateDefaults, wrist: s } }).evaluate().geometry.find(g => g.id === 'tip') as unknown as { pose: { t: number[] } }).pose.t
+  const edges = fan.shape.profile.filter(p => p.x !== 0 || p.y !== 0)
+  assert.ok(angle(flat(sub(onFan(edges[0]!), fan.pose.t)), flat(sub(tipAt(-120), fan.pose.t))) < 0.01)
+  assert.ok(angle(flat(sub(onFan(edges[edges.length - 1]!), fan.pose.t)), flat(sub(tipAt(120), fan.pose.t))) < 0.01)
+})
+
+test('one joint, one fan: the housing and the part it turns show the same fan, sized from what turns', () => {
+  const asset = column()
+  const size = (part: string) => {
+    const fan = jointFanOf(asset, part) as unknown as { shape: { profile: { x: number; y: number }[] }; pose: { t: number[] } }
+    return { radius: Math.max(...fan.shape.profile.map(p => Math.hypot(p.x, p.y))), pivot: fan.pose.t }
+  }
+  const housing = size('housing'),
+    tip = size('tip')
+  assert.ok(Math.abs(housing.radius - tip.radius) < 1e-6, `user 2026-09-24: the elbow housing's fan was smaller than the forearm's -- ${housing.radius} vs ${tip.radius}`)
+  assert.deepEqual(housing.pivot, tip.pivot)
+})
+
+test('an axis running through a part does not make it that joint’s: a roll along a link shows on the roller, not the link', () => {
+  /* ROBOT_ARM's forearm showed the wrist roll, whose axis runs its length (2026-09-24 audit). */
+  const source = {
+    version: 2,
+    type: 'ROLLER',
+    base: { x: 200, y: 800, z: 200 },
+    parts: [
+      { name: 'base', primitive: 'cube', transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 200, y: 100, z: 200 } }, material: { token: 'palette.dark' } },
+      { name: 'link', primitive: 'cube', transform: { position: { x: 0, y: 300, z: 0 }, size: { x: 80, y: 400, z: 80 } }, material: { token: 'palette.primary' }, parent: 'base' },
+      { name: 'roller', primitive: 'cube', transform: { position: { x: 30, y: 600, z: 0 }, size: { x: 120, y: 200, z: 60 } }, material: { token: 'palette.primary' }, parent: 'link' }
+    ],
+    joints: [
+      { name: 'hinge', child: 'link', type: 'revolute', origin: { x: 0, y: 100, z: 0 }, axis: { x: 1, y: 0, z: 0 }, limits: { min: -90, max: 60 } },
+      { name: 'twist', child: 'roller', type: 'revolute', origin: { x: 0, y: 500, z: 0 }, axis: { x: 0, y: 1, z: 0 }, limits: { min: -170, max: 170 } }
+    ]
+  }
+  const result = convertV2ToV3(source, { palette: { 'palette.dark': '#333333', 'palette.primary': '#3366cc' } } as never)
+  assert.equal(result.status, 'converted')
+  const asset = (result as unknown as { asset: V3Asset }).asset
+  const turns = (part: string) => (jointFanOf(asset, part) as unknown as { turns?: string } | null)?.turns ?? null
+  assert.equal(turns('link'), 'hinge', 'the twist axis runs through the link, and the link does not twist')
+  assert.equal(turns('roller'), 'twist')
+  assert.equal(turns('base'), null)
+})
+

package/test/v3-keys.test.ts

@@ -0,0 +1,37 @@
+/*
+ * **모델러의 키** — V2 의 Ctrl+Z · Ctrl+Y 에 더해 복제 · 지우기 · 도형 전체로. 칸에 치는 키는 칸의 것이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { keyActionOf } from '../client/modeller/v3-keys.ts'
+
+test('되돌리기 · 다시 하기 — Ctrl 과 Cmd 모두, 부품을 고르지 않아도', () => {
+  assert.equal(keyActionOf({ key: 'z', ctrlKey: true }, ''), 'undo')
+  assert.equal(keyActionOf({ key: 'Z', metaKey: true, shiftKey: true }, ''), 'redo')
+  assert.equal(keyActionOf({ key: 'y', ctrlKey: true }, ''), 'redo')
+})
+
+test('고른 부품에만 — 복제 · 지우기 · 도형 전체로', () => {
+  assert.equal(keyActionOf({ key: 'd', ctrlKey: true }, 'arm'), 'duplicate')
+  assert.equal(keyActionOf({ key: 'Delete' }, 'arm'), 'remove')
+  assert.equal(keyActionOf({ key: 'Backspace' }, 'arm'), 'remove')
+  assert.equal(keyActionOf({ key: 'Escape' }, 'arm'), 'deselect')
+  for (const key of ['Delete', 'Backspace', 'Escape']) assert.equal(keyActionOf({ key }, ''), null, `${key} 는 고른 부품이 없으면 아무 일도 안 한다`)
+})
+
+test('칸에 치는 키는 칸의 것 — 이름 칸의 Backspace 는 글자를 지운다', () => {
+  for (const tagName of ['INPUT', 'select', 'TEXTAREA'])
+    assert.equal(keyActionOf({ key: 'Backspace', target: { tagName } }, 'arm'), null, tagName)
+  assert.equal(keyActionOf({ key: 'z', ctrlKey: true, target: { tagName: 'INPUT' } }, ''), null, '칸 안의 Ctrl+Z 는 칸의 되돌리기')
+  assert.equal(keyActionOf({ key: 'Delete', target: { tagName: 'DIV', isContentEditable: true } }, 'arm'), null)
+  assert.equal(keyActionOf({ key: 'Delete', target: { tagName: 'CANVAS' } }, 'arm'), 'remove')
+})
+
+test('편집기가 창의 키를 듣고, 떼어지면 놓는다', () => {
+  const editor = readFileSync(fileURLToPath(new URL('../client/modeller/v3-editor.ts', import.meta.url)), 'utf8')
+  assert.ok(editor.includes("window.addEventListener('keydown', this.onKey)") && editor.includes("window.removeEventListener('keydown', this.onKey)"))
+  assert.ok(editor.includes('target: e.composedPath()[0] as HTMLElement'), '그림자 DOM 안의 칸도 칸으로 안다')
+})

package/test/v3-layout.test.ts

@@ -0,0 +1,78 @@
+/*
+ * **V3 모델러의 구성 — V2 의 세 칸과 오른쪽 탭, 그보다 낫게** (사용자 2026-09-24: 「v2 모델러의 구성과 레이아웃이
+ * 좋았다. 그 보다도 더 좋아야지.」).
+ *
+ * V2 는 부품 목록 · 캔버스 · 오른쪽 칸(아이콘 탭 여섯)이었다. V3 는 부품 속성이 캔버스 아래 좁은 칸에 끼어 있었다.
+ * 이 시험은 소스에서 그 구성을 확인한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+const editor = read('../client/modeller/v3-editor.ts')
+const renderBody = editor.slice(editor.indexOf('  render() {'), editor.indexOf('  private renderField('))
+
+test('세 칸 — 부품 목록 · 캔버스 · 오른쪽 칸, 캔버스 아래에는 아무것도 없다', () => {
+  /* The three panes are ox-three-pane's (ADR-0060 decision 8): parts in start, the canvas in the middle, the side in end. */
+  const main = renderBody.slice(renderBody.indexOf('<ox-three-pane'), renderBody.indexOf('</ox-three-pane>'))
+  const order = ['<figure-v3-parts', '<figure-v3-canvas', '<aside slot="end">'].map(tag => main.indexOf(tag))
+  assert.match(main, /<figure-v3-parts\s+slot="start"/, '부품 목록은 왼쪽 칸')
+  assert.ok(order.every(i => i >= 0) && order[0]! < order[1]! && order[1]! < order[2]!, '부품 · 캔버스 · 오른쪽 칸 순서')
+  assert.equal((main.match(/<aside/g) ?? []).length, 1, '오른쪽 칸은 하나 — 페이지가 따로 칸을 두지 않는다')
+  assert.doesNotMatch(read('../client/pages/figure-v3-modeller-page.ts'), /<aside/)
+})
+
+test('오른쪽 칸의 탭 — V2 의 여섯: 속성 · 능력 · 움직임 · 판정 · 환경 · 이력, 판정의 개수는 탭에 남는다', () => {
+  const tabs = [...renderBody.matchAll(/this\.renderTab\('([a-z]+)'/g)].map(m => m[1])
+  assert.deepEqual(tabs, ['properties', 'capability', 'motion', 'verdict', 'view', 'history'])
+  for (const tab of tabs) assert.ok(renderBody.includes(`?off=\${tab !== '${tab}'}`), `${tab} 는 감추되 떼지 않는다`)
+})
+
+test('부품을 고르면 — 도형 전체의 탭(판정 · 이력)은 그 부품의 속성으로 넘어가고, 부품 탭은 새 부품을 보여 준다', () => {
+  const choose = editor.slice(editor.indexOf('  private choose('), editor.indexOf('  private asset()'))
+  assert.match(choose, /this\.selected = id/)
+  assert.match(choose, /if \(id && \(this\.tab === 'verdict' \|\| this\.tab === 'view' \|\| this\.tab === 'history'\)\) this\.tab = 'properties'/)
+  for (const from of ['@select-part=${(e: CustomEvent) => this.choose(e.detail.id)}', '@part-selected=${(e: CustomEvent<string>) => this.choose(e.detail)}'])
+    assert.ok(renderBody.includes(from), from)
+})
+
+test('부품을 보고 있으면 도형 전체로 돌아가는 칩이 탭마다 있다', () => {
+  assert.ok((renderBody.match(/\$\{this\.renderSubject\(\)\}/g) ?? []).length >= 3)
+  assert.match(editor.slice(editor.indexOf('  private renderSubject()')), /@click=\$\{\(\) => \(this\.selected = ''\)\}/)
+})
+
+test('탭마다 제자리 — 속성엔 부품의 모양 · 재질, 자리와 능력엔 사다리와 자리, 움직임엔 움직임 · 조작값', () => {
+  const panel = (tab: string) => {
+    const start = renderBody.indexOf(`?off=\${tab !== '${tab}'}`)
+    return renderBody.slice(start, renderBody.indexOf('<div panel', start + 1))
+  }
+  assert.ok(panel('properties').includes("this.renderLinks(unavailable, 'shape')") && panel('properties').includes('<figure-v3-material'))
+  assert.ok(panel('capability').includes("this.renderLinks(unavailable, 'places')") && panel('capability').includes('<figure-v3-capability'))
+  assert.ok(panel('motion').includes("this.renderLinks(unavailable, 'motion')") && panel('motion').includes('this.renderControls('))
+})
+
+test('띠 — 칸 접기 · 되돌리기 · 전체 보기 · 저장 상태 · 저장, 말은 번역에서', () => {
+  /* The bar is ox-canvas-bar: folds at its edges (it folds the frame it is given), undo · redo · fit in the suite's places. */
+  const bar = renderBody.slice(renderBody.indexOf('<ox-canvas-bar'), renderBody.indexOf('</ox-canvas-bar>'))
+  for (const piece of ['.pane=${this.panes}', 'history', 'fit', 'undo-shortcut="Ctrl+Z"', 'redo-shortcut="Ctrl+Y"', 'session!.undo()', 'session!.redo()', '.fit()', 'role="status"', '@click=${this.save}'])
+    assert.ok(bar.includes(piece), piece)
+  assert.doesNotMatch(renderBody, /[가-힣]/, '편집기의 화면 말에 한국어가 박혀 있지 않다')
+  const keys = [...editor.matchAll(/'(figure\.[a-z.-]*[a-z])'/g)].map(m => m[1])
+  for (const lang of ['ko', 'en', 'ja', 'zh', 'ms']) {
+    const table = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of keys) assert.ok(table[key], `${lang}: ${key}`)
+  }
+})
+
+test('탭 아이콘은 오른쪽 칸 맨 위 — 타입 칸은 V2 처럼 속성 탭 안의 첫 칸', () => {
+  const aside = renderBody.slice(renderBody.indexOf('<aside slot="end">'), renderBody.indexOf('</aside>'))
+  assert.match(aside, /^<aside slot="end">\s*<div tabs>/, '탭이 첫째')
+  const properties = aside.slice(aside.indexOf("?off=${tab !== 'properties'}"), aside.indexOf("?off=${tab !== 'capability'}"))
+  assert.ok(properties.includes('<slot name="figure"></slot>'))
+  const figure = read('../client/modeller/figure-v3-properties.ts')
+  assert.match(figure, /<h3>\$\{i18next\.t\('figure\.label\.group-figure'\)\}<\/h3>\s*<slot name="type"><\/slot>/, '타입은 「도형」 절의 첫 칸')
+  const page = read('../client/pages/figure-v3-modeller-page.ts')
+  assert.ok(page.includes('<label slot="type" type-field>'))
+})