@things-factory/figure-ui 10.1.5 → 10.1.7

package/client/modeller/figure-animations.ts

@@ -0,0 +1,712 @@
+import { css, html, LitElement, nothing, type TemplateResult } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { live } from 'lit/directives/live.js'
+
+import { i18next, localize } from '@operato/i18n'
+import { ScrollbarStyles } from '@operato/styles'
+
+import { AXES, CHANNEL_PATHS, CLIP_DRIVES, INTERPOLATIONS, LIMITS } from '@hatiolab/figure-model'
+import type { ChannelPath, Vec3 } from '@hatiolab/figure-model'
+
+import type { BoardModel, PartModel } from './figure-source.js'
+
+/**
+ * 이 도형이 **어떻게 움직이는가.**
+ *
+ * ## 왜 탭 하나가 필요한가
+ *
+ * 움직임은 형식에 있고 런타임까지 서 있었다 — 검증이 촘촘히 보고, 청사진이 움직이는 부품을
+ * 단독 묶음으로 빼고(합치면 따로 못 움직인다), 씬이 frameClock 을 구독해 실제로 돌린다.
+ * 미리보기에도 clip 마다 슬라이더가 있었다.
+ *
+ * **만들 자리만 없었다.** 그래서 움직이는 도형을 얻는 길이 「AI 가 후보로 내놓는 것」 하나였고,
+ * 채널 하나를 고치려면 손댈 화면이 없었다.
+ *
+ * ## 부품이 아니라 도형의 것이다
+ *
+ * clip 하나가 부품 여럿을 함께 움직인다 — 문 열림은 왼짝과 오른짝이 반대로 미끄러지는 것
+ * 하나다. 그래서 부품을 고르고 「이 부품의 움직임」을 적는 형태가 될 수 없고, 속성 탭이 아니라
+ * 자기 탭에 산다.
+ *
+ * ## 트윈은 타임라인을 재생하지 않는다
+ *
+ * 「문 열기 clip 을 재생하라」가 아니라 **「지금 40% 열려 있다」**다. 그래서 clip 마다 그 값을
+ * 어떻게 받을지(`drive`)를 저작 시점에 정한다 — 도는 롤러는 배속을 받고, 열린 문은 0~1 위치를
+ * 받는다. 이 선택이 화면에서 가장 설명이 필요한 자리다.
+ */
+
+type Clip = NonNullable<BoardModel['animations']>[number]
+type Channel = Clip['channels'][number]
+type Keyframe = Channel['keys'][number]
+
+/** 새 clip 의 키 둘. **하나로 만들지 않는다** — 키 하나는 움직임이 아니라 자세다. */
+const NEW_KEYS: Keyframe[] = [
+  { at: 0, value: { x: 0, y: 0, z: 0 } },
+  { at: 1, value: { x: 0, y: 0, z: 0 } }
+]
+
+/** `scale` 만 1 에서 시작한다 — 0 은 부품을 지운다. */
+function startValue(path: ChannelPath): Vec3 {
+  return path === 'scale' ? { x: 1, y: 1, z: 1 } : { x: 0, y: 0, z: 0 }
+}
+
+function keysFor(path: ChannelPath): Keyframe[] {
+  return NEW_KEYS.map(key => ({ at: key.at, value: startValue(path) }))
+}
+
+/** 이미 쓴 이름을 비켜 간다. `type` 처럼 저장되는 식별자는 아니지만 인스턴스가 이 이름으로 구동한다. */
+function freeName(taken: readonly Clip[]): string {
+  const used = new Set(taken.map(clip => clip.name))
+  for (let n = 1; ; n++) {
+    const name = `clip-${n}`
+    if (!used.has(name)) return name
+  }
+}
+
+@customElement('figure-animations')
+export class FigureAnimations extends localize(i18next)(LitElement) {
+  static styles = [
+    ScrollbarStyles,
+    css`
+      :host {
+        display: flex;
+        flex-direction: column;
+        min-height: 0;
+        overflow-y: auto;
+        background-color: var(--md-sys-color-surface-container-lowest);
+        color: var(--md-sys-color-on-surface);
+        font: var(--label-font, inherit);
+        font-size: 0.76rem;
+      }
+
+      section {
+        display: flex;
+        flex-direction: column;
+        gap: var(--spacing-medium, 8px);
+        padding: var(--spacing-large, 12px);
+        border-bottom: 1px solid var(--md-sys-color-outline-variant);
+      }
+
+      /* 다른 탭들과 같은 눈금이다 */
+      h3 {
+        margin: 0 0 2px 0;
+        font-size: var(--ui-t-micro, 11px);
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+        color: var(--md-sys-color-on-surface-variant, var(--md-sys-color-on-surface));
+      }
+
+      p[quiet] {
+        margin: 0;
+        font-size: 0.72rem;
+        line-height: 1.5;
+        color: var(--md-sys-color-on-surface-variant);
+      }
+
+      /* ── clip ─────────────────────────────────────────────────────── */
+
+      div[clip] {
+        display: flex;
+        flex-direction: column;
+        gap: var(--spacing-medium, 8px);
+        padding: 8px;
+        border: 1px solid var(--md-sys-color-outline-variant);
+        border-radius: 4px;
+      }
+      div[clip][on] {
+        border-color: var(--md-sys-color-primary);
+        background-color: var(--md-sys-color-surface-container-low);
+      }
+
+      div[head] {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+      div[head] input[name] {
+        flex: 1;
+        min-width: 0;
+      }
+
+      /* ── channel ──────────────────────────────────────────────────── */
+
+      div[channel] {
+        display: flex;
+        flex-direction: column;
+        gap: 6px;
+        padding: 6px 8px;
+        border-left: 2px solid var(--md-sys-color-outline-variant);
+        background-color: var(--md-sys-color-surface-container-lowest);
+      }
+      div[channel][orphan] {
+        border-left-color: var(--md-sys-color-error);
+      }
+
+      div[row] {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+      div[row] > label {
+        flex: none;
+        min-width: 3.2em;
+        color: var(--md-sys-color-on-surface-variant);
+      }
+
+      /* ── keyframe ─────────────────────────────────────────────────── */
+
+      table[keys] {
+        width: 100%;
+        border-collapse: collapse;
+      }
+      table[keys] th {
+        padding: 0 2px 2px;
+        font-size: 0.68rem;
+        font-weight: 600;
+        text-align: left;
+        color: var(--md-sys-color-on-surface-variant);
+      }
+      table[keys] td {
+        padding: 1px 2px;
+      }
+      table[keys] input {
+        width: 100%;
+        min-width: 0;
+      }
+      table[keys] td[drop] {
+        width: 1.6em;
+      }
+
+      input,
+      select {
+        box-sizing: border-box;
+        padding: 3px 5px;
+        font: inherit;
+        font-size: 0.74rem;
+        color: var(--md-sys-color-on-surface);
+        background-color: var(--md-sys-color-surface-container-lowest);
+        border: 1px solid var(--md-sys-color-outline-variant);
+        border-radius: 3px;
+      }
+      input:focus,
+      select:focus {
+        outline: none;
+        border-color: var(--md-sys-color-primary);
+      }
+      input[bad] {
+        border-color: var(--md-sys-color-error);
+      }
+
+      button {
+        display: inline-flex;
+        align-items: center;
+        gap: 3px;
+        padding: 3px 8px;
+        font: inherit;
+        font-size: 0.72rem;
+        color: var(--md-sys-color-on-surface);
+        background-color: var(--md-sys-color-surface-container);
+        border: 1px solid var(--md-sys-color-outline-variant);
+        border-radius: 3px;
+        cursor: pointer;
+      }
+      button:hover:not(:disabled) {
+        background-color: var(--md-sys-color-surface-container-high);
+      }
+      button:disabled {
+        opacity: 0.4;
+        cursor: default;
+      }
+      button[plain] {
+        padding: 1px 4px;
+        background: none;
+        border: none;
+        color: var(--md-sys-color-on-surface-variant);
+      }
+      button[plain]:hover:not(:disabled) {
+        color: var(--md-sys-color-error);
+        background: none;
+      }
+      button md-icon {
+        font-size: 14px;
+        width: 14px;
+        height: 14px;
+      }
+
+      /* ── 예산 ─────────────────────────────────────────────────────── */
+
+      div[budget] {
+        display: flex;
+        align-items: baseline;
+        gap: 6px;
+      }
+      div[budget] strong {
+        font-size: 0.86rem;
+        font-weight: 700;
+      }
+      div[budget][over] strong {
+        color: var(--md-sys-color-error);
+      }
+
+      p[warn] {
+        margin: 0;
+        font-size: 0.7rem;
+        line-height: 1.5;
+        color: var(--md-sys-color-error);
+      }
+    `
+  ]
+
+  @property({ type: Object }) board?: BoardModel
+  @property({ type: Array }) parts: PartModel[] = []
+
+  /** 펼쳐 둔 clip. 이름이 아니라 자리로 잡는다 — 이름은 편집 중에 바뀐다. */
+  @state() private open = 0
+
+  private get clips(): Clip[] {
+    return this.board?.animations ?? []
+  }
+
+  /** 부품 이름 — 채널이 이것을 가리킨다. */
+  private get partNames(): string[] {
+    return this.parts.map(part => part.name).filter(name => !!name)
+  }
+
+  /**
+   * 몇 부품이 움직이나 — 채널이 가리키는 **서로 다른 부품**의 수.
+   *
+   * clip 수가 아니다. 한 부품을 세 clip 이 움직여도 그 부품 하나가 단독 묶음이 될 뿐이다.
+   * 청사진이 묶음을 가르는 기준과 같은 셈이어야 화면의 수와 판정의 수가 맞는다.
+   */
+  private get movingParts(): number {
+    const moving = new Set<string>()
+    for (const clip of this.clips) for (const channel of clip.channels) moving.add(channel.target)
+    return moving.size
+  }
+
+  render(): TemplateResult {
+    if (!this.board) return html``
+
+    return html`
+      <section>
+        <h3>${i18next.t('figure.label.animation')}</h3>
+        <p quiet>${i18next.t('figure.text.animation-is-driven-by-a-fact')}</p>
+      </section>
+
+      ${this.clips.length === 0 ? this.renderEmpty() : this.renderClips()}
+
+      <section>
+        <button @click=${() => this.addClip()} ?disabled=${this.partNames.length === 0}>
+          <md-icon>add</md-icon>${i18next.t('figure.button.add-clip')}
+        </button>
+        ${this.partNames.length === 0
+          ? html`<p quiet>${i18next.t('figure.text.animation-needs-a-named-part')}</p>`
+          : nothing}
+      </section>
+
+      ${this.clips.length === 0 ? nothing : this.renderBudget()}
+    `
+  }
+
+  /**
+   * 빈 화면 — **이 탭이 무엇인지 가르치는 자리다.**
+   *
+   * 「clip 을 추가하세요」라고만 쓰면 처음 여는 사람은 clip 이 무엇인지 모른 채 단추를 누른다.
+   * 그래서 무엇을 만들 수 있는지 예를 들고, 그것이 어떻게 움직이는지(사실이 들어온다)를 적는다.
+   */
+  private renderEmpty(): TemplateResult {
+    return html`
+      <section>
+        <p quiet>${i18next.t('figure.text.animation-empty-what-it-is')}</p>
+        <p quiet>${i18next.t('figure.text.animation-empty-examples')}</p>
+      </section>
+    `
+  }
+
+  private renderClips(): TemplateResult {
+    return html`
+      <section>
+        ${this.clips.map((clip, at) => this.renderClip(clip, at))}
+      </section>
+    `
+  }
+
+  private renderClip(clip: Clip, at: number): TemplateResult {
+    const on = this.open === at
+    const duplicate = this.clips.some((other, i) => i !== at && other.name === clip.name)
+    const nameless = !clip.name?.trim()
+
+    return html`
+      <div clip ?on=${on}>
+        <div head>
+          <button plain @click=${() => (this.open = on ? -1 : at)} title=${i18next.t('figure.label.channels')}>
+            <md-icon>${on ? 'expand_more' : 'chevron_right'}</md-icon>
+          </button>
+          <input
+            name
+            .value=${live(clip.name ?? '')}
+            ?bad=${duplicate || nameless}
+            placeholder=${i18next.t('figure.label.clip-name')}
+            title=${duplicate ? i18next.t('figure.text.clip-name-taken') : i18next.t('figure.text.clip-name-is-how-it-is-driven')}
+            @change=${(e: Event) => this.renameClip(at, (e.target as HTMLInputElement).value)}
+          />
+          <select
+            .value=${live(clip.drive ?? 'loop')}
+            title=${i18next.t('figure.text.drive-explained')}
+            @change=${(e: Event) => this.setDrive(at, (e.target as HTMLSelectElement).value as Clip['drive'])}
+          >
+            ${CLIP_DRIVES.map(
+              drive => html`<option value=${drive}>${i18next.t('figure.label.drive-' + drive)}</option>`
+            )}
+          </select>
+          <button plain @click=${() => this.removeClip(at)} title=${i18next.t('figure.button.remove')}>
+            <md-icon>close</md-icon>
+          </button>
+        </div>
+
+        ${duplicate ? html`<p warn>${i18next.t('figure.text.clip-name-taken')}</p>` : nothing}
+        ${nameless ? html`<p warn>${i18next.t('figure.text.clip-needs-a-name')}</p>` : nothing}
+        ${on ? this.renderChannels(clip, at) : nothing}
+      </div>
+    `
+  }
+
+  private renderChannels(clip: Clip, at: number): TemplateResult {
+    return html`
+      <p quiet>${i18next.t('figure.text.drive-' + (clip.drive ?? 'loop') + '-note')}</p>
+
+      ${clip.channels.length === 0 ? html`<p warn>${i18next.t('figure.text.clip-needs-a-channel')}</p>` : nothing}
+      ${clip.channels.map((channel, j) => this.renderChannel(channel, at, j))}
+
+      <button @click=${() => this.addChannel(at)}>
+        <md-icon>add</md-icon>${i18next.t('figure.button.add-channel')}
+      </button>
+    `
+  }
+
+  /**
+   * 채널 하나 — 어느 부품의 어느 속성을 움직이나.
+   *
+   * 없는 부품을 가리키는 채널은 붉게 낸다. 부품 이름을 바꾸면 그 순간 이렇게 되는데,
+   * 검증은 저장할 때 말하고 여기서는 **그 자리에서** 보여 준다.
+   */
+  private renderChannel(channel: Channel, at: number, j: number): TemplateResult {
+    const orphan = !this.partNames.includes(channel.target)
+    const turning = channel.path === 'rotation'
+
+    return html`
+      <div channel ?orphan=${orphan}>
+        <div row>
+          <label>${i18next.t('figure.label.channel-target')}</label>
+          <select
+            .value=${live(channel.target ?? '')}
+            @change=${(e: Event) => this.setChannel(at, j, { target: (e.target as HTMLSelectElement).value })}
+          >
+            ${orphan ? html`<option value=${channel.target}>${channel.target}</option>` : nothing}
+            ${this.partNames.map(name => html`<option value=${name}>${name}</option>`)}
+          </select>
+          <button plain @click=${() => this.removeChannel(at, j)} title=${i18next.t('figure.button.remove')}>
+            <md-icon>close</md-icon>
+          </button>
+        </div>
+
+        ${orphan ? html`<p warn>${i18next.t('figure.text.channel-target-is-gone')}</p>` : nothing}
+
+        <div row>
+          <label>${i18next.t('figure.label.channel-path')}</label>
+          <select
+            .value=${live(channel.path)}
+            @change=${(e: Event) => this.setPath(at, j, (e.target as HTMLSelectElement).value as ChannelPath)}
+          >
+            ${CHANNEL_PATHS.map(path => html`<option value=${path}>${i18next.t('figure.label.path-' + path)}</option>`)}
+          </select>
+          <select
+            .value=${live(channel.interpolation ?? 'linear')}
+            title=${i18next.t('figure.text.interpolation-explained')}
+            @change=${(e: Event) =>
+              this.setChannel(at, j, { interpolation: (e.target as HTMLSelectElement).value as Channel['interpolation'] })}
+          >
+            ${INTERPOLATIONS.map(
+              one => html`<option value=${one}>${i18next.t('figure.label.interpolation-' + one)}</option>`
+            )}
+          </select>
+        </div>
+
+        <p quiet>${i18next.t('figure.text.path-' + channel.path + '-unit')}</p>
+
+        ${turning ? this.renderPivot(channel, at, j) : nothing}
+        ${this.renderKeys(channel, at, j)}
+      </div>
+    `
+  }
+
+  /**
+   * 회전 중심 — **`rotation` 에서만 뜻이 있다.**
+   *
+   * 그래서 경로가 rotation 일 때만 낸다. 언제나 내면 저작자가 옮김·배율에도 적고, 검증이
+   * 저장할 때 「쓰이지 않는다」고 알린다. 안 보이면 적을 일이 없다.
+   */
+  private renderPivot(channel: Channel, at: number, j: number): TemplateResult {
+    const pivot = channel.pivot
+    const on = pivot !== undefined
+
+    return html`
+      <div row>
+        <label>${i18next.t('figure.label.channel-pivot')}</label>
+        <button
+          @click=${() => this.setChannel(at, j, { pivot: on ? undefined : { x: 0, y: 0, z: 0 } })}
+          title=${i18next.t('figure.text.pivot-defaults-to-the-part-centre')}
+        >
+          ${i18next.t(on ? 'figure.button.pivot-clear' : 'figure.button.pivot-set')}
+        </button>
+        ${on
+          ? AXES.map(
+              axis => html`
+                <input
+                  type="number"
+                  step="1"
+                  .value=${live(String(pivot![axis]))}
+                  aria-label=${axis}
+                  @change=${(e: Event) =>
+                    this.setChannel(at, j, {
+                      pivot: { ...pivot!, [axis]: Number((e.target as HTMLInputElement).value) || 0 }
+                    })}
+                />
+              `
+            )
+          : nothing}
+      </div>
+    `
+  }
+
+  /**
+   * 키프레임 표.
+   *
+   * **둘 미만으로 못 내려간다.** 하나뿐이면 움직이는 것이 아니라 자세 하나이고, 형식이
+   * 오류로 막는다. 저장하고 나서 알려 주는 것보다 지우는 단추를 죽이는 것이 낫다.
+   *
+   * 시각이 오름차순이어야 하는 것도 형식의 규칙이다. 여기서는 어긋난 줄을 붉게 내고 값을
+   * 고치지는 않는다 — 저작자가 3 을 1 로 고치던 중일 수 있다.
+   */
+  private renderKeys(channel: Channel, at: number, j: number): TemplateResult {
+    const keys = channel.keys ?? []
+
+    return html`
+      <table keys>
+        <tr>
+          <th>${i18next.t('figure.label.key-at')}</th>
+          ${AXES.map(axis => html`<th>${axis}</th>`)}
+          <th></th>
+        </tr>
+        ${keys.map((key, k) => {
+          const backwards = k > 0 && key.at <= (keys[k - 1]!.at ?? 0)
+          return html`
+            <tr>
+              <td>
+                <input
+                  type="number"
+                  step="0.1"
+                  min="0"
+                  ?bad=${backwards || key.at < 0}
+                  .value=${live(String(key.at))}
+                  title=${backwards ? i18next.t('figure.text.keys-must-rise') : ''}
+                  @change=${(e: Event) =>
+                    this.setKey(at, j, k, { at: Math.max(0, Number((e.target as HTMLInputElement).value) || 0) })}
+                />
+              </td>
+              ${AXES.map(
+                axis => html`
+                  <td>
+                    <input
+                      type="number"
+                      step=${channel.path === 'scale' ? '0.1' : '1'}
+                      .value=${live(String(key.value[axis]))}
+                      aria-label=${axis}
+                      @change=${(e: Event) =>
+                        this.setKey(at, j, k, {
+                          value: { ...key.value, [axis]: Number((e.target as HTMLInputElement).value) || 0 }
+                        })}
+                    />
+                  </td>
+                `
+              )}
+              <td drop>
+                <button
+                  plain
+                  ?disabled=${keys.length <= 2}
+                  title=${keys.length <= 2 ? i18next.t('figure.text.two-keys-at-least') : i18next.t('figure.button.remove')}
+                  @click=${() => this.removeKey(at, j, k)}
+                >
+                  <md-icon>close</md-icon>
+                </button>
+              </td>
+            </tr>
+          `
+        })}
+      </table>
+
+      ${keys.some((key, k) => k > 0 && key.at <= (keys[k - 1]!.at ?? 0))
+        ? html`<p warn>${i18next.t('figure.text.keys-must-rise')}</p>`
+        : nothing}
+
+      <button @click=${() => this.addKey(at, j)}>
+        <md-icon>add</md-icon>${i18next.t('figure.button.add-key')}
+      </button>
+    `
+  }
+
+  /**
+   * 움직이는 부품 예산.
+   *
+   * **넘어도 막지 않는다.** 움직이는 부품은 저마다 단독 묶음이라 draw call 이 늘고 프레임마다
+   * 갱신이 는다 — 그 대가가 수로 보이면 저작자가 아낀다. 랜드마크 설비 하나는 정교해도 되고,
+   * 그 값이 도면 예산에 드러나면 된다.
+   */
+  private renderBudget(): TemplateResult {
+    const used = this.movingParts
+    const over = used > LIMITS.animatedParts
+
+    return html`
+      <section>
+        <h3>${i18next.t('figure.label.budget-animations')}</h3>
+        <div budget ?over=${over}>
+          <strong>${used}</strong>
+          <span quiet>/ ${LIMITS.animatedParts}</span>
+        </div>
+        <p quiet>${i18next.t('figure.text.animated-parts-cost')}</p>
+        ${over ? html`<p warn>${i18next.t('figure.text.animated-parts-over')}</p>` : nothing}
+      </section>
+    `
+  }
+
+  // ─── 고치기 ───────────────────────────────────────────────────────────────
+
+  /**
+   * 보드에 실어 올려보낸다.
+   *
+   * `animations` 는 도형 전체의 것이므로 부품 편집(`update-part`)이 아니라 `update-board` 로
+   * 간다. 빈 배열은 칸을 지운다 — clip 을 다 지운 도형은 `animations: []` 가 아니라 없는 것이다.
+   */
+  private tell(animations: Clip[]): void {
+    if (!this.board) return
+
+    const board: BoardModel = { ...this.board }
+    if (animations.length === 0) delete board.animations
+    else board.animations = animations
+
+    this.dispatchEvent(new CustomEvent('update-board', { detail: { board }, bubbles: true, composed: true }))
+  }
+
+  private patchClip(at: number, patch: Partial<Clip>): void {
+    this.tell(this.clips.map((clip, i) => (i === at ? { ...clip, ...patch } : clip)))
+  }
+
+  private patchChannel(at: number, j: number, next: Channel): void {
+    const clip = this.clips[at]
+    if (!clip) return
+    this.patchClip(at, { channels: clip.channels.map((channel, i) => (i === j ? next : channel)) })
+  }
+
+  private addClip(): void {
+    const target = this.partNames[0]
+    if (!target) return
+
+    const clip: Clip = {
+      name: freeName(this.clips),
+      drive: 'loop',
+      channels: [{ target, path: 'translation', keys: keysFor('translation') }]
+    }
+
+    this.open = this.clips.length
+    this.tell([...this.clips, clip])
+  }
+
+  private renameClip(at: number, name: string): void {
+    this.patchClip(at, { name: name.trim() })
+  }
+
+  private setDrive(at: number, drive: Clip['drive']): void {
+    this.patchClip(at, { drive })
+  }
+
+  private removeClip(at: number): void {
+    if (this.open >= at) this.open = Math.max(0, this.open - 1)
+    this.tell(this.clips.filter((_, i) => i !== at))
+  }
+
+  private addChannel(at: number): void {
+    const clip = this.clips[at]
+    const target = this.partNames[0]
+    if (!clip || !target) return
+
+    this.patchClip(at, {
+      channels: [...clip.channels, { target, path: 'translation', keys: keysFor('translation') }]
+    })
+  }
+
+  private setChannel(at: number, j: number, patch: Partial<Channel>): void {
+    const channel = this.clips[at]?.channels[j]
+    if (!channel) return
+
+    const next: Channel = { ...channel, ...patch }
+    /* `undefined` 를 얹는 것은 지우는 뜻이다. 남겨 두면 저장 형식에 빈 칸이 실린다. */
+    if ('pivot' in patch && patch.pivot === undefined) delete next.pivot
+    this.patchChannel(at, j, next)
+  }
+
+  /**
+   * 경로를 바꾼다 — **값까지 함께 옮긴다.**
+   *
+   * 옮김·회전의 0 은 「제자리」인데 배율의 0 은 **부품을 지운다.** 경로만 바꾸고 값을 그대로
+   * 두면 저작자는 부품이 사라진 것을 보고 도구가 고장 난 줄 안다. 그래서 옮김·회전 ↔ 배율을
+   * 건널 때 시작값을 그 경로의 제자리로 되돌린다. 시각은 지킨다 — 저작자가 짠 박자다.
+   */
+  private setPath(at: number, j: number, path: ChannelPath): void {
+    const channel = this.clips[at]?.channels[j]
+    if (!channel) return
+
+    const crossing = (channel.path === 'scale') !== (path === 'scale')
+    const next: Channel = {
+      ...channel,
+      path,
+      keys: crossing ? channel.keys.map(key => ({ at: key.at, value: startValue(path) })) : channel.keys
+    }
+    /* 회전이 아니면 회전 중심은 쓰이지 않는다. 남겨 두면 검증이 「쓰이지 않는다」고 알린다. */
+    if (path !== 'rotation') delete next.pivot
+
+    this.patchChannel(at, j, next)
+  }
+
+  private removeChannel(at: number, j: number): void {
+    const clip = this.clips[at]
+    if (!clip) return
+    this.patchClip(at, { channels: clip.channels.filter((_, i) => i !== j) })
+  }
+
+  /** 마지막 키에서 1 초 뒤. 값은 그 키를 그대로 받는다 — 붙여 놓고 고치는 것이 짜기 쉽다. */
+  private addKey(at: number, j: number): void {
+    const channel = this.clips[at]?.channels[j]
+    if (!channel) return
+
+    const last = channel.keys[channel.keys.length - 1]
+    const key: Keyframe = { at: (last?.at ?? 0) + 1, value: { ...(last?.value ?? startValue(channel.path)) } }
+    this.patchChannel(at, j, { ...channel, keys: [...channel.keys, key] })
+  }
+
+  private setKey(at: number, j: number, k: number, patch: Partial<Keyframe>): void {
+    const channel = this.clips[at]?.channels[j]
+    if (!channel) return
+    this.patchChannel(at, j, {
+      ...channel,
+      keys: channel.keys.map((key, i) => (i === k ? { ...key, ...patch } : key))
+    })
+  }
+
+  /** 둘 미만으로 내려가지 않는다 — 단추가 이미 죽어 있지만 밖에서 불릴 수 있다. */
+  private removeKey(at: number, j: number, k: number): void {
+    const channel = this.clips[at]?.channels[j]
+    if (!channel || channel.keys.length <= 2) return
+    this.patchChannel(at, j, { ...channel, keys: channel.keys.filter((_, i) => i !== k) })
+  }
+}