@things-factory/figure-ui 10.1.152 → 10.1.153

package/client/modeller/figure-first-save.ts

@@ -63,6 +63,15 @@ export class FigureFirstSave extends LitElement {
     if (offer.suggested !== undefined) this.suggested = offer.suggested
   }
 
+  /*
+    The name is focused here, each time the question opens. The browser honours `autofocus` once per document: the
+    question asked again opened with nothing focused, and any autofocus taken earlier on the page left even the first
+    opening unfocused (2026-10-11, product-page check).
+  */
+  firstUpdated() {
+    this.renderRoot.querySelector<HTMLInputElement>('#name')?.focus()
+  }
+
   render() {
     return html`
       <div class="what">${i18next.t('figure.text.save-new-figure-desc')}</div>
@@ -70,7 +79,6 @@ export class FigureFirstSave extends LitElement {
         <label for="name">${i18next.t('figure.label.name')}</label>
         <input
           id="name"
-          autofocus
           .value=${this.name}
           placeholder=${i18next.t('figure.text.figure-name-example')}
           @input=${(e: Event) => (this.name = (e.target as HTMLInputElement).value)}

package/client/modeller/modeller-keys.ts

@@ -0,0 +1,60 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+import { keyActionOf, type KeyAction } from './keys.js'
+
+/** What the keys ask of the editor. */
+export interface ModellerKeysHost {
+  /** Whether the modeller takes keys now: a figure open, not loading or saving, and no section editor open. */
+  taking(): boolean
+  /** The scene, whose keys the modeller's are too. */
+  scene(): Element | null
+  selected(): string
+  act(action: KeyAction): void
+}
+
+/**
+ * The modeller's keys (`keys.ts`): undo, redo, duplicate, remove, back to the whole figure, the gizmo's modes. Heard on
+ * the window, first (capture), while the editor is on the page.
+ */
+export class ModellerKeys implements ReactiveController {
+  constructor(
+    host: ReactiveControllerHost,
+    private readonly of: ModellerKeysHost
+  ) {
+    host.addController(this)
+  }
+
+  hostConnected() {
+    window.addEventListener('keydown', this.onKey, true)
+  }
+
+  hostDisconnected() {
+    window.removeEventListener('keydown', this.onKey, true)
+  }
+
+  private onKey = (e: KeyboardEvent) => {
+    if (!this.of.taking()) return
+    const canvas = this.of.scene()
+    const path = e.composedPath()
+    const action = keyActionOf(
+      {
+        key: e.key,
+        ctrlKey: e.ctrlKey,
+        metaKey: e.metaKey,
+        shiftKey: e.shiftKey,
+        altKey: e.altKey,
+        target: path[0] as HTMLElement,
+        inScene: !!canvas && path.includes(canvas)
+      },
+      this.of.selected()
+    )
+    if (!action) return
+    e.preventDefault()
+    /*
+      The session's history is the only one. With the canvas focused the scene took Ctrl+Z as well, undoing on its own
+      board the last value the canvas had written -- which the canvas then told as a drag: an undo of a drag on a
+      part placed by a rule wrote the drag again (2026-09-25). Heard first (capture) and kept from the scene.
+    */
+    e.stopPropagation()
+    this.of.act(action)
+  }
+}

package/client/modeller/pane-fold.ts

@@ -0,0 +1,61 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+import { i18next } from '@operato/i18n'
+import type { OxThreePane } from '@operato/layout'
+import { notify } from '@operato/layout'
+
+/** Whether the narrow fold was said in this browser before; true from now on. Storage refused: said, as before. */
+function foldSaid(): boolean {
+  try {
+    if (localStorage.getItem('figure-fold-said')) return true
+    localStorage.setItem('figure-fold-said', '1')
+  } catch {
+    /* No storage here: said every time, as it was. */
+  }
+  return false
+}
+
+/*
+  Narrow, the parts list gives way to the canvas rather than all three shrinking (designer 2026-09-27, U11): under
+  FOLD_START_UNDER px the canvas would be left under about 560 px beside both sides. The fold is said once, and the
+  bar's own toggle opens it again; opened by the author, it is not folded again until the screen has been wide.
+  Said once in this browser, not on every opening (2026-10-02): the list folds as before, the notice does not come back.
+*/
+export class PaneFold implements ReactiveController {
+  static readonly FOLD_START_UNDER = 1100
+  private foldedForWidth = false
+  private keptOpenByAuthor = false
+  private widthWatch = new ResizeObserver(([entry]) => this.fitTo(entry!.contentRect.width))
+
+  /** `panes` is the frame the bar folds, once it is drawn. */
+  constructor(
+    private readonly host: ReactiveControllerHost & HTMLElement,
+    private readonly panes: () => OxThreePane | undefined
+  ) {
+    host.addController(this)
+  }
+
+  hostConnected() {
+    this.widthWatch.observe(this.host)
+  }
+
+  hostDisconnected() {
+    this.widthWatch.disconnect()
+  }
+
+  fitTo(width: number) {
+    const panes = this.panes()
+    if (!panes || !width) return
+    if (this.foldedForWidth && !panes.foldStart) this.keptOpenByAuthor = true
+    if (width < PaneFold.FOLD_START_UNDER) {
+      if (!panes.foldStart && !this.keptOpenByAuthor) {
+        panes.foldStart = true
+        this.foldedForWidth = true
+        if (!foldSaid()) notify({ level: 'info', message: i18next.t('figure.text.parts-panel-folded-narrow') })
+      }
+    } else {
+      if (this.foldedForWidth && panes.foldStart) panes.foldStart = false
+      this.foldedForWidth = false
+      this.keptOpenByAuthor = false
+    }
+  }
+}

package/client/modeller/panel-memory.ts

@@ -0,0 +1,53 @@
+/*
+  Per model and per part, how far its properties panel was scrolled and which of its folds were open, so going back
+  to one finds it as it was left (designer 2026-09-27, B.1). The path stays held at the top, so a scroll kept cannot
+  hide which part the panel speaks of. Another model starts clean.
+*/
+export class PanelMemory {
+  private kept = new Map<string, { top: number; open: boolean[] }>()
+  private restoreFor?: string
+
+  /** `root` is where the properties panel is drawn: the editor's render root. */
+  constructor(private readonly root: () => ParentNode) {}
+
+  private panel() {
+    return this.root().querySelector<HTMLElement>('div[panel]')
+  }
+
+  private foldsOf(panel: HTMLElement): HTMLDetailsElement[] {
+    const folds = [...panel.querySelectorAll('details')]
+    for (const inner of panel.querySelectorAll('figure-links')) folds.push(...(inner.shadowRoot?.querySelectorAll('details') ?? []))
+    return folds
+  }
+
+  /** Another model: nothing kept. */
+  clear() {
+    this.kept.clear()
+  }
+
+  /** The selection moves from `was` to `now` ('' is the model): the panel as `was` left it is kept, `now`'s put back after the update. */
+  leave(was: string, now: string) {
+    const panel = this.panel()
+    if (panel) this.kept.set(was || '@model', { top: panel.scrollTop, open: this.foldsOf(panel).map(d => d.open) })
+    this.restoreFor = now || '@model'
+  }
+
+  /** After the update: the panel of the part chosen as it was left, while that part is still the one chosen. */
+  restore(selected: () => string) {
+    if (this.restoreFor === undefined) return
+    const key = this.restoreFor
+    this.restoreFor = undefined
+    /*
+      Put back as soon as the links have drawn, before any click can come: the updates are microtasks. Put back a
+      frame later, it closed a fold opened by a click in that frame (2026-10-11, the row on a bench under load).
+    */
+    const panel = this.panel()
+    if (panel)
+      void Promise.all([...panel.querySelectorAll<HTMLElement & { updateComplete?: Promise<unknown> }>('figure-links')].map(el => el.updateComplete)).then(() => {
+        if ((selected() || '@model') !== key) return
+        const kept = this.kept.get(key)
+        if (kept) this.foldsOf(panel).forEach((fold, i) => i < kept.open.length && (fold.open = kept.open[i]!))
+        panel.scrollTop = kept?.top ?? 0
+      })
+  }
+}

package/client/modeller/refusal-teller.ts

@@ -0,0 +1,93 @@
+import type { PropertyValues } from 'lit'
+import { i18next } from '@operato/i18n'
+import { notify } from '@operato/layout'
+import { OxPrompt } from '@operato/popup'
+import type { FigureAuthoringAction, FigureClipLoss } from '@hatiolab/figure-model'
+import type { FigureProductSession } from './product-session.js'
+import { clipLossOf } from './refusals.js'
+
+/** The same link offered again with the size range narrowed, after a link the declared range could not hold. */
+export type Retry = { label: string; action?: FigureAuthoringAction; run?: () => void }
+
+/** What the teller reads of the editor, and what it asks of it. */
+export interface RefusalHost {
+  session(): FigureProductSession | undefined
+  error(): string
+  notice(): string
+  retry(): Retry | undefined
+  /** Said as the editor's refusal. */
+  refuse(message: string): void
+  /** A narrowed link, confirmed: run as the editor runs a command. */
+  command(action: FigureAuthoringAction): void
+}
+
+/**
+ * Refusals and notices go to the app's shared surfaces, as every screen's do (user, 2026-09-27: 「왜 모두가 사용하는
+ * notification 오류 표현 방법을 사용하지 않고」 · 「혹은 oxprompt 에서 확인하고 진행하던지」). A refusal with a way on --
+ * delete and fit the space again, narrow the range -- asks in the app's prompt and goes on when confirmed; any
+ * other refusal is the app's notification, which stays until it is closed.
+ */
+export class RefusalTeller {
+  private toldViewError = ''
+
+  constructor(private readonly of: RefusalHost) {}
+
+  /** After the editor's update: what changed in its refusal and notice, and the session's own error, said once. */
+  tell(changed: PropertyValues) {
+    const error = this.of.error()
+    if (changed.has('error') && error) {
+      const retry = this.of.retry()
+      if (retry) this.ask(error, retry)
+      else notify({ level: 'error', message: error })
+    }
+    const notice = this.of.notice()
+    if (changed.has('notice') && notice) notify({ level: 'info', message: notice })
+    const viewError = this.of.session()?.read()?.error ?? ''
+    if (viewError && viewError !== this.toldViewError) notify({ level: 'error', message: viewError })
+    this.toldViewError = viewError
+  }
+
+  /*
+    An edit that would stop clips is refused by figure-model with the clips named (CLIPS_DROPPED). The person is told
+    which, and why, before anything is written; agreed, the same edit is made again letting exactly those go, as one
+    step undo brings back (designer 2026-09-27).
+  */
+  askClipLoss(error: unknown, again: () => void): boolean {
+    const clips = clipLossOf(error)
+    if (!clips) return false
+    /* The consent is for this edit, on this figure as it is now: held with it while the person reads. */
+    const session = this.of.session()!
+    const { context, revision } = session.read()
+    void this.confirmClipLoss(clips, again, { session, context: context!, revision: revision! })
+    return true
+  }
+
+  private async confirmClipLoss(clips: FigureClipLoss[], again: () => void, asked: { session: FigureProductSession; context: string; revision: number }) {
+    const agreed = await OxPrompt.open({
+      type: 'warning',
+      text: i18next.t('figure.text.clips-would-go', { clips: clips.map(c => i18next.t(`figure.text.clip-${c.why}`, { clip: c.clip })).join(', ') }),
+      confirmButton: { text: i18next.t('figure.button.let-clips-go') },
+      cancelButton: { text: i18next.t('figure.button.keep-editing') }
+    })
+    if (!agreed) return
+    /* Changed while the person read -- another figure, or an edit in between: the consent was not for this; nothing is applied. */
+    const now = this.of.session() === asked.session ? asked.session.read() : undefined
+    if (!now || now.context !== asked.context || now.revision !== asked.revision) {
+      this.of.refuse(i18next.t('figure.text.clips-consent-stale'))
+      return
+    }
+    asked.session.withConsent({ dropClips: clips.map(c => c.id), context: asked.context, revision: asked.revision }, again)
+  }
+
+  private async ask(message: string, retry: Retry) {
+    const agreed = await OxPrompt.open({
+      type: 'question',
+      text: message,
+      confirmButton: { text: retry.label },
+      cancelButton: { text: i18next.t('figure.button.keep-editing') }
+    })
+    if (!agreed) return
+    if (retry.run) retry.run()
+    else this.of.command(retry.action!)
+  }
+}

package/client/modeller/refusals.ts

@@ -7,7 +7,7 @@
  * English is for logs and readers of the kernel, and a screen that read it went quiet whenever a sentence changed or a
  * new one came under the same code (ADR-0054). A refusal with no details the screen knows is said with its code.
  */
-import { FIGURE_INSTANCE_SIZE_INPUTS, type FigureRefusalDetails } from '@hatiolab/figure-model'
+import { FIGURE_INSTANCE_SIZE_INPUTS, type FigureClipLoss, type FigureRefusalDetails } from '@hatiolab/figure-model'
 
 type Say = (key: string, params: Record<string, string>) => string
 type Reason = FigureRefusalDetails['reason']
@@ -70,6 +70,23 @@ export function placementRefusalOf(error: unknown, say: Say): string | null {
   })
 }
 
+/** A refusal carried on in a record (an AI proposal's outcome) in figure-model's own shape: its code and details. */
+export interface FigureRefusalRecord {
+  code?: string
+  details?: FigureRefusalDetails
+}
+
+/** The record of a refusal: figure-model's code and details, copied as they are. */
+export function refusalRecordOf(error: unknown): FigureRefusalRecord {
+  const { details } = (error ?? {}) as FigureRefusalRecord
+  return { code: codeOf(error), ...(details ? { details } : {}) }
+}
+
+/** The clips an edit would stop, as figure-model named them (CLIPS_DROPPED) -- the person is asked before any go; nothing for any other refusal. */
+export function clipLossOf(error: unknown): FigureClipLoss[] | null {
+  return codeOf(error) === 'CLIPS_DROPPED' ? (detailsOf(error, 'clips-dropped')?.clips ?? []) : null
+}
+
 /** A part refused because the declared room reads it -- the one refusal deleting it with the room refitted answers. */
 export function inDeclaredRoom(error: unknown): boolean {
   return codeOf(error) === 'PART_REFERENCED' && !!detailsOf(error, 'in-declared-space')

package/dist-client/modeller/ai-proposal.d.ts

@@ -1,5 +1,6 @@
 import type { FigureProposalStep } from '@hatiolab/figure-model';
 import type { FigureProductSession } from './product-session.js';
+import { type FigureRefusalRecord } from './refusals.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. */
@@ -10,8 +11,11 @@ export interface FigureProposalCard {
     context?: string;
     revision?: number;
 }
-/** The `figure-apply` event's detail. The page that takes it sets `applied`, and `error` when refused. */
-export interface FigureApplyDetail {
+/**
+ * The `figure-apply` event's detail. The page that takes it sets `applied`, and when refused `error` and the refusal in
+ * figure-model's shape (`code`, `details`, the `clips` it would stop).
+ */
+export interface FigureApplyDetail extends FigureRefusalRecord {
     key?: string;
     steps: FigureProposalStep[];
     create: boolean;
@@ -19,9 +23,6 @@ export interface FigureApplyDetail {
     revision?: number;
     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;
 export interface FigureProposalTarget {

package/dist-client/modeller/ai-proposal.js

@@ -1,3 +1,4 @@
+import { clipLossOf, refusalRecordOf } from './refusals.js';
 /**
  * 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`,
@@ -11,7 +12,9 @@ export function proposalOutcomeFrom(saved, say) {
 }
 /** 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, error, say, clips) {
+function refused(refusal, say) {
+    const { code, error } = refusal;
+    const clips = clipLossOf(refusal);
     /*
       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).
@@ -20,8 +23,8 @@ function refused(code, error, say, clips) {
         ? say('figure.text.proposal-stale')
         : code === 'NEW_FIGURE_UNSAVED'
             ? (error ?? '')
-            : code === 'CLIPS_DROPPED'
-                ? say('figure.text.proposal-would-drop-clips', { clips: (clips ?? []).join(', ') })
+            : clips
+                ? say('figure.text.proposal-would-drop-clips', { clips: clips.map(c => c.clip).join(', ') })
                 : say('figure.text.proposal-refused', { reason: error ?? '' });
     return { verdict: 'refused', errorCode: code ?? 'refused', note };
 }
@@ -58,11 +61,8 @@ export function takeFigureOffer(session, detail, { onSavedFigure, say }) {
     }
     catch (error) {
         detail.applied = false;
-        detail.code = error?.code;
+        Object.assign(detail, refusalRecordOf(error));
         detail.error = error instanceof Error ? error.message : String(error);
-        const clips = error?.clips;
-        if (clips)
-            detail.clips = clips.map(c => c.clip);
         return false;
     }
 }
@@ -80,7 +80,7 @@ export async function runFigureProposal(card, target, say) {
     if (detail.applied)
         return accepted();
     if (detail.applied === false)
-        return refused(detail.code, detail.error, say, detail.clips);
+        return refused(detail, say);
     /* 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') };
@@ -89,7 +89,7 @@ export async function runFigureProposal(card, target, say) {
         return accepted();
     return opened.code === 'not-opened'
         ? { verdict: 'unavailable', errorCode: 'not-opened', note: say('figure.text.proposal-not-opened') }
-        : refused(opened.code, opened.error, say);
+        : refused(opened, say);
 }
 /*
   A new figure's proposal handed to the modeller page across a navigation: the handler leaves it here and opens the

package/dist-client/modeller/ai-proposal.js.map

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

package/dist-client/modeller/clips.d.ts

@@ -35,5 +35,5 @@ export declare const trackEdit: (clip: Clip, track: ClipTrack, patch?: Partial<P
     clip: string;
     keys: ClipKey[];
     loop: "wrap" | "hold";
-    interpolation: "linear" | "step";
+    interpolation: "step" | "linear";
 };

package/dist-client/modeller/command-preview-controller.d.ts

@@ -0,0 +1,75 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type FigureAuthoringAction } from '@hatiolab/figure-model';
+import { type HeldPreview } from './command-preview.js';
+import type { FigureProductSession } from './product-session.js';
+import type { FigureRenderPart } from './renderer.js';
+import { type FigureRevision } from './revision.js';
+/** The words a panel is given when there are none: one array, so it does not read as a change. */
+export declare const NO_WORDS: string[];
+/** A command a form is trying, with the face it names when it names one. */
+export type PreviewCandidate = {
+    action: FigureAuthoringAction;
+    face?: {
+        part: string;
+        face: string;
+    };
+};
+/** What the preview reads of the editor. */
+export interface CommandPreviewHost {
+    session(): FigureProductSession | undefined;
+    selected(): string;
+    /** The figure on screen at its version (`revision.ts`). */
+    shown(): FigureRevision | undefined;
+    /** Whether the properties panel, where the forms are, is in sight: the edit middle, the properties tab. */
+    formsInSight(): boolean;
+    /** A refusal in the person's words. */
+    said(error: unknown): string;
+}
+/**
+ * A command seen before it is done (ADR-0097 §5.5): worked out on a copy for the figure, version, part and command it
+ * names, and shown only while all four are still the ones on screen. Nothing of it is saved or undone. And what taking
+ * the selected part off would do, worked out the same way. Both wait for the figure to rest; the editor taken down
+ * stops both.
+ */
+export declare class CommandPreview implements ReactiveController {
+    private readonly host;
+    private readonly of;
+    private preview?;
+    private drawn?;
+    private wordsSaid?;
+    private previewTimer?;
+    private detachTimer?;
+    private detachAsked?;
+    constructor(host: ReactiveControllerHost, of: CommandPreviewHost);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Drawn again only when it is another preview, as a state of the editor would be. */
+    private hold;
+    /**
+     * The fastening form's command, seen before it is done; null clears what was shown. What a command would do is worked
+     * out on a copy of the figure -- several compiles of it -- so it waits for the field to rest: a number typed digit by
+     * digit asks once, for the number it ends on. Clearing is at once, and the same question on the same version is not
+     * asked again.
+     */
+    ask(candidate: PreviewCandidate | null): void;
+    private compute;
+    /** The preview, while it still speaks of what is on screen: this figure, this version, this part. */
+    current(): (HeldPreview & {
+        part: string;
+    }) | undefined;
+    /** What the preview says, the same array while it says the same thing. */
+    words(): string[];
+    /** What the canvas draws of a preview, made once per preview: a new list every render would stand the board up each time. */
+    drawnOf(p: (HeldPreview & {
+        part: string;
+    }) | undefined): {
+        ghost: FigureRenderPart[];
+        highlight: FigureRenderPart | null;
+    };
+    /**
+     * Said once the figure has rested: working it out is a preview of the command on a copy (tens of milliseconds), and the
+     * edit that made this version should be on screen before it. Until then nothing is said, as for a part with no joint.
+     */
+    detachWords(shown: FigureRevision): string[];
+    private computeDetachWords;
+}