@things-factory/figure-ui 10.1.27 → 10.1.29

package/client/modeller/joint-edits.ts

@@ -50,6 +50,63 @@ export function parentChoices(parts: readonly PartModel[], part: string): string
   return parts.map(one => one.name).filter(name => !!name && !below.has(name))
 }
 
+type Span = { min: number; max: number }
+
+/** 한 축에서 부품이 차지하는 구간. */
+const reachOf = (part: FigurePart, axis: 'x' | 'y' | 'z'): Span => ({
+  min: part.transform.position[axis] - part.transform.size[axis] / 2,
+  max: part.transform.position[axis] + part.transform.size[axis] / 2
+})
+
+/**
+ * 새 관절이 설 자리 — **부품이 붙은 부품과 맞닿는 면의 한가운데.**
+ *
+ * 경첩은 두 부품이 닿는 자리에 있다. 팔꿈치는 윗팔과 앞팔이 만나는 곳이고, 문은 문틀에 닿는
+ * 모서리에 있다. 그래서 처음 값은 그 자리여야 한다.
+ *
+ * 한동안 **부품 아랫면 한가운데**를 썼다. 위로 쌓는 부품에는 맞는 자리인데(로봇 팔이 그렇다),
+ * 옆에 달린 부품에는 틀린다 — 캐비닛 옆에 달린 문의 축이 문 바닥에 생긴다. 저작자는 그것을
+ * 화면에서 보고 손으로 옮겨야 했고, 어디로 옮길지는 두 부품의 치수를 머릿속에서 빼야 나왔다.
+ *
+ * **가장 벌어진 축이 맞닿는 축이다.** 두 상자가 겹치는 축에서는 뺀 값이 음수이고, 마주 보는
+ * 축에서만 0 이나 양수가 된다. 나머지 두 축은 겹치는 구간의 한가운데를 쓴다 — 문의 축은 문
+ * 높이의 한가운데에 있지 위아래 끝에 있지 않다.
+ *
+ * 붙은 부품이 없으면(Figure 틀에 직접 붙는다) 아랫면 한가운데다. 그때 맞닿는 것은 바닥이다.
+ *
+ * ⚠ 부품의 제 회전은 보지 않는다. 비스듬히 세운 부품에서는 축에 나란한 상자로 셈한 자리가
+ * 나오고, 그것은 **처음 값**이다 — 저작자가 옮길 수 있고, 화면의 부채꼴이 어디인지 보여 준다.
+ */
+export function seamOrigin(part: FigurePart, parent?: FigurePart): Vec3 {
+  const { position, size } = part.transform
+  if (!parent) return { x: position.x, y: position.y - size.y / 2, z: position.z }
+
+  const axes = ['x', 'y', 'z'] as const
+  const gaps = axes.map(axis => {
+    const mine = reachOf(part, axis)
+    const theirs = reachOf(parent, axis)
+    return { axis, gap: Math.max(mine.min - theirs.max, theirs.min - mine.max), mine, theirs }
+  })
+
+  const meeting = gaps.reduce((widest, one) => (one.gap > widest.gap ? one : widest))
+  const origin = { x: position.x, y: position.y, z: position.z }
+
+  for (const { axis, mine, theirs } of gaps) {
+    if (axis === meeting.axis) {
+      /* 맞닿는 면은 **내 면**이다. 부모 쪽 면을 쓰면 둘 사이가 벌어져 있을 때 축이 허공에 선다. */
+      origin[axis] = mine.min >= theirs.max ? mine.min : mine.max
+      continue
+    }
+    const from = Math.max(mine.min, theirs.min)
+    const to = Math.min(mine.max, theirs.max)
+    origin[axis] = from <= to ? (from + to) / 2 : position[axis]
+  }
+
+  return { x: round4(origin.x), y: round4(origin.y), z: round4(origin.z) }
+}
+
+const round4 = (value: number) => Math.round(value * 10000) / 10000
+
 function freeName(taken: Iterable<string>, stem: string): string {
   const used = new Set(taken)
   if (!used.has(stem)) return stem
@@ -106,14 +163,19 @@ function isPlainDriver(parameter: Parameter, joint: FigureJoint, span: { min: nu
 /**
  * Sets how a part moves relative to its parent, or clears the joint with `undefined`.
  *
- * - From none: adds a joint whose origin is the centre of the part's bottom face, with a vertical axis and
- *   starting limits, and a parameter that drives it over those limits.
+ * - From none: adds a joint at the seam with the parent (`seamOrigin`), with a vertical axis and starting
+ *   limits, and a parameter that drives it over those limits.
  * - To none: removes the joint and every channel that drove it; a parameter or clip left with no channel
  *   is removed too, because the format refuses an empty one.
  * - Between types: keeps the origin and axis, sets limits for the new type (none for continuous), and
  *   moves a plain driving parameter along with them.
  */
-export function setJointType(draft: FigureDraft, part: FigurePart, type: JointType | undefined): FigureDraft {
+export function setJointType(
+  draft: FigureDraft,
+  part: FigurePart,
+  type: JointType | undefined,
+  parent?: FigurePart
+): FigureDraft {
   const joints = draft.joints ?? []
   const existing = joints.find(joint => joint.child === part.name)
 
@@ -123,12 +185,11 @@ export function setJointType(draft: FigureDraft, part: FigurePart, type: JointTy
   }
 
   if (!existing) {
-    const { position, size } = part.transform
     const joint: FigureJoint = {
       name: freeName([...joints.map(one => one.name)], `${part.name}-joint`),
       child: part.name,
       type,
-      origin: { x: position.x, y: position.y - size.y / 2, z: position.z },
+      origin: seamOrigin(part, parent),
       axis: { x: 0, y: 1, z: 0 }
     }
     if (type !== 'continuous') joint.limits = { ...NEW_LIMITS[type] }

package/client/modeller/joint-gizmo.ts

@@ -0,0 +1,180 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+
+import type { FigureJoint, FigurePart, FigureSource } from '@hatiolab/figure-model'
+
+import { partFromFigure } from './figure-source.js'
+import type { FigureDraft, PartModel } from './figure-source.js'
+
+/**
+ * 관절이 **어느 자리에서 어느 쪽으로 얼마나 도는지**를 저작면에 그린다.
+ *
+ * 축은 `+x · -x · +y …` 중에서 고른다. 이름만 보고 어느 쪽으로 도는지 아는 사람은 없고, 지금은
+ * 미리보기로 건너가 막대를 끝까지 밀어 봐야 안다 — 여섯 축짜리 로봇에서는 그 왕복이 여섯 번이다.
+ * 도는 자리를 그 자리에 그려 두면 고르는 순간 보인다.
+ *
+ * ## 부채꼴 하나다
+ *
+ * 관절의 기준점에 **가동 범위만큼 벌어진 얇은 부채꼴**을 눕힌다. 부채꼴의 면이 도는 평면이고,
+ * 두께 방향이 축이며, 벌어진 각이 `limits` 다. 무한 회전(`continuous`)은 온전한 원이다.
+ *
+ * 부품 하나로 그린다 — 씬에 겹쳐 그리는 길을 따로 뚫지 않는다. 저작면은 부품을 컴포넌트로
+ * 세우는 자리이고, 이 부채꼴도 그 규칙을 그대로 따른다. `locked` 라 클릭·마퀴·기즈모가 집지
+ * 않고, 저장 형식으로는 나가지 않는다(저작면 안에서만 만들어 붙인다).
+ */
+
+/** 저작면에만 있는 이름. 부품 목록에는 없다. */
+export const JOINT_GIZMO = '__joint-gizmo'
+
+/** 부채꼴을 몇 조각으로 그리나. 한 조각이 6도쯤이면 원이 원으로 보인다. */
+const STEP = 6
+
+/** 두께. 얇아야 부품을 가리지 않고, 너무 얇으면 옆에서 볼 때 사라진다. */
+const THICKNESS = 6
+
+/**
+ * 도는 평면과 두께 방향을 축에 맞춘다.
+ *
+ * 부채꼴은 단면이 눕고 **제 y 방향으로** 밀려 두꺼워지는 도형이라, 기본 상태의 축이 +y 다.
+ * 다른 축은 부품 회전으로 눕힌다 — 부품이 제 회전을 지는 것과 같은 방법이고, 형식이 이미
+ * 아는 길이다.
+ *
+ * `turn` 은 단면 안에서 각을 재는 방향이다. 씬의 회전과 단면의 각이 도는 쪽이 반대인 축이
+ * 있어서, 그것을 여기 한 곳에 적어 둔다 — 부채꼴이 실제로 도는 쪽과 반대로 벌어지면
+ * 가리키는 뜻이 뒤집힌다.
+ */
+const AXIS_LAY: Record<string, { rotation?: FigurePart['transform']['rotation']; turn: 1 | -1 }> = {
+  '+y': { turn: -1 },
+  '-y': { turn: 1 },
+  '+x': { rotation: { z: 90 }, turn: 1 },
+  '-x': { rotation: { z: 90 }, turn: -1 },
+  '+z': { rotation: { x: 90 }, turn: -1 },
+  '-z': { rotation: { x: 90 }, turn: 1 }
+}
+
+/** 축 벡터를 `+x` 꼴의 이름으로. 형식은 단위 벡터를 쓰고 저작면은 여섯 중 하나를 고른다. */
+export function axisName(axis: { x: number; y: number; z: number }): string | undefined {
+  const named = [
+    ['x', axis.x],
+    ['y', axis.y],
+    ['z', axis.z]
+  ] as const
+  const on = named.filter(([, value]) => value !== 0)
+  if (on.length !== 1) return undefined
+  const [name, value] = on[0]!
+  return `${value > 0 ? '+' : '-'}${name}`
+}
+
+/** 이 관절이 도는 범위. 무한 회전은 한 바퀴다. */
+function span(joint: FigureJoint): { from: number; to: number } {
+  if (joint.type === 'continuous' || !joint.limits) return { from: -180, to: 180 }
+  return { from: joint.limits.min, to: joint.limits.max }
+}
+
+/** 부채꼴의 단면. 점은 부품 중심 기준의 밀리미터다. */
+function sector(from: number, to: number, radius: number, turn: 1 | -1): { x: number; y: number }[] {
+  const path: { x: number; y: number }[] = []
+  const full = Math.abs(to - from) >= 359.999
+
+  if (!full) path.push({ x: 0, y: 0 })
+
+  const steps = Math.max(2, Math.ceil(Math.abs(to - from) / STEP))
+  for (let i = 0; i <= steps; i++) {
+    const degrees = from + ((to - from) * i) / steps
+    const rad = (degrees * Math.PI * turn) / 180
+    path.push({ x: +(Math.cos(rad) * radius).toFixed(3), y: +(Math.sin(rad) * radius).toFixed(3) })
+  }
+
+  return path
+}
+
+/**
+ * 관절 하나를 그리는 부품. 그릴 수 없으면 `undefined` — 축이 비스듬하면 부채꼴로 그릴 수 없고,
+ * 그때 아무 쪽이나 골라 그리면 **틀린 방향을 가리킨다.**
+ */
+export function gizmoPart(joint: FigureJoint, child: PartModel | undefined, draft: FigureDraft): PartModel | undefined {
+  const lay = AXIS_LAY[axisName(joint.axis) ?? '']
+  if (!lay) return undefined
+
+  /* 반지름은 **도는 부품의 크기**에서 온다. 부채꼴이 그 부품보다 작으면 무엇이 도는지 안 읽힌다. */
+  const reach = child ? Math.max(child.width, child.height, child.depth) : 0
+  const radius = Math.max(60, Math.round(reach * 0.6))
+
+  const { from, to } = span(joint)
+  const part: FigurePart = {
+    name: JOINT_GIZMO,
+    primitive: 'polygon',
+    transform: {
+      position: { ...joint.origin },
+      size: { x: radius * 2, y: THICKNESS, z: radius * 2 },
+      ...(lay.rotation ? { rotation: lay.rotation } : {})
+    },
+    shape: { path: sector(from, to, radius, lay.turn) },
+    material: { token: 'palette.accent', transparent: true }
+  }
+
+  return { ...partFromFigure(part, draft), locked: true }
+}
+
+/*
+ * 미리보기에서 **관절이 돌았다는 것**을 보이게 하는 바늘.
+ *
+ * 상자 위에 원기둥을 얹고 그 축으로 돌리면 화면이 그대로다 — 원기둥은 제 축에서 대칭이라
+ * 돌아도 같은 그림이다. 저작자는 막대를 76도까지 밀고도 아무것도 못 보고 「관절이 안 먹는다」로
+ * 읽는다. 값은 제대로 갔고 부품도 돌았는데 볼 것이 없었을 뿐이다.
+ *
+ * 그래서 관절이 모는 부품에 얇은 막대 하나를 **자식으로** 붙인다. 부모가 관절의 자식이라
+ * 관절이 도는 만큼 같이 돌고, 축에서 비켜나 있어 대칭인 부품에서도 움직임이 보인다. 매 프레임
+ * 무엇을 다시 그릴 일도, 막대를 밀 때마다 씬을 다시 세울 일도 없다.
+ *
+ * **미리보기에만 붙인다.** 저장 형식에도, 저작면에도, 카드 그림에도 안 들어간다 — 미리보기는
+ * 크기 반응을 보는 작업대이고 거기서만 쓰는 표시다.
+ */
+
+/** 미리보기에만 있는 이름. 저장 형식에는 없다. */
+export const NEEDLE = '__needle-'
+
+/**
+ * 막대의 굵기 — **길이에 견주어** 잡는다.
+ *
+ * 8mm 로 고정했더니 미리보기에서 안 보였다. 미리보기는 여덟 대를 한 화면에 세우는 자리라
+ * 100mm 짜리 부품이 화면에서 20 픽셀쯤이고, 그 위의 8mm 는 한 픽셀이 안 된다. 세어 보면
+ * 막대는 분명히 서 있는데(부품 둘짜리 표본의 인스턴스에 mesh 셋 · 삼각형 72) 눈에 안 띈다.
+ */
+const needleThick = (radius: number) => Math.max(6, Math.round(radius / 5))
+
+/** 축에서 비켜날 방향. 그 축과 직각이어야 도는 것이 보인다. */
+const ASIDE: Record<string, 'x' | 'z'> = { x: 'z', y: 'x', z: 'x' }
+
+export function jointNeedles(source: FigureSource): FigurePart[] {
+  const byName = new Map(source.parts.map(part => [part.name, part]))
+
+  return (source.joints ?? []).flatMap(joint => {
+    const axis = axisName(joint.axis)
+    if (!axis) return []
+
+    const child = byName.get(joint.child)
+    const size = child?.transform.size
+    const reach = size ? Math.max(size.x, size.y, size.z) : 0
+    const radius = Math.max(60, Math.round(reach * 0.6))
+    const aside = ASIDE[axis.slice(1)]!
+    const thick = needleThick(radius)
+
+    return [
+      {
+        name: `${NEEDLE}${joint.name}`,
+        primitive: 'cube' as const,
+        transform: {
+          position: { ...joint.origin, [aside]: joint.origin[aside] + radius / 2 },
+          size:
+            aside === 'x'
+              ? { x: radius, y: thick, z: thick }
+              : { x: thick, y: thick, z: radius }
+        },
+        material: { token: 'palette.accent' },
+        parent: joint.child
+      }
+    ]
+  })
+}

package/client/modeller/part-edits.ts

@@ -27,6 +27,13 @@ function freeName(taken: Set<string>, base: string): string {
   }
 }
 
+const round = (value: number) => Math.round(value)
+
+/** 값을 두 끝 사이로 당긴다. 끝이 뒤집혀 있으면(부품이 상자보다 크다) 앞의 끝을 따른다. */
+function clamp(value: number, least: number, most: number): number {
+  return Math.max(least, Math.min(most, value))
+}
+
 /** 이 초안에 부품을 몇 개까지 넣을 수 있는지. 디테일 등급이 결정한다. */
 export function partLimit(draft: FigureDraft): number {
   return PART_LIMIT[(draft.detailLevel ?? 'M') as DetailLevel]
@@ -35,26 +42,58 @@ export function partLimit(draft: FigureDraft): number {
 /**
  * 새 부품 하나를 만든다.
  *
- * 기준 상자의 3분의 1 크기로, **바닥 가운데**에 놓는다. 추가하자마자 화면에 보여야 한다 —
- * 크기 0 으로 놓으면 사용자에게는 아무 일도 일어나지 않은 것으로 보인다.
+ * 기준 상자의 3분의 1 크기다. 추가하자마자 화면에 보여야 한다 — 크기 0 으로 놓으면
+ * 사용자에게는 아무 일도 일어나지 않은 것으로 보인다.
+ *
+ * ## 어디에 놓나 — 고른 부품 **위**다
+ *
+ * 전에는 언제나 바닥 한가운데였다. 첫 부품은 그 자리가 맞지만 둘째부터는 **첫 부품 속에**
+ * 들어간다 — 같은 자리에 같은 크기로 놓이니 화면에는 덩어리 하나뿐이고, 저작자는 무엇이
+ * 늘었는지 못 본다. 「추가하자마자 보여야 한다」는 그때 이미 깨져 있었다.
+ *
+ * 그래서 고른 부품이 있으면 그 부품의 **윗면**에 얹고 발자국을 가운데로 맞춘다. 기계는
+ * 대개 그렇게 쌓인다(받침 → 어깨 → 팔). 관절을 걸 때도 이 자리가 필요하다 — 맞닿는 면이
+ * 실제로 있어야 `seamOrigin` 이 회전 중심을 그 면에서 잡는다.
+ *
+ * 위에 얹으면 기준 상자를 넘는 경우에는 바닥 한가운데로 간다. 넘은 채로 놓으면 발행이
+ * 막히고(`part-outside-base`), 그것을 고치는 일이 「부품을 추가했다」의 대가가 된다.
+ * 가로·세로는 상자 안으로 당긴다 — 고른 부품이 가장자리에 있으면 그 위가 상자 밖이다.
  */
-export function newPart(draft: FigureDraft, parts: PartModel[], primitive: PrimitiveKind): PartModel {
+export function newPart(
+  draft: FigureDraft,
+  parts: PartModel[],
+  primitive: PrimitiveKind,
+  onTopOf?: PartModel
+): PartModel {
   const taken = new Set(parts.map(part => part.name))
 
   const width = Math.max(1, Math.round(draft.width / 3))
   const height = Math.max(1, Math.round(draft.height / 3))
   const depth = Math.max(1, Math.round(draft.depth / 3))
 
+  // 바닥 한가운데 — 고를 부품이 없을 때, 그리고 위가 상자 밖일 때의 자리.
+  const middle = {
+    left: Math.round((draft.width - width) / 2),
+    top: Math.round((draft.height - height) / 2),
+    // `zPos` 는 부피의 밑면이라 0 이 곧 상자 바닥이다.
+    zPos: 0
+  }
+  const above = onTopOf && {
+    left: clamp(Math.round(onTopOf.left + onTopOf.width / 2 - width / 2), 0, draft.width - width),
+    top: clamp(Math.round(onTopOf.top + onTopOf.height / 2 - height / 2), 0, draft.height - height),
+    zPos: Math.round(onTopOf.zPos + onTopOf.depth)
+  }
+  const at = above && above.zPos + depth <= draft.depth ? above : middle
+
   const part: PartModel = {
     type: 'figure-part',
     name: freeName(taken, primitive),
     primitive,
-    left: Math.round((draft.width - width) / 2),
-    top: Math.round((draft.height - height) / 2),
+    left: at.left,
+    top: at.top,
     width,
     height,
-    // 바닥에 붙인다. `zPos` 는 부피의 밑면이라 0 이 곧 상자 바닥이다.
-    zPos: 0,
+    zPos: at.zPos,
     depth,
     // 팔레트 토큰은 기존 부품의 것을 물려받는다 — 토큰이 늘어날 때마다 재질 그룹이 하나씩 는다.
     token: parts[0]?.token ?? 'palette.primary'
@@ -79,8 +118,35 @@ export function newPart(draft: FigureDraft, parts: PartModel[], primitive: Primi
   return part
 }
 
-export function addPart(draft: FigureDraft, parts: PartModel[], primitive: PrimitiveKind): PartModel[] {
-  return [...parts, newPart(draft, parts, primitive)]
+/**
+ * 씬에서 온 부품을 밀리미터로 맞춘다.
+ *
+ * 기즈모는 비율을 곱해서 크기를 낸다 — 420 에 1.72 를 곱하면 722.4180046035418 이고, 손대지
+ * 않은 축도 384.99999999999994 처럼 흔들린다. 저작자가 끈 결과가 소수 넷째 자리까지 남을
+ * 까닭이 없고, 칸에는 「722.4…」로 잘려 보인다. 이 편집기의 다른 길은 전부 정수 밀리미터로
+ * 맞춘다(부품을 새로 놓을 때 · 가운데 맞추기 · 격자 맞추기).
+ *
+ * 크기는 1 밑으로 내려가지 않는다 — 0 이면 부피가 사라지고 배율이 0 으로 나뉜다.
+ */
+export function roundPart(part: PartModel): PartModel {
+  return {
+    ...part,
+    left: round(part.left),
+    top: round(part.top),
+    zPos: round(part.zPos),
+    width: Math.max(1, round(part.width)),
+    height: Math.max(1, round(part.height)),
+    depth: Math.max(1, round(part.depth))
+  }
+}
+
+export function addPart(
+  draft: FigureDraft,
+  parts: PartModel[],
+  primitive: PrimitiveKind,
+  onTopOf?: PartModel
+): PartModel[] {
+  return [...parts, newPart(draft, parts, primitive, onTopOf)]
 }
 
 export function removePart(parts: PartModel[], index: number): PartModel[] {

package/client/modeller/pose-defaults.ts

@@ -0,0 +1,67 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+
+import type { FigureDraft } from './figure-source.js'
+
+/**
+ * 지금 세워 둔 자세를 **기본값으로 앉힌다.**
+ *
+ * ## 왜 필요한가
+ *
+ * 관절의 휴지 자세는 값이 0 인 자세다(ADR-0066). 팔이 여섯 마디면 그 자세는 곧게 선 기둥이라,
+ * 목록에서도 도면에서도 로봇으로 안 보인다. 로봇다운 자세는 **파라미터의 기본값**이 만든다 —
+ * 어깨 -35, 팔꿈치 70 을 적어 두면 아무도 값을 주지 않을 때 그 자세로 선다.
+ *
+ * 그것을 손으로 적으려면 미리보기에서 막대를 맞춘 뒤 그 수를 읽어 파라미터 칸마다 옮겨야 한다.
+ * 여섯 축이면 여섯 번이고, 옮기는 동안 화면의 자세와 적은 수가 갈린다. 여기서 하는 일은 그
+ * 옮겨 적기 하나다.
+ *
+ * ## 무엇을 건드리나
+ *
+ * **막대를 민 파라미터만** 건드린다. 안 민 것은 이미 제 기본값에 서 있으므로 적을 것이 없다.
+ * 값이 지금 기본값과 같으면 그 파라미터는 **그대로 둔다** — 새 객체로 바꾸면 고친 것이 없는데도
+ * 「저장 안 됨」이 붙는다. 하나도 안 바뀌면 받은 초안을 그대로 돌려준다.
+ */
+
+type Parameter = NonNullable<FigureDraft['parameters']>[number]
+
+/** 지금 이 파라미터가 서는 값. 형식의 `valueOf` 와 같은 순서로 읽는다. */
+function standing(parameter: Parameter): number {
+  return parameter.default ?? parameter.range?.min ?? 0
+}
+
+/** 범위 밖은 끝에서 문다. 막대는 범위 안에서만 움직이지만, 값은 다른 길로도 들어온다. */
+function settled(value: number, parameter: Parameter): number {
+  const range = parameter.range
+  const bound = range ? Math.min(Math.max(value, range.min), range.max) : value
+  return Math.round(bound * 10000) / 10000
+}
+
+/** 무엇이 달라지나 — 이름과 바뀔 값. 비어 있으면 앉힐 것이 없다. */
+export function poseChanges(
+  draft: FigureDraft | undefined,
+  values: Record<string, number>
+): { name: string; from: number; to: number }[] {
+  return (draft?.parameters ?? []).flatMap(parameter => {
+    const given = values[parameter.name]
+    if (given === undefined || !Number.isFinite(given)) return []
+
+    const to = settled(given, parameter)
+    const from = standing(parameter)
+    return to === from ? [] : [{ name: parameter.name, from, to }]
+  })
+}
+
+/** 지금 자세를 기본값으로 앉힌 초안. 앉힐 것이 없으면 **받은 초안 그대로**다. */
+export function poseAsDefaults(draft: FigureDraft, values: Record<string, number>): FigureDraft {
+  const changes = new Map(poseChanges(draft, values).map(change => [change.name, change.to]))
+  if (changes.size === 0) return draft
+
+  return {
+    ...draft,
+    parameters: (draft.parameters ?? []).map(parameter =>
+      changes.has(parameter.name) ? { ...parameter, default: changes.get(parameter.name)! } : parameter
+    )
+  }
+}

package/client/modeller/proposal.ts

@@ -32,6 +32,7 @@ export type ChangeKind =
   | 'animations'
   | 'parameters'
   | 'capabilities'
+  | 'joints'
 
 /**
  * 부품 밖에서 바뀔 수 있는 것 전부.
@@ -45,11 +46,15 @@ export type ChangeKind =
  * 말없이 사라진다. 그리고 `anchor` 는 도형 수준 필드였다가 형식에서 없어진 것인데(2026-09-10)
  * 여기 남아 있었다 — 이 목록이 형식을 따라가지 않은 것이 양쪽으로 드러난 셈이다.
  *
- * 형식의 `FigureSource` 는 `type` · `parts` 를 빼면 이 여섯이 전부다. `type` 은 저장되는
+ * 같은 일이 `joints` 로 한 번 더 났다(2026-09-18). 형식에 관절이 서고 저작 화면도 지었는데 이
+ * 목록만 그대로여서, 관절을 더해 온 후보는 변경 목록에 안 뜨고 받아도 관절이 사라졌다. 형식의
+ * 칸을 세는 시험이 그것을 잡았다.
+ *
+ * 형식의 `FigureSource` 는 `type` · `parts` 를 빼면 이 일곱이 전부다. `type` 은 저장되는
  * 식별자라 후보가 바꿔 와도 받지 않고(`applyProposal` 참고), `version` 은 저작자가 고를 것이
  * 아니라 저장할 때 서버가 찍는다.
  */
-const FIGURE_FIELDS = ['base', 'placement', 'detailLevel', 'styleKit', 'animations', 'parameters', 'capabilities'] as const
+const FIGURE_FIELDS = ['base', 'placement', 'detailLevel', 'styleKit', 'animations', 'parameters', 'capabilities', 'joints'] as const
 const FIELD_KIND: Record<(typeof FIGURE_FIELDS)[number], ChangeKind> = {
   base: 'base',
   placement: 'placement',
@@ -57,7 +62,8 @@ const FIELD_KIND: Record<(typeof FIGURE_FIELDS)[number], ChangeKind> = {
   styleKit: 'styleKit',
   animations: 'animations',
   parameters: 'parameters',
-  capabilities: 'capabilities'
+  capabilities: 'capabilities',
+  joints: 'joints'
 }
 
 export interface ProposalChange {

package/client/modeller/scene-budget.ts

@@ -1,58 +1,52 @@
 import type { FigureCost } from '@hatiolab/figure-model'
 
 /**
- * 한 도면이 감당하는 양 — 「몇 개까지 편한가」의 분모.
+ * 한 화면이 감당하는 양 — 「몇 개까지 편한가」의 분모.
  *
- * ## 이 값은 figure-model 것이어야 한다
+ * ## 놓은 개수가 아니라 **보이는 개수**다
  *
- * figure-model 의 `LIMITS` 는 전부 **Figure 하나짜리** 한도다(묶음 3 · 애니메이션 2 …).
- * 「몇 개를 놓을 수 있나」는 한 도면이 감당하는 양을 알아야 나오는데, 그 값은 아직
- * 어디에도 선언돼 있지 않다. 여기 두는 것은 임시다 — figure-model 이 선언하면 이
- * 파일을 지운다. 두 벌이 되면 갈린다.
+ * 3D 는 요청이 있어야 다시 그린다. 가만히 서 있는 도형은 프레임마다 아무 값도 치르지 않는다 —
+ * 900 대를 놓아 두어도 60fps 다. 값을 치르는 것은 **카메라 안에 들어 있고 그 프레임에 다시
+ * 그려지는** 것뿐이다. 그래서 이 파일의 분모는 「한 도면에 놓는 수」가 아니라 「한 화면에 보이는
+ * 부품 묶음 수」다.
  *
- * ## 지어낸 수가 아니다
+ * ## 이 수는 잰 값이다
  *
- * `docs/design/component-authoring-tool.md` §4.15 「목표 수치」에 적힌 값이다.
+ * 전에는 설계 문서의 목표치(도면당 draw call 2,500)를 썼고, 그 문서가 스스로 「측정 없이 정한
+ * 목표」라고 적어 두었다. 2026-09-18 에 실기에서 쟀다
+ * (`things-scene/test/browser/measure-figure-frames.mjs`, Apple M5, 저작 화면과 같은 조명 · 그림자):
  *
- *     한 도면        자산 500 개
- *     draw call      ≤ 2500
- *     삼각형         ≤ 50 만
+ *     묶음 9 짜리 6 축 로봇   600 대 보이면 59.5 fps · 700 대에서 56.7 fps
+ *     묶음 2 짜리 컨베이어    1,600 대 보이면 59.3 fps · 2,500 대에서 36.8 fps
  *
- * 그 문서가 스스로 이렇게 적어 두었다 — **「측정 없이 정한 목표다. 저작도구가 서면
- * 실제 도면으로 재고 조정한다」**(미결 D-20). 그래서 화면에도 근거를 함께 띄운다.
- * 숫자만 크게 내걸면 재 본 값처럼 읽힌다.
- */
-/**
- * 그림자 패스가 draw call 을 두 배로 만든다.
- *
- * 실측이다(2026-09-05, Apple M5). 자산 500~5,500 어디서나 실측이 figure-model 예측의
- * **정확히 2.00 배**로 나왔고, 그림자 맵을 끄면 예측과 같아졌다. 그림자 맵은 장면을
- * 한 번 더 그리기 때문이다. figure-model 의 `at.drawCalls` 는 색 패스만 센다.
+ * 두 도형의 꺾이는 지점이 **인스턴스 × 묶음 = 3,600 ~ 5,400** 에 들어온다. 보수적으로 4,000 을
+ * 쓴다. 도형이 달라도 이 곱이 비슷한 데서 꺾이므로, 분모는 묶음 수로 둔다.
  *
- * ## 등급 S 도 그림자를 진다
+ * ⚠ 이 수는 **이 기계에서 이 씬으로** 잰 값이다. 더 낮은 GPU 나 브라우저에서는 더 일찍 꺾인다.
+ * 화면에는 잰 기계와 날짜를 함께 적는다 — 적지 않으면 어디서나 참인 수처럼 읽힌다.
  *
- * 설계 문서 §4.15 는 「그림자는 등급 M 이상만」이라고 정했다. 그래서 처음에는 등급이
- * S 면 이 곱을 빼려 했다. **그런데 등급 S 로 세워 재 보니 draw call 이 똑같이 두 배로
- * 나왔다** — 그 규칙은 문서에만 있고 제품에는 없다.
+ * ## 그림자는 이미 들어 있다
  *
- * 그래서 등급을 보지 않고 언제나 곱한다. 없는 규칙을 믿고 셈하면 화면이 「S 로 하면
- * 두 배 놓을 수 있다」고 거짓말을 한다. things-scene 이 그 규칙을 구현하면 그때
- * 등급을 보면 된다 — 그쪽에 알릴 것.
+ * 2026-09-05 에는 draw call 을 figure-model 의 예측과 견주며 그림자 패스가 두 배로 만든다고
+ * 쟀다. 지금 값은 **그림자를 켠 채 프레임 시간을 직접 잰 것**이라 그 배수가 이미 안에 있다.
+ * 다시 곱하면 두 번 세는 것이다.
  */
-export const SHADOW_PASS_FACTOR = 2
 
 export const SCENE_BUDGET = {
-  /** 한 도면의 draw call. 로우폴리에서 먼저 차는 쪽이 대개 이것이다. */
-  drawCalls: 2500,
-  /** 한 도면의 삼각형. */
+  /** 한 화면에 보이는 부품 묶음. 60fps 가 꺾이는 지점, 실측. */
+  groupsOnScreen: 4000,
+  /** 한 화면의 삼각형. **이 수는 아직 안 쟀다** — 설계 문서의 목표치다. */
   triangles: 500_000
 } as const
 
+/** 어디서 언제 잰 값인가. 화면이 함께 보여 준다 — 적지 않으면 어디서나 참인 수로 읽힌다. */
+export const MEASURED = { gpu: 'Apple M5', on: '2026-09-18', fps: 60 } as const
+
 /** 무엇이 먼저 차나. */
-export type BindingBudget = 'drawCalls' | 'triangles'
+export type BindingBudget = 'groups' | 'triangles'
 
 export interface FigureCapacity {
-  /** 이 형상을 몇 개까지 놓을 수 있나. */
+  /** 이 형상이 **한 화면에 몇 개 보일 때까지** 60fps 로 도나. */
   instances: number
   /** 먼저 차는 예산. **여기부터 고치면 된다.** */
   bound: BindingBudget
@@ -89,14 +83,11 @@ export function capacityFrom(groups: number, triangles: number): FigureCapacity
     return undefined
   }
 
-  // 화면이 실제로 내는 draw call. 그림자 패스가 장면을 한 번 더 그린다 — 등급과 무관하게.
-  const calls = groups * SHADOW_PASS_FACTOR
-
-  const byDrawCalls = calls > 0 ? Math.floor(SCENE_BUDGET.drawCalls / calls) : Infinity
+  const byGroups = groups > 0 ? Math.floor(SCENE_BUDGET.groupsOnScreen / groups) : Infinity
   const byTriangles = triangles > 0 ? Math.floor(SCENE_BUDGET.triangles / triangles) : Infinity
 
-  return byDrawCalls <= byTriangles
-    ? { instances: byDrawCalls, bound: 'drawCalls', per: calls, budget: SCENE_BUDGET.drawCalls }
+  return byGroups <= byTriangles
+    ? { instances: byGroups, bound: 'groups', per: groups, budget: SCENE_BUDGET.groupsOnScreen }
     : { instances: byTriangles, bound: 'triangles', per: triangles, budget: SCENE_BUDGET.triangles }
 }
 

package/client/pages/figure-list-page.ts

@@ -10,7 +10,7 @@ import { i18next, localize } from '@operato/i18n'
 import { p13n } from '@operato/p13n'
 import { auth } from '@things-factory/auth-base/dist-client'
 import { navigate, PageView } from '@operato/shell'
-import { CommonGristStyles, CommonHeaderStyles, ScrollbarStyles } from '@operato/styles'
+import { CommonGristStyles, CommonHeaderStyles, ScrollbarStyles, WorkSurfacePageStyles } from '@operato/styles'
 
 import { capacityFrom } from '../modeller/scene-budget.js'
 import { deleteFigure, fetchFigureList } from '../graphql/index.js'
@@ -78,14 +78,13 @@ const FigureListPageBase = p13n(localize(i18next)(PageView))
 @customElement('figure-list-page')
 export class FigureListPage extends FigureListPageBase {
   static styles = [
+    /* The frame owns the page shell; the grist is the content it sizes (ADR-0060 decision 8). */
+    WorkSurfacePageStyles,
     ScrollbarStyles,
     CommonGristStyles,
     CommonHeaderStyles,
     css`
       :host {
-        display: flex;
-        flex-direction: column;
-        width: 100%;
         background-color: var(--md-sys-color-surface);
         color: var(--md-sys-color-on-surface);
         /* 떠 있는 단추의 기준 상자 */
@@ -129,11 +128,6 @@ export class FigureListPage extends FigureListPageBase {
       }
 
       /* 격자가 바깥에 요구하는 것은 확정된 높이 하나뿐이다 — 스크롤은 격자가 안에서 한다 */
-      ox-grist {
-        flex: 1;
-        min-height: 0;
-      }
-
       /*
         ── 그림이 주인공인 카탈로그 ────────────────────────────────────────
         카드 기본값은 글이 많은 목록(직원·결재함)에 맞춰져 있다. 여기서는 사람이 먼저 보는 것이
@@ -210,6 +204,7 @@ export class FigureListPage extends FigureListPageBase {
   render() {
     return html`
       <ox-grist
+        class="page-fill"
         mode="CARD"
         @search-tag=${(e: CustomEvent) => this.findByTag(e.detail.tag)}
         .config=${this.gristConfig}