# #122 KeyFrame 操作ガイド

## 0. 文書情報
- UI ID: `UI-122`
- DOC ID: `DOC-0122`
- Component: `#122 KeyFrame`
- Runtime: `BoneKeyFrame 1.0.0`
- Status: Development Candidate

このガイドは #122 KeyFrame の通常利用、Property、Preview、接続、Security、OUT WAIT / BLOCKED、Smoke / Validation、HTML Functional Class を説明します。

## 1. KeyFrameの役割
#122 KeyFrameは、Animationの進行上にある**各地点の状態**を定義・保持します。正式状態は次の5種類です。

- **Position** — X / Y位置
- **Rotation** — 回転角度
- **Scale** — 拡大・縮小率
- **Opacity** — 透明度
- **Color** — 色

#122自身はAnimationを再生しません。また、状態間を補間したり、何秒かけるかを決めたりしません。

## 2. どんな時に使うか
開始状態と終了状態だけでは足りず、途中の動きを細かく作り込みたい時に使います。

例: 白から赤へ2秒かけて徐々に変化させる場合は、役割を次のように分けます。

- #121 Timeline: `Duration = 2秒`
- #122 KeyFrame: `0% = 白`、`100% = 赤`
- #118 Transition: 白から赤までの中間状態を補間

さらに途中を指定する場合は `0% = 白 / 50% = ピンク / 100% = 赤` のようにKeyFrameを追加します。

## 3. Component責務境界
### #117 Animation
Animationそのものの動作・再生を担当します。

### #118 Transition
KeyFrame間の状態変化・補間を担当します。

### #121 Timeline
Delay / Duration / Loop / Repeat / Sequence / Parallelを担当します。

### #122 KeyFrame
各%地点のPosition / Rotation / Scale / Opacity / Colorだけを定義・保持します。

`何秒後` や `Duration` を #122 のPropertyへ追加しません。

## 4. Property Editor
Property Editorは画面左側です。右側のPreviewと一対で使用します。

### 4.1 プロパティ言語
Property上部の **日本語 / English** で、Property内の見出し・ラベル・説明・Previewラベルを切り替えます。値そのものは言語切替で変更されません。

### 4.2 時点（%）
`0`〜`100` の範囲で指定します。Animation全体の進行率上の地点であり、秒数ではありません。

例: #121 TimelineのDurationが4秒なら、#122の50%は結果的に開始2秒後の状態です。

### 4.3 Position
`X` / `Y` を指定します。各値はそのKeyFrame地点での位置です。

### 4.4 Rotation
回転角度をdegで指定します。

### 4.5 Scale
拡大・縮小率を指定します。`1` が等倍です。

### 4.6 Opacity
`0`〜`1` で指定します。`0` は完全透明、`1` は完全不透明です。

### 4.7 Color
色は #040 ColorPicker Runtime 1.0.18 のCallerから選択します。Caller表示に必要な #118 BoneTransition Runtime 1.0.3 は#040の依存として読み込みます。これは#122が補間責務を持つという意味ではありません。#122が独自ColorPickerを持つことはありません。

### 4.8 KeyFrame保存 / 削除
**KeyFrame保存**は現在のProperty値を指定%地点へ保存します。同じ%地点を保存した場合はその地点を更新します。

**KeyFrame削除**は現在指定している%地点を削除します。

## 5. 合算プレビュー
右側の合算プレビューは、選択したKeyFrame 1点の状態だけを表示します。

確認できる内容:
- Offset
- Position
- Rotation / Scale
- Opacity
- Color
- KeyFrame総数
- 選択状態の安全なデータ

Previewには再生ボタンを置きません。Animation再生は#117、時間制御は#121、補間は#118の責務だからです。

## 6. 接続イメージ
接続イメージは #017 Text と同じ正常系・異常系の構成で表示します。判定・線・端点・異常マーカーは #002 Bone Joint 1.1.36 の公開APIを使用し、#122独自のJoint表現を作りません。

表示する5ケース:
1. 正常接続（IN / OUT） — `Timeline.progress (Number) -> KeyFrame.offset (Number)` と `KeyFrame.state (Object) -> Animation.state (Object)`。
2. IN Target Field不存在 — `Timeline.progress -> KeyFrame.missing`。#002公式の不存在表示を使用します。
3. OUT Target Field不存在 — `KeyFrame.state -> Animation.missing`。#002公式の不存在表示を使用します。
4. 型不一致（IN） — `Timeline.progress (Number) -> KeyFrame.color (String)`。
5. 型不一致（OUT） — `KeyFrame.color (String) -> Animation.progress (Number)`。

各カードには Source Field Exists / Target Field Exists / Compatibility / Joint State を表示し、色だけではなく診断値でも正常・異常を確認できます。

## 7. Untrusted IN / Security Test
Security Testでは次を確認します。

- getter / setterを持つPropertyを実行せず拒否
- Offset範囲外を拒否
- Position範囲外を拒否
- Scale範囲外を拒否
- Opacity範囲外を拒否
- 重複Offsetを拒否
- 実行可能値を含む不正Colorデータを拒否
- Security失敗時に既存Previewを破壊しない

## 8. OUT WAIT / BLOCKED - #002 Joint v1.1.36 Integration
この領域は #017 Text の正式な OUT WAIT / BLOCKED 構成を基準にし、#002 Bone Joint 1.1.36 の `createDeliveryChannel()` / `evaluate()` / `drawLine()` を使用します。独自のWAIT spinner、BLOCKED icon、独自Joint線は作りません。

画面は単一の横長カードで、`KeyFrame OUT` から `Target` までを #002 Joint で接続します。その下に `Joint State` / `Target` / `Queue` / `Delivered` の4項目、1行ログ、2つの目視確認を表示します。操作は次の3つだけです。

- `▶ WAIT / FIFO 実行`
- `⛔ BLOCKED 実行`
- `↻ Reset`

Target READY/BUSYの手動selector、Payload A/B selector、独立FIFOボタンは置きません。

2つの目視確認チェックは独立して保持します。WAIT/FIFO確認済みのチェックはBLOCKEDテストへ切り替えても解除せず、BLOCKED確認済みのチェックもWAIT/FIFOテストへ切り替えても解除しません。両方を明示的に初期化する操作は `↻ Reset` です。

### WAIT → READY → FIFO
WAITテストではTargetをBUSYにし、AとBを投入順にQueueへ保持します。WAIT中も接続は維持され、Target端には #002正式 spinner が表示されます。目視時間の後にTargetをREADYへ戻すと、A → B のFIFO順で自動配送され、Queueは0へ戻ります。この目視用待機時間はテストUIの確認時間であり、#122 KeyFrameのPropertyや時間責務ではありません。

### BLOCKED
BLOCKEDテストではGuardが配送を拒否します。接続自体は維持し、Target端には #002正式 ban marker / beat-fade を表示します。Targetへの配送は行わず、Deliveredは0のままです。

`createDeliveryChannel().getState()` は `state` / `targetReady` / `queueLength` / `historyLength` を確認するために使用します。接続維持の `connectionEstablished` は Delivery Channel state から捏造せず、`BoneJoint.evaluate(... state:"waiting" / "blocked")` で別途確認します。

表示前後関係は Joint line = z-index 1、Source / Target node = z-index 2、#002正式WAIT/BLOCKED marker = z-index 3 とします。

## 9. Smoke Test / Validation Report
画面のテスト領域は #017 Text と同じ構成で、Smoke TestとValidationを分離して表示します。

- **Smoke Test**: Runtime、正式状態5種、Functional Class、#002、#040、Connection、WAIT/FIFO、BLOCKED、Security、Preview、Property言語切替、DOC導線を確認
- **Validation**: 範囲外値、重複Offset、getter、安全性、責務越境、Property構造、Completion構造、重複ID等を確認

JSON / Markdownのレポート保存ができます。

## 10. Completion
Package内テストだけではCompletedにしません。次のすべてが必要です。

1. Smoke Test成功
2. Validation成功
3. KeyFrame Property / Previewをlocalhostで目視確認
4. #002 Joint正常系・異常系Connection Imageをlocalhostで目視確認
5. WAIT → READY → FIFO配送をlocalhostで目視確認
6. BLOCKEDでTarget不達をlocalhostで目視確認
7. #040 ColorPicker Callerをlocalhostで目視確認

ユーザー確認前にCompleted / Specification Frozenとは扱いません。

## 11. HTML Functional Class
通常利用ClassはDevelopment Candidateとして `bf-keyframe` を使用します。

```html
<div class="bf-keyframe">
  <div class="bf-keyframe-point"
       data-offset="0"
       data-x="0"
       data-y="0"
       data-rotation="0"
       data-scale="1"
       data-opacity="1"
       data-color="#FFFFFF"></div>

  <div class="bf-keyframe-point"
       data-offset="100"
       data-x="180"
       data-y="0"
       data-rotation="360"
       data-scale="1"
       data-opacity="1"
       data-color="#FF0000"></div>
</div>
```

`bf-keyframe` は宣言されたKeyFrame点を BoneKeyFrame Runtime状態へ変換します。再生、時間制御、補間は行いません。

## 12. 確認URL
- Test: `http://localhost/boneflow/test/bone-keyframe.html`
- Cumulative Regression: `http://localhost/boneflow/test/bone-development-order.html`