@things-factory/figure-ui 10.1.81 → 10.1.83

package/test/clip-ai-proposal.test.ts

@@ -0,0 +1,104 @@
+/*
+ * Designer 2026-09-27: an AI proposal that would stop a clip is refused whole -- nothing written, nothing saved -- and
+ * the AI can never agree to it for the person. A proposal that stops none keeps every clip.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { addFigureBox, applyFigureAuthoring, createFigureAsset, editFigurePart, parseFigureAsset, serializeFigureAsset, type FigureAsset } from '@hatiolab/figure-model'
+
+import { createFigureProductSession } from '../client/modeller/product-session.js'
+import { runFigureProposal, takeFigureOffer, type FigureApplyDetail } from '../client/modeller/ai-proposal.js'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+const ko = JSON.parse(read('../translations/ko.json'))
+const say = (key: string, params: Record<string, string> = {}) => ko[key].replace(/\{(\w+)\}/g, (_: string, k: string) => params[k] ?? '')
+
+function door(): string {
+  let a = createFigureAsset('Door')
+  a = addFigureBox(a, { id: 'frame', size: { x: 1000, y: 100, z: 200 }, position: { x: 0, y: 50, z: 0 } })
+  a = addFigureBox(a, { id: 'leaf', size: { x: 900, y: 1800, z: 40 }, position: { x: 0, y: 1000, z: 0 } })
+  a = addFigureBox(a, { id: 'sign', size: { x: 200, y: 100, z: 10 }, position: { x: 0, y: 2200, z: 200 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'leaf', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  const j = a.joints!.find(k => k.body1.part === 'leaf')!
+  a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { ...j, type: 'revolute', axis: 'Y', state: { id: 'open' } } })
+  a = editFigurePart(a, { kind: 'set-driver', state: 'open', clip: 'swing', duration: 2, keys: [{ seconds: 0, value: 0 }, { seconds: 2, value: 80 }] })
+  return serializeFigureAsset(a)
+}
+const saved: string[] = []
+const store = { load: async (id: string) => ({ id, source: door() }), save: async (q: { id?: string; source: string }) => (saved.push(q.source), { id: q.id ?? 'x', source: q.source }) }
+
+/** The modeller page's own handler (figure-modeller-page.ts calls it): no copy of it here. */
+const pageOf = (s: ReturnType<typeof createFigureProductSession>) => ({
+  offer: (detail: FigureApplyDetail) => (takeFigureOffer(s, detail, { onSavedFigure: false, say }), detail),
+  openNew: async () => ({ applied: false, code: 'not-opened' })
+})
+const clipsOf = (s: ReturnType<typeof createFigureProductSession>) => (parseFigureAsset(s.source()) as FigureAsset).drivers?.map(d => d.clip) ?? []
+
+test('a proposal that would stop a clip is refused whole: nothing written, nothing saved, the clip named', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('door')
+  const { context, revision } = s.read()
+  const before = s.source()
+  const steps = [{ kind: 'rename', name: 'Renamed by AI' }, { kind: 'remove-part', target: 'leaf' }] as never[]
+  const out = await runFigureProposal({ steps, context: context!, revision: revision! }, pageOf(s), say)
+  assert.equal(out.verdict, 'refused')
+  assert.equal(out.errorCode, 'CLIPS_DROPPED')
+  assert.match(out.note!, /swing/)
+  assert.equal(s.source(), before, 'not even the rename before it: refused whole')
+  assert.equal(s.read().revision, revision)
+  assert.equal(s.read().dirty, false, 'nothing to save')
+  assert.equal(saved.length, 0, 'and nothing saved')
+  assert.deepEqual(clipsOf(s), ['swing'])
+})
+
+test('a proposal that stops no clip keeps every clip', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('door')
+  const { context, revision } = s.read()
+  const steps = [{ kind: 'rename', name: 'Door by AI' }, { kind: 'nudge-part', part: 'sign', by: { x: 50 } }, { kind: 'rename-part', target: 'frame', name: 'jamb' }] as never[]
+  const out = await runFigureProposal({ steps, context: context!, revision: revision! }, pageOf(s), say)
+  assert.equal(out.verdict, 'accepted')
+  assert.deepEqual((parseFigureAsset(s.source()) as FigureAsset).drivers, (parseFigureAsset(door()) as FigureAsset).drivers)
+})
+
+test('the AI never agrees for the person: no consent on any proposal path, and none carried in a step', async () => {
+  for (const file of ['../client/modeller/ai-proposal.ts', '../client/pages/figure-modeller-page.ts'])
+    assert.ok(!/withConsent|dropClips/.test(read(file)), `${file} gives no consent`)
+  /* Consent written into the steps or beside them by the model is not consent: the proposal is still refused. */
+  const s = createFigureProductSession(store)
+  await s.open('door')
+  const { context, revision } = s.read()
+  const steps = [{ kind: 'remove-part', target: 'leaf', dropClips: ['swing/open'] }] as never[]
+  const card = { steps, context: context!, revision: revision!, dropClips: ['swing/open'] } as never
+  const out = await runFigureProposal(card, pageOf(s), say)
+  assert.equal(out.verdict, 'refused')
+  assert.equal(out.errorCode, 'CLIPS_DROPPED', 'refused for the clip it would stop: the consent it carries is read as nothing')
+  assert.deepEqual(clipsOf(s), ['swing'])
+  const page = read('../client/pages/figure-modeller-page.ts')
+  assert.ok(page.includes('if (takeFigureOffer(this.session, detail, {'), 'the page takes an offer by the handler tested here')
+})
+
+/* Designer 2026-09-27: not calling it is not forbidding it -- an AI proposal made inside a person's consent, still refused. */
+test('an AI proposal made while a person\'s consent is held is refused; clips, figure and version stay', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('door')
+  const { context, revision } = s.read()
+  const before = s.source()
+  const steps = [{ kind: 'remove-part', target: 'leaf' }] as never[]
+  assert.throws(
+    () => s.withConsent({ dropClips: ['swing/open'], context: context!, revision: revision! }, () => s.applyProposal(steps, revision!, context!)),
+    (e: { code?: string }) => e.code === 'CLIPS_DROPPED'
+  )
+  /* And through the page's handler, with the consent held around it. */
+  const detail = { steps, create: false, context: context!, revision: revision! } as FigureApplyDetail
+  s.withConsent({ dropClips: ['swing/open'], context: context!, revision: revision! }, () => takeFigureOffer(s, detail, { onSavedFigure: false, say }))
+  assert.equal(detail.applied, false)
+  assert.equal(detail.code, 'CLIPS_DROPPED')
+  assert.equal(s.source(), before)
+  assert.equal(s.read().revision, revision)
+  assert.equal(s.read().dirty, false)
+  assert.deepEqual(clipsOf(s), ['swing'])
+  assert.ok(!/origin: 'ai'[^\n]*consented\(\)/.test(read('../client/modeller/product-session.ts')), 'the AI path passes no consent')
+})

package/test/clip-consent.test.ts

@@ -0,0 +1,88 @@
+/*
+ * Designer 2026-09-27: an edit that would stop a clip is told to the person before anything is written, with the clips
+ * named; agreed, it lets exactly those go in one step, and undo brings them back. Consent never outlives the edit it was
+ * given for.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { addFigureBox, applyFigureAuthoring, createFigureAsset, editFigurePart, parseFigureAsset, serializeFigureAsset, type FigureAsset } from '@hatiolab/figure-model'
+
+import { createFigureProductSession } from '../client/modeller/product-session.js'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+/** Two doors on a frame, each swinging on a clip of its own. */
+function doors(): string {
+  let a = createFigureAsset('Doors')
+  a = addFigureBox(a, { id: 'frame', size: { x: 2000, y: 100, z: 200 }, position: { x: 0, y: 50, z: 0 } })
+  for (const [id, x] of [['left', -500], ['right', 500]] as const) {
+    a = addFigureBox(a, { id, size: { x: 900, y: 1800, z: 40 }, position: { x, y: 1000, z: 0 } })
+    a = applyFigureAuthoring(a, { kind: 'attach', part: id, face: 'bottom', to: { part: 'frame', face: 'top' } })
+    const j = a.joints!.find(k => k.body1.part === id)!
+    a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { ...j, type: 'revolute', axis: 'Y', state: { id: `${id}-open` } } })
+    a = editFigurePart(a, { kind: 'set-driver', state: `${id}-open`, clip: `${id}-swing`, duration: 2, keys: [{ seconds: 0, value: 0 }, { seconds: 2, value: 80 }] })
+  }
+  return serializeFigureAsset(a)
+}
+const store = { load: async (id: string) => ({ id, source: doors() }), save: async (q: { id?: string; source: string }) => ({ id: q.id ?? 'x', source: q.source }) }
+const clipsOf = (s: ReturnType<typeof createFigureProductSession>) => (parseFigureAsset(s.source()) as FigureAsset).drivers?.map(d => d.clip) ?? []
+const fixed = (s: ReturnType<typeof createFigureProductSession>, part: string) => {
+  const j = (parseFigureAsset(s.source()) as FigureAsset).joints!.find(k => k.body1.part === part)!
+  return { kind: 'set-joint', joint: { id: j.id, type: 'fixed', body0: j.body0, body1: j.body1, origin: j.origin } } as never
+}
+
+test('refused and named first; agreed, exactly those go in one step; undo brings them back; consent does not outlive it', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('doors')
+  const revision = s.read().revision
+  assert.throws(() => s.command(fixed(s, 'left')), (e: { code?: string; clips?: Array<{ id: string; clip: string; why: string }> }) =>
+    e.code === 'CLIPS_DROPPED' && e.clips?.map(c => `${c.clip} ${c.why}`).join() === 'left-swing gone')
+  assert.equal(s.read().revision, revision, 'nothing written')
+  assert.deepEqual(clipsOf(s), ['left-swing', 'right-swing'])
+  const ids = ['left-swing/left-open']
+  const at = () => ({ context: s.read().context!, revision: s.read().revision! })
+  s.withConsent({ dropClips: ids, ...at() }, () => s.command(fixed(s, 'left')))
+  assert.deepEqual(clipsOf(s), ['right-swing'], 'only the one agreed to')
+  s.undo()
+  assert.deepEqual(clipsOf(s), ['left-swing', 'right-swing'], 'one undo, and the clip is back')
+  /* The same edit again, not agreed to this time: asked again -- the consent ended with the edit it was given for. */
+  assert.throws(() => s.command(fixed(s, 'left')), (e: { code?: string }) => e.code === 'CLIPS_DROPPED', 'consent ended with its edit')
+  /* A part taken away with its clip is asked about the same way. */
+  assert.throws(() => s.edit({ kind: 'remove-part', target: 'right' }), (e: { code?: string }) => e.code === 'CLIPS_DROPPED')
+  assert.deepEqual(clipsOf(s), ['left-swing', 'right-swing'])
+})
+
+/* Designer 2026-09-27: a consent is for the edit it was asked about, on the figure and version it was asked on. */
+test('a consent is used by one edit only, on the version and figure it was given for', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('doors')
+  const ids = ['left-swing/left-open']
+  const asked = { context: s.read().context!, revision: s.read().revision! }
+  /* An edit in between: the version it was given on is gone. Refused; nothing written. */
+  s.command({ kind: 'rename', name: 'Doors 2' } as never)
+  const revision = s.read().revision
+  assert.throws(() => s.withConsent({ dropClips: ids, ...asked }, () => s.command(fixed(s, 'left'))), (e: { code?: string }) => e.code === 'CONSENT_STALE')
+  assert.equal(s.read().revision, revision)
+  assert.deepEqual(clipsOf(s), ['left-swing', 'right-swing'])
+  /* Another figure's consent. */
+  assert.throws(() => s.withConsent({ dropClips: ids, context: 'another', revision: s.read().revision! }, () => s.command(fixed(s, 'left'))), (e: { code?: string }) => e.code === 'CONSENT_STALE')
+  /* Taken by the first edit made under it: a second edit, the one that would stop the clip, is asked about again. */
+  const now = { context: s.read().context!, revision: s.read().revision! }
+  assert.throws(() => s.withConsent({ dropClips: ids, ...now }, () => (s.command({ kind: 'rename', name: 'Doors 3' } as never), s.command(fixed(s, 'left')))), (e: { code?: string }) => e.code === 'CLIPS_DROPPED')
+  assert.deepEqual(clipsOf(s), ['left-swing', 'right-swing'])
+})
+
+test('the modeller asks on every path an edit can stop a clip, in every language', () => {
+  const editor = read('../client/modeller/editor.ts')
+  for (const path of ['() => this.run(action)', '() => this.linkCommand(action)', '() => this.removePart(id, refitRoom)'])
+    assert.ok(editor.includes(`if (this.askClipLoss(error, ${path})) return`), path)
+  assert.ok(editor.includes('if (!now || now.context !== asked.context || now.revision !== asked.revision) {'), 'what was asked about is checked after the answer')
+  assert.ok(editor.includes('asked.session.withConsent({ dropClips: clips.map(c => c.id), context: asked.context, revision: asked.revision }, again)'))
+  for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
+    const t = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of ['figure.text.clips-would-go', 'figure.text.clip-gone', 'figure.text.clip-changed', 'figure.button.let-clips-go', 'figure.text.clips-consent-stale']) assert.ok(t[key], `${lang} ${key}`)
+    assert.ok(t['figure.text.clips-would-go'].includes('{clips}') && t['figure.text.clip-gone'].includes('{clip}'), lang)
+  }
+})

package/test/command-preview.test.ts

@@ -0,0 +1,288 @@
+/*
+ * ADR-0097 §5.5 (designer 2026-09-27): a fastening is seen before it is done -- the bodies it moves where they would
+ * stand, the face they would meet, and in words how far and how each turns. It changes nothing: no revision, no history,
+ * no save, no clip. It is shown only for the figure, version and part it was worked out for.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { addFigureBox, applyFigureAuthoring, createFigureAsset, figurePartFaceOf, serializeFigureAsset } from '@hatiolab/figure-model'
+
+import { createFigureProductSession } from '../client/modeller/product-session.js'
+import { faceHighlightOf, ghostPartsOf, previewWordsOf, type HeldPreview } from '../client/modeller/command-preview.js'
+
+const read = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+const ko = JSON.parse(read('../translations/ko.json'))
+const say = (key: string, params: Record<string, string> = {}) => {
+  assert.ok(ko[key], `ko has no words for ${key}`)
+  return ko[key].replace(/\{(\w+)\}/g, (_: string, k: string) => params[k] ?? '')
+}
+
+function bench(): string {
+  let a = createFigureAsset('Bench')
+  a = addFigureBox(a, { id: 'leg', size: { x: 60, y: 700, z: 60 }, position: { x: -400, y: 350, z: 0 } })
+  a = addFigureBox(a, { id: 'top', size: { x: 1200, y: 40, z: 600 }, position: { x: 0, y: 900, z: 0 } })
+  a = addFigureBox(a, { id: 'lamp', size: { x: 80, y: 80, z: 80 }, position: { x: 200, y: 960, z: 100 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'lamp', face: 'bottom', to: { part: 'top', face: 'top' } })
+  return serializeFigureAsset(a)
+}
+const store = { load: async (id: string) => ({ id, source: bench() }), save: async (q: { id?: string; source: string }) => ({ id: q.id ?? 'x', source: q.source }) }
+const onLeg = { kind: 'attach', part: 'top', face: 'bottom', to: { part: 'leg', face: 'top' } } as never
+
+test('seen, not done: the session\'s preview writes nothing, and names the version it was worked out on', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('bench')
+  const before = s.source()
+  const seen = s.previewCommand(onLeg)
+  assert.equal(s.source(), before)
+  assert.equal(s.read().revision, seen.revision)
+  assert.equal(s.read().canUndo, false)
+  assert.equal(s.read().dirty, false)
+  /* Drawn: only what moves, translucent, never the part as it stands. */
+  const held: HeldPreview = { context: seen.context, revision: seen.revision, key: 'k', geometry: seen.geometry, moves: seen.moves }
+  const ghost = ghostPartsOf(held)
+  assert.deepEqual(ghost.map(g => g.id).sort(), ['__preview:lamp', '__preview:top'], 'the top and the lamp on it')
+  assert.ok(ghost.every(g => g.material.transparent && g.material.token === '__preview'))
+  /* Said: how far the part goes, and what goes with it. */
+  const words = previewWordsOf(held, 'top', say)
+  /* Attached with no alignment, it is centred on the leg too: said, not hidden. */
+  assert.deepEqual(words, ['도형 기준으로 X −400 · Y −180 mm 옮겨집니다.', '함께 움직이는 부품: lamp'])
+})
+
+test('a turn is said as one axis and one signed angle; a refusal clears the result and says why', () => {
+  const turned: HeldPreview = { context: 'c', revision: 0, key: 'k', moves: [{ body: 'box', part: 'box', translate: [0, 0, 0], turn: { axis: 'y', degrees: -30 } }] }
+  assert.deepEqual(previewWordsOf(turned, 'box', say), ['도형 기준 Y축 둘레로 −30° 돕니다.'])
+  const slanted: HeldPreview = { context: 'c', revision: 0, key: 'k', moves: [{ body: 'box', part: 'box', translate: [0, 0, 0], turn: { axis: [0.577, 0.577, 0.577], degrees: 120 } }] }
+  assert.match(previewWordsOf(slanted, 'box', say)[0]!, /기울어진 축\(0\.58, 0\.58, 0\.58\) 둘레로 \+120°/)
+  const refused: HeldPreview = { context: 'c', revision: 0, key: 'k', refused: '거꾸로 붙일 수 없습니다', geometry: [{}], moves: turned.moves }
+  assert.deepEqual(previewWordsOf(refused, 'box', say), ['이대로는 붙일 수 없습니다: 거꾸로 붙일 수 없습니다'])
+  const rows: HeldPreview = { context: 'c', revision: 0, key: 'k', moves: [{ body: 'frame', part: 'frame', translate: [0, 100, 0] }, ...[0, 1, 2].map(i => ({ body: `["roller.repeat",${i},"roller.placed"]`, part: 'roller', translate: [0, 100, 0] as [number, number, number] }))] }
+  assert.equal(previewWordsOf(rows, 'frame', say)[1], '함께 움직이는 부품: roller 3개')
+})
+
+test('the face it would meet is lit where attaching reads it, just off the face', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('bench')
+  const { parseFigureAsset } = await import('@hatiolab/figure-model')
+  const face = figurePartFaceOf(parseFigureAsset(s.source()), 'leg', 'top')!
+  const lit = faceHighlightOf(face)!
+  assert.equal(lit.id, '__target-face')
+  assert.deepEqual(lit.shape, { provider: 'box', dimensions: { width: 60, height: 2, depth: 60 } })
+  assert.deepEqual(lit.pose.t.map(v => Math.round(v)), [-400, 702, 0], 'the leg top is at 700; lifted 1 mm, half its thickness above')
+  assert.equal(faceHighlightOf(undefined), null)
+})
+
+test('the editor shows it only for the figure, version and part it was worked out for, and clears it when the form lets go', () => {
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes('if (!p || !view || p.context !== view.context || p.revision !== view.revision || p.part !== this.selected || this.middle !== \'edit\' || this.tab !== \'properties\') return undefined'))
+  assert.ok(editor.includes('this.preview = { ...held, refused: this.said(error) }'), 'refused: no earlier result stays')
+  assert.ok(editor.includes('.ghost=${this.previewShown().ghost}') && editor.includes('.highlight=${this.previewShown().highlight}'))
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes("this.dispatchEvent(new CustomEvent('preview-command', { detail: this.candidate ?? null, bubbles: true, composed: true }))"))
+  assert.ok(links.includes("if (this.told && this.told !== 'null') this.dispatchEvent(new CustomEvent('preview-command', { detail: null, bubbles: true, composed: true }))"), 'leaving the panel clears it')
+  assert.ok(links.includes("if (this.section !== 'shape' && !this.told) return"), 'the sections without the form do not clear it')
+  assert.ok(links.includes('<button act ?disabled=${this.locked || !action} @click=${() => action && this.command(action)}>'), 'the button applies the command the preview showed')
+})
+
+test('the details fold, and what they hold that is not the default stays said', () => {
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes('<details fasten-detail>'))
+  assert.ok(links.includes("detail.length ? detail.join(' · ') : i18next.t('figure.text.fasten-summary-default')"))
+  for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
+    const t = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of ['preview-refused', 'preview-stays', 'preview-moves', 'preview-turns-named', 'preview-turns-slanted', 'preview-carries', 'preview-copies', 'preview-clips', 'preview-face-unknown', 'target-would-loop', 'fasten-summary-default', 'fasten-summary-gap', 'fasten-summary-twist', 'fasten-summary-off-centre', 'fasten-summary-edge-min', 'fasten-summary-edge-max', 'fasten-summary-follows'])
+      assert.ok(t[`figure.text.${key}`], `${lang} ${key}`)
+    assert.ok(t['figure.label.fasten-detail'] && t['figure.label.facing'], lang)
+  }
+})
+
+/* ADR-0097 §5.5 (Q2): the list stays flat; a part says what it is fastened to, beside its name. */
+test('the part list names what each part is fastened to, without reordering or nesting it', () => {
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("'plane' in j.body0 ? i18next.t('figure.label.mounting-plane') : `${partLabelOf(j.body0.part)} · ${i18next.t(`figure.label.face-${j.body0.face}`)}`"))
+  assert.ok(editor.includes('...(fastened.has(id) ? { fastenedTo: fastened.get(id)! } : {})'))
+  const parts = read('../client/modeller/figure-parts.ts')
+  assert.ok(parts.includes('<small fastened-to title=${i18next.t(\'figure.label.fastened-to\')}>${part.fastenedTo}</small>'))
+})
+
+/* Detaching is seen before it is done: "it stays where it is" only when the copy shows it does. */
+test('detaching says what it would do: stays, what stays fastened to it, the clips it would stop', async () => {
+  const s = createFigureProductSession(store)
+  await s.open('bench')
+  const seen = s.previewCommand({ kind: 'detach', part: 'lamp' } as never)
+  assert.equal(seen.moves.length, 0, 'the lamp stays where it stands')
+  assert.equal(s.read().revision, 0)
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("const own = seen.moves.some(m => m.body === this.selected)"))
+  assert.ok(editor.includes(": [say('figure.text.detach-stays', { from })]"), 'said only when it stays')
+  assert.equal(say('figure.text.detach-stays', { from: 'top' }), '떼면 지금 자리에 그대로 남고, top과의 붙임만 없어집니다.')
+  const links = read('../client/modeller/figure-links.ts')
+  assert.equal(links.match(/\$\{this\.renderDetachWords\(\)\}/g)?.length, 2, 'beside both buttons that detach')
+  for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
+    const t = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of ['detach-stays', 'detach-moves', 'detach-keeps-children', 'detach-clips', 'detach-refused']) assert.ok(t[`figure.text.${key}`], `${lang} ${key}`)
+  }
+})
+
+/* A panel made with a part already chosen loads that part's fastening: "editing the fastening it has" over an empty target was wrong. */
+test('the fastening form opens on the part\'s own fastening however the panel came to be', () => {
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes('if (this.asset && this.partId && this.partId !== this.loadedFor) {'))
+  assert.ok(!links.includes("changed.get('partId') !== undefined"), 'not only when the part changes after the panel was made')
+})
+
+/* ADR-0097 §5.5: a row is said as what it makes, read as drawn; where it cannot be made, why. */
+test('a row is seen before it is made, read as figure-model draws it -- and said where it cannot be made', async () => {
+  const { rowWordsOf } = await import('../client/modeller/command-preview.js')
+  const { rowBlockOf } = await import('../client/modeller/links.js')
+  const { figureRowOf, previewFigureCommand } = await import('@hatiolab/figure-model')
+  let a = createFigureAsset('Conveyor')
+  a = addFigureBox(a, { id: 'frame', size: { x: 2000, y: 100, z: 600 }, position: { x: 0, y: 50, z: 0 } })
+  a = addFigureBox(a, { id: 'roller', size: { x: 60, y: 60, z: 560 }, position: { x: 0, y: 130, z: 0 } })
+  assert.equal(rowBlockOf(a, 'roller'), 'unfastened')
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'roller', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  assert.equal(rowBlockOf(a, 'roller'), undefined)
+  const seen = previewFigureCommand(a, { kind: 'make-repeat', part: 'roller', axis: 'x', pitch: 200 } as never)
+  const held: HeldPreview = { context: 'c', revision: 0, key: 'k', geometry: seen.geometry, moves: seen.moves, added: seen.added, row: figureRowOf(seen.asset, 'roller') }
+  assert.deepEqual(previewWordsOf(held, 'roller', say), ['roller 10개 · X 방향 · pitch 200 mm (중심 간격)', '가운데 정렬 · 양 끝에 70 mm씩 남음'])
+  assert.equal(ghostPartsOf(held).length, 10, 'the copies it would draw, translucent')
+  /* A set count is spread over the length: said as drawn, 970 apart, nothing left at the ends. */
+  const three = figureRowOf(applyFigureAuthoring(a, { kind: 'make-repeat', part: 'roller', axis: 'x', pitch: 1, count: 3 }), 'roller')
+  assert.deepEqual(rowWordsOf(three, say), ['roller 3개 · X 방향 · pitch 970 mm (중심 간격)', '가운데 정렬 · 양 끝에 0 mm씩 남음'])
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes("<p hint row-blocked>${i18next.t(`figure.text.row-blocked-${blocked ?? 'unfastened'}`, { part: this.partId })}</p>"), 'not hidden: why')
+  assert.ok(links.includes("this.candidate = this.working === 'row' && this.rowCandidate ? { action: this.rowCandidate } : this.fastenCandidate"), 'the form being worked on is the one seen')
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("const row = candidate.action.kind === 'make-repeat' ? figureRowOf(seen.asset, this.selected, this.currentInputs()) : undefined"))
+  assert.ok(editor.includes('<ul row-reading>${rowWordsOf(this.rowNow(asset)'), 'a row made says the same, as it stands')
+  for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
+    const t = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of ['row-count-pitch', 'row-count-uneven', 'row-ends-centred', 'row-ends', 'row-ends-unknown', 'row-companions', 'row-count-spreads', 'row-blocked-unfastened', 'row-blocked-on-plane', 'row-blocked-holds-parts'])
+      assert.ok(t[`figure.text.${key}`], `${lang} ${key}`)
+  }
+})
+
+/* Designer 2026-09-27: a pitch the board may set, typed into its field, is one edit -- undone once, whatever path it takes. */
+test('a published pitch typed into its field is one edit, undone once', async () => {
+  let a = createFigureAsset('Conveyor')
+  a = addFigureBox(a, { id: 'frame', size: { x: 2000, y: 100, z: 600 }, position: { x: 0, y: 50, z: 0 } })
+  a = addFigureBox(a, { id: 'roller', size: { x: 60, y: 60, z: 560 }, position: { x: 0, y: 130, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'roller', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  a = applyFigureAuthoring(a, { kind: 'make-repeat', part: 'roller', axis: 'x', pitch: 200 })
+  const source = serializeFigureAsset(a)
+  const s = createFigureProductSession({ load: async (id: string) => ({ id, source }), save: async (q: { id?: string; source: string }) => ({ id: q.id ?? 'x', source: q.source }) })
+  await s.open('conveyor')
+  /* Published as the modeller does it (editor.renderPublicPitch): one input, the row reading it, published. */
+  s.applyRecipe([
+    { kind: 'add-design-input', id: 'pitch', unit: 'mm', min: 100, max: 400, value: 200 },
+    { kind: 'set-repeat', part: 'roller', pitch: { from: { of: 'input', input: 'pitch' } } },
+    { kind: 'publish-input', input: 'pitch', label: 'pitch' }
+  ] as never)
+  const count = () => s.read().geometry.filter(g => g.id.includes('roller')).length
+  const before = { revision: s.read().revision, count: count() }
+  assert.equal(before.count, 10)
+  /* The field's one change, as setPitch sends it. */
+  s.apply([{ kind: 'set-design', input: 'pitch', unit: 'mm', value: 300 }])
+  assert.equal(count(), 7)
+  assert.equal(s.read().revision, before.revision! + 1, 'one step')
+  s.undo()
+  assert.equal(count(), 10, 'one undo, and it is back')
+  assert.equal(s.read().fields.find(f => f.id === 'pitch')?.value, 200)
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("this.run(() => this.session!.apply([{ kind: 'set-design', input: from, unit: 'mm', value: pitch }]))"), 'the field sends one change, on change -- not per key')
+})
+
+/* ADR-0097 §5.5: a motion is named by its parts, and where it takes the part is drawn at both ends of its range. */
+test('a motion is named by its parts, and drawn at both ends of its range -- only the ends', async () => {
+  const { motionEndsOf } = await import('../client/modeller/motion-ends.js')
+  let a = createFigureAsset('Doors')
+  a = addFigureBox(a, { id: 'frame', size: { x: 2000, y: 100, z: 200 }, position: { x: 0, y: 50, z: 0 } })
+  a = addFigureBox(a, { id: 'leaf', size: { x: 900, y: 1800, z: 40 }, position: { x: 0, y: 1000, z: 0 } })
+  a = addFigureBox(a, { id: 'gate', size: { x: 400, y: 400, z: 40 }, position: { x: 700, y: 300, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'leaf', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'gate', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  const j = (part: string) => a.joints!.find(k => k.body1.part === part)!
+  assert.equal(motionEndsOf(a, 'leaf'), null, 'not moving: nothing drawn')
+  a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { ...j('leaf'), type: 'revolute', axis: 'Y', lowerLimit: 0, upperLimit: 90, state: { id: 'open' } } })
+  a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { ...j('gate'), type: 'prismatic', axis: 'X', lowerLimit: 0, upperLimit: 300, state: { id: 'slide' } } })
+  /* With the values the screen holds -- design and control alike -- as the editor passes them. */
+  const held = { ...a.designInputs, ...a.stateDefaults, 'frame.size.x': 2400 }
+  const turn = motionEndsOf(a, 'leaf', held)!
+  assert.deepEqual([turn.control, turn.min, turn.max], ['open', 0, 90])
+  assert.deepEqual(turn.ghost.map(g => g.id).sort(), ['__preview:max:leaf', '__preview:min:leaf'], 'the leaf at 0 and at 90, nothing else')
+  const slide = motionEndsOf(a, 'gate', held)!
+  const line = slide.ghost.find(g => g.id === '__target-face:slide')!
+  assert.equal(Math.round((line.shape.dimensions as { width: number }).width), 300, 'the line it travels, its whole stroke')
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("if (!p && this.tab === 'motion' && this.middle === 'edit') return { ghost: this.motionEnds()?.ghost ?? [], highlight: null }"))
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes("i18next.t('figure.text.motion-summary', {"))
+  assert.ok(links.includes("new CustomEvent('go-fasten', { bubbles: true, composed: true })"), 'a part fastened to nothing is taken to fastening')
+  assert.equal(say('figure.text.motion-summary', { part: 'leaf', against: 'frame', kind: '회전', axis: 'Y' }), 'leaf · frame 기준 · Y축 회전')
+  assert.match(say('figure.text.motion-ends-shown', { min: '0', max: '90', unit: 'deg' }), /그 사이는 확인하지 않습니다/)
+})
+
+/* ADR-0097 §5.5, Q3: past the face's edge is said beside the fastening, with the way to change it; nothing moves. */
+test('past the edge of its face is said beside the fastening, with the way to change alignment and gap', () => {
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("if (own?.state === 'out') words.push(say('figure.text.overhang-out', { ...where(own), sides: sides(own) }))"))
+  assert.ok(editor.includes("else if (own?.state === 'possible') words.push(say('figure.text.overhang-possible', where(own)))"))
+  assert.ok(editor.includes("else if (own?.state === 'unknown') words.push(say('figure.text.overhang-unknown', where(own)))"))
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes("<button act @click=${() => this.openDetail()}><md-icon>tune</md-icon>${i18next.t('figure.button.fix-alignment')}</button>"))
+  assert.equal(say('figure.text.overhang-out', { on: 'top', face: '윗면', sides: say('figure.text.overhang-side-high', { axis: 'X', mm: '100' }) }), 'top의 윗면 가장자리 밖으로 나와 있습니다: X 높은 쪽 100 mm. 모델의 점유 공간과는 따로 봅니다.')
+  for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
+    const t = JSON.parse(read(`../translations/${lang}.json`))
+    for (const key of ['figure.text.overhang-out', 'figure.text.overhang-possible', 'figure.text.overhang-unknown', 'figure.text.overhang-held', 'figure.text.overhang-side-low', 'figure.text.overhang-side-high', 'figure.button.fix-alignment']) assert.ok(t[key], `${lang} ${key}`)
+  }
+})
+
+/* Designer 2026-09-27: a moving part may be a row, and a row may be given a motion -- the modeller's own forms keep the row. */
+test('a moving part is made into a row, and a row given or relieved of a motion stays a row, by the modeller\'s forms', async () => {
+  const { rowAxesOf, rowBlockOf, motionJoint, fixedJointOf } = await import('../client/modeller/links.js')
+  let a = createFigureAsset('Conveyor')
+  a = addFigureBox(a, { id: 'frame', size: { x: 2000, y: 100, z: 600 }, position: { x: 0, y: 50, z: 0 } })
+  a = addFigureBox(a, { id: 'roller', size: { x: 60, y: 60, z: 560 }, position: { x: 0, y: 130, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'roller', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  const source = serializeFigureAsset(a)
+  const s = createFigureProductSession({ load: async (id: string) => ({ id, source }), save: async (q: { id?: string; source: string }) => ({ id: q.id ?? 'x', source: q.source }) })
+  await s.open('conveyor')
+  const now = () => JSON.parse(s.source()) as import('@hatiolab/figure-model').FigureAsset
+  const jointOf = () => now().joints!.find(j => j.body1.part === 'roller')!
+  const rollers = () => s.read().geometry.filter(g => g.id === 'roller' || g.id.includes('"roller.')).length
+  const turn = { kind: 'turn', axis: 'y', min: -180, max: 180, id: 'spin', follow: '', multiplier: 1, offset: 0, travel: '', travelPlus: 0 } as never
+  /* Moving first, then a row: offered, not refused. */
+  s.command({ kind: 'set-joint', joint: motionJoint(jointOf(), turn, 'roller') })
+  assert.equal(rowBlockOf(now(), 'roller'), undefined)
+  assert.deepEqual(rowAxesOf(now(), 'roller'), ['x', 'z'])
+  s.command({ kind: 'make-repeat', part: 'roller', axis: 'x', pitch: 200 })
+  assert.equal(rollers(), 10)
+  assert.equal(jointOf().type, 'revolute')
+  /* The motion changed by the form: the row stays. */
+  s.command({ kind: 'set-joint', joint: motionJoint(jointOf(), { ...(turn as object), kind: 'slide', axis: 'z', min: 0, max: 100 } as never, 'roller') })
+  assert.deepEqual([jointOf().type, rollers()], ['prismatic', 10])
+  /* The motion taken away by its button: still a row. */
+  s.command({ kind: 'set-joint', joint: fixedJointOf(jointOf()) })
+  assert.deepEqual([jointOf().type, rollers()], ['fixed', 10])
+  /* Each undone once. */
+  s.undo()
+  assert.deepEqual([jointOf().type, rollers()], ['prismatic', 10])
+  s.undo()
+  s.undo()
+  assert.deepEqual([jointOf().type, rollers()], ['revolute', 1])
+})
+
+/* Designer 2026-09-27: wider than its face is not hidden -- a fact in the relation's details, off to one side said. */
+test('a part wider than its face is said in the relation, with its numbers and whether it sits to one side', () => {
+  const editor = read('../client/modeller/editor.ts')
+  assert.ok(editor.includes("if (own?.state === 'larger') {"))
+  assert.ok(editor.includes("if (own.lopsided.length) note.push(say('figure.text.overhang-lopsided'"))
+  const links = read('../client/modeller/figure-links.ts')
+  assert.ok(links.includes("${this.overhangNote.length ? html`<p hint overhang-note>${this.overhangNote.join(' ')}</p>` : nothing}"), 'in the details, not the warning')
+  assert.equal(say('figure.text.overhang-larger', { on: 'leg', face: '윗면', sides: 'X 낮은 쪽 270 mm, X 높은 쪽 870 mm' }), 'leg의 윗면보다 넓어 가장자리 밖으로 나와 있습니다: X 낮은 쪽 270 mm, X 높은 쪽 870 mm.')
+  for (const lang of ['en', 'ja', 'ko', 'ms', 'zh']) {
+    const t = JSON.parse(read(`../translations/${lang}.json`))
+    assert.ok(t['figure.text.overhang-larger'] && t['figure.text.overhang-lopsided'], lang)
+  }
+})

package/test/fields.test.ts

@@ -83,7 +83,7 @@ test('편집기는 저작한 부품 단위로 고르고 보인다 — 되풀이
   assert.ok(canvas.includes('.filter(([name]) => ownerOf(name) === this.selected)'), '사용자 2026-09-24: 「why repeatable parts are not selected?」')
   const editor = read('../client/modeller/editor.ts')
   assert.ok(editor.includes('this.selected = id ? ownerOf(id) : id'), '캔버스에서 복사본을 누르면 그 되풀이를 고른다')
-  assert.ok(editor.includes('.parts=${this.partRows(view.geometry)}'), '목록은 저작한 부품 한 줄씩')
+  assert.ok(editor.includes('.parts=${this.partRows(view.geometry, asset as FigureAsset | undefined)}'), '목록은 저작한 부품 한 줄씩')
   assert.ok(editor.includes("this.session!.command({ kind: 'set-repeat', part: this.selected, pitch })"), 'pitch 는 명령으로 정한다')
   const parts = read('../client/modeller/figure-parts.ts')
   assert.ok(parts.includes('?disabled=${this.locked || full}'), '등급 한도에 이르면 팔레트가 잠긴다')
@@ -91,14 +91,15 @@ test('편집기는 저작한 부품 단위로 고르고 보인다 — 되풀이
 
 test('pitch 는 한 곳에서 하나의 값이고, 늘 set-repeat 로 바꿔 최대 길이가 따라온다', () => {
   const editor = readFileSync(fileURLToPath(new URL('../client/modeller/editor.ts', import.meta.url)), 'utf8')
-  assert.ok(editor.includes("groupFields(own, this.selected)"), '사용자 2026-09-24: 되풀이의 간격과 형상 치수의 repeat · pitch 가 같은 값으로 두 번 떴다')
+  assert.ok(editor.includes("groupFields(partFields, this.selected)") && editor.includes("const partFields = own.filter("), '사용자 2026-09-24: 되풀이의 간격과 형상 치수의 repeat · pitch 가 같은 값으로 두 번 떴다')
   assert.ok(editor.includes("!i.id.startsWith(this.selected + '.repeat.')"))
   const pitch = editor.slice(editor.indexOf('  private setPitch('), editor.indexOf('  /** Choose a part,'))
   assert.ok(pitch.includes("this.session!.command({ kind: 'set-repeat', part: this.selected, pitch })"), '늘 명령으로 — 최대 길이가 따라온다')
   assert.ok(!pitch.includes('changeField'))
   for (const lang of ['ko', 'en', 'ja', 'zh', 'ms']) {
     const table = JSON.parse(readFileSync(fileURLToPath(new URL(`../translations/${lang}.json`, import.meta.url)), 'utf8'))
-    assert.equal(table['figure.label.repeat-gap'], 'pitch', lang)
+    /* The term stays pitch; what it measures is said beside it (ADR-0097 §5.5: centre to centre). */
+    assert.ok(table['figure.label.repeat-gap'].startsWith('pitch') && table['figure.label.repeat-gap'].length > 'pitch'.length, lang)
     assert.ok(['{length}', '{count}', '{longest}', '{limit}'].every(k => table['figure.text.repeat-what-pitch-gives']?.includes(k)), lang)
   }
 })

package/test/figure-assistant-surface.test.ts

@@ -35,7 +35,10 @@ test('the surface is taken back when the page goes inactive or leaves', () => {
 
 test('the dock applies a proposal through the page, on the version the model saw', () => {
   assert.match(source, /window\.addEventListener\('figure-apply', this\.applyAI\)/)
-  assert.match(source, /this\.session\.applyProposal\(detail\.steps, detail\.revision, detail\.context\)/)
+  /* The page takes it by `takeFigureOffer` (ai-proposal.ts), tested there on the session itself. */
+  assert.match(source, /takeFigureOffer\(this\.session, detail, \{/)
+  const offer = readFileSync(fileURLToPath(new URL('../client/modeller/ai-proposal.ts', import.meta.url)), 'utf8')
+  assert.match(offer, /session\.applyProposal\(detail\.steps, detail\.revision!, detail\.context!, detail\.key\)/)
   assert.match(source, /this\.takeNewFigureProposal\(\)/, 'a new figure opened for a proposal takes its steps')
 })