feat(editor): expose precise overlay and caption controls

Author: erickkkyt

docs/MCP.md

@@ -147,9 +147,15 @@ the MCP tool contract instead of guessing an opaque operation object.
 
 Editor agents add a project-owned image overlay with `add_overlay`, then adjust
 its normalized position, width, opacity, rotation, and fades with
-`update_overlay`. Overlay clips live on their own visual track, may overlap the
+`update_overlay`. Use `replace_overlay_asset` with another project-owned image
+Asset to swap the artwork while preserving the clip's timing and transform.
+Overlay clips live on their own visual track, may overlap the
 base video, and remain subject to the same revision checks, Asset boundary, and
-durable timeline persistence as UI edits. Captions are composited after overlays.
+durable timeline persistence as UI edits. The UI also lets users drag an active
+overlay directly in the preview frame. Captions are composited after overlays.
+Use `update_caption` to tune one caption cue's normalized font size, maximum
+width, and bottom position without changing later cues; `set_caption_style`
+continues to select the shared visual preset.
 
 For a newly connected Canvas node, append a `place_card` operation after its
 `upsert_card`. By default it places the target once to the right of the frames

docs/PRODUCT_PLAN_AND_STATUS.md

@@ -112,16 +112,17 @@ Codex / Claude Code / Other Agent
 - 非破坏式 trim、split、move、delete 和 ripple delete。
 - undo/redo。
 - 音量、静音、淡入和淡出。
-- 图片 Overlay 叠加，支持位置、宽度、透明度、旋转和淡入淡出；预览与 MP4 导出保持一致。
+- 图片 Overlay 叠加，支持在预览中直接拖动，并可精确调整位置、宽度、透明度、旋转和淡入淡出；预览与 MP4 导出保持一致。
 - 浏览器本地预览。
 - 选区派生 MP4。
 - BeatAPI 选区 AI redo。
 - Redo 结果作为 Take 保存、激活和恢复 Original。
 - 完整 Timeline H.264/AAC MP4 导出。
-- 字幕在 Overlay 之后绘制，确保字幕始终位于最终画面层。
+- 字幕在 Overlay 之后绘制，确保字幕始终位于最终画面层；单条字幕可独立调整字号、最大宽度和垂直位置，UI 与 MCP 共用同一操作。
 - 导出写回 Assets 和 Canvas Timeline Node。
 - 缺失素材、Clip 重叠和视频轨空隙诊断。
 - Editor 自动保存统一走 Command Kernel；并发写入使用 revision/CAS 和三方合并，不再用旧文档覆盖新版本。
+- 右侧栏是 Agent 中立的 Timeline Inspector，不内置或假装存在专有 Clip Agent；Codex、Claude Code、Cursor 等通用 Agent 通过 MCP 修改同一份 Timeline。
 - 同一次加入时间线使用稳定 Clip ID 和幂等键，重复点击、网络重试不会重复插入同一批 Clip。
 - Take 必须覆盖 Clip 时长；过短 Take 不可激活，诊断会阻止可能产生冻结尾帧的导出。
 

messages/en.json

@@ -525,6 +525,11 @@
       "captions": {
         "text": "Caption text",
         "style": "Caption style",
+        "currentCue": "Current caption",
+        "currentCueHint": "This cue only",
+        "fontScale": "Text size",
+        "maxWidth": "Maximum width",
+        "bottomOffset": "Position from bottom",
         "styles": {
           "classic": "Classic",
           "bold": "Bold",
@@ -542,6 +547,8 @@
         "activeHint": "Audio follows the timeline playhead and fades are applied during preview and export."
       },
       "overlay": {
+        "dragLabel": "Move image overlay",
+        "dragHint": "Drag to move · Arrow keys to nudge",
         "x": "Horizontal position",
         "y": "Vertical position",
         "width": "Width",
@@ -551,14 +558,13 @@
         "fadeOut": "Fade out"
       },
       "panel": {
-        "title": "Clip Agent",
-        "local": "Local",
-        "subtitle": "Your editing workspace",
+        "title": "Inspector",
+        "subtitle": "Timeline properties",
         "properties": "Properties",
         "quickActions": "Clip actions",
         "exactHint": "Open Exact to edit source range, duration, and timeline position.",
         "welcomeTitle": "Edit with a clear workflow",
-        "welcomeDescription": "Select a timeline clip to edit its properties here. Your source media stays local until an action explicitly needs BeatAPI.",
+        "welcomeDescription": "Select a timeline clip to edit its properties here, or let any MCP-capable agent update the same timeline. Your source media stays local until an action explicitly needs BeatAPI.",
         "workflow": {
           "studio": {
             "title": "Start in Studio",

messages/ja.json

@@ -525,6 +525,11 @@
       "captions": {
         "text": "字幕テキスト",
         "style": "字幕スタイル",
+        "currentCue": "現在の字幕",
+        "currentCueHint": "この字幕のみ",
+        "fontScale": "文字サイズ",
+        "maxWidth": "最大幅",
+        "bottomOffset": "下端からの位置",
         "styles": {
           "classic": "クラシック",
           "bold": "ボールド",
@@ -542,6 +547,8 @@
         "activeHint": "音声はTimelineの再生ヘッドに追従し、プレビューと書き出し時にフェードが適用されます。"
       },
       "overlay": {
+        "dragLabel": "画像オーバーレイを移動",
+        "dragHint": "ドラッグで移動・矢印キーで微調整",
         "x": "水平位置",
         "y": "垂直位置",
         "width": "幅",
@@ -551,14 +558,13 @@
         "fadeOut": "フェードアウト"
       },
       "panel": {
-        "title": "Clip Agent",
-        "local": "ローカル",
-        "subtitle": "編集ワークスペース",
+        "title": "インスペクター",
+        "subtitle": "Timelineのプロパティ",
         "properties": "プロパティ",
         "quickActions": "Clipの操作",
         "exactHint": "詳細設定を開き、ソース範囲、長さ、Timeline上の位置を編集します。",
         "welcomeTitle": "明確な流れで編集",
-        "welcomeDescription": "TimelineのClipを選択すると、ここでプロパティを編集できます。BeatAPIが明示的に必要な操作を行うまで、ソースメディアはローカルに保持されます。",
+        "welcomeDescription": "TimelineのClipを選択すると、ここでプロパティを編集できます。MCP対応の汎用Agentも同じTimelineを更新できます。BeatAPIが明示的に必要な操作を行うまで、ソースメディアはローカルに保持されます。",
         "workflow": {
           "studio": {
             "title": "Studioから始める",

messages/zh.json

@@ -525,6 +525,11 @@
       "captions": {
         "text": "字幕文案",
         "style": "字幕样式",
+        "currentCue": "当前字幕",
+        "currentCueHint": "仅调整这一句",
+        "fontScale": "文字大小",
+        "maxWidth": "最大宽度",
+        "bottomOffset": "距底部位置",
         "styles": {
           "classic": "经典描边",
           "bold": "短视频粗体",
@@ -542,6 +547,8 @@
         "activeHint": "音频跟随时间线播放头，淡入淡出会同时应用于预览和导出。"
       },
       "overlay": {
+        "dragLabel": "移动叠加图片",
+        "dragHint": "拖动移动 · 方向键微调",
         "x": "水平位置",
         "y": "垂直位置",
         "width": "宽度",
@@ -551,14 +558,13 @@
         "fadeOut": "淡出"
       },
       "panel": {
-        "title": "片段助手",
-        "local": "本地",
-        "subtitle": "你的剪辑工作区",
+        "title": "属性检查器",
+        "subtitle": "时间线属性",
         "properties": "片段属性",
         "quickActions": "片段操作",
         "exactHint": "展开精确参数，可以修改素材范围、持续时间和时间线位置。",
         "welcomeTitle": "按清晰流程完成剪辑",
-        "welcomeDescription": "选择时间线片段后，可在这里编辑参数。除非某个操作明确需要 BeatAPI，否则源素材始终保留在本地。",
+        "welcomeDescription": "选择时间线片段后，可在这里编辑参数；任何支持 MCP 的通用 Agent 也能修改同一条时间线。除非某个操作明确需要 BeatAPI，否则源素材始终保留在本地。",
         "workflow": {
           "studio": {
             "title": "从 Studio 开始",

src/components/editor/video-editor-workspace.test.ts

@@ -5,11 +5,37 @@ import { createTimelineDocument } from '@/core/editor/timeline-document';
 import { applyEditorOperations } from '@/core/commands/editor-commands';
 import {
   findVisualClipAtTimelineTime,
+  moveOverlayInPreview,
   PROJECT_TIMELINE_EXTERNAL_POLL_INTERVAL_MS,
   shouldPersistTimelineDocument,
   timelineDocumentsEqualForPersistence,
 } from './video-editor-workspace';
 
+test('overlay preview dragging maps pixels to normalized frame coordinates', () => {
+  assert.deepEqual(
+    moveOverlayInPreview({
+      originX: 0.5,
+      originY: 0.25,
+      deltaX: 100,
+      deltaY: 50,
+      frameWidth: 500,
+      frameHeight: 1000,
+    }),
+    { x: 0.7, y: 0.3 }
+  );
+  assert.deepEqual(
+    moveOverlayInPreview({
+      originX: 0.98,
+      originY: 0.02,
+      deltaX: 100,
+      deltaY: -100,
+      frameWidth: 500,
+      frameHeight: 1000,
+    }),
+    { x: 1, y: 0 }
+  );
+});
+
 test('does not echo a remotely loaded timeline back through UI autosave', () => {
   const remote = createTimelineDocument({
     projectId: 'project-1',