@things-factory/figure-ui 10.1.26 → 10.1.28

package/test/joint-edits.test.ts

@@ -0,0 +1,165 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { validate } from '@hatiolab/figure-model'
+import type { FigurePart } from '@hatiolab/figure-model'
+
+import { parentChoices, patchJoint, setJointType, jointOf } from '../client/modeller/joint-edits.ts'
+import { fromFigureSource, partToFigure, toFigureSource } from '../client/modeller/figure-source.ts'
+import type { FigureDraft, PartModel } from '../client/modeller/figure-source.ts'
+
+/*
+ * Editing joints (ADR-0066). Every result is checked against the format's own validate, so an edit that
+ * produces a source the format refuses fails here instead of on save.
+ */
+
+const part = (name: string, zPos: number, depth: number, parent?: string): PartModel => ({
+  type: 'figure-part',
+  name,
+  primitive: 'cube',
+  left: 50,
+  top: 50,
+  width: 100,
+  height: 100,
+  zPos,
+  depth,
+  token: 'palette.primary',
+  ...(parent ? { parent } : {})
+})
+
+const PARTS: PartModel[] = [part('base', 0, 100), part('arm', 100, 400, 'base'), part('tip', 500, 100, 'arm')]
+const DRAFT: FigureDraft = { version: 2, figureType: 'ARM', width: 200, height: 200, depth: 600, detailLevel: 'M' }
+
+const figurePart = (draft: FigureDraft, name: string): FigurePart => partToFigure(PARTS.find(p => p.name === name)!, draft)
+const errorsOf = (draft: FigureDraft) => validate(toFigureSource(draft, PARTS)).errors.map(e => `${e.code}@${e.path}`)
+
+describe('joint edits', () => {
+  it('offers as parents every part except itself and what hangs below it', () => {
+    assert.deepEqual(parentChoices(PARTS, 'arm'), ['base'])
+    // arm and tip hang below base, so base has nothing to attach to
+    assert.deepEqual(parentChoices(PARTS, 'base'), [])
+    assert.deepEqual(parentChoices([...PARTS, part('lamp', 0, 10)], 'arm'), ['base', 'lamp'])
+    assert.deepEqual(parentChoices(PARTS, 'tip'), ['base', 'arm'])
+  })
+
+  it('adds a joint where the part meets its parent, with a parameter that drives it', () => {
+    const draft = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute', figurePart(DRAFT, 'base'))
+    const joint = jointOf(draft, 'arm')!
+    assert.deepEqual(joint, {
+      name: 'arm-joint',
+      child: 'arm',
+      type: 'revolute',
+      origin: { x: 0, y: 100, z: 0 },
+      axis: { x: 0, y: 1, z: 0 },
+      limits: { min: -90, max: 90 }
+    })
+    assert.deepEqual(draft.parameters, [
+      {
+        name: 'arm-joint',
+        range: { unit: 'deg', min: -90, max: 90 },
+        default: 0,
+        clip: { channels: [{ target: 'arm-joint', keys: [{ at: 0, value: -90 }, { at: 1, value: 90 }] }] }
+      }
+    ])
+    assert.deepEqual(errorsOf(draft), [])
+  })
+
+  it('moves a plain driving parameter to millimetres when the joint starts sliding', () => {
+    const turning = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute')
+    const sliding = setJointType(turning, figurePart(turning, 'arm'), 'prismatic')
+    assert.deepEqual(jointOf(sliding, 'arm')!.limits, { min: 0, max: 500 })
+    assert.deepEqual(sliding.parameters![0]!.range, { unit: 'mm', min: 0, max: 500 })
+    assert.deepEqual(errorsOf(sliding), [])
+  })
+
+  it('drops limits for a continuous joint and still validates', () => {
+    const turning = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute')
+    const endless = setJointType(turning, figurePart(turning, 'arm'), 'continuous')
+    assert.equal('limits' in jointOf(endless, 'arm')!, false)
+    assert.deepEqual(endless.parameters![0]!.range, { unit: 'deg', min: -360, max: 360 })
+    assert.deepEqual(errorsOf(endless), [])
+  })
+
+  it('moves a plain driving parameter with new limits, and leaves one the author reshaped alone', () => {
+    const turning = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute')
+    const wider = patchJoint(turning, 'arm-joint', { limits: { min: -120, max: 150 } })
+    assert.deepEqual(wider.parameters![0]!.range, { unit: 'deg', min: -120, max: 150 })
+    assert.deepEqual(errorsOf(wider), [])
+
+    const reshaped: FigureDraft = {
+      ...turning,
+      parameters: [
+        {
+          ...turning.parameters![0]!,
+          clip: { channels: [{ target: 'arm-joint', keys: [{ at: 0, value: 0 }, { at: 0.5, value: 45 }, { at: 1, value: 90 }] }] }
+        }
+      ]
+    }
+    const kept = patchJoint(reshaped, 'arm-joint', { limits: { min: -120, max: 150 } })
+    assert.deepEqual(kept.parameters, reshaped.parameters)
+  })
+
+  it('clearing the joint removes it and every channel that drove it, and nothing else', () => {
+    const turning = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute')
+    const withClip: FigureDraft = {
+      ...turning,
+      animations: [
+        {
+          name: 'wiggle',
+          channels: [
+            { target: 'arm-joint', keys: [{ at: 0, value: 0 }, { at: 1, value: 30 }] },
+            { target: 'tip', path: 'rotation', keys: [{ at: 0, value: { x: 0, y: 0, z: 0 } }, { at: 1, value: { x: 0, y: 90, z: 0 } }] }
+          ]
+        }
+      ]
+    }
+    const cleared = setJointType(withClip, figurePart(withClip, 'arm'), undefined)
+    assert.equal(cleared.joints, undefined)
+    assert.deepEqual(cleared.parameters, [])
+    assert.deepEqual(cleared.animations![0]!.channels.map(c => c.target), ['tip'])
+    assert.deepEqual(errorsOf(cleared), [])
+  })
+
+  /*
+   * 관절은 두 부품이 **맞닿는 자리**에 선다. 위로 쌓은 부품에서는 아랫면이지만, 옆에 달린
+   * 부품에서는 옆면이다 — 그 구분이 없으면 캐비닛 문의 축이 문 바닥에 생긴다.
+   */
+  describe('새 관절이 서는 자리', () => {
+    const at = (over: Partial<PartModel>): PartModel => ({ ...part('door', 0, 100), ...over })
+
+    it('위에 쌓인 부품은 아랫면에서 만난다', () => {
+      /* arm 은 base(0..100) 위 100..500 이다. 맞닿는 면이 100 이고, 가로로는 둘이 겹치는 가운데다. */
+      const joint = jointOf(setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute', figurePart(DRAFT, 'base')), 'arm')!
+      assert.deepEqual(joint.origin, { x: 0, y: 100, z: 0 })
+    })
+
+    it('옆에 달린 부품은 옆면에서 만난다 — 아랫면이 아니다', () => {
+      /* 문은 몸통(가운데 0, 폭 100)의 오른쪽에 붙어 선다. 축은 문의 왼쪽 면, 높이는 겹치는 가운데. */
+      const body = at({ name: 'body', left: 0, top: 0, width: 100, height: 100, zPos: 0, depth: 400 })
+      const door = at({ name: 'door', left: 100, top: 0, width: 20, height: 100, zPos: 40, depth: 320, parent: 'body' })
+      const parts = [body, door]
+      const draft: FigureDraft = { ...DRAFT, width: 400, height: 400, depth: 400 }
+      const shown = (one: PartModel) => partToFigure(one, draft)
+
+      const joint = jointOf(setJointType(draft, shown(door), 'revolute', shown(body)), 'door')!
+      const half = draft.width / 2
+
+      assert.equal(joint.origin.x, 100 - half, '문의 왼쪽 면에 선다')
+      assert.equal(joint.origin.y, 200, '겹치는 높이(40..360 과 0..400)의 한가운데다')
+      assert.deepEqual(parts.map(one => one.name), ['body', 'door'])
+    })
+
+    it('붙은 부품이 없으면 아랫면이다 — 그때 맞닿는 것은 바닥이다', () => {
+      const joint = jointOf(setJointType(DRAFT, figurePart(DRAFT, 'base'), 'revolute'), 'base')!
+      assert.equal(joint.origin.y, 0)
+    })
+  })
+
+  it('a joint survives opening and saving', () => {
+    const turning = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute')
+    const saved = toFigureSource(turning, PARTS)
+    const { draft, parts } = fromFigureSource(saved)
+    assert.deepEqual(toFigureSource(draft, parts), saved)
+    assert.equal(saved.parts.find(p => p.name === 'tip')!.parent, 'arm')
+  })
+})

package/test/joint-gizmo.test.ts

@@ -0,0 +1,174 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import type { FigureJoint } from '@hatiolab/figure-model'
+
+import { axisName, gizmoPart, JOINT_GIZMO } from '../client/modeller/joint-gizmo.ts'
+import type { FigureDraft, PartModel } from '../client/modeller/figure-source.ts'
+
+/*
+ * 관절이 도는 자리를 저작면에 그리는 부채꼴.
+ *
+ * 저작자가 축을 고를 때 보는 것이라, **잘못 그리면 틀린 쪽을 가리킨다** — 아무것도 안 그리는
+ * 것보다 나쁘다. 그래서 그릴 수 없는 축은 그리지 않는다.
+ */
+
+const DRAFT: FigureDraft = { version: 2, figureType: 'ARM', width: 400, height: 400, depth: 1200, detailLevel: 'M' }
+
+const ARM: PartModel = {
+  type: 'figure-part',
+  name: 'arm',
+  primitive: 'cube',
+  left: 150,
+  top: 150,
+  width: 100,
+  height: 100,
+  zPos: 200,
+  depth: 500,
+  token: 'palette.primary'
+}
+
+const joint = (over: Partial<FigureJoint> = {}): FigureJoint => ({
+  name: 'arm-joint',
+  child: 'arm',
+  type: 'revolute',
+  origin: { x: 0, y: 200, z: 0 },
+  axis: { x: 0, y: 1, z: 0 },
+  limits: { min: -90, max: 90 },
+  ...over
+})
+
+/** 부채꼴 점들이 도는 각. 0 도에서 시작해 어디까지 벌어졌나. */
+function angles(path: { x: number; y: number }[]) {
+  const arc = path.filter(point => Math.hypot(point.x, point.y) > 1)
+  return arc.map(point => Math.round((Math.atan2(point.y, point.x) * 180) / Math.PI))
+}
+
+describe('관절 부채꼴', () => {
+  it('축 벡터를 이름으로 옮긴다', () => {
+    assert.equal(axisName({ x: 0, y: 1, z: 0 }), '+y')
+    assert.equal(axisName({ x: -1, y: 0, z: 0 }), '-x')
+    assert.equal(axisName({ x: 0, y: 0, z: 1 }), '+z')
+  })
+
+  it('비스듬한 축은 이름이 없고, 그리지도 않는다 — 아무 쪽이나 고르면 틀린 쪽을 가리킨다', () => {
+    const slanted = { x: 0.7, y: 0.7, z: 0 }
+    assert.equal(axisName(slanted), undefined)
+    assert.equal(gizmoPart(joint({ axis: slanted }), ARM, DRAFT), undefined)
+  })
+
+  it('가동 범위만큼 벌어지고, 가운데 점이 하나 있다', () => {
+    const part = gizmoPart(joint(), ARM, DRAFT)!
+    const path = part.path!
+
+    assert.equal(part.name, JOINT_GIZMO)
+    assert.deepEqual(path[0], { x: 0, y: 0 }, '부채꼴은 가운데에서 시작한다')
+
+    const turned = angles(path)
+    const span = Math.abs(turned[turned.length - 1]! - turned[0]!)
+    assert.equal(span, 180, '−90 에서 90 까지면 180 도 벌어진다')
+  })
+
+  it('무한 회전은 온전한 원이라 가운데 점이 없다', () => {
+    const part = gizmoPart(joint({ type: 'continuous', limits: undefined }), ARM, DRAFT)!
+    const path = part.path!
+
+    assert.ok(path.every(point => Math.hypot(point.x, point.y) > 1), '가운데 점이 없다')
+    assert.ok(path.length >= 60, '한 바퀴를 6도씩 그린다')
+  })
+
+  it('반지름은 도는 부품의 크기를 따라간다 — 부품보다 작으면 무엇이 도는지 안 읽힌다', () => {
+    const big = gizmoPart(joint(), ARM, DRAFT)!
+    const small = gizmoPart(joint(), { ...ARM, width: 40, height: 40, depth: 40 }, DRAFT)!
+
+    assert.equal(big.width, 2 * Math.round(500 * 0.6))
+    assert.equal(small.width, 2 * 60, '작은 부품에도 눈에 보이는 최소 크기가 있다')
+  })
+
+  it('관절의 기준점에 선다', () => {
+    const part = gizmoPart(joint({ origin: { x: 50, y: 300, z: -20 } }), ARM, DRAFT)!
+    /* 저작면은 왼쪽 위 기준이고 z 는 밑면이다. 기준점이 가운데로 가야 맞다. */
+    assert.equal(part.left + part.width / 2, DRAFT.width / 2 + 50)
+    assert.equal(part.top + part.height / 2, DRAFT.height / 2 - 20)
+    assert.equal(part.zPos + part.depth / 2, 300)
+  })
+
+  it('저작면에만 있고, 씬이 집지 않는다', () => {
+    const part = gizmoPart(joint(), ARM, DRAFT)!
+    assert.equal(part.locked, true)
+    assert.equal(part.transparent, true)
+  })
+
+  /*
+   * 가리키는 쪽이 맞나 — **이것이 이 부채꼴의 전부다.**
+   *
+   * 반대로 벌어진 부채꼴은 없느니만 못하다. 저작자가 그것을 보고 축을 고르기 때문이다. 축마다
+   * 씬의 회전과 단면의 각이 도는 쪽이 갈려서, 여섯 축을 하나씩 런타임이 도는 식(로드리게스)과
+   * 맞대 본다.
+   */
+  describe('벌어진 쪽이 실제로 도는 쪽과 같다', () => {
+    const AXES: [string, { x: number; y: number; z: number }][] = [
+      ['+x', { x: 1, y: 0, z: 0 }],
+      ['-x', { x: -1, y: 0, z: 0 }],
+      ['+y', { x: 0, y: 1, z: 0 }],
+      ['-y', { x: 0, y: -1, z: 0 }],
+      ['+z', { x: 0, y: 0, z: 1 }],
+      ['-z', { x: 0, y: 0, z: -1 }]
+    ]
+
+    /** 로드리게스 — 런타임이 관절을 돌리는 식(`setFromAxisAngle`)과 같은 회전이다. */
+    function turned(v: { x: number; y: number; z: number }, axis: { x: number; y: number; z: number }, degrees: number) {
+      const t = (degrees * Math.PI) / 180
+      const c = Math.cos(t)
+      const s = Math.sin(t)
+      const dot = axis.x * v.x + axis.y * v.y + axis.z * v.z
+      const cross = {
+        x: axis.y * v.z - axis.z * v.y,
+        y: axis.z * v.x - axis.x * v.z,
+        z: axis.x * v.y - axis.y * v.x
+      }
+      return {
+        x: v.x * c + cross.x * s + axis.x * dot * (1 - c),
+        y: v.y * c + cross.y * s + axis.y * dot * (1 - c),
+        z: v.z * c + cross.z * s + axis.z * dot * (1 - c)
+      }
+    }
+
+    /** 단면의 점을 부품 회전까지 태워 figure 좌표로. 단면은 부품의 x–z 평면에 눕는다. */
+    function inFigure(part: PartModel, point: { x: number; y: number }) {
+      const v = { x: point.x, y: 0, z: point.y }
+      const rx = part.rotationX ?? 0
+      const rz = part.rotationY ?? 0
+      const afterZ = { x: v.x * Math.cos(rz) - v.y * Math.sin(rz), y: v.x * Math.sin(rz) + v.y * Math.cos(rz), z: v.z }
+      return { x: afterZ.x, y: afterZ.y * Math.cos(rx) - afterZ.z * Math.sin(rx), z: afterZ.y * Math.sin(rx) + afterZ.z * Math.cos(rx) }
+    }
+
+    for (const [name, axis] of AXES) {
+      it(`${name} 축`, () => {
+        const limits = { min: -90, max: 90 }
+        const part = gizmoPart(joint({ axis, limits }), ARM, DRAFT)!
+        /* 가운데 점 하나에 호가 이어진다. 한 바퀴가 아니면 늘 그렇다. */
+        const arc = part.path!.slice(1)
+        const at = (degrees: number) =>
+          inFigure(part, arc[Math.round(((degrees - limits.min) / (limits.max - limits.min)) * (arc.length - 1))]!)
+
+        /* 조각이 6 도씩이라 48 도가 점 하나에 정확히 떨어진다 — 사이 값을 쓰면 반올림이 섞인다. */
+        const zero = at(0)
+        const swung = at(48)
+        const runtime = turned(zero, axis, 48)
+        const flipped = turned(zero, axis, -48)
+
+        const off = Math.hypot(swung.x - runtime.x, swung.y - runtime.y, swung.z - runtime.z)
+        const offFlipped = Math.hypot(swung.x - flipped.x, swung.y - flipped.y, swung.z - flipped.z)
+
+        assert.ok(off < 0.5, `${name}: 부채꼴이 ${off.toFixed(1)}mm 어긋난다 — 반대로 재면 ${offFlipped.toFixed(1)}mm`)
+      })
+    }
+  })
+
+  it('수평축 관절은 눕는다 — 도는 평면이 세로다', () => {
+    const part = gizmoPart(joint({ axis: { x: 1, y: 0, z: 0 } }), ARM, DRAFT)!
+    /* 씬은 라디안을 쓴다. z 90 도가 `rotationY` 로 간다(`figure-source.ts`). */
+    assert.equal(Math.round(((part.rotationY ?? 0) * 180) / Math.PI), 90)
+  })
+})

package/test/pose-defaults.test.ts

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { poseAsDefaults, poseChanges } from '../client/modeller/pose-defaults.ts'
+import type { FigureDraft } from '../client/modeller/figure-source.ts'
+
+/*
+ * 미리보기에서 세운 자세를 기본값으로 앉힌다.
+ *
+ * 관절 도형의 휴지 자세(값 0)는 곧게 선 기둥이라, 기본값이 없으면 목록에서도 도면에서도 그
+ * 모양으로 선다. 옮겨 적는 일을 손으로 하면 여섯 축에 여섯 번이고, 옮기는 사이 화면의 자세와
+ * 적은 수가 갈린다.
+ */
+
+const DRAFT: FigureDraft = {
+  version: 2,
+  figureType: 'ARM',
+  width: 900,
+  height: 900,
+  depth: 1900,
+  detailLevel: 'L',
+  parameters: [
+    { name: 'shoulder', range: { unit: 'deg', min: -120, max: 120 }, default: 0, clip: { channels: [] } },
+    { name: 'elbow', range: { unit: 'deg', min: -150, max: 150 }, default: 0, clip: { channels: [] } },
+    /* 기본값을 안 적은 파라미터. 형식은 그때 범위의 처음에 선다. */
+    { name: 'hoist', range: { unit: 'mm', min: 0, max: 1800 }, clip: { channels: [] } }
+  ]
+}
+
+describe('이 자세를 기본으로', () => {
+  it('민 것만 앉히고 나머지는 건드리지 않는다', () => {
+    const next = poseAsDefaults(DRAFT, { shoulder: -35 })
+
+    assert.equal(next.parameters![0]!.default, -35)
+    assert.equal(next.parameters![1], DRAFT.parameters![1], '안 민 파라미터는 같은 객체 그대로다')
+    assert.equal(next.parameters![2], DRAFT.parameters![2])
+  })
+
+  it('이미 그 값이면 초안을 그대로 돌려준다 — 고친 것이 없는데 「저장 안 됨」이 붙지 않게', () => {
+    assert.equal(poseAsDefaults(DRAFT, { shoulder: 0 }), DRAFT)
+    assert.equal(poseAsDefaults(DRAFT, {}), DRAFT)
+    /* 기본값을 안 적은 파라미터는 범위의 처음에 서 있다. 그 값을 다시 적지 않는다. */
+    assert.equal(poseAsDefaults(DRAFT, { hoist: 0 }), DRAFT)
+  })
+
+  it('기본값을 안 적었던 파라미터에도 앉는다', () => {
+    const next = poseAsDefaults(DRAFT, { hoist: 1200 })
+    assert.equal(next.parameters![2]!.default, 1200)
+  })
+
+  it('범위 밖은 끝에서 문다 — 다른 길로 들어온 값도 형식을 지나야 한다', () => {
+    const next = poseAsDefaults(DRAFT, { elbow: 400 })
+    assert.equal(next.parameters![1]!.default, 150)
+  })
+
+  it('수가 아닌 값은 안 말한 것으로 친다', () => {
+    for (const bad of [NaN, Infinity, undefined as unknown as number]) {
+      assert.equal(poseAsDefaults(DRAFT, { shoulder: bad }), DRAFT, String(bad))
+    }
+  })
+
+  it('무엇이 달라지는지 먼저 말할 수 있다 — 단추를 띄울지 이것으로 정한다', () => {
+    assert.deepEqual(poseChanges(DRAFT, { shoulder: -35, elbow: 0 }), [{ name: 'shoulder', from: 0, to: -35 }])
+    assert.deepEqual(poseChanges(DRAFT, { shoulder: 0 }), [])
+    assert.deepEqual(poseChanges(undefined, { shoulder: -35 }), [])
+  })
+
+  it('없는 파라미터 이름은 무시한다 — 후보를 보다 남은 값이 섞여도 초안을 늘리지 않는다', () => {
+    assert.equal(poseAsDefaults(DRAFT, { 'no-such-thing': 42 }), DRAFT)
+  })
+})

package/test/preview-board-depth.test.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { previewBoardDepth } from '../client/modeller/figure-view.ts'
+
+describe('preview board depth', () => {
+  it('a floor figure gets room for its tallest instance, not the ceiling', () => {
+    // AGV: base 460 tall, shown up to twice. The board was 4400 and the camera aimed at 2200.
+    assert.equal(previewBoardDepth({ placement: 'floor', base: { y: 460 } }, 4000, 2), 1012)
+  })
+
+  it('a figure with no placement stands on the floor', () => {
+    assert.equal(previewBoardDepth({ base: { y: 460 } }, 4000, 2), 1012)
+  })
+
+  it('a center figure has no default height, so it stands on the floor too', () => {
+    assert.equal(previewBoardDepth({ placement: 'center', base: { y: 460 } }, 4000, 2), 1012)
+  })
+
+  it('a ceiling figure gets room up to the ceiling it hangs from', () => {
+    assert.equal(previewBoardDepth({ placement: 'ceiling', base: { y: 460 } }, 4000, 2), 4400)
+  })
+
+  it('a ceiling figure taller than the ceiling still fits', () => {
+    assert.equal(previewBoardDepth({ placement: 'ceiling', base: { y: 2500 } }, 4000, 2), 5500)
+  })
+})

package/test/scene-budget.test.ts

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { capacityFrom, MEASURED, SCENE_BUDGET } from '../client/modeller/scene-budget.ts'
+
+/*
+ * 「몇 개까지 편한가」의 분모.
+ *
+ * 이 수는 **잰 값이다**(2026-09-18, Apple M5). 시험이 지키는 것은 셈이 아니라 그 사실이다 —
+ * 분모가 조용히 목표치로 돌아가거나, 잰 기계와 날짜가 화면에서 빠지면 사람이 어디서나 참인
+ * 수로 읽는다.
+ */
+
+describe('한 화면이 감당하는 양', () => {
+  it('분모는 화면에 보이는 부품 묶음이고, 잰 기계와 날짜를 달고 있다', () => {
+    assert.equal(SCENE_BUDGET.groupsOnScreen, 4000)
+    assert.equal(MEASURED.gpu, 'Apple M5')
+    assert.equal(MEASURED.on, '2026-09-18')
+    assert.equal(MEASURED.fps, 60)
+  })
+
+  it('묶음으로 갈리면 묶음 수로 나눈다 — 그림자를 다시 곱하지 않는다', () => {
+    /*
+      실측이 그림자를 켠 채 잰 값이라 배수가 이미 안에 있다. 전에는 여기서 2 를 곱했고,
+      그 곱을 남겨 두면 같은 값을 두 번 세어 개수가 절반으로 나온다.
+    */
+    const robot = capacityFrom(9, 200)!
+    assert.equal(robot.bound, 'groups')
+    assert.equal(robot.per, 9)
+    assert.equal(robot.instances, Math.floor(4000 / 9))
+  })
+
+  it('삼각형이 먼저 차면 그쪽으로 갈린다', () => {
+    const heavy = capacityFrom(2, 100_000)!
+    assert.equal(heavy.bound, 'triangles')
+    assert.equal(heavy.instances, 5)
+  })
+
+  it('잴 것이 없으면 답하지 않는다 — 「무한히 놓을 수 있다」가 아니다', () => {
+    assert.equal(capacityFrom(0, 0), undefined)
+  })
+
+  /*
+    실측한 두 도형이 이 분모로 되돌아오는지 본다. 분모를 누가 고치면 이 둘이 먼저 어긋난다.
+  */
+  it('잰 두 도형이 잰 수와 맞다', () => {
+    /* 묶음 9 짜리 6 축 로봇: 600 대에서 59.5fps, 700 대에서 56.7fps 였다. */
+    assert.ok(capacityFrom(9, 200)!.instances <= 600, '잰 값보다 많이 놓으라고 하면 안 된다')
+    /* 묶음 2 짜리 컨베이어: 1,600 대에서 59.3fps, 2,500 대에서 36.8fps 였다. */
+    const conveyor = capacityFrom(2, 100)!
+    assert.ok(conveyor.instances >= 1600 && conveyor.instances <= 2500)
+  })
+})

package/translations/en.json

@@ -12,6 +12,7 @@
   "figure.button.delete-figure": "delete",
   "figure.button.discard": "discard",
   "figure.button.duplicate-part": "duplicate",
+  "figure.button.fit-base-to-parts": "fit to parts",
   "figure.button.mirror-x": "mirror X",
   "figure.button.mirror-z": "mirror Z",
   "figure.button.move-part-down": "move down",
@@ -19,6 +20,7 @@
   "figure.button.new-figure": "new figure",
   "figure.button.pivot-clear": "part centre",
   "figure.button.pivot-set": "set",
+  "figure.button.pose-as-default": "make this the default pose",
   "figure.button.preview-fix": "preview fix · {part} {axis} face: {from} → {to}",
   "figure.button.redo": "redo",
   "figure.button.release-figure": "release",
@@ -82,6 +84,7 @@
   "figure.label.axis-scale": "scale",
   "figure.label.axis-scale-short": "scale",
   "figure.label.axis-width": "width",
+  "figure.label.base-box": "base box (mm)",
   "figure.label.budget-animations": "moving parts",
   "figure.label.budget-groups": "material groups",
   "figure.label.budget-parts": "part count",
@@ -96,6 +99,8 @@
   "figure.label.channel-path": "moves",
   "figure.label.channel-pivot": "pivot",
   "figure.label.channel-target": "part",
+  "figure.label.channel-target-joints": "joints",
+  "figure.label.channel-target-parts": "parts",
   "figure.label.channels": "channels",
   "figure.label.clip-name": "clip name",
   "figure.label.clips": "animation (plays over time)",
@@ -137,6 +142,21 @@
   "figure.label.intensity": "intensity",
   "figure.label.interpolation-linear": "smooth",
   "figure.label.interpolation-step": "stepped",
+  "figure.label.joint": "joint",
+  "figure.label.joint-axis": "axis",
+  "figure.label.joint-limit-max": "max",
+  "figure.label.joint-limit-min": "min",
+  "figure.label.joint-limits-deg": "limits (degrees)",
+  "figure.label.joint-limits-mm": "limits (mm)",
+  "figure.label.joint-origin": "origin",
+  "figure.label.joint-parent": "attached to",
+  "figure.label.joint-parent-none": "none (figure frame)",
+  "figure.label.joint-type": "movement",
+  "figure.label.joint-type-continuous": "turn without limits",
+  "figure.label.joint-type-none": "fixed",
+  "figure.label.joint-type-prismatic": "slide",
+  "figure.label.joint-type-revolute": "turn within limits",
+  "figure.label.joint-value": "joint value",
   "figure.label.keep-round": "section",
   "figure.label.key-at": "at (s)",
   "figure.label.key-at-value": "at (0–1)",
@@ -245,6 +265,8 @@
   "figure.label.triangles": "triangles",
   "figure.label.triangles-at-100": "triangles for 100",
   "figure.label.triangles-at-10k": "triangles at 10k instances",
+  "figure.label.unit-none": "no unit",
+  "figure.label.unit-type-it": "type it…",
   "figure.label.weight": "drawing cost",
   "figure.label.what-this-does": "what this figure does",
   "figure.text.accepts-anything": "empty means anything",
@@ -261,8 +283,10 @@
   "figure.text.animation-needs-a-named-part": "add a part first.",
   "figure.text.assistant-proposed-a-figure": "the proposal is shown on the right.",
   "figure.text.axes-not-measurable-yet": "left off the chart because they cannot be measured: {axes}. the reasons are below.",
-  "figure.text.bound-by-drawCalls": "draw calls reach the limit first ({per} per instance, {budget} per drawing).",
+  "figure.text.base-box-explained": "The box that sets the scale when the figure is placed on a drawing. A part reaching outside it blocks release. Changing the size leaves the parts where they are.",
+  "figure.text.bound-by-groups": "Part groups fill up first — this figure is {per} groups, and one screen draws {budget} groups at 60fps.",
   "figure.text.bound-by-triangles": "triangles reach the limit first ({per} per instance, {budget} per drawing).",
+  "figure.text.budget-measured-on": "Measured on {gpu}, {on}. A figure standing still costs nothing — only what is on screen and redrawn counts.",
   "figure.text.budget-not-measured-yet": "this target has not been measured yet.",
   "figure.text.cannot-release-now": "cannot be released yet",
   "figure.text.canvas-appears-once-a-part-exists": "pick a shape on the left to add the first part.",
@@ -279,6 +303,7 @@
   "figure.text.change-capabilities": "capabilities",
   "figure.text.change-changed": "a changed part",
   "figure.text.change-detail": "the detail level",
+  "figure.text.change-joints": "joints",
   "figure.text.change-placement": "placement",
   "figure.text.change-removed": "a part being removed",
   "figure.text.change-styleKit": "the style kit",
@@ -290,6 +315,7 @@
   "figure.text.clip-needs-a-name": "enter a name.",
   "figure.text.collapse-parts-pane": "collapse the part list",
   "figure.text.collapse-properties-pane": "collapse the property pane",
+  "figure.text.contract-not-compared": "Could not check whether this change breaks what is already placed — {why}",
   "figure.text.coordinate-ground-explained": "draws the origin and a grid on the floor",
   "figure.text.delete-figure-confirm": "delete {name}? drawings already using this type will no longer find it.",
   "figure.text.designate-in-properties": "nothing designated yet. select a part and set its role in the properties tab.",
@@ -306,6 +332,7 @@
   "figure.text.figure-type-example": "e.g. OHT, AGV_LIFTER",
   "figure.text.figure-type-placeholder": "Figure type identifier (e.g. OHT)",
   "figure.text.find-by-this-tag": "find by this tag",
+  "figure.text.fit-base-explained": "Shrinks the box to the smallest one holding every part. The centre stays put, so a part sitting off-centre leaves room on the other side.",
   "figure.text.fits-n-instances": "up to {n}",
   "figure.text.floor-explained": "overlaps the coordinate ground, so it is usually off",
   "figure.text.follow-camera-explained": "turn off to fix the shadow direction",
@@ -316,9 +343,16 @@
   "figure.text.hemisphere-light-explained": "even light from sky and ground. it brightens shaded faces.",
   "figure.text.hide-all-parts": "hide all",
   "figure.text.hide-this-part": "hide this part while you work. not saved",
-  "figure.text.how-many-fit": "how many fit on one drawing without slowing it down",
+  "figure.text.how-many-fit": "how many can be on screen before it slows down",
   "figure.text.instances-unit": "instances",
   "figure.text.interpolation-explained": "how the gap between keys is filled.",
+  "figure.text.joint-channel-value-deg": "key values are joint angles in degrees.",
+  "figure.text.joint-channel-value-mm": "key values are joint travel in mm.",
+  "figure.text.joint-driven-by": "parameter \"{name}\" moves this joint. check it in the preview.",
+  "figure.text.joint-explained": "when the part it is attached to moves, this part moves with it. a joint sets the axis this part turns about or slides along relative to that part, and its limits. a parameter created with the joint sets its value.",
+  "figure.text.joint-limits-must-include-zero": "the limits must include 0. the pose as drawn is 0.",
+  "figure.text.joint-not-driven": "no parameter moves this joint. add one in the animation tab.",
+  "figure.text.joint-value-beyond-limits": "outside the joint limits.",
   "figure.text.keep-round-cost": "1 draw call",
   "figure.text.keep-round-merged": "merged into a group",
   "figure.text.keep-round-off": "off",
@@ -368,6 +402,7 @@
   "figure.text.picked-changes-do-not-validate": "the selected changes do not make a valid figure",
   "figure.text.pivot-defaults-to-the-part-centre": "left unset, the part turns about its own centre. coordinates are local to the part.",
   "figure.text.placement-explained": "sets the anchor plane in 3D scene (floor: AGV/conveyor, ceiling: OHT/hoist, center: sensor/drone).",
+  "figure.text.pose-as-default-explained": "Writes the pose you have set as the parameters’ defaults, so the figure stands like this when nobody gives it a value.",
   "figure.text.preview-blocked-by-errors": "cannot show the preview because of format errors. see the maturity tab for the reason.",
   "figure.text.preview-needs-a-part": "add a part to see how it looks placed on a drawing.",
   "figure.text.proposal-feedback-note": "optional note for the next suggestion (this session only)",