@things-factory/figure-ui 10.1.51 → 10.1.53

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,10 +28,10 @@ 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, sizeRangeRefusalOf } from './v3-refusals.js'
 import type { V3RenderPart } from './v3-renderer.js'
 import type { V3BudgetLine } from './v3-maturity.js'
-import { instanceRangeOf, rangeDiffers, turnsAboutAJoint } from './v3-links.js'
+import { instanceRangeOf, instanceRangeToDeclare, rangeDiffers, turnsAboutAJoint } from './v3-links.js'
 import { jointFanOf } from './v3-joint-fan.js'
 import { jointDragOf } from './v3-joint-drag.js'
 import type { FirstSave } from './v3-first-save.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
@@ -654,12 +656,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')
@@ -721,7 +730,7 @@ export class FigureV3Editor extends LitElement {
     label.addEventListener('pointercancel', up)
   }
   /** The measured range, kept for the revision it was measured at: measuring evaluates the figure at its edges. */
-  private range?: { at: string; of: ReturnType<typeof instanceRangeOf> }
+  private range?: { at: string; of: ReturnType<typeof instanceRangeOf>; toDeclare?: ReturnType<typeof instanceRangeToDeclare> }
   /** The sizes a board may give the figure, and the way to measure them again after its parts changed. */
   private renderInstanceRange(asset: V3Asset | undefined, unavailable: boolean) {
     if (!asset) return nothing
@@ -729,14 +738,30 @@ export class FigureV3Editor extends LitElement {
     const at = `${this.session?.read().context ?? ''}:${this.revision}`
     if (this.range?.at !== at) {
       let of: ReturnType<typeof instanceRangeOf>
+      let toDeclare: ReturnType<typeof instanceRangeToDeclare>
       try {
         of = instanceRangeOf(asset)
       } catch {
         of = undefined
       }
-      this.range = { at, of }
+      try {
+        toDeclare = of ? undefined : instanceRangeToDeclare(asset)
+      } catch {
+        toDeclare = undefined
+      }
+      this.range = { at, of, toDeclare }
     }
     const range = this.range.of
+    /* No size yet: the figure is declared its size from its parts, so a board can resize it and parts can follow it. */
+    const toDeclare = this.range.toDeclare
+    if (!range && toDeclare)
+      return html`<section>
+        <h3>${i18next.t('figure.label.instance-range')}</h3>
+        <p hint>${i18next.t('figure.text.instance-size-undeclared')}</p>
+        <button act ?disabled=${unavailable} @click=${() => this.linkCommand({ kind: 'declare-instance-size', range: toDeclare.range, at: toDeclare.at })}>
+          <md-icon>straighten</md-icon>${i18next.t('figure.button.declare-instance-size')}
+        </button>
+      </section>`
     if (!range) return nothing
     const mm = (v: number) => Math.round(v).toLocaleString()
     const differs = rangeDiffers(range.declared, range.measured)
@@ -957,7 +982,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, compileV3Graph, defaultInstanceSizeRange, foldInstanceSizeRange, v3AttachmentsOf, v3BindingsOf, v3InstanceSizeLimitsOf } from '@hatiolab/figure-model'
+import { V3_FACES, v3ShapeFaces, proposeV3Occupancy, 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}` } }
 }
 
@@ -358,6 +391,21 @@ export function instanceRangeOf(asset: V3Asset): { declared: V3SizeRange; measur
   return { declared, measured }
 }
 
+/**
+ * The size range to declare for a figure that has none yet: its parts' extent now as the size it is authored at, and
+ * as wide as its parts allow around it (the same measure 「다시 재기」 uses). Undefined when the figure already has a
+ * size or has nothing to measure. Without a declared size a board cannot resize the figure, and no part is offered
+ * to follow its size -- every figure made in the modeller was left there (user, 2026-09-25).
+ */
+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>
+  if (AXES.some(axis => !(at[axis] > 0))) return undefined
+  const start = defaultInstanceSizeRange(at)
+  return { range: foldInstanceSizeRange(start, v3InstanceSizeLimitsOf(asset, start)).range, at }
+}
+
 /** Whether measuring again would change the declared range (to a micrometre). */
 export function rangeDiffers(a: V3SizeRange, b: V3SizeRange): boolean {
   return AXES.some(axis => Math.abs(a[axis].min - b[axis].min) > 1e-3 || Math.abs(a[axis].max - b[axis].max) > 1e-3)

package/client/modeller/v3-refusals.ts

@@ -19,3 +19,22 @@ 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 }
+  }
+}

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

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

@@ -32,12 +32,14 @@ export declare class FigureV3Links extends FigureV3Links_base {
     private place;
     private row;
     willUpdate(changed: Map<string, unknown>): void;
-    render(): typeof nothing | import("lit-html").TemplateResult<1>;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
     /** Where things are held on this part: a seat things rest on, or a grip things are held in (parity row ⑤). */
     private renderPlaces;
     /** 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