@things-factory/figure-ui 10.1.151 → 10.1.153

package/client/modeller/ai-proposal.ts

@@ -7,6 +7,7 @@
  */
 import type { FigureProposalStep } from '@hatiolab/figure-model'
 import type { FigureProductSession } from './product-session.js'
+import { clipLossOf, refusalRecordOf, type FigureRefusalRecord } from './refusals.js'
 
 /** What the card carries, as `proposeFigureCandidate` returned it. */
 export interface FigureProposalCard {
@@ -19,8 +20,11 @@ export interface FigureProposalCard {
   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
@@ -28,9 +32,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
@@ -63,7 +64,9 @@ export function proposalOutcomeFrom(saved: ReadonlyArray<{ figureId: string; typ
 /** 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, clips?: string[]): FigureProposalOutcome {
+function refused(refusal: FigureRefusalRecord & { error?: string }, say: Say): FigureProposalOutcome {
+  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).
@@ -73,8 +76,8 @@ function refused(code: string | undefined, error: string | undefined, say: Say,
       ? 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 }
 }
@@ -110,10 +113,8 @@ export function takeFigureOffer(
     return true
   } catch (error) {
     detail.applied = false
-    detail.code = (error as { code?: string })?.code
+    Object.assign(detail, refusalRecordOf(error))
     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
   }
 }
@@ -130,7 +131,7 @@ export async function runFigureProposal(card: FigureProposalCard, target: Figure
 
   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, detail.clips)
+  if (detail.applied === false) 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') }
@@ -139,7 +140,7 @@ export async function runFigureProposal(card: FigureProposalCard, target: Figure
   if (opened.applied) 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)
 }
 
 /*

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

@@ -0,0 +1,210 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+import { i18next } from '@operato/i18n'
+import { figurePartFaceOf, figureRowOf, type FigureAuthoringAction, type FigureFaceArea } from '@hatiolab/figure-model'
+import { faceHighlightOf, ghostPartsOf, previewWordsOf, type HeldPreview } from './command-preview.js'
+import { partLabelOf } from './fields.js'
+import type { FigureProductSession } from './product-session.js'
+import type { FigureRenderPart } from './renderer.js'
+import { derivedHeld, derivedOf, 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 const NO_WORDS: string[] = []
+
+/** How long a command's candidate rests before its preview is worked out. */
+const PREVIEW_SETTLE_MS = 150
+
+/** 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 class CommandPreview implements ReactiveController {
+  private preview?: HeldPreview & { part: string }
+  private drawn?: { of: HeldPreview; ghost: FigureRenderPart[]; highlight: FigureRenderPart | null }
+  /*
+    What a panel is handed is the same object while it says the same thing: a new array each render reads as a change to
+    the panel, which draws itself again for nothing (sixteen times for one edit).
+  */
+  private wordsSaid?: { preview: unknown; part: string; language: string; words: string[] }
+  private previewTimer?: ReturnType<typeof setTimeout>
+  /*
+    What taking the selected part off would do, worked out on a copy before the button is pressed (ADR-0097 §5.5): whether
+    it stays where it stands now, what stays fastened to it, which clips would go. "It stays where it is" is said only
+    when the copy shows it does.
+  */
+  private detachTimer?: ReturnType<typeof setTimeout>
+  private detachAsked?: { shown: FigureRevision; part: string }
+
+  constructor(
+    private readonly host: ReactiveControllerHost,
+    private readonly of: CommandPreviewHost
+  ) {
+    host.addController(this)
+  }
+
+  hostConnected() {}
+
+  hostDisconnected() {
+    clearTimeout(this.previewTimer)
+    clearTimeout(this.detachTimer)
+  }
+
+  /** Drawn again only when it is another preview, as a state of the editor would be. */
+  private hold(preview: (HeldPreview & { part: string }) | undefined) {
+    if (preview === this.preview) return
+    this.preview = preview
+    this.host.requestUpdate()
+  }
+
+  /**
+   * 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) {
+    clearTimeout(this.previewTimer)
+    const session = this.of.session()
+    const selected = this.of.selected()
+    if (!candidate || !session || !selected) {
+      this.hold(undefined)
+      return
+    }
+    const view = session.read()
+    const key = JSON.stringify(candidate)
+    const same =
+      this.preview &&
+      this.preview.key === key &&
+      this.preview.context === view.context &&
+      this.preview.part === selected &&
+      'revision' in this.preview &&
+      this.preview.revision === view.revision
+    if (same) return
+    /*
+      What another command would do is not said of this one while this one is worked out: a row's pitch refused stayed
+      on screen for the count chosen after it (:3300, 2026-10-11).
+    */
+    if (this.preview && this.preview.key !== key) this.hold(undefined)
+    this.previewTimer = setTimeout(() => this.compute(candidate), PREVIEW_SETTLE_MS)
+  }
+
+  private compute(candidate: PreviewCandidate) {
+    const session = this.of.session()
+    const selected = this.of.selected()
+    if (!session || !selected) return
+    const view = session.read()
+    const held = { context: view.context!, revision: view.revision!, key: JSON.stringify(candidate), part: selected }
+    try {
+      const seen = session.previewCommand(candidate.action)
+      let face: FigureFaceArea | undefined
+      if (candidate.face) {
+        try {
+          const shown = this.of.shown()!
+          face = figurePartFaceOf(shown.asset, candidate.face.part, candidate.face.face, shown.inputs)
+        } catch {
+          face = undefined
+        }
+      }
+      /* A row is read on the figure the command would make, by figure-model, as drawn. */
+      const row = candidate.action.kind === 'make-repeat' ? figureRowOf(seen.asset, selected, this.of.shown()!.inputs) : undefined
+      this.hold({
+        ...held,
+        context: seen.context,
+        revision: seen.revision,
+        geometry: seen.geometry,
+        moves: seen.moves,
+        added: seen.added,
+        ...(row ? { row } : {}),
+        clipsWouldGo: seen.clipsWouldGo,
+        face,
+        faceUnknown: !!candidate.face && !face
+      })
+    } catch (error) {
+      /* Refused: nothing of an earlier result stays on screen, and the reason is said. */
+      this.hold({ ...held, refused: this.of.said(error) })
+    }
+  }
+
+  /** The preview, while it still speaks of what is on screen: this figure, this version, this part. */
+  current(): (HeldPreview & { part: string }) | undefined {
+    const p = this.preview
+    const view = this.of.session()?.read()
+    /* Only where its form is: the properties panel stays in the page on another tab, and did not clear it (2026-09-27, :3391). */
+    if (!p || !view || p.context !== view.context || p.revision !== view.revision || p.part !== this.of.selected() || !this.of.formsInSight()) return undefined
+    return p
+  }
+
+  /** What the preview says, the same array while it says the same thing. */
+  words(): string[] {
+    const preview = this.current()
+    const selected = this.of.selected()
+    const language = i18next.language
+    if (this.wordsSaid && this.wordsSaid.preview === preview && this.wordsSaid.part === selected && this.wordsSaid.language === language) return this.wordsSaid.words
+    const words = previewWordsOf(preview, selected, (key, params) => i18next.t(key, params))
+    this.wordsSaid = { preview, part: selected, language, words }
+    return words
+  }
+
+  /** 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 } {
+    if (!p || p.refused) return { ghost: [], highlight: null }
+    if (this.drawn?.of !== p) this.drawn = { of: p, ghost: ghostPartsOf(p), highlight: faceHighlightOf(p.face) }
+    return this.drawn
+  }
+
+  /**
+   * 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[] {
+    const part = this.of.selected()
+    if (!this.of.session() || !shown.asset.joints?.some(j => j.body1.part === part)) return NO_WORDS
+    const key = `detach|${part}`
+    const said = derivedHeld<string[]>(shown, key)
+    if (said) return said
+    if (this.detachAsked?.shown !== shown || this.detachAsked.part !== part) {
+      this.detachAsked = { shown, part }
+      clearTimeout(this.detachTimer)
+      this.detachTimer = setTimeout(() => {
+        if (this.of.shown() !== shown || this.of.selected() !== part) return
+        derivedOf(shown, key, () => this.computeDetachWords(shown, part))
+        this.host.requestUpdate()
+      }, PREVIEW_SETTLE_MS)
+    }
+    return NO_WORDS
+  }
+
+  private computeDetachWords(shown: FigureRevision, part: string): string[] {
+    const say = (k: string, params?: Record<string, string>) => i18next.t(k, params)
+    let words: string[]
+    try {
+      const seen = this.of.session()!.previewCommand({ kind: 'detach', part })
+      const own = seen.moves.some(m => m.body === part)
+      words = own
+        ? [say('figure.text.detach-moves'), ...previewWordsOf({ context: seen.context, revision: seen.revision, key: `detach|${part}`, moves: seen.moves }, part, say)]
+        : /* It stays where it is: as expected, so nothing is said (user 2026-10-01). */ []
+      const children = (shown.asset.joints ?? []).filter(j => 'part' in j.body0 && j.body0.part === part).map(j => partLabelOf(j.body1.part))
+      if (children.length) words.push(say('figure.text.detach-keeps-children', { parts: children.join(', ') }))
+      if (seen.clipsWouldGo.length) words.push(say('figure.text.detach-clips', { clips: seen.clipsWouldGo.map(c => c.clip).join(', ') }))
+    } catch (error) {
+      words = [say('figure.text.detach-refused', { reason: this.of.said(error) })]
+    }
+    return words
+  }
+}

package/client/modeller/editor-styles.ts

@@ -0,0 +1,307 @@
+import { css } from 'lit'
+
+/** The modeller editor's own styles: the bar's tools, the panes, the start card, the side's tabs and panels. */
+export const EditorStyles = css`
+  :host {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+    /* The editor folds by the width it is given, not the window's (UX ruling, 2026-09-24). */
+    container-type: inline-size;
+    font: 13px sans-serif;
+    color: var(--md-sys-color-on-surface);
+  }
+  /* The bar over the work is ox-canvas-bar (ADR-0060 decision 8): the folds at its edges, undo, redo and
+     fit in the suite's places. What the editor puts in it - the mode switch, the status, save - is styled here. */
+  ox-canvas-bar button[mode] {
+    height: 28px;
+    padding: 0 10px;
+    border-radius: 999em;
+    border-color: transparent;
+    background: none;
+  }
+  ox-canvas-bar button[mode][aria-pressed='true'] {
+    border-color: var(--md-sys-color-primary);
+  }
+  /* The gizmo's tools, drawn as the bar's own icon buttons (undo, redo, fit). */
+  ox-canvas-bar .gizmo-tools {
+    display: inline-flex;
+    gap: 2px;
+    padding-left: 4px;
+    border-left: 1px solid var(--md-sys-color-outline-variant);
+  }
+  ox-canvas-bar button[tool] {
+    display: inline-grid;
+    place-items: center;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    border: none;
+    border-radius: var(--md-sys-shape-corner-small, 8px);
+    background: transparent;
+    color: var(--md-sys-color-on-surface-variant);
+    cursor: pointer;
+  }
+  ox-canvas-bar button[tool]:hover:not(:disabled) {
+    background: var(--md-sys-color-surface-container-high);
+    color: var(--md-sys-color-on-surface);
+  }
+  ox-canvas-bar button[tool][aria-pressed='true'] {
+    background: var(--md-sys-color-secondary-container);
+    color: var(--md-sys-color-on-secondary-container);
+  }
+  ox-canvas-bar button[tool]:disabled {
+    opacity: 0.38;
+    cursor: default;
+  }
+  /*
+    Slotted into the bar from here, the tools do not get the bar's own icon size (20px, set inside its shadow): they
+    showed at md-icon's 24px, heavier than undo, redo and fit beside them. The same size, and the bar's focus ring.
+  */
+  ox-canvas-bar button[tool] md-icon {
+    --md-icon-size: 20px;
+  }
+  ox-canvas-bar button[tool]:focus-visible {
+    outline: 2px solid var(--md-sys-color-primary);
+    outline-offset: 1px;
+  }
+  figure-preview {
+    min-width: 0;
+    min-height: 0;
+  }
+  /* The edit canvas stays standing while the preview is in front (a 3D scene costs a third of a second to make), out of sight. */
+  div[middle][hidden] {
+    display: none;
+  }
+  /* The preview, once made, stays standing out of sight too: its 3D scene is not made again each time it is asked for. */
+  figure-preview[hidden] {
+    display: none;
+  }
+  ox-canvas-bar .status {
+    padding: 0 8px;
+    color: var(--md-sys-color-on-surface-variant);
+  }
+  ox-canvas-bar .status[dirty] {
+    color: var(--md-sys-color-primary);
+    font-weight: 600;
+  }
+  ox-canvas-bar button[save] {
+    height: 32px;
+    padding: 0 14px;
+    border: none;
+    border-radius: 999em;
+    color: var(--md-sys-color-on-primary);
+    background: var(--md-sys-color-primary);
+  }
+  /* The three panes are ox-three-pane's (ADR-0060 decision 8): widths 200 | 1fr | 340, 160 | 300 under
+     860px and one column with the middle first under 560px are the frame's, as are the dividers. */
+  ox-three-pane {
+    flex: 1;
+    min-height: 0;
+  }
+  figure-parts {
+    min-height: 0;
+  }
+  figure-canvas {
+    flex: 1;
+    min-width: 0;
+    min-height: 0;
+  }
+  div[middle] {
+    position: relative;
+    display: flex;
+    min-width: 0;
+    min-height: 0;
+  }
+  /* A new figure's first question, over the empty canvas. */
+  div[start] {
+    position: absolute;
+    inset: 50% auto auto 50%;
+    z-index: 10;
+    color: var(--md-sys-color-on-surface);
+    transform: translate(-50%, -50%);
+    width: min(440px, calc(100% - 32px));
+    box-sizing: border-box;
+    padding: 20px;
+    border-radius: 12px;
+    background: var(--md-sys-color-surface, #fff);
+    box-shadow: 0 6px 24px rgba(0, 0, 0, 0.18);
+  }
+  div[start] button[start-button] {
+    width: auto;
+    margin: 0;
+    font-size: var(--ui-t-body);
+    height: 36px;
+    padding: 0 16px;
+    border: 1px solid var(--md-sys-color-outline);
+    border-radius: 999em;
+    color: var(--md-sys-color-primary);
+    background: var(--md-sys-color-surface, #fff);
+    cursor: pointer;
+  }
+  div[start] button[start-button]:hover:not(:disabled) {
+    background: var(--md-sys-color-primary-container);
+  }
+  div[start] button[start-button][pressed] {
+    color: var(--md-sys-color-on-primary);
+    background: var(--md-sys-color-primary);
+    border-color: var(--md-sys-color-primary);
+  }
+  div[start] button[start-button]:disabled {
+    opacity: 0.5;
+    cursor: default;
+  }
+  div[start] h2 {
+    margin: 0 0 12px;
+    font-size: var(--ui-t-title);
+  }
+  div[start-paths] {
+    display: grid;
+    gap: 14px;
+  }
+  div[start-paths] h3 {
+    margin: 0 0 6px;
+    font-size: var(--ui-t-body);
+  }
+  div[start-shapes] {
+    display: flex;
+    gap: 8px;
+    flex-wrap: wrap;
+  }
+  div[start] small {
+    display: block;
+    margin-top: 4px;
+    color: var(--md-sys-color-on-surface-variant);
+  }
+  /* The side: tabs over one panel at a time, each using the whole height. */
+  aside {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    background: var(--md-sys-color-surface-container-lowest);
+  }
+  div[tabs] {
+    display: flex;
+    flex: none;
+    border-bottom: 1px solid var(--md-sys-color-outline-variant);
+  }
+  button[tab] {
+    flex: 1;
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 1px;
+    min-width: 0;
+    height: 48px;
+    padding: 0;
+    border: none;
+    border-radius: 0;
+    border-bottom: 2px solid transparent;
+    background: none;
+    color: var(--md-sys-color-on-surface-variant);
+  }
+  button[tab]:hover:not([on]) {
+    background: var(--md-sys-color-surface-container);
+  }
+  button[tab][on] {
+    color: var(--md-sys-color-primary);
+    border-bottom-color: var(--md-sys-color-primary);
+  }
+  button[tab] md-icon {
+    font-size: 20px;
+    width: 20px;
+    height: 20px;
+  }
+  button[tab] span[tab-label] {
+    max-width: 100%;
+    overflow: hidden;
+    font-size: 0.66rem;
+    line-height: 1.2;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  span[badge] {
+    position: absolute;
+    top: 3px;
+    right: 2px;
+    padding: 0 5px;
+    font-size: 0.62rem;
+    font-weight: 700;
+    line-height: 1.5;
+    color: var(--md-sys-color-on-primary-container);
+    background: var(--md-sys-color-primary-container);
+    border-radius: 999em;
+    pointer-events: none;
+  }
+  /* The sections inside carry the margins (side-panel-styles); the panel only scrolls. */
+  div[panel] {
+    flex: 1;
+    min-height: 0;
+    overflow: auto;
+    padding: 0;
+  }
+  div[panel][flush] {
+    padding: 0;
+  }
+  /* Hidden, not removed: a panel keeps what it holds (the verdict its last answer) while another tab is open. */
+  [off] {
+    display: none !important;
+  }
+  /* Which part the panel speaks of. */
+  div[subject] {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    display: grid;
+    gap: 4px;
+    padding: 10px 12px;
+    background: var(--md-sys-color-surface-container-lowest);
+    border-bottom: 1px solid var(--md-sys-color-outline-variant);
+  }
+  /* The panel's three sizes (side-panel-styles): the part's kind at the title's, its two lines at the hint's. */
+  div[subject-summary] {
+    display: grid;
+    gap: 2px;
+  }
+  div[subject-summary] b {
+    font-size: var(--ui-t-body, 13px);
+    font-weight: 600;
+  }
+  div[subject-summary] b span {
+    font-weight: 400;
+    color: var(--md-sys-color-on-surface-variant);
+  }
+  div[subject-summary] small {
+    color: var(--md-sys-color-on-surface-variant);
+  }
+  button {
+    font: inherit;
+    box-sizing: border-box;
+    height: 32px;
+    border: 1px solid var(--md-sys-color-outline-variant);
+    border-radius: 6px;
+    background: var(--md-sys-color-surface);
+    color: inherit;
+    padding: 0 8px;
+    min-width: 0;
+  }
+  button {
+    cursor: pointer;
+  }
+  button:disabled {
+    opacity: 0.45;
+    cursor: default;
+  }
+  button[aria-pressed='true'] {
+    background: var(--md-sys-color-secondary-container);
+    color: var(--md-sys-color-on-secondary-container);
+    border-color: var(--md-sys-color-primary);
+  }
+  .hint {
+    color: var(--md-sys-color-on-surface-variant);
+    line-height: 1.5;
+  }
+`