@things-factory/figure-ui 10.1.28 → 10.1.29

package/dist-client/types.d.ts

@@ -81,6 +81,8 @@ export interface NewFigure {
  * 찾으므로, 바꾸면 그 도면이 빈 화면이 된다.
  */
 export interface FigurePatch {
+    /** 발행 전 초안에서만 받는다 — 발행된 뒤에는 문이 거절한다(ADR-0063 결정 4). */
+    type?: string;
     name?: string;
     description?: string;
     category?: string;

package/dist-client/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../client/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * 화면이 다루는 모양.\n *\n * 정본 형식(`FigureSource`)의 타입은 **여기서 다시 정의하지 않는다** —\n * `@hatiolab/figure-model` 에서 가져온다. 두 벌이면 갈리고, 갈리면 화면이 서버가\n * 거절할 것을 만들어 낸다.\n */\nexport type { FigureSource, FigureBlueprint, FigurePart, ErrorCode, ViolationCode } from '@hatiolab/figure-model'\n\n/** 서버가 돌려주는 Figure 한 벌. `source` 는 저작면에서만 받는다. */\nexport interface Figure {\n  id: string\n  /** 컴포넌트 타입 이름. **만든 뒤에 고칠 수 없다.** */\n  type: string\n  name: string\n  description?: string\n  /** 분류 하나 — 팔레트에서 묶어 보이는 기준. */\n  category?: string\n  /** 태그 여럿 — 분류로는 못 하는 찾기. */\n  tags?: string[]\n  state?: 'draft' | 'released'\n  /** 재활용 점수 0~100. 서버가 정본에서 계산한다 — 화면이 보내는 값이 아니다. */\n  score?: number\n  triangles?: number\n  groups?: number\n  thumbnail?: string\n  thumbnailUpdatedAt?: string\n  updatedAt?: string\n  updater?: { id: string; name: string }\n  /** `FigureSource` JSON 문자열. 목록 질의에는 실려 오지 않는다. */\n  source?: string\n  properties?: string\n  version?: number\n}\n\n/**\n * 발행된 판 하나.\n *\n * 저작 중 저장은 여기 오지 않는다 — 판본은 발행에서만 생긴다.\n */\nexport interface FigureVersion {\n  version: number\n  /** 발행하며 남긴 말. */\n  comment?: string\n  state?: 'draft' | 'released'\n  updatedAt?: string\n  updater?: { id: string; name: string }\n  score?: number\n  triangles?: number\n  groups?: number\n}\n\nexport interface FigureListResult {\n  items: Figure[]\n  total: number\n}\n\n/**\n * 새 Figure.\n *\n * `score`·`triangles`·`groups` 가 없다 — **서버가 정본에서 계산한다.** 화면이 보내면\n * 거짓이 들어오고 목록이 실물과 다른 것을 보여 준다.\n */\nexport interface NewFigure {\n  type: string\n  name: string\n  description?: string\n  category?: string\n  tags?: string[]\n  source: string\n  properties?: string\n  state?: 'draft' | 'released'\n  thumbnail?: string\n}\n\n/**\n * 수정.\n *\n * `type` 이 없다 — 저장되는 식별자라 고칠 수 없다. 배치된 도면이 그 이름으로 타입을\n * 찾으므로, 바꾸면 그 도면이 빈 화면이 된다.\n */\nexport interface FigurePatch {\n  name?: string\n  description?: string\n  category?: string\n  /** 빈 배열은 「전부 지운다」, 안 주는 것은 「건드리지 않는다」. */\n  tags?: string[]\n  source?: string\n  properties?: string\n  state?: 'draft' | 'released'\n  thumbnail?: string\n}\n\n/** 검증 결과 한 줄. 코드는 figure-model 의 것을 그대로 쓴다. */\nexport interface FigureFinding {\n  code: string\n  message: string\n  at?: string\n}\n\n/**\n * 저작 보조가 낸 후보.\n *\n * **정본이 아니다.** 저작자가 보고 받아야 정본이 된다 — 서버는 저장하지 않고\n * 돌려주기만 한다.\n */\nexport interface FigureProposal {\n  /** 후보 정본. JSON 문자열이다 — 화면이 파싱한다. */\n  source: string\n  score: number\n  grade: string\n  triangles: number\n  /** 재질 묶음 = 인스턴스 하나가 무는 draw call. */\n  groups: number\n  /** Rule-based review of measurable design concerns; it is not an aesthetic verdict. */\n  quality: {\n    status: 'ready' | 'review'\n    summary: string\n    findings: Array<{ dimension: string; code: string; message: string }>\n    visualRegions: number\n    visualCoverage: number\n    visualReadability: number\n  }\n  /** 형식은 맞으나 정책을 넘은 것. 막지 않는다 — 저작자가 정한다. */\n  violations: FigureFinding[]\n  /** 몇 번 만에 됐나. 진단용이다. */\n  attempts: number\n}\n\n/** 사람이 후보를 수락하거나 버릴 때 직접 남긴 현재 저작 세션의 참고 신호. */\nexport interface ProposalFeedback {\n  outcome: 'accepted' | 'discarded'\n  selectedChanges: number\n  totalChanges: number\n  note?: string\n  grade?: string\n  quality?: { status?: 'ready' | 'review'; findingCodes?: string[] }\n}\n\n/**\n * 발행 판정 한 줄.\n *\n * `FigureFinding` 과 달리 **`blocking` 이 있다.** 저장 쪽 발견은 정의상 막지 않는 것들이고,\n * 발행 판정은 막는 것과 알리는 것을 함께 내므로 어느 쪽인지를 값이 스스로 말한다 — 코드를 보고\n * 화면이 다시 분류하면 규칙이 두 벌이 된다.\n */\n/** One reversible anchor edit the sizing gate has measured against this exact source. */\nexport interface FigureGateFix {\n  findingWay: string\n  part: string\n  axis: 'x' | 'y' | 'z'\n  from?: string\n  to: 'min' | 'center' | 'max' | 'span'\n  resolved: number\n  /** All blocking sizing cases clear after this exact edit was remeasured server-side. */\n  safe: boolean\n}\n\nexport interface FigureGateFinding {\n  code: string\n  message: string\n  /** 왜 그것이 문제인가 — 사람이 무엇을 보게 되나. */\n  why?: string\n  /** 무엇을 바꾸면 되나 — 부품 이름과 값으로. */\n  how?: string\n  /** 갈라진 부품 이름들, 또는 정본 안의 경로. */\n  at?: string\n  /** Candidate edits; the UI must preview and explicitly apply these, never auto-save them. */\n  fixes?: FigureGateFix[]\n  blocking: boolean\n}\n\n/** 발행해도 되나. `blocked` 면 서버가 거절한다. */\nexport interface FigureInspection {\n  blocked: boolean\n  findings: FigureGateFinding[]\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../client/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * 화면이 다루는 모양.\n *\n * 정본 형식(`FigureSource`)의 타입은 **여기서 다시 정의하지 않는다** —\n * `@hatiolab/figure-model` 에서 가져온다. 두 벌이면 갈리고, 갈리면 화면이 서버가\n * 거절할 것을 만들어 낸다.\n */\nexport type { FigureSource, FigureBlueprint, FigurePart, ErrorCode, ViolationCode } from '@hatiolab/figure-model'\n\n/** 서버가 돌려주는 Figure 한 벌. `source` 는 저작면에서만 받는다. */\nexport interface Figure {\n  id: string\n  /** 컴포넌트 타입 이름. **만든 뒤에 고칠 수 없다.** */\n  type: string\n  name: string\n  description?: string\n  /** 분류 하나 — 팔레트에서 묶어 보이는 기준. */\n  category?: string\n  /** 태그 여럿 — 분류로는 못 하는 찾기. */\n  tags?: string[]\n  state?: 'draft' | 'released'\n  /** 재활용 점수 0~100. 서버가 정본에서 계산한다 — 화면이 보내는 값이 아니다. */\n  score?: number\n  triangles?: number\n  groups?: number\n  thumbnail?: string\n  thumbnailUpdatedAt?: string\n  updatedAt?: string\n  updater?: { id: string; name: string }\n  /** `FigureSource` JSON 문자열. 목록 질의에는 실려 오지 않는다. */\n  source?: string\n  properties?: string\n  version?: number\n}\n\n/**\n * 발행된 판 하나.\n *\n * 저작 중 저장은 여기 오지 않는다 — 판본은 발행에서만 생긴다.\n */\nexport interface FigureVersion {\n  version: number\n  /** 발행하며 남긴 말. */\n  comment?: string\n  state?: 'draft' | 'released'\n  updatedAt?: string\n  updater?: { id: string; name: string }\n  score?: number\n  triangles?: number\n  groups?: number\n}\n\nexport interface FigureListResult {\n  items: Figure[]\n  total: number\n}\n\n/**\n * 새 Figure.\n *\n * `score`·`triangles`·`groups` 가 없다 — **서버가 정본에서 계산한다.** 화면이 보내면\n * 거짓이 들어오고 목록이 실물과 다른 것을 보여 준다.\n */\nexport interface NewFigure {\n  type: string\n  name: string\n  description?: string\n  category?: string\n  tags?: string[]\n  source: string\n  properties?: string\n  state?: 'draft' | 'released'\n  thumbnail?: string\n}\n\n/**\n * 수정.\n *\n * `type` 이 없다 — 저장되는 식별자라 고칠 수 없다. 배치된 도면이 그 이름으로 타입을\n * 찾으므로, 바꾸면 그 도면이 빈 화면이 된다.\n */\nexport interface FigurePatch {\n  /** 발행 전 초안에서만 받는다 — 발행된 뒤에는 문이 거절한다(ADR-0063 결정 4). */\n  type?: string\n  name?: string\n  description?: string\n  category?: string\n  /** 빈 배열은 「전부 지운다」, 안 주는 것은 「건드리지 않는다」. */\n  tags?: string[]\n  source?: string\n  properties?: string\n  state?: 'draft' | 'released'\n  thumbnail?: string\n}\n\n/** 검증 결과 한 줄. 코드는 figure-model 의 것을 그대로 쓴다. */\nexport interface FigureFinding {\n  code: string\n  message: string\n  at?: string\n}\n\n/**\n * 저작 보조가 낸 후보.\n *\n * **정본이 아니다.** 저작자가 보고 받아야 정본이 된다 — 서버는 저장하지 않고\n * 돌려주기만 한다.\n */\nexport interface FigureProposal {\n  /** 후보 정본. JSON 문자열이다 — 화면이 파싱한다. */\n  source: string\n  score: number\n  grade: string\n  triangles: number\n  /** 재질 묶음 = 인스턴스 하나가 무는 draw call. */\n  groups: number\n  /** Rule-based review of measurable design concerns; it is not an aesthetic verdict. */\n  quality: {\n    status: 'ready' | 'review'\n    summary: string\n    findings: Array<{ dimension: string; code: string; message: string }>\n    visualRegions: number\n    visualCoverage: number\n    visualReadability: number\n  }\n  /** 형식은 맞으나 정책을 넘은 것. 막지 않는다 — 저작자가 정한다. */\n  violations: FigureFinding[]\n  /** 몇 번 만에 됐나. 진단용이다. */\n  attempts: number\n}\n\n/** 사람이 후보를 수락하거나 버릴 때 직접 남긴 현재 저작 세션의 참고 신호. */\nexport interface ProposalFeedback {\n  outcome: 'accepted' | 'discarded'\n  selectedChanges: number\n  totalChanges: number\n  note?: string\n  grade?: string\n  quality?: { status?: 'ready' | 'review'; findingCodes?: string[] }\n}\n\n/**\n * 발행 판정 한 줄.\n *\n * `FigureFinding` 과 달리 **`blocking` 이 있다.** 저장 쪽 발견은 정의상 막지 않는 것들이고,\n * 발행 판정은 막는 것과 알리는 것을 함께 내므로 어느 쪽인지를 값이 스스로 말한다 — 코드를 보고\n * 화면이 다시 분류하면 규칙이 두 벌이 된다.\n */\n/** One reversible anchor edit the sizing gate has measured against this exact source. */\nexport interface FigureGateFix {\n  findingWay: string\n  part: string\n  axis: 'x' | 'y' | 'z'\n  from?: string\n  to: 'min' | 'center' | 'max' | 'span'\n  resolved: number\n  /** All blocking sizing cases clear after this exact edit was remeasured server-side. */\n  safe: boolean\n}\n\nexport interface FigureGateFinding {\n  code: string\n  message: string\n  /** 왜 그것이 문제인가 — 사람이 무엇을 보게 되나. */\n  why?: string\n  /** 무엇을 바꾸면 되나 — 부품 이름과 값으로. */\n  how?: string\n  /** 갈라진 부품 이름들, 또는 정본 안의 경로. */\n  at?: string\n  /** Candidate edits; the UI must preview and explicitly apply these, never auto-save them. */\n  fixes?: FigureGateFix[]\n  blocking: boolean\n}\n\n/** 발행해도 되나. `blocked` 면 서버가 거절한다. */\nexport interface FigureInspection {\n  blocked: boolean\n  findings: FigureGateFinding[]\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-ui",
-  "version": "10.1.28",
+  "version": "10.1.29",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -26,8 +26,8 @@
     "clean": "npm run clean:server && npm run clean:client"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.21",
-    "@hatiolab/things-scene": "^10.1.14",
+    "@hatiolab/figure-model": "^0.1.27",
+    "@hatiolab/things-scene": "^10.1.22",
     "@material/web": "^2.0.0",
     "@operato/data-grist": "^10.0.0",
     "@operato/graphql": "^10.0.0",
@@ -37,8 +37,8 @@
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.0.0",
-    "@things-factory/figure-service": "^10.1.28",
+    "@things-factory/figure-service": "^10.1.29",
     "three": "^0.185.1"
   },
-  "gitHead": "3a260a0f79bc6b41a692a103955bfcc541aff60e"
+  "gitHead": "e6bf9dec003fe5e794746aaeb5852b3b50478232"
 }

package/test/angle-dial.test.ts

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { dialShape } from '../client/modeller/angle-dial.ts'
+
+/*
+ * 막대 옆의 각도 눈.
+ *
+ * 관절이 돌았다는 것을 3D 안에서만 보이려 했다가 잰 값에 막혔다 — 미리보기의 부품에 단 바늘이
+ * 4 × 2 픽셀이었다. 여덟 대를 한 화면에 세우는 자리라 한 대가 20 픽셀쯤이고, 그 안의 표시는
+ * 무엇이든 몇 픽셀을 못 넘는다. 그래서 각은 3D 의 배율에서 떼어 이 눈이 읽는다.
+ */
+
+const near = (got: number, want: number, why: string) => assert.ok(Math.abs(got - want) < 0.05, `${why}: ${got}`)
+
+describe('각도 눈', () => {
+  it('0 도는 위를 가리킨다', () => {
+    const dial = dialShape(-90, 90, 0)
+
+    near(dial.needle.x, dial.centre.x, '가운데에서 안 벗어난다')
+    near(dial.needle.y, dial.centre.y - dial.radius, '위로 반지름만큼')
+  })
+
+  it('양수는 시계 방향이다 — 화면의 각과 같은 쪽', () => {
+    const dial = dialShape(-180, 180, 90)
+
+    near(dial.needle.x, dial.centre.x + dial.radius, '오른쪽')
+    near(dial.needle.y, dial.centre.y, '높이는 가운데')
+  })
+
+  it('음수는 반대쪽이다', () => {
+    const dial = dialShape(-180, 180, -90)
+    near(dial.needle.x, dial.centre.x - dial.radius, '왼쪽')
+  })
+
+  it('범위 밖의 값은 범위 끝에 선다 — 밖을 가리키는 바늘은 없는 값을 말한다', () => {
+    const over = dialShape(-90, 90, 200)
+    const under = dialShape(-90, 90, -200)
+
+    assert.deepEqual(over.needle, dialShape(-90, 90, 90).needle)
+    assert.deepEqual(under.needle, dialShape(-90, 90, -90).needle)
+  })
+
+  it('180 도를 넘는 범위는 큰 호로 그린다 — 안 그러면 부채꼴이 반대쪽으로 패인다', () => {
+    const wide = dialShape(-150, 150, 0)
+    const narrow = dialShape(-45, 45, 0)
+
+    assert.ok(/A 9 9 0 1 1/.test(wide.sector), `큰 호: ${wide.sector}`)
+    assert.ok(/A 9 9 0 0 1/.test(narrow.sector), `작은 호: ${narrow.sector}`)
+  })
+
+  it('한 바퀴는 원이다 — 부채꼴의 두 변이 겹쳐 그어지지 않는다', () => {
+    const full = dialShape(-180, 180, 45)
+
+    assert.ok(!full.sector.includes('L'), `변을 긋지 않는다: ${full.sector}`)
+    assert.equal((full.sector.match(/A /g) ?? []).length, 2, '반원 둘로 원을 만든다')
+  })
+})
+
+describe('눈이 화면에 붙어 있다', () => {
+  const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+  it('미리보기의 파라미터 줄이 눈을 그린다', () => {
+    const preview = read('../client/modeller/figure-preview.ts')
+
+    assert.ok(/this\.renderDial\(range, value\)/.test(preview), '막대 옆에 있다')
+    assert.ok(/dialShape\(range\.min, range\.max, value\)/.test(preview), '값으로 그린다')
+  })
+
+  it('각이 아닌 파라미터에는 안 단다', () => {
+    const preview = read('../client/modeller/figure-preview.ts')
+
+    assert.ok(/range\.unit !== 'deg'/.test(preview), 'deg 만')
+  })
+})

package/test/base-box.test.ts

@@ -138,6 +138,17 @@ describe('화면에 붙어 있다', () => {
     assert.ok(/private resizeBase\(draft: FigureDraft, parts: PartModel\[\]\) \{\s*\n\s*this\.recordHistory\('base'\)/.test(page))
   })
 
+  it('발행 전에는 타입 칸이 열려 있다 — 기계가 지은 이름을 고칠 자리가 있어야 한다', () => {
+    const inspector = source('../client/modeller/figure-inspector.ts')
+    const side = source('../client/modeller/figure-side.ts')
+    const page = source('../client/pages/figure-modeller-page.ts')
+
+    /* 판 번호가 0 이면 고칠 수 있다. 「저장됐나」로 가르면 저장하는 순간 굳는다. */
+    assert.ok(/figureVersion \?\? 0\) > 0/.test(inspector), '판 번호로 가른다')
+    assert.ok(/<figure-inspector[\s\S]{0,200}\.figureVersion=/.test(side), '판 번호가 검사기까지 온다')
+    assert.ok(/type: this\.figure\.type/.test(page), '저장할 때 행의 타입도 함께 보낸다')
+  })
+
   it('발행된 도형을 고치는 동안 그 자리에서 말한다', () => {
     const page = source('../client/pages/figure-modeller-page.ts')
     const inspector = source('../client/modeller/figure-inspector.ts')

package/test/expect.ts

@@ -29,6 +29,7 @@ export interface Expectation {
   toBeUndefined(): void
   toBeGreaterThan(expected: number): void
   toBeLessThan(expected: number): void
+  toBeGreaterThanOrEqual(expected: number): void
   toBeLessThanOrEqual(expected: number): void
 }
 
@@ -50,6 +51,7 @@ export function expect(actual: any): Expectation {
     toBeUndefined: () => assert.strictEqual(actual, undefined),
     toBeGreaterThan: expected => assert.ok(actual > expected, `${actual} is not greater than ${expected}`),
     toBeLessThan: expected => assert.ok(actual < expected, `${actual} is not less than ${expected}`),
+    toBeGreaterThanOrEqual: expected => assert.ok(actual >= expected, `${actual} is not >= ${expected}`),
     toBeLessThanOrEqual: expected => assert.ok(actual <= expected, `${actual} is not <= ${expected}`)
   }
 }

package/test/i18n-prefix-guard.test.ts

@@ -105,6 +105,23 @@ test('통째로 부르는 키가 번역 파일에 있다 — 없으면 화면에
   assert.deepEqual(missing, [], `부르는 키가 번역에 없다:\n  ${missing.join('\n  ')}`)
 })
 
+test('★ 한국어를 defaultValue 로 들고 있지 않다 — 번역 파일을 지나지 않는 문구가 된다', () => {
+  const hard: string[] = []
+  for (const path of FILES) {
+    const text = readFileSync(path, 'utf-8')
+    for (const match of text.matchAll(/defaultValue:\s*(['"`])([^'"`]*)\1/g)) {
+      if (/[가-힣]/.test(match[2]!)) hard.push(`${path.slice(CLIENT.length + 1)}  ${match[2]}`)
+    }
+  }
+
+  /*
+    `t(key, { defaultValue })` 는 키가 없을 때 그 값을 그대로 쓴다. 한국어를 적어 두면 다른
+    언어에서도 그 한국어가 뜨고, 번역 파일에 키를 넣어도 아무도 그 자리를 다시 안 본다.
+    ADR-0049 ②.
+  */
+  assert.deepEqual(hard, [], `한국어 defaultValue:\n  ${hard.join('\n  ')}`)
+})
+
 /*
   이어 붙이는 자리는 값을 코드에서 읽어야 알 수 있어 여기서 전수 검사하지 않는다. 대신 **통이
   갈린 짝**을 못 박는다 — 사다리 이름은 `label`, 그 설명은 `text` 다. 한 번 어긋났고, 그때

package/test/joint-needle.test.ts

@@ -0,0 +1,162 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { compile, validate } from '@hatiolab/figure-model'
+import type { FigureSource } from '@hatiolab/figure-model'
+
+import { jointNeedles, NEEDLE } from '../client/modeller/joint-gizmo.ts'
+
+/*
+ * 미리보기에서 관절이 돌았다는 것을 보이게 하는 바늘.
+ *
+ * 이 시험이 지키는 것은 하나다 — **축에서 비켜나 있을 것.** 축 위에 붙으면 대칭인 부품과 같이
+ * 돌면서 같은 그림이 되고, 그러면 바늘을 붙인 뜻이 없어진다. 없는 것보다 나쁘다: 화면에 무엇이
+ * 하나 더 생겼는데 여전히 아무것도 안 움직인다.
+ */
+
+const source = (over: Partial<FigureSource> = {}): FigureSource => ({
+  version: 2,
+  type: 'ARM',
+  base: { x: 400, y: 1200, z: 400 },
+  placement: 'floor',
+  detailLevel: 'M',
+  parts: [
+    {
+      name: 'post',
+      primitive: 'cylinder',
+      transform: { position: { x: 0, y: 100, z: 0 }, size: { x: 200, y: 200, z: 200 } },
+      material: { token: 'palette.dark' }
+    },
+    {
+      name: 'arm',
+      primitive: 'cylinder',
+      transform: { position: { x: 0, y: 400, z: 0 }, size: { x: 120, y: 400, z: 120 } },
+      material: { token: 'palette.primary' },
+      parent: 'post'
+    }
+  ],
+  joints: [
+    {
+      name: 'turn',
+      child: 'arm',
+      type: 'revolute',
+      origin: { x: 0, y: 200, z: 0 },
+      axis: { x: 0, y: 1, z: 0 },
+      limits: { min: -90, max: 90 }
+    }
+  ],
+  ...over
+})
+
+describe('관절 바늘', () => {
+  it('관절이 모는 부품에 자식으로 붙는다 — 그래야 관절이 도는 만큼 같이 돈다', () => {
+    const [needle] = jointNeedles(source())
+
+    assert.equal(needle!.parent, 'arm')
+    assert.equal(needle!.name, `${NEEDLE}turn`)
+  })
+
+  it('축에서 비켜나 선다 — 축 위에 있으면 대칭인 부품과 같은 그림이다', () => {
+    const [needle] = jointNeedles(source())
+    const { position, size } = needle!.transform
+
+    /* y 축으로 도는 관절: 바늘은 x 로 비켜나고 x 로 길다. */
+    assert.ok(position.x > 0, '축에서 비켜났다')
+    assert.equal(position.y, 200, '기준점 높이 그대로')
+    assert.ok(size.x > size.y && size.x > size.z, 'x 로 길다')
+  })
+
+  it('가로축으로 도는 관절은 z 로 비켜난다', () => {
+    const [needle] = jointNeedles(source({ joints: [{ ...source().joints![0]!, axis: { x: 1, y: 0, z: 0 } }] }))
+    const { position, size } = needle!.transform
+
+    assert.ok(position.z > 0)
+    assert.ok(size.z > size.x && size.z > size.y)
+  })
+
+  it('세로축(z)으로 도는 관절은 x 로 비켜난다', () => {
+    const [needle] = jointNeedles(source({ joints: [{ ...source().joints![0]!, axis: { x: 0, y: 0, z: 1 } }] }))
+    assert.ok(needle!.transform.position.x > 0)
+  })
+
+  it('비스듬한 축은 그리지 않는다 — 비켜날 쪽을 못 고른다', () => {
+    const oblique = source({ joints: [{ ...source().joints![0]!, axis: { x: 1, y: 1, z: 0 } }] })
+    assert.deepEqual(jointNeedles(oblique), [])
+  })
+
+  it('길이는 도는 부품에서 온다. 작은 부품에서도 보일 만큼은 된다', () => {
+    const [big] = jointNeedles(source())
+    assert.equal(big!.transform.size.x, Math.round(400 * 0.6))
+
+    const small = source({
+      parts: source().parts.map(part =>
+        part.name === 'arm'
+          ? { ...part, transform: { ...part.transform, size: { x: 10, y: 10, z: 10 } } }
+          : part
+      )
+    })
+    assert.equal(jointNeedles(small)[0]!.transform.size.x, 60)
+  })
+
+  it('굵기는 길이에 견준다 — 8mm 로 고정했더니 미리보기에서 한 픽셀이 안 됐다', () => {
+    const [needle] = jointNeedles(source())
+    const { size } = needle!.transform
+
+    /* 길이 240 짜리 막대는 48 로 두껍다. 부품이 작아도 6 밑으로는 안 내려간다. */
+    assert.equal(size.y, Math.round(size.x / 5))
+    assert.equal(size.z, size.y)
+
+    const small = source({
+      parts: source().parts.map(part =>
+        part.name === 'arm' ? { ...part, transform: { ...part.transform, size: { x: 10, y: 10, z: 10 } } } : part
+      )
+    })
+    assert.equal(jointNeedles(small)[0]!.transform.size.y, Math.max(6, Math.round(60 / 5)))
+  })
+
+  it('관절이 없으면 바늘도 없다', () => {
+    assert.deepEqual(jointNeedles(source({ joints: [] })), [])
+    assert.deepEqual(jointNeedles(source({ joints: undefined })), [])
+  })
+
+  it('바늘을 붙인 형식이 그대로 선다 — 미리보기가 이것을 compile 한다', () => {
+    const shown: FigureSource = { ...source(), parts: [...source().parts, ...jointNeedles(source())] }
+
+    assert.deepEqual(validate(shown).errors, [])
+    assert.doesNotThrow(() => compile(shown))
+  })
+})
+
+/*
+ * 바늘은 **미리보기에만** 있다. 저장 형식으로 새어 나가면 발행된 도형에 없던 막대가 생기고,
+ * 계약 판정에서는 부품이 하나 늘어난 것으로 읽힌다.
+ */
+describe('바늘이 미리보기 밖으로 안 나간다', () => {
+  const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+  it('미리보기가 붙여서 세운다', () => {
+    const preview = read('../client/modeller/figure-preview.ts')
+
+    assert.ok(/jointNeedles\(source\)/.test(preview), '붙인다')
+    assert.ok(/registerFigure\(compile\(shown\)/.test(preview), '붙인 것을 세운다')
+  })
+
+  it('저작면과 저장은 원본 그대로다', () => {
+    const page = read('../client/pages/figure-modeller-page.ts')
+    const canvas = read('../client/modeller/figure-canvas.ts')
+
+    assert.ok(!/jointNeedles/.test(page), '페이지는 바늘을 모른다')
+    assert.ok(!/jointNeedles/.test(canvas), '저작 캔버스는 바늘을 모른다')
+  })
+
+  it('원본 목록을 건드리지 않는다 — 같은 배열에 밀어 넣으면 저장에 들어간다', () => {
+    const original = source()
+    const before = original.parts.length
+    jointNeedles(original)
+
+    assert.equal(original.parts.length, before)
+  })
+})

package/test/part-edits.test.ts

@@ -1,5 +1,7 @@
 import assert from 'node:assert/strict'
 import { describe, it, test } from 'node:test'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 
 import { expect } from './expect.ts'
 
@@ -17,6 +19,7 @@ import {
   niceStep,
   partLimit,
   removePart,
+  roundPart,
   snapPart,
   updatePart
 } from '../client/modeller/part-edits.ts'
@@ -55,6 +58,53 @@ const DECK: PartModel = {
   token: 'palette.primary'
 }
 
+/*
+ * 기즈모에서 온 숫자.
+ *
+ * 화면에서 끌면 씬이 비율을 곱한 값을 돌려준다. 그 값이 그대로 부품에 들어가면 저장 형식에
+ * 소수 넷째 자리가 남고, 크기 칸은 잘려서 보인다.
+ */
+describe('씬에서 온 부품을 밀리미터로 맞춘다', () => {
+  const part = (over: Partial<PartModel> = {}): PartModel => ({ ...DECK, ...over })
+
+  it('끈 크기와 자리를 정수로 맞춘다', () => {
+    const dragged = part({ left: 384.99999999999994, top: 380, zPos: 930, width: 368.98743869823886, height: 140, depth: 722.4180046035418 })
+    const fixed = roundPart(dragged)
+
+    expect(fixed.left).toBe(385)
+    expect(fixed.width).toBe(369)
+    expect(fixed.depth).toBe(722)
+    expect(fixed.top).toBe(380)
+  })
+
+  it('크기는 1 밑으로 안 내려간다 — 0 이면 부피가 사라지고 배율이 0 으로 나뉜다', () => {
+    const tiny = roundPart(part({ width: 0.2, height: 0.4, depth: 0 }))
+    expect(tiny.width).toBe(1)
+    expect(tiny.height).toBe(1)
+    expect(tiny.depth).toBe(1)
+  })
+
+  it('맞춘 값을 다시 맞춰도 같다', () => {
+    const once = roundPart(part({ left: 12.5, width: 7.5 }))
+    expect(roundPart(once)).toEqual(once)
+  })
+
+  it('캔버스가 씬의 변경을 받을 때 그것을 지난다 — 안 부르면 위 넷이 전부 초록인 채로 소수가 남는다', () => {
+    const canvas = readFileSync(fileURLToPath(new URL('../client/modeller/figure-canvas.ts', import.meta.url)), 'utf8')
+
+    assert.ok(/roundPart/.test(canvas), 'import')
+    assert.ok(/this\.tell\('part-changed', \{ name, part: roundPart\(/.test(canvas), '올려 보내기 전에 맞춘다')
+  })
+
+  it('크기·자리 밖의 값은 건드리지 않는다', () => {
+    const kept = roundPart(part({ name: 'arm', token: 'palette.dark', segments: 12, zPos: 3.4 }))
+    expect(kept.name).toBe('arm')
+    expect(kept.token).toBe('palette.dark')
+    expect(kept.segments).toBe(12)
+    expect(kept.zPos).toBe(3)
+  })
+})
+
 describe('부품 생성', () => {
   it('기준 상자의 3분의 1 크기로 생성된다 — 추가하자마자 보여야 한다', () => {
     const part = newPart(DRAFT, [], 'cube')
@@ -98,6 +148,56 @@ describe('부품 생성', () => {
     expect(newPart(DRAFT, [], 'polygon').path).toHaveLength(3)
   })
 
+  /*
+   * 둘째 부품이 어디에 서는가.
+   *
+   * 언제나 바닥 한가운데였을 때, 둘째 부품은 첫 부품 **속에** 들어갔다 — 같은 자리에 같은
+   * 크기라 화면에는 덩어리 하나뿐이고 저작자는 무엇이 늘었는지 못 봤다.
+   */
+  describe('고른 부품 위에 얹는다', () => {
+    /* 갑판을 바닥에 내려 둔다 — 그 위에 3분의 1 짜리가 들어가야 얹는 갈래를 볼 수 있다. */
+    const FLOOR_DECK = { ...DECK, zPos: 0 }
+
+    it('윗면에 서고 발자국이 가운데로 맞는다', () => {
+      const part = newPart(DRAFT, [FLOOR_DECK], 'cube', FLOOR_DECK)
+
+      expect(part.zPos).toBe(FLOOR_DECK.zPos + FLOOR_DECK.depth)
+      // 자리도 크기도 정수로 맞추므로 0.5 까지는 어긋난다
+      const middle = { x: FLOOR_DECK.left + FLOOR_DECK.width / 2, y: FLOOR_DECK.top + FLOOR_DECK.height / 2 }
+      expect(Math.abs(part.left + part.width / 2 - middle.x)).toBeLessThanOrEqual(0.5)
+      expect(Math.abs(part.top + part.height / 2 - middle.y)).toBeLessThanOrEqual(0.5)
+    })
+
+    it('얹으면 상자를 넘을 때는 바닥 한가운데로 간다 — 추가가 발행을 막지 않는다', () => {
+      /* 갑판이 이미 높다: 500 + 200 위에 267 을 더 쌓으면 상자 높이 800 을 넘는다. */
+      const part = newPart(DRAFT, [DECK], 'cube', DECK)
+
+      expect(part.zPos).toBe(0)
+      expect(Math.abs(part.left + part.width / 2 - DRAFT.width / 2)).toBeLessThanOrEqual(0.5)
+    })
+
+    it('가장자리 부품 위에서도 상자 안에 남는다', () => {
+      const corner = { ...DECK, left: 0, top: 0, width: 200, height: 200, zPos: 0, depth: 100 }
+      const part = newPart(DRAFT, [corner], 'cube', corner)
+
+      expect(part.left).toBe(0)
+      expect(part.top).toBe(0)
+      expect(part.left + part.width).toBeLessThanOrEqual(DRAFT.width)
+      expect(part.top + part.height).toBeLessThanOrEqual(DRAFT.height)
+    })
+
+    it('고른 것이 없으면 전과 같이 바닥 한가운데다', () => {
+      const alone = newPart(DRAFT, [DECK], 'cube')
+      expect(alone.zPos).toBe(0)
+      expect(Math.abs(alone.left + alone.width / 2 - DRAFT.width / 2)).toBeLessThanOrEqual(0.5)
+    })
+
+    it('쌓은 둘이 서로 겹치지 않는다 — 이 규칙이 지키는 것이 그것이다', () => {
+      const [, stacked] = addPart(DRAFT, [FLOOR_DECK], 'cylinder', FLOOR_DECK)
+      expect(stacked!.zPos).toBeGreaterThanOrEqual(FLOOR_DECK.zPos + FLOOR_DECK.depth)
+    })
+  })
+
   /*
     화면에서 멀쩡해 보여도 저장이 거부되면 사용자는 이유를 알 수 없다. 새로 만든 부품은
     손대지 않은 상태로도 검증을 통과해야 한다.

package/test/scene-budget.test.ts

@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict'
 import { describe, it } from 'node:test'
 
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import { capacityFrom, MEASURED, SCENE_BUDGET } from '../client/modeller/scene-budget.ts'
 
 /*
@@ -51,3 +55,28 @@ describe('한 화면이 감당하는 양', () => {
     assert.ok(conveyor.instances >= 1600 && conveyor.instances <= 2500)
   })
 })
+
+/*
+ * 놓는 개수로 값을 말하지 않는다 — ADR-0051 ③.
+ *
+ * 보고서에 「100개 기준 draw call」 · 「1만개 기준」이 오래 남아 있었다. 놓는 개수는 값을 치르지
+ * 않는다(가만히 선 도형은 프레임 비용 0, 카메라 밖은 컬링). 치르는 것은 한 화면에 보이는 개수 ×
+ * 그 도형의 묶음 수이고, 그 답은 위의 실측 분모가 한다.
+ */
+describe('놓는 개수 기준 문구가 화면에 없다', () => {
+  const HERE = fileURLToPath(new URL('.', import.meta.url))
+
+  it('보고서가 「N개 기준」 칸을 그리지 않는다', () => {
+    const report = readFileSync(join(HERE, '../client/modeller/figure-report.ts'), 'utf8')
+
+    assert.ok(!/at-100|at-10k/.test(report), '개수 기준 칸')
+    assert.ok(!/costOf\(blueprint, \d/.test(report), '개수를 넣어 셈하지 않는다')
+  })
+
+  it('번역에 그 낱말이 남아 있지 않다', () => {
+    const ko = JSON.parse(readFileSync(join(HERE, '../translations/ko.json'), 'utf8')) as Record<string, string>
+    const left = Object.entries(ko).filter(([key]) => /at-100|at-10k/.test(key))
+
+    assert.deepEqual(left, [])
+  })
+})

package/translations/en.json

@@ -85,8 +85,8 @@
   "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-independent": "independently moved parts",
   "figure.label.budget-parts": "part count",
   "figure.label.budget-surface": "surfaces outside the palette",
   "figure.label.budget-transparent": "transparent materials",
@@ -113,8 +113,6 @@
   "figure.label.distinct-materials": "distinct materials",
   "figure.label.distinct-shapes": "distinct shapes",
   "figure.label.draft": "draft",
-  "figure.label.draw-calls-at-100": "draw calls for 100",
-  "figure.label.draw-calls-at-10k": "draw calls at 10k instances",
   "figure.label.emissive": "emissive",
   "figure.label.emissive-color": "lit color",
   "figure.label.environment": "environment",
@@ -263,8 +261,6 @@
   "figure.label.tools": "align",
   "figure.label.transparent": "transparent",
   "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",
@@ -276,8 +272,6 @@
   "figure.text.already-released-edit-to-release-again": "already released. edit and save to go back to draft, then release again.",
   "figure.text.anchor-explained": "where this part stays as the box grows. two touching parts on different faces drift apart as it grows.",
   "figure.text.anchors-are-not-drawn": "slots and ports are not drawn on a drawing; only the editor shows them.",
-  "figure.text.animated-parts-cost": "each moving part adds one draw call.",
-  "figure.text.animated-parts-over": "over the limit. many of these on one drawing will slow it down.",
   "figure.text.animation-empty-examples": "a turning roller · a sliding door leaf · a rising lift · a blinking beacon.",
   "figure.text.animation-empty-what-it-is": "no motion yet. add a clip to move parts.",
   "figure.text.animation-needs-a-named-part": "add a part first.",
@@ -344,6 +338,8 @@
   "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 can be on screen before it slows down",
+  "figure.text.independent-parts-cost": "each part that carries its own transform adds one draw call.",
+  "figure.text.independent-parts-over": "over the limit. fewer of these fit on one screen at once.",
   "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.",

package/translations/ja.json

@@ -85,8 +85,8 @@
   "figure.label.axis-scale-short": "scale",
   "figure.label.axis-width": "width",
   "figure.label.base-box": "基準ボックス (mm)",
-  "figure.label.budget-animations": "animation points",
   "figure.label.budget-groups": "material groups",
+  "figure.label.budget-independent": "個別に動く部品",
   "figure.label.budget-parts": "part count",
   "figure.label.budget-surface": "surfaces outside the palette",
   "figure.label.budget-transparent": "transparent materials",
@@ -113,8 +113,6 @@
   "figure.label.distinct-materials": "distinct materials",
   "figure.label.distinct-shapes": "distinct shapes",
   "figure.label.draft": "下書き",
-  "figure.label.draw-calls-at-100": "draw calls for 100",
-  "figure.label.draw-calls-at-10k": "draw calls at 10k instances",
   "figure.label.emissive": "emissive",
   "figure.label.emissive-color": "lit color",
   "figure.label.environment": "environment",
@@ -263,8 +261,6 @@
   "figure.label.tools": "align",
   "figure.label.transparent": "transparent",
   "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": "単位なし",
   "figure.label.unit-type-it": "直接入力…",
   "figure.label.weight": "weight",
@@ -276,8 +272,6 @@
   "figure.text.already-released-edit-to-release-again": "すでに公開済みです。修正して保存すると下書きに戻り、そこで再び公開できます。",
   "figure.text.anchor-explained": "ボックスが伸びるときにこの部品が付いている面です。接する部品と違う面に付くと、伸びたときに間が空きます。",
   "figure.text.anchors-are-not-drawn": "スロットとポートは図面には描かれず、編集画面にだけ表示されます。",
-  "figure.text.animated-parts-cost": "動く部品ごとに draw call が 1 増えます。",
-  "figure.text.animated-parts-over": "上限を超えました。1 つの図面に多く置くと画面が遅くなります。",
   "figure.text.animation-empty-examples": "回るローラー · スライドする扉 · 上下するリフト · 点滅する表示灯。",
   "figure.text.animation-empty-what-it-is": "まだ動きがありません。clip を追加して部品を動かしてください。",
   "figure.text.animation-needs-a-named-part": "先に部品を追加してください。",
@@ -344,6 +338,8 @@
   "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": "画面に出しても遅くならない数",
+  "figure.text.independent-parts-cost": "個別に動く部品ごとに draw call が 1 増えます。",
+  "figure.text.independent-parts-over": "上限を超えました。1 つの画面に一緒に置ける台数がその分減ります。",
   "figure.text.instances-unit": "instances",
   "figure.text.interpolation-explained": "キーの間をどうつなぐか。",
   "figure.text.joint-channel-value-deg": "キーの値は関節の角度 (度) です。",