@things-factory/figure-ui 10.1.147 → 10.1.149

package/client/modeller/figure-slot-layout-panel.ts

@@ -0,0 +1,208 @@
+import { css, html, LitElement, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { i18next, localize } from '@operato/i18n'
+import '@material/web/icon/icon.js'
+import '@operato/slot-layout-editor'
+import { compileFigureAsset, type FigureAsset, type SlotLayout } from '@hatiolab/figure-model'
+
+import {
+  anchorFacesOf,
+  anchorIdFor,
+  figureSlotIssues,
+  slotLayoutCommandOf,
+  slotLayoutFormOf,
+  slotPresetsOf,
+  type SlotAnchor,
+  type SlotAnchorFace,
+  type SlotLayoutForm
+} from './slot-layout-host.js'
+
+/**
+ * A figure's slot layout (ADR-0118): places made by a rule -- anchors on parts' tops or bottoms, tiers on them, slots in
+ * the tiers. The tiers and slots are edited in the shared editor (`ox-slot-layout-editor`, the one fmsim hosts); this
+ * panel owns what only the modeller knows: which part's face each anchor is, the layout's name and what its slots are.
+ * Every change goes out as one `set-slot-layout` command -- one step of the history, refused by figure-model in its words.
+ *
+ * The layout here is the only one: a scene or a run never overrides it (ADR-0118 decision 8), so there is no "default".
+ */
+@customElement('figure-slot-layout-panel')
+export class FigureSlotLayoutPanel extends localize(i18next)(LitElement) {
+  static styles = css`
+    :host {
+      display: flex;
+      flex-direction: column;
+      gap: 6px;
+    }
+    div[form] {
+      display: grid;
+      grid-template-columns: auto 1fr;
+      gap: 4px 8px;
+      align-items: center;
+    }
+    ul {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+    }
+    li {
+      display: grid;
+      grid-template-columns: 1fr 1fr auto auto;
+      gap: 4px;
+      align-items: center;
+    }
+    input,
+    select {
+      min-width: 0;
+      font: inherit;
+    }
+    div[actions] {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 4px;
+    }
+    button {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      font: inherit;
+    }
+    md-icon {
+      --md-icon-size: 16px;
+    }
+    small[hint] {
+      color: var(--md-sys-color-on-surface-variant);
+    }
+  `
+
+  @property({ attribute: false }) asset?: FigureAsset
+  /** The part selected on the canvas: what a new anchor stands on. */
+  @property() partId = ''
+  @property({ type: Boolean }) locked = false
+
+  /** The name, role and anchors being edited; started again from the figure whenever the figure changes. */
+  @state() private form?: SlotLayoutForm
+  private formFor?: FigureAsset
+  private options?: { key: string; asset: FigureAsset; value: object }
+  /*
+    The figure's layout, read once per figure: the editor starts its draft again whenever its value changes, so a value
+    read again every render would throw the author's edits away.
+  */
+  private stored?: ReturnType<typeof slotLayoutFormOf>
+
+  willUpdate() {
+    /* A figure changed under the panel (an undo, another edit): what is shown is the figure's, not an old draft. */
+    if (this.asset !== this.formFor) {
+      this.formFor = this.asset
+      this.stored = this.asset ? slotLayoutFormOf(this.asset, this.partId) : undefined
+      this.form = this.stored?.form
+    }
+  }
+
+  render() {
+    const asset = this.asset
+    const stored = this.stored
+    const form = this.form
+    if (!asset || !stored || !form) return nothing
+    const parts = asset.document.model.nodes.filter(n => n.op === 'place@1').map(n => n.id)
+    const changed = JSON.stringify(form) !== JSON.stringify(stored.form)
+    return html`
+      <div form>
+        <span>${i18next.t('figure.label.slot-layout-name')}</span>
+        <input .value=${form.label} placeholder=${i18next.t('figure.label.slot-layout')} ?disabled=${this.locked} @change=${(e: Event) => this.edit({ label: (e.target as HTMLInputElement).value })} />
+        <span>${i18next.t('figure.label.slot-layout-role')}</span>
+        <select ?disabled=${this.locked} @change=${(e: Event) => this.edit({ role: (e.target as HTMLSelectElement).value as 'seat' | 'grip' })}>
+          <option value="seat" ?selected=${form.role === 'seat'}>${i18next.t('figure.label.place-seat')}</option>
+          <option value="grip" ?selected=${form.role === 'grip'}>${i18next.t('figure.label.place-grip')}</option>
+        </select>
+      </div>
+
+      <h4>${i18next.t('figure.label.slot-anchors')}</h4>
+      <ul>
+        ${form.anchors.map(
+          (a, i) => html`<li>
+            <input .value=${a.id} aria-label=${i18next.t('figure.label.slot-anchor-id')} ?disabled=${this.locked} @change=${(e: Event) => this.anchor(i, { id: (e.target as HTMLInputElement).value.trim() })} />
+            <select aria-label=${i18next.t('figure.label.part')} ?disabled=${this.locked} @change=${(e: Event) => this.anchor(i, { part: (e.target as HTMLSelectElement).value })}>
+              ${parts.map(p => html`<option value=${p} ?selected=${p === a.part}>${p}</option>`)}
+            </select>
+            <select aria-label=${i18next.t('figure.label.face')} ?disabled=${this.locked} @change=${(e: Event) => this.anchor(i, { face: (e.target as HTMLSelectElement).value as SlotAnchorFace })}>
+              ${(['top', 'bottom'] as const).map(f => html`<option value=${f} ?selected=${f === a.face}>${i18next.t('figure.label.face-' + f)}</option>`)}
+            </select>
+            <button ?disabled=${this.locked || form.anchors.length <= 1} title=${i18next.t('figure.button.remove-slot-anchor')} @click=${() => this.edit({ anchors: form.anchors.filter((_, k) => k !== i) })}>
+              <md-icon>close</md-icon>
+            </button>
+          </li>`
+        )}
+      </ul>
+      <div actions>
+        ${(['top', 'bottom'] as const).map(
+          face => html`<button ?disabled=${this.locked || !this.partId} @click=${() => this.addAnchor(face)}>
+            <md-icon>add</md-icon>${i18next.t(face === 'top' ? 'figure.button.add-slot-anchor-top' : 'figure.button.add-slot-anchor-bottom', { part: this.partId })}
+          </button>`
+        )}
+      </div>
+      <small hint>${i18next.t('figure.text.slot-anchor-pick')}</small>
+
+      <ox-slot-layout-editor .value=${stored.layout} .options=${this.editorOptions(asset, form, stored.layout)} @change=${(e: Event) => this.apply((e.target as { value?: SlotLayout }).value)}></ox-slot-layout-editor>
+
+      <div actions>
+        ${stored.layout && changed
+          ? html`<button ?disabled=${this.locked} @click=${() => this.apply(stored.layout)}><md-icon>check</md-icon>${i18next.t('figure.button.apply-slot-anchors')}</button>`
+          : nothing}
+        ${stored.layout
+          ? html`<button ?disabled=${this.locked} @click=${() => this.command({ kind: 'remove-slot-layout' })}><md-icon>delete</md-icon>${i18next.t('figure.button.remove-slot-layout')}</button>`
+          : nothing}
+      </div>
+    `
+  }
+
+  /*
+    The editor's options, made again only when what they are made from changes: the editor starts its draft again when its
+    starting layout changes, so a new object every render would throw the author's edits away.
+  */
+  private editorOptions(asset: FigureAsset, form: SlotLayoutForm, layout: SlotLayout | undefined) {
+    const key = JSON.stringify([form.anchors, !!layout])
+    if (this.options?.key === key && this.options.asset === asset) return this.options.value
+    const geometry = compileFigureAsset(asset).evaluate().geometry as never
+    const anchorFaces = anchorFacesOf(form.anchors, geometry)
+    const value = {
+      canUseDefault: false,
+      presets: slotPresetsOf(form.anchors, key => i18next.t(key)),
+      /* The first anchor's face is the size a preset is laid out over; the slot height is the author's. */
+      presetSize: anchorFaces[form.anchors[0]?.id ?? ''] ?? {},
+      anchors: form.anchors.map(a => ({ id: a.id, label: `${a.id} · ${a.part} ${i18next.t('figure.label.face-' + a.face)}` })),
+      anchorFaces,
+      validate: (layout: SlotLayout) => figureSlotIssues(layout, form.anchors.map(a => a.id)),
+      issueText: (issue: { code: string; path: string }) =>
+        issue.code === 'ACCEPTS_REQUIRED' ? `${issue.path}: ${i18next.t('figure.text.slot-accepts-required')}` : undefined
+    }
+    this.options = { key, asset, value }
+    return value
+  }
+
+  private edit(patch: Partial<SlotLayoutForm>) {
+    this.form = { ...this.form!, ...patch }
+  }
+
+  private anchor(i: number, patch: Partial<SlotAnchor>) {
+    this.edit({ anchors: this.form!.anchors.map((a, k) => (k === i ? { ...a, ...patch } : a)) })
+  }
+
+  /** A new anchor on the selected part's face: what an author picks on the canvas comes here. */
+  private addAnchor(face: SlotAnchorFace) {
+    const anchors = this.form!.anchors
+    this.edit({ anchors: [...anchors, { id: anchorIdFor(this.partId, anchors.map(a => a.id)), part: this.partId, face }] })
+  }
+
+  /** The whole layout with the anchors and name as they stand: one command, one step. */
+  private apply(layout: SlotLayout | undefined) {
+    if (!layout || !this.form) return
+    this.command(slotLayoutCommandOf(this.form, layout, i18next.t('figure.label.slot-layout')))
+  }
+
+  private command(action: object) {
+    this.dispatchEvent(new CustomEvent('command', { detail: { action }, bubbles: true, composed: true }))
+  }
+}

package/client/modeller/figure-verdict.ts

@@ -5,7 +5,7 @@ import { customElement, property, state } from 'lit/decorators.js'
 
 import { i18next, localize } from '@operato/i18n'
 import { ScrollbarStyles } from '@operato/styles'
-import { LIMITS, FIGURE_PER_INSTANCE, figureCostOf } from '@hatiolab/figure-model'
+import { LIMITS, FIGURE_PER_INSTANCE } from '@hatiolab/figure-model'
 
 import { inspectFigureDraft } from '../graphql/index.js'
 import type { FigureInspection } from '../types.js'
@@ -13,7 +13,8 @@ import { gateFindingStyles, renderGateFinding } from './gate-findings.js'
 import { MEASURED } from './scene-budget.js'
 import type { FigureRevision } from './revision.js'
 import { SidePanelStyles } from './side-panel-styles.js'
-import { budgetOf, CURVE_SIZE, curveLayout, GRADE_SCALE, shortNumber, figureReportOf } from './maturity.js'
+import { CURVE_SIZE, curveLayout, gradeBoundsOf, shortNumber, verdictMeasureOf } from './maturity.js'
+import { newestAnswer } from './newest-answer.js'
 import type { FigureBudgetUse, FigureMaturityAxis, FigureReport } from './maturity.js'
 
 /** How long an edit settles before the server is asked again. One question per pause, not one per keystroke. */
@@ -400,7 +401,7 @@ export class FigureVerdict extends localize(i18next)(LitElement) {
 
   private timer?: ReturnType<typeof setTimeout>
   /** Answers can come back out of order; only the newest question's answer is shown. */
-  private asked = 0
+  private answers = newestAnswer<FigureInspection>()
 
   disconnectedCallback() {
     clearTimeout(this.timer)
@@ -423,21 +424,11 @@ export class FigureVerdict extends localize(i18next)(LitElement) {
   }
 
   private measure() {
-    let report: FigureReport | undefined
-    let bodies = 0
-    try {
-      const asset = this.revision?.asset
-      const cost = asset ? figureCostOf(asset) : undefined
-      bodies = cost ? cost.groups + cost.hidden : 0
-      report = asset ? figureReportOf(asset) : undefined
-    } catch {
-      /* A source the format refuses has no report; the server's finding below says why. */
-      report = undefined
-    }
+    const { report, bodies, told } = verdictMeasureOf(this.revision?.asset)
     this.report = report
     this.bodies = bodies
     if (!report) this.expanded = false
-    this.dispatchEvent(new CustomEvent('capacity-changed', { detail: { instances: report?.capacity.instances, budget: budgetOf(report) } }))
+    this.dispatchEvent(new CustomEvent('capacity-changed', { detail: told }))
   }
 
   private schedule() {
@@ -450,22 +441,22 @@ export class FigureVerdict extends localize(i18next)(LitElement) {
   }
 
   private async ask() {
-    const question = ++this.asked
     const source = this.revision!.text
     this.asking = true
-    try {
-      const inspection = await inspectFigureDraft(source, this.figureId)
-      if (question !== this.asked) return
-      this.inspection = inspection
-      this.failure = ''
-    } catch (error) {
-      if (question !== this.asked) return
-      /* The server's reason as it gave it — the screen does not make one up. The last answer is dropped with it. */
-      this.inspection = undefined
-      this.failure = error instanceof Error ? error.message : String(error)
-    } finally {
-      if (question === this.asked) this.asking = false
-    }
+    await this.answers(
+      () => inspectFigureDraft(source, this.figureId),
+      outcome => {
+        this.asking = false
+        if ('answer' in outcome) {
+          this.inspection = outcome.answer
+          this.failure = ''
+        } else {
+          /* The server's reason as it gave it — the screen does not make one up. The last answer is dropped with it. */
+          this.inspection = undefined
+          this.failure = outcome.failure instanceof Error ? outcome.failure.message : String(outcome.failure)
+        }
+      }
+    )
   }
 
   render() {
@@ -545,11 +536,10 @@ export class FigureVerdict extends localize(i18next)(LitElement) {
 
   /** A · B · C · D and where this figure stands, drawn from the bounds the grade is computed with. */
   private renderGradeScale(now: string) {
-    const bounds = [...GRADE_SCALE.map(([grade, bound]) => [grade, `≤ ${bound * 100}%`]), ['D', '> 100%']]
     return html`
       <p scale>
         <span>${i18next.t('figure.text.grade-scale-lead')}</span>
-        ${bounds.map(([grade, bound]) => html`<span ?now=${grade === now}><b>${grade}</b> ${bound}</span>`)}
+        ${gradeBoundsOf().map(([grade, bound]) => html`<span ?now=${grade === now}><b>${grade}</b> ${bound}</span>`)}
       </p>
     `
   }

package/client/modeller/first-save.ts

@@ -35,6 +35,29 @@ export function suggestTypeOf(name: string, taken: readonly string[], random: ()
   }
 }
 
+/** The shape of an identifier the modeller offers (`suggestTypeOf`'s random form). */
+const OFFERED = /^fig-[0-9a-z]{6}$/
+
+/**
+ * The identifier the first save's question shows, given the one it opens on (Q-D3). The identifier is not the name:
+ * renaming does not change it, and a retried first save opens on the one answered before. A new one is offered only when
+ * there is none, or when an offered one is found taken -- told by the server, or in the list; one the author typed is
+ * kept as typed, and its refusal said. `suggested` is the identifier now on offer, absent when that is unchanged.
+ */
+export function offeredTypeOf(
+  type: string,
+  name: string,
+  taken: readonly string[],
+  random: () => number = Math.random
+): { type: string; suggested?: string } {
+  const offeredAndTaken = OFFERED.test(type) && taken.includes(type)
+  if (!type || offeredAndTaken) {
+    const made = suggestTypeOf(name, taken, random)
+    return { type: made, suggested: made }
+  }
+  return OFFERED.test(type) ? { type, suggested: type } : { type }
+}
+
 /** Why the first save cannot go on with this type, as an i18n key, or null when it can. */
 export function firstSaveRefusalOf(type: string, taken: readonly string[]): { key: string; type?: string } | null {
   if (!type) return { key: 'figure.text.enter-a-type-name' }

package/client/modeller/links.ts

@@ -1,7 +1,8 @@
 import { FIGURE_FACES, figureShapeFaces, figurePartsExtentOf, compileFigureAsset, figureFollowOf, proposeFigureProportion, defaultInstanceSizeRange, foldInstanceSizeRange, figureAttachmentsOf, figureBindingsOf, figureInstanceSizeLimitsOf, figureFollowableAxesOf, figureShapeProviderOf, figureMimicTermsOf } from '@hatiolab/figure-model'
 import type { FigureFollow, FigureSizeRange } from '@hatiolab/figure-model'
-import type { FigureAsset, FigureBindingPlace, FigureFace, FigureJoint } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureAuthoringAction, FigureBindingPlace, FigureDimensionSource, FigureFace, FigureJoint } from '@hatiolab/figure-model'
 import { startingShapeKindOf } from './starting-shape.js'
+import { boxOf } from './align.js'
 import { graphValuesOf, type FigureRevision } from './revision.js'
 import { jointAxisToken, jointAxisVectorOf, type JointAxisVector } from './joint-axis.js'
 
@@ -178,6 +179,27 @@ export function dimensionNow(revision: FigureRevision, part: string, axis: Axis)
   }
 }
 
+/**
+ * The command a dimension's rule chosen in the size form sends (`choice` as `choiceOf` writes it), or nothing to send.
+ * The measure as it stands decides the numbers: a dimension stops following at it, and a share is taken of it, so
+ * neither choice changes the part's size. A share needs the figure's size on that axis.
+ */
+export function followCommandOf(revision: FigureRevision, part: string, axis: Axis, choice: string, now: Follow): FigureAuthoringAction | undefined {
+  const following = now.of !== 'own'
+  /* The part's own measure on the axis now (a cylinder's radius, not its width), else its extent as drawn. */
+  const current = dimensionNow(revision, part, axis) ?? boxOf(revision, part)?.dims[AXES.indexOf(axis)] ?? 100
+  if (choice === 'own') return following ? { kind: 'unlink-dimension', part, axis, mm: Math.max(1, Math.round(current)) } : undefined
+  const [of, a, b] = choice.split(':')
+  if (of === 'share') {
+    const size = revision.asset.designInputs[`size.${a}`]
+    if (!size) return undefined
+    const times = Math.round((current / size) * 1e6) / 1e6
+    return { kind: 'link-dimension', part, axis, source: { of: 'instance', axis: a as Axis }, times, replace: following }
+  }
+  const source: FigureDimensionSource = of === 'instance' ? { of: 'instance', axis: a as Axis } : { of: 'part', part: a!, axis: b as Axis }
+  return { kind: 'link-dimension', part, axis, source, replace: following }
+}
+
 /**
  * How long a part is along one axis now, as it is drawn: the shape's own measure through figure-model's provider (a
  * cylinder's width is twice its radius), read after any rule it follows -- so a linked measure still says its size.
@@ -290,6 +312,35 @@ export function alignAxesOf(asset: FigureAsset, part: string, target: { part: st
   return AXES.filter(axis => axis !== along).map(axis => ({ axis, edges: !twisted && OUTER[axis].every(f => theirs.has(f) && mine.has(f)) }))
 }
 
+/**
+ * The faces of its own a part may be fastened by: its outer faces -- on the mounting plane only the ones the plane takes
+ * (a bottom or a top on the floor, a back on a wall) -- and, to another part, its centre, which a roller spins about.
+ */
+export function ownFacesOf(asset: FigureAsset, part: string, toPlane: boolean): Array<FigureFace | 'centre'> {
+  const outer = Object.keys(FIGURE_FACES) as FigureFace[]
+  const plane = mountingPlaneOf(asset)
+  return [
+    ...(facesOf(asset, part).filter(face => outer.includes(face as FigureFace) && (!toPlane || plane.faces.includes(face as FigureFace))) as FigureFace[]),
+    ...(toPlane ? [] : (['centre'] as const))
+  ]
+}
+
+/**
+ * The axes across the face the fastening form asks about in rows: only where the face drawing (`view`, its axes) cannot
+ * set the place -- no drawing at all, an axis it does not draw, a place that follows a position field, or one the
+ * figure's size may scale.
+ */
+export function alignRowsOf(
+  asset: FigureAsset,
+  part: string,
+  aim: { part: string; face: string } | 'plane',
+  view: { axes: readonly Axis[] } | undefined,
+  twisted: boolean,
+  alignInput: Partial<Record<Axis, string>> = {}
+): { axis: Axis; edges: boolean }[] {
+  return alignAxesOf(asset, part, aim, twisted).filter(({ axis }) => !view || !view.axes.includes(axis) || !!alignInput[axis] || hasInstanceSize(asset, axis))
+}
+
 /** The controls a part's showing can follow: the figure's state inputs, with their range and label. */
 export function visibilityControlsOf(asset: FigureAsset): Array<{ id: string; unit: string; min: number; max: number; label: string }> {
   const labels = (asset as unknown as { stateInputs?: Record<string, { label?: string }> }).stateInputs ?? {}

package/client/modeller/material-edit.ts

@@ -0,0 +1,38 @@
+import type { FigureMaterial, FigurePartEdit } from '@hatiolab/figure-model'
+
+/*
+ * The edit the material panel (`figure-material-panel`) sends for a change of a part's material: worked out here, apart
+ * from the panel, so what it sends can be read without a screen.
+ */
+
+/** The colours a material is picked from: the app's palette, with the asset's own colours over it. */
+export function offeredPaletteOf(app: Record<string, string>, asset: Record<string, string>): Record<string, string> {
+  return { ...app, ...asset }
+}
+
+/** The glow at an intensity: 0 is no glow at all; a new glow takes the part's own colour until another is picked. */
+export function glowOf(material: FigureMaterial, intensity: number): Partial<FigureMaterial> {
+  return { emissive: intensity > 0 ? { token: material.emissive?.token ?? material.token, intensity, on: true } : undefined }
+}
+
+/**
+ * The material with a change over it, as one `set-material` edit. A field the change empties is left out -- the format
+ * refuses an undefined field. A colour it names that the asset does not carry yet (a new asset carries only its primary
+ * colour) is sent with it, from the colours offered, and added in the same edit.
+ */
+export function materialEditOf(
+  target: string,
+  material: FigureMaterial,
+  patch: Partial<FigureMaterial>,
+  assetPalette: Record<string, string>,
+  offered: Record<string, string>
+): FigurePartEdit {
+  const next: FigureMaterial = { ...material, ...patch }
+  for (const key of Object.keys(next) as (keyof FigureMaterial)[]) if (next[key] === undefined) delete next[key]
+  const palette = Object.fromEntries(
+    [next.token, next.emissive?.token]
+      .filter((token): token is string => !!token && assetPalette[token] === undefined && offered[token] !== undefined)
+      .map(token => [token, offered[token]!])
+  )
+  return { kind: 'set-material', target, material: next, ...(Object.keys(palette).length ? { palette } : {}) }
+}

package/client/modeller/maturity.ts

@@ -50,6 +50,11 @@ import type { FigureCapacity } from './scene-budget.js'
 export { FIGURE_BUDGET_KEYS, FIGURE_GRADE_SCALE as GRADE_SCALE, figureGradeOf as gradeOf }
 export type { FigureBudgetKey, FigureBudgetUse, FigureScore }
 
+/** A · B · C · D as the tab draws its scale: each grade with the bound it is computed with, and D past the last. */
+export function gradeBoundsOf(): [string, string][] {
+  return [...FIGURE_GRADE_SCALE.map(([grade, bound]): [string, string] => [grade, `≤ ${bound * 100}%`]), ['D', '> 100%']]
+}
+
 export type FigureAxisKey = 'scale' | 'consistency' | 'reuse' | 'detail' | 'reactive' | 'readable'
 
 /** One maturity axis. */
@@ -411,6 +416,29 @@ export interface FigureBudgetLine {
   tightest: { key: string; used: number; limit: number }
 }
 
+/**
+ * What the verdict tab measures of the figure on screen once it settles: the report, the bodies there are to fit the
+ * space to (drawn or hidden -- a hidden part is still a part to measure), and what it tells the page: the count for its
+ * tab and the parts list's line, from the same report. A source the format refuses has no report.
+ */
+export function verdictMeasureOf(asset: FigureAsset | undefined): {
+  report?: FigureReport
+  bodies: number
+  told: { instances?: number; budget?: FigureBudgetLine }
+} {
+  let report: FigureReport | undefined
+  let bodies = 0
+  try {
+    const cost = asset ? figureCostOf(asset) : undefined
+    bodies = cost ? cost.groups + cost.hidden : 0
+    report = asset ? figureReportOf(asset) : undefined
+  } catch {
+    /* A source the format refuses has no report; the server's finding says why. */
+    report = undefined
+  }
+  return { report, bodies, told: { instances: report?.capacity.instances, budget: budgetOf(report) } }
+}
+
 export function budgetOf(report: FigureReport | undefined): FigureBudgetLine | undefined {
   if (!report) return undefined
   const { tightest } = report.score

package/client/modeller/mesh-import.ts

@@ -0,0 +1,77 @@
+/*
+ * A GLB made into a mesh part (ADR-0129, figure-model contract §13). The server reads the file when it is uploaded and
+ * answers its hash and what it holds; this turns that answer and the author's choice -- the whole file, or one node of it
+ * -- into the part figure-model adds. Kept free of Lit and the network so node tests read it directly.
+ */
+import type { FigurePrimitiveCreation } from '@hatiolab/figure-model'
+
+type Vec = { x: number; y: number; z: number }
+type Box = { min: Vec; max: Vec }
+
+/** What `uploadFigureMesh` answers: the file's hash and what the server read of it. */
+export interface MeshUpload {
+  hash: string
+  summary: {
+    bounds: Box
+    triangles: number
+    primitives: number
+    unit: 'm'
+    nodes: Array<{
+      index: number
+      name: string
+      parent: number | null
+      bounds: Box | null
+      triangles: number
+      primitives: number
+      position: Vec
+      rotation: Vec
+      refused?: 'no-mesh' | 'sheared'
+    }>
+  }
+}
+
+/** What the author can make a part of: the whole file first, then each node that holds a mesh and has a frame. */
+export function meshChoicesOf(upload: MeshUpload): Array<{ node?: number; name: string; triangles: number }> {
+  return [
+    { name: '', triangles: upload.summary.triangles },
+    ...upload.summary.nodes.filter(n => n.bounds && !n.refused).map(n => ({ node: n.index, name: n.name, triangles: n.triangles }))
+  ]
+}
+
+/** A part id from a node's name: letter-led, letters, digits, `_` and `-`; another number when it is taken. */
+export function meshPartIdOf(name: string, taken: ReadonlySet<string>): string {
+  const cleaned = name.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^[^a-zA-Z]+/, '').replace(/-+$/, '')
+  const base = cleaned || 'mesh'
+  if (!taken.has(base)) return base
+  let n = 2
+  while (taken.has(`${base}-${n}`)) n++
+  return `${base}-${n}`
+}
+
+/**
+ * The part: its bounds and counts as the server read them, its size the reach along its longest axis (so it is 1:1),
+ * and -- for a node -- standing where the node stood in the file, so a crane taken apart node by node stands as it did.
+ */
+export function meshPartOf(upload: MeshUpload, choice: { node?: number }, id: string): FigurePrimitiveCreation {
+  const node = choice.node === undefined ? undefined : upload.summary.nodes.find(n => n.index === choice.node)
+  if (choice.node !== undefined && (!node?.bounds || node.refused)) throw new Error(`node ${choice.node} of the file cannot be a part`)
+  const bounds = node ? node.bounds! : upload.summary.bounds
+  const size = Math.max(bounds.max.x - bounds.min.x, bounds.max.y - bounds.min.y, bounds.max.z - bounds.min.z)
+  const turned = node && (node.rotation.x || node.rotation.y || node.rotation.z)
+  return {
+    kind: 'mesh',
+    id,
+    dimensions: { size },
+    mesh: {
+      asset: upload.hash,
+      format: 'glb',
+      unit: upload.summary.unit,
+      ...(node ? { node: node.index } : {}),
+      bounds,
+      triangles: node ? node.triangles : upload.summary.triangles,
+      primitives: node ? node.primitives : upload.summary.primitives
+    },
+    position: node ? { ...node.position } : { x: 0, y: 0, z: 0 },
+    ...(turned ? { rotation: { ...node!.rotation } } : {})
+  }
+}

package/client/modeller/modeller-route.ts

@@ -7,3 +7,12 @@ export const MODELLER = 'figure-modeller'
 export function modellerPathOf(figure?: { id?: string }): string {
   return figure?.id ? `${MODELLER}/${figure.id}` : MODELLER
 }
+
+/**
+ * Where one released version downloads as a package file, by its release reference {namespace}/{type}@{version}
+ * (ADR-0114) -- or undefined before the figure has a full name.
+ */
+export function packageHrefOf(contextPath: string, namespace: string | null | undefined, type: string | null | undefined, version: number): string | undefined {
+  if (!namespace || !type) return undefined
+  return `${contextPath}/figure-package?refs=${encodeURIComponent(`${namespace}/${type}@${version}`)}`
+}

package/client/modeller/mounting-part.ts

@@ -0,0 +1,15 @@
+import type { FigureFace } from '@hatiolab/figure-model'
+import type { FigureFigureFacts } from './figure-facts.js'
+
+/**
+ * The mounting face the properties tab offers: the part and face picked in its lists, else the one set, else where the
+ * figure meets its plane (`suggested`) -- a conveyor's legs, not its bed (walk 1, 2026-09-26) -- else the first part.
+ * A part no longer in the figure is passed over.
+ */
+export function offeredMountingOf(
+  facts: Pick<FigureFigureFacts, 'parts' | 'mounting' | 'suggested'>,
+  picked: { part?: string; face?: FigureFace } = {}
+): { part?: string; face: FigureFace } {
+  const part = [picked.part, facts.mounting?.part, facts.suggested?.part, facts.parts[0]].find(one => one && facts.parts.includes(one))
+  return { part, face: picked.face ?? facts.mounting?.face ?? facts.suggested?.face ?? 'bottom' }
+}

package/client/modeller/newest-answer.ts

@@ -0,0 +1,21 @@
+/** What came back for a question: its answer, or why there is none. */
+export type FigureOutcome<T> = { answer: T } | { failure: unknown }
+
+/**
+ * Questions asked again while an earlier one is still out (a figure edited while the server judges it): answers can
+ * come back out of order, and only the newest question's lands -- its answer or its failure alike. An older one arriving
+ * late is dropped, so it never covers the newer one.
+ */
+export function newestAnswer<T>() {
+  let asked = 0
+  return async (question: () => Promise<T>, land: (outcome: FigureOutcome<T>) => void): Promise<void> => {
+    const mine = ++asked
+    let outcome: FigureOutcome<T>
+    try {
+      outcome = { answer: await question() }
+    } catch (failure) {
+      outcome = { failure }
+    }
+    if (mine === asked) land(outcome)
+  }
+}

package/client/modeller/preview-model.ts

@@ -5,6 +5,11 @@ import type { FigureAsset } from '@hatiolab/figure-model'
 
 export const PREVIEW_FACTOR = 2
 
+/** The type the preview registers the figure under: this figure's own, never a real type a board uses. */
+export function previewTypeOf(context: string): string {
+  return `figure-preview-${context || 'new'}`
+}
+
 export const PREVIEW_WAYS: readonly { name: string; axes: readonly ('x' | 'y' | 'z')[] }[] = [
   { name: 'base', axes: [] },
   { name: 'x', axes: ['x'] },