@things-factory/figure-ui 10.1.37 → 10.1.39

package/client/modeller/figure-v3-verdict.ts

@@ -0,0 +1,247 @@
+import '@material/web/icon/icon.js'
+
+import { css, html, LitElement, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+
+import { i18next, localize } from '@operato/i18n'
+import { parseV3Asset, v3CostOf } from '@hatiolab/figure-model'
+
+import { inspectFigureDraft } from '../graphql/index.js'
+import type { FigureInspection } from '../types.js'
+import { gateFindingStyles, renderGateFinding } from './gate-findings.js'
+import { capacityFrom, MEASURED } from './scene-budget.js'
+import type { FigureCapacity } from './scene-budget.js'
+
+/** How long an edit settles before the server is asked again. One question per pause, not one per keystroke. */
+export const VERDICT_SETTLE_MS = 400
+
+/**
+ * 판정 — the V3 modeller's verdict while editing (parity row ①).
+ *
+ * The V2 modeller shows, as the author edits, how many of the figure fit on one screen and what would stop it
+ * being published. The V3 page showed neither: the author learned what blocked a release only after saving, in the
+ * release panel. This tab answers both from the source being edited.
+ *
+ * The count is computed here, from `v3CostOf` and the same `capacityFrom` the catalogue cards use, so the tab and
+ * the card cannot disagree. The findings are not: they come from the server's release door (`inspectFigureDraft`),
+ * the same door and the same sentences as the release panel. A second judgement on the screen would say something
+ * different the first time either changed.
+ *
+ * No grade. V2's grade measures V2 reuse; nothing measures it for V3, so the tab shows no letter rather than one
+ * nothing computed.
+ */
+@customElement('figure-v3-verdict')
+export class FigureV3Verdict extends localize(i18next)(LitElement) {
+  static styles = [
+    gateFindingStyles,
+    css`
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: 14px;
+        padding: 12px;
+        overflow: auto;
+        font-size: 0.76rem;
+        color: var(--md-sys-color-on-surface);
+      }
+      section > h3 {
+        margin: 0 0 6px 0;
+        font-size: var(--ui-t-micro, 11px);
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+        color: var(--md-sys-color-on-surface-variant, var(--md-sys-color-on-surface));
+      }
+      p {
+        margin: 4px 0 0;
+      }
+      p[lead],
+      p[basis],
+      p[quiet] {
+        color: var(--md-sys-color-on-surface-variant, var(--md-sys-color-on-surface));
+      }
+      div[count] {
+        display: flex;
+        align-items: baseline;
+        gap: 6px;
+      }
+      span[capacity] {
+        font-size: 2.1rem;
+        font-weight: 800;
+        line-height: 1;
+        letter-spacing: -0.01em;
+        color: var(--md-sys-color-primary);
+      }
+      span[unit] {
+        font-size: 0.9rem;
+        font-weight: 600;
+        color: var(--md-sys-color-primary);
+      }
+      p[clear] {
+        color: var(--md-sys-color-primary);
+        font-weight: 600;
+      }
+      p[failed] {
+        color: var(--md-sys-color-error);
+      }
+      button[fit] {
+        align-self: flex-start;
+        margin-top: 4px;
+        padding: 4px 10px;
+        font: inherit;
+        color: var(--md-sys-color-on-secondary-container);
+        background: var(--md-sys-color-secondary-container);
+        border: none;
+        border-radius: 999em;
+        cursor: pointer;
+      }
+    `
+  ]
+
+  /** The source being edited, serialised. Every change of it is a new question. */
+  @property({ type: String }) source?: string
+  /** The saved row, if any — the server reads its type and last release from it. */
+  @property({ type: String }) figureId?: string
+  /** Changing the type changes the verdict (a temporary type is refused), so it is a reason to ask again. */
+  @property({ type: String }) figureType?: string
+
+  @state() private capacity?: FigureCapacity
+  /** Bodies in the asset, drawn or hidden. With none there is nothing to fit the space to, so the button is not offered. */
+  @state() private bodies = 0
+  @state() private inspection?: FigureInspection
+  @state() private failure = ''
+  @state() private asking = false
+
+  private timer?: ReturnType<typeof setTimeout>
+  /** Answers can come back out of order; only the newest question's answer is shown. */
+  private asked = 0
+
+  disconnectedCallback() {
+    clearTimeout(this.timer)
+    super.disconnectedCallback()
+  }
+
+  updated(changes: Map<string, unknown>) {
+    if (changes.has('source')) this.measure()
+    if (changes.has('source') || changes.has('figureId') || changes.has('figureType')) this.schedule()
+  }
+
+  private measure() {
+    let capacity: FigureCapacity | undefined
+    let bodies = 0
+    try {
+      const cost = this.source ? v3CostOf(parseV3Asset(this.source)) : undefined
+      capacity = cost ? capacityFrom(cost.groups, cost.triangles) : undefined
+      bodies = cost ? cost.groups + cost.hidden : 0
+    } catch {
+      /* A source the format refuses has no count; the server's finding below says why. */
+      capacity = undefined
+    }
+    this.capacity = capacity
+    this.bodies = bodies
+    this.dispatchEvent(new CustomEvent('capacity-changed', { detail: { instances: capacity?.instances } }))
+  }
+
+  private schedule() {
+    clearTimeout(this.timer)
+    if (!this.source) {
+      this.inspection = undefined
+      return
+    }
+    this.timer = setTimeout(() => this.ask(), VERDICT_SETTLE_MS)
+  }
+
+  private async ask() {
+    const question = ++this.asked
+    const source = this.source!
+    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
+    }
+  }
+
+  render() {
+    return html`${this.renderCount()} ${this.renderGate()}`
+  }
+
+  private renderCount() {
+    const capacity = this.capacity
+    return html`
+      <section>
+        <h3>${i18next.t('figure.label.maturity')}</h3>
+        <p lead>${i18next.t('figure.text.how-many-fit')}</p>
+        ${capacity
+          ? html`
+              <div count>
+                <span capacity>${capacity.instances.toLocaleString()}</span>
+                <span unit>${i18next.t('figure.text.instances-unit')}</span>
+              </div>
+              <p basis>
+                ${i18next.t('figure.text.bound-by-' + capacity.bound, {
+                  per: capacity.per.toLocaleString(),
+                  budget: capacity.budget.toLocaleString()
+                })}
+                <em>
+                  ${capacity.bound === 'groups'
+                    ? i18next.t('figure.text.budget-measured-on', { gpu: MEASURED.gpu, on: MEASURED.on })
+                    : i18next.t('figure.text.budget-not-measured-yet')}
+                </em>
+              </p>
+            `
+          : html`<p quiet>${i18next.t('figure.text.maturity-blocked-no-parts')}</p>`}
+      </section>
+    `
+  }
+
+  private renderGate() {
+    const findings = this.inspection?.findings ?? []
+    const blocking = findings.filter(finding => finding.blocking)
+    const advisory = findings.filter(finding => !finding.blocking)
+    return html`
+      <section>
+        <h3>${i18next.t('figure.label.release-verdict')}</h3>
+        ${this.failure
+          ? html`<p failed role="alert">${i18next.t('figure.text.verdict-not-received', { reason: this.failure })}</p>`
+          : !this.inspection
+            ? html`<p quiet>${i18next.t(this.asking ? 'figure.text.verdict-asking' : 'figure.text.verdict-waiting')}</p>`
+            : blocking.length
+              ? html`<p>${i18next.t('figure.text.cannot-release-now')}</p>`
+              : html`<p clear>${i18next.t('figure.text.nothing-blocks-release')}</p>`}
+        ${blocking.length
+          ? html`<ul gate>
+              <li head>${i18next.t('figure.text.must-fix-to-release')}</li>
+              ${blocking.map(finding => renderGateFinding(finding, true, this.actionsFor(finding.code)))}
+            </ul>`
+          : nothing}
+        ${advisory.length
+          ? html`<ul gate>
+              <li head quiet>${i18next.t('figure.text.does-not-block')}</li>
+              ${advisory.map(finding => renderGateFinding(finding, false))}
+            </ul>`
+          : nothing}
+      </section>
+    `
+  }
+
+  /** The same way out the release panel offers for the same two findings — declare the space from the parts. */
+  private actionsFor(code: string) {
+    if (code !== 'part-outside-occupancy' && code !== 'occupancy-undeclared') return nothing
+    /* A new figure with no parts is refused as undeclared too, but fitting needs parts to measure (seen 2026-09-24). */
+    if (!this.bodies) return nothing
+    return html`<button fit @click=${this.fit}>${i18next.t('figure.button.fit-base-to-parts')}</button>`
+  }
+
+  private fit = () => {
+    this.dispatchEvent(new CustomEvent('fit-base-to-parts', { bubbles: true, composed: true }))
+  }
+}

package/client/modeller/gate-findings.ts

@@ -0,0 +1,105 @@
+import { css, html, nothing, type TemplateResult } from 'lit'
+import { i18next } from '@operato/i18n'
+
+import type { FigureGateFinding } from '../types.js'
+
+/**
+ * One release-gate finding as a line on screen — the measured fact, where, why it matters, and what to change.
+ *
+ * Two places draw these: the release panel (`figure-history-panel`) and the V3 modeller's verdict while editing
+ * (`figure-v3-verdict`). They show the same findings from the same server door, so they draw them one way; a copy
+ * in each would drift the first time one of them is touched. The caller passes its own action buttons, because
+ * what can be done about a finding depends on the screen it is shown on.
+ */
+export function renderGateFinding(finding: FigureGateFinding, blocking: boolean, actions: unknown = nothing): TemplateResult {
+  return html`
+    <li finding ?blocking=${blocking}>
+      <span msg>${finding.message}</span>
+      ${finding.at
+        ? html`
+            <details affected>
+              <summary>${i18next.t('figure.text.show-affected-parts')}</summary>
+              <code where>${finding.at}</code>
+            </details>
+          `
+        : nothing}
+      ${finding.why ? html`<span why-line>${finding.why}</span>` : nothing}
+      ${finding.how ? html`<span how-line><md-icon>build</md-icon>${finding.how}</span>` : nothing}
+      ${actions}
+    </li>
+  `
+}
+
+export const gateFindingStyles = css`
+    ul[gate] {
+      margin: var(--spacing-small, 6px) 0 0;
+      padding: 0;
+      list-style: none;
+      display: flex;
+      flex-direction: column;
+      gap: 3px;
+    }
+
+    li[head] {
+      font: var(--label-font, inherit);
+      font-size: 0.72rem;
+      color: var(--md-sys-color-error);
+    }
+
+    li[head][quiet] {
+      color: var(--md-sys-color-on-surface-variant, var(--md-sys-color-on-surface));
+    }
+
+    li[finding] {
+      display: flex;
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 3px;
+      padding: 3px 6px;
+      font-size: 0.72rem;
+      line-height: 1.5;
+      color: var(--md-sys-color-on-surface-variant, var(--md-sys-color-on-surface));
+      background-color: var(--md-sys-color-surface-container);
+      border-radius: 4px;
+    }
+
+    li[finding][blocking] {
+      color: var(--md-sys-color-on-error-container, var(--md-sys-color-on-surface));
+      background-color: var(--md-sys-color-error-container);
+    }
+
+    li[finding] code[where] {
+      font-family: var(--mono-font, monospace);
+      font-size: 0.68rem;
+      opacity: 0.85;
+    }
+
+    li[finding] details[affected] {
+      width: 100%;
+      color: inherit;
+    }
+
+    li[finding] details[affected] summary {
+      cursor: pointer;
+      font-weight: 600;
+    }
+
+    /* 왜 나쁜지는 곁글로 — 읽어야 하지만 잰 것보다 먼저 눈에 들 필요는 없다 */
+    li[finding] span[why-line] {
+      opacity: 0.8;
+    }
+
+    /* 무엇을 바꾸면 되나 — 이 줄이 실제로 사람이 할 일이다. 연장 표를 달아 눈에 걸리게 한다 */
+    li[finding] span[how-line] {
+      display: flex;
+      align-items: flex-start;
+      gap: 4px;
+      padding-top: 2px;
+      font-weight: 600;
+    }
+    li[finding] span[how-line] md-icon {
+      --md-icon-size: 13px;
+      flex: none;
+      margin-top: 1px;
+    }
+`

package/client/modeller/v3-editor.ts

@@ -2,6 +2,8 @@ import { LitElement, html, css, type PropertyValues } from 'lit'
 import { customElement, property, state } from 'lit/decorators.js'
 import type { V3InputChange, V3PrimitiveCreation } from '@hatiolab/figure-model'
 import type { V3ProductSession } from './v3-product-session.js'
+import { captureV3Thumbnail } from './v3-thumbnail.js'
+import { drawableV3Parts } from './v3-renderer.js'
 import './v3-canvas.js'
 import type { FigureV3Canvas } from './v3-canvas.js'
 
@@ -172,7 +174,14 @@ export class FigureV3Editor extends LitElement {
   private async save() {
     if (!this.session) return
     try {
-      const promise = this.session.save()
+      /*
+        The card's picture is taken before the save starts, from a canvas of its own at the card's size —
+        not from the one on screen, which stands wherever the author left it turned. A picture that cannot
+        be taken is not an error: the save goes on without it (see `v3-thumbnail.ts`).
+      */
+      const view = this.session.read()
+      const thumbnail = await captureV3Thumbnail(drawableV3Parts(view.geometry ?? []), view.palette ?? {})
+      const promise = this.session.save({ thumbnail })
       this.changed()
       await promise
       this.error = ''
@@ -274,7 +283,7 @@ export class FigureV3Editor extends LitElement {
           </div>
         </aside>
         <figure-v3-canvas
-          .parts=${view.geometry}
+          .parts=${drawableV3Parts(view.geometry ?? [])}
           .palette=${view.palette ?? {}}
           .context=${view.context ?? ''}
           @part-selected=${(e: CustomEvent<string>) => {

package/client/modeller/v3-occupancy.ts

@@ -0,0 +1,22 @@
+import { parseV3Asset, proposeV3Occupancy, type V3AuthoringAction } from '@hatiolab/figure-model'
+
+/**
+ * 「부품에 맞추기」의 V3 짝 — 공간을 지금 부품에서 다시 선언하는 한 걸음.
+ *
+ * figure-model 은 이것을 둘로 나눠 두었다: 제안(`proposeV3Occupancy`)은 무엇이 선언될지를 보여 주고, 확인
+ * (`declare-occupancy`)은 그 제안이 읽은 모양 그대로일 때만 받는다. 저작자가 누른 단추가 그 확인이다. 제안과 확인
+ * 사이에 모델이 바뀌면 figure-model 이 `OCCUPANCY_STALE` 로 거절하므로, 여기서는 누른 순간의 원본으로 둘을 한
+ * 번에 만든다.
+ *
+ * 범위는 움직임 전체다(`over: 'range'`). 쉬는 자세만 담으면 움직이는 부품이 선언한 공간을 넘어 발행 판정이 다시
+ * 막는다. 배치 기준은 이미 선언된 것을 지키고, 처음 선언하는 도형은 바닥에 선다고 둔다 — 새로 만든 도형의
+ * 모델러 기본이 바닥이다.
+ */
+export function occupancyFromParts(source: string): V3AuthoringAction {
+  const asset = parseV3Asset(source)
+  return {
+    kind: 'declare-occupancy',
+    proposal: proposeV3Occupancy(asset, { over: 'range' }),
+    placement: asset.occupancy?.placement ?? 'floor'
+  }
+}

package/client/modeller/v3-product-session.ts

@@ -5,7 +5,8 @@ import {
   parseV3Asset,
   type V3InputChange,
   type V3PrimitiveCreation,
-  type V3PartEdit
+  type V3PartEdit,
+  type V3AuthoringAction
 } from '@hatiolab/figure-model'
 
 export interface V3ProductRecord {
@@ -16,7 +17,14 @@ export interface V3ProductRecord {
 /** Persistence is injected; neither the model engine nor the renderer owns the product ID. */
 export interface V3ProductStore {
   load(id: string): Promise<V3ProductRecord>
-  save(request: { id?: string; source: string; expectedSource?: string; creationId?: string }): Promise<V3ProductRecord>
+  save(request: {
+    id?: string
+    source: string
+    expectedSource?: string
+    creationId?: string
+    /** The card's picture. Absent when the browser could not draw one; the source is saved either way. */
+    thumbnail?: string
+  }): Promise<V3ProductRecord>
 }
 
 /** Product lifecycle boundary. A late response can never change another editor's asset or ID. */
@@ -107,6 +115,10 @@ export function createV3ProductSession(store: V3ProductStore) {
     edit(edit: V3PartEdit) {
       return workspace.editPart({ ...writable(), edit })
     },
+    /** One authoring command — what a person means, not a graph edit — as one step of the same history. */
+    command(action: V3AuthoringAction) {
+      return workspace.command({ ...writable(), action })
+    },
     undo() {
       return workspace.undo(writable())
     },
@@ -117,13 +129,20 @@ export function createV3ProductSession(store: V3ProductStore) {
       const { context } = writable()
       return workspace.export({ context }).text
     },
-    async save() {
+    /**
+     * Saves the model, and the card's picture when the caller managed to take one.
+     *
+     * The picture is the caller's because taking it needs a canvas, and this session is the place that knows
+     * nothing about drawing. A save with no picture is a save: a tab in the background cannot draw, and the
+     * source matters more than the card (see `v3-thumbnail.ts`).
+     */
+    async save({ thumbnail }: { thumbnail?: string } = {}) {
       const control = writable(),
         requestEpoch = epoch
       const exported = workspace.export(control)
       saving = true
       try {
-        const record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId })
+        const record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId, thumbnail })
         if (requestEpoch !== epoch) return read()
         if (!record.id || (id !== undefined && record.id !== id)) throw Error('저장 응답의 Figure 대상이 다릅니다.')
         if (serializeV3Asset(parseV3Asset(record.source)) !== exported.text)

package/client/modeller/v3-renderer.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three'
+import { buildV3Geometry } from '@hatiolab/things-scene'
 
 /** Evaluated V3 boundary: graph values are resolved before reaching the renderer. */
 export interface V3RenderPart {
@@ -9,24 +10,32 @@ export interface V3RenderPart {
   segments?:number
 }
 
-function geometry(part:V3RenderPart):THREE.BufferGeometry {
- const d=part.shape.dimensions
- let g:THREE.BufferGeometry
- if(part.shape.provider==='box')g=new THREE.BoxGeometry(d.width,d.height,d.depth)
- else if(part.shape.provider==='cylinder')g=new THREE.CylinderGeometry(d.radius,d.radius,d.length,part.segments??12)
- else if(part.shape.provider==='roundedBox'){
-  const w=d.width/2,z=d.depth/2,r=d.round,s=new THREE.Shape()
-  s.moveTo(-w+r,-z);s.lineTo(w-r,-z);s.quadraticCurveTo(w,-z,w,-z+r)
-  s.lineTo(w,z-r);s.quadraticCurveTo(w,z,w-r,z);s.lineTo(-w+r,z)
-  s.quadraticCurveTo(-w,z,-w,z-r);s.lineTo(-w,-z+r);s.quadraticCurveTo(-w,-z,-w+r,-z)
-  g=new THREE.ExtrudeGeometry(s,{depth:d.height,bevelEnabled:false,steps:1,curveSegments:6})
-  g.rotateX(Math.PI/2);g.translate(0,d.height/2,0)
- }else if(part.shape.provider==='portal'){
-  if(!part.shape.profile?.length)throw Error('Portal profile is missing')
-  const s=new THREE.Shape(part.shape.profile.map(p=>new THREE.Vector2(p.x,p.y)))
-  g=new THREE.ExtrudeGeometry(s,{depth:d.depth,bevelEnabled:false,steps:1});g.translate(0,0,-d.depth/2)
- }else throw Error('Unsupported V3 provider: '+part.shape.provider)
- return g
+/**
+ * The bodies a canvas draws, out of everything the asset evaluated.
+ *
+ * Two are left out. A scalar body carries no shape or pose — it is a number the graph produced, not something
+ * on screen. A body the asset hides is evaluated, placed and gated exactly as a shown one, and excluded from
+ * rendering, from shadows and from pointer picking (V3 designer's ruling 2026-09-22); drawing it would make
+ * "hidden" mean nothing in the modeller while it means something on a board.
+ */
+export function drawableV3Parts(geometry: readonly unknown[]): V3RenderPart[] {
+  return geometry.filter(
+    (body): body is V3RenderPart =>
+      !!body && typeof body === 'object' && 'shape' in body && 'pose' in body && (body as { visible?: boolean }).visible !== false
+  )
+}
+
+/**
+ * The mesh for one body — things-scene's builder, not a copy of it.
+ *
+ * The modeller kept its own provider switch and it knew four providers; the converter writes eleven. A body the
+ * board drew was refused here with "Unsupported V3 provider: roundedBoxXZ" (2026-09-24, the first canvas check of
+ * ADR-0087 step 4). One builder, and the canvas an author looks at shows what a board will show.
+ */
+function geometry(part: V3RenderPart): THREE.BufferGeometry {
+  const built = buildV3Geometry(part.shape as never, part.segments ?? 12) as THREE.BufferGeometry | undefined
+  if (!built) throw Error('Unsupported V3 provider: ' + part.shape.provider)
+  return built
 }
 
 export function disposeV3Meshes(group:THREE.Group):void {

package/client/modeller/v3-thumbnail.ts

@@ -0,0 +1,97 @@
+import './v3-canvas.js'
+
+import type { V3RenderPart } from './v3-renderer.js'
+
+/**
+ * 카드에 쓸 그림을 찍는다 — **숨은 자리에 V3 캔버스를 하나 더 세워서.**
+ *
+ * V2 의 `figure-thumbnail.ts` 와 같은 규율이고, 까닭도 같다.
+ *
+ * ## 왜 보이는 캔버스를 찍지 않나
+ *
+ * 저작면의 캔버스는 저작자가 돌려 둔 각도와 확대로 서 있다. 그것을 찍으면 카드마다 프레임이
+ * 달라지고, 방금 확대해 보던 나사 하나가 그 자산의 얼굴이 된다. 목록은 견주는 자리이므로 그림은
+ * **정해진 크기와 정해진 카메라**로 찍는다. `figure-v3-canvas` 의 `thumbnail()` 은 보이는 캔버스를
+ * 그대로 뽑으므로 카드용이 아니다 — 여기서는 새로 세운 캔버스가 스스로 `fit()` 한 자리에서 찍는다.
+ *
+ * ## 왜 서버가 아니라 브라우저인가
+ *
+ * 백엔드에 GPU 가 없는 배포가 많아 헤드리스로 3D 를 찍는 것이 자주 실패한다. 도형을 그릴 GPU 는
+ * 이미 보는 사람 손에 있다.
+ *
+ * ## 못 찍어도 저장은 간다
+ *
+ * 탭이 뒤로 가면 브라우저가 `requestAnimationFrame` 을 멈춘다. 그 위에 저장이 얹혀 있으면 저장이
+ * 통째로 멈춘다 — 단추는 잠긴 채로, 아무 말도 없이. 그래서 시계와 경주시키고, 늦으면 그림 없이
+ * 간다. 정본이 그림보다 중하고, 그림은 다음에 저작면을 열 때 다시 채운다.
+ */
+
+/** 카드는 4:3 이다. V2 와 같은 크기 — 목록에 두 판이 섞여 있어도 카드가 고르다. */
+const WIDTH = 480
+const HEIGHT = 360
+
+/** 넘으면 그림 없이 저장한다. 빠르기가 아니라 저장이 멈추지 않는 것이 목적이다. */
+const PATIENCE = 5000
+
+interface Shooter extends HTMLElement {
+  parts?: V3RenderPart[]
+  palette?: Record<string, string>
+  context?: string
+  thumbnail?: () => string | undefined
+  fit?: () => void
+}
+
+const delay = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))
+
+/** 씬이 서고 카메라가 자리를 잡을 틈. rAF 가 멈춘 탭에서도 풀리도록 시계와 경주시킨다. */
+function settle(): Promise<void> {
+  const frames = new Promise<void>(resolve =>
+    requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(resolve, 150)))
+  )
+  return Promise.race([frames, delay(600)])
+}
+
+function within<T>(work: Promise<T>, ms: number): Promise<T | undefined> {
+  return Promise.race([work, delay(ms).then(() => undefined)])
+}
+
+export async function captureV3Thumbnail(
+  parts: V3RenderPart[],
+  palette: Record<string, string>
+): Promise<string | undefined> {
+  if (!parts.length) return undefined
+
+  /*
+    화면 밖에 둔다. `display: none` 이면 캔버스가 크기를 못 얻어 아무것도 그리지 못한다.
+    WebGL context 는 브라우저가 8~16개에서 끊으므로 찍은 뒤 반드시 버린다(아래 finally).
+  */
+  const host = document.createElement('div')
+  host.setAttribute('figure-v3-thumbnail-stage', '')
+  host.style.cssText = `position: fixed; left: -10000px; top: 0; width: ${WIDTH}px; height: ${HEIGHT}px; pointer-events: none;`
+  document.body.appendChild(host)
+
+  const shooter = document.createElement('figure-v3-canvas') as Shooter
+  shooter.parts = parts
+  shooter.palette = palette
+  shooter.context = 'thumbnail'
+  shooter.style.cssText = 'display: block; width: 100%; height: 100%;'
+
+  try {
+    host.appendChild(shooter)
+    const shot = await within(
+      (async () => {
+        await settle()
+        shooter.fit?.()
+        return shooter.thumbnail?.()
+      })(),
+      PATIENCE
+    )
+    if (!shot) console.warn(`[thumbnail] ${PATIENCE}ms 안에 못 찍었습니다 — 그림 없이 저장합니다`)
+    return shot
+  } catch (e) {
+    console.warn(`[thumbnail] 세우지 못했습니다 — ${(e as Error).message}`)
+    return undefined
+  } finally {
+    host.remove()
+  }
+}