@things-factory/figure-ui 10.1.27 → 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.27",
+  "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.27",
+    "@things-factory/figure-service": "^10.1.29",
     "three": "^0.185.1"
   },
-  "gitHead": "d04dc762cacf2aac8ba0b0f5d768eca365fc09da"
+  "gitHead": "e6bf9dec003fe5e794746aaeb5852b3b50478232"
 }

package/test/ai-proposal-contract.test.ts

@@ -128,21 +128,22 @@ test('피드백은 후보 세션의 선택과 측정값만 전송한다', () =>
 })
 
 /*
- * The modeller has one AI entrance now: the toolbar button opens the asidebar dock, and the dock
- * runs the whole exchange. `figure-ask` — a second, inline form that called `proposeFigure`
- * directly — was removed on 2026-09-16. It had already stopped being rendered, so it was dead
- * code a reader would still have to understand before touching this path.
+ * The modeller opens no AI door of its own. The application header already has one and it opens the
+ * same dock, and two doors to one room on one screen make a reader look for the difference between
+ * them (2026-09-18, on the author's reading of the screen). `figure-ask` — a second, inline form
+ * that called `proposeFigure` directly — went on 2026-09-16.
  *
- * What the entrance owes the author is unchanged and checked here: it must not save anything by
- * itself, and it must hand the server the current source and palette so the candidate is a
- * revision of what is open rather than something invented from the prompt alone.
+ * What the page owes is unchanged and checked here: when the dock asks, it answers with the source
+ * as it stands right now — unsaved edits included — so the candidate is a revision of what is open
+ * rather than something invented from the prompt alone. And it saves nothing by itself.
  */
-test('the modeller has exactly one AI entrance, and it opens the dock', () => {
+test('모델러는 AI 문을 스스로 두지 않고, 물으면 지금 정본을 답한다', () => {
   const path = fileURLToPath(new URL('../client/pages/figure-modeller-page.ts', import.meta.url))
   const source = readFileSync(path, 'utf8')
 
-  assert.match(source, /requestFigureAI\(\{ figureId: this\.figure\?\.id, source: this\.folded \}\)/)
-  assert.match(source, /openOverlay\('figure-ai-dock'/)
+  assert.doesNotMatch(source, /openOverlay\('figure-ai-dock'/, '앱 머리줄에 이미 있는 문을 여기 또 두지 않는다')
+  assert.match(source, /addEventListener\('figure-ai-context-request'/)
+  assert.match(source, /detail: \{ figureId: this\.figure\?\.id, source: this\.folded \}/)
   assert.doesNotMatch(source, /<figure-ask/, 'the inline ask form is gone; the dock is the entrance')
   assert.doesNotMatch(source, /proposeFigure\(/, 'the page must not call the propose mutation itself')
 })
@@ -568,7 +569,11 @@ test('구조 · 저작 가능한 모든 칸은 검토를 지난다 — 조용히
     styleKit: ['plain', 'factory'],
     animations: [undefined, animationOnly().animations],
     parameters: [undefined, parameterOnly().parameters],
-    capabilities: [['Holdable'], ['Holdable', 'FlowNode']]
+    capabilities: [['Holdable'], ['Holdable', 'FlowNode']],
+    joints: [
+      undefined,
+      [{ name: 'motor-joint', child: 'motor', type: 'revolute', origin: { x: 0, y: 50, z: 0 }, axis: { x: 0, y: 1, z: 0 }, limits: { min: -90, max: 90 } }]
+    ]
   }
 
   const unsampled = mustBeReviewable.filter(f => !(f in sample))

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

@@ -0,0 +1,165 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { baseFittingParts, baseOf, resizeBase } from '../client/modeller/base-box.ts'
+import { toFigureSource } from '../client/modeller/figure-source.ts'
+import type { FigureDraft, PartModel } from '../client/modeller/figure-source.ts'
+
+/*
+ * 기준 상자를 고치는 일.
+ *
+ * 저작면의 자리는 판의 왼쪽 위에서 재고 저장 형식의 자리는 상자 한가운데에서 잰다. 그래서 상자만
+ * 바꾸면 **저장되는 부품 자리가 전부 달라진다** — 이 시험이 지키는 것이 그 한 가지다.
+ */
+
+const DRAFT: FigureDraft = { version: 2, figureType: 'BOX', width: 1000, height: 1000, depth: 500, detailLevel: 'M' }
+
+const part = (over: Partial<PartModel> = {}): PartModel => ({
+  type: 'figure-part',
+  name: 'body',
+  primitive: 'cube',
+  left: 400,
+  top: 400,
+  width: 200,
+  height: 200,
+  zPos: 0,
+  depth: 300,
+  token: 'palette.primary',
+  ...over
+})
+
+/** 저장 형식에서 본 부품 자리. 상자를 고쳐도 이 값이 그대로여야 한다. */
+const placed = (draft: FigureDraft, parts: readonly PartModel[]) =>
+  toFigureSource(draft, [...parts]).parts.map(one => one.transform.position)
+
+describe('기준 상자', () => {
+  it('지금 크기를 읽는다', () => {
+    assert.deepEqual(baseOf(DRAFT), { width: 1000, height: 1000, depth: 500 })
+  })
+
+  it('상자를 키워도 부품의 저장 자리는 한 값도 안 바뀐다', () => {
+    const parts = [part(), part({ name: 'lamp', left: 450, top: 450, width: 100, height: 100, zPos: 300, depth: 60 })]
+    const before = placed(DRAFT, parts)
+
+    const next = resizeBase(DRAFT, parts, { width: 1600, height: 1200, depth: 500 })
+
+    assert.deepEqual(placed(next.draft, next.parts), before)
+    assert.equal(next.draft.width, 1600)
+    /* 늘어난 절반만큼 부품이 함께 옮겨 간다 — 저작면의 값은 달라진다. */
+    assert.equal(next.parts[0]!.left, 400 + 300)
+    assert.equal(next.parts[0]!.top, 400 + 100)
+  })
+
+  it('높이만 바꾸면 부품은 안 움직인다 — 밑면이 바닥이다', () => {
+    const parts = [part()]
+    const next = resizeBase(DRAFT, parts, { width: 1000, height: 1000, depth: 900 })
+
+    assert.equal(next.parts, parts, '같은 배열 그대로다')
+    assert.equal(next.draft.depth, 900)
+  })
+
+  it('달라질 것이 없으면 받은 것을 그대로 돌려준다', () => {
+    const parts = [part()]
+    const same = resizeBase(DRAFT, parts, { width: 1000, height: 1000, depth: 500 })
+
+    assert.equal(same.draft, DRAFT)
+    assert.equal(same.parts, parts)
+  })
+
+  it('0 으로 만들 수 없다 — 배율이 0 으로 나뉜다', () => {
+    const next = resizeBase(DRAFT, [part()], { width: 0, height: -20, depth: 0 })
+    assert.deepEqual(baseOf(next.draft), { width: 1, height: 1, depth: 1 })
+  })
+
+  describe('부품에 맞추기', () => {
+    it('부품을 감싸는 가장 작은 상자를 낸다', () => {
+      /* 가운데(500,500)에서 가장 먼 모서리가 600 이므로 반지름 100 → 200. 높이는 제일 높은 끝. */
+      const fitted = baseFittingParts(DRAFT, [part()])
+      assert.deepEqual(fitted, { width: 200, height: 200, depth: 300 })
+    })
+
+    it('치우친 부품은 한가운데를 지키느라 반대쪽에 여유가 남는다', () => {
+      /*
+        부품을 가운데로 끌어오지 않는다. 끌어오면 저작자가 놓은 자리가 소리 없이 달라지고,
+        발행된 도형에서는 문의 자리가 함께 움직인다.
+      */
+      const off = part({ left: 700, top: 400, width: 200, height: 200 })
+      const fitted = baseFittingParts(DRAFT, [off])!
+
+      assert.equal(fitted.width, 800, '가운데에서 900 까지가 400 이므로 양쪽으로 800')
+      const next = resizeBase(DRAFT, [off], fitted)
+      assert.deepEqual(placed(next.draft, next.parts), placed(DRAFT, [off]))
+    })
+
+    it('부품이 없으면 잴 것이 없다', () => {
+      assert.equal(baseFittingParts(DRAFT, []), undefined)
+    })
+
+    it('맞춘 상자 안에서는 부품이 상자를 넘지 않는다', () => {
+      const parts = [part(), part({ name: 'arm', left: 300, top: 250, width: 120, height: 500, zPos: 200, depth: 420 })]
+      const fitted = baseFittingParts(DRAFT, parts)!
+      const next = resizeBase(DRAFT, parts, fitted)
+      const source = toFigureSource(next.draft, [...next.parts])
+
+      for (const one of source.parts) {
+        const { position, size } = one.transform
+        assert.ok(Math.abs(position.x) + size.x / 2 <= source.base.x / 2 + 0.001, `${one.name} x`)
+        assert.ok(Math.abs(position.z) + size.z / 2 <= source.base.z / 2 + 0.001, `${one.name} z`)
+        assert.ok(position.y + size.y / 2 <= source.base.y + 0.001, `${one.name} y`)
+      }
+    })
+  })
+})
+
+/*
+ * 셈이 맞아도 **화면에 안 붙어 있으면** 저작자는 아무것도 못 본다. 이 묶음은 붙어 있는지를 본다 —
+ * 이 파일의 다른 시험들이 전부 초록인 채로 칸이 사라질 수 있는 자리다.
+ */
+describe('화면에 붙어 있다', () => {
+  const source = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+  it('검사기에 기준 상자 칸과 「부품에 맞추기」가 있다', () => {
+    const inspector = source('../client/modeller/figure-inspector.ts')
+
+    assert.ok(/figure\.label\.base-box/.test(inspector), '칸 이름')
+    assert.ok(/this\.resizeBase\(\{ width: value \}\)/.test(inspector), 'X 가 가로를 고친다')
+    assert.ok(/this\.resizeBase\(\{ depth: value \}\)/.test(inspector), 'Y 가 높이를 고친다')
+    assert.ok(/this\.fitBaseToParts\(\)/.test(inspector), '부품에 맞추기')
+    assert.ok(/new CustomEvent\('resize-base'/.test(inspector), '초안과 부품을 함께 올린다')
+  })
+
+  it('초안과 부품이 한 걸음으로 기록된다 — 한 번 되돌리면 둘 다 돌아온다', () => {
+    const page = source('../client/pages/figure-modeller-page.ts')
+
+    assert.ok(/@resize-base=\$\{\(e: CustomEvent\) => this\.resizeBase\(e\.detail\.draft, e\.detail\.parts\)\}/.test(page))
+    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')
+
+    /* 견줄 상대(직전 발행판)를 가져오고, 고칠 때마다 다시 잰다. */
+    assert.ok(/fetchReleasedSource\(id\)/.test(page), '직전 발행판을 읽는다')
+    assert.ok(/contractChanges\(this\.releasedSource, this\.folded\)/.test(page), '고치는 동안 견준다')
+    assert.ok(/\.contract=\$\{this\.contract\}/.test(page), '화면으로 내려보낸다')
+
+    /* 기준 상자에 대한 것은 그 칸 아래에서 말한다. */
+    assert.ok(/renderBaseContract\(\)/.test(inspector))
+    assert.ok(/base-ratio-changed|base-size-changed/.test(inspector))
+  })
+})

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-edits.test.ts

@@ -42,8 +42,8 @@ describe('joint edits', () => {
     assert.deepEqual(parentChoices(PARTS, 'tip'), ['base', 'arm'])
   })
 
-  it('adds a joint at the bottom face of the part, with a parameter that drives it', () => {
-    const draft = setJointType(DRAFT, figurePart(DRAFT, 'arm'), 'revolute')
+  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',
@@ -120,6 +120,41 @@ describe('joint edits', () => {
     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)

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)
+  })
+})