@things-factory/figure-ui 10.1.81 → 10.1.83

package/client/modeller/product-session.ts

@@ -7,9 +7,16 @@ import {
   type FigurePrimitiveCreation,
   type FigurePartEdit,
   type FigureAuthoringAction,
-  type FigureProposalStep
+  type FigureProposalStep,
+  type FigureClipConsent
 } from '@hatiolab/figure-model'
 
+/** Consent to let clips go, and the figure and version it was given on. */
+export interface FigureClipConsentFor extends FigureClipConsent {
+  context: string
+  revision: number
+}
+
 export interface FigureProductRecord {
   id: string
   source: string
@@ -18,6 +25,8 @@ export interface FigureProductRecord {
 /** Persistence is injected; neither the model engine nor the renderer owns the product ID. */
 export interface FigureProductStore {
   load(id: string): Promise<FigureProductRecord>
+  /** Every field a save writes, as the server holds it now: to tell whether a save whose answer was lost landed. */
+  readBack?(id: string): Promise<FigureProductRecord & { thumbnail?: string; type?: string }>
   save(request: {
     id?: string
     source: string
@@ -27,6 +36,8 @@ export interface FigureProductStore {
     thumbnail?: string
     /** The type name a new figure is created under (the first save asks for it). Not sent for an existing one. */
     type?: string
+    /** Keys of the AI proposals whose steps the source holds: the server records them with the save. */
+    proposalKeys?: string[]
   }): Promise<FigureProductRecord>
 }
 
@@ -40,9 +51,47 @@ export function createFigureProductSession(store: FigureProductStore) {
     saving = false,
     error: string | undefined
   let creationId: string | undefined
+  /*
+    The history as steps, each tagged with the AI proposal it came from (or nothing): mirrored here, since the
+    workspace's history does not say where a step came from. A proposal is in the model while its step is on `done` --
+    undone, it is not; undone and written past, it never comes back. What a save sends as `proposalKeys`.
+  */
+  let done: Array<string | undefined> = [],
+    undone: Array<string | undefined> = []
+  function tracked<T>(kind: 'do' | 'undo' | 'redo', run: () => T, tag?: string): T {
+    const before = workspace.read().revision
+    const result = run()
+    if (workspace.read().revision === before) return result
+    if (kind === 'do') {
+      done.push(tag)
+      undone = []
+    } else if (kind === 'undo') undone.push(done.pop())
+    else done.push(undone.pop())
+    return result
+  }
+  const inEffect = () => [...new Set(done.filter((tag): tag is string => !!tag))]
   function read() {
     return { ...workspace.read(), id, loading, saving, error }
   }
+  /* Texts sent whose save was never answered: found on the server, the server is confirmed to hold what was sent. */
+  const unconfirmed = new Map<string, { thumbnail?: string }>()
+  /*
+    Consent to let clips go: given for one edit, on the figure and the version it was asked on. The first edit made under
+    it takes it; an edit on another figure or another version is refused rather than let clips go that were never named
+    for it (designer 2026-09-27).
+  */
+  let consent: FigureClipConsentFor | undefined
+  const consented = () => {
+    if (!consent) return {}
+    const given = consent
+    consent = undefined
+    const view = workspace.read()
+    if (view.context !== given.context || view.revision !== given.revision) {
+      const stale = Object.assign(Error('확인한 뒤 모델이 바뀌어 적용하지 않았습니다. 다시 해 주세요.'), { code: 'CONSENT_STALE' })
+      throw stale
+    }
+    return { dropClips: given.dropClips }
+  }
   function writable() {
     const view = workspace.read()
     if (loading || error || !view.context || view.revision === null) throw Error('먼저 모델을 정상적으로 열어 주세요.')
@@ -57,6 +106,8 @@ export function createFigureProductSession(store: FigureProductStore) {
     error = undefined
     saving = false
     creationId = undefined
+    done = []
+    undone = []
   }
   function canLeave(discard: boolean) {
     if (saving) throw Error('저장이 끝난 뒤 모델을 전환해 주세요.')
@@ -64,6 +115,11 @@ export function createFigureProductSession(store: FigureProductStore) {
   }
   return {
     read,
+    /**
+     * The source the server is confirmed to hold: loaded, or answered by a save. What a revert sends as `expectedSource`
+     * -- the server writes over it only while it still holds this. Nothing for a figure not saved yet.
+     */
+    confirmedSource: () => (id ? baseline : undefined),
     startNew({ discard = false } = {}) {
       canLeave(discard)
       ++epoch
@@ -104,45 +160,79 @@ export function createFigureProductSession(store: FigureProductStore) {
       // AI must supply the context AND revision captured when it started. Never substitute current values.
       if (origin === 'ai' && (context === undefined || expectedRevision === undefined))
         throw Error('AI 편집에는 요청 당시의 모델 문맥과 리비전이 필요합니다.')
-      return workspace.apply({
-        ...control,
-        origin,
-        context: context ?? control.context,
-        expectedRevision: expectedRevision ?? control.expectedRevision,
-        changes
-      })
+      return tracked('do', () =>
+        workspace.apply({
+          ...control,
+          origin,
+          context: context ?? control.context,
+          expectedRevision: expectedRevision ?? control.expectedRevision,
+          changes
+        })
+      )
     },
     /**
      * An AI proposal (ADR-0094): the modeller's commands, as one step of the history, on the version the model saw.
      * Never on the current one instead -- a person's edit in between makes the proposal stale, and it is refused.
      */
-    applyProposal(steps: readonly FigureProposalStep[], expectedRevision: number, context: string) {
+    applyProposal(steps: readonly FigureProposalStep[], expectedRevision: number, context: string, key?: string) {
       writable()
-      return workspace.applyProposal({ origin: 'ai', context, expectedRevision, steps })
+      /* Never with consent: only the person may let a clip go, and an AI proposal is not the person (designer 2026-09-27). */
+      return tracked('do', () => workspace.applyProposal({ origin: 'ai', context, expectedRevision, steps }), key)
+    },
+    /**
+     * A new figure made from an AI proposal is created under the proposal's key (ADR-0097 §5.6 item 5): the same
+     * proposal taken twice meets the first figure on the server, never a second one. Only on a new figure not yet
+     * touched -- one being made is the person's, and keeps its own.
+     */
+    createUnder(key: string) {
+      if (id || workspace.read().dirty) throw Error('손대지 않은 새 모델에만 쓸 수 있습니다.')
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(key)) throw Error('제안 식별자가 올바르지 않습니다.')
+      creationId = key
     },
+    /** The AI proposals whose steps are in the model now, each once. */
+    proposalsInEffect: inEffect,
     /**
      * A recipe put in by the person (ADR-0095): its resolved commands, as one step of the history, on the version open
      * now. The same path as a proposal; the person is its origin.
      */
     applyRecipe(steps: readonly FigureProposalStep[]) {
       const at = writable()
-      return workspace.applyProposal({ origin: 'ui', context: at.context, expectedRevision: at.expectedRevision, steps })
+      return tracked('do', () => workspace.applyProposal({ origin: 'ui', context: at.context, expectedRevision: at.expectedRevision, steps, ...consented() }))
     },
     add(part: FigurePrimitiveCreation) {
-      return workspace.addPrimitive({ ...writable(), part })
+      return tracked('do', () => workspace.addPrimitive({ ...writable(), part }))
     },
     edit(edit: FigurePartEdit) {
-      return workspace.editPart({ ...writable(), edit })
+      return tracked('do', () => workspace.editPart({ ...writable(), edit, ...consented() }))
+    },
+    /** What a command would do, on a copy (ADR-0097 §5.5): nothing is written, and the answer names its version. */
+    previewCommand(action: FigureAuthoringAction) {
+      const view = workspace.read()
+      if (loading || error || !view.context || view.revision === null) throw Error('먼저 모델을 정상적으로 열어 주세요.')
+      return workspace.previewCommand({ context: view.context, action })
     },
     /** One authoring command — what a person means, not a graph edit — as one step of the same history. */
     command(action: FigureAuthoringAction) {
-      return workspace.command({ ...writable(), action })
+      return tracked('do', () => workspace.command({ ...writable(), action, ...consented() }))
+    },
+    /**
+     * The first edit made inside `run` may let go of exactly these clips -- the ones a CLIPS_DROPPED refusal named and
+     * the person agreed to -- on the figure and version they were named on (designer 2026-09-27). Any other edit that
+     * would stop a clip is refused and asked about.
+     */
+    withConsent<T>(given: FigureClipConsentFor, run: () => T): T {
+      consent = given
+      try {
+        return run()
+      } finally {
+        consent = undefined
+      }
     },
     undo() {
-      return workspace.undo(writable())
+      return tracked('undo', () => workspace.undo(writable()))
     },
     redo() {
-      return workspace.redo(writable())
+      return tracked('redo', () => workspace.redo(writable()))
     },
     source() {
       const { context } = writable()
@@ -159,16 +249,62 @@ export function createFigureProductSession(store: FigureProductStore) {
       const control = writable(),
         requestEpoch = epoch
       const exported = workspace.export(control)
+      /* Read with the text it goes with: an edit while saving is not what this save holds. */
+      const proposalKeys = inEffect()
       saving = true
       try {
-        const record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId, thumbnail, ...(id || !type ? {} : { type }) })
+        let record: FigureProductRecord
+        try {
+          record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId, thumbnail, proposalKeys, ...(id || !type ? {} : { type }) })
+        } catch (error) {
+          /*
+            A save that failed may still have landed: the answer lost on the way back (SAVE_UNREACHABLE), or a second
+            try refused because the first did land -- its expected source is the old one (FIGURE_SOURCE_CONFLICT). Only
+            those are read back; a refusal on grounds -- permission, validation -- stays a failure whatever the row
+            holds. Read back, every field the save writes must be what was sent: the source, the picture, the type
+            (designer 2026-09-27: a network failure alone does not say nothing was saved; nor does a matching source
+            alone say it was).
+          */
+          const code = (error as { code?: string })?.code
+          const unknown = code === 'SAVE_UNREACHABLE' || code === 'FIGURE_SOURCE_CONFLICT'
+          const landed = unknown && id !== undefined && requestEpoch === epoch && store.readBack ? await store.readBack(id).catch(() => undefined) : undefined
+          const held = landed ? serializeFigureAsset(parseFigureAsset(landed.source)) : undefined
+          const same = !!landed && held === exported.text && (thumbnail === undefined || landed.thumbnail === thumbnail) && (type === undefined || landed.type === type)
+          if (same) record = landed!
+          else if (
+            code === 'FIGURE_SOURCE_CONFLICT' &&
+            landed &&
+            held !== undefined &&
+            unconfirmed.has(held) &&
+            /* Every field that earlier save wrote, not the source alone: nothing not compared is written over. */
+            (unconfirmed.get(held)!.thumbnail === undefined || landed.thumbnail === unconfirmed.get(held)!.thumbnail)
+          ) {
+            /*
+              The row holds a text this session sent and never heard back about -- edited further since, the new text
+              is not it. The server is known to hold what was sent: this save is sent again, once, conditional on that
+              server text as the expected source (designer 2026-09-27: "the sent content is confirmed on the server").
+            */
+            baseline = landed.source
+            unconfirmed.clear()
+            record = await store.save({ id, source: exported.text, expectedSource: baseline, creationId, thumbnail, proposalKeys, ...(id || !type ? {} : { type }) })
+          } else {
+            if (code === 'SAVE_UNREACHABLE') unconfirmed.set(exported.text, { thumbnail })
+            throw error
+          }
+        }
         if (requestEpoch !== epoch) return read()
         if (!record.id || (id !== undefined && record.id !== id)) throw Error('저장 응답의 Figure 대상이 다릅니다.')
         if (serializeFigureAsset(parseFigureAsset(record.source)) !== exported.text)
           throw Error('저장 응답이 보낸 모델과 다릅니다. 저장 상태를 다시 확인해 주세요.')
-        workspace.acknowledgeSaved(exported)
+        /* The server has it: the next save expects it, whatever happened on screen meanwhile. */
         id = record.id
         baseline = record.source
+        unconfirmed.clear()
+        /*
+          Edited while it was saving: what was sent is saved, the edits since are not -- they stay, and the model stays
+          unsaved (the workspace refuses a stale acknowledgement). Never marked saved, never wiped.
+        */
+        if (workspace.read().revision === exported.revision) workspace.acknowledgeSaved(exported)
       } finally {
         if (requestEpoch === epoch) saving = false
       }

package/client/modeller/refusals.ts

@@ -140,3 +140,18 @@ export function inputRangeRefusalOf(error: unknown, say: Say): string | null {
   const params = { value: number(value!), min: number(min!), max: number(max!) }
   return axis ? say('figure.text.input-range-size', { ...params, axis: axis.toUpperCase() }) : say('figure.text.input-range', params)
 }
+
+/**
+ * Why "follow the size and keep where the figure is placed" was not applied, in the author's words (ADR-0097): the plan
+ * says what it would have had to overwrite, and for a part through the plane how far. A code the screen has no words
+ * for is said as a refusal with its code, never in the kernel's English.
+ */
+export function resizeRefusalOf(plan: { mode: string; refusal?: { code: string; axis?: string; mm?: number } }, part: string, say: Say): string {
+  const refusal = plan.refusal
+  if (!refusal) return ''
+  const place = say(`figure.label.resize-place-${plan.mode}`, {})
+  const params = { part, place, axis: (refusal.axis ?? '').toUpperCase(), mm: refusal.mm === undefined ? '' : String(Math.round(refusal.mm)) }
+  const known = ['HELD', 'TURNED', 'UNIFORM_POLICY', 'SHAPE_EDIT', 'DIMENSION_RULE', 'POSITION_RULE', 'GAP_CHOICE', 'NO_FACE']
+  if (known.includes(refusal.code)) return say(`figure.text.resize-refused-${refusal.code.toLowerCase().replace(/_/g, '-')}`, params)
+  return say('figure.text.edit-refused', { code: refusal.code })
+}

package/client/modeller/revert-request.ts

@@ -0,0 +1,26 @@
+/**
+ * The request id a revert or an undo goes with (ADR-0097 §5.6, designer 2026-09-27: a retry after a lost answer never
+ * runs the same restore twice).
+ *
+ * Asked again for the same thing -- the same version over the same confirmed source, or the same kept draft -- after
+ * an answer that never came, the id is the one already sent: the server answers with what it did. Anything else is a
+ * new request.
+ */
+export interface RevertRequest {
+  key: string
+  requestId: string
+}
+
+/** Outcomes that leave it unknown whether the server did it. */
+const UNKNOWN = new Set(['REVERT_UNREACHABLE', 'FIGURE_REVERT_IN_FLIGHT'])
+
+export function revertRequestFor(pending: RevertRequest | undefined, key: string, fresh: () => string = () => crypto.randomUUID()): RevertRequest {
+  return pending?.key === key ? pending : { key, requestId: fresh() }
+}
+
+/** After the answer, or its absence: kept only while it is not known whether the server did it. */
+export function afterRevertAnswer(sent: RevertRequest, code?: string): RevertRequest | undefined {
+  return code !== undefined && UNKNOWN.has(code) ? sent : undefined
+}
+
+export const revertOutcomeUnknown = (code?: string) => code !== undefined && UNKNOWN.has(code)

package/client/modeller/side-panel-styles.ts

@@ -263,6 +263,18 @@ export const SidePanelStyles = css`
   div[cell] input:focus {
     outline: none;
   }
+  /* An axis a rule sets: its number, read-only, on a quieter ground (ADR-0097). */
+  div[cell][held] {
+    background-color: var(--md-sys-color-surface-container);
+    border-style: dashed;
+  }
+  div[cell][held] input {
+    color: var(--md-sys-color-on-surface-variant);
+    font-style: italic;
+  }
+  p[held-axes] {
+    margin: 2px 0 6px;
+  }
   label[toggle] {
     display: flex;
     align-items: center;

package/client/modeller/stage-model.ts

@@ -64,8 +64,16 @@ function colours(part: FigureRenderPart, palette: Record<string, string>) {
   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: FigureRenderPart, palette: Record<string, string>, board: Board): Record<string, unknown> | null {
+/** Per axis of the body's own frame, the face a size drag keeps: 1 the low face, -1 the high face, 0 the centre. */
+export type ScaleAnchor = Record<'x' | 'y' | 'z', -1 | 0 | 1>
+
+/**
+ * The component state that draws a body where figure-model put it. With `anchor` -- figure-model's
+ * `figureScaleAnchorOf` for its part -- the scene's scale gizmo keeps that face while it is dragged, the face the model
+ * keeps when the drag is written; without it the gizmo keeps the face across from the handle held, and the part jumped
+ * on release (designer 2026-09-27). Body x · y · z are the component's width · depth · height, as the scene's axes are.
+ */
+export function componentOf(part: FigureRenderPart, palette: Record<string, string>, board: Board, anchor?: ScaleAnchor): Record<string, unknown> | null {
   const frame = frameOf(part)
   if (!frame) return null
   const { centre, extent, rotation, origin } = frame
@@ -88,7 +96,8 @@ export function componentOf(part: FigureRenderPart, palette: Record<string, stri
     zPos: round(world.y - depth / 2),
     rotationX: round(euler.x),
     rotation: round(-euler.y),
-    rotationY: round(euler.z)
+    rotationY: round(euler.z),
+    ...(anchor ? { scaleAnchor: { ...anchor } } : {})
   }
 }
 
@@ -181,3 +190,16 @@ export function boardFor(parts: readonly FigureRenderPart[], at: Board & { depth
     depth: Math.max(at.depth ?? 0, Math.ceil(size.y * 1.1), 200)
   }
 }
+
+/**
+ * A body's placement as its fields would read it: its origin in mm and its turn in degrees (rigid@1's X·Y·Z order, as
+ * `componentOf` reads it). For a field a rule sets -- a fastened part's height, a turn its joint fixes -- the screen shows
+ * this number read-only rather than a blank (designer 2026-09-27).
+ */
+export function placementOf(part: FigureRenderPart): { position: [number, number, number]; rotation: [number, number, number] } {
+  const r = part.pose.r
+  const m = 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)
+  const e = new THREE.Euler().setFromRotationMatrix(m, 'XYZ')
+  const deg = (v: number) => Math.round(THREE.MathUtils.radToDeg(v) * 10) / 10 || 0
+  return { position: part.pose.t.map(round) as [number, number, number], rotation: [deg(e.x), deg(e.y), deg(e.z)] }
+}

package/client/pages/figure-modeller-page.ts

@@ -6,7 +6,7 @@ import { modellerPathOf } from '../modeller/modeller-route.js'
 import { createFigureProductSession } from '../modeller/product-session.js'
 import { figureProductStore } from '../graphql/store.js'
 import { i18next } from '@operato/i18n'
-import { fetchFigure, fetchFigureTypeNames, updateFigure } from '../graphql/index.js'
+import { fetchFigure, fetchFigureTypeNames, fetchProposalOutcome, updateFigure } from '../graphql/index.js'
 import { availableRecipes, recipeGuide } from '../modeller/recipe-source.js'
 import type { RecipeTemplate } from '../modeller/recipes.js'
 import { occupancyFromParts } from '../modeller/occupancy.js'
@@ -18,17 +18,18 @@ import '../modeller/figure-verdict.js'
 import '../modeller/figure-properties.js'
 import type { FigureBudgetLine } from '../modeller/maturity.js'
 import { OxPrompt } from '@operato/popup'
-import { openPopup } from '@operato/layout'
+import { notify, openPopup } from '@operato/layout'
 import '../modeller/figure-first-save.js'
 import { activePalette } from '@hatiolab/things-scene'
 import {
+  askAssistant,
   clearAssistantSurface,
   notifyAssistantSurface,
   provideAssistantSurface
 } from '@things-factory/ai-assistant/dist-client/index.js'
 import type { FirstSave } from '../modeller/first-save.js'
 import { placementRefusalOf } from '../modeller/refusals.js'
-import { takePendingNewFigure } from '../modeller/ai-proposal.js'
+import { proposalOutcomeFrom, takeFigureOffer, takePendingNewFigure } from '../modeller/ai-proposal.js'
 
 /**
  * The product page has exactly one authoritative workspace for UI and AI input transactions.
@@ -161,6 +162,9 @@ export class FigureModellerPage extends PageView {
       label: () => this.session.read().name || id,
       detail: () => (this.session.read().dirty ? i18next.t('figure.text.unsaved-changes') : ''),
       anchor: () => ({ anchorType: 'figure', anchorId: id }),
+      /* The card's "check the result": the server's record, never the dock's memory; nothing is applied again. */
+      proposalOutcome: async (proposalKey: string) =>
+        proposalOutcomeFrom(await fetchProposalOutcome(proposalKey), (key, params) => i18next.t(key, params)),
       hostContext: () => ({
         surface: 'figure-modeller',
         editorMode: 'existing',
@@ -169,10 +173,23 @@ export class FigureModellerPage extends PageView {
         /* The version the model sees; a proposal is applied on it, or refused if the figure moved on (ADR-0094). */
         context: this.session.read().context,
         revision: this.session.read().revision,
-        palette: Object.keys(activePalette())
+        palette: Object.keys(activePalette()),
+        ...this.assistantFocus()
       })
     })
   }
+  /**
+   * The part selected and what the preview is trying, with the version they were seen on (ADR-0097 §5.6 item 5). Read
+   * when a request is sent; selecting is not a new subject, so the dock is not told about it and the conversation stays.
+   */
+  private assistantFocus() {
+    const focus = this.renderRoot.querySelector<HTMLElement & { assistantFocus?: () => { part?: string; trying?: object } }>('figure-editor')?.assistantFocus?.() ?? {}
+    const { context, revision } = this.session.read()
+    return {
+      ...(focus.part ? { selection: { part: focus.part, context, revision } } : {}),
+      ...(focus.trying ? { trying: { ...focus.trying, context, revision } } : {})
+    }
+  }
   private withdrawAssistant() {
     this.assistantFor = undefined
     clearAssistantSurface(this)
@@ -201,9 +218,19 @@ export class FigureModellerPage extends PageView {
     if (this.wasDirty && !view.dirty && !view.saving && view.id) this.readRow(view.id)
     this.wasDirty = !!view.dirty
   }
+  /*
+    A released figure changed on the server -- its source saved, or its category or tags -- comes back a draft, and a
+    board keeps the released version until it is released again. Said when it happens (D, designer 2026-09-27), not left
+    to a badge in the history tab.
+  */
+  /* True of what boards read: `figureBlueprint` answers a draft row with its latest released version (releasedSourceOf). */
+  private toldDemoted(before: string | undefined, after: string | undefined) {
+    if (before === 'released' && after === 'draft') notify({ level: 'info', message: i18next.t('figure.text.released-now-draft') })
+  }
   private async readRow(id: string) {
     try {
       const figure = await fetchFigure(id)
+      if (this.session.read().id === id) this.toldDemoted(this.row.state, figure.state)
       if (this.session.read().id === id)
         this.row = {
           state: figure.state as 'draft' | 'released',
@@ -290,7 +317,15 @@ export class FigureModellerPage extends PageView {
     try {
       const result = await updateFigure(id, patch)
       this.commandError = ''
-      this.row = { ...this.row, category: result.figure.category ?? undefined, tags: result.figure.tags ?? undefined }
+      /* The server's answer on its state too: a category changed on a released figure made it a draft, and the badge stayed. */
+      this.toldDemoted(this.row.state, result.figure.state)
+      this.row = {
+        ...this.row,
+        category: result.figure.category ?? undefined,
+        tags: result.figure.tags ?? undefined,
+        ...(result.figure.state ? { state: result.figure.state as 'draft' | 'released' } : {}),
+        ...(result.figure.version !== undefined ? { version: result.figure.version ?? 0 } : {})
+      }
     } catch (error) {
       this.commandError = error instanceof Error ? error.message : String(error)
     }
@@ -300,7 +335,22 @@ export class FigureModellerPage extends PageView {
     /* Keep the rest of the row: rebuilding it from these two dropped the type, and the locked type field went blank. */
     if (figure?.id && figure.id === this.session.read().id) this.row = { ...this.row, state: figure.state, version: figure.version ?? 0 }
   }
-  /** 과거 판으로 되돌렸으면 서버의 원본이 바뀐 것이다 — 다시 연다. 패널은 저장 안 된 것이 있으면 되돌리기를 막는다. */
+  /*
+    The edits in hand saved before going back to a released version: known saved, or not -- a failure, or an outcome not
+    known, holds the revert (designer 2026-09-27, Q-D1). The figure has a row here: there is no first save to ask.
+  */
+  private saveBeforeRevert = async (): Promise<{ ok: boolean; reason?: string }> => {
+    try {
+      await this.session.save()
+      this.changed()
+      return this.session.read().dirty ? { ok: false } : { ok: true }
+    } catch (error) {
+      this.changed()
+      const code = (error as { code?: string })?.code
+      return { ok: false, reason: code === 'SAVE_UNREACHABLE' ? i18next.t('figure.text.save-unreachable') : error instanceof Error ? error.message : String(error) }
+    }
+  }
+  /** 과거 판으로 되돌렸으면 서버의 원본이 바뀐 것이다 — 다시 연다. 저장 안 된 것이 있으면 패널이 먼저 저장·버리기·취소를 묻는다. */
   private reverted = async () => {
     const id = this.session.read().id
     if (!id) return
@@ -316,26 +366,7 @@ export class FigureModellerPage extends PageView {
   private applyAI = (event: Event) => {
     const detail = (event as CustomEvent).detail
     if (!this.active || !detail) return
-    const view = this.session.read()
-    if (detail.create && this.routeId) return
-    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 = i18next.t('figure.text.proposal-new-figure-unsaved')
-      return
-    }
-    try {
-      if (detail.create) this.session.applyProposal(detail.steps, view.revision!, view.context!)
-      else if (detail.steps) this.session.applyProposal(detail.steps, detail.revision, detail.context)
-      else this.session.apply(detail.changes, 'ai', detail.revision, detail.context)
-      detail.applied = true
-      this.changed()
-    } catch (error) {
-      detail.applied = false
-      detail.code = (error as { code?: string })?.code
-      detail.error = error instanceof Error ? error.message : String(error)
-    }
+    if (takeFigureOffer(this.session, detail, { onSavedFigure: !!this.routeId, say: (key, params) => i18next.t(key, params) })) this.changed()
   }
   /*
     Reloading or closing the tab is not a move the shell asks `canDeactivate` about: a new figure not yet saved was lost
@@ -420,7 +451,9 @@ export class FigureModellerPage extends PageView {
     if (!waiting) return
     const view = this.session.read()
     try {
-      this.session.applyProposal(waiting.steps, view.revision!, view.context!)
+      /* Created under the proposal's key: taken twice, it meets the first figure, never a second (ADR-0097 §5.6 item 5). */
+      if (waiting.key) this.session.createUnder(waiting.key)
+      this.session.applyProposal(waiting.steps, view.revision!, view.context!, waiting.key)
       waiting.settle({ applied: true })
     } catch (error) {
       waiting.settle({ applied: false, code: (error as { code?: string })?.code, error: error instanceof Error ? error.message : String(error) })
@@ -429,11 +462,14 @@ export class FigureModellerPage extends PageView {
   /** The first save's question, over the names this domain already uses. */
   private askFirstSave = async (name: string): Promise<FirstSave | undefined> => {
     const taken = await fetchFigureTypeNames().catch(() => [] as string[])
-    return openPopup<FirstSave>(html`<figure-first-save .type=${this.row.type ?? ''} .name=${name} .taken=${taken}></figure-first-save>`, {
+    const answer = await openPopup<FirstSave>(html`<figure-first-save .type=${this.row.type ?? ''} .name=${name} .taken=${taken}></figure-first-save>`, {
       backdrop: true,
       size: 'small',
       title: i18next.t('figure.title.save-new-figure')
     }).result
+    /* Kept: a first save that failed opens again on the same identifier, not a new draw (ADR-0097 §5.6, Q-D3). */
+    if (answer) this.row = { ...this.row, type: answer.type }
+    return answer
   }
   get context() {
     return {
@@ -450,7 +486,8 @@ export class FigureModellerPage extends PageView {
   render() {
     if (this.error) return html`<p role="alert" class="error">${this.error}</p>`
     const view = this.session.read()
-    return html`<figure-editor .session=${this.session} .templates=${this.templates} .guideOf=${this.guideOf} .thumbnailOf=${this.thumbnailOf} .firstSave=${this.askFirstSave} .revision=${this.revision} .instances=${this.instances} .budget=${this.budget} @changed=${this.changed}>
+    /* A new figure's third way to start: the app's assistant dock, with a request put in its input for the author to finish and send (B, U04). */
+    return html`<figure-editor .session=${this.session} .releaseState=${this.row} .templates=${this.templates} .guideOf=${this.guideOf} .thumbnailOf=${this.thumbnailOf} .firstSave=${this.askFirstSave} .revision=${this.revision} .instances=${this.instances} .budget=${this.budget} aiDraft @ask-ai-draft=${() => askAssistant({ draft: i18next.t('figure.text.ai-draft-request') })} @changed=${this.changed}>
       ${this.commandError ? html`<p slot="notice" fit-error role="alert">${this.commandError}</p>` : ''}
       <figure-properties
         slot="figure"
@@ -491,6 +528,8 @@ export class FigureModellerPage extends PageView {
         .figureVersion=${this.row.version}
         .figureType=${this.row.type}
         .dirty=${!!view.dirty}
+        .saveFirst=${this.saveBeforeRevert}
+        .serverSource=${() => this.session.confirmedSource()}
         @fit-base-to-parts=${this.fitToParts}
         @figure-released=${this.released}
         @figure-reverted=${this.reverted}

package/dist-client/figure-assistant.js

@@ -18,8 +18,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/dist-client/figure-assistant.js.map

@@ -1 +1 @@
-{"version":3,"file":"figure-assistant.js","sourceRoot":"","sources":["../client/figure-assistant.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mDAAmD,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAA0B,MAAM,2BAA2B,CAAA;AAEpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAA;AAE7D,uBAAuB,CAAC,qBAAqB,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE;IACzE,MAAM,OAAO,GAAG,MAAM,iBAAiB,CACrC,QAAQ,EACR;QACE,KAAK,CAAC,MAAyB;YAC7B,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;YACjE,OAAO,MAAM,CAAA;QACf,CAAC;QACD,OAAO,CAAC,KAAK;YACX,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;YACnC,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAA;YAC1B,OAAO,MAAM,CAAA;QACf,CAAC;KACF,EACD,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CACxC,CAAA;IACD,IAAI,OAAO,CAAC,IAAI;QAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACjG,OAAO,OAAO,CAAA;AAChB,CAAC,CAAC,CAAA","sourcesContent":["/*\n * What the AI dock does with a figure proposal - figure-ui declares it because figure-service declares the tool\n * (`proposeFigureCandidate`, design/ai/shared-dock.md §4).\n *\n * A proposal is a list of the modeller's own commands (ADR-0094). Running it applies them in the modeller as one step\n * of its history: a revision on the figure open there, at the version the model saw; a new figure on a new figure the\n * modeller opens. The outcome is said in words on every branch (`ai-proposal.ts`).\n */\nimport { i18next } from '@operato/i18n'\nimport { navigate } from '@operato/shell'\nimport { registerProposalHandler } from '@things-factory/ai-assistant/dist-client/index.js'\n\nimport { modellerPathOf } from './modeller/modeller-route.js'\nimport { pendNewFigure, runFigureProposal, type FigureApplyDetail } from './modeller/ai-proposal.js'\n\nexport const FIGURE_CANDIDATE_TOOL = 'proposeFigureCandidate'\n\nregisterProposalHandler(FIGURE_CANDIDATE_TOOL, async (proposal, context) => {\n  const outcome = await runFigureProposal(\n    proposal,\n    {\n      offer(detail: FigureApplyDetail) {\n        window.dispatchEvent(new CustomEvent('figure-apply', { detail }))\n        return detail\n      },\n      openNew(steps) {\n        const opened = pendNewFigure(steps)\n        navigate(modellerPathOf())\n        return opened\n      }\n    },\n    (key, params) => i18next.t(key, params)\n  )\n  if (outcome.note) context.notify(outcome.verdict === 'accepted' ? 'info' : 'error', outcome.note)\n  return outcome\n})\n"]}
+{"version":3,"file":"figure-assistant.js","sourceRoot":"","sources":["../client/figure-assistant.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mDAAmD,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAA0B,MAAM,2BAA2B,CAAA;AAEpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAA;AAE7D,uBAAuB,CAAC,qBAAqB,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE;IACzE,MAAM,OAAO,GAAG,MAAM,iBAAiB,CACrC,QAAQ,EACR;QACE,KAAK,CAAC,MAAyB;YAC7B,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;YACjE,OAAO,MAAM,CAAA;QACf,CAAC;QACD,OAAO,CAAC,KAAK,EAAE,GAAG;YAChB,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YACxC,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAA;YAC1B,OAAO,MAAM,CAAA;QACf,CAAC;KACF,EACD,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CACxC,CAAA;IACD,IAAI,OAAO,CAAC,IAAI;QAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACjG,OAAO,OAAO,CAAA;AAChB,CAAC,CAAC,CAAA","sourcesContent":["/*\n * What the AI dock does with a figure proposal - figure-ui declares it because figure-service declares the tool\n * (`proposeFigureCandidate`, design/ai/shared-dock.md §4).\n *\n * A proposal is a list of the modeller's own commands (ADR-0094). Running it applies them in the modeller as one step\n * of its history: a revision on the figure open there, at the version the model saw; a new figure on a new figure the\n * modeller opens. The outcome is said in words on every branch (`ai-proposal.ts`).\n */\nimport { i18next } from '@operato/i18n'\nimport { navigate } from '@operato/shell'\nimport { registerProposalHandler } from '@things-factory/ai-assistant/dist-client/index.js'\n\nimport { modellerPathOf } from './modeller/modeller-route.js'\nimport { pendNewFigure, runFigureProposal, type FigureApplyDetail } from './modeller/ai-proposal.js'\n\nexport const FIGURE_CANDIDATE_TOOL = 'proposeFigureCandidate'\n\nregisterProposalHandler(FIGURE_CANDIDATE_TOOL, async (proposal, context) => {\n  const outcome = await runFigureProposal(\n    proposal,\n    {\n      offer(detail: FigureApplyDetail) {\n        window.dispatchEvent(new CustomEvent('figure-apply', { detail }))\n        return detail\n      },\n      openNew(steps, key) {\n        const opened = pendNewFigure(steps, key)\n        navigate(modellerPathOf())\n        return opened\n      }\n    },\n    (key, params) => i18next.t(key, params)\n  )\n  if (outcome.note) context.notify(outcome.verdict === 'accepted' ? 'info' : 'error', outcome.note)\n  return outcome\n})\n"]}

package/dist-client/graphql/index.d.ts

@@ -39,8 +39,45 @@ export declare function deleteFigure(id: string): Promise<boolean>;
  * 발행을 푼다(초안으로 돌아온다).
  */
 export declare function releaseFigure(id: string, comment?: string): Promise<Figure>;
-/** 옛 판을 초안으로 되살린다. 정본·속성·그림이 돌아오고 이름·설명은 그대로다. */
-export declare function revertFigureVersion(id: string, version: number): Promise<SaveResult>;
+/** 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;
+    };
+}
+/**
+ * 옛 판을 초안으로 되살린다. 정본·속성·그림이 돌아오고 이름·설명은 그대로다. 덮이는 초안은 같은 트랜잭션에서 서버가
+ * 보관한다. `expectedSource` 는 서버가 들고 있다고 확인된 정본 -- 그 사이 바뀌었으면 거절된다. 답을 못 받았으면
+ * (REVERT_UNREACHABLE) 같은 `requestId` 로 다시 묻는다: 서버는 같은 되돌리기로 답하고 두 번 하지 않는다.
+ */
+export declare function revertFigureVersion(id: string, version: number, requestId: string, expectedSource: string): Promise<SaveResult & {
+    kept: KeptDraft;
+}>;
+/** 되돌리기 취소 -- 보관한 초안을 되살린다. 되돌린 뒤 모델이 바뀌었으면 서버가 거절하고 보관본은 남는다. */
+export declare function undoFigureRevert(keptId: string, requestId: string): Promise<SaveResult & {
+    kept: KeptDraft;
+}>;
+/** 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 declare function fetchProposalOutcome(proposalKey: string): Promise<ProposalOutcome[]>;
+/** 되돌리기가 보관한 초안들, 새것부터 -- 다시 접속해도 여기서 찾는다. */
+export declare function fetchReplacedDrafts(id: string): Promise<KeptDraft[]>;
 /**
  * 발행해도 되나 — **누르기 전에** 묻는다.
  *