@things-factory/figure-ui 10.1.45 → 10.1.47

package/client/modeller/v3-maturity.ts

@@ -0,0 +1,415 @@
+import {
+  compileV3Asset,
+  compileV3Document,
+  LIMITS,
+  SEGMENT_PRESETS,
+  V3_BUDGET_KEYS,
+  V3_GRADE_SCALE,
+  v3CostOf,
+  v3GradeOf,
+  v3MaterialKeyOf,
+  v3ScoreOf,
+  v3WorldBoxesOf,
+  v3WritersOf
+} from '@hatiolab/figure-model'
+import type { V3Asset, V3AssetGeometry, V3BudgetKey, V3BudgetUse, V3Cost, V3Geometry, V3Score } from '@hatiolab/figure-model'
+
+import { capacityFrom } from './scene-budget.js'
+import type { FigureCapacity } from './scene-budget.js'
+
+/*
+ * The V2 modeller's maturity report, read off a V3 asset (user, 2026-09-24: the V3 tab showed a count and nothing
+ * else — 「왜 이렇게 너프되었는지」).
+ *
+ * V2's report was `figure-report.ts` over `costOf` · `scoreOf` · `costCurveSvg` (figure-model) and `maturity.ts`
+ * (figure-ui). Those read a V2 blueprint. This module asks the same questions of the evaluated V3 asset and keeps
+ * V2's answers where the question still has one:
+ *
+ *   grade A–D and its scale   V2's bounds, over figure-model's `v3ScoreOf`: one screen's target shared per instance
+ *                             (groups, triangles) and V2's declared rule limits (independent, transparent)
+ *   radar · axes              V2's six axes; the two V2 could not measure stay unmeasured, detail has no V3 field
+ *   drawing cost              triangles, distinct shapes, distinct materials
+ *   trend                     what grows with the instance count and what the instances share
+ *
+ * Kept apart from the element so it can be tested without a browser.
+ *
+ * ## What the V3 renderer shares, which is what the numbers count
+ *
+ * things-scene draws one mesh per drawn body (`figure-v3-rig.ts`) — no merging by material as V2 did — so a body is
+ * a draw call. It shares geometry by provider, dimensions, segments and profile (`figure-v3-geometry.ts`, `keyOf`)
+ * and materials by token, preset, transparency and light (`materialFor`). The keys below are those keys; a
+ * distinct-shape count that used another key would describe a renderer that does not exist.
+ *
+ * ## Budgets V3 does not have
+ *
+ * V2 had five. Two are not measured here, and are not shown as zero:
+ *   - off-palette surfaces: the V3 material has no surface field, so there is nothing to count;
+ *   - part count by detail level: V3 does not carry the detail level (chief architect, 2026-09-24, ADR-0087).
+ */
+
+/*
+  The grade, its budgets and its bounds are figure-model's (`v3ScoreOf`), so the catalogue grades a figure as this tab
+  does. The grade is the headroom against one screen's target (`LIMITS.screenInstances`), not a draw-call limit.
+*/
+export { V3_BUDGET_KEYS, V3_GRADE_SCALE as GRADE_SCALE, v3GradeOf as gradeOf }
+export type { V3BudgetKey, V3BudgetUse, V3Score }
+
+export type V3AxisKey = 'scale' | 'consistency' | 'reuse' | 'detail' | 'reactive' | 'readable'
+
+/** One maturity axis. The same shape V2's `maturity.ts` gave the report. */
+export interface V3MaturityAxis {
+  key: V3AxisKey
+  /** 0–1. Absent when the axis cannot be measured. */
+  ratio?: number
+  reading?: string
+  /** A reading that is words, not a number. */
+  readingKey?: string
+  because?: string
+  /** Why the axis is not measured. When present there is no ratio — an unmeasured axis is not a zero. */
+  blocked?: string
+}
+
+/** Instances on one screen, and what each series costs at that count. */
+export interface V3CurvePoint {
+  instances: number
+  triangles: number
+  drawCalls: number
+  /** Vertex buffers: one per distinct shape, shared by every instance of the same size. */
+  geometries: number
+  materials: number
+}
+
+export interface V3Report {
+  cost: V3Cost
+  capacity: FigureCapacity
+  score: V3Score
+  /** Distinct shapes and materials among the drawn bodies — V2's 「그리는 비용」 rows. */
+  distinctShapes: number
+  distinctMaterials: number
+  reuse: { distinct: number; parts: number; saved: number }
+  axes: V3MaturityAxis[]
+  curve: V3CurvePoint[]
+}
+
+/** V2's board target for the scale axis: 500 assets on one drawing (design document §4.15). */
+export const BOARD_ASSETS = 500
+
+/**
+ * The report for one asset, or nothing when no body is drawn — then there is nothing to measure, and the screen
+ * says so rather than drawing zeros.
+ *
+ * Evaluated at the asset's own design and state defaults, as `v3CostOf` is.
+ */
+export function v3ReportOf(asset: V3Asset): V3Report | undefined {
+  const cost = v3CostOf(asset)
+  const capacity = capacityFrom(cost.groups, cost.triangles)
+  if (!capacity) return undefined
+
+  const drawn = compileV3Asset(asset)
+    .evaluate()
+    .geometry.filter(body => body.visible !== false)
+  const plan = compileV3Document(asset.document)
+  const writers = v3WritersOf(asset)
+
+  const shapes = new Set(drawn.map(shapeKeyOf))
+  const materials = new Set(drawn.map(materialKeyOf))
+
+  const score = v3ScoreOf(asset)!
+
+  const reuse = { distinct: shapes.size, parts: drawn.length, saved: drawn.length - shapes.size }
+
+  const axes: V3MaturityAxis[] = [
+    {
+      key: 'scale',
+      // The board target filled is 1; room beyond it is better spent on the other axes, so it does not count more.
+      ratio: Math.min(1, capacity.instances / BOARD_ASSETS),
+      reading: String(capacity.instances),
+      because: 'figure.text.maturity-scale-because'
+    },
+    consistency(asset, materials.size),
+    {
+      key: 'reuse',
+      // A low distinct-to-parts ratio is much reuse; turned over so that more is higher.
+      ratio: reuse.parts === 0 ? 0 : 1 - reuse.distinct / reuse.parts,
+      reading: String(reuse.saved),
+      because: 'figure.text.maturity-reuse-because'
+    },
+    { key: 'detail', blocked: 'figure.text.maturity-blocked-no-detail-level' },
+    { key: 'reactive', blocked: 'figure.text.maturity-blocked-no-binding' },
+    readable(asset, plan, drawn, writers)
+  ]
+
+  return {
+    cost,
+    capacity,
+    score,
+    distinctShapes: shapes.size,
+    distinctMaterials: materials.size,
+    reuse,
+    axes,
+    curve: decadeSteps(1, 10000).map(instances => ({
+      instances,
+      triangles: cost.triangles * instances,
+      drawCalls: cost.groups * instances,
+      geometries: shapes.size,
+      materials: materials.size
+    }))
+  }
+}
+
+/**
+ * The key things-scene shares a body's geometry by (`figure-v3-geometry.ts` `keyOf`): provider, dimensions to a
+ * micrometre, segments (12 when unset), and a polygon's corners.
+ */
+export function shapeKeyOf(body: V3AssetGeometry | V3Geometry): string {
+  if (!('shape' in body)) {
+    // A scalar body has no mesh of its own; it is still one drawn body, told apart by what it declares.
+    const dims = Object.keys(body.dimensions).sort().map(k => `${k}=${body.dimensions[k]}`).join(',')
+    return `${body.provider}|${dims}`
+  }
+  const shape = body.shape
+  const round = (v: number) => Math.round(v * 1e6) / 1e6
+  const dims = Object.keys(shape.dimensions)
+    .sort()
+    .map(k => `${k}=${round(shape.dimensions[k]!)}`)
+    .join(',')
+  const profile = shape.profile ? '|' + shape.profile.map(p => `${round(p.x)}:${round(p.y)}`).join(';') : ''
+  const segments = (body as { segments?: number }).segments ?? 12
+  return `${shape.provider}|${dims}|s${segments}${profile}`
+}
+
+/**
+ * The key things-scene shares a material by (`figure-v3-rig.ts` `materialFor`), within one asset: token, preset,
+ * transparency, and the light when it is on. The colour follows from the token, so it is not a second key.
+ */
+export function materialKeyOf(body: V3AssetGeometry): string {
+  return v3MaterialKeyOf(body)
+}
+
+/**
+ * Does it look like one set — V2's baselines 3 and 4. V2 checks three things; V3 keeps the same three.
+ *
+ * Two of them hold by construction in V3: the material has no surface field, so there is no texture, and the
+ * format refuses a segment count outside the presets (`compileV3Asset`, `QUALITY`). They are still counted, as
+ * V2 counts them, so the ratio means what it meant: one fault in three.
+ */
+function consistency(asset: V3Asset, distinctMaterials: number): V3MaturityAxis {
+  const textures = 0
+  const offPreset = asset.appearance.filter(look => look.segments !== undefined && !SEGMENT_PRESETS.includes(look.segments)).length
+  const faults = (textures > 0 ? 1 : 0) + (offPreset > 0 ? 1 : 0) + (distinctMaterials > LIMITS.distinctMaterials ? 1 : 0)
+  return {
+    key: 'consistency',
+    ratio: (3 - faults) / 3,
+    readingKey: faults === 0 ? 'figure.text.maturity-consistency-clean' : 'figure.text.maturity-consistency-faults',
+    because: 'figure.text.maturity-consistency-because'
+  }
+}
+
+/** Seen from above, these do not fill their footprint box. V2's list, in V3's provider names. */
+const ROUND_FOOTPRINT: readonly string[] = ['cylinder', 'ellipticCylinder', 'frustum', 'sphere']
+
+/**
+ * Can it be told apart from above — V2's baseline 1, the same measure.
+ *
+ * Viewpoint entropy (Vázquez et al.) over the top view, counted by colour region rather than by face so that a
+ * finer segment count does not raise it: H = −Σ p·log p over each material's share of the footprint plus the
+ * background, divided by log(`LIMITS.distinctMaterials` + 1), the most this measure can reach.
+ *
+ * The footprint is V2's base box: the space the asset declares when it declares one (ADR-0044's box is V3's
+ * occupancy), otherwise the drawn bodies' own extent. Bodies are their axis-aligned world boxes
+ * (`v3WorldBoxesOf`, the gate's reading); the higher one covers the lower.
+ */
+function readable(
+  asset: V3Asset,
+  plan: ReturnType<typeof compileV3Document>,
+  drawn: V3AssetGeometry[],
+  writers: Map<string, string>
+): V3MaturityAxis {
+  const placed = drawn
+    .filter(body => 'pose' in body)
+    // One placed, drawn body gives exactly one box; boxes are taken one by one to keep each with its material.
+    .map(body => ({ body, box: v3WorldBoxesOf([body], writers)[0]! }))
+  if (placed.length === 0) return { key: 'readable', blocked: 'figure.text.maturity-blocked-no-parts' }
+
+  let frame: { x0: number; x1: number; z0: number; z1: number }
+  if (asset.occupancy) {
+    const values = plan.evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values
+    const at = (ref: string) => values[ref] as number
+    const b = asset.occupancy.bounds
+    frame = { x0: at(b.x.min), x1: at(b.x.max), z0: at(b.z.min), z1: at(b.z.max) }
+  } else {
+    frame = { x0: Infinity, x1: -Infinity, z0: Infinity, z1: -Infinity }
+    for (const { box } of placed) {
+      frame.x0 = Math.min(frame.x0, box.centre.x - box.extent.x / 2)
+      frame.x1 = Math.max(frame.x1, box.centre.x + box.extent.x / 2)
+      frame.z0 = Math.min(frame.z0, box.centre.z - box.extent.z / 2)
+      frame.z1 = Math.max(frame.z1, box.centre.z + box.extent.z / 2)
+    }
+  }
+
+  const regions = topViewRegions(placed, frame)
+  if (regions.total === 0) return { key: 'readable', blocked: 'figure.text.maturity-blocked-no-parts' }
+
+  const shares = [...regions.byMaterial.values(), regions.background].map(area => area / regions.footprint).filter(share => share > 0)
+  const entropy = -shares.reduce((sum, p) => sum + p * Math.log(p), 0)
+  const ceiling = Math.log(LIMITS.distinctMaterials + 1)
+  return {
+    key: 'readable',
+    // Clamped both ways: one region alone gives −0, which is not a reading anyone should see.
+    ratio: Math.max(0, Math.min(1, entropy / ceiling)),
+    reading: String(regions.byMaterial.size),
+    because: 'figure.text.maturity-readable-because'
+  }
+}
+
+/** Which material shows from above, on a 64 × 64 grid over the footprint. V2's `topViewRegions`, over world boxes. */
+function topViewRegions(
+  placed: { body: V3AssetGeometry; box: ReturnType<typeof v3WorldBoxesOf>[number] }[],
+  frame: { x0: number; x1: number; z0: number; z1: number }
+) {
+  const GRID = 64
+  const cells = new Array<string | null>(GRID * GRID).fill(null)
+  const height = new Float64Array(GRID * GRID)
+  const sx = GRID / Math.max(frame.x1 - frame.x0, 1e-6)
+  const sz = GRID / Math.max(frame.z1 - frame.z0, 1e-6)
+
+  for (const { body, box } of placed) {
+    const top = box.centre.y + box.extent.y / 2
+    const key = materialKeyOf(body)
+    const x0 = Math.max(0, Math.floor((box.centre.x - box.extent.x / 2 - frame.x0) * sx))
+    const x1 = Math.min(GRID, Math.ceil((box.centre.x + box.extent.x / 2 - frame.x0) * sx))
+    const y0 = Math.max(0, Math.floor((box.centre.z - box.extent.z / 2 - frame.z0) * sz))
+    const y1 = Math.min(GRID, Math.ceil((box.centre.z + box.extent.z / 2 - frame.z0) * sz))
+    const round = 'shape' in body && ROUND_FOOTPRINT.includes(body.shape.provider)
+
+    for (let y = y0; y < y1; y++) {
+      for (let x = x0; x < x1; x++) {
+        // A round body does not fill its box; the corners are cut, as V2 cuts them.
+        if (round) {
+          const cx = (x + 0.5 - (x0 + x1) / 2) / ((x1 - x0) / 2 || 1)
+          const cy = (y + 0.5 - (y0 + y1) / 2) / ((y1 - y0) / 2 || 1)
+          if (cx * cx + cy * cy > 1) continue
+        }
+        const i = y * GRID + x
+        if (cells[i] === null || top > height[i]!) {
+          cells[i] = key
+          height[i] = top
+        }
+      }
+    }
+  }
+
+  const byMaterial = new Map<string, number>()
+  let covered = 0
+  for (const key of cells) {
+    if (key === null) continue
+    covered++
+    byMaterial.set(key, (byMaterial.get(key) ?? 0) + 1)
+  }
+  return { byMaterial, total: covered, background: GRID * GRID - covered, footprint: GRID * GRID }
+}
+
+/** 1 · 2 · 5 per decade, as V2's trend (`cost-chart.ts`): even steps on a log axis. */
+export function decadeSteps(from: number, to: number): number[] {
+  const out: number[] = []
+  for (let decade = 1; decade <= to; decade *= 10) {
+    for (const m of [1, 2, 5]) {
+      const v = decade * m
+      if (v >= from && v <= to) out.push(v)
+    }
+  }
+  if (out.length === 0 || out[out.length - 1] !== to) out.push(to)
+  return [...new Set(out)].sort((a, b) => a - b)
+}
+
+// ─── The trend chart ─────────────────────────────────────────────────────────
+
+export type V3CurveSeries = 'triangles' | 'drawCalls' | 'geometries' | 'materials'
+
+/**
+ * The four lines V2 drew: two that grow with the instance count and two that stay flat — the flat ones are what the
+ * instances share. Materials are dashed and drawn last, so a line under them still shows where the two meet.
+ */
+export const CURVE_SERIES: readonly { key: V3CurveSeries; flat: boolean; dashed?: boolean }[] = [
+  { key: 'triangles', flat: false },
+  { key: 'drawCalls', flat: false },
+  { key: 'geometries', flat: true },
+  { key: 'materials', flat: true, dashed: true }
+]
+
+/** V2's chart size. The chart is shown at this size in a sheet; shrunk into the side, its words are unreadable. */
+export const CURVE_SIZE = { width: 680, height: 380, pad: { top: 52, right: 208, bottom: 44, left: 62 } } as const
+
+export interface V3CurveLayout {
+  xTicks: { x: number; label: string }[]
+  yTicks: { y: number; label: string }[]
+  lines: { key: V3CurveSeries; d: string; flat: boolean; dashed: boolean; last: number }[]
+  /** The value the flat lines share when they lie on one another, so the screen can say why one line is missing. */
+  overlap?: number
+}
+
+const log10 = (v: number) => Math.log(Math.max(v, 1)) / Math.LN10
+
+/** 1, 10, 100 … written short. */
+export function shortNumber(v: number): string {
+  if (v >= 1_000_000) return `${v / 1_000_000}M`
+  if (v >= 1_000) return `${v / 1_000}k`
+  return String(v)
+}
+
+/** Where V2's chart puts each line and tick. Both axes are logarithmic, as V2's are. */
+export function curveLayout(points: V3CurvePoint[]): V3CurveLayout | undefined {
+  if (points.length === 0) return undefined
+  const { width, height, pad } = CURVE_SIZE
+  const minX = points[0]!.instances
+  const maxX = points[points.length - 1]!.instances
+  let maxY = 1
+  for (const p of points) for (const s of CURVE_SERIES) maxY = Math.max(maxY, p[s.key])
+
+  const plotW = width - pad.left - pad.right
+  const plotH = height - pad.top - pad.bottom
+  const spanX = Math.max(log10(maxX) - log10(minX), 1e-9)
+  const spanY = Math.max(log10(maxY), 1e-9)
+  const px = (v: number) => pad.left + ((log10(v) - log10(minX)) / spanX) * plotW
+  const py = (v: number) => pad.top + plotH - (log10(v) / spanY) * plotH
+
+  const yTicks: V3CurveLayout['yTicks'] = []
+  for (let e = 0; Math.pow(10, e) <= maxY * 1.001; e++) yTicks.push({ y: py(Math.pow(10, e)), label: shortNumber(Math.pow(10, e)) })
+  const xTicks: V3CurveLayout['xTicks'] = []
+  for (let e = 0; Math.pow(10, e) <= maxX * 1.001; e++) {
+    const v = Math.pow(10, e)
+    if (v >= minX) xTicks.push({ x: px(v), label: shortNumber(v) })
+  }
+
+  const last = points[points.length - 1]!
+  const lines = CURVE_SERIES.map(s => ({
+    key: s.key,
+    d: points.map((p, i) => `${i === 0 ? 'M' : 'L'}${px(p.instances).toFixed(1)},${py(p[s.key]).toFixed(1)}`).join(' '),
+    flat: s.flat,
+    dashed: !!s.dashed,
+    last: last[s.key]
+  }))
+  const flat = new Set(CURVE_SERIES.filter(s => s.flat).map(s => last[s.key]))
+  return { xTicks, yTicks, lines, overlap: flat.size === 1 ? [...flat][0] : undefined }
+}
+
+/** What the parts list shows under its title: the cost, how many fit, the grade and what decides it. */
+export interface V3BudgetLine {
+  triangles: number
+  groups: number
+  instances: number
+  grade: string
+  tightest: { key: string; used: number; limit: number }
+}
+
+export function budgetOf(report: V3Report | undefined): V3BudgetLine | undefined {
+  if (!report) return undefined
+  const { tightest } = report.score
+  return {
+    triangles: report.cost.triangles,
+    groups: report.cost.groups,
+    instances: report.capacity.instances,
+    grade: report.score.grade,
+    tightest: { key: tightest.key, used: tightest.used, limit: Math.floor(tightest.limit) }
+  }
+}

package/client/modeller/v3-palette.ts

@@ -0,0 +1,45 @@
+import type { V3PrimitiveCreation } from '@hatiolab/figure-model'
+
+import type { V3PaletteKind } from './figure-v3-parts.js'
+
+/**
+ * What a palette button makes: the part at a starting size a person then changes. Standing on the floor (its lowest
+ * point at y 0) where the provider's frame is centred; a portal's frame already rises from its bottom.
+ */
+export function paletteRecipe(kind: V3PaletteKind, id: string): V3PrimitiveCreation {
+  const standing = (height: number) => ({ id, position: { x: 0, y: height / 2, z: 0 } })
+  switch (kind) {
+    case 'box':
+      return { ...standing(100), kind, dimensions: { width: 100, height: 100, depth: 100 } }
+    case 'cylinder':
+      return { ...standing(100), kind, dimensions: { radius: 50, length: 100 } }
+    case 'rounded-box':
+      return { ...standing(100), kind, dimensions: { width: 100, height: 100, depth: 100, round: 10 } }
+    case 'sphere':
+      return { ...standing(100), kind, dimensions: { radiusX: 50, radiusY: 50, radiusZ: 50 } }
+    case 'frustum':
+      return { ...standing(100), kind, dimensions: { radiusTop: 0, radiusBottom: 50, height: 100 } }
+    case 'polygon':
+      return {
+        ...standing(100),
+        kind,
+        dimensions: { height: 100 },
+        points: [
+          { x: -50, z: -43 },
+          { x: 50, z: -43 },
+          { x: 0, z: 43 }
+        ]
+      }
+    case 'plate':
+      return { ...standing(10), kind: 'box', dimensions: { width: 600, height: 10, depth: 400 } }
+    case 'wall':
+      return { ...standing(2400), kind: 'box', dimensions: { width: 1000, height: 2400, depth: 100 } }
+    case 'portal':
+      return {
+        id,
+        position: { x: 0, y: 0, z: 0 },
+        kind: 'portal',
+        dimensions: { left: -100, right: 100, bottom: 0, top: 200, openingLeft: -70, openingRight: 70, openingTop: 170, depth: 30 }
+      }
+  }
+}

package/client/modeller/v3-preview-model.ts

@@ -0,0 +1,54 @@
+import { compileV3Asset, v3OccupiedBoxesOf, v3WritersOf, V3_INSTANCE_SIZE_INPUTS } from '@hatiolab/figure-model'
+import type { V3Asset } from '@hatiolab/figure-model'
+
+/* The preview's arithmetic, apart from the element so it is tested without a browser (see figure-v3-preview.ts). */
+
+export const PREVIEW_FACTOR = 2
+
+export const PREVIEW_WAYS: readonly { name: string; axes: readonly ('x' | 'y' | 'z')[] }[] = [
+  { name: 'base', axes: [] },
+  { name: 'x', axes: ['x'] },
+  { name: 'y', axes: ['y'] },
+  { name: 'z', axes: ['z'] },
+  { name: 'x·y', axes: ['x', 'y'] },
+  { name: 'x·z', axes: ['x', 'z'] },
+  { name: 'y·z', axes: ['y', 'z'] },
+  { name: 'x·y·z', axes: ['x', 'y', 'z'] }
+]
+
+/** The size the figure was made at: its instance size when it declares one, else the room its bodies take. */
+export function authoredSizeOf(asset: V3Asset): { x: number; y: number; z: number } {
+  const d = asset.designInputs
+  const declared = (['x', 'y', 'z'] as const).map(axis => d[V3_INSTANCE_SIZE_INPUTS[axis]])
+  if (declared.every(v => typeof v === 'number' && v > 0)) return { x: declared[0]!, y: declared[1]!, z: declared[2]! }
+  /* No declared size: the room its bodies take up, so the instance is placed at the size it draws. */
+  const boxes = v3OccupiedBoxesOf(compileV3Asset(asset).evaluate().geometry, v3WritersOf(asset))
+  const span = (axis: 'x' | 'y' | 'z') =>
+    boxes.length ? Math.max(...boxes.map(b => b.centre[axis] + b.extent[axis] / 2)) - Math.min(...boxes.map(b => b.centre[axis] - b.extent[axis] / 2)) : 0
+  return { x: Math.max(1, Math.round(span('x'))), y: Math.max(1, Math.round(span('y'))), z: Math.max(1, Math.round(span('z'))) }
+}
+
+/** The eight instances: where each stands on the board and how large, in the scene's words. */
+export function previewInstances(type: string, size: { x: number; y: number; z: number }) {
+  const COLUMNS = 4
+  const cell = { x: size.x * PREVIEW_FACTOR * 1.25, z: size.z * PREVIEW_FACTOR * 1.25 }
+  const components = PREVIEW_WAYS.map((way, at) => {
+    const grow = (axis: 'x' | 'y' | 'z') => (way.axes.includes(axis) ? PREVIEW_FACTOR : 1)
+    const width = Math.round(size.x * grow('x'))
+    const height = Math.round(size.z * grow('z'))
+    const column = at % COLUMNS
+    const row = Math.floor(at / COLUMNS)
+    return {
+      type,
+      id: `at-${way.name}`,
+      left: Math.round(column * cell.x + (cell.x - width) / 2),
+      top: Math.round(row * cell.z + (cell.z - height) / 2),
+      width,
+      height,
+      /* Always written: without it the height is taken as the plan's mean and "grow y only" would not grow it. */
+      depth: Math.round(size.y * grow('y'))
+    }
+  })
+  return { components, board: { width: Math.round(cell.x * COLUMNS), height: Math.round(cell.z * Math.ceil(PREVIEW_WAYS.length / COLUMNS)) } }
+}
+

package/client/modeller/v3-stage-model.ts

@@ -0,0 +1,159 @@
+import * as THREE from 'three'
+import { buildV3Geometry } from '@hatiolab/things-scene'
+
+import type { GizmoResult } from './v3-gizmo.js'
+import type { V3RenderPart } from './v3-renderer.js'
+
+/*
+ * V3 bodies <-> scene components, in one place (V2's `figure-source.ts` was that place for V2 parts).
+ *
+ * The modeller stands on a things-scene board in editing mode, as V2's did: each body figure-model evaluates is a
+ * `figure-v3-part` component, and what the scene's gizmo writes back comes here to become a change of the part's
+ * inputs. The two vocabularies:
+ *
+ *     V3 (asset frame, mm, y up)            scene component
+ *     ────────────────────────────────      ─────────────────────────────────────────────
+ *     body box extent  x · y · z             width · depth · height
+ *     body box centre  x                     left + width/2  - board width/2
+ *                      y                     zPos + depth/2
+ *                      z                     top  + height/2 - board height/2
+ *     body rotation (rigid@1, Rx·Ry·Rz)      rotationX · -rotation · rotationY (radians; three 'XYZ')
+ *
+ * The box is the body's own bounding box in its local frame, so a turned body keeps its size and the gizmo's handles
+ * sit on its faces. Its centre is not always the body's origin (a portal rises from its bottom), so a turn about the
+ * centre moves the origin: the result gives the origin where the turned body puts it.
+ */
+
+export interface Board {
+  width: number
+  height: number
+}
+
+export interface BodyFrame {
+  /** The body's box: its centre in the body's own frame, and its extent. */
+  centre: THREE.Vector3
+  extent: THREE.Vector3
+  rotation: THREE.Matrix4
+  origin: THREE.Vector3
+}
+
+const round = (n: number) => Math.round(n * 1e6) / 1e6
+
+export function frameOf(part: V3RenderPart): BodyFrame | null {
+  /* The box things-scene's `figure-v3-part` centres the body on: the same builder, measured the same way. */
+  let built: THREE.BufferGeometry | undefined
+  try {
+    built = buildV3Geometry(part.shape as never, part.segments) as THREE.BufferGeometry | undefined
+  } catch {
+    return null
+  }
+  if (!built?.getAttribute('position')) return null
+  built.computeBoundingBox()
+  const box = built.boundingBox!
+  const unit = { centre: box.getCenter(new THREE.Vector3()), extent: box.getSize(new THREE.Vector3()) }
+  built.dispose()
+  const r = part.pose.r
+  const rotation = new THREE.Matrix4().set(r[0]![0]!, r[0]![1]!, r[0]![2]!, 0, r[1]![0]!, r[1]![1]!, r[1]![2]!, 0, r[2]![0]!, r[2]![1]!, r[2]![2]!, 0, 0, 0, 0, 1)
+  return { centre: unit.centre, extent: unit.extent, rotation, origin: new THREE.Vector3(...(part.pose.t as [number, number, number])) }
+}
+
+/** The colours a body is drawn in, from the palette the modeller resolved (the asset's, over which the theme wins). */
+function colours(part: V3RenderPart, palette: Record<string, string>) {
+  const m = part.material
+  const glow = m.emissive?.on ? { color: palette[m.emissive.token] ?? palette[m.token] ?? '#9a9a9a', intensity: m.emissive.intensity } : undefined
+  return { color: palette[m.token] ?? '#9a9a9a', preset: m.preset, transparent: !!m.transparent, ...(glow ? { glow } : {}) }
+}
+
+/** The component state that draws a body where figure-model put it. */
+export function componentOf(part: V3RenderPart, palette: Record<string, string>, board: Board): Record<string, unknown> | null {
+  const frame = frameOf(part)
+  if (!frame) return null
+  const { centre, extent, rotation, origin } = frame
+  const world = centre.clone().applyMatrix4(rotation).add(origin)
+  const euler = new THREE.Euler().setFromRotationMatrix(rotation, 'XYZ')
+  const width = extent.x || 1,
+    depth = extent.y || 1,
+    height = extent.z || 1
+  return {
+    type: 'figure-v3-part',
+    name: part.id,
+    shape: part.shape,
+    ...(part.segments !== undefined ? { segments: part.segments } : {}),
+    ...colours(part, palette),
+    width: round(width),
+    depth: round(depth),
+    height: round(height),
+    left: round(world.x + board.width / 2 - width / 2),
+    top: round(world.z + board.height / 2 - height / 2),
+    zPos: round(world.y - depth / 2),
+    rotationX: round(euler.x),
+    rotation: round(-euler.y),
+    rotationY: round(euler.z)
+  }
+}
+
+const num = (v: unknown, fallback = 0) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback)
+
+/**
+ * What the gizmo did, in the inputs' terms: where the body's origin is now, how it is turned (degrees, rigid@1's
+ * order) and how much each of its own axes grew. Only what changed is given; a component the gizmo did not move gives
+ * nothing.
+ */
+export function gizmoResultOf(part: V3RenderPart, after: Record<string, unknown>, board: Board): GizmoResult {
+  const frame = frameOf(part)
+  if (!frame) return {}
+  const { centre, extent, rotation, origin } = frame
+  const width = num(after.width, extent.x),
+    depth = num(after.depth, extent.y),
+    height = num(after.height, extent.z)
+  const scale = new THREE.Vector3(width / (extent.x || 1), depth / (extent.y || 1), height / (extent.z || 1))
+  const world = new THREE.Vector3(num(after.left) + width / 2 - board.width / 2, num(after.zPos) + depth / 2, num(after.top) + height / 2 - board.height / 2)
+  const euler = new THREE.Euler(num(after.rotationX), -num(after.rotation), num(after.rotationY), 'XYZ')
+  const turnedTo = new THREE.Matrix4().makeRotationFromEuler(euler)
+
+  const before = new THREE.Quaternion().setFromRotationMatrix(rotation)
+  const now = new THREE.Quaternion().setFromEuler(euler)
+  const turned = before.angleTo(now) > 1e-4
+  const sized = [scale.x, scale.y, scale.z].some(s => Math.abs(s - 1) > 1e-4)
+  /* The origin that puts the (scaled, turned) box centre where the scene has it. */
+  const newOrigin = world.clone().sub(centre.clone().multiply(scale).applyMatrix4(turnedTo))
+  const moved = newOrigin.distanceTo(origin) > 0.5
+
+  const result: GizmoResult = {}
+  if (moved || turned) result.position = newOrigin.toArray() as [number, number, number]
+  if (turned) result.rotation = [euler.x, euler.y, euler.z].map(THREE.MathUtils.radToDeg) as [number, number, number]
+  if (sized) result.scale = scale.toArray() as [number, number, number]
+  return result
+}
+
+/** The keys of `next` whose values differ from `current` -- only those are set, so the scene raises no echo. */
+export function changedKeys(current: Record<string, unknown>, next: Record<string, unknown>): Record<string, unknown> | null {
+  const diff: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(next)) {
+    if (key === 'type') continue
+    const was = current[key]
+    const same = typeof value === 'object' && value !== null ? JSON.stringify(was) === JSON.stringify(value) : was === value
+    if (!same) diff[key] = value
+  }
+  return Object.keys(diff).length ? diff : null
+}
+
+/** A board wide and deep enough for the figure, with room around it; its size only grows while a figure is edited. */
+export function boardFor(parts: readonly V3RenderPart[], at: Board & { depth?: number } = { width: 0, height: 0 }): Board & { depth: number } {
+  const box = new THREE.Box3()
+  for (const part of parts) {
+    const frame = frameOf(part)
+    if (!frame) continue
+    const half = frame.extent.clone().multiplyScalar(0.5)
+    const corners = [-1, 1].flatMap(x => [-1, 1].flatMap(y => [-1, 1].map(z => new THREE.Vector3(x * half.x, y * half.y, z * half.z))))
+    for (const corner of corners) box.expandByPoint(corner.add(frame.centre).applyMatrix4(frame.rotation).add(frame.origin))
+  }
+  const size = box.isEmpty() ? new THREE.Vector3(1000, 1000, 1000) : box.getSize(new THREE.Vector3())
+  const reach = (axis: 'x' | 'z') => 2 * Math.max(Math.abs(box.isEmpty() ? 500 : box.min[axis]), Math.abs(box.isEmpty() ? 500 : box.max[axis]))
+  return {
+    width: Math.max(at.width, Math.ceil(reach('x') * 1.2), 200),
+    height: Math.max(at.height, Math.ceil(reach('z') * 1.2), 200),
+    /* Only grows, as the plan does: a raised arm made the board taller than it was, and a new board lost the camera. */
+    depth: Math.max(at.depth ?? 0, Math.ceil(size.y * 1.1), 200)
+  }
+}