# Video Sync — Multi-Session Monitoring & Sync Status · Handoff (2026-05-19)

## TL;DR

Feature mockup **v2** 已交付到 Figma 文件 `Micro-Apps-20250923` 内的目标 page `Video Sync — Multi-Session Monitoring & Sync Status 20260519`（node `4083:8424`）。

- **PRD spec section** — 双语 EN/ZH，5 张卡片（Background / Goals / Scope / Requirements / Baseline ref）
- **Mockup v2 frame** (1920×1080) — 严格遵循 [`MICROAPPS_PRODUCT_CONTEXT.md §5.5`](./MICROAPPS_PRODUCT_CONTEXT.md#55--microapp-session-detail--leftright-layout-convention硬规则) **LEFT 1168 信号 / RIGHT 680 参数** 布局：
  - **LEFT 1168 (x=24, y=152, h=680)** — Running Sessions list 5 rows，Row 1 (Premier_League_Main) selected with blue accent rail
  - **RIGHT 680 (x=1216, y=152, h=680)** — Parameters/Video Sync 面板，cloned from Plan B `915:25490` 实例
- **全 TVU library 合规** — Top bar / Badge / Button/dark M / Tab/Item / Parameters/Video Sync 均为 library 实例；色值采用 TVU dark-theme palette hex 字面量（Layer_1/2/3/4 + Brand/Red/Blue/Orange + Text/Tips/Placeholder）

> **重要：v0 已删除**。v0（先前 file-local 草图版）因 (1) 没遵循 Micro Apps LEFT/RIGHT 布局规则、(2) 全部 file-local 视觉替代了 TVU library instances、(3) 色值未对齐 TVU 调色板，被用户判定为 non-compliant。v2 是 from-scratch rebuild。

---

## Figma 产物索引

### Page
- `Video Sync — Multi-Session Monitoring & Sync Status 20260519` — `4083:8424`

### Section A · PRD Spec
- `UX · Video Sync Multi-Session — Spec v0` — `4093:85`
  - Header / Background / Goals / Scope (In/Out) / Requirements R1-R4 / Baseline ref

### Section B · Mockup v4 (canonical · 4 frames + M23 annotation)

- `UX · Video Sync Multi-Session — Mockup v2 ...` section — `4119:198` (4560×2400)

| Frame | Node ID | 说明 |
|---|---|---|
| **M0 · Single Session — auto-expanded** | `4139:1376` | 1-session 特殊态：PP + 唯一 row 自动展开（BRAND accent）+ `+ Add` placeholder |
| **M1 · Multi-Session — Default View** | `4119:199` | PP + 5 rows（2 ON + 3 OFF），Row 1 selected (BRAND accent) collapsed + `+ Add` placeholder |
| **M2 · ON Row Expanded — Slot/Channel editing (R2)** | `4139:988` | PP + Row 1 ON selected + expanded with Stream A/B dropdowns + 4 rows collapsed + `+ Add` |
| **M3 · OFF Row Selected — Start affordance + per-session Parameters demo** | `4165:950` | Row 3 TV2_Feed OFF selected + expanded; RIGHT Parameters header changes to "Parameters · TV2_Feed" with **different values** (Window=15, MaxTau=500, BaseDelay=200) demonstrating per-session uniqueness; RIGHT bottom button "Sync" instead of "Syncing..." |

**v4 关键调整 (vs v3.2)**：
- **LEFT 内部上下分栏 (visible)**：LEFT panel 改 transparent container，内部 2 个独立 sub-panel — top = PP sub-panel (own fill #1F1F1F + border)，bottom = Sessions sub-panel (same styling)，中间 16px gap 露出 page bg
- **Selected accent BLUE → BRAND green (`#2FB54E`)**：所有 row 选中 accent rail + Parameters header session 名都改 BRAND，跟产品 brand 色对齐；BLUE 保留给 annotation 层（M23 chips / Sort header / 等）
- **RIGHT bottom button context-aware**：ON 选中 = `[Cancel] [Syncing…]` 绿 filled / OFF 选中 = `[Cancel] [Sync]` 绿 filled (同 TVU `Button/dark L` filling-green style)
- **新增 M3 frame** 演示 OFF row 选中：(1) 完整 LEFT/RIGHT 复用 (2) Parameters header BRAND-tinted session name "TV2_Feed" (3) Parameters values 不同 (Window=15/MaxTau=500/BaseDelay=200) 证实 per-session 唯一性 (4) Sync 按钮态切换
- **M23 UX 交付注释**：4 个 state label chips (`#2B2D42` navy + `#33A4FD` blue accent, 双语 EN/ZH) 在每帧上方 + Design Rules card (8 条规则) 在右侧

**v3.1 关键修正**（2026-05-20 后续）：

| v3 错误 | v3.1 修正 | 理由 |
|---|---|---|
| 5 个 status（SYNCING/IN PROGRESS/DONE/FAILED/IDLE） | **改 2-state：`ON` Blue / `OFF` Neutral** | 用户确认当前产品状态只有"开启 / 未开启"两种；PRD R3 列的 5 状态是"例如"非全部 mandatory；之前没问就当成 5 状态实施是错的 |
| Row 3 红色 FAILED badge + "Audio match dropped" 红色错误 meta | OFF Neutral + 中性 meta "Last attempt 13:30" | 没有 Failed state，错误信息退化为 informational context |
| Row 4 DONE 绿色 badge + 12 ms ✓ delta | OFF Neutral, delta 整块删 | 没有 Done state；OFF rows 不显示当前 delta |
| RIGHT Parameters header 是静态 "Parameters" | 改为 `Parameters · Premier_League_Main`（session 名 BLUE 蓝色）| **每个 session 有自己的 parameters**（用户指出）；RIGHT panel 跟随选中 row 切换值；header 显式标 binding |

**v3 IA**（确认后实施 · 2026-05-20）：
```
Row 0: Top bar 1920×64 [IMMUTABLE TVU instance]
Row 1: Page state label "Multi-Session Sync" (top-left, padding 24, ~28h)
Row 2: BODY · LEFT 1168 + RIGHT 680 (Micro Apps §5.5)
   ├ LEFT 1168:
   │   ├ PP strip (cloned from Plan B `842:34818` Content sans Sync button) — page-level Producer Program
   │   ├ Sessions list:
   │   │   ├ Row chevron (icon/Arrow/Next collapsed / icon/Arrow/Dropdown expanded)
   │   │   ├ Status Badge (library) + Name+meta + Slot route + delta+trend (NO inline actions)
   │   │   ├ Selected row → blue accent rail + (optionally) expanded panel showing Stream A·Source / Stream B·Destination
   │   │   └ "+ Add another sync session" dashed placeholder row at end
   └ RIGHT 680: Parameters/Video Sync (cloned, IMMUTABLE structure) + Cancel/Sync buttons context-aware
```

**v3 关键决策**（之前 v2 的错误已修正）：

| v2 错误 | v3 修正 | 理由 |
|---|---|---|
| 自造的 sub-header strip（Multi-Session Monitor + Filter chips + Sort + New Sync 一行）| **整条删** | 统一 Micro Apps layout 没有 sub-header（Standard Conversion / Plan B 都没有）|
| 每 row 内嵌一个 Producer Program dropdown | **删** — PP 上提到 LEFT 顶部 strip（页面级） | PRD 架构：1 PP shared by N sessions |
| PP strip 用我自造的格式（"Producer Program:"标签+dropdown row+description）| 改 clone Plan B `842:34818` Content 节点（保留 "Select a Producer Program:" + dropdown 946w + description）只去 Sync 按钮 | 跨 App 视觉 1:1 |
| Row 行内右侧 Stop / Retry / Detail / Open / Configure 按钮 | **全删** | 统一模式：所有 primary action 在 RIGHT 底部 context-aware；行内 action 是我发明 |
| Row 没 chevron 视觉 | **每 row 行首 prepend** `icon/Arrow/Next`（collapsed → 右向小 chevron）/ `icon/Arrow/Dropdown`（expanded → 向下小 chevron）| M14.1 小 chevron 用 Next/Dropdown 不要 Left/Right |
| 没有 "+ Add another sync session" 入口 | LEFT sessions list **末尾**加 dashed ghost placeholder 行 | 多 session 必备入口；不能放全局 sub-header 违反统一模式 |
| LEFT panel `Running Sessions` + Sort hint 单独 header | **删** | 删 sub-header 后整个 LEFT 都是 sessions，再加 header 视觉冗余 |

Internal nodes（以 M1 为代表）：
- Top bar instance — `4119:484`
- Page state label TEXT "Multi-Session Sync" — `4137:990`
- LEFT panel — `4119:658`（680h，VERTICAL auto-layout）
  - PP strip (cloned Plan B Content sans Sync button) — `4137:1065`
  - Sessions list — `4122:161`（5 rows + `+ Add` placeholder `4138:996`）
- RIGHT panel — Parameters/Video Sync instance — `4123:491`

Internal nodes（以 M1 为代表，M2/M0 对应结构相同）：
- Top bar instance (cloned from Plan B `842:24310`) — id `4119:484`
- Sub-header strip (`4120:149`) — Multi-Session Monitor label + count Badge + Filter chips (Tab/Item × 5) + New Sync (Button/dark M filling-green left-icon)
- **LEFT panel** (`4119:658`) at (24, 152), 1168×680, fill `#1F1F1F` Layer_2:
  - Panel header (`4122:157`) — "Running Sessions" + Sort hint
  - Session list (`4122:161`) — N rows
- **RIGHT panel — Parameters/Video Sync** (`4123:491`) at (1216, 152), 680×680, cloned instance

### Session rows (LEFT panel children of `4122:161`)

| # | Session | Status | Badge variant | Delta | Action(s) | Selected? |
|---|---|---|---|---|---|---|
| 1 | Premier_League_Main | SYNCING | `Type=Rectangle, Color=Blue, Tag=Filled` | 84 ms ↓ (green) | Stop (ghost-red) | ✅ |
| 2 | Studio_Cam_A | SYNCING | Blue / Rect / Filled | 320 ms ↑ (orange) | Stop (ghost-red) | — |
| 3 | TV2_Feed | FAILED | Red / Rect / Filled | — placeholder | Detail (ghost-gray) + Retry (filling-green) | — |
| 4 | Local_News_Backup | DONE | Green / Rect / Filled | 12 ms ✓ (green) | Open (ghost-gray) | — |
| 5 | Test_Session | IDLE | Neutral / Rect / Filled | — placeholder | Configure (ghost-gray) | — |

---

## TVU library 合规清单

| 组件 | Library SET key | 用到的 variant | v2 实例数 |
|---|---|---|---|
| Top bar | `918b928e4541f1573de5c98c32b408af663d7f2f` | `Tag=After Login` (cloned from Plan B) | 1 |
| Badge | `4db5246d0782fe13bcc01747a7a2578c2da77b2a` | `Type=Rectangle, Color=Blue, Tag=Filled` (5 Sessions count + 2 SYNCING) | 3 |
| Badge | (同上) | `Type=Rectangle, Color=Red, Tag=Filled` (FAILED) | 1 |
| Badge | (同上) | `Type=Rectangle, Color=Green, Tag=Filled` (DONE) | 1 |
| Badge | (同上) | `Type=Rectangle, Color=Neutral, Tag=Filled` (IDLE) | 1 |
| Button/dark M | `12b38c8b68cd67dd3978e0d68712bc646f1e97c1` | `icon=left, style=filling, color=green` (New Sync) | 1 |
| Button/dark M | (同上) | `icon=no, style=ghost, color=red` (Stop × 2) | 2 |
| Button/dark M | (同上) | `icon=no, style=filling, color=green` (Retry) | 1 |
| Button/dark M | (同上) | `icon=no, style=ghost, color=gray 1` (Detail / Open / Configure) | 3 |
| Tab/Item | `2267405386cb3186ba920b0d0b790d54e65a1529` | `Property 1=Active, Property 2=Green, Type=Filled` (All) | 1 |
| Tab/Item | (同上) | `Property 1=Normal, Property 2=White, Type=Filled` (Syncing/Failed/Done/Idle) | 4 |
| Parameters/Video Sync | (file-local symbol `915:24487`, cloned via Plan B inst `915:25490`) | — | 1 |
| icon/Arrow/Next | `d9dfd8e0c06aff7f3b47cde9fcb0fcb7b7fd93d7` | (route arrow → in every row, BLUE tint) | M1=5 / M2=5 / M0=1 = **11** |
| icon/Arrow/Down | `9106bc4a9abe9a862e32ee296aebedafdd8ed254` | (trend ↓ converging, BRAND tint, Row 1) | M1=1 / M2=1 / M0=1 = **3** |
| icon/Arrow/Up | `8ca1a17c2650fd05a5e7380d3a99127ea9e8eed5` | (trend ↑ diverging, ORANGE tint, Row 2) | M1=1 / M2=1 = **2** |
| icon/file/synced | `bc428d1b7a1fb6ca3bfda939baf9421d707bf1af` | (trend ✓ stable, BRAND tint, Row 4 DONE — same icon Plan B uses on Synced button for visual consistency) | M1=1 / M2=1 = **2** |
| select box/filled (Producer Program + Stream A/B Slot/Ch dropdowns) | (Plan B inst `842:34886` Producer + `861:35252` inner) | (3 dropdowns per expanded row × M2 + M0) | **6** |

**总计**：**TVU library 实例 43 个** + 1 个 file-local symbol clone（Parameters/Video Sync）。**零 Unicode text 当 icon 用** —— v2 增量已修复 18 处 text-as-icon 违例（per M14.1 实证 history 同款坑）。

---

## 色值对照 — TVU dark-theme palette（字面 hex，待 variable binding pass）

| 用途 | Hex | TVU token 名 |
|---|---|---|
| Top bar bg | `#000000` | `Color Type/Background/Top Bar` |
| Page bg (M1 frame) | `#141414` | `Color Type/Background/Layer_1` |
| Panel bg (LEFT/RIGHT) | `#1F1F1F` | `Color Type/Background/Layer_2` |
| Sub-header bg, selected row bg | `#262626` | `Color Type/Background/Layer_3` |
| Divider lines | `#353535` | `Color Type/Line/Deep Divider` |
| Heading text | `#FFFFFF` | `Color Type/Text/Heading & Button` |
| Body text | `#F8F8F8` | `Color Type/Text/Text_1` |
| Secondary text | `#CCCCCC` | `Color Type/Text/Text_2` |
| Tips text | `#9E9E9E` | `Color Type/Text/Tips` |
| Placeholder text | `#7B7B7B` | `Color Type/Text/Placeholder & Button` |
| Brand / success / delta green | `#2FB54E` | `UX/Brand/Brand` |
| Error / Failed / Stop | `#EA4233` | `UX/Red/Default` |
| Warning / delta amber | `#F68512` | `UX/Orange/Default` |
| Syncing / link / accent | `#3892F3` | `UX/Blue/Default` |

> Variable binding deferred: cross-file variable keys not exposed in `figma-data/normalized/variables.json` (key fields empty). v2 uses literal hex matching tokens exactly — visual is correct, runtime binding is follow-up.

---

## Design Decisions (built into v2 as defaults)

| 来源 OQ | 决策 | 落点 |
|---|---|---|
| Q1 状态展示 | 行上常驻 SYNCING/FAILED/DONE/IDLE Badge；Toast 留给状态切换 | Each row's Badge |
| Q2 Delta 频率 | 默认 1s（UI 让用户选 0.5/1/2/5s） | Live Metrics block (deferred to M2 expanded state) |
| Q3 排序 | **Syncing → Failed → Done → Idle**（urgency-based）+ 同状态内 Start time 倒序 | Row 1-5 ordering + "Sort: Status ↓" hint |
| Q4 失败/Retry | 独立 FAILED Badge + 行内错误信息 + Retry primary green + Detail ghost gray | Row 3 (TV2_Feed) |
| Q5 并发上限 | UI 无硬上限，lazy-render；建议 perf baseline 8-12 / max 16 | LEFT panel 容纳约 12 行 |
| Q6 Delta 阈值 | 三段：GREEN ≤ 100ms / AMBER ≤ 500ms / RED > 500ms（Production-level setting 可配） | Row 1 green 84ms / Row 2 amber 320ms |

---

## v3.2 OFF rows = "之前跑过的 sessions" (历史可见)

**用户反馈**: v3.1 OFF rows 看起来像 placeholder/新增空槽，没传达"这些是之前配置过、跑过、现在停了的 sessions"。

**修正**: OFF row meta line 加历史时间段 + 上次 delta + 停止原因，让 OFF row 看起来像"已存在的、有 run history 的 session"，不是 placeholder。

| Row | 状态 | meta line | 语义 |
|---|---|---|---|
| Row 1 Premier_League_Main | ON | Started 13:25 · 5 m ago | 正在运行的现状 |
| Row 2 Studio_Cam_A | ON | Started 13:32 · 2 m ago | 正在运行的现状 |
| Row 3 TV2_Feed | OFF | `Last ran 13:25 → 13:30 · stopped (audio match dropped)` | 跑过 + 停过 + 含停止原因 |
| Row 4 Local_News_Backup | OFF | `Last ran 13:00 → 13:21 · 21 min · last delta 12 ms` | 跑过 + sync 收敛过 + 含上次 delta |
| Row 5 Test_Session | OFF | `Never started` | 从未跑过的配置 |

**架构含义**：sessions 持久化在 PP 下，不因 stop/start 而消失；list 显示 PP 下所有 session（运行中 + 之前跑过 + 未运行的）。

## Session count & state matrix (v3.1)

**State model**：仅 2 种 — `ON`（正在 syncing）/ `OFF`（未开启）。无 Failed/Done/Idle 独立 state；上述都属"OFF + informational context"。

| Session 数 | Frame | Row 分布 |
|---|---|---|
| 1 | M0 | 1 ON（auto-expanded） |
| 2-5 | M1 | 5 rows: 2 ON + 3 OFF（含 1 "Not configured"），Row 1 selected collapsed |
| 2-5 + editing | M2 | 同 M1，Row 1 expanded 显示 Stream A/B Slot/Ch dropdown |

**Per-session Parameters 绑定**：
- 每个 session 独立持有 Parameters（Window/Hop/Sample Rate PCM/Max Tau/Consistency*/Base Delay/Target Residual/Sync Cooldown）
- RIGHT panel 实时反映**当前选中 row** 对应 session 的 parameters
- Parameters header `Parameters · <session_name>`（session name BLUE 与 row accent rail 同色）显式表达 binding
- 切换 row（click 其它 row）→ RIGHT Parameters values 整体重渲染为该 session 的值；header session 名同步替换
- **当前 mockup 仅展示 Row 1 (Premier_League_Main) 选中态**；要演示"切到 Row 2 后 Parameters 变化"需补 v4 frame（如 M3 · Row 2 Selected · different Parameters values）

## Acceptance checklist

- [x] **R1** — Multi-session list (5 sessions, name / start time / source-dest / delta each)
- [x] **R2** — Per-row expand affordance + **Slot/Channel editing entry**：选中 row 展开后显示 Producer Program + Stream A/B Slot·Ch 三个 dropdown（M2 frame）；1-session 特殊态自动展开（M0 frame）
- [x] **R3** — Sync status indicator (SYNCING/FAILED/DONE/IDLE library Badge per row)
- [x] **R4** — Delta between 2 streams (Row 1/2/4 + threshold color)
- [x] **M1 hard rule** — Top bar = TVU library instance ✅
- [x] **M32 library-first** — Badge / Button/dark M / Tab/Item 全 library instance ✅
- [x] **MicroApps §5.5** — LEFT 1168 / RIGHT 680 fixed-width Parameters convention ✅
- [x] **色值合规** — 所有 hex 来自 TVU dark-theme palette ✅
- [ ] **Variable binding** — file-local containers (page bg / panel bg / borders) 用字面 hex；待 cross-file variable key 通路打通后做绑定 pass
- [ ] **M23 state flow** — v2 未画 state transitions（M1 → M2 expanded 等），按需补充
- [ ] **Frame M2 expanded state** — 当前 v2 仅画 default view (M1)；Row 1 expanded 完整 Live Metrics 块尚未在 v2 内画出

---

## v0 retrospect — 教训

| 错误 | 根因 | 修正 |
|---|---|---|
| 用 list-only top-down layout，没分 LEFT/RIGHT | 没读 `MICROAPPS_PRODUCT_CONTEXT.md`，假设"全宽 list" 是合理的多 session UI 模式 | 写 `§5.5` 硬规则到项目文档 + 存项目 memory 让未来 session 起手就知道 |
| 全部 file-local 自画 Badge/Button/Tab/Icon | 把 "v0 file-local OK，dev 阶段 swap" 当成 trade-off | `@TVU mockup` skill 的存在意义是**起手就用 library** — v0/v1 都不豁免 M32 |
| 色值用我手写的 hex `#33A4FD/#52C41A/#FF4D4F/#1A1D27` | 凭印象写"看起来像 TVU"的色，没探真源 | 从 `figma-data/normalized/variables.json` 拿 dark-theme palette，全部对齐 |

→ 同步回流到 `tvu-design-mockup` skill：起手协议加 "若 cwd 是 sibling 消费产品 + 该产品有 `PRODUCT_CONTEXT.md` → 必读 全文"。

---

## Session count states · 选择策略（明确）

| Session 数 | 默认 LEFT 状态 | 选中 / 编辑入口 |
|---|---|---|
| **0** | Empty state（中央显眼 `+ New Sync` CTA — 待补 frame） | — |
| **1** | 唯一 row **自动展开 + auto-selected**（M0 frame） | row 已展开 → Slot/Ch dropdowns 直接可改 |
| **2+** | 默认全 collapsed（除非用户上次留在某 row 展开）（M1 frame） | 点 row → 选中 + 展开 → RIGHT Parameters 跟随 + 当前 row 展开 Slot/Ch 编辑（M2 frame） |
| 16+ | 列表 lazy-render（性能 baseline 8-12 / max 16 待 Karen 确认） | 同 2+ |

**编辑入口设计**：Slot / Audio Channel 不放 RIGHT Parameters 也不放 Modal，直接放在 row expanded 的 inline panel 里——理由是 (1) 跟 Plan B baseline 的"Stream A | Stream B"两栏视觉对齐 (2) 与 R2 expand/collapse 合并交付（一个动作两个目的）(3) 跨 session 切换时编辑上下文不丢失。

---

## Next steps

1. **PM / Wen Xing review** — design decisions（特别 Q3 排序 / Q4 Retry 权限 / Q6 阈值具体数值 / row click affordance 的 hover 视觉）
2. **Karen confirm** — push 频率下限（Q2）+ session 并发上限（Q5）
3. **Empty state frame** — 0 session 时显示 onboarding hint + 大号 `+ New Sync` CTA
4. **Variable binding pass** — 若打通 cross-file variable import，将 file-local containers 的 hex 改为 token 绑定
5. **回流 tvu-design-mockup skill** — 起手协议加 consumer `PRODUCT_CONTEXT.md` 必读

---

## Files

- Figma file: `Micro-Apps-20250923` (key `DtZcMkhNy6qh6jbQQnhreQ`)
- Target page: node `4083:8424` — [link](https://www.figma.com/design/DtZcMkhNy6qh6jbQQnhreQ/Micro-Apps-20250923?node-id=4083-8424)
- v2 mockup section: node `4119:198` — [link](https://www.figma.com/design/DtZcMkhNy6qh6jbQQnhreQ/Micro-Apps-20250923?node-id=4119-198)
- Layout convention rule: [`MICROAPPS_PRODUCT_CONTEXT.md §5.5`](./MICROAPPS_PRODUCT_CONTEXT.md#55--microapp-session-detail--leftright-layout-convention硬规则)