@things-factory/figure-ui 10.1.81 → 10.1.83

package/client/figure-assistant.ts

@@ -23,8 +23,8 @@ registerProposalHandler(FIGURE_CANDIDATE_TOOL, async (proposal, context) => {
         window.dispatchEvent(new CustomEvent('figure-apply', { detail }))
         return detail
       },
-      openNew(steps) {
-        const opened = pendNewFigure(steps)
+      openNew(steps, key) {
+        const opened = pendNewFigure(steps, key)
         navigate(modellerPathOf())
         return opened
       }

package/client/graphql/index.ts

@@ -2,6 +2,8 @@ import gql from 'graphql-tag'
 import { i18next } from '@operato/i18n'
 import { client } from '@operato/graphql'
 
+import { reached, refusedIn } from './reached.js'
+
 import type {
   Figure,
   FigureFinding,
@@ -208,21 +210,108 @@ export async function releaseFigure(id: string, comment?: string): Promise<Figur
   return unwrap<Figure>(response, 'releaseFigure')
 }
 
-/** 옛 판을 초안으로 되살린다. 정본·속성·그림이 돌아오고 이름·설명은 그대로다. */
-export async function revertFigureVersion(id: string, version: number): Promise<SaveResult> {
-  const response = await client.mutate({
-    mutation: gql`
-      mutation RevertFigureVersion($id: String!, $version: Float!) {
-        revertFigureVersion(id: $id, version: $version) {
-          figure { ${FIGURE_LIST_FIELDS} source }
-          violations { code message at }
+/** A draft a revert kept when it wrote over it (ADR-0097 §5.6). Not a released version. */
+export interface KeptDraft {
+  id: string
+  kind: 'revert' | 'undo'
+  state?: string
+  version?: number
+  revertedToVersion?: number
+  restoredAt?: string
+  createdAt?: string
+  creator?: { name?: string }
+}
+
+const KEPT_FIELDS = `id kind state version revertedToVersion restoredAt createdAt creator { name }`
+
+/**
+ * 옛 판을 초안으로 되살린다. 정본·속성·그림이 돌아오고 이름·설명은 그대로다. 덮이는 초안은 같은 트랜잭션에서 서버가
+ * 보관한다. `expectedSource` 는 서버가 들고 있다고 확인된 정본 -- 그 사이 바뀌었으면 거절된다. 답을 못 받았으면
+ * (REVERT_UNREACHABLE) 같은 `requestId` 로 다시 묻는다: 서버는 같은 되돌리기로 답하고 두 번 하지 않는다.
+ */
+export async function revertFigureVersion(
+  id: string,
+  version: number,
+  requestId: string,
+  expectedSource: string
+): Promise<SaveResult & { kept: KeptDraft }> {
+  const response = await reached(
+    client.mutate({
+      mutation: gql`
+        mutation RevertFigureVersion($id: String!, $version: Float!, $requestId: String!, $expectedSource: String!) {
+          revertFigureVersion(id: $id, version: $version, requestId: $requestId, expectedSource: $expectedSource) {
+            figure { ${FIGURE_LIST_FIELDS} source }
+            violations { code message at }
+            kept { ${KEPT_FIELDS} }
+          }
+        }
+      `,
+      variables: { id, version, requestId, expectedSource }
+    }),
+    'REVERT_UNREACHABLE'
+  )
+  refusedIn(response)
+  return unwrap<SaveResult & { kept: KeptDraft }>(response, 'revertFigureVersion')
+}
+
+/** 되돌리기 취소 -- 보관한 초안을 되살린다. 되돌린 뒤 모델이 바뀌었으면 서버가 거절하고 보관본은 남는다. */
+export async function undoFigureRevert(keptId: string, requestId: string): Promise<SaveResult & { kept: KeptDraft }> {
+  const response = await reached(
+    client.mutate({
+      mutation: gql`
+        mutation UndoFigureRevert($keptId: String!, $requestId: String!) {
+          undoFigureRevert(keptId: $keptId, requestId: $requestId) {
+            figure { ${FIGURE_LIST_FIELDS} source }
+            violations { code message at }
+            kept { ${KEPT_FIELDS} }
+          }
         }
+      `,
+      variables: { keptId, requestId }
+    }),
+    'REVERT_UNREACHABLE'
+  )
+  refusedIn(response)
+  return unwrap<SaveResult & { kept: KeptDraft }>(response, 'undoFigureRevert')
+}
+
+/** A figure an AI proposal was saved into (ADR-0097 §5.6 item 5). */
+export interface ProposalOutcome {
+  figureId: string
+  type?: string
+  name?: string
+  recordedAt?: string
+}
+
+/**
+ * 제안이 무엇이 됐나 -- 그 제안을 담은 저장이 들어간 도형들. 비었으면 저장되지 않았다(적용만 하고 저장 전이거나, 되돌렸거나,
+ * 적용하지 않았다). 도크의 「결과 확인」이 이것을 묻는다: 도크의 기억이 아니라 서버의 기록이다.
+ */
+export async function fetchProposalOutcome(proposalKey: string): Promise<ProposalOutcome[]> {
+  const response = await client.query({
+    query: gql`
+      query FigureProposalOutcome($proposalKey: String!) {
+        figureProposalOutcome(proposalKey: $proposalKey) { figureId type name recordedAt }
       }
     `,
-    variables: { id, version }
+    variables: { proposalKey },
+    fetchPolicy: 'network-only'
   })
+  return unwrap<ProposalOutcome[]>(response, 'figureProposalOutcome') ?? []
+}
 
-  return unwrap<SaveResult>(response, 'revertFigureVersion')
+/** 되돌리기가 보관한 초안들, 새것부터 -- 다시 접속해도 여기서 찾는다. */
+export async function fetchReplacedDrafts(id: string): Promise<KeptDraft[]> {
+  const response = await client.query({
+    query: gql`
+      query FigureReplacedDrafts($id: String!) {
+        figureReplacedDrafts(id: $id) { ${KEPT_FIELDS} }
+      }
+    `,
+    variables: { id },
+    fetchPolicy: 'network-only'
+  })
+  return unwrap<KeptDraft[]>(response, 'figureReplacedDrafts')
 }
 
 /**

package/client/graphql/reached.ts

@@ -0,0 +1,25 @@
+/**
+ * A request that never reached the server, or whose answer never came back, is told apart from a refusal: what
+ * happened to the write is not known (`unreachable`, SAVE_UNREACHABLE for a save). The caller finds out before saying
+ * more -- a save reads the server's copy back, a revert asks again with the same request id.
+ */
+export async function reached<T>(request: Promise<T>, unreachable = 'SAVE_UNREACHABLE'): Promise<T> {
+  try {
+    return await request
+  } catch (error) {
+    const lost = (error as { networkError?: unknown })?.networkError || error instanceof TypeError
+    if (lost) throw Object.assign(Error('서버에 연결하지 못했습니다.'), { code: unreachable, cause: error })
+    /* A refusal keeps the server's code, so a conflict is told from a refusal on grounds. */
+    const refused = (error as { graphQLErrors?: Array<{ message: string; extensions?: { code?: string } }> })?.graphQLErrors
+    if (refused?.length) throw Object.assign(Error(refused.map(e => e.message).join('\n')), { code: refused[0]!.extensions?.code, cause: error })
+    throw error
+  }
+}
+
+/** Errors carried in the answer (the client's error policy lets them through), thrown with the server's code. */
+export function refusedIn(response: { errors?: readonly unknown[] }) {
+  if (response.errors?.length)
+    throw Object.assign(Error(response.errors.map(e => (e as { message: string }).message).join('\n')), {
+      code: (response.errors[0] as { extensions?: { code?: string } }).extensions?.code
+    })
+}

package/client/graphql/store.ts

@@ -1,6 +1,7 @@
 import gql from 'graphql-tag'
 import { client } from '@operato/graphql'
 import { fetchFigure } from './index.js'
+import { reached } from './reached.js'
 import type { FigureProductStore, FigureProductRecord } from '../modeller/product-session.js'
 
 /** source is sent intact. No conversion into the old parts/base authoring representation. */
@@ -10,10 +11,30 @@ export const figureProductStore: FigureProductStore = {
     if (!record?.source) throw Error('Figure 정본이 없습니다.')
     return { id: record.id, source: record.source }
   },
+  /* What the server holds of every field a save writes, read back after a save whose outcome is not known. */
+  async readBack(id) {
+    const response = await client.query({
+      query: gql`
+        query ($id: String!) {
+          figure(id: $id) {
+            id
+            source
+            thumbnail
+            type
+          }
+        }
+      `,
+      variables: { id },
+      fetchPolicy: 'network-only'
+    })
+    const figure = response.data?.figure as { id: string; source: string; thumbnail?: string | null; type?: string } | undefined
+    if (!figure?.source) throw Error('Figure 정본이 없습니다.')
+    return { id: figure.id, source: figure.source, thumbnail: figure.thumbnail ?? undefined, type: figure.type }
+  },
   async save(request) {
-    const response = await client.mutate({
+    const response = await reached(client.mutate({
       mutation: gql`
-        mutation SaveFigure($source: String!, $id: String, $expectedSource: String, $creationId: String, $thumbnail: String, $type: String) {
+        mutation SaveFigure($source: String!, $id: String, $expectedSource: String, $creationId: String, $thumbnail: String, $type: String, $proposalKeys: [String!]) {
           saveFigure(
             source: $source
             id: $id
@@ -21,6 +42,7 @@ export const figureProductStore: FigureProductStore = {
             creationId: $creationId
             thumbnail: $thumbnail
             type: $type
+            proposalKeys: $proposalKeys
           ) {
             id
             source
@@ -28,8 +50,9 @@ export const figureProductStore: FigureProductStore = {
         }
       `,
       variables: request
-    })
-    if (response.errors?.length) throw Error(response.errors.map(e => e.message).join('\n'))
+    }))
+    if (response.errors?.length)
+      throw Object.assign(Error(response.errors.map(e => e.message).join('\n')), { code: (response.errors[0] as { extensions?: { code?: string } }).extensions?.code })
     const result = response.data?.saveFigure as FigureProductRecord | undefined
     if (!result?.id || !result.source) throw Error('서버가 저장 결과를 돌려주지 않았습니다.')
     return result

package/client/modeller/ai-proposal.ts

@@ -6,9 +6,12 @@
  * Kept free of Lit, i18n and the shell so node tests read it directly; the handler and the page pass in what they own.
  */
 import type { FigureProposalStep } from '@hatiolab/figure-model'
+import type { FigureProductSession } from './product-session.js'
 
 /** What the card carries, as `proposeFigureCandidate` returned it. */
 export interface FigureProposalCard {
+  /** The proposal's own name, given by the tool: a save records it, a new figure made from it is created under it. */
+  key?: string
   steps?: FigureProposalStep[]
   create?: boolean
   figureId?: string
@@ -18,6 +21,7 @@ export interface FigureProposalCard {
 
 /** The `figure-apply` event's detail. The page that takes it sets `applied`, and `error` when refused. */
 export interface FigureApplyDetail {
+  key?: string
   steps: FigureProposalStep[]
   create: boolean
   context?: string
@@ -25,6 +29,8 @@ export interface FigureApplyDetail {
   applied?: boolean
   error?: string
   code?: string
+  /** The clips a refused proposal would have stopped (CLIPS_DROPPED), by name. */
+  clips?: string[]
 }
 
 export type Say = (key: string, params?: Record<string, string>) => string
@@ -33,7 +39,7 @@ export interface FigureProposalTarget {
   /** Offers the proposal to a modeller on screen. It comes back untouched when none took it. */
   offer(detail: FigureApplyDetail): FigureApplyDetail
   /** Opens a new figure in the modeller and applies the steps there; resolves once the page has, or has not. */
-  openNew(steps: FigureProposalStep[]): Promise<{ applied: boolean; error?: string; code?: string }>
+  openNew(steps: FigureProposalStep[], key?: string): Promise<{ applied: boolean; error?: string; code?: string }>
 }
 
 export interface FigureProposalOutcome {
@@ -43,19 +49,75 @@ export interface FigureProposalOutcome {
   note?: string
 }
 
+/**
+ * The dock's "check the result" (ADR-0097 §5.6 item 5): what the server recorded of a proposal. Saved into figures:
+ * accepted, named. Nothing recorded: not known -- applied and not saved yet, undone, or never taken -- so `undefined`,
+ * which the dock keeps as "not known" and never turns into a refusal. Nothing is run again.
+ */
+export function proposalOutcomeFrom(saved: ReadonlyArray<{ figureId: string; type?: string; name?: string }>, say: Say): FigureProposalOutcome | undefined {
+  if (!saved.length) return undefined
+  const names = saved.map(f => f.name || f.type || f.figureId).join(', ')
+  return { verdict: 'accepted', note: say('figure.text.proposal-saved-into', { names }) }
+}
+
 /** The workspace refuses a request made on another version; said as what happened, not as the kernel's code. */
 const STALE = new Set(['REVISION_CONFLICT', 'CONTEXT_CONFLICT'])
 
-function refused(code: string | undefined, error: string | undefined, say: Say): FigureProposalOutcome {
+function refused(code: string | undefined, error: string | undefined, say: Say, clips?: string[]): FigureProposalOutcome {
+  /*
+    A proposal that would stop clips is refused whole; nobody but the person may agree to that, and a proposal is not
+    asked about -- the person edits by hand if they mean it (designer 2026-09-27).
+  */
   const note =
     code && STALE.has(code)
       ? say('figure.text.proposal-stale')
       : code === 'NEW_FIGURE_UNSAVED'
         ? (error ?? '')
-        : say('figure.text.proposal-refused', { reason: error ?? '' })
+        : code === 'CLIPS_DROPPED'
+          ? say('figure.text.proposal-would-drop-clips', { clips: (clips ?? []).join(', ') })
+          : say('figure.text.proposal-refused', { reason: error ?? '' })
   return { verdict: 'refused', errorCode: code ?? 'refused', note }
 }
 
+/**
+ * The modeller page's way of taking an offer from the dock (`figure-apply`): input changes, or a proposal's commands
+ * as one step (ADR-0094). A revision is applied on the version the model saw; a new figure's proposal only on a new
+ * figure not yet touched, and a page on a saved figure leaves it untaken. Never with a consent to let clips go: a
+ * proposal that would stop one is refused whole, the clips named (designer 2026-09-27). True when it was applied.
+ */
+export function takeFigureOffer(
+  session: FigureProductSession,
+  detail: FigureApplyDetail & { changes?: unknown },
+  { onSavedFigure, say }: { onSavedFigure: boolean; say: Say }
+): boolean {
+  const view = session.read()
+  if (detail.create && onSavedFigure) return false
+  if (detail.create && view.dirty) {
+    /* A new figure already being made is the person's; a proposal does not go on top of it or replace it. */
+    detail.applied = false
+    detail.code = 'NEW_FIGURE_UNSAVED'
+    detail.error = say('figure.text.proposal-new-figure-unsaved')
+    return false
+  }
+  try {
+    if (detail.create) {
+      /* Created under the proposal's key: taken twice, it meets the first figure, never a second (ADR-0097 §5.6 item 5). */
+      if (detail.key) session.createUnder(detail.key)
+      session.applyProposal(detail.steps, view.revision!, view.context!, detail.key)
+    } else if (detail.steps) session.applyProposal(detail.steps, detail.revision!, detail.context!, detail.key)
+    else session.apply(detail.changes as never, 'ai', detail.revision, detail.context)
+    detail.applied = true
+    return true
+  } catch (error) {
+    detail.applied = false
+    detail.code = (error as { code?: string })?.code
+    detail.error = error instanceof Error ? error.message : String(error)
+    const clips = (error as { clips?: Array<{ clip: string }> })?.clips
+    if (clips) detail.clips = clips.map(c => c.clip)
+    return false
+  }
+}
+
 export async function runFigureProposal(card: FigureProposalCard, target: FigureProposalTarget, say: Say): Promise<FigureProposalOutcome> {
   const steps = card?.steps
   if (!Array.isArray(steps) || !steps.length) return { verdict: 'unavailable', errorCode: 'no-steps' }
@@ -66,14 +128,14 @@ export async function runFigureProposal(card: FigureProposalCard, target: Figure
     note: say('figure.text.proposal-applied', { n: String(steps.length) })
   })
 
-  const detail = target.offer({ steps, create, context: card.context, revision: card.revision })
+  const detail = target.offer({ key: card.key, steps, create, context: card.context, revision: card.revision })
   if (detail.applied) return accepted()
-  if (detail.applied === false) return refused(detail.code, detail.error, say)
+  if (detail.applied === false) return refused(detail.code, detail.error, say, detail.clips)
 
   /* A revision belongs to the figure the model saw; with that modeller gone there is nowhere true to apply it. */
   if (!create) return { verdict: 'unavailable', errorCode: 'modeller-not-open', note: say('figure.text.proposal-needs-modeller') }
 
-  const opened = await target.openNew(steps)
+  const opened = await target.openNew(steps, card.key)
   if (opened.applied) return accepted()
   return opened.code === 'not-opened'
     ? { verdict: 'unavailable', errorCode: 'not-opened', note: say('figure.text.proposal-not-opened') }
@@ -85,13 +147,14 @@ export async function runFigureProposal(card: FigureProposalCard, target: Figure
   modeller on a new figure; the page takes it once it has started that figure. Left untaken, it lapses -- a later new
   figure must not receive steps nobody is waiting for.
 */
-let pending: { steps: FigureProposalStep[]; settle: (result: { applied: boolean; error?: string; code?: string }) => void } | undefined
+let pending: { steps: FigureProposalStep[]; key?: string; settle: (result: { applied: boolean; error?: string; code?: string }) => void } | undefined
 
-export function pendNewFigure(steps: FigureProposalStep[], ms = 10_000): Promise<{ applied: boolean; error?: string; code?: string }> {
+export function pendNewFigure(steps: FigureProposalStep[], key?: string, ms = 10_000): Promise<{ applied: boolean; error?: string; code?: string }> {
   pending?.settle({ applied: false, code: 'not-opened' })
   return new Promise(resolve => {
     const mine = {
       steps,
+      key,
       settle: (result: { applied: boolean; error?: string; code?: string }) => {
         clearTimeout(timer)
         if (pending === mine) pending = undefined
@@ -104,7 +167,9 @@ export function pendNewFigure(steps: FigureProposalStep[], ms = 10_000): Promise
 }
 
 /** For the page, on a new figure it has just started: the steps waiting for it, and where to say how it went. */
-export function takePendingNewFigure(): { steps: FigureProposalStep[]; settle: (result: { applied: boolean; error?: string; code?: string }) => void } | undefined {
+export function takePendingNewFigure():
+  | { steps: FigureProposalStep[]; key?: string; settle: (result: { applied: boolean; error?: string; code?: string }) => void }
+  | undefined {
   const taken = pending
   pending = undefined
   return taken

package/client/modeller/align.ts

@@ -14,7 +14,8 @@ import type { GizmoReach } from './gizmo.js'
  * Every tool writes the part's own position (and, for snap, size) inputs — the same ones the gizmo writes, and only
  * where the gizmo could (`GizmoReach`).
  */
-export type AlignTool = 'centre-x' | 'centre-z' | 'floor' | 'snap'
+/* The plane tool is figure-model's now, by placement (`figurePlaneAlignChanges`); these stay the screen's. */
+export type AlignTool = 'centre-x' | 'centre-z' | 'snap'
 
 const AXES = ['x', 'y', 'z'] as const
 
@@ -50,8 +51,6 @@ export function alignChanges(asset: FigureAsset, part: string, reach: GizmoReach
       return [set(at('x'), value(at('x')) - box.centre.x)]
     case 'centre-z':
       return [set(at('z'), value(at('z')) - box.centre.z)]
-    case 'floor':
-      return [set(at('y'), value(at('y')) - (box.centre.y - box.extent.y / 2))]
     case 'snap': {
       const step = gridStepOf(asset)
       const round = (n: number) => Math.round(n / step) * step

package/client/modeller/canvas.ts

@@ -6,8 +6,9 @@ import { create, Model, niceGridStep } from '@hatiolab/things-scene'
 import type { GizmoReach } from './gizmo.js'
 import type { FigureRenderPart } from './renderer.js'
 import { DEFAULT_VIEW, sceneLook, WORKBENCH, type ViewSettings } from './figure-view.js'
-import { boardFor, changedKeys, componentOf, gizmoResultOf, type Board } from './stage-model.js'
+import { boardFor, changedKeys, componentOf, gizmoResultOf, type Board, type ScaleAnchor } from './stage-model.js'
 import { JOINT_FAN } from './joint-fan.js'
+import { PREVIEW, TARGET_FACE } from './command-preview.js'
 import { ownerOf } from './fields.js'
 
 /*
@@ -81,6 +82,8 @@ export class FigureCanvas extends LitElement {
   `
   @property({ attribute: false }) parts: FigureRenderPart[] = []
   @property({ attribute: false }) palette: Record<string, string> = {}
+  /** The face a size drag keeps, per part (figure-model's `figureScaleAnchorOf`), so the drag shows what is written. */
+  @property({ attribute: false }) anchors: Record<string, ScaleAnchor> = {}
   /** Which figure is open. Another one stands the board up again. */
   @property() context = ''
   @property() selected = ''
@@ -93,8 +96,16 @@ export class FigureCanvas extends LitElement {
    * would reach the editor as an edit.
    */
   @property({ type: Boolean }) viewOnly = false
+  /** The editor shows a new figure's start card over the canvas: the canvas's own one-line hint gives way to it. */
+  @property({ type: Boolean }) startShown = false
   /** Where the selected part turns and how far (`joint-fan`): shown, never picked, never saved. */
   @property({ attribute: false }) fan: FigureRenderPart | null = null
+  /**
+   * A command seen before it is done (ADR-0097 §5.5): the bodies it would move, where they would stand, translucent,
+   * and the face they would be fastened to, lit. Shown, never picked, never saved; gone when the command is.
+   */
+  @property({ attribute: false }) ghost: FigureRenderPart[] = []
+  @property({ attribute: false }) highlight: FigureRenderPart | null = null
 
   @query('div[stage]') private stage!: HTMLDivElement
 
@@ -106,7 +117,7 @@ export class FigureCanvas extends LitElement {
   private writing = false
 
   render() {
-    return html`<div stage></div>${this.parts.length ? nothing : html`<p>${i18next.t('figure.text.add-a-shape-to-start')}</p>`}`
+    return html`<div stage></div>${this.parts.length || this.startShown ? nothing : html`<p>${i18next.t('figure.text.add-a-shape-to-start')}</p>`}`
   }
 
   firstUpdated() {
@@ -117,7 +128,7 @@ export class FigureCanvas extends LitElement {
 
   protected updated(changed: PropertyValues) {
     if (!this.hasUpdated) return
-    if (changed.has('parts') || changed.has('palette') || changed.has('context') || changed.has('fan')) this.standUp()
+    if (['parts', 'palette', 'context', 'fan', 'anchors', 'ghost', 'highlight'].some(key => changed.has(key))) this.standUp()
     if (changed.has('view')) this.applyView()
     if (changed.has('selected')) this.showSelected()
   }
@@ -210,10 +221,12 @@ export class FigureCanvas extends LitElement {
   }
 
   private components(): Record<string, unknown>[] {
-    const parts = this.parts.map(part => componentOf(part, this.palette, this.board!)).filter((c): c is Record<string, unknown> => !!c)
+    const parts = this.parts.map(part => componentOf(part, this.palette, this.board!, this.anchors[ownerOf(part.id)])).filter((c): c is Record<string, unknown> => !!c)
     /* The fan in the accent colour, translucent; `capturable: false` keeps clicks, the marquee and the gizmo off it. */
     const fan = this.fan ? componentOf(this.fan, { ...this.palette, [JOINT_FAN]: this.palette['palette.accent'] ?? FAN_COLOUR }, this.board!) : null
-    return fan ? [...parts, { ...fan, capturable: false, locked: true }] : parts
+    const accent = this.palette['palette.accent'] ?? FAN_COLOUR
+    const shown = [...(fan ? [fan] : []), ...this.ghost.map(part => componentOf(part, { ...this.palette, [PREVIEW]: accent, [TARGET_FACE]: accent }, this.board!)), ...(this.highlight ? [componentOf(this.highlight, { ...this.palette, [TARGET_FACE]: accent }, this.board!)] : [])]
+    return [...parts, ...shown.filter((c): c is Record<string, unknown> => !!c).map(c => ({ ...c, capturable: false, locked: true }))]
   }
 
   /** The components standing now, by name. Not held between calls: the scene stands its board up again at times. */

package/client/modeller/command-preview.ts

@@ -0,0 +1,113 @@
+import type { FigureBodyMove, FigureClipLoss, FigureFaceArea, FigureRowReading } from '@hatiolab/figure-model'
+
+import type { FigureRenderPart } from './renderer.js'
+
+/*
+ * A command seen before it is done, as the modeller shows it (ADR-0097 §5.5, designer 2026-09-27): the bodies it would
+ * move, translucent where they would stand; the face they would meet, lit; and in words, how far and how each turns --
+ * the turn as figure-model gives it, one axis and one angle in the figure's frame.
+ */
+
+/* The material tokens of what a command would do: the bodies where they would stand, and the face they would meet. */
+export const PREVIEW = '__preview'
+export const TARGET_FACE = '__target-face'
+
+export type Say = (key: string, params?: Record<string, string>) => string
+
+/** A preview as the editor holds it: bound to the figure, version and command it was worked out for. */
+export interface HeldPreview {
+  context: string
+  revision: number
+  /** The command, as text: a preview for another command is not this one's. */
+  key: string
+  geometry?: unknown[]
+  moves?: FigureBodyMove[]
+  /** Bodies it would draw that are not drawn now: a row's copies. */
+  added?: string[]
+  /** The row it would make, read on the preview's figure. */
+  row?: FigureRowReading
+  clipsWouldGo?: FigureClipLoss[]
+  face?: FigureFaceArea
+  /** Whether a face was asked for and could not be shown. */
+  faceUnknown?: boolean
+  /** Why the command would be refused; nothing else is shown then. */
+  refused?: string
+}
+
+/** The moving bodies where they would stand, drawn translucent. The ones that stay are not drawn twice. */
+export function ghostPartsOf(preview: HeldPreview | undefined): FigureRenderPart[] {
+  if (!preview?.geometry || !(preview.moves?.length || preview.added?.length)) return []
+  const moving = new Set([...(preview.moves ?? []).map(m => m.body), ...(preview.added ?? [])])
+  return (preview.geometry as FigureRenderPart[])
+    .filter(body => body && typeof body === 'object' && 'shape' in body && 'pose' in body && moving.has(body.id))
+    .map(body => ({ ...body, id: `${PREVIEW}:${body.id}`, material: { token: PREVIEW, transparent: true } }))
+}
+
+/** How thick the lit face is, and how far off the face it floats, so it neither hides nor flickers with it. */
+const THICKNESS = 2
+const LIFT = 1
+
+/** The face the part would meet, lit: a thin plate over a flat face, a thin disc over a round one. */
+export function faceHighlightOf(face: FigureFaceArea | undefined): FigureRenderPart | null {
+  if (!face) return null
+  /* Its own x · y · z are the face's two sides and its normal, as the kernel gives them. */
+  const r = [0, 1, 2].map(i => [face.u[i]!, face.normal[i]!, face.v[i]!])
+  const t = [0, 1, 2].map(i => face.centre[i]! + face.normal[i]! * (LIFT + THICKNESS / 2))
+  const shape: FigureRenderPart['shape'] = face.round
+    ? { provider: 'cylinder', dimensions: { radius: face.size.u / 2, length: THICKNESS } }
+    : { provider: 'box', dimensions: { width: face.size.u, height: THICKNESS, depth: face.size.v } }
+  /* Solid: a translucent plate over a light face was hardly seen (2026-09-27, :3391); it covers the face it names. */
+  return { id: TARGET_FACE, shape, pose: { r, t }, material: { token: TARGET_FACE } }
+}
+
+const mm = (v: number) => `${v > 0 ? '+' : v < 0 ? '−' : ''}${Math.abs(Math.round(v * 10) / 10).toLocaleString()}`
+
+/**
+ * What the command would do, in words: the part's own move and turn, what goes with it, the clips it would stop, and
+ * why nothing can be shown when the command would be refused.
+ */
+export function previewWordsOf(preview: HeldPreview | undefined, part: string, say: Say): string[] {
+  if (!preview) return []
+  if (preview.refused) return [say('figure.text.preview-refused', { reason: preview.refused })]
+  /* A row: what it would be, read as drawn; its part does not move, it is copied. */
+  if (preview.row) return [...rowWordsOf(preview.row, say), ...(preview.clipsWouldGo?.length ? [say('figure.text.preview-clips', { clips: preview.clipsWouldGo.map(c => c.clip).join(', ') })] : [])]
+  const words: string[] = []
+  const own = preview.moves?.find(m => m.body === part)
+  if (!own) words.push(say('figure.text.preview-stays'))
+  else {
+    const axes = (['x', 'y', 'z'] as const).map((axis, i) => [axis, own.translate[i]!] as const).filter(([, v]) => Math.abs(v) >= 0.05)
+    if (axes.length) words.push(say('figure.text.preview-moves', { by: axes.map(([axis, v]) => `${axis.toUpperCase()} ${mm(v)}`).join(' · ') }))
+    if (own.turn) {
+      /* Signed by the right hand about the axis, as the figure's frame has it. */
+      const degrees = mm(own.turn.degrees)
+      words.push(
+        typeof own.turn.axis === 'string'
+          ? say('figure.text.preview-turns-named', { axis: own.turn.axis.toUpperCase(), degrees })
+          : say('figure.text.preview-turns-slanted', { axis: own.turn.axis.map(v => v.toFixed(2)).join(', '), degrees })
+      )
+    }
+  }
+  /* What goes with it: parts fastened to it, each row once, with its count. */
+  const others = new Map<string, number>()
+  for (const m of preview.moves ?? []) if (m.part !== part) others.set(m.part, (others.get(m.part) ?? 0) + 1)
+  if (others.size)
+    words.push(say('figure.text.preview-carries', { parts: [...others].map(([name, n]) => (n > 1 ? say('figure.text.preview-copies', { part: name, n: String(n) }) : name)).join(', ') }))
+  if (preview.clipsWouldGo?.length) words.push(say('figure.text.preview-clips', { clips: preview.clipsWouldGo.map(c => c.clip).join(', ') }))
+  if (preview.faceUnknown) words.push(say('figure.text.preview-face-unknown'))
+  return words
+}
+
+/** A row in words, as figure-model reads it from what is drawn: how many, how far apart, what is left at the ends, what rides it. */
+export function rowWordsOf(row: FigureRowReading | undefined, say: Say): string[] {
+  if (!row) return []
+  const words = [
+    row.pitch !== undefined
+      ? say('figure.text.row-count-pitch', { part: row.part, count: String(row.count), pitch: String(row.pitch), axis: row.axis.toUpperCase() })
+      : say('figure.text.row-count-uneven', { part: row.part, count: String(row.count), axis: row.axis.toUpperCase() })
+  ]
+  if (!row.margins) words.push(say('figure.text.row-ends-unknown'))
+  else if (row.centred) words.push(say('figure.text.row-ends-centred', { mm: String(row.margins.low) }))
+  else words.push(say('figure.text.row-ends', { low: String(row.margins.low), high: String(row.margins.high) }))
+  if (row.companions.length) words.push(say('figure.text.row-companions', { parts: row.companions.map(c => say('figure.text.preview-copies', { part: c.part, n: String(c.count) })).join(', ') }))
+  return words
+}