@things-factory/figure-ui 10.1.3

package/client/modeller/part-edits.ts

@@ -0,0 +1,246 @@
+import { EXTRUDE_PRIMITIVES, SEGMENTED_PRIMITIVES, SEGMENT_PRESETS, PART_LIMIT } from '@hatiolab/figure-model'
+import type { DetailLevel, PrimitiveKind } from '@hatiolab/figure-model'
+
+import { AXIS_KEYS, boardExtent } from './figure-source.js'
+import type { BoardModel, PartModel, PlaneAxis } from './figure-source.js'
+
+/**
+ * 부품 편집 규칙. **씬 모델의 용어로** 다룬다.
+ *
+ * 편집 중에 기준이 되는 데이터는 씬 모델이다 — 보드 위에 부품 컴포넌트가 놓인 상태.
+ * 그래서 편집도 씬의 용어(`left`·`top`·`zPos`·`width`·`height`·`depth`)로 한다.
+ * FigureSource 의 좌표계로 바꾸는 변환은 `figure-source.ts` 한 곳에서만 한다.
+ *
+ * 사용자가 보는 축(X·Y·Z)이 씬의 어느 속성인지도 `figure-source.ts` 의 `AXIS_KEYS` 가 기준이다.
+ * 여기서 다시 정의하지 않는다.
+ *
+ * 모든 함수가 **새 배열·새 객체를 반환한다** — 원본을 수정하지 않는다. Lit 이 변경을
+ * 감지하려면 참조가 달라져야 하고, 실행 취소를 붙일 때도 이전 상태가 남아 있어야 한다.
+ */
+
+/** 중복되지 않는 이름을 만든다. 부품 이름은 저장되는 식별자라 중복되면 검증에서 걸린다. */
+function freeName(taken: Set<string>, base: string): string {
+  if (!taken.has(base)) return base
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`
+    if (!taken.has(candidate)) return candidate
+  }
+}
+
+/** 이 보드에 부품을 몇 개까지 넣을 수 있는지. 디테일 등급이 결정한다. */
+export function partLimit(board: BoardModel): number {
+  return PART_LIMIT[(board.detailLevel ?? 'M') as DetailLevel]
+}
+
+/**
+ * 새 부품 하나를 만든다.
+ *
+ * 보드의 3분의 1 크기로, **바닥 가운데**에 놓는다. 추가하자마자 화면에 보여야 한다 —
+ * 크기 0 으로 놓으면 사용자에게는 아무 일도 일어나지 않은 것으로 보인다.
+ */
+export function newPart(board: BoardModel, parts: PartModel[], primitive: PrimitiveKind): PartModel {
+  const taken = new Set(parts.map(part => part.name))
+
+  const width = Math.max(1, Math.round(board.width / 3))
+  const height = Math.max(1, Math.round(board.height / 3))
+  const depth = Math.max(1, Math.round(board.depth / 3))
+
+  const part: PartModel = {
+    type: 'figure-part',
+    name: freeName(taken, primitive),
+    primitive,
+    left: Math.round((board.width - width) / 2),
+    top: Math.round((board.height - height) / 2),
+    width,
+    height,
+    // 바닥에 붙인다. `zPos` 는 부피의 밑면이라 0 이 곧 보드 바닥이다.
+    zPos: 0,
+    depth,
+    // 팔레트 토큰은 기존 부품의 것을 물려받는다 — 토큰이 늘어날 때마다 재질 그룹이 하나씩 는다.
+    token: parts[0]?.token ?? 'palette.primary'
+  }
+
+  if (SEGMENTED_PRIMITIVES.includes(primitive)) {
+    part.segments = SEGMENT_PRESETS[1]
+  }
+  if (EXTRUDE_PRIMITIVES.includes(primitive)) {
+    part.round = 0
+  }
+  if (primitive === 'polygon') {
+    // polygon 은 점이 3개 이상이어야 한다. 없으면 검증에서 막히므로 삼각형으로 시작한다.
+    // 단면의 점은 부품 중심을 기준으로 적는다.
+    part.path = [
+      { x: -Math.round(width / 2), y: -Math.round(height / 2) },
+      { x: Math.round(width / 2), y: -Math.round(height / 2) },
+      { x: 0, y: Math.round(height / 2) }
+    ]
+  }
+
+  return part
+}
+
+export function addPart(board: BoardModel, parts: PartModel[], primitive: PrimitiveKind): PartModel[] {
+  return [...parts, newPart(board, parts, primitive)]
+}
+
+export function removePart(parts: PartModel[], index: number): PartModel[] {
+  return parts.filter((_, at) => at !== index)
+}
+
+/** 부품을 복제한다. 이름만 새로 붙인다 — 중복되면 검증에서 걸린다. */
+export function duplicatePart(parts: PartModel[], index: number): PartModel[] {
+  const origin = parts[index]
+  if (!origin) return parts
+
+  const copy: PartModel = JSON.parse(JSON.stringify(origin))
+  copy.name = freeName(new Set(parts.map(part => part.name)), `${origin.name}-copy`)
+
+  const next = [...parts]
+  next.splice(index + 1, 0, copy)
+  return next
+}
+
+/** 목록에서 순서를 바꾼다. 범위를 벗어나면 그대로 둔다. */
+export function movePart(parts: PartModel[], index: number, to: number): PartModel[] {
+  if (to < 0 || to >= parts.length || index === to) return parts
+
+  const next = [...parts]
+  const [moved] = next.splice(index, 1)
+  next.splice(to, 0, moved!)
+  return next
+}
+
+export function updatePart(parts: PartModel[], index: number, part: PartModel): PartModel[] {
+  return parts.map((old, at) => (at === index ? part : old))
+}
+
+/**
+ * 정밀 배치 도구 — 좌표를 손으로 계산하지 않게 한다.
+ *
+ * 보드 편집기는 자산을 **배치**하는 도구라 대략적인 위치로도 충분하다. 여기는 자산을
+ * **만드는** 도구라 다르다. 모터를 몸통 정중앙에 놓거나, 다리를 네 귀퉁이에 대칭으로
+ * 놓거나, 부품을 바닥에 정확히 붙이는 작업은 손으로 계산하면 늘 조금씩 어긋난다.
+ */
+
+function put(parts: PartModel[], index: number, fields: Partial<PartModel>): PartModel[] {
+  const part = parts[index]
+  if (!part) return parts
+  return updatePart(parts, index, { ...part, ...fields })
+}
+
+/** 위치의 한 축만 바꾼다. 어느 속성인지는 `AXIS_KEYS` 가 결정한다. */
+function putAt(parts: PartModel[], index: number, axis: PlaneAxis, value: number): PartModel[] {
+  return put(parts, index, { [AXIS_KEYS[axis].at]: value } as Partial<PartModel>)
+}
+
+/** 부품을 보드의 해당 축 가운데로 옮긴다. */
+export function centerPart(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+  const part = parts[index]
+  if (!part) return parts
+
+  return putAt(parts, index, axis, Math.round((boardExtent(board, axis) - part[AXIS_KEYS[axis].size]) / 2))
+}
+
+/** 부품을 보드 바닥(또는 해당 축의 시작)에 붙인다. */
+export function alignPartToStart(parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+  return putAt(parts, index, axis, 0)
+}
+
+/** 부품을 보드의 끝에 붙인다. */
+export function alignPartToEnd(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+  const part = parts[index]
+  if (!part) return parts
+
+  return putAt(parts, index, axis, Math.round(boardExtent(board, axis) - part[AXIS_KEYS[axis].size]))
+}
+
+/**
+ * 부품을 축 기준으로 대칭 복제한다.
+ *
+ * 다리 넷, 팔 둘 같은 형상을 이것 없이 만들면 고생한다. 이름은 **어느 쪽인지 알 수
+ * 있게** 붙인다 — `leg` 를 x 축으로 대칭하면 `leg-x`.
+ */
+export function mirrorPart(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): PartModel[] {
+  const part = parts[index]
+  if (!part || !canMirror(board, parts, index, axis)) return parts
+
+  const copy = JSON.parse(JSON.stringify(part)) as PartModel
+  copy.name = freeName(new Set(parts.map(p => p.name)), `${part.name}-${axis}`)
+
+  const next = [...parts]
+  next.splice(index + 1, 0, copy)
+  return putAt(next, index + 1, axis, mirroredAt(board, part, axis))
+}
+
+/** 대칭했을 때의 위치. 보드의 해당 축 안에서 뒤집는다. */
+function mirroredAt(board: BoardModel, part: PartModel, axis: PlaneAxis): number {
+  const { at, size } = AXIS_KEYS[axis]
+  return Math.round(boardExtent(board, axis) - part[at] - part[size])
+}
+
+/**
+ * 대칭이 의미가 있는지.
+ *
+ * 이미 그 축의 가운데에 있는 부품을 대칭하면 **같은 자리에 사본이 생긴다.** 화면에는
+ * 아무 변화가 없어 보이는데 부품 수만 늘고, 겹친 면에서 z-fighting 이 일어난다.
+ * 만들어 놓고 알리는 대신 미리 막는다.
+ */
+export function canMirror(board: BoardModel, parts: PartModel[], index: number, axis: PlaneAxis): boolean {
+  const part = parts[index]
+  if (!part) return false
+
+  return mirroredAt(board, part, axis) !== Math.round(part[AXIS_KEYS[axis].at])
+}
+
+/**
+ * 부품의 위치와 크기를 격자에 맞춘다.
+ *
+ * 격자 간격은 보드 크기에서 계산한다 — 고정 값이면 작은 형상에서는 너무 크고 큰
+ * 형상에서는 너무 잘다. 3D 바닥 격자와 같은 계산이라 화면에서 보이는 것과 일치한다.
+ */
+export function snapPart(board: BoardModel, parts: PartModel[], index: number): PartModel[] {
+  const part = parts[index]
+  if (!part) return parts
+
+  const step = gridStep(board)
+  const round = (value: number) => Math.round(value / step) * step
+
+  return put(parts, index, {
+    left: round(part.left),
+    top: round(part.top),
+    zPos: round(part.zPos),
+    // 크기는 0 이 되면 안 된다 — 부품이 사라진 것처럼 보인다
+    width: Math.max(step, round(part.width)),
+    height: Math.max(step, round(part.height)),
+    depth: Math.max(step, round(part.depth))
+  })
+}
+
+/**
+ * 격자 간격. 3D 바닥에 그려지는 격자와 같은 값이다.
+ *
+ * **세 축을 다 본다.** 평면만 보면 키가 큰 모델에서 격자가 지나치게 잘아진다. 시그널타워
+ * (바닥 160 x 160, 높이 1100)는 평면 기준으로 간격이 20 이 나와서, 옆에서 보면 높이가
+ * 격자 55 칸이 된다. 격자는 크기를 가늠하는 자이므로 모델 전체에 대해 읽혀야 한다.
+ */
+export function gridStep(board: BoardModel): number {
+  return niceStep(Math.max(board.width, board.height, board.depth))
+}
+
+/**
+ * 주어진 길이에 어울리는 **읽기 좋은** 격자 간격. 다섯 칸 정도가 되게 잡는다.
+ *
+ * 그냥 나누면 27·33 같은 값이 나온다. 그 격자에 맞추면 좌표가 54·81 이 되어 읽기
+ * 어렵다. 1·2·5 배수로 올림한다 — 자와 차트 눈금이 쓰는 방식이다.
+ *
+ * 격자가 성겨야 형상이 눈에 먼저 들어온다. 열 칸으로 잡았더니 격자가 촘촘해 배경이
+ * 먼저 보였다.
+ */
+export function niceStep(span: number): number {
+  const raw = Math.max(span, 1) / 5
+  const magnitude = Math.pow(10, Math.floor(Math.log10(raw)))
+  const n = raw / magnitude
+
+  const multiple = n < 1.5 ? 1 : n < 3.5 ? 2 : n < 7.5 ? 5 : 10
+  return Math.max(1, multiple * magnitude)
+}

package/client/modeller/proposal.ts

@@ -0,0 +1,142 @@
+import type { FigurePart, FigureSource } from '@hatiolab/figure-model'
+
+/**
+ * AI 후보를 지금 것과 비교하고, 고른 것만 받아들인다.
+ *
+ * 비교는 **저장 형식**으로 한다. 편집 중의 데이터는 씬 모델이지만, 후보는 서버에서
+ * FigureSource 로 오고 기준 치수·디테일 등급처럼 부품 밖의 값도 함께 봐야 한다.
+ *
+ * 부품 편집 규칙은 여기 없다 — `part-edits.ts` 가 씬 모델 용어로 갖고 있다.
+ */
+
+/**
+ * 후보가 무엇을 바꾸자는 것인가.
+ *
+ * 후보를 통째로만 받게 두면 「몸통은 좋은데 모터 자리가 틀렸다」에 답할 수 없다 —
+ * 그게 가장 흔한 반응이다. 그래서 후보를 **변경 목록**으로 본다.
+ *
+ * 부품은 이름으로 짝짓는다. `FigurePart.name` 이 저장되는 식별자이고 바인딩이
+ * 그 이름을 가리키므로, 이름이 같으면 같은 부품이다.
+ *
+ * 기준 치수와 디테일 등급도 목록에 넣는다. 부품만 골라 받으면 새 부품이 옛 기준
+ * 상자 밖으로 나가 **검증에 걸릴 수 있다** — 무엇을 함께 받아야 하는지 보여야 한다.
+ */
+export type ChangeKind = 'added' | 'changed' | 'removed' | 'base' | 'detail' | 'anchor' | 'styleKit'
+
+/**
+ * 부품 밖에서 바뀔 수 있는 것 전부.
+ *
+ * 여기 없는 필드는 **조용히 버려진다** — 후보가 바꿔 왔어도 목록에 안 뜨고 받아도
+ * 반영되지 않는다. 형식에 필드가 늘면 여기에 더해야 한다.
+ */
+const FIGURE_FIELDS = ['base', 'detailLevel', 'anchor', 'styleKit'] as const
+const FIELD_KIND: Record<(typeof FIGURE_FIELDS)[number], ChangeKind> = {
+  base: 'base',
+  detailLevel: 'detail',
+  anchor: 'anchor',
+  styleKit: 'styleKit'
+}
+
+export interface ProposalChange {
+  kind: ChangeKind
+  /** 부품 변경이면 부품 이름. 그 밖이면 무엇이 바뀌는지. */
+  key: string
+  /** 부품 변경일 때 후보 쪽 부품. */
+  part?: FigurePart
+}
+
+/** 부품 둘이 같은가. 순서까지 같은 JSON 으로 견준다 — 필드 순서는 만드는 쪽이 정한다. */
+function samePart(a: FigurePart, b: FigurePart): boolean {
+  return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b))
+}
+
+/** 키 순서를 맞춰 견줄 수 있게 한다. */
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(value as object).sort()) {
+      out[key] = sortKeys((value as Record<string, unknown>)[key])
+    }
+    return out
+  }
+  return value
+}
+
+export function diffProposal(current: FigureSource | undefined, proposal: FigureSource): ProposalChange[] {
+  const changes: ProposalChange[] = []
+  const mine = new Map((current?.parts ?? []).map(part => [part.name, part]))
+  const theirs = new Map(proposal.parts.map(part => [part.name, part]))
+
+  for (const field of FIGURE_FIELDS) {
+    if (!current) break
+    const before = JSON.stringify(sortKeys(current[field]))
+    const after = JSON.stringify(sortKeys(proposal[field]))
+    if (before !== after) {
+      changes.push({ kind: FIELD_KIND[field], key: field })
+    }
+  }
+
+  for (const part of proposal.parts) {
+    const old = mine.get(part.name)
+    if (!old) changes.push({ kind: 'added', key: part.name, part })
+    else if (!samePart(old, part)) changes.push({ kind: 'changed', key: part.name, part })
+  }
+  for (const part of current?.parts ?? []) {
+    if (!theirs.has(part.name)) changes.push({ kind: 'removed', key: part.name })
+  }
+
+  return changes
+}
+
+/**
+ * 고른 변경만 받는다.
+ *
+ * **타입 이름은 지금 것을 지킨다.** 만든 뒤에는 고칠 수 없는 저장 식별자이고,
+ * 배치된 인스턴스가 그 이름으로 청사진을 찾는다. 후보가 다른 이름을 지어 왔어도
+ * 그것 때문에 이미 놓인 것이 빈 자리가 되면 안 된다.
+ *
+ * `picked` 를 주지 않으면 전부 받는다 — 그것이 보통의 길이다.
+ *
+ * 더해지는 부품은 **뒤에 붙인다.** 후보가 놓은 자리에 끼워 넣으면, 일부만 골랐을
+ * 때 순서가 어디서 온 것인지 알 수 없게 된다.
+ */
+export function applyProposal(
+  current: FigureSource | undefined,
+  proposal: FigureSource,
+  picked?: Set<string>
+): FigureSource {
+  const takes = (change: ProposalChange) => !picked || picked.has(change.key)
+  const changes = diffProposal(current, proposal)
+
+  if (!current) {
+    return { ...proposal }
+  }
+
+  const removed = new Set(changes.filter(c => c.kind === 'removed' && takes(c)).map(c => c.key))
+  const replaced = new Map(
+    changes.filter(c => c.kind === 'changed' && takes(c)).map(c => [c.key, c.part as FigurePart])
+  )
+  const added = changes.filter(c => c.kind === 'added' && takes(c)).map(c => c.part as FigurePart)
+
+  const parts = [
+    ...current.parts.filter(part => !removed.has(part.name)).map(part => replaced.get(part.name) ?? part),
+    ...added
+  ]
+
+  // 고른 필드만 후보 값으로 바꾼다. 안 고른 것은 지금 값이 남는다.
+  const fields: Record<string, unknown> = {}
+  for (const field of FIGURE_FIELDS) {
+    const change = changes.find(c => c.key === field)
+    if (change && takes(change)) {
+      fields[field] = proposal[field]
+    }
+  }
+
+  return { ...current, ...fields, parts } as FigureSource
+}
+
+/** 전부 받는다. */
+export function takeProposal(current: FigureSource | undefined, proposal: FigureSource): FigureSource {
+  return applyProposal(current, proposal)
+}

package/client/modeller/scene-budget.ts

@@ -0,0 +1,102 @@
+import type { FigureCost } from '@hatiolab/figure-model'
+
+/**
+ * 한 도면이 감당하는 양 — 「몇 개까지 편한가」의 분모.
+ *
+ * ## 이 값은 figure-model 것이어야 한다
+ *
+ * figure-model 의 `LIMITS` 는 전부 **Figure 하나짜리** 한도다(묶음 3 · 애니메이션 2 …).
+ * 「몇 개를 놓을 수 있나」는 한 도면이 감당하는 양을 알아야 나오는데, 그 값은 아직
+ * 어디에도 선언돼 있지 않다. 여기 두는 것은 임시다 — figure-model 이 선언하면 이
+ * 파일을 지운다. 두 벌이 되면 갈린다.
+ *
+ * ## 지어낸 수가 아니다
+ *
+ * `docs/design/component-authoring-tool.md` §4.15 「목표 수치」에 적힌 값이다.
+ *
+ *     한 도면        자산 500 개
+ *     draw call      ≤ 2500
+ *     삼각형         ≤ 50 만
+ *
+ * 그 문서가 스스로 이렇게 적어 두었다 — **「측정 없이 정한 목표다. 저작도구가 서면
+ * 실제 보드로 재고 조정한다」**(미결 D-20). 그래서 화면에도 근거를 함께 띄운다.
+ * 숫자만 크게 내걸면 재 본 값처럼 읽힌다.
+ */
+/**
+ * 그림자 패스가 draw call 을 두 배로 만든다.
+ *
+ * 실측이다(2026-09-05, Apple M5). 자산 500~5,500 어디서나 실측이 figure-model 예측의
+ * **정확히 2.00 배**로 나왔고, 그림자 맵을 끄면 예측과 같아졌다. 그림자 맵은 장면을
+ * 한 번 더 그리기 때문이다. figure-model 의 `at.drawCalls` 는 색 패스만 센다.
+ *
+ * ## 등급 S 도 그림자를 진다
+ *
+ * 설계 문서 §4.15 는 「그림자는 등급 M 이상만」이라고 정했다. 그래서 처음에는 등급이
+ * S 면 이 곱을 빼려 했다. **그런데 등급 S 로 세워 재 보니 draw call 이 똑같이 두 배로
+ * 나왔다** — 그 규칙은 문서에만 있고 제품에는 없다.
+ *
+ * 그래서 등급을 보지 않고 언제나 곱한다. 없는 규칙을 믿고 셈하면 화면이 「S 로 하면
+ * 두 배 놓을 수 있다」고 거짓말을 한다. things-scene 이 그 규칙을 구현하면 그때
+ * 등급을 보면 된다 — 그쪽에 알릴 것.
+ */
+export const SHADOW_PASS_FACTOR = 2
+
+export const SCENE_BUDGET = {
+  /** 한 도면의 draw call. 로우폴리에서 먼저 차는 쪽이 대개 이것이다. */
+  drawCalls: 2500,
+  /** 한 도면의 삼각형. */
+  triangles: 500_000
+} as const
+
+/** 무엇이 먼저 차나. */
+export type BindingBudget = 'drawCalls' | 'triangles'
+
+export interface FigureCapacity {
+  /** 이 형상을 몇 개까지 놓을 수 있나. */
+  instances: number
+  /** 먼저 차는 예산. **여기부터 고치면 된다.** */
+  bound: BindingBudget
+  /** 인스턴스 하나가 무는 값. */
+  per: number
+  /** 그 예산의 한 도면 총량. */
+  budget: number
+}
+
+/**
+ * 몇 개까지 놓을 수 있나.
+ *
+ * 두 예산 중 **먼저 차는 쪽**이 답이다. 평균이나 곱을 내지 않는다 — 하나만 꽉 차도
+ * 그것이 병목이고, 저작자가 고쳐야 할 곳은 그 하나다.
+ *
+ * 셈은 여기서 하지만 재료는 전부 figure-model 이 낸 것이다. `cost.groups` 가 인스턴스
+ * 하나당 draw call 이고 `cost.triangles` 가 인스턴스 하나의 삼각형 수다.
+ */
+export function capacityOf(cost: FigureCost): FigureCapacity | undefined {
+  return capacityFrom(cost.groups, cost.triangles)
+}
+
+/**
+ * 저장된 값만으로 셈한다.
+ *
+ * 목록은 정본을 받아 오지 않는다 — 카드 수십 장마다 컴파일하면 목록이 무거워진다.
+ * 대신 서버가 저장해 둔 `groups` · `triangles` 를 쓴다. **목록과 저작면이 같은 함수를
+ * 쓰는 것**이 요점이다. 카드가 제 나름대로 셈하면 같은 형상이 두 화면에서 다른 개수로
+ * 나온다.
+ */
+export function capacityFrom(groups: number, triangles: number): FigureCapacity | undefined {
+  // 부품이 없으면 「무한히 놓을 수 있다」가 아니라 **답할 것이 없다**.
+  if (groups <= 0 && triangles <= 0) {
+    return undefined
+  }
+
+  // 화면이 실제로 내는 draw call. 그림자 패스가 장면을 한 번 더 그린다 — 등급과 무관하게.
+  const calls = groups * SHADOW_PASS_FACTOR
+
+  const byDrawCalls = calls > 0 ? Math.floor(SCENE_BUDGET.drawCalls / calls) : 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 }
+    : { instances: byTriangles, bound: 'triangles', per: triangles, budget: SCENE_BUDGET.triangles }
+}
+