@things-factory/figure-ui 10.1.49 → 10.1.50

package/test/joints.ts

@@ -0,0 +1,33 @@
+/*
+ * Moving a part in a test, as the modeller does it now (ADR-0093): the joint above the part is given a turn or a
+ * slide. A part fastened to nothing is stood on the floor first -- a joint has a parent.
+ */
+import { applyV3Authoring } from '@hatiolab/figure-model'
+import type { V3Asset, V3Joint } from '@hatiolab/figure-model'
+
+export function moving(
+  asset: V3Asset,
+  part: string,
+  spec: { kind: 'slide' | 'turn'; axis: 'x' | 'y' | 'z'; id: string; min: number; max: number; start?: number }
+): V3Asset {
+  /* Stood on the floor where it is: its X and Z kept as offsets on the plane. */
+  const at = (axis: 'x' | 'z') => ({ mm: asset.designInputs[`${part}.position.${axis}`] ?? 0 })
+  const above: V3Joint = asset.joints?.find(j => j.body1.part === part) ?? {
+    id: part,
+    type: 'fixed',
+    body0: { plane: 'mounting-plane' },
+    body1: { part, face: 'bottom' },
+    origin: { align: { x: at('x'), z: at('z') } }
+  }
+  return applyV3Authoring(asset, {
+    kind: 'set-joint',
+    joint: {
+      ...above,
+      type: spec.kind === 'slide' ? 'prismatic' : 'revolute',
+      axis: spec.axis.toUpperCase() as 'X' | 'Y' | 'Z',
+      lowerLimit: spec.min,
+      upperLimit: spec.max,
+      state: { id: spec.id, ...(spec.start !== undefined ? { start: spec.start } : {}) }
+    }
+  })
+}

package/test/v3-clips.test.ts

@@ -12,15 +12,16 @@ import { addV3Box, applyV3Authoring, createV3Asset, editV3Part } from '@hatiolab
 import type { V3Asset } from '@hatiolab/figure-model'
 
 import { clipsOf, poseAt, trackEdit, undrivenOf, withKey, withoutKey } from '../client/modeller/v3-clips.ts'
+import { moving } from './joints.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 = moving(asset, 'block', { kind: 'slide', axis: 'x', id: 'shift', 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 } })
+  return moving(asset, 'arm', { kind: 'turn', axis: 'y', id: 'spin', min: -180, max: 180, start: 0 })
 }
 
 test('클립마다 길이와 트랙을, 트랙마다 키를 초로 읽는다', () => {

package/test/v3-controls.test.ts

@@ -13,15 +13,16 @@ import { addV3Box, applyV3Authoring, createV3Asset, editV3Part } from '@hatiolab
 import type { V3Asset } from '@hatiolab/figure-model'
 
 import { controlsOf, poseAsDefault, poseDiffers } from '../client/modeller/v3-controls.ts'
+import { moving } from './joints.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 = moving(asset, 'block', { kind: 'slide', axis: 'x', id: 'shift', 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 } })
+  return moving(asset, 'arm', { kind: 'turn', axis: 'y', id: 'spin', min: -90, max: 90, start: 0 })
 }
 
 test('조작값마다 이름 · 단위 · 범위 · 지금 값 · 시작 값 · 이동 시간을 읽는다', () => {

package/test/v3-fields.test.ts

@@ -101,7 +101,8 @@ test('pitch 는 한 곳에서 하나의 값이고, 늘 set-repeat 로 바꿔 최
 test('기즈모로 끈 변환 부품은 규칙을 지킨 채 옮겨지고, 관절·붙이기가 정하는 부품은 까닭을 말한다 — 튕겨 돌아가지 않는다', () => {
   const editor = readFileSync(fileURLToPath(new URL('../client/modeller/v3-editor.ts', import.meta.url)), 'utf8')
   const moved = editor.slice(editor.indexOf('  private transformed('), editor.indexOf('  /** 맞추기'))
-  assert.ok(moved.includes("this.session!.command({ kind: 'nudge-part', part: id,"), '사용자 2026-09-24: 「기즈모 컨트롤도 전혀 작동이 안되는군」')
-  assert.ok(moved.includes("'figure.text.gizmo-joint-places'") && moved.includes("'figure.text.gizmo-fastening-places'") && moved.includes("'figure.text.gizmo-size-worked-out'"))
+  assert.ok(moved.includes("kind: 'nudge-part',"), '사용자 2026-09-24: 「기즈모 컨트롤도 전혀 작동이 안되는군」')
+  assert.ok(moved.includes('...(Object.keys(grow).length ? { grow } : {})'), '크기 끌기도 배율로 — 「되는 듯하다가 다시 원래 크기로 돌아간다」')
+  assert.ok(moved.includes("'figure.text.gizmo-joint-places'") && moved.includes("'figure.text.gizmo-fastening-places'"))
 })
 

package/test/v3-first-save.test.ts

@@ -0,0 +1,75 @@
+/*
+ * **처음 저장은 타입과 이름을 묻는다** — V2 의 저장 창. V3 로 옮기며 빠져서 새 도형이 기계 이름으로 저장됐다(2026-09-25).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { placeholderType } from '@hatiolab/figure-model'
+import { firstSaveRefusalOf, releasableType, typeOf } from '../client/modeller/v3-first-save.ts'
+import { createV3ProductSession, type V3ProductStore } from '../client/modeller/v3-product-session.ts'
+
+test('치는 대로 타입의 모양이 된다 — 대문자 · 숫자 · 밑줄', () => {
+  assert.equal(typeOf(' agv lifter '), 'AGV_LIFTER')
+  assert.equal(typeOf('oht-2'), 'OHT_2')
+})
+
+test('발행할 수 없는 이름은 미리 말한다 — 임시 이름 · 형식 · 길이', () => {
+  assert.equal(releasableType('AGV_LIFTER'), true)
+  assert.equal(releasableType(placeholderType()), false, '서버가 붙이는 임시 이름')
+  assert.equal(releasableType('AB'), false, '3 자 미만')
+  assert.equal(releasableType('A__B'), false, '밑줄 둘')
+  assert.equal(releasableType('_OHT'), false)
+})
+
+test('비었거나 이미 쓰는 이름이면 저장하지 않는다', () => {
+  assert.deepEqual(firstSaveRefusalOf('', ['OHT']), { key: 'figure.text.enter-a-type-name' })
+  assert.deepEqual(firstSaveRefusalOf('OHT', ['OHT']), { key: 'figure.text.type-name-already-taken', type: 'OHT' })
+  assert.equal(firstSaveRefusalOf('AGV', ['OHT']), null)
+})
+
+/** A store that remembers what it was asked. */
+function recording() {
+  const requests: Parameters<V3ProductStore['save']>[0][] = []
+  const store: V3ProductStore = {
+    load: async id => ({ id, source: saved ?? '' }),
+    save: async request => {
+      requests.push(request)
+      saved = request.source
+      return { id: request.id ?? 'new-id', source: request.source }
+    }
+  }
+  let saved: string | undefined
+  return { store, requests }
+}
+
+test('타입은 새 도형을 만드는 저장에만 실린다 — 이미 있는 도형의 저장은 타입을 보내지 않는다', async () => {
+  const { store, requests } = recording()
+  const session = createV3ProductSession(store)
+  session.startNew()
+  await session.save({ type: 'AGV_LIFTER' })
+  assert.equal(requests[0]!.type, 'AGV_LIFTER')
+  assert.equal(requests[0]!.id, undefined, '만드는 저장')
+
+  session.command({ kind: 'rename', name: '리프터' })
+  await session.save({ type: 'OTHER' })
+  assert.equal(requests[1]!.id, 'new-id')
+  assert.equal('type' in requests[1]!, false, '있는 도형에는 보내지 않는다')
+})
+
+test('타입을 주지 않으면 싣지 않는다 — 서버가 임시 이름을 붙인다', async () => {
+  const { store, requests } = recording()
+  const session = createV3ProductSession(store)
+  session.startNew()
+  await session.save()
+  assert.equal('type' in requests[0]!, false)
+})
+
+test('저장 전에 적은 타입은 처음 저장의 물음에 실려 온다 — 칸이 막혀 있어 적어도 사라졌다 (09-25)', async () => {
+  const { readFileSync } = await import('node:fs')
+  const page = readFileSync(new URL('../client/pages/figure-v3-modeller-page.ts', import.meta.url), 'utf8')
+  const field = page.slice(page.indexOf('<label slot="type" type-field>'), page.indexOf('</label>', page.indexOf('<label slot="type" type-field>')))
+  assert.doesNotMatch(field, /disabled=\$\{!view\.id\}/, '저장 전에도 칸에 적을 수 있다')
+  const rename = page.slice(page.indexOf('private renameType'), page.indexOf('private fitToParts'))
+  assert.match(rename, /if \(!id\) \{\s*this\.row = \{ \.\.\.this\.row, type: wanted \|\| undefined \}/, '저장 전에는 행 대신 화면이 타입을 쥔다')
+  assert.match(page, /<figure-v3-first-save \.type=\$\{this\.row\.type \?\? ''\}/, '물음은 그 타입으로 열린다')
+})

package/test/v3-gizmo.test.ts

@@ -12,6 +12,7 @@ import { fileURLToPath } from 'node:url'
 import { addV3Box, addV3Primitive, applyV3Authoring, compileV3Asset, createV3Asset, createV3EditorWorkspace } from '@hatiolab/figure-model'
 
 import { gizmoChanges, gizmoReachOf } from '../client/modeller/v3-gizmo.ts'
+import { moving } from './joints.ts'
 
 const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
 const probe = () => {
@@ -28,11 +29,14 @@ const apply = (asset: ReturnType<typeof probe>, changes: ReturnType<typeof gizmo
 const pose = (asset: ReturnType<typeof probe>, id: string) =>
   (compileV3Asset(asset).evaluate().geometry.find(g => (g as { id: string }).id === id) as unknown as { pose: { t: number[]; r: number[][] } }).pose
 
-test('만든 상자는 셋 다, 원기둥은 크기를 뺀 둘을 낸다', () => {
+test('만든 상자는 셋 다, 원기둥도 셋 다 — 원기둥의 크기는 반지름과 길이로', () => {
   assert.deepEqual(gizmoReachOf(probe() as never, 'body'), {
     translate: true, rotate: true, scale: true, sizes: ['body.size.x', 'body.size.y', 'body.size.z']
   })
-  assert.deepEqual(gizmoReachOf(probe() as never, 'drum'), { translate: true, rotate: true, scale: false })
+  const drum = gizmoReachOf(probe() as never, 'drum')
+  assert.equal(drum.scale, true, '사용자 2026-09-24: 크기 기즈모가 원기둥에서 먹지 않았다')
+  assert.equal(drum.round?.across.length, 1)
+  assert.equal(drum.round?.along.length, 1)
 })
 
 test('편집기의 도형 팔레트로 만든 상자 · 둥근 상자도 크기를 낸다 — 입력 이름이 dimension.* 이다', () => {
@@ -80,7 +84,7 @@ test('끈 것은 세션의 한 걸음이다 — 한 번의 되돌리기로 돌
   const editor = read('../client/modeller/v3-editor.ts')
   const moved = editor.slice(editor.indexOf('  private transformed('), editor.indexOf('  /** 맞추기'))
   assert.ok(moved.includes('this.run(() => this.session!.apply(changes))'), 'one apply, one step')
-  assert.ok(moved.includes("this.session!.command({ kind: 'nudge-part'"), 'a nudge is one command, one step')
+  assert.ok(moved.includes("kind: 'nudge-part',"), 'a nudge is one command, one step')
 })
 
 test('캔버스 — 기즈모 · W E R · 스냅은 씬의 편집 모드가 한다, V2 처럼', () => {
@@ -102,6 +106,35 @@ test('떼어 낸 부품은 다시 옮길 수 있다 — 움직임이 있는 부
   const fastened = applyV3Authoring(asset, { kind: 'attach', part: 'lid', face: 'bottom', to: { part: 'body', face: 'top' } })
   const free = applyV3Authoring(fastened, { kind: 'detach', part: 'lid' })
   assert.equal(gizmoReachOf(free as never, 'lid').translate, true)
-  const moving = applyV3Authoring(free, { kind: 'add-motion', part: 'lid', motion: { kind: 'slide', axis: 'x' }, state: { id: 'lid-slide', unit: 'mm', min: 0, max: 100, start: 0 } })
-  assert.equal(gizmoReachOf(moving as never, 'lid').translate, false)
+  const slid = moving(free, 'lid', { kind: 'slide', axis: 'x', id: 'lid-slide', min: 0, max: 100, start: 0 })
+  assert.equal(gizmoReachOf(slid as never, 'lid').translate, false, 'not its own numbers: a drag on a joint edits the joint (v3-joint-drag)')
+})
+
+test('끄는 동안은 모아 두고 놓을 때 한 번 적는다 — 크기 기즈모가 편집기와 싸우지 않는다', () => {
+  const canvas = read('../client/modeller/v3-canvas.ts')
+  const watch = canvas.slice(canvas.indexOf('  private watchScene()'), canvas.indexOf('  /** Components the gizmo changed'))
+  assert.ok(watch.includes('this.pending.set(name, origin!)') && watch.includes('if (!this.pointerDown) this.commitSoon(80)'), '사용자 2026-09-24: 「기즈모 컨트롤 중에 scale은 제대로 작동하지 않는군」')
+  assert.ok(!watch.includes("new CustomEvent('part-transformed'"), '움직일 때마다 알리지 않는다')
+  assert.ok(canvas.includes('private onPointerUp = () => {') && canvas.includes('this.commitSoon(0)'))
+})
+
+
+test('원기둥 · 구도 크기 기즈모가 먹는다 — 단면은 원으로(V2 의 keepRound)', async () => {
+  const { addV3Primitive, createV3Asset } = await import('@hatiolab/figure-model')
+  const { paletteRecipe } = await import('../client/modeller/v3-palette.ts')
+  const { gizmoChanges, gizmoReachOf } = await import('../client/modeller/v3-gizmo.ts')
+  let asset = createV3Asset('Round') as any
+  asset = addV3Primitive(asset, paletteRecipe('cylinder', 'drum') as any)
+  asset = addV3Primitive(asset, paletteRecipe('sphere', 'ball') as any)
+  const values = { ...asset.designInputs }
+  const drum = gizmoReachOf(asset, 'drum')
+  assert.equal(drum.scale, true, '원기둥도 크기를 받는다')
+  const [radius] = drum.round!.across, [length] = drum.round!.along
+  const changes = gizmoChanges('drum', drum, { scale: [1.5, 2, 1] }, values)
+  const put = Object.fromEntries(changes.map((c: any) => [c.input, c.value]))
+  assert.equal(put[radius!], Math.round(values[radius!] * 1.5), 'X 로 끈 만큼 반지름 — Z 도 같은 반지름이라 원이다')
+  assert.equal(put[length!], Math.round(values[length!] * 2))
+  const ball = gizmoReachOf(asset, 'ball')
+  const radii = gizmoChanges('ball', ball, { scale: [1, 1, 0.5] }, values).map((c: any) => c.value / values[c.input])
+  assert.equal(new Set(radii.map((r: number) => r.toFixed(2))).size, 1, '구의 세 반지름이 한 배율로 — 타원체가 되지 않는다')
 })

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

@@ -0,0 +1,93 @@
+/*
+ * **기즈모로 관절에 달린 부품을 끌면 관절을 고친다** (ADR-0093) — 도는 관절은 값, 미끄러지는 관절은 값, 그 밖의 이동은
+ * 관절이 놓인 자리(간격 · 면 위 오프셋). 관계를 끊는 끌기는 이유와 함께 거절한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { addV3Box, applyV3Authoring, compileV3Asset, createV3Asset } from '@hatiolab/figure-model'
+import type { V3Asset, V3Joint } from '@hatiolab/figure-model'
+import { jointDragOf } from '../client/modeller/v3-joint-drag.ts'
+
+/** A post on the floor, and a link on its top. */
+function column(joint: Partial<V3Joint>): V3Asset {
+  let asset = createV3Asset('Column')
+  asset = addV3Box(asset, { id: 'post', size: { x: 100, y: 200, z: 100 }, position: { x: 0, y: 100, z: 0 } })
+  asset = addV3Box(asset, { id: 'link', size: { x: 60, y: 300, z: 60 }, position: { x: 0, y: 350, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'post', face: 'bottom', to: { plane: 'mounting-plane' } })
+  return applyV3Authoring(asset, {
+    kind: 'set-joint',
+    joint: { id: 'bend', type: 'fixed', body0: { part: 'post', face: 'top' }, body1: { part: 'link', face: 'bottom' }, ...joint } as V3Joint
+  })
+}
+
+const drawn = (asset: V3Asset, id: string, state: Record<string, number> = {}) =>
+  compileV3Asset(asset).evaluate(state).geometry.find(g => g.id === id) as never as { id: string; pose: { t: number[]; r: number[][] } }
+
+/** The link turned `deg` about Z, as the gizmo would report it (degrees, XYZ). */
+const turnedZ = (deg: number) => [0, 0, deg] as [number, number, number]
+
+test('돌리면 관절값 — 관절 축 둘레로 돈 만큼, 범위 안으로', () => {
+  const asset = column({ type: 'revolute', axis: 'Z', lowerLimit: -90, upperLimit: 90 })
+  const part = drawn(asset, 'link')
+  assert.deepEqual(jointDragOf(asset, 'link', part as never, { rotation: turnedZ(30) }, {}), { kind: 'value', input: 'bend', unit: 'deg', value: 30 })
+  assert.deepEqual(jointDragOf(asset, 'link', part as never, { rotation: turnedZ(120) }, {}), { kind: 'value', input: 'bend', unit: 'deg', value: 90 }, '범위 끝에서 멈춘다')
+  /* Already at 40: a further 30 makes 70. */
+  const at40 = drawn(asset, 'link', { bend: 40 })
+  assert.deepEqual(jointDragOf(asset, 'link', at40 as never, { rotation: turnedZ(70) }, { bend: 40 }), { kind: 'value', input: 'bend', unit: 'deg', value: 70 })
+})
+
+test('끝없이 도는 관절은 −180..180 으로 감는다', () => {
+  const asset = column({ type: 'revolute', axis: 'Y' })
+  const at170 = drawn(asset, 'link', { bend: 170 })
+  const drag = jointDragOf(asset, 'link', at170 as never, { rotation: [0, 190, 0] }, { bend: 170 })
+  assert.equal(drag?.kind, 'value')
+  assert.ok(Math.abs((drag as { value: number }).value - -170) < 0.2, JSON.stringify(drag))
+})
+
+test('미끄러지는 관절은 축을 따라 옮긴 거리가 값', () => {
+  const asset = column({ type: 'prismatic', axis: 'X', lowerLimit: -100, upperLimit: 100 })
+  const part = drawn(asset, 'link')
+  const to = [part.pose.t[0]! + 40, part.pose.t[1]!, part.pose.t[2]!] as [number, number, number]
+  assert.deepEqual(jointDragOf(asset, 'link', part as never, { position: to }, {}), { kind: 'value', input: 'bend', unit: 'mm', value: 40 })
+})
+
+test('고정 관절에 달린 부품을 옮기면 관절이 놓인 자리 — 면을 따라는 간격, 면 위로는 오프셋', () => {
+  const asset = column({})
+  const part = drawn(asset, 'link')
+  const up = jointDragOf(asset, 'link', part as never, { position: [part.pose.t[0]!, part.pose.t[1]! + 25, part.pose.t[2]!] }, {})
+  assert.deepEqual(up, { kind: 'joint', joint: { ...asset.joints!.find(j => j.id === 'bend')!, origin: { gap: 25 } } })
+  const aside = jointDragOf(asset, 'link', part as never, { position: [part.pose.t[0]! + 30, part.pose.t[1]!, part.pose.t[2]!] }, {})
+  assert.deepEqual((aside as { joint: V3Joint }).joint.origin, { align: { x: { mm: 30 } } })
+})
+
+test('관계를 끊는 끌기는 거절하고 까닭을 댄다', () => {
+  const edge = column({ origin: { align: { x: 'min' } } })
+  const part = drawn(edge, 'link')
+  assert.deepEqual(jointDragOf(edge, 'link', part as never, { position: [part.pose.t[0]! + 30, part.pose.t[1]!, part.pose.t[2]!] }, {}), { kind: 'refused', reason: 'origin-follows', joint: 'bend' }, '모서리에 맞춘 자리는 그 모서리를 따른다')
+  const bend = column({ type: 'revolute', axis: 'Z', lowerLimit: -90, upperLimit: 90 })
+  assert.deepEqual(jointDragOf(bend, 'link', drawn(bend, 'link') as never, { rotation: [25, 0, 0] }, {}), { kind: 'refused', reason: 'off-axis', joint: 'bend', axis: 'Z' }, '다른 축으로 돌린 것은 적지 않는다')
+  const still = column({})
+  assert.deepEqual(jointDragOf(still, 'link', drawn(still, 'link') as never, { rotation: turnedZ(20) }, {}), { kind: 'refused', reason: 'fixed-turn', joint: 'bend' })
+})
+
+test('관절이 없는 부품은 이 길로 오지 않는다 — 제 숫자를 쓰는 길', () => {
+  let asset = createV3Asset('Free')
+  asset = addV3Box(asset, { id: 'box', size: { x: 10, y: 10, z: 10 }, position: { x: 0, y: 5, z: 0 } })
+  assert.equal(jointDragOf(asset, 'box', drawn(asset, 'box') as never, { position: [10, 5, 0] }, {}), null)
+})
+
+test('크기 끌기는 관절이 아니라 부품의 치수 — 따라가는 치수는 두고 제 치수만 쓴다 (사용자 09-25: 「R 모드에서 크기가 변하지 않는다」)', async () => {
+  const { gizmoChanges, gizmoReachOf } = await import('../client/modeller/v3-gizmo.ts')
+  let asset = column({ type: 'revolute', axis: 'Z', lowerLimit: -90, upperLimit: 90 })
+  /* A square section: the link's depth follows its width. */
+  asset = applyV3Authoring(asset, { kind: 'link-dimension', part: 'link', axis: 'z', source: { of: 'part', part: 'link', axis: 'x' } })
+  const part = drawn(asset, 'link')
+  const scaled = { position: [part.pose.t[0]!, part.pose.t[1]! + 60, part.pose.t[2]!] as [number, number, number], scale: [1, 1.4, 1] as [number, number, number] }
+  assert.equal(jointDragOf(asset, 'link', part as never, scaled, {}), null, '관절 자리로 받지 않는다')
+  const reach = gizmoReachOf(asset as never, 'link')
+  assert.deepEqual(reach.ownSizes, ['link.size.x', 'link.size.y', null], '깊이는 너비를 따른다')
+  const sizes = Object.fromEntries(asset.document.model.inputs.map(i => [i.id, asset.designInputs[i.id]!]))
+  assert.deepEqual(gizmoChanges('link', reach, { scale: scaled.scale }, sizes), [{ kind: 'set-design', input: 'link.size.y', unit: 'mm', value: 420 }])
+  assert.deepEqual(gizmoChanges('link', reach, { scale: [1, 1, 1.5] }, sizes), [], '따라가는 깊이만 끌면 아무것도 쓰지 않는다 — 편집기가 까닭을 말한다')
+})

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

@@ -12,6 +12,7 @@ import { addV3Box, applyV3Authoring, compileV3Asset, convertV2ToV3, createV3Asse
 import type { V3Asset } from '@hatiolab/figure-model'
 
 import { JOINT_FAN, jointFanOf } from '../client/modeller/v3-joint-fan.ts'
+import { moving } from './joints.ts'
 
 const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
 
@@ -19,16 +20,22 @@ 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 } })
+  /* On the base's top, level with its left edge: it turns about that edge, at x = -100. */
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'arm', face: 'bottom', to: { part: 'base', face: 'top' }, align: { x: 'min' } })
+  return moving(asset, 'arm', { kind: 'turn', axis: 'y', id: 'arm.turn', min: -45, max: 90 })
 }
+const PIVOT = [-100, 100, 0]
 
 /** 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)
 
+/** Which way a point lies from the joint, in the plane it turns in. */
 const direction = (v: number[]) => {
-  const l = Math.hypot(v[0]!, v[2]!)
-  return [v[0]! / l, v[2]! / l]
+  const x = v[0]! - PIVOT[0]!,
+    z = v[2]! - PIVOT[2]!
+  const l = Math.hypot(x, z)
+  return [x / l, z / l]
 }
 
 test('a part that turns gets a fan from the lowest value to the highest, where the part really goes', () => {
@@ -61,18 +68,21 @@ test('a fan is as large as what turns, and never smaller than 60 mm', () => {
 })
 
 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)
+  /* The base does not turn; it shows the joint that sits on it, the arm's -- one joint, one fan (the elbow rule). */
+  const onBase = jointFanOf(arm(), 'base') as unknown as { shape: { profile: unknown[] } }
+  const ofArm = jointFanOf(arm(), 'arm') as unknown as { shape: { profile: unknown[] } }
+  assert.deepEqual(onBase?.shape.profile, ofArm.shape.profile)
   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 } })
+  slider = moving(slider, 'block', { kind: 'slide', axis: 'x', id: 'shift', 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)'))
+  assert.ok(editor.includes('return jointFanOf(asset, this.selected, { ...this.currentInputs(), ...this.live.values })'), 'the fan reads the pose the session holds')
   const canvas = read('../client/modeller/v3-canvas.ts')
   assert.ok(canvas.includes('{ ...fan, capturable: false, locked: true }'))
 })

package/test/v3-keys.test.ts

@@ -32,6 +32,19 @@ test('칸에 치는 키는 칸의 것 — 이름 칸의 Backspace 는 글자를
 
 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 안의 칸도 칸으로 안다')
+  assert.ok(editor.includes("window.addEventListener('keydown', this.onKey, true)") && editor.includes("window.removeEventListener('keydown', this.onKey, true)"))
+})
+
+test('W · E · R 은 gizmo 의 모드 — 부품 목록에서 골라 포커스가 캔버스 밖에 있어도', () => {
+  assert.equal(keyActionOf({ key: 'w' }, 'arm'), 'translate')
+  assert.equal(keyActionOf({ key: 'E' }, 'arm'), 'rotate')
+  assert.equal(keyActionOf({ key: 'r' }, 'arm'), 'scale')
+  assert.equal(keyActionOf({ key: 'w' }, ''), null, '고른 부품이 없으면 붙일 곳이 없다')
+  assert.equal(keyActionOf({ key: 'r', ctrlKey: true }, 'arm'), null, 'Ctrl+R 은 브라우저의 것')
+  assert.equal(keyActionOf({ key: 'w', target: { tagName: 'INPUT' } }, 'arm'), null, '칸에 치는 w 는 글자')
+})
+
+test('캔버스에서 누른 W · E · R 은 씬이 이미 받았다 — 또 넘기면 gizmo 가 꺼진다', () => {
+  for (const key of ['w', 'e', 'r']) assert.equal(keyActionOf({ key, inScene: true }, 'arm'), null, key)
+  assert.equal(keyActionOf({ key: 'Delete', inScene: true }, 'arm'), 'remove', '다른 키는 그대로')
 })

package/test/v3-links.test.ts

@@ -53,30 +53,23 @@ test('붙이기 — 누구에게 붙었나, 붙일 수 있는 모양인가', ()
 test('움직임 — 미끄러짐 · 돌기, 축, 무엇이 모느냐를 읽는다', () => {
   const asset = pair()
   assert.equal(motionOf(asset, 'block'), undefined)
-  const sliding = applyV3Authoring(asset, {
-    kind: 'add-motion',
-    part: 'block',
-    motion: { kind: 'slide', axis: 'x' },
-    state: { id: 'travel', unit: 'mm', min: 0, max: 300, start: 0 }
-  })
+  const sliding = moving(asset, 'block', { kind: 'slide', axis: 'x', id: 'travel', min: 0, max: 300, start: 0 })
   const motion = motionOf(sliding, 'block')!
   assert.equal(motion.kind, 'slide')
   assert.equal(motion.axis, 'x')
   assert.equal(motion.control?.id, 'travel')
   assert.equal(motion.control?.max, 300)
-  const turning = applyV3Authoring(asset, {
-    kind: 'add-motion',
-    part: 'block',
-    motion: { kind: 'turn', axis: 'y' },
-    state: { id: 'swing', unit: 'deg', min: -90, max: 90, start: 0 }
-  })
+  const turning = moving(asset, 'block', { kind: 'turn', axis: 'y', id: 'swing', min: -90, max: 90, start: 0 })
   assert.deepEqual([motionOf(turning, 'block')!.kind, motionOf(turning, 'block')!.axis], ['turn', 'y'])
-  assert.equal(motionOf(applyV3Authoring(sliding, { kind: 'remove-motion', part: 'block' }), 'block'), undefined)
+  const joint = sliding.joints!.find(j => j.body1.part === 'block')!
+  const still = applyV3Authoring(sliding, { kind: 'set-joint', joint: { id: joint.id, type: 'fixed', body0: joint.body0, body1: joint.body1 } })
+  assert.equal(motionOf(still, 'block'), undefined, 'a fixed joint does not move')
 })
 
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { choiceOf } from '../client/modeller/v3-links.ts'
+import { moving } from './joints.ts'
 
 const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
 
@@ -235,7 +228,7 @@ test('놓일 수 있는 크기 — 남은 만큼 채우던 부품을 비례로
 test('관절이 있는 도형에는 한 비율로 키우기를 권하고, 선언하면 규칙으로 보인다(수석 아키텍트 판정 09-24)', () => {
   let asset = sizedPair()
   assert.equal(turnsAboutAJoint(asset), false)
-  asset = applyV3Authoring(asset, { kind: 'add-motion', part: 'flange', motion: { kind: 'turn', axis: 'y' }, state: { id: 'flange.turn', unit: 'deg', min: 0, max: 90 } })
+  asset = moving(asset, 'flange', { kind: 'turn', axis: 'y', id: 'flange.turn', min: 0, max: 90 })
   assert.equal(turnsAboutAJoint(asset), true)
   const editor = read('../client/modeller/v3-editor.ts')
   const rule = editor.slice(editor.indexOf('  private renderSizingRule('), editor.indexOf('  /** Choose a part,'))
@@ -244,3 +237,58 @@ test('관절이 있는 도형에는 한 비율로 키우기를 권하고, 선언
   assert.ok(rule.includes("this.linkCommand({ kind: 'scale-uniformly' })"), '누르면 선언한다 — 사람이 정한다')
 })
 
+
+test('붙일 때 면 위 어디에 — 그 면을 가로지르는 두 축만, 바닥에는 모서리가 없다 (문을 틀 모서리에 달기, 09-25)', async () => {
+  const { alignAxesOf, alignOf } = await import('../client/modeller/v3-links.ts')
+  assert.deepEqual(alignAxesOf('right'), [{ axis: 'y', edges: true }, { axis: 'z', edges: true }])
+  assert.deepEqual(alignAxesOf('plane'), [{ axis: 'x', edges: false }, { axis: 'z', edges: false }])
+  /* A door on the jamb's right face: bottoms level, fronts level. The x choice is along the face and is not sent. */
+  assert.deepEqual(alignOf('right', { x: 'max', y: 'min', z: 'max' }, {}), { y: 'min', z: 'max' })
+  assert.deepEqual(alignOf('top', { x: 'mm', z: 'centre' }, { x: 120 }), { x: { mm: 120 } })
+  assert.equal(alignOf('plane', { x: 'min' }, {}), undefined, '바닥에는 맞출 모서리가 없다')
+  assert.equal(alignOf('top', {}, {}), undefined)
+
+  /* What the form sends is what hangs the part on the edge: the door's pivot is on the jamb's front edge line. */
+  let asset = createV3Asset('Door')
+  asset = addV3Box(asset, { id: 'jamb', size: { x: 100, y: 2100, z: 150 }, position: { x: 0, y: 1050, z: 0 } })
+  asset = addV3Box(asset, { id: 'leaf', size: { x: 900, y: 2000, z: 40 }, position: { x: 600, y: 1000, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'jamb', face: 'bottom', to: { plane: 'mounting-plane' } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'leaf', face: 'left', to: { part: 'jamb', face: 'right' }, align: alignOf('right', { y: 'min', z: 'max' }, {}) })
+  const { compileV3Asset } = await import('@hatiolab/figure-model')
+  const leaf = compileV3Asset(asset).evaluate().geometry.find(g => g.id === 'leaf')!
+  assert.deepEqual(leaf.pose.t.map(Math.round), [500, 1000, 55], '문짝 아래가 문틀 아래에, 앞이 문틀 앞에')
+})
+
+test('따라 움직이는 관절 — 같은 방식으로 움직이고 제 조작값이 있는 관절만 고르고, 기록에는 배율과 더하기만 (집게 두 손가락, 09-25)', async () => {
+  const { leadersFor, motionJoint } = await import('../client/modeller/v3-links.ts')
+  const { compileV3Asset } = await import('@hatiolab/figure-model')
+  let asset = createV3Asset('Gripper')
+  asset = addV3Box(asset, { id: 'palm', size: { x: 240, y: 70, z: 160 }, position: { x: 0, y: 35, z: 0 } })
+  for (const id of ['left', 'right']) asset = addV3Box(asset, { id, size: { x: 30, y: 140, z: 100 }, position: { x: 0, y: 200, z: 0 } })
+  asset = addV3Box(asset, { id: 'wrist', size: { x: 60, y: 60, z: 60 }, position: { x: 0, y: 400, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'palm', face: 'bottom', to: { plane: 'mounting-plane' } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'left', face: 'bottom', to: { part: 'palm', face: 'top' }, align: { x: 'min' } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'right', face: 'bottom', to: { part: 'palm', face: 'top' }, align: { x: 'max' } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'wrist', face: 'top', to: { part: 'palm', face: 'bottom' } })
+  const form = { kind: 'slide' as const, axis: 'x' as const, id: 'grip', min: 0, max: 60, follow: '', multiplier: 1, offset: 0 }
+  const jointOf = (part: string) => asset.joints!.find(j => j.body1.part === part)!
+  asset = applyV3Authoring(asset, { kind: 'set-joint', joint: motionJoint(jointOf('left'), form, 'left') })
+  asset = applyV3Authoring(asset, { kind: 'set-joint', joint: motionJoint(jointOf('wrist'), { ...form, kind: 'turn', axis: 'y', id: 'twist', min: -90, max: 90 }, 'wrist') })
+
+  assert.deepEqual(leadersFor(asset, 'right', 'slide').map(j => j.id), ['left'], '미끄러지는 관절은 미끄러지는 관절을 따른다')
+  assert.deepEqual(leadersFor(asset, 'right', 'turn').map(j => j.id), ['wrist'])
+  assert.deepEqual(leadersFor(asset, 'left', 'slide'), [], '제 관절은 고르지 않는다')
+
+  const follower = motionJoint(jointOf('right'), { ...form, id: 'ignored', follow: 'left', multiplier: -1 }, 'right')
+  assert.deepEqual(follower.mimic, { joint: 'left', multiplier: -1 })
+  assert.equal(follower.state, undefined, '따라가는 관절은 제 조작값이 없다')
+  assert.equal(follower.lowerLimit, undefined)
+  asset = applyV3Authoring(asset, { kind: 'set-joint', joint: follower })
+  assert.deepEqual(leadersFor(asset, 'wrist', 'slide').map(j => j.id), ['left'], '따라가는 관절은 앞장서지 않는다')
+
+  const x = (id: string, grip: number) => Math.round(compileV3Asset(asset).evaluate({ grip }).geometry.find(g => g.id === id)!.pose.t[0]!)
+  assert.equal(x('left', 40) - x('left', 0), 40)
+  assert.equal(x('right', 40) - x('right', 0), -40, '오른손은 거울로 따라 닫힌다')
+  const { motionOf } = await import('../client/modeller/v3-links.ts')
+  assert.deepEqual(motionOf(asset, 'right')?.follows, { joint: 'left', multiplier: -1 }, '화면은 무엇을 따르는지 읽는다')
+})

package/test/v3-live.test.ts

@@ -7,16 +7,17 @@ import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-import { addV3Box, applyV3Authoring, createV3Asset } from '@hatiolab/figure-model'
+import { addV3Box, applyV3Authoring, compileV3Asset, createV3Asset } from '@hatiolab/figure-model'
 
-import { liveOverridesOf, livePartsOf, NOTHING_LIVE, scrubbed, scrubStep } from '../client/modeller/v3-live.ts'
+import { liveOverridesOf, liveOverSession, livePartsOf, NOTHING_LIVE, scrubbed, scrubStep } from '../client/modeller/v3-live.ts'
+import { moving } from './joints.ts'
 
 const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
 
 const slider = () => {
   let asset = createV3Asset('Slider')
   asset = addV3Box(asset, { id: 'block', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
-  return applyV3Authoring(asset, { kind: 'add-motion', part: 'block', motion: { kind: 'slide', axis: 'x' }, state: { id: 'shift', unit: 'mm', min: 0, max: 60, start: 0 } })
+  return moving(asset, 'block', { kind: 'slide', axis: 'x', id: 'shift', min: 0, max: 60, start: 0 })
 }
 
 test('끄는 값으로 그 자세를 바로 그린다 — 도형은 그대로', () => {
@@ -73,7 +74,7 @@ test('속성창 숫자 칸은 치는 동안 알리고, 이름표를 끌 수 있
   assert.ok(editor.includes('@input=${(e: Event) => this.typing(field as never, e)}'))
   assert.ok(editor.includes('@pointerdown=${(e: PointerEvent) => this.scrub(group.cells[axis] as never, e, unavailable)}'))
   for (const event of ['@v3-state-live=', '@v3-states-live=', '@v3-part-live=']) assert.ok(editor.includes(event), event)
-  assert.ok(editor.includes('livePartsOf(asset as V3Asset, this.live)') && editor.includes('.parts=${this.drawnParts(view.geometry, asset)}'), '캔버스가 끄는 값을 그린다')
+  assert.ok(editor.includes('liveOverSession(asset as V3Asset, this.currentInputs(), this.live)'), '캔버스는 세션 위에 끄는 값을 그린다 (행동은 아래 시험)')
   const run = editor.slice(editor.indexOf('  private run(action'), editor.indexOf('  private hold('))
   assert.ok(run.includes('this.live = NOTHING_LIVE'), '기록하거나 거절되면 끄는 값을 버린다')
   const material = read('../client/modeller/figure-v3-material.ts')
@@ -97,3 +98,21 @@ test('클립 트랙의 머리는 이름 한 줄, 그 아래 반복 방식과 지
   assert.ok(head.includes('width: 30px;'), '지우기는 작은 버튼')
 })
 
+test('끄는 동안은 세션이 지금 든 자세 위에 그린다 — 다른 관절이 저장된 각도로 돌아가지 않는다', () => {
+  /* Two joints: the author turned one with its control; then drags the other. */
+  let asset = slider()
+  /* An arm on a post of its own, turning about the post's left edge -- so a swing moves it, and the slide does not. */
+  asset = addV3Box(asset, { id: 'post', size: { x: 100, y: 100, z: 100 }, position: { x: 400, y: 50, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'post', face: 'bottom', to: { plane: 'mounting-plane' }, align: { x: { mm: 400 } } })
+  asset = addV3Box(asset, { id: 'arm', size: { x: 100, y: 20, z: 20 }, position: { x: 400, y: 110, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'arm', face: 'bottom', to: { part: 'post', face: 'top' }, align: { x: 'min' } })
+  asset = moving(asset, 'arm', { kind: 'turn', axis: 'y', id: 'swing', min: -180, max: 180 })
+  const current = { ...asset.designInputs, ...asset.stateDefaults, swing: 90 }
+  const armAt = (parts: { id: string; pose: { t: number[] } }[]) => parts.find(p => p.id === 'arm')!.pose.t.map(v => Math.round(v))
+  const committed = armAt(compileV3Asset({ ...asset, stateDefaults: { ...asset.stateDefaults, swing: 90 } }).evaluate().geometry as never)
+  const dragging = armAt(liveOverSession(asset, current, { values: { shift: 30 } }) as never)
+  assert.deepEqual(dragging, committed, '사용자 2026-09-24: 「조작을 끝내면 완전히 다른 위치로 된다」 — swing 90 이 끄는 동안에도 남는다')
+  const overSaved = armAt(livePartsOf(asset, { values: { shift: 30 } }) as never)
+  assert.notDeepEqual(overSaved, committed, '전제: 저장된 기본값 위에 그리면 swing 이 0 으로 돌아간다')
+})
+

package/test/v3-maturity.test.ts

@@ -25,6 +25,7 @@ import {
   v3ReportOf
 } from '../client/modeller/v3-maturity.ts'
 import { capacityFrom } from '../client/modeller/scene-budget.ts'
+import { moving } from './joints.ts'
 
 const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
 const verdict = read('../client/modeller/figure-v3-verdict.ts')
@@ -109,12 +110,7 @@ test('상태를 따라 움직이는 부품을 센다 — V2 의 「따로 움직
   asset = addV3Box(asset, cube('arm', 200))
   assert.equal(v3ReportOf(asset)!.score.budgets.find(b => b.key === 'independent')!.used, 0, '전제: 움직임이 없으면 0')
 
-  asset = applyV3Authoring(asset, {
-    kind: 'add-motion',
-    part: 'arm',
-    motion: { kind: 'turn', axis: 'y' },
-    state: { id: 'arm.turn', unit: 'deg', min: 0, max: 90 }
-  })
+  asset = moving(asset, 'arm', { kind: 'turn', axis: 'y', id: 'arm.turn', min: 0, max: 90 })
   assert.equal(v3ReportOf(asset)!.score.budgets.find(b => b.key === 'independent')!.used, 1, '도는 팔 하나')
 })