@things-factory/figure-ui 10.1.46 → 10.1.47

package/client/modeller/v3-canvas.ts

@@ -1,307 +1,265 @@
-import { LitElement, html, css, type PropertyValues } from 'lit'
-import { customElement, property } from 'lit/decorators.js'
+import { LitElement, html, css, nothing, unsafeCSS, type PropertyValues } from 'lit'
+import { customElement, property, query } from 'lit/decorators.js'
 import { i18next } from '@operato/i18n'
-import * as THREE from 'three'
-import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'
-import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js'
-import type { GizmoReach, GizmoResult } from './v3-gizmo.js'
-import { replaceV3Meshes, disposeV3Meshes, type V3RenderPart } from './v3-renderer.js'
+import { create, Model, niceGridStep } from '@hatiolab/things-scene'
+
+import type { GizmoReach } from './v3-gizmo.js'
+import type { V3RenderPart } from './v3-renderer.js'
+import { DEFAULT_VIEW, sceneLook, WORKBENCH, type ViewSettings } from './figure-view.js'
+import { boardFor, changedKeys, componentOf, gizmoResultOf, type Board } from './v3-stage-model.js'
+
+/*
+ * The V3 modeller's canvas -- a things-scene board in editing mode, as the V2 modeller's was.
+ *
+ * Each body figure-model evaluates stands on the board as a `figure-v3-part` component, so everything the V2 canvas
+ * had comes from the scene, not from code of our own: picking and the orange outline, the gizmo with its snapping and
+ * live readout, box and shift selection, the camera (damping, zoom toward the cursor, double-click to fit, the six
+ * view presets and their keys), the studio environment, the coordinate ground, lights and shadows, supersampling.
+ * An earlier canvas drew the bodies with three.js directly and lost all of that (user, 2026-09-24: "why nerf it?").
+ *
+ * What the gizmo writes back to a component comes out as `part-transformed` in the inputs' terms (`v3-stage-model`),
+ * and the editor turns it into one step of the history; the next evaluation puts the component where the inputs say,
+ * so a change a part cannot take (a fastened part moved) springs back.
+ */
+
+interface SceneComponent {
+  state: Record<string, unknown>
+  set: (props: Record<string, unknown>) => void
+  dispose?: () => void
+}
+interface SceneLayer extends SceneComponent {
+  components?: SceneComponent[]
+  root?: { on?: (event: string, handler: (...args: unknown[]) => void) => void; selected?: SceneComponent[] }
+  on?: (event: string, handler: (...args: unknown[]) => void) => void
+  addComponent?: (component: SceneComponent) => void
+  removeComponent?: (component: SceneComponent) => void
+  invalidate?: () => void
+  fitCameraToModel?: () => void
+  app?: unknown
+}
+interface SceneHandle {
+  dispose?: () => void
+  resize?: () => void
+  fit?: (type?: string) => void
+  root?: SceneLayer
+}
+
+/* The 2D side of the board, which the author never sees on this page but the scene paints. */
+const PAPER = '#ffffff'
 
-/** Renders evaluated V3 geometry directly. There is no parts/base or things-scene conversion. */
 @customElement('figure-v3-canvas')
 export class FigureV3Canvas extends LitElement {
   static styles = css`
     :host {
-      display: block;
-      min-width: 0;
-      min-height: 0;
       position: relative;
-      /*
-        The working board is one step above the surface in both themes (UX, 2026-09-24): surface-container is 238
-        in light and 31 in dark. The 3D background is read from this same value (paintBackground), so the
-        first paint and the scene agree and there is no flash between them.
-      */
-      background: var(--md-sys-color-surface-container);
+      display: flex;
+      min-height: 0;
+      overflow: hidden;
+      background-color: ${unsafeCSS(WORKBENCH)};
     }
-    canvas {
-      display: block;
+    /* The scene sets position: relative inline on its target; the size is given so it still fills the host. */
+    div[stage] {
+      position: absolute;
+      inset: 0;
       width: 100%;
       height: 100%;
     }
-    div[gizmo] {
-      position: absolute;
-      top: 8px;
-      left: 8px;
-      display: flex;
-      gap: 2px;
-      padding: 2px;
-      border-radius: 6px;
-      background: var(--md-sys-color-surface);
-      border: 1px solid var(--md-sys-color-outline-variant);
-    }
-    div[gizmo] button {
-      font: inherit;
-      font-size: 12px;
-      padding: 3px 8px;
-      border: none;
-      border-radius: 4px;
-      background: none;
-      color: var(--md-sys-color-on-surface);
-      cursor: pointer;
-    }
-    div[gizmo] button[on] {
-      background: var(--md-sys-color-secondary-container);
-      color: var(--md-sys-color-on-secondary-container);
-    }
-    div[gizmo] button:disabled {
-      opacity: 0.4;
-      cursor: default;
-    }
     p {
       position: absolute;
       inset: 45% 1rem auto;
+      margin: 0;
       text-align: center;
       pointer-events: none;
-      color: var(--md-sys-color-on-surface-variant);
+      color: #f4f4f4;
     }
   `
   @property({ attribute: false }) parts: V3RenderPart[] = []
   @property({ attribute: false }) palette: Record<string, string> = {}
+  /** Which figure is open. Another one stands the board up again. */
   @property() context = ''
-  /** The selected part, and what the gizmo may write for it (`gizmoReachOf`). Nothing reachable, no gizmo. */
   @property() selected = ''
+  /** What the gizmo may write for the selected part; a change beyond it is not applied and the part springs back. */
   @property({ attribute: false }) reach: GizmoReach = { translate: false, rotate: false, scale: false }
-  /** Move · turn · size — W · E · R, as in the V2 modeller. */
-  @property() mode: 'translate' | 'rotate' | 'scale' = 'translate'
-  private transform?: TransformControls
-  /** What the gizmo holds: a stand-in at the body's origin, so the body's own matrix stays the evaluation's. */
-  private readonly proxy = new THREE.Object3D()
-  private dragStart?: { proxy: THREE.Matrix4; mesh: THREE.Matrix4; body: THREE.Mesh }
-  /** The pointerup that ends a drag is not a pick — releasing off the body would otherwise deselect it. */
-  private justDragged = false
-  private renderer?: THREE.WebGLRenderer
-  private readonly scene = new THREE.Scene()
-  private readonly group = new THREE.Group()
-  private readonly camera = new THREE.PerspectiveCamera(40, 1, 0.1, 1000000)
-  private controls?: OrbitControls
-  private observer?: ResizeObserver
-  private themeObserver?: MutationObserver
-  private initialized = false
-  private contextAtRender = ''
+  @property({ attribute: false }) view: ViewSettings = DEFAULT_VIEW
+
+  @query('div[stage]') private stage!: HTMLDivElement
+
+  private scene?: SceneHandle
+  private board?: Board & { depth: number }
+  private standingFor?: string
+  private watcher?: ResizeObserver
+  /** Set while this canvas writes to components, so the scene's echo of it is not taken for a drag. */
+  private writing = false
+
   render() {
-    const any = this.selected && (this.reach.translate || this.reach.rotate || this.reach.scale)
-    return html`<canvas aria-label="Figure 3D 모델" tabindex="0" @pointerup=${this.pick} @keydown=${this.key}></canvas
-      >${any
-        ? html`<div gizmo>
-            ${(['translate', 'rotate', 'scale'] as const).map(
-              (mode, i) => html`<button
-                ?on=${this.mode === mode}
-                ?disabled=${!this.reach[mode]}
-                title=${`${i18next.t('figure.label.gizmo-' + mode)} (${'WER'[i]})`}
-                @click=${() => (this.mode = mode)}
-              >
-                ${i18next.t('figure.label.gizmo-' + mode)}
-              </button>`
-            )}
-          </div>`
-        : null}${this.parts.length ? null : html`<p>도형을 추가해 모델링을 시작하세요.</p>`}`
-  }
-  private key = (event: KeyboardEvent) => {
-    const mode = ({ w: 'translate', e: 'rotate', r: 'scale' } as const)[event.key.toLowerCase() as 'w' | 'e' | 'r']
-    if (mode && this.reach[mode]) this.mode = mode
-  }
-  protected firstUpdated() {
-    this.initialize()
+    return html`<div stage></div>${this.parts.length ? nothing : html`<p>${i18next.t('figure.text.add-a-shape-to-start')}</p>`}`
   }
-  connectedCallback() {
-    super.connectedCallback()
-    if (this.hasUpdated) void this.updateComplete.then(() => this.initialize())
-  }
-  private initialize() {
-    if (this.initialized || !this.isConnected) return
-    const canvas = this.renderRoot.querySelector('canvas')!
-    this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true, preserveDrawingBuffer: true })
-    this.renderer.setPixelRatio(Math.min(devicePixelRatio, 2))
-    this.paintBackground()
-    /*
-      The app switches theme by the body's class (light · dark). Reading the colour once at start left a light
-      board in the middle of a dark screen after every switch (seen 2026-09-24), so it is read again then.
-    */
-    this.themeObserver = new MutationObserver(() => {
-      this.paintBackground()
-      this.draw()
-    })
-    this.themeObserver.observe(document.body, { attributes: true, attributeFilter: ['class'] })
-    this.scene.add(this.group, new THREE.HemisphereLight(0xffffff, 0x62717d, 2.5))
-    const light = new THREE.DirectionalLight(0xffffff, 3)
-    light.position.set(1, 2, 3)
-    this.scene.add(light)
-    this.controls = new OrbitControls(this.camera, canvas)
-    this.controls.addEventListener('change', this.draw)
-    this.transform = new TransformControls(this.camera, canvas)
-    this.transform.setSpace('world')
-    this.transform.addEventListener('change', this.draw)
-    this.transform.addEventListener('dragging-changed', this.dragging)
-    this.transform.addEventListener('objectChange', this.follow)
-    this.scene.add(this.proxy, this.transform.getHelper())
-    this.observer = new ResizeObserver(() => {
-      const r = this.getBoundingClientRect()
-      if (r.width && r.height) {
-        this.renderer!.setSize(r.width, r.height, false)
-        this.camera.aspect = r.width / r.height
-        this.camera.updateProjectionMatrix()
-        this.draw()
-      }
-    })
-    this.observer.observe(this)
-    this.initialized = true
-    this.updateGeometry(true)
+
+  firstUpdated() {
+    this.standUp()
+    this.watcher = new ResizeObserver(() => this.scene?.resize?.())
+    this.watcher.observe(this)
   }
+
   protected updated(changed: PropertyValues) {
-    if (this.initialized && (changed.has('parts') || changed.has('palette') || changed.has('context')))
-      this.updateGeometry(this.contextAtRender !== this.context)
-    if (this.initialized && ['parts', 'selected', 'reach', 'mode', 'context'].some(key => changed.has(key))) this.placeGizmo()
+    if (!this.hasUpdated) return
+    if (changed.has('parts') || changed.has('palette') || changed.has('context')) this.standUp()
+    if (changed.has('view')) this.applyView()
+    if (changed.has('selected')) this.showSelected()
   }
-  /** Puts the gizmo on the selected body, in a mode it may write — or takes it away. */
-  private placeGizmo() {
-    const transform = this.transform
-    if (!transform || this.dragStart) return
-    if (!this.reach[this.mode]) {
-      const first = (['translate', 'rotate', 'scale'] as const).find(mode => this.reach[mode])
-      if (first && first !== this.mode) {
-        this.mode = first
-        return
-      }
-    }
-    const body = this.group.children.find(child => child.name === this.selected) as THREE.Mesh | undefined
-    if (!body || !this.reach[this.mode]) {
-      transform.detach()
-      this.draw()
-      return
-    }
-    const position = new THREE.Vector3(),
-      quaternion = new THREE.Quaternion(),
-      scale = new THREE.Vector3()
-    body.matrix.decompose(position, quaternion, scale)
-    this.proxy.position.copy(position)
-    this.proxy.quaternion.copy(quaternion)
-    this.proxy.scale.set(1, 1, 1)
-    this.proxy.updateMatrixWorld(true)
-    transform.setMode(this.mode)
-    /* Size follows the body's own axes; moving and turning read in the asset's axes, which the inputs are in. */
-    transform.setSpace(this.mode === 'scale' ? 'local' : 'world')
-    transform.attach(this.proxy)
-    this.draw()
+
+  disconnectedCallback() {
+    super.disconnectedCallback()
+    this.watcher?.disconnect()
+    this.watcher = undefined
+    this.teardown()
   }
-  private dragging = (event: { value: unknown }) => {
-    const on = !!event.value
-    if (this.controls) this.controls.enabled = !on
-    const body = this.group.children.find(child => child.name === this.selected) as THREE.Mesh | undefined
-    if (on && body) {
-      this.proxy.updateMatrix()
-      this.dragStart = { proxy: this.proxy.matrix.clone(), mesh: body.matrix.clone(), body }
+
+  /** The whole figure in view: the board's fit, then the 3D camera's own, as V2 did. */
+  fit() {
+    this.scene?.fit?.('ratio')
+    this.scene?.root?.fitCameraToModel?.()
+  }
+
+  /**
+   * Stand the board up for this figure, or bring the one standing up to date. A new board only for another figure or
+   * one that has outgrown it -- standing up again loses the selection and the camera.
+   */
+  private standUp() {
+    if (!this.stage) return
+    const needed = boardFor(this.parts, this.board)
+    const outgrown = !this.board || needed.width > this.board.width || needed.height > this.board.height || needed.depth > this.board.depth
+    if (this.scene && this.standingFor === this.context && !outgrown) {
+      this.sync()
       return
     }
-    const start = this.dragStart
-    this.dragStart = undefined
-    if (!start) return
-    /* Either listener may see the release first; the flag lasts past both, then clears. */
-    this.justDragged = true
-    setTimeout(() => (this.justDragged = false))
-    const result: GizmoResult = {}
-    if (this.mode === 'translate') result.position = this.proxy.position.toArray() as [number, number, number]
-    if (this.mode === 'rotate') {
-      /* rigid@1 composes Rx·Ry·Rz — three's 'XYZ' order — so the angles come back as the inputs mean them. */
-      const euler = new THREE.Euler().setFromQuaternion(this.proxy.quaternion, 'XYZ')
-      result.rotation = [euler.x, euler.y, euler.z].map(THREE.MathUtils.radToDeg) as [number, number, number]
-    }
-    if (this.mode === 'scale') result.scale = this.proxy.scale.toArray() as [number, number, number]
-    this.dispatchEvent(new CustomEvent('part-transformed', { detail: { id: this.selected, result }, bubbles: true, composed: true }))
-  }
-  /** While dragging, the body follows the stand-in; the next evaluation replaces it with where the inputs put it. */
-  private follow = () => {
-    const start = this.dragStart
-    if (!start) return
-    this.proxy.updateMatrix()
-    const delta = this.proxy.matrix.clone().multiply(start.proxy.clone().invert())
-    start.body.matrix.copy(delta.multiply(start.mesh))
-    start.body.matrixWorldNeedsUpdate = true
-    this.group.updateMatrixWorld(true)
-  }
-  private updateGeometry(fit: boolean) {
+    this.teardown()
+    if (!this.parts.length) return
+    this.board = needed
     try {
-      const wasEmpty = this.group.children.length === 0
-      replaceV3Meshes(this.group, this.parts, this.palette)
-      this.contextAtRender = this.context
-      if (fit || wasEmpty) this.fit()
-      this.draw()
+      this.scene = create({
+        target: this.stage,
+        model: {
+          type: 'model-layer',
+          width: needed.width,
+          height: needed.height,
+          depth: needed.depth,
+          threed: true,
+          /* Two samples a pixel: MSAA alone leaves steps on the silhouettes of one asset shown large (V2). */
+          pixelRatio: Math.min(3, (window.devicePixelRatio || 1) * 2),
+          ...sceneLook(this.view ?? DEFAULT_VIEW),
+          gridStep: niceGridStep(Math.max(needed.width, needed.height)),
+          sky: 'color',
+          fillStyle: PAPER,
+          components: this.components()
+        },
+        /* Editing mode: the camera view buttons, gizmo modes, help and keys V2's canvas had. */
+        mode: 1
+      }) as SceneHandle
+      this.standingFor = this.context
+      this.watchScene()
+      this.scene.resize?.()
+      this.fit()
+      this.showSelected()
     } catch (error) {
-      // Do not leave another model's geometry visible after a failed context switch.
-      if (this.contextAtRender !== this.context) {
-        disposeV3Meshes(this.group)
-        this.draw()
-      }
       this.dispatchEvent(new CustomEvent('render-error', { detail: error, bubbles: true, composed: true }))
     }
   }
-  fit() {
-    const bounds = new THREE.Box3().setFromObject(this.group),
-      center = new THREE.Vector3(),
-      size = new THREE.Vector3()
-    if (!bounds.isEmpty()) {
-      bounds.getCenter(center)
-      bounds.getSize(size)
+
+  private components(): Record<string, unknown>[] {
+    return this.parts.map(part => componentOf(part, this.palette, this.board!)).filter((c): c is Record<string, unknown> => !!c)
+  }
+
+  /** The components standing now, by name. Not held between calls: the scene stands its board up again at times. */
+  private standing(): Map<string, SceneComponent> {
+    const found = new Map<string, SceneComponent>()
+    for (const component of this.scene?.root?.components ?? []) {
+      const name = component.state?.name
+      if (typeof name === 'string') found.set(name, component)
     }
-    const radius = Math.max(size.length() / 2, 100),
-      distance = (radius / Math.sin(THREE.MathUtils.degToRad(this.camera.fov / 2))) * 1.3
-    this.camera.position.copy(center).add(new THREE.Vector3(1, 0.8, 1).normalize().multiplyScalar(distance))
-    this.camera.near = Math.max(0.01, distance / 10000)
-    this.camera.far = Math.max(10000, distance * 100)
-    this.camera.updateProjectionMatrix()
-    this.controls?.target.copy(center)
-    this.controls?.update()
-    this.draw()
+    return found
   }
-  /**
-   * The scene's background, taken from the host's computed background — the token resolved and normalised to
-   * `rgb(r, g, b)`, which THREE.Color reads. The token's own text may use the space-separated form it does not.
-   */
-  private paintBackground() {
-    const colour = getComputedStyle(this).backgroundColor
-    if (colour && colour !== 'rgba(0, 0, 0, 0)' && colour !== 'transparent') this.scene.background = new THREE.Color(colour)
+
+  /** Bring the components to the evaluation: remove the gone, write only what differs, add the new. */
+  private sync() {
+    const layer = this.scene?.root
+    if (!layer || !this.board) return
+    const wanted = new Map(this.components().map(c => [c.name as string, c]))
+    const standing = this.standing()
+    this.writing = true
+    try {
+      for (const [name, component] of standing) {
+        if (wanted.has(name)) continue
+        layer.removeComponent?.(component)
+        component.dispose?.()
+      }
+      for (const [name, state] of wanted) {
+        const found = standing.get(name)
+        if (found) {
+          const diff = changedKeys(found.state, state)
+          if (diff) found.set(diff)
+          continue
+        }
+        const made = Model.compile({ ...state }, layer.app as never) as SceneComponent | null
+        if (made) layer.addComponent?.(made)
+      }
+    } finally {
+      this.writing = false
+    }
+    layer.invalidate?.()
   }
-  private draw = () => {
-    if (this.renderer) this.renderer.render(this.scene, this.camera)
+
+  /** Selection and drags, told out by the part's name -- never by its place in the list, which may change meanwhile. */
+  private watchScene() {
+    const layer = this.scene?.root
+    const root = layer?.root
+    if (!layer || !root?.on) return
+    root.on('selected', (after: unknown) => {
+      const name = (after as SceneComponent[] | undefined)?.[0]?.state?.name
+      const id = typeof name === 'string' ? name : ''
+      if (id !== this.selected) this.dispatchEvent(new CustomEvent('part-selected', { detail: id, bubbles: true, composed: true }))
+    })
+    /*
+      A change comes up to the board with the component in the last argument's `origin` (the scene appends
+      { origin, name, deliverer } as it bubbles). Reading the first argument as the component does nothing (V2).
+    */
+    layer.on?.('change', (...args: unknown[]) => {
+      if (this.writing) return
+      const origin = (args[args.length - 1] as { origin?: SceneComponent } | undefined)?.origin
+      const name = origin?.state?.name
+      const part = typeof name === 'string' ? this.parts.find(p => p.id === name) : undefined
+      if (!part || !this.board) return
+      const result = gizmoResultOf(part, origin!.state, this.board)
+      if (!result.position && !result.rotation && !result.scale) return
+      this.dispatchEvent(new CustomEvent('part-transformed', { detail: { id: part.id, result }, bubbles: true, composed: true }))
+      /* After the editor has applied (or refused) it: a refused change springs back to where the inputs put it. */
+      setTimeout(() => this.sync())
+    })
   }
-  private pick = (event: PointerEvent) => {
-    if (this.justDragged || this.transform?.dragging) return
-    const r = (event.currentTarget as HTMLCanvasElement).getBoundingClientRect(),
-      ray = new THREE.Raycaster()
-    ray.setFromCamera(
-      new THREE.Vector2(((event.clientX - r.left) / r.width) * 2 - 1, (-(event.clientY - r.top) / r.height) * 2 + 1),
-      this.camera
-    )
-    const hit = ray.intersectObjects(this.group.children)[0]
-    this.dispatchEvent(
-      new CustomEvent('part-selected', { detail: hit?.object.name ?? '', bubbles: true, composed: true })
-    )
+
+  private showSelected() {
+    const layer = this.scene?.root
+    const root = layer?.root
+    if (!layer || !root) return
+    const component = this.selected ? this.standing().get(this.selected) : undefined
+    const now = root.selected ?? []
+    if ((now[0] ?? undefined) === component && now.length === (component ? 1 : 0)) return
+    root.selected = component ? [component] : []
+    layer.invalidate?.()
   }
-  thumbnail() {
-    this.draw()
-    return this.renderer?.domElement.toDataURL('image/png')
+
+  /** View settings go into the scene as they are: they are the board's own state names. Nothing is stood up again. */
+  private applyView() {
+    const layer = this.scene?.root
+    if (!layer) return
+    layer.set(sceneLook(this.view ?? DEFAULT_VIEW))
+    layer.invalidate?.()
   }
-  disconnectedCallback() {
-    this.observer?.disconnect()
-    this.themeObserver?.disconnect()
-    this.controls?.dispose()
-    this.transform?.detach()
-    this.transform?.dispose()
-    this.transform = undefined
-    disposeV3Meshes(this.group)
-    this.renderer?.dispose()
-    this.renderer = undefined
-    this.scene.clear()
-    this.initialized = false
-    super.disconnectedCallback()
+
+  private teardown() {
+    this.scene?.dispose?.()
+    this.scene = undefined
+    this.standingFor = undefined
+    this.board = undefined
   }
 }

package/client/modeller/v3-clips.ts

@@ -0,0 +1,89 @@
+import { driverValue } from '@hatiolab/figure-model'
+import type { V3Asset, V3Driver, V3InputChange } from '@hatiolab/figure-model'
+
+/*
+ * The figure's clips -- V2's animations: controls played by keys over time, grouped into clips that each run on one
+ * clock. Kept apart from the element so the reading is tested without a browser.
+ */
+export interface ClipKey {
+  seconds: number
+  value: number
+}
+export interface ClipTrack {
+  state: string
+  label: string
+  unit: string
+  min: number
+  max: number
+  keys: ClipKey[]
+  interpolation: 'linear' | 'step'
+  loop: 'wrap' | 'hold'
+  accumulates: boolean
+}
+export interface Clip {
+  name: string
+  duration: number
+  tracks: ClipTrack[]
+}
+
+const round = (n: number) => Math.round(n * 1000) / 1000
+
+export function clipsOf(asset: V3Asset): Clip[] {
+  const inputs = new Map(asset.document.model.inputs.map(i => [i.id, i]))
+  const clips = new Map<string, Clip>()
+  for (const d of asset.drivers ?? []) {
+    const input = inputs.get(d.state)
+    const clip = clips.get(d.clip) ?? { name: d.clip, duration: d.time.duration, tracks: [] }
+    clip.tracks.push({
+      state: d.state,
+      label: asset.stateInputs?.[d.state]?.label ?? d.state,
+      unit: input?.unit ?? '',
+      min: input?.min ?? 0,
+      max: input?.max ?? 0,
+      keys: d.keys.map(k => ({ seconds: round(k.at * d.time.duration), value: k.value })),
+      interpolation: d.interpolation,
+      loop: d.loop,
+      accumulates: d.accumulates
+    })
+    clips.set(d.clip, 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: V3Asset): 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 pose a clip gives at a moment, as one batch of state changes -- one step of the history. */
+export function poseAt(asset: V3Asset, clip: string, seconds: number): V3InputChange[] {
+  const units = new Map(asset.document.model.inputs.map(i => [i.id, i.unit]))
+  return (asset.drivers ?? [])
+    .filter((d: V3Driver) => d.clip === clip)
+    .map(d => {
+      const unit = units.get(d.state)!
+      return { kind: 'set-state' as const, input: d.state, unit, value: driverValue(d, seconds, unit === 'deg' || unit === 'rad' ? unit : 'other') }
+    })
+}
+
+/** A key added at a moment, replacing one already there; the keys stay in time order. */
+export function withKey(keys: readonly ClipKey[], key: ClipKey): ClipKey[] {
+  return [...keys.filter(k => k.seconds !== key.seconds), key].sort((a, b) => a.seconds - b.seconds)
+}
+
+/** A track's keys without one; a track keeps at least its two ends, as the format asks. */
+export function withoutKey(keys: readonly ClipKey[], index: number): ClipKey[] | null {
+  if (keys.length <= 2 || index === 0) return null
+  return keys.filter((_, i) => i !== index)
+}
+
+/** The edit that writes a track back. */
+export const trackEdit = (clip: Clip, track: ClipTrack, patch: Partial<Pick<ClipTrack, 'keys' | 'loop' | 'interpolation'>> = {}) => ({
+  kind: 'set-driver' as const,
+  state: track.state,
+  clip: clip.name,
+  keys: patch.keys ?? track.keys,
+  loop: patch.loop ?? track.loop,
+  interpolation: patch.interpolation ?? track.interpolation
+})