@things-factory/figure-ui 10.1.52 → 10.1.54

package/client/figure-assistant.ts

@@ -0,0 +1,20 @@
+/*
+ * What the AI dock does with a figure candidate - figure-ui declares it because figure-service declares the tool
+ * (`proposeFigureCandidate`, design/ai/shared-dock.md §4).
+ *
+ * Today a candidate cannot be taken anywhere. The proposer writes V2 figures and the modeller opens V3 only; the V2
+ * modeller that reviewed candidates was removed with its listeners (`figure-ai-review`, `figure-ai-stage`), and the
+ * server already refuses to propose for a V3 figure (`V3_PROPOSAL_UNAVAILABLE`). So the outcome is `unavailable`,
+ * said to the person in words, not a silent pass - until a proposer writes V3 changes, which the modeller takes
+ * through `figure-v3-apply`.
+ */
+import { i18next } from '@operato/i18n'
+import { registerProposalHandler } from '@things-factory/ai-assistant/dist-client/index.js'
+
+export const FIGURE_CANDIDATE_TOOL = 'proposeFigureCandidate'
+
+registerProposalHandler(FIGURE_CANDIDATE_TOOL, async (_proposal, context) => {
+  const note = i18next.t('figure.text.candidate-cannot-open')
+  context.notify('info', note)
+  return { verdict: 'unavailable', errorCode: 'v3-review-missing', note }
+})

package/client/index.ts

@@ -1,2 +1,3 @@
 export * from './types.js'
 export * from './graphql/index.js'
+export * from './figure-assistant.js'

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

@@ -52,7 +52,7 @@ const freshFasten = () => ({
   align: {} as Partial<Record<Axis, Alignment>>,
   alignMm: {} as Partial<Record<Axis, number>>
 })
-const freshMotion = (): MotionForm => ({ kind: 'slide', axis: 'x', id: '', min: 0, max: 500, follow: '', multiplier: 1, offset: 0 })
+const freshMotion = (): MotionForm => ({ kind: 'slide', axis: 'x', id: '', min: 0, max: 500, follow: '', multiplier: 1, offset: 0, travel: '', travelPlus: 0 })
 const freshRow = () => ({ axis: '' as Axis | '', pitch: 200, fills: true, count: 5 })
 const freshPlace = () => ({ role: 'grip' as 'seat' | 'grip', face: 'top' as V3Face, label: '', accepts: '', capacity: 1 })
 
@@ -89,6 +89,16 @@ export class FigureV3Links extends localize(i18next)(LitElement) {
     b[bound] {
       font-weight: 600;
     }
+    /* The difference a following measure keeps: under its choice, on the same line as its words. */
+    label[inline-plus] {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+    label[inline-plus] input {
+      flex: 1;
+      min-width: 0;
+    }
   `]
 
   /** The asset being edited. */
@@ -241,10 +251,32 @@ export class FigureV3Links extends localize(i18next)(LitElement) {
             ? html`<option value=${value} selected>${now.of === 'input' ? now.input : i18next.t('figure.label.follows-expression')}</option>`
             : nothing}
         </select>
+        ${now.of === 'instance' || now.of === 'part'
+          ? html`<span></span>
+              <label inline-plus>
+                ${i18next.t('figure.label.follows-plus')}
+                <input
+                  type="number"
+                  step="any"
+                  ?disabled=${this.locked}
+                  .value=${String(now.plus ?? 0)}
+                  @change=${(e: Event) => this.followPlus(axis, now, Number((e.target as HTMLInputElement).value) || 0)}
+                />
+              </label>`
+          : nothing}
       </div>`
     })
   }
 
+  /** The same source, the same share, a new difference: a leaf the opening less its gaps (link-dimension's `plus`). */
+  private followPlus(axis: Axis, now: Follow, plus: number) {
+    if (now.of !== 'instance' && now.of !== 'part') return
+    if ((now.plus ?? 0) === plus) return
+    const source: V3DimensionSource = now.of === 'instance' ? { of: 'instance', axis: now.axis } : { of: 'part', part: now.part, axis: now.axis }
+    const times = now.of === 'instance' ? now.times : (now.times ?? 1)
+    this.command({ kind: 'link-dimension', part: this.partId, axis, source, ...(times !== 1 ? { times } : {}), ...(plus ? { plus } : {}), replace: true })
+  }
+
   private follow(asset: V3Asset, axis: Axis, choice: string, now: Follow) {
     const following = now.of !== 'own'
     /* The measure as it stands: a dimension stops following at it, and a share is taken of it. */
@@ -382,8 +414,11 @@ export class FigureV3Links extends localize(i18next)(LitElement) {
                   <option value="max" ?selected=${how === 'max'}>${i18next.t(`figure.label.align-${axis}-max`)}</option>`
               : nothing}
             <option value="mm" ?selected=${how === 'mm'}>${i18next.t('figure.label.align-mm')}</option>
+            ${this.asset && hasInstanceSize(this.asset, axis)
+              ? html`<option value="share" ?selected=${how === 'share'}>${i18next.t('figure.label.align-share')}</option>`
+              : nothing}
           </select>
-          ${how === 'mm'
+          ${how === 'mm' || how === 'share'
             ? html`<span></span><input type="number" step="any" aria-label=${i18next.t('figure.label.align-mm')} .value=${String(f.alignMm[axis] ?? 0)} @change=${(e: Event) => setMm(axis, Number((e.target as HTMLInputElement).value) || 0)} />`
             : nothing}`
       })}
@@ -438,6 +473,9 @@ export class FigureV3Links extends localize(i18next)(LitElement) {
       return html`<div pair>
         <span>
           ${i18next.t('figure.label.motion-' + now.kind)} · ${String(now.axis).toUpperCase()}
+          ${now.travel
+            ? html`<small>${i18next.t('figure.label.motion-travel-is', { part: now.travel.part, axis: now.travel.axis.toUpperCase(), plus: now.travel.plus ?? 0 })}</small>`
+            : nothing}
           ${now.follows
             ? html`<small>${i18next.t('figure.label.motion-follows', { joint: now.follows.joint, multiplier: now.follows.multiplier, offset: now.follows.offset ?? 0 })}</small>`
             : now.control
@@ -488,9 +526,23 @@ export class FigureV3Links extends localize(i18next)(LitElement) {
             <input type="number" step="any" .value=${String(m.offset)} @change=${(e: Event) => (this.motion = { ...m, offset: Number((e.target as HTMLInputElement).value) || 0 })} />
           </div>`
         : html`<div form>
+            ${m.kind === 'slide'
+              ? html`<span>${i18next.t('figure.label.motion-travel')}</span>
+                  <select @change=${(e: Event) => (this.motion = { ...m, travel: (e.target as HTMLSelectElement).value })}>
+                    <option value="" ?selected=${!m.travel}>${i18next.t('figure.label.motion-travel-mm')}</option>
+                    ${asset.appearance
+                      .map(look => look.target)
+                      .filter(one => canFollow(asset, one))
+                      .flatMap(one => AXES.map(a => html`<option value=${`${one}:${a}`} ?selected=${m.travel === `${one}:${a}`}>${one} · ${a.toUpperCase()}</option>`))}
+                  </select>
+                  ${m.travel
+                    ? html`<span>${i18next.t('figure.label.follows-plus')}</span>
+                        <input type="number" step="any" .value=${String(m.travelPlus ?? 0)} @change=${(e: Event) => (this.motion = { ...m, travelPlus: Number((e.target as HTMLInputElement).value) || 0 })} />`
+                    : nothing}`
+              : nothing}
             <span>${i18next.t('figure.label.control-id')}</span>
             <input .value=${m.id} placeholder=${`${this.partId}-${m.kind}`} @change=${(e: Event) => (this.motion = { ...m, id: (e.target as HTMLInputElement).value.trim() })} />
-            ${m.kind === 'continuous'
+            ${m.kind === 'continuous' || (m.kind === 'slide' && m.travel)
               ? nothing
               : html`<span>${i18next.t('figure.label.control-range')} (${unit})</span>
                   <div pair>
@@ -500,7 +552,7 @@ export class FigureV3Links extends localize(i18next)(LitElement) {
           </div>`}
       <button
         act
-        ?disabled=${this.locked || (follow ? !(Number.isFinite(m.multiplier) && m.multiplier !== 0) : m.kind !== 'continuous' && !(m.max > m.min && m.min <= 0 && 0 <= m.max))}
+        ?disabled=${this.locked || (follow ? !(Number.isFinite(m.multiplier) && m.multiplier !== 0) : m.kind !== 'continuous' && !(m.kind === 'slide' && m.travel) && !(m.max > m.min && m.min <= 0 && 0 <= m.max))}
         title=${!follow && m.kind !== 'continuous' && !(m.min <= 0 && 0 <= m.max) ? i18next.t('figure.text.joint-range-holds-zero') : ''}
         @click=${() => this.command({ kind: 'set-joint', joint: motionJoint(joint, { ...m, follow }, this.partId) })}
       >

package/client/modeller/v3-editor.ts

@@ -28,7 +28,7 @@ import type { V3PaletteKind, V3PartRow } from './figure-v3-parts.js'
 import { paletteRecipe } from './v3-palette.js'
 import type { FigureV3Canvas } from './v3-canvas.js'
 import { nudgeOf } from './v3-stage-model.js'
-import { sizeRangeRefusalOf } from './v3-refusals.js'
+import { narrowingRetryOf, partRefusalOf, sizeRangeRefusalOf } from './v3-refusals.js'
 import type { V3RenderPart } from './v3-renderer.js'
 import type { V3BudgetLine } from './v3-maturity.js'
 import { instanceRangeOf, instanceRangeToDeclare, rangeDiffers, turnsAboutAJoint } from './v3-links.js'
@@ -238,6 +238,8 @@ export class FigureV3Editor extends LitElement {
   @property({ attribute: false }) firstSave?: (name: string) => Promise<FirstSave | undefined>
   @state() private selected = ''
   @state() private error = ''
+  /** The same link offered again with the size range narrowed, after a link the declared range could not hold. */
+  @state() private retry?: { label: string; action: V3AuthoringAction }
   @state() private tab: SideTab = 'properties'
   /** The frame the bar folds - found after the first render, since the bar is drawn before it. */
   @state() private panes?: OxThreePane
@@ -425,12 +427,7 @@ export class FigureV3Editor extends LitElement {
       this.changed()
     } catch (error) {
       /* The refusal a person meets most: another part stands on this one or follows its size. Said in their words. */
-      this.error =
-        (error as { code?: string })?.code === 'PART_REFERENCED'
-          ? i18next.t('figure.text.part-is-referenced', { part: id })
-          : error instanceof Error
-            ? error.message
-            : String(error)
+      this.error = partRefusalOf(error, id, (key, params) => i18next.t(key, params)) ?? (error instanceof Error ? error.message : String(error))
     }
   }
   private toggleHiddenPart(id: string) {
@@ -654,12 +651,19 @@ export class FigureV3Editor extends LitElement {
   }
   /** One command, one step of the history. A refusal a person can meet here is said in their words. */
   private linkCommand(action: V3AuthoringAction) {
+    this.retry = undefined
     try {
       this.session!.command(action)
       this.error = ''
       this.changed()
     } catch (error) {
       const code = (error as { code?: string })?.code
+      const narrowing = narrowingRetryOf(action, error, (key, params) => i18next.t(key, params))
+      if (narrowing) {
+        this.error = narrowing.message
+        this.retry = { label: narrowing.label, action: narrowing.retry as V3AuthoringAction }
+        return
+      }
       this.error =
         code === 'DIMENSION_CYCLE'
           ? i18next.t('figure.text.follow-would-loop')
@@ -973,7 +977,14 @@ export class FigureV3Editor extends LitElement {
         <span slot="status" class="status" role="status" ?dirty=${status === 'figure.text.unsaved-changes'}>${i18next.t(status)}</span>
         <button slot="commit" save ?disabled=${unavailable || (!view.dirty && !!view.id)} @click=${this.save}>${i18next.t('figure.button.save')}</button>
       </ox-canvas-bar>
-      ${this.error || view.error ? html`<div role="alert" class="error">${this.error || view.error}</div>` : null}
+      ${this.error || view.error
+        ? html`<div role="alert" class="error">
+            ${this.error || view.error}
+            ${this.retry && this.error
+              ? html`<button act @click=${() => this.linkCommand(this.retry!.action)}><md-icon>straighten</md-icon>${this.retry.label}</button>`
+              : null}
+          </div>`
+        : null}
       <ox-three-pane>
         <figure-v3-parts
           slot="start"

package/client/modeller/v3-links.ts

@@ -1,4 +1,4 @@
-import { V3_FACES, v3ShapeFaces, proposeV3Occupancy, compileV3Graph, defaultInstanceSizeRange, foldInstanceSizeRange, v3AttachmentsOf, v3BindingsOf, v3InstanceSizeLimitsOf } from '@hatiolab/figure-model'
+import { V3_FACES, v3ShapeFaces, v3PartsExtentOf, compileV3Graph, defaultInstanceSizeRange, foldInstanceSizeRange, v3AttachmentsOf, v3BindingsOf, v3InstanceSizeLimitsOf } from '@hatiolab/figure-model'
 import type { V3SizeRange } from '@hatiolab/figure-model'
 import type { V3Asset, V3BindingPlace, V3Face, V3Joint } from '@hatiolab/figure-model'
 
@@ -23,8 +23,8 @@ const modelOf = (asset: V3Asset) =>
 export type Follow =
   | { of: 'own' }
   /** `times` 1 is the instance size itself; any other is a share of it -- V2's proportional rule. */
-  | { of: 'instance'; axis: Axis; times: number }
-  | { of: 'part'; part: string; axis: Axis }
+  | { of: 'instance'; axis: Axis; times: number; plus?: number }
+  | { of: 'part'; part: string; axis: Axis; times?: number; plus?: number }
   | { of: 'input'; input: string }
   /** Worked out some other way (the converter writes expressions) — shown, not offered as a choice. */
   | { of: 'expression' }
@@ -48,13 +48,29 @@ export function followOf(asset: V3Asset, part: string, axis: Axis): Follow {
   const constant = (ref: string) => m.constants.find(c => c.id === ref)
   /* The constant factors met on the way back: a share of the instance size is `size × share`. */
   let times = 1
+  /*
+    A link the author made is `source × times + plus` (link-dimension): its outermost sum with a number is the plus --
+    a leaf the opening's width less its gaps. Deeper sums, or a measure no link routes, read as worked out elsewhere.
+  */
+  let plus = 0
+  let at = start
+  const outer = node && writerOf(start)
+  if (outer?.op === 'add@1') {
+    const numbers = outer.args.filter(arg => constant(arg))
+    const onward = outer.args.filter(arg => !constant(arg))
+    if (numbers.length === 1 && onward.length === 1) {
+      plus = constant(numbers[0]!)!.value
+      at = onward[0]!
+    }
+  }
+  const withPlus = <T extends object>(f: T) => (plus ? { ...f, plus } : f)
   const walk = (ref: string): Follow => {
     if (seen.has(ref)) return { of: 'expression' }
     seen.add(ref)
     const instance = /^size\.([xyz])$/.exec(ref)
-    if (instance) return { of: 'instance', axis: instance[1] as Axis, times: Math.round(times * 1e6) / 1e6 }
+    if (instance) return withPlus({ of: 'instance' as const, axis: instance[1] as Axis, times: Math.round(times * 1e6) / 1e6 })
     const other = /^(.+)\.dimension\.([xyz])\.value$/.exec(ref)
-    if (other) return { of: 'part', part: other[1]!, axis: other[2] as Axis }
+    if (other) return withPlus({ of: 'part' as const, part: other[1]!, axis: other[2] as Axis, ...(times !== 1 ? { times: Math.round(times * 1e6) / 1e6 } : {}) })
     const input = m.inputs.find(i => i.id === ref)
     if (input) return ref.startsWith(`${part}.`) ? { of: 'own' } : { of: 'input', input: ref }
     const writer = writerOf(ref)
@@ -72,7 +88,7 @@ export function followOf(asset: V3Asset, part: string, axis: Axis): Follow {
     else if (factors.some(v => v !== 0) || !['mul@1', 'div@1', 'add@1', 'sub@1'].includes(writer.op)) return { of: 'expression' }
     return walk(onward[0]!)
   }
-  return walk(start)
+  return walk(at)
 }
 
 /** Whether the asset declares an instance size on an axis — only then can a dimension follow it. */
@@ -154,7 +170,8 @@ export function rowAxesOf(asset: V3Asset, part: string): Axis[] {
 export const rowOf = (asset: V3Asset, part: string) => asset.joints?.find(o => o.body1.part === part)?.repeat
 
 /** Where a part sits across the face it is fastened to, on one axis: centred, level with an edge, or a distance off centre. */
-export type Alignment = 'centre' | 'min' | 'max' | 'mm'
+/** `share`: the distance as a share of the figure's size on that axis, so it keeps its place when the figure is resized. */
+export type Alignment = 'centre' | 'min' | 'max' | 'mm' | 'share'
 
 /**
  * The axes across the face a part is fastened to — the two a fastening does not set by itself. Edges to line up with
@@ -180,10 +197,13 @@ export function alignOf(
   mm: Partial<Record<Axis, number>>,
   twisted = false
 ) {
-  const align: Partial<Record<Axis, 'min' | 'max' | { mm: number }>> = {}
+  const align: Partial<Record<Axis, 'min' | 'max' | { mm: number | { from: { of: 'instance'; axis: Axis }; times: number } }>> = {}
   for (const { axis, edges } of alignAxesOf(asset, part, target, twisted)) {
     const one = how[axis] ?? 'centre'
-    if (one === 'mm' && mm[axis]) align[axis] = { mm: mm[axis]! }
+    const size = asset.designInputs[`size.${axis}`]
+    if (one === 'share' && mm[axis] && hasInstanceSize(asset, axis) && size)
+      align[axis] = { mm: { from: { of: 'instance', axis }, times: Math.round((mm[axis]! / size) * 1e6) / 1e6 } }
+    else if (one === 'mm' && mm[axis]) align[axis] = { mm: mm[axis]! }
     else if ((one === 'min' || one === 'max') && edges) align[axis] = one
   }
   return Object.keys(align).length ? align : undefined
@@ -220,6 +240,8 @@ export interface Motion {
   control?: { id: string; unit?: string; min?: number; max?: number }
   /** A joint that moves with another (URDF's mimic): the leader's value times `multiplier`, plus `offset`. */
   follows?: { joint: string; multiplier: number; offset?: number }
+  /** A slide whose distance is a part's length (plus a difference): the control is its share. */
+  travel?: { part: string; axis: string; plus?: number }
 }
 
 export function motionOf(asset: V3Asset, part: string): Motion | undefined {
@@ -246,7 +268,8 @@ export function motionOf(asset: V3Asset, part: string): Motion | undefined {
     }
     return undefined
   }
-  return { kind, axis, control: control(quantity), ...(record?.mimic ? { follows: record.mimic } : {}) }
+  const travel = record?.travel?.source && 'part' in record.travel.source ? { part: record.travel.source.part, axis: record.travel.source.axis, ...(record.travel.plus ? { plus: record.travel.plus } : {}) } : undefined
+  return { kind, axis, control: control(quantity), ...(record?.mimic ? { follows: record.mimic } : {}), ...(travel ? { travel } : {}) }
 }
 
 /** What the motion form holds: how the part moves, and either its own control or the joint it moves with. */
@@ -260,6 +283,12 @@ export interface MotionForm {
   follow: string
   multiplier: number
   offset: number
+  /**
+   * A slide whose distance follows a part's length (figure-model `travel`): `<part>:<axis>`, empty for a distance in
+   * millimetres. The control is then the share of that length, 0..1, and the stroke grows when the part does.
+   */
+  travel?: string
+  travelPlus?: number
 }
 
 /**
@@ -285,6 +314,10 @@ export function motionJoint(joint: V3Joint, m: MotionForm, part: string): V3Join
     axis: m.axis.toUpperCase() as 'X' | 'Y' | 'Z'
   }
   if (m.follow) return { ...moving, mimic: { joint: m.follow, multiplier: m.multiplier, ...(m.offset ? { offset: m.offset } : {}) } }
+  if (m.kind === 'slide' && m.travel) {
+    const [of, axis] = m.travel.split(':')
+    return { ...moving, travel: { source: { of: 'part', part: of!, axis: axis as Axis }, ...(m.travelPlus ? { plus: m.travelPlus } : {}) }, state: { id: m.id || `${part}-${m.kind}` } }
+  }
   return { ...moving, ...(m.kind === 'continuous' ? {} : { lowerLimit: m.min, upperLimit: m.max }), state: { id: m.id || `${part}-${m.kind}` } }
 }
 
@@ -366,8 +399,8 @@ export function instanceRangeOf(asset: V3Asset): { declared: V3SizeRange; measur
  */
 export function instanceRangeToDeclare(asset: V3Asset): { range: V3SizeRange; at: Record<Axis, number> } | undefined {
   if (instanceRangeOf(asset) || !asset.appearance.length) return undefined
-  const proposal = proposeV3Occupancy(asset, { over: 'rest' })
-  const at = Object.fromEntries(AXES.map(axis => [axis, Math.round((proposal.at[axis].max - proposal.at[axis].min) * 1e6) / 1e6])) as Record<Axis, number>
+  /* The parts as they rest -- not the room their joints swing them through, which declared a door 8208 mm every way. */
+  const at = v3PartsExtentOf(asset) as Record<Axis, number>
   if (AXES.some(axis => !(at[axis] > 0))) return undefined
   const start = defaultInstanceSizeRange(at)
   return { range: foldInstanceSizeRange(start, v3InstanceSizeLimitsOf(asset, start)).range, at }

package/client/modeller/v3-refusals.ts

@@ -19,3 +19,41 @@ export function sizeRangeRefusalOf(error: unknown, say: Say): string | null {
     part: part ?? ''
   })
 }
+
+/**
+ * A link refused because the size range it would leave cannot hold: measuring again cannot help (the link is not there
+ * to measure), so the author is offered the same link that narrows the range to what the figure then allows.
+ */
+export function narrowingRetryOf<A extends { kind: string }>(action: A, error: unknown, say: Say): { message: string; label: string; retry: A & { narrowRange: true } } | null {
+  if (action.kind !== 'link-dimension' || (error as { code?: string })?.code !== 'INSTANCE_SIZE_RANGE') return null
+  const message = error instanceof Error ? error.message : String(error)
+  const found = /size\.([xyz]):\s*(below|above) ([\d.]+) mm [^(;]*(?:\(([^)]+)\))?;/.exec(message)
+  if (!found) return null
+  const [, axis, side, raw, part] = found
+  const mm = Number(raw).toLocaleString(undefined, { maximumFractionDigits: 1 })
+  const words = { axis: axis!.toUpperCase(), mm, part: part ?? '' }
+  return {
+    message: say(side === 'below' ? 'figure.text.link-needs-smaller-range' : 'figure.text.link-needs-larger-range', words),
+    label: say(side === 'below' ? 'figure.button.narrow-range-from' : 'figure.button.narrow-range-to', words),
+    retry: { ...action, narrowRange: true }
+  }
+}
+
+/**
+ * Why a part cannot be deleted, in the author's words -- figure-model names four reasons (PART_REFERENCED): parts hang
+ * from it, the declared space holds it, another part follows its size or place, or a joint moves with its joint. One
+ * sentence for all of them told the author to undo a link that was not there (the architect's workbench, 2026-09-25).
+ */
+export function partRefusalOf(error: unknown, part: string, say: Say): string | null {
+  if ((error as { code?: string })?.code !== 'PART_REFERENCED') return null
+  /* figure-model's sentence after its code and path: 「PART_REFERENCED: top: top holds leg-2, lamp; …」. */
+  const message = (error instanceof Error ? error.message : String(error)).replace(/^[A-Z_]+: [^:]+: /, '')
+  const holds = / holds (.+?); take (?:them|it) off first/.exec(message)
+  if (holds) return say('figure.text.part-holds-others', { part, others: holds[1]! })
+  if (/is in the space the figure declares/.test(message)) return say('figure.text.part-in-declared-space', { part })
+  const moves = /^(.+?) (?:moves|move) with /.exec(message)
+  if (moves) return say('figure.text.part-is-led', { part, others: moves[1]! })
+  const follows = /^(.+?) (?:follows|follow) .+'s size or place/.exec(message)
+  if (follows) return say('figure.text.part-is-followed', { part, others: follows[1]! })
+  return say('figure.text.part-is-referenced', { part })
+}

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

@@ -17,6 +17,12 @@ import type { V3BudgetLine } from '../modeller/v3-maturity.js'
 import { OxPrompt } from '@operato/popup'
 import { openPopup } from '@operato/layout'
 import '../modeller/figure-v3-first-save.js'
+import { activePalette } from '@hatiolab/things-scene'
+import {
+  clearAssistantSurface,
+  notifyAssistantSurface,
+  provideAssistantSurface
+} from '@things-factory/ai-assistant/dist-client/index.js'
 import type { FirstSave } from '../modeller/v3-first-save.js'
 
 /**
@@ -119,20 +125,45 @@ export class FigureV3ModellerPage extends PageView {
   }
   private wasDirty = false
   private titled?: string | null
-  private announce = () => {
+  /** The figure the AI dock was last told about - another id is another conversation. */
+  private assistantFor?: string
+  /*
+    The figure on screen is what the AI dock talks about (design/ai/shared-dock.md §3). A figure not saved yet has no
+    row to hang a conversation on, so it provides nothing and the dock stays on the application's conversation.
+    The draft is read at the moment of sending, never cached - the dock must not answer about a shape already changed.
+  */
+  private provideAssistant = () => {
     const view = this.session.read()
-    if (!this.active || view.loading || view.saving || view.error || !view.context) return
-    window.dispatchEvent(
-      new CustomEvent('figure-ai-context', {
-        detail: {
-          figureId: view.id,
-          source: JSON.parse(this.session.source()),
-          context: view.context,
-          revision: view.revision,
-          format: 'v3'
-        }
+    if (!this.active || view.loading || view.error || !view.context) return
+    if (!view.id) {
+      this.withdrawAssistant()
+      return
+    }
+    if (this.assistantFor === view.id) {
+      notifyAssistantSurface(this)
+      return
+    }
+    const id = view.id
+    this.assistantFor = id
+    provideAssistantSurface(this, {
+      key: `figure:${id}`,
+      subject: 'figure',
+      icon: 'category',
+      label: () => this.session.read().name || id,
+      detail: () => (this.session.read().dirty ? i18next.t('figure.text.unsaved-changes') : ''),
+      anchor: () => ({ anchorType: 'figure', anchorId: id }),
+      hostContext: () => ({
+        surface: 'figure-modeller',
+        editorMode: 'existing',
+        figureId: id,
+        draftSource: JSON.parse(this.session.source()),
+        palette: Object.keys(activePalette())
       })
-    )
+    })
+  }
+  private withdrawAssistant() {
+    this.assistantFor = undefined
+    clearAssistantSurface(this)
   }
   private changed = () => {
     this.revision++
@@ -144,7 +175,7 @@ export class FigureV3ModellerPage extends PageView {
       this.titled = view.name
       this.updateContext()
     }
-    if (!view.saving) this.announce()
+    if (!view.saving) this.provideAssistant()
     /*
       A new figure's first save gives it an id: the address becomes the figure's own, in place of the history entry.
       Left at the bare modeller address, opening the modeller again from the menu was taken for the same page and kept
@@ -279,11 +310,10 @@ export class FigureV3ModellerPage extends PageView {
   }
   connectedCallback() {
     super.connectedCallback()
-    window.addEventListener('figure-ai-context-request', this.announce)
     window.addEventListener('figure-v3-apply', this.applyAI)
   }
   disconnectedCallback() {
-    window.removeEventListener('figure-ai-context-request', this.announce)
+    this.withdrawAssistant()
     window.removeEventListener('figure-v3-apply', this.applyAI)
     super.disconnectedCallback()
   }
@@ -307,7 +337,7 @@ export class FigureV3ModellerPage extends PageView {
   async pageUpdated(changes: Record<string, unknown>, lifecycle: { resourceId?: string }) {
     if (!this.active) {
       if (this.session.read().loading) this.session.close()
-      window.dispatchEvent(new CustomEvent('figure-ai-context', { detail: undefined }))
+      this.withdrawAssistant()
       return
     }
     const id = lifecycle?.resourceId
@@ -317,6 +347,9 @@ export class FigureV3ModellerPage extends PageView {
       this.discardApproved = false
       if (id) {
         this.draft = undefined
+        /* The row is read after the figure opens; until then the last figure's type must not stand in the field (C2). */
+        this.row = { version: 0 }
+        this.typeError = ''
         const opening = this.session.open(id, { discard })
         this.changed()
         await opening

package/dist-client/figure-assistant.d.ts

@@ -0,0 +1 @@
+export declare const FIGURE_CANDIDATE_TOOL = "proposeFigureCandidate";

package/dist-client/figure-assistant.js

@@ -0,0 +1,19 @@
+/*
+ * What the AI dock does with a figure candidate - figure-ui declares it because figure-service declares the tool
+ * (`proposeFigureCandidate`, design/ai/shared-dock.md §4).
+ *
+ * Today a candidate cannot be taken anywhere. The proposer writes V2 figures and the modeller opens V3 only; the V2
+ * modeller that reviewed candidates was removed with its listeners (`figure-ai-review`, `figure-ai-stage`), and the
+ * server already refuses to propose for a V3 figure (`V3_PROPOSAL_UNAVAILABLE`). So the outcome is `unavailable`,
+ * said to the person in words, not a silent pass - until a proposer writes V3 changes, which the modeller takes
+ * through `figure-v3-apply`.
+ */
+import { i18next } from '@operato/i18n';
+import { registerProposalHandler } from '@things-factory/ai-assistant/dist-client/index.js';
+export const FIGURE_CANDIDATE_TOOL = 'proposeFigureCandidate';
+registerProposalHandler(FIGURE_CANDIDATE_TOOL, async (_proposal, context) => {
+    const note = i18next.t('figure.text.candidate-cannot-open');
+    context.notify('info', note);
+    return { verdict: 'unavailable', errorCode: 'v3-review-missing', note };
+});
+//# sourceMappingURL=figure-assistant.js.map

package/dist-client/figure-assistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figure-assistant.js","sourceRoot":"","sources":["../client/figure-assistant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mDAAmD,CAAA;AAE3F,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAA;AAE7D,uBAAuB,CAAC,qBAAqB,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE;IAC1E,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAA;IAC3D,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC5B,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAA;AACzE,CAAC,CAAC,CAAA","sourcesContent":["/*\n * What the AI dock does with a figure candidate - figure-ui declares it because figure-service declares the tool\n * (`proposeFigureCandidate`, design/ai/shared-dock.md §4).\n *\n * Today a candidate cannot be taken anywhere. The proposer writes V2 figures and the modeller opens V3 only; the V2\n * modeller that reviewed candidates was removed with its listeners (`figure-ai-review`, `figure-ai-stage`), and the\n * server already refuses to propose for a V3 figure (`V3_PROPOSAL_UNAVAILABLE`). So the outcome is `unavailable`,\n * said to the person in words, not a silent pass - until a proposer writes V3 changes, which the modeller takes\n * through `figure-v3-apply`.\n */\nimport { i18next } from '@operato/i18n'\nimport { registerProposalHandler } from '@things-factory/ai-assistant/dist-client/index.js'\n\nexport const FIGURE_CANDIDATE_TOOL = 'proposeFigureCandidate'\n\nregisterProposalHandler(FIGURE_CANDIDATE_TOOL, async (_proposal, context) => {\n  const note = i18next.t('figure.text.candidate-cannot-open')\n  context.notify('info', note)\n  return { verdict: 'unavailable', errorCode: 'v3-review-missing', note }\n})\n"]}

package/dist-client/index.d.ts

@@ -1,2 +1,3 @@
 export * from './types.js';
 export * from './graphql/index.js';
+export * from './figure-assistant.js';

package/dist-client/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './graphql/index.js';
+export * from './figure-assistant.js';
 //# sourceMappingURL=index.js.map

package/dist-client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../client/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA","sourcesContent":["export * from './types.js'\nexport * from './graphql/index.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../client/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA","sourcesContent":["export * from './types.js'\nexport * from './graphql/index.js'\nexport * from './figure-assistant.js'\n"]}

package/dist-client/modeller/figure-v3-capability.d.ts

@@ -15,7 +15,7 @@ export declare class FigureV3Capability extends FigureV3Capability_base {
     /** The selected part, whose places are marked. */
     selected: string;
     locked: boolean;
-    render(): typeof nothing | import("lit-html").TemplateResult<1>;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
     private setRung;
     private pick;
 }

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

@@ -18,7 +18,7 @@ export declare class FigureV3Clips extends FigureV3Clips_base {
     /** Where each clip is scrubbed to, in seconds. */
     private at;
     private adding;
-    render(): typeof nothing | import("lit-html").TemplateResult<1>;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
     private renderClip;
     private renderTrack;
     private renderAdd;

package/dist-client/modeller/figure-v3-controls.d.ts

@@ -22,7 +22,7 @@ export declare class FigureV3Controls extends FigureV3Controls_base {
     private open;
     /** Values in hand while a slider is dragged: the dial and the number follow them before the release commits. */
     private live;
-    render(): typeof nothing | import("lit-html").TemplateResult<1>;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
     private renderControl;
     private renderDial;
     private renderSettings;

package/dist-client/modeller/figure-v3-links.d.ts

@@ -38,6 +38,8 @@ export declare class FigureV3Links extends FigureV3Links_base {
     /** The figure holds things: `Capacity` and `Holdable`, the ladder's middle rung. One part edit, one undo step. */
     private declareHolding;
     private renderDimensions;
+    /** The same source, the same share, a new difference: a leaf the opening less its gaps (link-dimension's `plus`). */
+    private followPlus;
     private follow;
     /**
      * Positions worked out from other values — V2's anchor rules, as the converter wrote them — each with the way to