@things-factory/figure-ui 10.1.156 → 10.1.157

package/client/modeller/clips.ts

@@ -50,12 +50,51 @@ export function clipsOf(asset: FigureAsset): Clip[] {
   return [...clips.values()]
 }
 
-/** The controls no clip plays yet -- the ones a new track can take. One driver per control. */
-export function undrivenOf(asset: FigureAsset): string[] {
-  const driven = new Set((asset.drivers ?? []).map(d => d.state))
-  return asset.document.model.inputs.filter(i => i.role === 'state' && !driven.has(i.id)).map(i => i.id)
+/**
+ * The controls a new track of `clip` can take (ADR-0051 §3.2): one the clip does not play yet, and that no clip plays
+ * outside the clip's motion group -- `group` for a clip not made yet. A clip in no group takes only a control no clip
+ * plays. Without a clip, the controls no clip plays at all.
+ */
+export function undrivenOf(asset: FigureAsset, clip = '', group?: string): string[] {
+  const groupOf = new Map((asset.motionGroups ?? []).flatMap(g => g.clips.map(c => [c, g.id] as const)))
+  const mine = group ?? (clip ? groupOf.get(clip) : undefined)
+  const taken = (state: string) =>
+    (asset.drivers ?? []).some(d => d.state === state && (d.clip === clip || mine === undefined || groupOf.get(d.clip) !== mine))
+  return asset.document.model.inputs.filter(i => i.role === 'state' && !taken(i.id)).map(i => i.id)
+}
+
+/** A motion group as the panel shows it: its setting, and the clips it holds in the clips' order. */
+export interface ClipGroup {
+  id: string
+  label: string
+  clips: string[]
+  defaultClip: string
+  transitionSeconds: number
+}
+
+/** The figure's motion groups, and the clips in none -- the ones a group can take. */
+export function clipGroupsOf(asset: FigureAsset): { groups: ClipGroup[]; free: string[] } {
+  const groups = (asset.motionGroups ?? []).map(g => ({ ...g, clips: [...g.clips] }))
+  const grouped = new Set(groups.flatMap(g => g.clips))
+  const free = [...new Set((asset.drivers ?? []).map(d => d.clip))].filter(c => !grouped.has(c))
+  return { groups, free }
+}
+
+/** A group id not yet taken: `motion`, then `motion-2`, `motion-3`, … An id is not made from a label a person types. */
+export function freeGroupIdOf(asset: FigureAsset): string {
+  const taken = new Set((asset.motionGroups ?? []).map(g => g.id))
+  if (!taken.has('motion')) return 'motion'
+  let n = 2
+  while (taken.has(`motion-${n}`)) n++
+  return `motion-${n}`
 }
 
+/** The edit that writes a group back with a change: one whole group, as the kernel takes it. */
+export const groupEdit = (group: ClipGroup, patch: Partial<Omit<ClipGroup, 'id'>> = {}) => ({
+  kind: 'set-motion-group' as const,
+  group: { id: group.id, label: patch.label ?? group.label, clips: patch.clips ?? group.clips, defaultClip: patch.defaultClip ?? group.defaultClip, transitionSeconds: patch.transitionSeconds ?? group.transitionSeconds }
+})
+
 /** The pose a clip gives at a moment, as one batch of state changes -- one step of the history. */
 export function poseAt(asset: FigureAsset, clip: string, seconds: number): FigureInputChange[] {
   const units = new Map(asset.document.model.inputs.map(i => [i.id, i.unit]))

package/client/modeller/data-interface.ts

@@ -0,0 +1,110 @@
+/*
+ * The figure's public data properties and what each moves (ADR-0051 §2.2): what the data tab offers and shows. Every
+ * rule is figure-model's -- which transform a property may take, whether a connection holds, what a sample moves; this
+ * only lists what there is to choose and drafts a first connection the kernel then checks. Kept apart from the element so
+ * it is tested without a browser.
+ */
+import { compileFigureDataInterface, evaluateFigureDataInterface, validateFigureDataValues, FIGURE_PART_ID } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureDataConnection, FigureDataProperty, FigureDataResult, FigureDataTarget, FigureDataValue, FigureDataValueIssue } from '@hatiolab/figure-model'
+
+/** Something a connection can write, with what the screen shows of it. */
+export interface DataTargetChoice {
+  /** One string per target, for a select's value. */
+  key: string
+  target: FigureDataTarget
+  /** The control's label, the colour token, or the group's label. */
+  name: string
+  unit?: string
+  min?: number
+  max?: number
+}
+
+export const targetKeyOf = (t: FigureDataTarget): string =>
+  t.kind === 'state' ? `state:${t.input}` : t.kind === 'palette' ? `palette:${t.token}` : `${t.kind}:${t.group}`
+
+/**
+ * What a property of this kind can be connected to: a number moves a control or a group's speed; an enum or a boolean
+ * moves a control, a colour or which clip of a group plays (through a case per value). A control is offered observed: a
+ * value read from the machine applies as it comes.
+ */
+export function dataTargetsOf(asset: FigureAsset, kind: FigureDataProperty['kind']): DataTargetChoice[] {
+  const out: DataTargetChoice[] = []
+  for (const input of asset.document.model.inputs) {
+    if (input.role !== 'state') continue
+    const target: FigureDataTarget = { kind: 'state', input: input.id, sourceMode: 'observed' }
+    out.push({ key: targetKeyOf(target), target, name: asset.stateInputs?.[input.id]?.label ?? input.id, unit: input.unit, min: input.min, max: input.max })
+  }
+  if (kind !== 'number')
+    for (const token of Object.keys(asset.palette)) {
+      const target: FigureDataTarget = { kind: 'palette', token }
+      out.push({ key: targetKeyOf(target), target, name: token })
+    }
+  for (const group of asset.motionGroups ?? []) {
+    const target: FigureDataTarget = kind === 'number' ? { kind: 'motion-speed', group: group.id } : { kind: 'motion-clip', group: group.id }
+    out.push({ key: targetKeyOf(target), target, name: group.label })
+  }
+  return out
+}
+
+/** The values a lookup has a case for: an enum's values, or both booleans. Nothing for a number. */
+export const domainOf = (property: FigureDataProperty): FigureDataValue[] =>
+  property.kind === 'enum' ? [...property.values] : property.kind === 'boolean' ? [false, true] : []
+
+/** An id not taken among `taken`: `base`, then `base-2`, `base-3`, … made into the kernel's id shape. */
+export function freeDataIdOf(taken: Iterable<string>, base: string): string {
+  const used = new Set(taken)
+  const cleaned = base.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^[^a-zA-Z]+/, '').replace(/-+$/, '') || 'data'
+  const id = FIGURE_PART_ID.test(cleaned) ? cleaned : 'data'
+  if (!used.has(id)) return id
+  let n = 2
+  while (used.has(`${id}-${n}`)) n++
+  return `${id}-${n}`
+}
+
+/**
+ * A first connection of a property to a target, for the author to adjust: a number as it is in the control's own unit,
+ * or scaled from another; an enum or a boolean case by case, each case at what the target shows now -- the control's
+ * rest value, the colour, the group's first clip. The kernel says whether it holds.
+ */
+export function connectionDraftOf(asset: FigureAsset, property: FigureDataProperty, choice: DataTargetChoice): FigureDataConnection {
+  const taken = (asset.dataInterface?.connections ?? []).map(c => c.id)
+  const id = freeDataIdOf(taken, `${property.id}-${choice.target.kind === 'state' ? choice.target.input : choice.target.kind === 'palette' ? 'colour' : choice.target.group}`)
+  const target = choice.target
+  if (property.kind === 'number') {
+    const same = target.kind === 'motion-speed' || (target.kind === 'state' && choice.unit === property.unit)
+    return { id, property: property.id, transform: same ? { kind: 'identity' } : { kind: 'affine', scale: 1, offset: 0 }, target }
+  }
+  const now: FigureDataValue =
+    target.kind === 'state'
+      ? (asset.stateDefaults[target.input] ?? 0)
+      : target.kind === 'palette'
+        ? (asset.palette[target.token] ?? '#000000')
+        : ((asset.motionGroups ?? []).find(g => g.id === target.group)?.defaultClip ?? '')
+  return { id, property: property.id, transform: { kind: 'lookup', cases: domainOf(property).map(when => ({ when, value: now })) }, target }
+}
+
+/** What a property looks like when first made: a number 0 to 1, a boolean off, an enum of two values. */
+export function propertyDraftOf(asset: FigureAsset, label: string, kind: FigureDataProperty['kind']): FigureDataProperty {
+  const id = freeDataIdOf((asset.dataInterface?.properties ?? []).map(p => p.id), label)
+  if (kind === 'number') return { id, label, kind, unit: 'ratio', min: 0, max: 1, default: 0 }
+  if (kind === 'boolean') return { id, label, kind, default: false }
+  return { id, label, kind, values: ['off', 'on'], default: 'off' }
+}
+
+/** A value typed in a sample field, as the property takes it: a number, true or false, or the enum value. */
+export function sampleValueOf(property: FigureDataProperty, typed: string): FigureDataValue {
+  if (property.kind === 'number') return typed.trim() === '' ? Number.NaN : Number(typed)
+  if (property.kind === 'boolean') return typed === 'true'
+  return typed
+}
+
+/**
+ * What a sample of values would move, as the figure would run it: the kernel's check and evaluation of the interface.
+ * Refused whole when one value cannot be taken, with each one's reason, as a live snapshot is.
+ */
+export function dataSampleOf(asset: FigureAsset, values: Record<string, FigureDataValue>): { result: FigureDataResult } | { issues: FigureDataValueIssue[] } {
+  const plan = compileFigureDataInterface(asset)
+  if (!plan) return { issues: [] }
+  const issues = validateFigureDataValues(plan, values)
+  return issues.length ? { issues } : { result: evaluateFigureDataInterface(plan, values) }
+}

package/client/modeller/editor.ts

@@ -24,6 +24,7 @@ import { motionEndsOf, type MotionEnds } from './motion-ends.js'
 import './figure-links.js'
 import './figure-controls.js'
 import './figure-clips.js'
+import './figure-data-panel.js'
 import './figure-preview.js'
 import './figure-settings.js'
 import { DEFAULT_VIEW, type ViewSettings } from '@things-factory/figure-viewer/dist-client/figure-view.js'
@@ -68,10 +69,10 @@ import { startingShapeKindOfBody } from './starting-shape.js'
 
 
 /**
- * The side's tabs: properties, what it does (places), motion, the verdict, the view, the release history. A figure-level tab (verdict, history) gives way to properties when a part is chosen; a tab about
+ * The side's tabs: properties, what it does (places), motion, its data (ADR-0051), the verdict, the view, the release history. A figure-level tab (verdict, history) gives way to properties when a part is chosen; a tab about
  * parts keeps showing the newly chosen part.
  */
-type SideTab = 'properties' | 'capability' | 'motion' | 'verdict' | 'view' | 'history'
+type SideTab = 'properties' | 'capability' | 'motion' | 'data' | 'verdict' | 'view' | 'history'
 
 /** Product editor surface. The injected session is shared by page persistence and AI commands. */
 const NO_OVERHANG = { words: NO_WORDS, note: NO_WORDS }
@@ -749,6 +750,8 @@ export class FigureEditor extends LitElement {
     return this.lastAnchors
   }
   private lastAnchors: Record<string, ScaleAnchor> = {}
+  /** Data values tried in the data tab, run by the preview's figure; null when none are (ADR-0051 §2.2). */
+  @state() private dataSample: Record<string, unknown> | null = null
   /** The figure's controls: try a value, name it, set its range and travel time, keep the pose. */
   private renderControls(view: { fields: Array<{ id: string; role?: string; value: number }> }, unavailable: boolean) {
     const asset = this.shown()?.asset
@@ -1549,6 +1552,7 @@ export class FigureEditor extends LitElement {
               .context=${view.context ?? ''}
               .view=${this.view}
               .selected=${this.selected}
+              .sample=${this.dataSample}
               @configure-size=${async (e: CustomEvent<{ part: string }>) => {
                 this.middle = 'edit'
                 this.selected = e.detail.part
@@ -1585,6 +1589,7 @@ export class FigureEditor extends LitElement {
             ${this.renderTab('properties', 'tune', i18next.t('figure.label.properties'))}
             ${this.renderTab('capability', 'conveyor_belt', i18next.t('figure.label.tab-capability'))}
             ${this.renderTab('motion', 'animation', i18next.t('figure.label.motion'))}
+            ${this.renderTab('data', 'sensors', i18next.t('figure.label.tab-data'))}
             ${this.renderTab('verdict', 'insights', i18next.t('figure.label.maturity'), this.instances)}
             ${this.renderTab('view', 'wb_sunny', i18next.t('figure.label.tab-environment'))}
             ${this.renderTab('history', 'history', i18next.t('figure.label.history'))}
@@ -1656,6 +1661,15 @@ export class FigureEditor extends LitElement {
             ${this.selected && part ? this.renderLinks(unavailable, 'motion') : html`<section><p hint>${i18next.t('figure.text.choose-a-part-to-move')}</p></section>`}
             ${this.renderControls(view, unavailable)}
           </div>
+          <div panel ?off=${tab !== 'data'}>
+            ${this.renderSubject()}
+            <figure-data-panel
+              .asset=${asset}
+              ?locked=${unavailable}
+              @data-sample=${(e: CustomEvent) => (this.dataSample = e.detail.values)}
+              @part-edit=${(e: CustomEvent) => this.run(() => this.session!.edit(e.detail.edit))}
+            ></figure-data-panel>
+          </div>
           <div panel flush ?off=${tab !== 'verdict'}><slot name="verdict"></slot></div>
           <div panel flush ?off=${tab !== 'view'}>
             <figure-settings .view=${this.view} @update-view=${(e: CustomEvent) => this.setView(e.detail.view)}></figure-settings>

package/client/modeller/figure-clips.ts

@@ -6,7 +6,7 @@ import { customElement, property, state } from 'lit/decorators.js'
 import { i18next, localize } from '@operato/i18n'
 import type { FigureAsset } from '@hatiolab/figure-model'
 
-import { clipsOf, poseAt, trackEdit, undrivenOf, withKey, withoutKey, type Clip, type ClipTrack } from './clips.js'
+import { clipGroupsOf, clipsOf, freeGroupIdOf, groupEdit, poseAt, trackEdit, undrivenOf, withKey, withoutKey, type Clip, type ClipGroup, type ClipTrack } from './clips.js'
 import { SidePanelStyles } from '@things-factory/figure-viewer/dist-client/side-panel-styles.js'
 import { HelpToggles } from './help.js'
 
@@ -15,6 +15,9 @@ import { HelpToggles } from './help.js'
  * control. Scrubbing a clip shows its pose at that moment (one batch of input changes, not saved as the default); a key
  * is added at the scrubbed moment with the control's value there, so a pose is made with the controls' sliders and
  * then kept as a key. Every change is one part edit.
+ *
+ * Clips of one motion group play one at a time on the same controls -- idle, walk, run (ADR-0051 §3.2): only clips of
+ * one group may play the same control, so a new clip is put in a group as it is made when it is to take one.
  */
 @customElement('figure-clips')
 export class FigureClips extends localize(i18next)(LitElement) {
@@ -98,7 +101,8 @@ export class FigureClips extends localize(i18next)(LitElement) {
 
   /** Where each clip is scrubbed to, in seconds. */
   @state() private at: Record<string, number> = {}
-  @state() private adding = { state: '', clip: '', name: '', duration: 2 }
+  @state() private adding = { state: '', clip: '', name: '', duration: 2, group: '' }
+  @state() private grouping = { clip: '', label: '' }
 
   render() {
     const asset = this.asset
@@ -110,7 +114,7 @@ export class FigureClips extends localize(i18next)(LitElement) {
         ${this.help.hint('figure.text.clips-explained')}
         ${clips.map(clip => this.renderClip(clip))}
       </section>
-      ${this.renderAdd(asset, clips)}
+      ${this.renderAdd(asset, clips)} ${this.renderGroups(asset)}
     `
   }
 
@@ -155,7 +159,7 @@ export class FigureClips extends localize(i18next)(LitElement) {
           <option value="wrap" ?selected=${track.loop === 'wrap'}>${i18next.t('figure.label.clip-loop-wrap')}</option>
           <option value="hold" ?selected=${track.loop === 'hold'}>${i18next.t('figure.label.clip-loop-hold')}</option>
         </select>
-        <button act ?disabled=${this.locked} title=${i18next.t('figure.button.remove-track')} @click=${() => this.edit({ kind: 'remove-driver', state: track.state })}>
+        <button act ?disabled=${this.locked} title=${i18next.t('figure.button.remove-track')} @click=${() => this.edit({ kind: 'remove-driver', state: track.state, clip: clip.name })}>
           <md-icon>close</md-icon>
         </button>
       </div>
@@ -185,19 +189,22 @@ export class FigureClips extends localize(i18next)(LitElement) {
   }
 
   private renderAdd(asset: FigureAsset, clips: Clip[]) {
-    const free = undrivenOf(asset)
-    if (!free.length) return clips.length ? nothing : html`<p hint>${i18next.t('figure.text.no-controls')}</p>`
     const a = this.adding
-    const stateId = free.includes(a.state) ? a.state : free[0]!
     const joining = clips.find(c => c.name === a.clip)
+    const { groups } = clipGroupsOf(asset)
+    const group = joining ? undefined : groups.find(g => g.id === a.group)
+    /* The controls this clip may take: not played by it yet, and by no clip outside its group. */
+    const free = undrivenOf(asset, joining?.name ?? '', group?.id)
+    if (!free.length && !clips.length && !groups.length) return html`<p hint>${i18next.t('figure.text.no-controls')}</p>`
+    const stateId = free.includes(a.state) ? a.state : free[0]
     const name = joining ? joining.name : a.name.trim()
-    const input = asset.document.model.inputs.find(i => i.id === stateId)!
+    const input = asset.document.model.inputs.find(i => i.id === stateId)
     const duration = joining ? joining.duration : a.duration
-    const ready = !!name && duration > 0
+    const ready = !!name && duration > 0 && !!input
     return html`<section><h3>${i18next.t('figure.label.add-track')}</h3>
       <div form>
         <span>${i18next.t('figure.label.controls')}</span>
-        <select @change=${(e: Event) => (this.adding = { ...a, state: (e.target as HTMLSelectElement).value })}>
+        <select ?disabled=${!free.length} @change=${(e: Event) => (this.adding = { ...a, state: (e.target as HTMLSelectElement).value })}>
           ${free.map(id => html`<option value=${id} ?selected=${id === stateId}>${asset.stateInputs?.[id]?.label ?? id}</option>`)}
         </select>
         <span>${i18next.t('figure.label.clip')}</span>
@@ -205,6 +212,13 @@ export class FigureClips extends localize(i18next)(LitElement) {
           <option value="" ?selected=${!joining}>${i18next.t('figure.label.new-clip')}</option>
           ${clips.map(c => html`<option value=${c.name} ?selected=${c === joining}>${c.name}</option>`)}
         </select>
+        ${joining || !groups.length
+          ? nothing
+          : html`<span>${i18next.t('figure.label.motion-group')}</span>
+              <select @change=${(e: Event) => (this.adding = { ...a, group: (e.target as HTMLSelectElement).value })}>
+                <option value="" ?selected=${!group}>${i18next.t('figure.label.no-motion-group')}</option>
+                ${groups.map(g => html`<option value=${g.id} ?selected=${g === group}>${g.label}</option>`)}
+              </select>`}
         ${joining
           ? nothing
           : html`<span>${i18next.t('figure.label.clip-name')}</span>
@@ -221,9 +235,10 @@ export class FigureClips extends localize(i18next)(LitElement) {
             state: stateId,
             clip: name,
             ...(joining ? {} : { duration }),
+            ...(group ? { group: group.id } : {}),
             keys: [
-              { seconds: 0, value: input.min },
-              { seconds: duration, value: input.max }
+              { seconds: 0, value: input!.min },
+              { seconds: duration, value: input!.max }
             ]
           })}
       >
@@ -231,6 +246,104 @@ export class FigureClips extends localize(i18next)(LitElement) {
       </button></section>`
   }
 
+  /**
+   * The motion groups: a name, the clip that plays until another is chosen, how long a change of clip blends, and the
+   * clips each holds. A group is made from a clip in none; a clip in none joins one here. Every change is one edit.
+   */
+  private renderGroups(asset: FigureAsset) {
+    const { groups, free } = clipGroupsOf(asset)
+    if (!groups.length && !free.length) return nothing
+    const g = this.grouping
+    const first = free.includes(g.clip) ? g.clip : free[0]
+    return html`<section>
+      <h3>${i18next.t('figure.label.motion-groups')}${this.help.button('figure.text.motion-groups-explained')}</h3>
+      ${this.help.hint('figure.text.motion-groups-explained')}
+      ${groups.map(group => this.renderGroup(group, free))}
+      ${free.length
+        ? html`<div form>
+              <span>${i18next.t('figure.label.motion-group-name')}</span>
+              <input .value=${g.label} placeholder=${i18next.t('figure.label.motion-group')} @input=${(e: Event) => (this.grouping = { ...g, label: (e.target as HTMLInputElement).value })} />
+              <span>${i18next.t('figure.label.clip')}</span>
+              <select @change=${(e: Event) => (this.grouping = { ...g, clip: (e.target as HTMLSelectElement).value })}>
+                ${free.map(c => html`<option value=${c} ?selected=${c === first}>${c}</option>`)}
+              </select>
+            </div>
+            <button
+              act
+              ?disabled=${this.locked || !first || !g.label.trim()}
+              @click=${() => {
+                this.edit({ kind: 'set-motion-group', group: { id: freeGroupIdOf(asset), label: g.label.trim(), clips: [first!], defaultClip: first!, transitionSeconds: 0.2 } })
+                this.grouping = { clip: '', label: '' }
+              }}
+            >
+              <md-icon>add</md-icon>${i18next.t('figure.button.add-motion-group')}
+            </button>`
+        : nothing}
+    </section>`
+  }
+
+  private renderGroup(group: ClipGroup, free: string[]) {
+    const value = (e: Event) => (e.target as HTMLInputElement | HTMLSelectElement).value
+    return html`<section clip>
+      <div track-head>
+        <strong>${group.label}</strong>
+        <span></span>
+        <button act ?disabled=${this.locked} title=${i18next.t('figure.button.remove-motion-group')} @click=${() => this.edit({ kind: 'remove-motion-group', id: group.id })}>
+          <md-icon>close</md-icon>
+        </button>
+      </div>
+      <div form>
+        <span>${i18next.t('figure.label.motion-group-name')}</span>
+        <input .value=${group.label} ?disabled=${this.locked} @change=${(e: Event) => value(e).trim() && this.edit(groupEdit(group, { label: value(e).trim() }))} />
+        <span>${i18next.t('figure.label.motion-group-default')}</span>
+        <select ?disabled=${this.locked} @change=${(e: Event) => this.edit(groupEdit(group, { defaultClip: value(e) }))}>
+          ${group.clips.map(c => html`<option value=${c} ?selected=${c === group.defaultClip}>${c}</option>`)}
+        </select>
+        <span>${i18next.t('figure.label.motion-group-transition')}</span>
+        <input
+          type="number"
+          min="0"
+          step="any"
+          .value=${String(group.transitionSeconds)}
+          ?disabled=${this.locked}
+          @change=${(e: Event) => this.edit(groupEdit(group, { transitionSeconds: (e.target as HTMLInputElement).valueAsNumber }))}
+        />
+      </div>
+      <div keys>
+        ${group.clips.map(
+          c => html`<span key
+            >${c}
+            <button
+              ?disabled=${this.locked || group.clips.length < 2}
+              title=${i18next.t('figure.button.remove-clip-from-group')}
+              aria-label=${i18next.t('figure.button.remove-clip-from-group')}
+              @click=${() => {
+                const clips = group.clips.filter(x => x !== c)
+                this.edit(groupEdit(group, { clips, defaultClip: group.defaultClip === c ? clips[0]! : group.defaultClip }))
+              }}
+            >
+              <md-icon>close</md-icon>
+            </button></span
+          >`
+        )}
+      </div>
+      ${free.length
+        ? html`<select
+            aria-label=${i18next.t('figure.button.add-clip-to-group')}
+            ?disabled=${this.locked}
+            @change=${(e: Event) => {
+              const c = value(e)
+              if (c) this.edit(groupEdit(group, { clips: [...group.clips, c] }))
+              ;(e.target as HTMLSelectElement).value = ''
+            }}
+          >
+            <option value="" selected>${i18next.t('figure.button.add-clip-to-group')}</option>
+            ${free.map(c => html`<option value=${c}>${c}</option>`)}
+          </select>`
+        : nothing}
+    </section>`
+  }
+
   /** Show the clip's pose at a moment: one batch of input changes, not saved as the default. */
   /** Show the clip's pose at a moment. While the bar is dragged the pose is live (drawn, not recorded); the release
    * applies it as one batch of input changes. */