# #121 Timeline 操作ガイド

## Overview
#121 Timeline は**開始指示を受けた後**の時間管理を担当し、複数の Motion に対して Delay / Duration / Sequence / Parallel / Repeat / Loop を管理します。絶対時刻やイベントなど「何が開始させるか」は#121自身の責務ではありません。

正式責務は次の6つだけです。

- Delay
- Duration
- Loop
- Repeat
- Sequence
- Parallel

#021 TIME JOB のSchedule開始条件、#120 Trigger のイベント開始条件、#122 KeyFrame の途中状態・値、#117 Animation の単体Animation挙動、#054 Display Timeline の表示UIは #121 の責務ではありません。

## Property
### Mode
`sequence` または `parallel` を指定します。

- `sequence`: 前の Motion が終了してから次の Motion を開始します。
- `parallel`: 複数 Motion を同じ時間軸上で並行実行します。

### Delay
単位は ms。0〜600000 の整数です。Timeline開始前の待ち時間を指定します。

### Duration
単位は ms。0〜600000 の整数です。各 Motion を保持する時間です。

### Repeat
1〜1000 の整数です。Timeline全体の有限反復回数です。

### Loop
Booleanです。ONの場合、停止されるまでTimeline全体を反復します。

## 実行テスト
画面の「実行テスト」は #054 Display Timeline を再実装しません。各 Motion の start / end / duration と、Runtimeから届いた実callbackだけを表示します。

1. Propertyを設定します。
2. 「Property反映」でPlanを確認します。
3. 「Timeline実行」で実callbackを開始します。
4. Motion A / B / C の状態が READY → RUNNING → DONE と変わることを確認します。
5. Sequenceでは前のMotion終了後に次が開始し、Parallelでは同時時間軸に配置されることを確認します。

## #121を呼ぶ開始元UI / Component
#121は自分で絶対時刻や開始イベントを決めません。開始元は上流Componentです。

- **#021 Shape / TIME JOB / SCHEDULE_TRIGGER**: 日時・曜日・時刻・Cron等のSchedule条件で開始します。CLOCK / MANUAL / API / JOINTの起動契約は#021側が保持します。#021自身は常駐timerを持たず、Runtime / Flow Editor側が`matchesSchedule(date)`を評価し、一致時に`triggerSchedule(...)`を呼びます。
- **#120 Trigger**: Click / Focus / Change / Runtime Event / Command等のイベント条件で開始します。
- **#121 Timeline**: 上記から開始指示を受けた後、Delay / Duration / Sequence / Parallel / Repeat / Loopを管理します。

画面にはこの関係を#002 BoneJointの**正常系接続だけ**で2件表示します。

1. `#021 TIME JOB / SCHEDULE_TRIGGER → #121 Timeline → Target`
2. `#120 Trigger / Event callback → #121 Timeline → Target`

この追加表示には不存在・型不一致などの異常系カードを作りません。既存のIN/OUT接続テスト5ケースとは目的を分離します。

## 接続イメージ — #002 BoneJoint v1.1.36
Security Testとは別セクションです。#017 Textと同じ確認構造で、次の5ケースを#002正式Jointで実描画します。

- 正常接続（IN / OUT）
- IN：Target Field不存在
- OUT：Target Field不存在
- 型不一致（IN）
- 型不一致（OUT）

線・端点・異常markerはBoneJoint v1.1.36の正式APIを使用します。独自SVG marker、CSS疑似Joint、独自異常iconは作りません。

## Security
Untrusted IN / Security Testでは以下を確認します。

- 不正Modeを拒否する
- 負のDelay / Durationを拒否する
- Motion ID重複を拒否する
- getter/setterを実行せず拒否する
- Security Testが通常の実行テスト表示を破壊しない

## OUT WAIT / BLOCKED - #002 Joint v1.1.36 Integration
#002 BoneJoint v1.1.36の正式`createDeliveryChannel()` / `drawLine()`を使用する、単一の横長カードです。WAITとBLOCKEDを別カードへ分割しません。

表示項目は次の4つです。

- Joint State
- Target
- Queue
- Delivered

操作は次の3つです。

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

WAITではTarget BUSYのまま接続を維持してA/BをQueueへ積み、Target READY後にA→Bの順でFIFO自動配送します。BLOCKEDではconnectionEstablishedを維持したままTargetへ配送しません。操作の下は1行ログと、WAIT→READY→FIFO、BLOCKEDでTarget不達の2つの目視確認だけです。Target READY/BUSY selector、Payload selector、独立FIFOボタンは追加しません。

## Smoke Test / Validation
各テスト行には「何を確認しているか」を日本語またはEnglishで表示します。言語切替後もテストIDと判定は変わりません。

Smoke TestはRuntimeの正常系・実callback・#002 Delivery Channelを確認します。

Validationは不正値拒否・責務境界・I18N・DOM重複・Completion gateを確認します。

## Completion
Smoke / Validationの両方がPASSし、次を目視確認した後だけCompletion可能です。

- Sequence / Parallel / Repeatの実callback
- WAIT → READY → FIFO
- BLOCKEDでTarget不達

localhostでのユーザー確認前は正式Completed / Specification Frozenではありません。

## HTML Functional Class
通常利用Classは `bf-timeline` 1件です。

```html
<div class="bf-timeline"
     data-mode="sequence"
     data-delay-ms="100"
     data-duration-ms="300"
     data-repeat="2">
  <div class="bf-timeline-item" data-motion-id="motion-a"></div>
  <div class="bf-timeline-item" data-motion-id="motion-b"></div>
</div>
```

## Public API
Runtimeは `BoneTimeline` です。主要API:

- `create(options)`
- `run(instance, handlers)`
- `stop(instance)`
- `update(instance, patch)`
- `buildPlan(options)`
- `normalizeOptions(options)`
- `validateOptions(options)`
- `getOptions(instance)`
- `getPlan(instance)`
- `getState(instance)`
- `getHistory(instance)`
- `destroy(instance)`
- `complete(instance, evidence)`
- `reopen(instance)`

## Property 表示言語
Propertyパネル先頭の「表示言語」で **日本語 / English** を切り替えます。切替対象はProperty見出し、各Property名、Mode選択肢、Preview説明、WAIT/BLOCKED説明、Smoke / Validationの検査名・検査内容、Completion説明です。言語切替はRuntime値や判定条件を変更しません。

## QA 検査内容一覧
### Smoke Test
- S01 Runtime識別 — BoneTimeline 1.0.0 / #121 / TIMELINE
- S02 正式責務 — Delay / Duration / Loop / Repeat / Sequence / Parallel の6種だけ
- S03 Sequence計画 — 前Motion終了後に次Motion開始
- S04 Parallel計画 — 複数Motionを同じ時間軸へ配置
- S05 Repeat — 有限反復回数
- S06 Loop — 明示停止まで全体反復
- S07 `bf-timeline` Functional Class Runtime
- S08 #002 BoneJoint 1.1.36 Delivery Channel
- S09 接続イメージ — #002正式Jointで5ケースを実描画
- S10 FIFO — READY後A→B自動配送
- S11 BLOCKED — 接続維持・Target非配送
- S12 Security — getter / 不正設定拒否、Preview保持
- S13 責務境界 — Trigger / KeyFrame / Display Timeline API非所有
- S14 実callback — start → stop順
- S15 Guide / I18N — DOC-0121日本語/English導線

### Validation
- V01 不正Mode拒否
- V02 負のDelay拒否
- V03 負のDuration拒否
- V04 Repeat 1〜1000範囲
- V05 Motion ID重複拒否
- V06 getterを実行せず拒否
- V07 5正式Property + 日本語/English表示
- V08 #120 Trigger責務境界
- V09 #122 KeyFrame責務境界
- V10 #054 Display Timeline軸/バー非実装
- V11 接続イメージ5ケース + 単一OUT WAIT / BLOCKEDカードを確認
- V12 Completion gate
- V13 `bf-timeline` 1件
- V14 HTML id重複なし
- V15 Runtime Development状態
- V16 日本語/EnglishでProperty・テスト説明が切替
- V17 DOC-0121 ja.md / en.md source
- V18 #002 native WAIT/BLOCKED marker前面（line z=1 / node z=2 / marker z=3）